Merge remote-tracking branch 'origin/main' into codex/whe-28-terraform

# Conflicts:
#	docs/runbooks/dev-setup.md

docs/runbooks/dev-setup.md

@@ -22,6 +22,9 @@ bun run format:check
 bun run typecheck
 bun run test
 bun run build
+bun run db:generate
+bun run db:check
+bun run db:migrate
 bun run infra:fmt:check
 bun run infra:validate
 ```
@@ -45,6 +48,10 @@ bun run review:coderabbit
 - Linting uses `oxlint`.
 - Formatting uses `oxfmt` with no-semicolon style.
 - AI review uses CodeRabbit CLI in `--prompt-only` mode against `main`.
+- Drizzle config is in `packages/db/drizzle.config.ts`.
+- Typed environment validation lives in `packages/config/src/env.ts`.
+- Copy `.env.example` to `.env` before running app/database commands.
+- Migration workflow is documented in `docs/runbooks/migrations.md`.
 
 ## CI/CD
 
@@ -56,6 +63,7 @@ bun run review:coderabbit
   - `GCP_PROJECT_ID`
   - `GCP_WORKLOAD_IDENTITY_PROVIDER`
   - `GCP_SERVICE_ACCOUNT`
+  - optional for automated migrations: `DATABASE_URL`
 
 ## IaC Runbook
 

docs/runbooks/migrations.md

@@ -0,0 +1,60 @@
+# Migration Runbook
+
+## Model
+
+- Source of truth: Drizzle schema in `packages/db/src/schema.ts`
+- Generated SQL migrations: `packages/db/drizzle/*.sql`
+- Do not edit generated SQL manually unless required and reviewed.
+
+## Local workflow (algorithm)
+
+1. Change schema in `packages/db/src/schema.ts`.
+2. Generate migration:
+
+```bash
+bun run db:generate
+```
+
+3. Review generated SQL in `packages/db/drizzle/`.
+4. Validate migration metadata:
+
+```bash
+bun run db:check
+```
+
+5. Apply migration to target DB:
+
+```bash
+bun run db:migrate
+```
+
+6. Run quality gates:
+
+```bash
+bun run format:check
+bun run lint
+bun run typecheck
+bun run test
+bun run build
+```
+
+7. Commit schema + migration files together in one PR.
+
+## CI behavior
+
+- CI runs `bun run db:check` in parallel with other quality jobs.
+- CI does not apply migrations to shared environments.
+
+## CD behavior
+
+- CD deploy can run migrations before deploy **if** `DATABASE_URL` secret is present.
+- If `DATABASE_URL` is not set, deploy continues without auto-migration.
+
+## Safety rules
+
+- Prefer additive migrations first (new columns/tables) over destructive changes.
+- For destructive changes, use two-step rollout:
+  1. Backward-compatible deploy
+  2. Data backfill/cutover
+  3. Cleanup migration
+- Never run `db:push` in production pipelines.