Add an in-app docs section

[duncankmckinnon]

Adds a Docs surface to the local web UI: five tabs explaining how valcore works, reachable without leaving the app.

What lands

• Docs in the sidebar, directly under Overview as the second ungrouped entry — it is what you read before you have anything to author or measure.
• Five tabs at /docs/:slug, driven by one registry: Keys, Evals, Datasets, Runs, CLI.

Tab	Covers
Keys	The three credentials from the Overview setup card, where each comes from, what breaks without it, and where they are stored
Evals	Judges, output fields and label spaces, active vs. frozen versions, capabilities, seeding a dataset
Datasets	Generated / uploaded / blank rows, generation settings and label mix, the labeling grid, when labels are required
Runs	Run kinds, confusion matrix vs. MAE/RMSE, comparison, run vs. experiment, --min-accuracy
CLI	Usage patterns: id-prefix resolution, the run flags, which command group to reach for, --db

Design decisions

The spec lives at docs/superpowers/specs/2026-08-11-web-docs-section-design.md (untracked — docs/superpowers/* is gitignored).

• TSX content, no markdown renderer. ui.tsx commits to no component library; a markdown parser dependency for static prose would violate that. TSX also lets docs link straight into live pages.
• One registry drives everything. Tab strip, routes, and titles read from a single ordered array, so a tab cannot exist without reachable content. Mirrors the existing SECTIONS array in Layout.tsx.
• /docs and unknown slugs resolve in-component, not by redirect: a stale link degrades to the first tab with its URL intact and no history entry spent.
• Keys leads, so it is what /docs lands on — nothing that calls a model runs until the gateway key exists. Reordering is one line in the registry; the tests assert against DOCS[0], not a hardcoded title.
• No data fetching. Docs render from static content, so they work with an empty workspace and never depend on the API.
• The README keeps its command table and every reference topic. It is the PyPI long_description, where a reader cannot open these tabs; the CLI tab teaches patterns instead of restating rows, so a new command means one edit, not two.

Bug caught during review

The first implementation used NavLink for the tabs, which derives active state by matching the URL. On the bare /docs route — and on any unknown slug — the first tab's body rendered under an entirely unlit tab strip, because /docs/keys does not match /docs. Tests passed, because they only asserted active state on a slug route; a screenshot caught it. Fixed by deriving the selected tab from the resolved entry (the tab whose body renders is the selected one), with two regression tests for the fallback paths.

Testing

• New: registry.test.tsx (order, unique slugs, resolveDoc fallbacks, every body smoke-renders), primitives.test.tsx (clipboard copy, external link target/rel, heading level), DocsPage.test.tsx (tab strip, slug selection, fallbacks, single h1), and App.test.tsx for the route table.
• Updated as predicted by the spec: Layout.test.tsx asserted exactly five nav links and now asserts six plus their full order; icons.test.tsx is table-driven over every icon, so DocsIcon joins the table and satisfies all eight shared assertions.
• styles.test.ts needed no edit — it reads every component from disk and fails on any class rendered but not defined, which is what forced the docs-* family to be complete.

586 tests passing across 43 files (up from 579 on main). tsc --noEmit clean, Vite build succeeds, and both /docs and /docs/cli were rendered in headless Chrome to confirm the dark-theme styling.

⚠️ The Python suite was not run. The local venv is unsynced — httpx, pydantic, and valcore itself are missing, and this sandbox has no network to sync it. This diff contains no Python, so nothing in it can affect that suite, but it is unverified here rather than verified-passing. CI will be the real check.

🤖 Generated with Claude Code