## 1. Folder Structure & Index

- [x] 1.1 Create `docs/devops/` directory
- [x] 1.2 Create `docs/devops/README.md` — index + system overview (what AgentIdP is, what this folder covers, links to all docs)

## 2. Architecture

- [x] 2.1 Create `docs/devops/architecture.md` — component diagram (Express, PostgreSQL, Redis) with roles and responsibilities
- [x] 2.2 Document all service ports (app: 3000, PostgreSQL: 5432, Redis: 6379)
- [x] 2.3 Document data flow: request → auth middleware → rate limit → controller → service → repository → PostgreSQL/Redis
- [x] 2.4 Document Redis usage: token revocation keys, rate limit counters, monthly token counts
- [x] 2.5 Document graceful shutdown: SIGTERM/SIGINT handling, server.close(), process.exit(0)

## 3. Environment Variables

- [x] 3.1 Create `docs/devops/environment-variables.md` — complete reference table
- [x] 3.2 Document required vars: DATABASE_URL, REDIS_URL, JWT_PRIVATE_KEY, JWT_PUBLIC_KEY
- [x] 3.3 Document optional vars: PORT (default 3000), NODE_ENV, CORS_ORIGIN (default *)
- [x] 3.4 Add format notes: DATABASE_URL connection string format, REDIS_URL format, PEM key format
- [x] 3.5 Add `.env` file example with all vars populated

## 4. Database

- [x] 4.1 Create `docs/devops/database.md` — schema overview section
- [x] 4.2 Document `agents` table: all columns, types, constraints, indexes
- [x] 4.3 Document `credentials` table: all columns, types, constraints, indexes, FK to agents
- [x] 4.4 Document `audit_events` table: all columns, types, constraints, indexes, append-only design
- [x] 4.5 Document `token_revocations` table: all columns, types, indexes, dual-store design (Redis + PG)
- [x] 4.6 Document migration runner: how it works, commands to run, how to verify applied migrations
- [x] 4.7 Document `schema_migrations` tracking table

## 5. Local Development

- [x] 5.1 Create `docs/devops/local-development.md` — prerequisites (Docker, Node.js 18+)
- [x] 5.2 Document infrastructure-only docker-compose startup (postgres + redis only, not app service)
- [x] 5.3 Document service ports and health check verification commands
- [x] 5.4 Document migration step: exact `npm run db:migrate` command and expected output
- [x] 5.5 Document application startup: `npm run dev` vs `npm start` (compiled), expected log output
- [x] 5.6 Note Dockerfile gap: app service in docker-compose.yml requires Dockerfile (Phase 1 P1 pending)
- [x] 5.7 Document full docker-compose stack startup (for when Dockerfile is available)
- [x] 5.8 Document stopping and cleaning up: `docker-compose down` and volume removal

## 6. Security

- [x] 6.1 Create `docs/devops/security.md` — JWT key management section
- [x] 6.2 Document RSA-2048 keypair generation using openssl (exact commands)
- [x] 6.3 Document PEM format for env vars (newlines as \n in single-line env, or file path approach)
- [x] 6.4 Document key rotation procedure: generate new pair, update env, restart server, old tokens expire naturally
- [x] 6.5 Document CORS configuration: CORS_ORIGIN env var, wildcard vs specific origin
- [x] 6.6 Document secret storage guidance: never commit .env, use secrets manager in production
- [x] 6.7 Document bcrypt: credentials are stored as bcrypt hashes, plaintext never persisted

## 7. Operations

- [x] 7.1 Create `docs/devops/operations.md` — startup checklist
- [x] 7.2 Document startup order: PostgreSQL → Redis → run migrations → start app
- [x] 7.3 Document graceful shutdown: send SIGTERM, server drains in-flight requests, exits 0
- [x] 7.4 Document log output format: what each startup log line means
- [x] 7.5 Document troubleshooting: DATABASE_URL not set, REDIS_URL not set, JWT keys not set
- [x] 7.6 Document troubleshooting: PostgreSQL connection refused (service not ready)
- [x] 7.7 Document troubleshooting: Redis connection error (service not ready)
- [x] 7.8 Document troubleshooting: migration fails (connection issue vs SQL error)
- [x] 7.9 Document Redis key patterns used by the application (rate:, revoked:, monthly:)

## 8. QA & Review

- [x] 8.1 Verify all commands are exact and runnable (no placeholders in shell commands)
- [x] 8.2 Verify all env var names match source code exactly
- [x] 8.3 Verify all table/column names match migration SQL exactly
- [x] 8.4 Verify all port numbers match docker-compose.yml
- [x] 8.5 Verify all internal links resolve