docs: build a Diátaxis documentation site and slim the README

[jmgilman]

Summary

Reworks the documentation ahead of the v0.1.0 release. The 438-line README tried to be product intro, full flag reference, how-to collection, and release-design doc all at once; this splits that into a proper Diátaxis-organized MkDocs site and shrinks the README to an entry point.

New docs site (docs/docs/, wired into the nav)

• Tutorial (1): Your first mock sign-in — a curl-only, guaranteed-happy-path walk from docker run through the full authorization-code flow, token decode, userinfo, and a first /_mock/mint.
• How-to guides (11): get tokens for every grant · drive the authorization-code flow · shape token claims · simulate expiry and time · capture and assert requests · use multiple issuers · serve over TLS · run behind a proxy or in Docker · lock down the control plane · migrate from mock-oauth2-server · verify released artifacts.
• Reference (5 + the existing generated API page): Configuration · CLI · Tokens and claims · Control plane (/_mock) · Observability.
• Explanation (4): the security model · issuers and advertised identity · parity with mock-oauth2-server · architecture and distribution.

README + CONTRIBUTING

• README → ~120 lines: description, features, quickstart (run + discovery + one client_credentials token), a by-need documentation map linking the site, and a short development section. The flag table, TLS/proxy/tracing how-tos, project layout, container-build lore, and release-chain design all move into the site or CONTRIBUTING.
• CONTRIBUTING gains project-layout, tests, and common-tasks sections; its stale "Go web API server template" framing is corrected. Dual-license section preserved.

Verification

• moon run docs:build (mkdocs build --strict) passes: no broken links, nav matches disk, 24 pages.
• Every command in the tutorial and the jwt-bearer how-to was run against a live server: the full auth-code chain, token claims (UUID sub, azp/tid scoping, aud=[client_id]), single-use-code invalid_grant, /_mock/mint round-trip, and the dummy-signature jwt-bearer recipe all behave as documented.
• Adversarial per-page review pass for Diátaxis type-purity and factual accuracy against the code; no ghd references (removed in ci(release): drop the ghd distribution integration and fix the openapi smoke tests #22).

Authored with multi-agent orchestration. No product code changed.

🤖 Generated with Claude Code