fix(mcp): agent-docs prose corpus is a stale pre-#1373 snapshot — 60 `api-clients` references still ship to agents, and no CI check can see it

[rickylabs]

Summary

docs/site contains zero references to lib/api-clients.ts — #1373/PR #1424 swept it clean.
But the checked-in agent-docs prose corpus still carries 60 occurrences, and that corpus is
compiled into packages/mcp/src/publish-assets.generated.ts and shipped to every agent that reads
NetScript documentation through MCP. The corpus snapshot was taken ~6 hours before the sweep
merged and nothing regenerates or diffs it in CI, so the staleness is invisible by construction.

This is the same defect class as #1425 (a surface #1373's page-scoped acceptance did not cover),
at 60× the count and on the surface agents actually read.

Evidence

Verified at 01aa12b67:

1. docs/site is clean. grep -rn "api-clients" docs/ → 0 matches.
2. The corpus is not. gunzip -c .llm/assets/agent-docs/prose.json.gz | grep -o "api-clients" | wc -l
   → 60.
3. It ships. packages/mcp/src/publish-assets.generated.ts (header:
   // @generated by .llm/tools/generate-publish-assets.ts) embeds that prose, including
   a `lib/api-clients.ts`, that exports a typed `ordersClient`…, // apps/dashboard/lib/api-clients,
   and import { widgets } from "../lib/api-clients — i.e. the exact module path and the exact
   dialect fix(docs/sdk): the golden path names three different client modules and two incompatible query APIs, and the file the quickstart points at is a CSS entry #1373 removed. .llm/tools/generate-publish-assets.ts:3 imports the docs-corpus port;
   :190 reads .llm/assets/agent-docs/prose.json.gz.
4. The snapshot predates the fix by ~6 hours. .llm/assets/agent-docs/provenance.json:
   "version": "0.0.5", "sourceCommit": "eda49bb2e", "extractionTimestamp": "2026-08-09T10:03:43Z".
   eda49bb2e is dated 2026-08-09 09:25:38 +0200. PR fix(docs/sdk): teach one client module and query dialect #1424 (fix(docs/sdk): teach one client module and query dialect) merged at 2026-08-09T16:04:57Z. The corpus has not been
   regenerated since.
5. Nothing regenerates or diffs it in CI. gen:agent-docs-prose (deno.json:106) appears in
   no workflow. check:assets-barrel (deno.json:109) runs gen:assets-barrel and diffs the
   *.generated.ts barrels, but never runs gen:agent-docs-prose, so a prose corpus that has
   drifted from docs/site produces no diff and no failure.

Why it matters

The MCP corpus is the surface an agent consumes when it asks NetScript how to write a data layer.
Today it teaches lib/api-clients.ts and the demoted query dialect, while every human-facing page
teaches apps/<app>/lib/<service>.ts. An agent scaffolding from our own documentation produces
code that does not match the framework it just read about — and the human-facing sweep that was
supposed to fix this shipped three days ago.

Scope

• Regenerate the agent-docs prose corpus from current docs/site and rebuild the dependent
  generated assets.
• Add a CI gate that fails when the corpus is stale relative to its sources — the same
  regenerate-and-diff shape check:assets-barrel already uses for the barrels, extended to
  gen:agent-docs-prose. Without the gate, the next docs sweep re-opens this issue.

Boundaries

• mcp: include SDK guidance in the shipped search_docs corpus #1260 owns what SDK prose ships in the MCP corpus (content selection). This issue is about
  the corpus being a stale snapshot of whatever docs/site says, not about which pages belong
  in it.
• mcp: serve the generated export surfaces, not just prose docs — the most-used doc surface has no MCP path #1201 owns serving export surfaces through MCP.
• test(docs): docs:accuracy is a fixed-string needle checker — no docs/site code block is ever compiled, and a CLI change never revalidates the site #1374 owns compiling docs/site code blocks. A compile gate over docs/site would not have
  caught this — the stale copy lives outside docs/site.
• fix(sdk): JSDoc example still imports the removed ./api-clients.ts module, rendering on JSR #1425 owns the single stale JSDoc occurrence in packages/sdk, which is where this was found.

Acceptance criteria

• gunzip -c .llm/assets/agent-docs/prose.json.gz | grep -c "api-clients" returns 0.
• packages/mcp/src/publish-assets.generated.ts contains no api-clients reference.
• provenance.json's sourceCommit is at or after PR fix(docs/sdk): teach one client module and query dialect #1424's merge commit 2e7c845ad.
• A CI check regenerates the prose corpus and fails on drift from docs/site.
• Negative test: reverting a docs/site page without regenerating the corpus fails that check.

Provenance

Found by the 0.0.6 documentation-lane orchestrator while independently verifying PR #1526's
repo-wide api-clients census (#1425). The census was correct within its stated scope
(packages/sdk/**); this is the surface that scope did not cover. Filed to Backlog / Triage
rather than 0.0.6 because it falls outside that lane's exclusive ownership — triage should decide
whether it belongs in the current release.

[rickylabs]

Independently corroborated, with one detail that makes this sharper

A separate fresh-session reviewer hit this from a different direction while adversarially reviewing PR #1526, and found the same drift plus a fact the original filing missed.

The stale corpus violates a rule the repo already enforces. The snapshot of docs/site/web-layer/query.md embedded in packages/mcp/src/publish-assets.generated.ts contains not only // apps/dashboard/lib/api-clients.ts and from "../lib/api-clients.ts" (×3), but also from "@contracts" — and @contracts is a term explicitly forbidden by .llm/tools/docs/check-accuracy-and-discoverability.ts:57.

So the corpus is not merely stale: it ships a string the repo's own accuracy gate would reject on sight. The gate cannot see it because that checker walks docs/site only (:38), while the shipped copy lives in packages/mcp. The source page is clean — grep -n "api-clients" docs/site/web-layer/query.md exits 1.

This tightens the fix: the missing CI check does not need to be invented from scratch. Pointing the existing forbidden-term assertions at the generated corpus as well as at docs/site would have caught this, and would catch the next one, independently of whether the regenerate-and-diff check lands.

Everything in the original filing stands unchanged: 60 occurrences in prose.json.gz, provenance sourceCommit eda49bb2e / extractionTimestamp 2026-08-09T10:03:43Z, PR #1424 merged 2026-08-09T16:04:57Z, and gen:agent-docs-prose referenced by no workflow.