docs(devops): update all documentation for DockerSpec compliance

- Replace all docker-compose.yml/docker-compose.monitoring.yml references with
  compose.yaml/compose.monitoring.yaml (modern Compose Spec naming)
- Replace all `docker-compose` CLI commands with `docker compose` (plugin syntax)
- Update Dockerfile stage descriptions: node:18-alpine → node:20.11-bookworm-slim,
  built-in node user → explicit nodeapp:1001 non-root user
- Update image version references: postgres:14-alpine → postgres:14.12-alpine3.19,
  redis:7-alpine → redis:7.2-alpine3.19
- Externalize postgres credentials: hardcoded values → POSTGRES_USER/PASSWORD/DB env vars
- Externalize Grafana admin password: hardcoded 'agentidp' → GF_ADMIN_PASSWORD env var
- Add Docker Compose Variables section to environment-variables.md (POSTGRES_*, GF_ADMIN_PASSWORD)
- Update local-development.md Step 3: cp .env.example .env, document POSTGRES_* purpose
- Update quick-start.md: cp .env.example .env, use awk/sed for JWT key injection
- Update 07-dev-setup.md: remove 'no .env.example' claim, reference cp .env.example
- Update docker-compose.yml key file description in 04-codebase-structure.md
- Update monitoring overlay launch commands across all docs (compose.yaml + compose.monitoring.yaml)
- Update volume names to kebab-case: postgres_data → postgres-data, redis_data → redis-data
- Fix compliance encryption-runbook: docker-compose restart agentidp → docker compose restart app

All docs now consistent with compose.yaml in repo root.

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

docs/engineering/03-tech-stack.md

@@ -123,8 +123,8 @@ rate-limiter uses a Redis sorted set for the sliding-window algorithm.
 - PostgreSQL for revocation — rejected because the token verification path is the hot path in every authenticated request. A PostgreSQL round-trip adds 5–15 ms compared to a Redis `GET` at sub-millisecond latency.
 
 **Consequences**: Redis is a required infrastructure dependency. A Redis instance must
-be running and reachable via `REDIS_URL` before the server starts. `docker-compose.yml`
-provides a Redis 7 Alpine container for local development on port 6379.
+be running and reachable via `REDIS_URL` before the server starts. `compose.yaml`
+provides a Redis 7.2 Alpine container for local development on port 6379.
 
 ---
 
@@ -217,7 +217,7 @@ environments. The `prom-client` npm package integrates natively with Express and
 provides `Counter` and `Histogram` metric types that cover all observability needs for
 AgentIdP. Grafana's YAML provisioning in `monitoring/grafana/provisioning/` makes
 dashboards reproducible and version-controlled. The monitoring stack runs as a Docker
-Compose overlay (`docker-compose.monitoring.yml`) without interfering with the base dev
+Compose overlay (`compose.monitoring.yaml`) without interfering with the base dev
 environment.
 
 **Alternatives considered**:

docs/engineering/04-codebase-structure.md

@@ -56,8 +56,8 @@ sentryagent-idp/
 │   ├── agntcy-conformance/    # AGNTCY conformance test suite (separate Jest config)
 │   └── load/                  # k6 load test scripts
 ├── Dockerfile                 # Multi-stage production build (build + runtime stages)
-├── docker-compose.yml         # Local development: PostgreSQL 14 (port 5432) + Redis 7 (port 6379)
-├── docker-compose.monitoring.yml  # Monitoring overlay: Prometheus (port 9090) + Grafana (port 3001)
+├── compose.yaml               # Local development: PostgreSQL 14.12 (port 5432) + Redis 7.2 (port 6379)
+├── compose.monitoring.yaml    # Monitoring overlay: Prometheus (port 9090) + Grafana (port 3001)
 ├── package.json               # Node.js dependencies and npm scripts
 ├── tsconfig.json              # TypeScript strict configuration — compiled to dist/
 └── jest.config.ts             # Jest configuration — ts-jest, test timeouts, coverage thresholds
@@ -134,11 +134,14 @@ The `errorHandler` middleware in `src/middleware/errorHandler.ts` maps
 `SentryAgentError` subclasses to their `httpStatus` codes and serialises the response
 as `IErrorResponse { code, message, details }`.
 
-**`docker-compose.yml`**
-Starts PostgreSQL 14 (Alpine) on port 5432 with database `sentryagent_idp` and
-Redis 7 (Alpine) on port 6379. Used for local development only. Both services have
-health checks so `depends_on` conditions work correctly. The `app` service mounts
-`./src` as a read-only volume for live code reloading.
+**`compose.yaml`**
+Starts PostgreSQL 14.12 (Alpine) on port 5432 and Redis 7.2 (Alpine) on port 6379.
+All services use a dedicated `app-tier` bridge network, `restart: unless-stopped`,
+and `deploy.resources.limits` per DockerSpec standards. Both infrastructure services
+have health checks so `depends_on` conditions work correctly. The `app` service mounts
+`./src` as a read-only bind volume for live code reloading and has its own
+`healthcheck` probe via `curl /health`. Postgres credentials and Grafana admin
+password are externalized to environment variables — see `docs/devops/environment-variables.md`.
 
 **`tsconfig.json`**
 TypeScript compiler configuration. `strict: true` enables the full suite of strictness

