Every fenced sample compiles, extracted — the doctest model instead of hand-picked gates

[btravers]

From the 2026-08-23 docs audit. This is the systemic version of #53 — if
adopted, it supersedes that issue's per-starter harness rather than adding to
it.

The record so far

Documentation samples in this repo drift, and the hand-picked gates catch only
the pages someone chose to gate. Three recurrences, two of them this week:

• The HTTP example contract validates nothing: type<>() is not a schema #74/Six docs pages still describe order-api before it had authentication #75 — six pages describing examples/order-api as it was before auth;
  answered by hand-building docs-examples.test-d.ts for the HTTP pages.
• 2026-08-23, PR feat(http)!: named security schemes, OpenAPI's model #89's final review — docs/tutorial/getting-started.md
  importing a deleted export, TS2305 on the tutorial's first sample. The page
  was outside every gate's file list.
• 2026-08-23, post-merge /code-review — two pages building a scoped answer as
  a plain object after granted() became mandatory; cast past the type error,
  every caller on the route is 403'd forever. The gate file covered the
  controllers and the router but not the authenticator — nobody had picked that
  half.

The pattern is structural: a curated gate protects the samples someone thought
to curate, and every drift so far happened in the complement.

The model to borrow

Rust compiles every fenced code block in documentation as a doctest;
opting out is the visible, annotated act (```ignore). The inversion is the
point — coverage is the default and gaps are declared, not discovered.

The shape here

A script (a sibling of docs/scripts/build-api.ts) that:

1. Extracts every ```ts fence from docs/**/*.md and the nine package
   READMEs into generated .test-d.ts units, grouped by the workspace whose
   dependencies the page needs (the mapping the root CLAUDE.md already
   states: kernel pages compile in packages/core, HTTP pages in
   examples/order-api, worker pages in the two workers).
2. Wires the generated units into each workspace's existing test:types, so
   pnpm typecheck is the gate and CI needs nothing new.
3. Supports an explicit opt-out marker for the fences that genuinely cannot
   compile (a deliberately-failing negative shown in prose, a shell block
   mislabeled ts) — visible in the source, counted in the script's output.

Illustrative fences that only exist to show a diagnostic can keep their
@ts-expect-error inline; the extractor preserves them, which turns every
documented compile error into a measured one — the same discipline the
.test-d.ts files already follow.

What it replaces

• docs-examples.test-d.ts for the four starters — the deferral's own trigger fired twice in PR #49 #53's four hand-built harnesses (never built for temporal/amqp/observability).
• The standing instruction that every site sample "was compiled when written in
  a scratch file, then deleted" — the scratch file stops being deleted.
• The post-hoc grep audits that PR feat(http)!: named security schemes, OpenAPI's model #89's fix waves ran.

Acceptance

• pnpm typecheck fails when any un-opted-out fence stops compiling.
• The three historical drifts above are all reproduced as failures against
  their pre-fix pages (the regression proof that the net actually catches what
  the curated gates missed).
• Opt-outs are enumerable (grep-able marker) and each carries a reason.
• Root CLAUDE.md's "Deferred, deliberately" entry for the starter gates is
  closed by this, and docs-examples.test-d.ts for the four starters — the deferral's own trigger fired twice in PR #49 #53 closed as superseded.