docs(ops): add environment and deployment runbook

TODO.md

@@ -75,7 +75,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [x] [P1] RBAC and permission model documentation in docs site
 - [x] [P2] i18n conventions docs (keys, namespaces, fallback, translation workflow)
 - [x] [P1] CRUD base patterns documentation and examples
-- [ ] [P1] Environment and deployment runbook docs (dev/staging/production)
+- [x] [P1] Environment and deployment runbook docs (dev/staging/production)
 - [ ] [P2] API and domain glossary pages
 - [ ] [P2] Architecture Decision Records (ADR) structure and first ADRs
 

docs/.vitepress/config.mts

@@ -25,6 +25,7 @@ export default defineConfig({
           { text: "i18n Baseline", link: "/product-engineering/i18n-baseline" },
           { text: "i18n Conventions", link: "/product-engineering/i18n-conventions" },
           { text: "RBAC And Permissions", link: "/product-engineering/rbac-permission-model" },
+          { text: "Environment Runbook", link: "/product-engineering/environment-runbook" },
           { text: "Testing Strategy", link: "/product-engineering/testing-strategy" },
           { text: "Workflow", link: "/workflow" },
         ],

docs/product-engineering/environment-runbook.md

@@ -0,0 +1,103 @@
+# Environment and Deployment Runbook
+
+## Scope
+
+Operational baseline for `dev`, `staging`, and `production`.
+
+## Environments
+
+### Dev (local)
+
+- Runtime: Bun + local Next dev servers
+- Entry point: `bun run dev`
+- Database: local/remote dev Postgres from `.env`
+- Characteristics:
+  - fastest feedback
+  - non-production data acceptable
+  - migrations created here first
+
+### Staging
+
+- Runtime: Docker Compose (`docker-compose.staging.yml`)
+- Purpose: integration validation and release candidate checks
+- Characteristics:
+  - production-like environment
+  - controlled test data
+  - candidate for production promotion
+
+### Production
+
+- Runtime: Docker Compose (`docker-compose.production.yml`)
+- Purpose: end-user traffic
+- Characteristics:
+  - protected secrets and stricter access controls
+  - immutable release artifacts
+  - rollback procedures required
+
+## Core Commands
+
+### Local development
+
+```bash
+bun install
+bun run db:generate
+bun run db:migrate
+bun run db:seed
+bun run dev
+```
+
+### Staging compose
+
+```bash
+bun run docker:staging:up
+bun run docker:staging:down
+```
+
+### Production compose
+
+```bash
+bun run docker:production:up
+bun run docker:production:down
+```
+
+## Release Flow
+
+1. Complete work on task branch.
+2. Merge into `dev` and pass quality gates.
+3. Promote `dev` -> `staging`.
+4. Validate staging smoke/e2e + manual checks.
+5. Promote `staging` -> `main` and tag release.
+
+## Migration Policy
+
+- Create migrations in development only.
+- Apply migrations in deployment using `prisma migrate deploy`.
+- Never hand-edit applied migration history.
+
+## Rollback Baseline
+
+Current baseline strategy:
+
+- rollback app image/tag to previous known-good release
+- restore database from backup when schema/data changes require recovery
+
+## Secrets and Config
+
+- Dev: `.env`
+- Staging: `.env.staging` (from `.env.staging.example`)
+- Production: `.env.production` (from `.env.production.example`)
+
+Minimum sensitive values:
+
+- `DATABASE_URL`
+- `BETTER_AUTH_SECRET`
+- `CMS_SUPPORT_*` credentials/keys
+
+## Verification Checklist
+
+- `bun run check`
+- `bun run typecheck`
+- `bun run test`
+- `bun run test:e2e`
+- app startup health for web/admin
+- login flow and permissions smoke

docs/product-engineering/index.md

@@ -10,6 +10,7 @@ This section covers platform and implementation documentation for engineers and
 - [RBAC And Permissions](/product-engineering/rbac-permission-model)
 - [i18n Conventions](/product-engineering/i18n-conventions)
 - [CRUD Examples](/product-engineering/crud-examples)
+- [Environment Runbook](/product-engineering/environment-runbook)
 - [Testing Strategy Baseline](/product-engineering/testing-strategy)
 - [Workflow](/workflow)