docs/engineering/05-services.md

@@ -332,10 +332,10 @@ not exposed to the public internet.
 
 Start the monitoring overlay:
 ```bash
-docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up
+docker compose -f compose.yaml -f compose.monitoring.yaml up
 ```
 - Prometheus: `http://localhost:9090`
-- Grafana: `http://localhost:3001` — default credentials: `admin` / `agentidp`
+- Grafana: `http://localhost:3001` — credentials: `admin` / `<GF_ADMIN_PASSWORD from .env>`
 
 Grafana is pre-provisioned with a Prometheus data source pointing to `http://prometheus:9090`
 and dashboard JSON files from `monitoring/grafana/dashboards/`. No manual configuration

docs/engineering/07-dev-setup.md

@@ -44,18 +44,24 @@ development dependencies (TypeScript, Jest, ts-jest, eslint).
 
 ## 8.3 Environment Variables Setup
 
-The server requires a `.env` file at the project root. There is no `.env.example`
-file — create it from scratch using the template below.
+The server requires a `.env` file at the project root. Copy the template:
 
 ```bash
-touch .env
+cp .env.example .env
 ```
 
-Add the following content to `.env`. Every variable is documented below.
+The template includes all required variables with sensible local defaults. Edit `.env` to set your values. Key variables are documented below.
 
 ```bash
 # ─────────────────────────────────────────────────────────────
-# PostgreSQL connection
+# PostgreSQL — individual credentials for compose.yaml
+# ─────────────────────────────────────────────────────────────
+POSTGRES_USER=sentryagent
+POSTGRES_PASSWORD=sentryagent
+POSTGRES_DB=sentryagent_idp
+
+# ─────────────────────────────────────────────────────────────
+# PostgreSQL connection (application reads this directly)
 # ─────────────────────────────────────────────────────────────
 DATABASE_URL=postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp
 

docs/engineering/10-deployment.md

@@ -8,12 +8,12 @@ This document covers building and running AgentIdP in production: Docker, enviro
 
 The Dockerfile uses a two-stage build:
 
-- **Stage 1 (builder):** `node:18-alpine` — installs all dependencies (including dev) and compiles TypeScript to `dist/`.
-- **Stage 2 (production):** `node:18-alpine` — copies `dist/` and `node_modules` (production only), runs as the built-in non-root `node` user.
+- **Stage 1 (build):** `node:20.11-bookworm-slim` — installs all dependencies (including dev) and compiles TypeScript to `dist/`.
+- **Stage 2 (final):** `node:20.11-bookworm-slim` — copies `dist/` and `node_modules` (production only), installs `curl` for healthcheck, and runs as the created non-root `nodeapp` user (UID 1001).
 
 ```bash
 # Build
-docker build -t sentryagent-idp:latest .
+docker build -t sentryagent-idp:1.0.0 .
 
 # Run (supply required env vars)
 docker run -d \
@@ -22,18 +22,18 @@ docker run -d \
   -e REDIS_URL=redis://<host>:6379 \
   -e JWT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..." \
   -e JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..." \
-  sentryagent-idp:latest
+  sentryagent-idp:1.0.0
 ```
 
-The container exposes port `3000`. Override with `PORT` environment variable if needed.
+The container exposes port `3000`. Override with `PORT` environment variable if needed. The container runs as non-root user `nodeapp` (UID 1001) — do not mount volumes requiring root ownership.
 
 For local full-stack development, use Docker Compose instead:
 
 ```bash
-docker compose up -d
+docker compose up --build -d
 ```
 
-The `docker-compose.yml` starts the app, PostgreSQL 14, and Redis 7 with health checks and data volumes.
+The `compose.yaml` starts the app, PostgreSQL 14.12, and Redis 7.2 with health checks, resource limits, restart policies, and data volumes — per DockerSpec standards.
 
 ---
 
@@ -178,11 +178,11 @@ The HTTP metrics (`agentidp_http_requests_total` and `agentidp_http_request_dura
 ### Local Grafana
 
 ```bash
-docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d
+docker compose -f compose.yaml -f compose.monitoring.yaml up -d
 ```
 
 - Prometheus: http://localhost:9090
-- Grafana: http://localhost:3001 (admin password: `agentidp`)
+- Grafana: http://localhost:3001 (admin password: `GF_ADMIN_PASSWORD` value from `.env`)
 
 The monitoring compose overlay starts `prom/prometheus:v2.53.0` and `grafana/grafana:11.2.0`. Grafana dashboards and datasource provisioning are loaded from `monitoring/grafana/provisioning/`.