docs: reorganise by reader intent, and add a rendered site

[tito]

Why

Read as an integrator, the docs mixed implementation detail into task pages and buried the commands. Getting a provider registered meant reading about schema_migration transaction bookkeeping, two-stage Dockerfile design, cookie signing and cached-token normalisation first. There was no goal-based entry point: docs/README.md was a flat file list, so "I want to deploy this for my team, where do I start" had no answer.

What changed

Structure. 12 flat files become 16 organised by what the reader is doing:

docs/README.md              goal router, one screen
    getting-started.md      tutorial, now from the release binary not `git clone`
    install/               binary.md · docker.md · upgrades.md (new)
    guides/                providers · models · api-keys · pricing · usage · sso · claude-code
    reference/             configuration · api · openapi.yaml · performance
    concepts/              architecture.md

The two 400+ line pages were split along their real seams. keys-and-usage.md (446 lines, six topics) became three single-purpose pages; providers-and-models.md (421) became two.

Language. The rules now live in CONTRIBUTING.md so future pages stay consistent:

• Second person, imperative, present tense.
• One action per step, numbered, each with its command and the output that says it worked.
• Happy path first; variations (TLS, Postgres, overrides) under their own skippable headings.
• Rationale is one sentence and a link. The why lives in concepts/architecture.md, stated once.
• Consequences stay, justifications go. "Losing the secret invalidates every key" survives the cut; "the alternative would buy microseconds" does not, outside concepts/.
• Reference pages are tables, not narrative.

concepts/architecture.md and the README keep the explanatory voice deliberately. That split is stated in CONTRIBUTING.md rather than left implicit, so nobody flattens them later.

Load-bearing rationale moved rather than died. The cached-token normalisation treatise buried in the usage how-to is now a design rule in concepts/architecture.md, with a two-sentence definition left where an operator actually hits it. The migration transaction mechanics became five bullets in install/upgrades.md. The admin audit trail and pagination sections moved from the providers page to reference/api.md where they belong.

Deduplication. The loopback guard was explained three times; it is now stated once in install/binary.md, linked from docker.md and configuration.md.

Rendered site. mkdocs.yml (Material) plus a Docs workflow: mkdocs build --strict on every PR touching docs/, deploy to Pages on push to main. Every pre-reorganisation path redirects to its new home. just docs previews locally through uvx, so the repo gains no permanent Python dependency.

Testing

• mkdocs build --strict clean (fails on broken internal links).
• All 11 redirect stubs verified to generate and point at the right target.
• Every internal link and heading anchor across all 16 files verified to resolve, by script rather than by eye.
• go test ./... passing.

One prediction that did not hold

The plan expected total line count to drop noticeably. It rose 7% (2,457 → 2,639) while word count fell 4% (14,739 → 14,131), and that figure absorbs a wholly new page plus new sections in architecture.md and api.md. Prose was cut, but numbered steps, expected-output blocks and tables each take more lines than the paragraphs they replaced. Scannability is the goal that was met; the line-count prediction was simply wrong.

Two things needed from a maintainer

1. Enable GitHub Pages (Settings → Pages → source: GitHub Actions), or the deploy job fails on its first run on main. The strict build in this PR does not depend on it.
2. Old deep links break. github.com/.../docs/installation.md and friends have no redirect; the plugin only covers the rendered site. The repo went public recently so inbound links should be few, and stub files seemed worse than the breakage. Flagging it rather than hiding it.

Note on pinning

The MkDocs toolchain now warns that a 2.0 is planned which drops the plugin system entirely. mkdocs itself is pinned alongside the theme and redirects plugin in both CI and the just docs recipe, so that release cannot break the build unattended.