docs(examples): three-persona cleanup — newcomer/senior/junior

[drewstone]

Applies the genuine-defect fixes from a three-persona (newcomer / senior / junior) review of the 22 examples. Scope: fix the things that actively mislead a reader, and clean the rough edges that teach the wrong habit — without churning the examples judged good/great. Every example still typechecks (typecheck:examples), the held-out coding-benchmark anti-cheat + its smoke test stay intact, and docs:check stays green.

Genuine defects fixed (these mislead a reader)

• self-improving-loop — the demo gates at n=3 yet called it "the production held-out gate's statistical core" flatly, re-teaching this repo's documented fix: persist final runtime stream failures #1 failure mode (the small-n mirage). Added a loud minimum-evidence-floor caveat at the gate() definition AND in the README: the production gate floors the evidence (heldoutSignificance won't report a pair under minSamples, default 8; HeldOutGate rejects below minProductiveRuns with few_runs) — never ship a real change on n=3. (helps the junior most — the persona most likely to lift gate() verbatim).
• delegate — was a Tier-1 example with no README, and the file was a CI test (E2E PASSED, process.exit) wearing an example's clothes, with internal history in the header. Added README.md; split a lean teaching delegate.ts + reusable shared.ts from the regression proof, which moved to tests/delegate-example.test.ts (env-gated: a paid live e2e when TANGLE_API_KEY is set, an always-on offline fail-loud assertion otherwise); stripped the history per the repo's no-history-in-source rule. (newcomer + senior).
• improve — README named ImprovementDriver / gepaDriver; improve() actually builds SurfaceProposer / gepaProposer. Corrected both, plus the stale test path (src/improvement/improve.test.ts). (a README grep now resolves).
• knowledge-gating — README featured adapter.onKnowledgeBlocked as the headline hook but the adapter never defined it (doc/code drift). Wired the hook into the adapter so the blocked run demonstrates it (converts the gap into a "would ask the user" decision that flows through as the stop reason).

Quality wins (remove ceremony / amateur tells, no behavior change)

• coding-benchmark — renamed offlineSolutions → offlineAgentScripts with a clear 2-line header; kept the rate-limiter cheat/real pair inline (the one anti-cheat teaching moment), moved the round-invariant csv-parser / lru-cache real impls to fixtures.ts as readable template literals (no + '\n' + escaped-string ceremony). The held-out anti-cheat, the firewall test, the reps-don't-fake-n regression, and the BH-corrected stats are all unchanged and still pass.
• supervise — wrapped the flagship in main().catch (matching the sibling examples) and uncommented the completion-oracle deliverable so the headline models the safe path.
• ui-audit — LENSES_TO_RUN → lensesToRun (the publish-safe module-global convention; an UPPERCASE module-global trips the Tangle obfuscator).
• driver-loop / researcher-loop — one-line justification at the offline-box as unknown as SandboxInstance casts (the other casts already carried one).
• strategy-evolution README — one line noting promoted: false at toy scale is the gate working, not a break.

Left alone (already good/great — no churn)

driver-loop, strategy-suite, supervisor-loop, chat-handler, recursive-supervisor, runtime-run, stream-backends, sanitized-telemetry-streaming, mcp-delegation, fleet-delegation, intelligence-recommend, intelligence-drop-in, agents-of-all-shapes, product-eval. The verdict's older snapshot flagged a few of these (mcp-delegation's delegate_ui_audit, the fleet-delegation casts) but they already carry the right framing/justification on current main; forcing fake-complete SandboxInstance helpers would add ceremony against the cleanup goal.

Verification

• pnpm run build — clean
• pnpm run typecheck (src + examples) — clean
• pnpm run lint — clean (333 files)
• pnpm run docs:check — green (0 errors; freshness OK)
• pnpm test — 115 files / 1120 passed, 2 skipped (the env-gated live e2es)
• ran each materially-changed example offline: knowledge-gating (hook fires), self-improving-loop, ui-audit, coding-benchmark (identical 0.944 leaderboard)

[tangletools]

✅ Auto-approved PR — efb6b428

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-24T15:09:11Z}