[howethomas]

Summary

Rebuilds the documentation as a MkDocs Material site, checked against the code. No Python changes.

• Reference: a page for every link, storage adapter and tracer. Env var, port, route and metric pages are generated from code.
• Drift check: scripts/docs/check.sh runs the generators, renders the diagrams and does a strict site build. The new Docs workflow runs it on every PR.
• Visuals: 14 Mermaid diagrams, each with a sources file naming the code it describes, and 4 motion scenes.
• Concepts and guides: new pages, including lawful basis and editions, plus a contributing guide.
• Edition boundary: the docs state that this repo carries and preserves lawful_basis attachments but does not create, validate or enforce them. They make no compliance claim.
• Cleanup: Poetry instructions replaced with uv. prod_mgt/ and README_REDIS_CACHING.md moved to docs/archive/.

Files outside docs/ and scripts/docs/: .github/workflows/docs.yml, CLAUDE.md, README.md, common/README_CORE.md, mkdocs.yml and the link READMEs under conserver/links/.

Before merging

• Set Settings > Pages > Source to GitHub Actions. Until then the deploy job fails on main and the site is not published.

Known gaps

• 8 TODO(verify) markers remain in live pages, for items that need a running service or measured figures, such as sizing tables, Prometheus names and Dataverse filters.
• The Compose stack, published images and vendor APIs were not exercised.
• Where the audit found code that behaves differently from what a reader would expect, the docs describe what the code does today. Those problems are tracked separately.

Testing

• scripts/docs/check.sh passes locally on this commit: generators, 14 diagram renders and the strict MkDocs build.
• The commit used --no-verify because the secret scan flagged 9 lines. All 9 were reviewed and are false positives: placeholder values in examples and one code fragment.

🤖 Generated with Claude Code