# Code Handover Playbook

This is the minimum runbook for a new engineer to continue delivery safely.

## Local Setup

1. Install Bun matching repo policy.
2. Copy `.env.example` to `.env` and fill required values.
3. Generate Prisma client:
   `bun run db:generate`
4. Apply migrations:
   `bun run db:migrate:deploy` (or local named migration flow)
5. Seed data:
   `bun run db:seed`
6. Start apps:
   `bun run dev`

## Daily Development Loop

1. Create branch by task type:
   `todo/*`, `refactor/*`, `code/*`.
2. Implement smallest vertical slice for one TODO item.
3. Run quality gates:
   `bun run check`
   `bun run typecheck`
   `bun run test`
4. Update `TODO.md` status and discovery log.
5. Commit with Conventional Commit message and GPG signing.

## Database Workflow

- Schema source is:
  `packages/db/prisma/schema.prisma`
- Use named dev migrations for schema changes.
- Avoid manual SQL unless migration tooling is blocked.
- Always regenerate client after schema change.

## Testing Strategy

- Unit/service tests:
  `packages/*` and logic helpers.
- App-boundary integration tests:
  auth flow and route-level behavior.
- E2E tests:
  full admin/public happy paths through Playwright.

## Common Failure Recovery

- `DATABASE_URL not set`:
  ensure root `.env` is loaded for Bun/Prisma scripts.
- Prisma client import errors:
  run `bun run db:generate`.
- Migration drift:
  run deploy/reset flow in dev and reseed.
- Playwright host deps missing:
  install browser dependencies on host before running e2e.

## Ownership Expectations

- Keep invariants explicit and tested before changing auth/media pipelines.
- Treat `TODO.md` as delivery source of truth.
- If changing branch/release workflow, update docs in same branch.