docs(api): every visible catalog row informative — tag-position fix, TSDoc backfill, collapse undocumented types, ratchet

[drewstone]

What

The primitive catalog (docs/api/primitive-catalog.md) is the anti-reinvention inventory, but 629 of its 1366 rows (46%) printed the same "(no summary…)" placeholder, destroying the scannability that is the artifact's whole job. This PR makes every visible table row informative, four layers:

1. Tag-position fix (mechanical, one-shot codemod — script not committed). 139 doc blocks had a bare @experimental/@stable as their FIRST content line with a real description after it; the TS compiler classes everything after a block tag as tag content, so getDocumentationComment returned empty and the row rendered blank. The tag now sits at the END of each block (TSDoc-correct: summary first, tags last). Recovers 38 catalog rows for free (e.g. openSandboxRun, Deliverable, runDelegatedLoop).
2. TSDoc backfill (36 hand-authored one-liners) at the keystone declarations canonical-api §2 and the examples point agents at: supervise, runLoop, createScope/createEventBus/createInbox/supervisorAgent, the RSI verbs (sample/refine/observe/runStrategyEvolution/promotionGate/harvestCorpus), the lifecycle entrypoints (runAgentTask/runAgentTaskStream/runConversationStream), sandbox/workspace seams, createMcpServer, the loop-runner family, the improvement generators, BenchmarkReport, ExecCtx. Wording condensed from the existing file-header docs + canonical-api.md.
3. Generator collapse: undocumented interface/type entries no longer occupy table rows — each section renders them as one compact "Undocumented supporting types: A, B, …" paragraph. Names stay backticked/greppable; existence is still proven. (Verified: check-docs-freshness.mjs resolves symbols from TypeDoc page headings, never from catalog table rows, so nothing in the gate needed a matcher change.)
4. Ratchet: the generator counts blank-summary function/class/const entries across all sections and exits 1 with the offending names when the count exceeds maxUndocumentedCallables = 108 (the exact current count). Rides the existing pnpm docs:check — no new CI job. New callables must ship with a TSDoc summary; the constant only ever moves down.

Numbers

	before (origin/main)	after
visible blank rows	629 / 1366 symbols (46%)	108 / 919 rows (12%)
blank interface/type rows	465 (419 interface + 46 type)	0 visible (18 recovered; 447 collapsed into 16 per-section paragraphs)
blank callables (function/class/const), own / substrate	131 / 33	75 / 33 — capped by the ratchet at 108
catalog length	1496 lines	1081 lines

Verification

• pnpm run lint / pnpm run typecheck (incl. examples) / pnpm test — 122 files, 1194 passed, 2 skipped.
• pnpm run build && pnpm run docs:api && pnpm run docs:check — green; regenerated docs/api committed.
• Ratchet proven live: lowering the ceiling to 107 exits 1 and lists all 108 undocumented callables.

Follow-up (upstream)

33 of the remaining 108 blank callables are agent-eval re-exports (CAMPAIGN 24, JUDGE 7, VERIFICATION 2) that genuinely lack TSDoc at their dist declarations — needs an agent-eval issue (incl. the tsup dts comment-detachment case where heldOutGate's description lands on HeldOutGateOptions); this catalog auto-heals on the next version bump.

[tangletools]

✅ Auto-approved drewstone PR — ce78ddc8

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-02T22:22:19Z}