docs: README rewrite + follow-up fixes from external review

[babs]

Summary

Two-part change:

1. README rewrite

The README's 39-row configuration mega-table was unscannable. Split into:

• README (~370 lines): TL;DR runtime contract + Requirements at the top, the 6 required env vars, a "Production posture" callout summarising the safe-by-default guarantees, and pointers to the new reference doc.
• docs/configuration.md (NEW): full env-var reference grouped by purpose — Required / Listeners & logging / Identity & authorization / Signing & rotation / Replay store / Rate limiting / Resource management / Production posture / Logging & observability — plus the alerting playbook and PromQL recipes that lived inline.

A new reader can land on the README, deploy in 5 minutes, and dig into the reference doc only when they need to. The architecture diagram, sealed-state TTL table, endpoint table, and supply-chain verification sections all stay in the README.

2. Follow-up fixes from a review pass

Doc drift caught by a fresh-eyes review:

• docs/threat-model.md row 12 referenced token/seal.go and token/seal_test.go; actual paths are token/token.go + token/fuzz_test.go + token/token_test.go.
• /readyz endpoint in the README table was flagged as if public; it lives on the metrics listener (port 9090). Fixed.
• Per-replica rate-limit scope was implicit; now called out in both README (production-posture section) and docs/configuration.md (rate-limiting section). Operators sizing N replicas multiply the per-endpoint ceiling accordingly.

Contract fix:

• MCP_TOOL_METRICS_MAX_CARDINALITY=0 is now accepted as the documented "disable the cap" sentinel. The consumer at metrics.ToolCardinality.ToolLabel already gates on MaxCardinality > 0; the only blocker was the config validator rejecting 0 with "must be a positive integer". Negative values still fail. New regression test TestLoad_ToolMetrics_ZeroDisablesCap pins the contract.

Supply-chain pins:

• Dockerfile base images pinned by @sha256 digest (golang:1.26-alpine and gcr.io/distroless/static-debian13:nonroot). A base-image rebuild can no longer silently change the published binary's environment.
• CI's govulncheck install pinned to v1.1.4 (was @latest).

README polish:

• TL;DR uses <your-idp-secret> placeholder (copy-paste-safe) and a reachable Redis hostname.
• TOKEN_SIGNING_SECRET row cross-references the key-rotation runbook.
• OIDC_ALLOW_INSECURE_HTTP moved next to the other PROD_MODE-gated relaxation toggles.
• MCP_PER_SUBJECT_CONCURRENCY split into a dedicated "Resource management" sub-section (it's a concurrency cap, not a rate limit).
• Observability heading renamed for a clean GitHub anchor.

Items deferred to a follow-up PR

The same review flagged two items that need their own focused PR with regression tests:

• TOKEN_SIGNING_SECRET entropy gate is structurally flawed. A 64-char openssl rand -hex 32 value is drawn from a 16-symbol alphabet — the expected number of distinct chars is ~15.75, so a real random secret can intermittently fail the < 16 distinct bytes check while a patterned 0123456789abcdef0123456789abcdef (exactly 16 distinct bytes) passes. False-positive AND false-negative on the same heuristic. Will replace with an obvious-pattern check + align docs on manifests/scripts/generate-signing-secret.sh.
• Optional Redis-backed rate limiter for deployments that want a true cluster-wide ceiling rather than the documented N × per-replica math.

Test plan

• CI green (test, lint, keycloak-e2e, fuzz-smoke, manifest-prod, govulncheck, build).
• go test ./config/ -run "ToolMetrics" -v passes (incl. new ZeroDisablesCap regression).
• Manual: render the README on github.com — TL;DR is the first thing after the diagram; cross-references resolve.