---
id: w4/m1/t007
title: ADR `docs/ADR012-auth.md` + docs index entry in root `CLAUDE.md`
worker: worker4
status: done
estimate: 30m
depends_on: [w4/m1/t006]
---

## Objective

Record the auth architecture as an ADR in `docs/ADR012-auth.md`, following the style of `docs/ADR009-postgresql-management.md`: why Ory (vs building auth into the control plane, vs Keycloak/etc.), the Kratos-vs-Hydra split of responsibilities, the two-CNPG-cluster DB topology and its rationale, secret handling (`.env` → out-of-band Secrets locally; sealed-secrets/SOPS in prod per w1/m7), and the bex-api integration plan (points at w4/m2: introspection middleware, `BEX_AUTH_MODE`, static-token fallback).

## Context

- ADR style reference: `docs/ADR009-postgresql-management.md` (Status line, Context, Decision with diagrams, alternatives considered).
- Goal linkage to cite: vision roadmap #1 (control-plane accounts), pillars 3–4 (per-agent credentials).
- Root `CLAUDE.md` has a "Docs index" section — add a one-line entry.

## Steps

1. Write `docs/ADR012-auth.md` grounded in what actually shipped in t001–t006 (manifests, hosts, secret names — no aspirational content).
2. Add the index line to root `CLAUDE.md`.
3. `npx prettier@3.4.2 --write "**/*.md"` (repo CI rule).

## Files

- `docs/ADR012-auth.md` (new)
- `CLAUDE.md`

## Acceptance criteria

- [ ] `docs/ADR012-auth.md` covers: why Ory, component roles, DB topology, secret handling, integration plan — each grounded in shipped manifests/paths.
- [ ] Root `CLAUDE.md` docs index links it; prettier passes.

## Out of scope

- User-facing auth documentation (how tenants log in) — that follows w4/m2.
