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/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-28

openspec/changes/devops-documentation/design.md

@@ -0,0 +1,48 @@
+## Context
+
+Phase 1 MVP is complete and live on `develop`. The bedroom developer docs cover the API surface. DevOps engineers — responsible for deployment, configuration, and operations — have no documentation. This gap creates operational risk: misconfigured environment variables, missed migration steps, and no recovery path when services fail.
+
+**Audience**: Engineers who deploy and operate the AgentIdP infrastructure. Assumed knowledge: Linux shell, Docker, PostgreSQL basics, Node.js process management.
+
+**Constraints:**
+- Markdown only — renders on GitHub, no build step
+- All commands are exact and runnable — no placeholders
+- Honest about Phase 1 P1 gaps: Dockerfile does not exist yet; document what works now and mark pending items clearly
+- Files live in `docs/devops/` — separate from `docs/developers/`
+
+## Goals / Non-Goals
+
+**Goals:**
+- DevOps engineer can stand up a working local environment from scratch using only these docs
+- Every environment variable is documented with type, requirement, and example
+- Database schema and migration procedure are fully documented
+- Security setup (JWT keys, CORS, secrets) is step-by-step
+- Operations runbook covers the most likely failure scenarios
+
+**Non-Goals:**
+- Container deployment guide (Dockerfile is Phase 1 P1 — not built yet)
+- Cloud/Kubernetes deployment (Phase 2)
+- Monitoring/alerting setup (Phase 2)
+- Multi-region or HA configuration (Phase 2)
+
+## Decisions
+
+**Decision 1: Separate folder vs subdirectory of docs/developers/**
+Chosen: `docs/devops/` as a peer of `docs/developers/`.
+Reason: Different audiences, no shared content, prevents confusion.
+
+**Decision 2: Mark Dockerfile gap explicitly**
+Chosen: `local-development.md` documents working `docker-compose` + `npm` path; `Dockerfile` noted as Phase 1 P1 pending with a placeholder section.
+Reason: Honest documentation prevents broken deployments.
+
+**Decision 3: Operations and security as separate files**
+Chosen: `security.md` and `operations.md` are separate.
+Reason: DevOps engineers frequently consult these independently — security during setup, operations during incidents.
+
+## Migration Plan
+
+Documentation only. No code changes. No rollback needed.
+
+## Open Questions
+
+*(none — scope fully defined)*

openspec/changes/devops-documentation/proposal.md

@@ -0,0 +1,19 @@
+## Why
+
+SentryAgent.ai AgentIdP Phase 1 MVP is complete and `docs/developers/` covers API consumers. However, there is no documentation for the engineers who deploy, configure, and operate the infrastructure. A DevOps engineer joining the project today has no reference for environment variables, database schema, deployment procedure, security configuration, or operational runbook. We fix that now.
+
+## What Changes
+
+- New `docs/devops/` folder — fully separate from `docs/developers/` — containing a complete operational reference for DevOps engineers
+- System architecture overview: components, ports, dependencies, data flow
+- Complete environment variable reference: every variable, required vs optional, format, examples
+- Database documentation: 4-table schema, migration runner, how to apply/verify migrations
+- Local development guide: docker-compose infrastructure setup, service ports, health checks
+- Security guide: RSA keypair generation and rotation, CORS config, secret storage
+- Operations runbook: startup procedure, graceful shutdown (SIGTERM/SIGINT), logging, common failures and fixes
+
+## What Does Not Change
+
+- `docs/developers/` — not touched
+- Source code — documentation only
+- No new dependencies

openspec/changes/devops-documentation/specs/database/spec.md

@@ -0,0 +1,4 @@
+## ADDED Requirements
+
+### Requirement: Database doc exists at docs/devops/database.md
+The system SHALL provide `docs/devops/database.md` documenting the 4-table schema (agents, credentials, audit_events, token_revocations), the migration runner, and exact commands to apply and verify migrations.

openspec/changes/devops-documentation/specs/deployment/spec.md

@@ -0,0 +1,4 @@
+## ADDED Requirements
+
+### Requirement: Local development guide exists at docs/devops/local-development.md
+The system SHALL provide `docs/devops/local-development.md` documenting the complete local setup using docker-compose for infrastructure and npm for the application server, including all service ports, health check verification, and the Dockerfile gap note.

openspec/changes/devops-documentation/specs/operations/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+
+### Requirement: Security guide exists at docs/devops/security.md
+The system SHALL provide `docs/devops/security.md` documenting RSA keypair generation, key rotation procedure, CORS configuration, and secret storage guidance.
+
+### Requirement: Operations runbook exists at docs/devops/operations.md
+The system SHALL provide `docs/devops/operations.md` covering startup procedure, graceful shutdown (SIGTERM/SIGINT), log interpretation, and troubleshooting for the most common operational failures.

openspec/changes/devops-documentation/specs/system-overview/spec.md

@@ -0,0 +1,10 @@
+## ADDED Requirements
+
+### Requirement: System overview exists at docs/devops/README.md
+The system SHALL provide a `docs/devops/README.md` that serves as the entry point for DevOps engineers, including an index of all DevOps docs and a brief system overview.
+
+### Requirement: Architecture doc exists at docs/devops/architecture.md
+The system SHALL provide `docs/devops/architecture.md` documenting all components (Express server, PostgreSQL, Redis), their roles, ports, and data flow.
+
+### Requirement: Environment variable reference exists at docs/devops/environment-variables.md
+The system SHALL provide `docs/devops/environment-variables.md` documenting every environment variable with name, type, required/optional, default, and example value.

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