docs: DevOps documentation — complete docs/devops/ set

Adds the full devops-documentation OpenSpec change implementation.
Separate from docs/developers/ — serves a different audience (operators,
not API consumers).

docs/devops/:
- README.md          — index and system overview
- architecture.md    — components, ports, data flow, Redis key patterns
- environment-variables.md — all 7 env vars (required + optional, formats, .env example)
- database.md        — 4-table schema, indexes, constraints, migration runner
- local-development.md — docker-compose setup, health checks, startup, Dockerfile gap noted
- security.md        — RSA key generation/rotation, CORS, bcrypt, secret storage guidance
- operations.md      — startup order, graceful shutdown, log reference, troubleshooting

QA gates: 48/48 tasks complete. All env vars verified against source.
All table names verified against migrations. All ports verified against
docker-compose.yml. All internal links resolve.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

openspec/changes/devops-documentation/tasks.md

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