Content coverage map — public docs

Tracks public Fumadocs pages (web/content/docs/) against the sources that should keep them honest. Phase 1.5 seeded much of the site from engineering markdown; after the late-Phase-2 proxy work, docs should prefer implementation-native sources where available (services/*/README.md, packages/*, proto contracts, and accepted ADRs).

Treat this file as a living coverage map, not a one-time Phase 1.5 porting plan.

Coverage status

Area	Current source of truth	Coverage status	Notes
Getting started	`web/content/roadmap/current-state.mdx`, `Makefile`, `services/auth/README.md`, `services/proxy/README.md`	Current	Rebaselined for mock/live Phase 2; FAQ/quickstart no longer teach 501 as happy path
Architecture	`services/README.md`, `services/*/README.md`, accepted ADRs	Current	Overview/lifecycle updated for forwarding, sessions, traces
Proxy	`services/proxy/README.md`, `services/proxy/internal/http/`, `packages/directive`, `packages/injection`, `packages/authcache`, `packages/idempotency`, `packages/session`	Current	Feature deep-dives shipped for directives, sessions, auth cache, traces
Auth	`services/auth/README.md`, `packages/proto/proto/ibex/auth/v1/auth.proto`, accepted ADRs	Current	Proto-backed gRPC reference + issuing keys guides
Deployment / ops	`services/*/.env.example`, `infra/compose/dev/.env.example`, `services/proxy/internal/config/`, `packages/clickhouse`, `packages/metrics`, `packages/telemetry`	Current	Env docs + compose smoke path match late Phase 2
API reference	Manual MDX + proto (`auth.proto`) + HTTP route inventory	Current	Behavioral pages + `/docs/api-reference/http-routes`; OpenAPI / fumadocs-openapi deferred until CI-validated spec

Getting Started

Public page	Source	Notes
Introduction	`/roadmap/current-state`, `services/README.md`	Late-Phase-2 capability boundary
Concepts	`services/README.md`, `services/proxy/README.md`, `web/engineering/GLOSSARY.md`	Distinguishes shipped proxy features from Phase 3 memory
Quickstart	`Makefile`, `compose-dev`, `services/auth/README.md`, `services/proxy/README.md`	Mock-mode happy path; live optional
FAQ	Current docs corpus + issue/PR feedback	Mock/live + unregistered-model 501

Architecture

Public page	Source
Overview	`services/README.md`, accepted ADRs, `/roadmap/current-state`
Services	`services/*/README.md`, `packages/README.md`
Data model	`web/engineering/DATABASE_SCHEMA.md` plus session/directive ADRs
Request lifecycle	`services/proxy/README.md`, ADR-0011/0012/0013/0031/0035

Proxy

Public page	Source
Overview	`services/proxy/README.md`
Configuration	`services/proxy/.env.example`, `services/proxy/internal/config/`, `services/proxy/README.md`
Authentication	ADR-0011, ADR-0028, ADR-0029, `services/proxy/README.md`
Rate limiting	ADR-0015, `packages/ratelimit/`
Request routing	`services/proxy/README.md`, ADR-0012, ADR-0013, ADR-0031, ADR-0035
Provider adapters	`packages/provider/`, `packages/provider/openai/`, ADR-0025/0026/0027

Auth

Public page	Source
Overview	`services/auth/README.md`
Issuing API keys	ADR-0007, token management docs
Org & project model	`web/engineering/DATABASE_SCHEMA.md`, ADR-0014
Multi-tenant RLS	`web/engineering/SECURITY.md`, migration docs

Security

Public page	Source
Overview	`web/engineering/SECURITY.md` objectives + threat model
Authentication	ADR-0007, ADR-0010, ADR-0011
Tenant isolation	`web/engineering/SECURITY.md` §5, ADR-0014, ADR-0009
Secrets and keys	`web/engineering/ENVIRONMENT_VARIABLES.md`, ADR-0010

Deployment

Public page	Source
Docker Compose (dev)	`infra/compose/dev/`, `web/engineering/DEVELOPMENT_GUIDE.md`
Kubernetes	Honest future-facing stub until production manifests become authoritative
Environment variables	`services/*/.env.example`, `services/proxy/internal/config/`, `services/auth/internal/config/`

Operations

Public page	Source
Observability	`packages/metrics/`, `packages/telemetry/`, `services/proxy/internal/http/trace/`, ADR-0019/0021/0033
Troubleshooting	`web/engineering/TROUBLESHOOTING.md`, `services/auth/README.md`, `services/proxy/README.md`
Health checks	ADR-0022, `packages/healthcheck/`
Incident response	`web/engineering/runbooks/RUNBOOKS.md` (subset)

API Reference (manual + contract-backed)

Public page	Source
HTTP route inventory	`services/proxy/internal/http/router.go`, `router_protected.go`
Auth gRPC	`packages/proto/proto/ibex/auth/v1/auth.proto`, `services/auth/README.md`
Proxy health	`services/proxy/README.md`, ADR-0022
Chat completions	`services/proxy/README.md`, `services/proxy/internal/http/router.go`, ADR-0012/0013/0031/0035
Errors	ADR-0013 error envelope, `packages/provider/errors.go`, `packages/provider/map_error.go`

Deferred: OpenAPI auto-generation stays out of scope until a maintained openapi.yaml exists and is CI-validated against implemented routes.

ADRs

Public page	Source
ADR index + 0002–0023	`docs/adr/` → migrated to `web/content/docs/adr/`

Changelog & Glossary

Public page	Source
Changelog	`CHANGELOG.md` plus release parser pipeline
Glossary	`web/engineering/GLOSSARY.md` plus current docs corpus

Stays internal only

web/engineering/CODING_STANDARDS.md, web/engineering/FILE_STRUCTURE.md, web/engineering/TESTING_STRATEGY.md
web/engineering/DEPENDENCIES.md, web/engineering/PERFORMANCE.md, web/engineering/TOOLCHAIN.md, web/engineering/UI_UX_GUIDELINES.md
Full web/engineering/DATABASE_SCHEMA.md, web/engineering/API_DOCUMENTATION.md Phase 2+ surfaces
web/engineering/SECURITY-CI-GATES-DELIVERABLES.md, CI audit registers
Contributor workspace prompts (not published)

Public ADRs: /docs/adr. Canonical short-form status: /roadmap/current-state.