docs: a configuration reference, because there wasn't one

[ExposureGuard]

Independent of #73/#74/#75 — branched from main.

The gap

.env.example documents eight of the forty-eight HALDIR_* names the code reads. The rest — Postgres pool sizing, the Ed25519 signing keys, the transparency mirror, SMTP, the metrics token, the log switches, x402 — were discoverable only by reading the modules that use them. For a product you self-host, that's the difference between "configurable" and "configurable if you read the source".

What this adds

CONFIGURATION.md — every variable, its default, and what it does, grouped by what you're trying to do (start here / storage / logging / tamper-evidence / HTTP / outbound / MCP / x402 / email / containers / build-only) rather than alphabetically. Packaged with the wheel and sdist alongside SELF_HOSTING.md, CLI.md and THREAT_MODEL.md, and linked from the five-minute setup — the point where someone has finished the required settings and starts wondering what else there is.

tests/test_configuration_docs.py — scans the tree for names the code refers to as string literals and fails when one is missing from the document. Same shape as the version-literal and packaging guards, for the same reason: a fact that lives in one place and is checked in none.

It found a bug before it was committed

haldir_mcp_proxy.py's usage line advertised HALDIR_SESSION_ID=ses_xxx — a variable nothing has ever read. The proxy creates its own session on first use (_ensure_session), so anyone who set it got a silent no-op. The docstring says what actually happens now.

(The scan also produced two false positives on its first run — HALDIR_KEY in a shell example, HALDIR_VERSION as a Python identifier. It requires the name to stand alone as a string literal, which excludes both; both cases are commented in the test.)

Verification

• 1093 tests pass, flake8 clean, mypy clean over 29 files
• Wheel built and inspected — CONFIGURATION.md ships
• The scan reports 48 names in code, all documented; the only names in the doc that no code reads are HALDIR_PORT (read by docker-compose.yml, documented under Containers) and HALDIR_ORIGIN_SECRET (the variable release(0.4.3): the client address, the spec, and the OAuth metadata #73 adds — documented here ahead of it, so merging either order leaves the guard green)

🤖 Generated with Claude Code