docs: LLM-support sweep — skill triggers/boundaries/splits, consumer discovery, doc guards - #660

Problem

The 43 skills shipped to npm are the package's primary interface for LLM coding agents, but the doc surface had four consumer-observable problems: (1) the shipped AGENTS.md opened with a factually wrong positioning line ("a file-system based router") and linked ../../ paths that 404 inside node_modules; (2) 37 of 43 skill descriptions were bare topic labels, so an agent asking "why is my data stale?" never triggered /caching; (3) nothing told a consumer (or their agent) the skills exist — no index, no README section; (4) the internal maps documented a phantom public API (live(), removed in #645) that would send any PPR-working agent chasing a fictional export. None of this was mechanically guarded, so it could only rot further.

Before vs. after (consumer's seat)

# before — skills/caching/SKILL.md frontmatter
description: Configure segment caching with memory or Cloudflare KV stores in @rangojs/router

# after — same file
description: Configure route/segment-subtree caching with memory, Cloudflare KV, or Vercel cache stores in @rangojs/router. Use when responses should be cached or revalidated, data is stale or not updating after code changes, or you are wiring up a cache store

An agent matching a user's plain-language symptom now selects the right skill; on arrival, a new "Not this skill if…" section redirects wrong landings (e.g. /caching → /use-cache for single-function caching).

End-to-end consumer example

A consumer on Cursor/Codex CLI/Gemini CLI wiring the skills into their app:

npm i @rangojs/router
# these harnesses auto-discover skills from .agents/skills/
mkdir -p .agents/skills
ln -s ../../node_modules/@rangojs/router/skills/rango .agents/skills/rango
ln -s ../../node_modules/@rangojs/router/skills/caching .agents/skills/caching
# machine-readable index for tooling:
cat node_modules/@rangojs/router/skills/catalog.json | jq '.skills[] | .name'

The README's new "Using the skills with your coding agent" section documents this; the shipped AGENTS.md is now consumer-only with correct positioning and no dead links.

Code-change summary

Docs/tooling only — zero runtime source changes.

• Skills (ship to npm): all 43 frontmatter descriptions gain "Use when" triggers; 9 confusable skills gain "Not this skill if…" boundaries (+1 cross-link in server-actions); the three 900+-line skills (hooks, typesafety, migrate-react-router) split into ≤153-line indexes + companion files (word-preservation 103–109%, testing/ pattern); generated skills/catalog.json (43 entries).
• Shipped AGENTS.md: rewritten consumer-only (positioning fixed, contributor pre-push rules and dead relative links removed).
• Internal docs: phantom live() removed from feature-map.md (replaced with the render-defined-holes contract); docs hub now links the root caching designs, security/semantic-change checklists, and named-routes.md; internal/reviews/ bannered as point-in-time snapshots; shallow-navigation.md moved to design/ with a corrected status — the RFC is actually shipped as revalidate: false (src/browser/navigation-bridge.ts:124); all 23 semantic-matrix row ids now tagged in execution-model.md, including 6 newly authored guarantees for rows that had none (RC1/RC2/SWR1/I1/W1/P1, each derived from its test's assertions).
• Guards (new): tools/check-skills.mjs — frontmatter schema (name↔dir, non-empty description), cross-skill `/name` reference resolution (13-entry verified URL-example allowlist), relative-link resolution; tools/generate-skills-catalog.mjs --check — catalog byte-currency + bidirectional rango-table completeness; check-doc-links.mjs widened to ../../skills/ targets. All wired into package.json scripts, lefthook pre-commit, and the CI lint job (check-docs-api added to pre-commit too).

Location rationale: guards follow the existing tools/check-*.mjs convention (dependency-free ESM, OK-line/exit-1); catalog is committed (not build-time) so it is greppable and versioned, kept honest by --check.

Test plan

• pnpm check:skills / check:skills-catalog / check:doc-links / check:docs-api / check:e2e-bucketing — all green on the merged branch
• Guard violation classes proven red-before-green during development: name↔dir mismatch, dead `/ref`, dead relative link, stale catalog, missing rango-table row — each fails with path:line, reverts to green
• Typecheck (tsc --noEmit, router): clean
• Router unit suite: 4803 passed; RSC/Flight suite: 66 passed
• oxfmt --check . (1994 files) + oxlint --deny-warnings: clean
• CI unit-tests job covers the recursive consumer-app suites (no TS source changed; not run locally due to the local pnpm wrapper issue)

Notes

• The [skip ci] convention was deliberately NOT used: this PR adds the CI lint steps that verify its own guards, so CI must run.
• New docs contracts pinned: a future removed export can no longer survive in skills (check-skills) or the catalog (--check); mistitled/missing skill frontmatter fails pre-commit.
• Deferred, recorded in the repo advisor notes: extending identifier-level drift checking to all skills (needs allowlist tuning); 3 feature-map gaps found by measurement (createVar, keepClientCache, notFound); SWR1's doc bullet does not mention the row is prod-only.
• Skills changes reach consumers at the next experimental npm publish.