docs(skills): measured perf guidance — async include sizing, cache() economics, typecheck scaling, CF timing caveat - #668

Problem statement

The skills describe WHAT async include(), cache(), and debugPerformance do, but gave a consumer no numbers to size decisions with: how big should an include group be, when does cache() actually pay, why does typecheck crawl in a many-include app, and why Server-Timing reads ~0 on a deployed worker. All four now have measured answers from the 26k-route stress app's deployed-edge benchmark (#667, BENCHMARK-2026-07-04-edge-26k.md).

What a consumer reads differently

• /composability — new "Sizing async include groups (measured)": first-hit latency scales with routes-per-chunk (~75ms at 240 routes vs ~188ms at 9k on the edge; 3-level async chains ~464ms), giving three rules — prefer more smaller groups, keep async-in-async nesting shallow, give sibling groups distinct static prefixes — plus the reassurance that warm matching is O(segments) regardless, and the post-deploy warmup-ping escape hatch.
• /route — Nested Routes cross-ref: steers whole-module composition toward code-split include() with a pointer to the sizing rules.
• /caching — new "When cache() does not pay": measured hit (36ms p50) vs miss (35ms) for a trivial page on the real Cache API; the rule that cache() wins proportionally to the render cost it saves, and to prefer loader-data caching when the data is the expensive part.
• /typesafety — new "Typecheck cost when composing many include modules" (generated-files-and-cli.md + hub routing-table row): inference through dozens of include thunks measured at 4.05M instantiations / 20s vs 140k / 3.6s after annotating intermediate exports UrlPatterns<any>; notes that UrlPatterns<unknown> breaks handler assignability, that named-route typing is unaffected (it comes from the gen file), and to diagnose with tsc --extendedDiagnostics.
• /observability — deployed-CF caveat in the performance-timeline section: timers are frozen during request execution on production Workers, so Server-Timing durations read ~0 on the edge — the waterfall is a local diagnostic; production analysis uses client-observed timing and structured telemetry.

Code-change summary

Markdown only, 6 files, +97 lines. No frontmatter changes (skills catalog unaffected).

Test plan

• node tools/check-skills.mjs — 43 skills, frontmatter valid, cross-references resolve
• node tools/check-doc-links.mjs — all internal links resolve
• pnpm run format / lint — clean

Notes

The cited benchmark document lands in #667 — merge that first (or together) so the reference resolves in-repo; the numbers themselves are inlined here and stand alone.