docs(handover): add architecture map and takeover playbook

docs/product-engineering/code-handover-playbook.md

@@ -0,0 +1,62 @@
+# 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.