## 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)*