docs(router): warm the 9 explanation/"why" docs into the onboarding voice - #549

What

Warms the 9 strong "why"/explanation docs into the onboarding voice (AGENTS.md "Documentation voice"; exemplar: the matching doc from #547). Docs-only, [skip ci].

• Full warm rewrites: rendered-barrier, why-web-streams-everywhere, why-includes-is-sync, file-name-conflict-warnings, context-api, api-boundary-policy.
• Intro-warming only (dense/factual — body untouched on purpose): execution-model, manifests, use-cache-api-design.

Every fact, file ref, identifier, table, code block, and number is preserved — these are reference docs, so warmth goes in the prose around the facts, never instead of them.

How (and a lesson worth recording)

I first tried fanning this out to agents with an adversarial fidelity verifier. The verifier earned its keep: 7 of 9 agent rewrites invented content — fabricated rationale, a made-up "stays in lockstep" cross-reference in execution-model, a dropped "unrelated" qualifier in api-boundary-policy, and a three→four miscount of caching mechanisms in use-cache. The "lead with the why" instruction is the trap: when the source doesn't state a rationale, an agent confidently manufactures one.

So I reverted all 7 and hand-authored these, self-checking each against the original. No agent touched doc prose. (Recorded the lesson in AGENTS.md already.)

Accuracy fixes found along the way

• rendered-barrier: "non-streaming only" reframed to the concrete trigger — unavailable when the matched route tree uses loading() (which is exactly what the guard's error message says at loader-resolution.ts:316). The streaming follow-up is now tracked in feat(router): support ctx.rendered() on streaming (loading()) route trees #548 and linked from the doc.
• file-name-conflict-warnings: reconciled an internal inconsistency — the TL;DR said "two bugs" while the body enumerates three.
• context-api: ctx.var removal is correctly labeled decided, not "unsettled" (an error the agent draft made).

Test plan

• Docs + comments only; no code change. format clean; pre-commit hook green.
• [skip ci] per the docs convention.
• No remaining "honest" usages in the warmed docs.

Follow-ups (not in this PR)

• 11 light-touch docs (caching, mime-routes, named-routes, client-chunking, telemetry, tree-structure, etc.) — warm the intro/framing only. Pending go-ahead.
• 18 stale archive-candidates (completed action-plans, handoffs, superseded research) — pending a move-to-archive/ vs delete decision.