@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/skills/caching/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: caching
-description: Configure segment caching with memory or Cloudflare KV stores in @rangojs/router
-argument-hint: [setup]
+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.
+argument-hint: "[setup]"
 ---
 
 # Caching
@@ -14,6 +14,16 @@ argument-hint: [setup]
 > route-segment entries expire at TTL with no background revalidation — use
 > `CFCacheStore` for real segment SWR. See `/cache-guide`.
 
+## Not this skill if…
+
+- You want to cache ONE function or component's return value — that is
+  `"use cache"`: see `/use-cache`.
+- You want the whole HTTP response frozen at the edge, loader output included —
+  see `/document-cache`.
+- You want the HTML shell cached while loaders stay live per request — see
+  `/ppr`.
+- You are unsure which cache layer you need — start at `/cache-guide`.
+
 ## cache() is Partial Prerendering (PPR)
 
 `cache()` caches **everything except loaders**. On a cache hit, the cached
@@ -81,10 +91,116 @@ cache(
 );
 ```
 
-## Named Profile Shorthand
+## When cache() does not pay
+
+A cache hit is not free: it still runs middleware, the store read, and the
+document render AROUND the cached segment. The win is proportional to what
+the cached render itself costs — measured on a deployed Cloudflare worker
+(2026-07), a trivial page inside `cache()` served hits at p50 36 ms while
+misses (render + store) served at 35 ms: indistinguishable. The same
+boundary around an expensive render (slow data, big trees) is where the TTL
+pays for itself.
+
+Rule of thumb: reach for `cache()` when the segment's own render cost is
+meaningfully above your latency floor — expensive render-embedded data work,
+large component trees, third-party calls captured in the render. Do not wrap cheap
+pages "just in case": you add store traffic and invalidation surface for no
+latency win. If the data is what's expensive and it changes per-request,
+prefer a loader with `cache()` on the loader DATA (see "Loader-Level
+Caching") over caching the rendered segment.
 
-Use a named cache profile string instead of an options object. The profile must be
-defined in `createRouter({ cacheProfiles })`. Unknown names throw at boot time.
+## Tag-Based Invalidation
+
+Tag cached entries, then invalidate them on demand. Tags can be attached four ways:
+
+```typescript
+// 1. Static tags in the cache() DSL
+cache({ ttl: 300, tags: ["products"] }, () => [path("/products", List)]);
+
+// 2. Dynamic tags (function of ctx)
+cache(
+  { ttl: 300, tags: (ctx) => [`product:${ctx.params.id}`, "products"] },
+  () => [path("/products/:id", Detail)],
+);
+
+// 3. Runtime tags inside a "use cache" function
+async function getProduct(id: string) {
+  "use cache";
+  cacheTag(`product:${id}`, "products"); // variadic, additive
+  return db.getProduct(id);
+}
+
+// 4. Render-callable — a plain server component (no "use cache" in its tree)
+//    records onto the request's document/shell artifact.
+function CampaignBanner() {
+  cacheTag("campaign:spring"); // rides ctx._requestTags → shell/document entry
+  return <aside>Spring sale</aside>;
+}
+```
+
+Form 4 is how you make a PPR shell or a `/document-cache` page tag-invalidatable
+without wrapping anything in `"use cache"`: the tag rides the request's
+`_requestTags` onto the shell/document entry, and `revalidateTag` then evicts it.
+On a route that is neither PPR nor document-cached the tag records where nothing
+reads it — a silent no-op, so don't expect a bare `cacheTag()` to tag an ordinary
+uncached page.
+
+Invalidate with one of two server-only verbs (both variadic, imported from
+`@rangojs/router`):
+
+```typescript
+// Server Action — read-your-own-writes. Await it so the action's own re-render
+// (and the next navigation) sees fresh data.
+async function updateProduct(formData: FormData) {
+  "use server";
+  await db.updateProduct(formData);
+  await updateTag("products");
+}
+
+// Route handler / webhook — background, non-blocking (waitUntil). Hard-purge:
+// the next read re-renders fresh (NOT stale-while-revalidate).
+export async function POST() {
+  "use server";
+  revalidateTag("products");
+  return new Response("ok");
+}
+```
+
+| API                      | Timing                      | Use in                    | Semantics                                             |
+| ------------------------ | --------------------------- | ------------------------- | ----------------------------------------------------- |
+| `updateTag(...tags)`     | awaitable (`Promise<void>`) | server actions            | immediate; next read is fresh                         |
+| `revalidateTag(...tags)` | background (`void`)         | route handlers / webhooks | background (non-blocking); next read re-renders fresh |
+
+Both built-in stores support tags. For `CFCacheStore`, distributed (cross-colo)
+invalidation requires a `kv` namespace — the tag-invalidation markers live in
+that same namespace; there is **no** separate tag-invalidation store to wire.
+If no tag-capable store is configured, `updateTag`/`revalidateTag` warn and no-op.
+
+By default `CFCacheStore` reads the KV marker on every tagged cache read
+(strongest invalidation latency). To cut KV reads on hot tagged routes, set
+`tagCacheTtl` (seconds) to cache each marker in the per-colo edge cache for that
+window — the colo running `updateTag`/`revalidateTag` writes the fresh marker
+into its own edge cache immediately (read-your-own-writes), while other colos
+converge within `tagCacheTtl` (the **maximum extra cross-colo invalidation
+latency** when no purge is wired). Keep it small (e.g. 30–60), or wire a purge
+(below) and set it large. (Contrast `tagInvalidationTtl`, which must be _large_
+— it bounds how long the KV marker itself lives and must exceed your max entry
+TTL+SWR. Left unset there is no expiry: KV markers accumulate unbounded under
+high-cardinality tags, so set it above your largest entry TTL+SWR to bound them.)
+
+To make other colos prompt without a short `tagCacheTtl`, pass `onRevalidateTag`:
+each cached marker carries a namespaced Cloudflare `Cache-Tag`, and the hook is
+handed exactly those tags (batched, once per `updateTag`/`revalidateTag` call) to
+feed Cloudflare's purge-by-tag API — evicting the cached lookups everywhere.
+Purge-by-tag is available on all plans (since April 2025), subject to per-plan
+rate limits, so the batched single call matters. With a purge wired, `tagCacheTtl`
+becomes a pure read-cost reducer + fallback window.
+
+## Named Cache Profiles
+
+Define named profiles in `createRouter({ cacheProfiles })` so the same TTL/SWR
+values can be shared across the DSL and `"use cache"` functions without repetition.
+Unknown names throw at boot time.
 
 ```typescript
 // Define profiles in router
@@ -95,19 +211,25 @@ createRouter({
     long: { ttl: 3600, swr: 7200 },
   },
 });
+```
 
-// Use by name in urls
+In the DSL, pass the profile's options directly to `cache()`:
+
+```typescript
 export const urlpatterns = urls(({ path, cache }) => [
-  cache("long", () => [path("/blog", BlogIndex, { name: "blog" })]),
+  cache({ ttl: 3600, swr: 7200 }, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+  ]),
 
-  // Also works without children (orphan cache boundary)
-  cache("short"),
+  // Orphan cache boundary (covers subsequent siblings)
+  cache({ ttl: 60, swr: 120 }),
   path("/feed", FeedPage, { name: "feed" }),
 ]);
 ```
 
-These profile names are shared with the `"use cache: <name>"` directive. See
-`/use-cache` for function-level caching.
+The DSL `cache()` helper does NOT accept a string profile name — strings are only
+valid in the `"use cache: <name>"` directive inside server functions. See
+`/use-cache` for function-level caching with named profiles.
 
 ## Loader-Level Caching
 
@@ -156,9 +278,15 @@ import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 const store = new MemorySegmentCacheStore({
   defaults: { ttl: 60, swr: 300 },
+  maxEntries: 1000, // per-family FIFO cap (default 1000)
 });
 ```
 
+Each internal family (segments, responses, `"use cache"` items, PPR shells) is
+capped at `maxEntries`; on insert past the cap the oldest entry is evicted FIFO
+and its tag-index entries are cleaned up, so a long-lived process cannot grow
+without bound. TTL expiry stays lazy on top of the cap.
+
 ### Cloudflare Edge Cache Store
 
 For distributed caching on Cloudflare Workers using the Cache API:
@@ -212,6 +340,80 @@ const router = createRouter<AppBindings>({
 KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
 are only cached in L1.
 
+### Resilience & latency budgets
+
+Every cache read is **fail-safe**: a degraded tier never stalls or fails the
+request — it degrades to the next tier (L1 → L2 → render). Three optional latency
+budgets (milliseconds) bound each tier so a slow colo or KV namespace cannot pin
+a request behind it:
+
+| Option                | Default | Bounds                              |
+| --------------------- | ------- | ----------------------------------- |
+| `edgeLookupTimeoutMs` | `10`    | L1 `cache.match` (the lookup)       |
+| `edgeReadTimeoutMs`   | `20`    | L1 body read (CF streams it lazily) |
+| `kvReadTimeoutMs`     | `170`   | L2 / KV read                        |
+
+Set any to `0` (or a negative value) to disable that budget and always await the
+read. A non-finite value (e.g. `Number(env.UNSET)`) falls back to the default.
+The tag-invalidation marker reads inherit these same budgets and **fail open** on
+a KV timeout — the entry is served rather than wrongly treated as invalidated.
+
+```typescript
+new CFCacheStore({
+  ctx,
+  kv: env.CACHE_KV,
+  defaults: { ttl: 60, swr: 300 },
+  // Raise a budget only if your HEALTHY reads legitimately run slower (large
+  // Flight payloads, far-from-colo regions); measure the p99 first. These are
+  // degradation guard-rails, not tuning levers for "slow is normal here".
+  kvReadTimeoutMs: 250,
+});
+```
+
+Failure handling, by kind — none of these fail the request:
+
+| Failure                         | Behavior                                                                                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Transient read error (5xx/blip) | Degrade to the next tier; entry left intact                                                                                                       |
+| Read budget exceeded (timeout)  | Abandon the read, degrade to the next tier                                                                                                        |
+| Corrupt / unparseable L1 entry  | Reported corrupt; degrade to L2 (served if present). The L1 entry is evicted ONLY when L2 has no copy — so the evict can't race the L2→L1 promote |
+| Corrupt / unparseable KV entry  | Reported corrupt; evicted (self-heal) + render (no tier below it)                                                                                 |
+| Write failure                   | No-op (entry simply not cached); never throws                                                                                                     |
+
+Each is surfaced to the router's `onError` callback (phase `"cache"`, with
+`metadata.category` one of `cache-read`, `cache-corrupt`, `cache-write`,
+`cache-delete`, `cache-invalidate`, `stale-revalidation`) so you can observe
+cache health without affecting users.
+
+### Validating cache behavior with `debug`
+
+Pass `debug` to emit one structured event per L1 read — use it to confirm on a
+real deployment (via `wrangler tail`) that the store behaves as expected before
+relying on it. It is intended for validation, not steady-state production.
+
+```typescript
+new CFCacheStore({
+  ctx,
+  kv: env.CACHE_KV,
+  debug: true, // logs each CFCacheReadDebugEvent to the console
+  // ...or capture programmatically:
+  // debug: (event) => myTelemetry.record(event),
+});
+```
+
+Each event reports which tier answered and why (`outcome`: `l1-fresh`,
+`l1-stale-revalidate`, `l1-revalidating-guarded`, `match-timeout`, `match-error`,
+`body-timeout`, `body-error`, `non-200`, `tag-invalidated`, `l1-miss`, `kv-fresh`,
+`kv-stale`, `kv-stale-suppressed`, `kv-miss`, `kv-timeout`, `error`), the
+staleness / revalidating timestamps, and the measured per-tier durations:
+`matchMs` (the L1 `match`), `markerMs` (the tag-marker resolution tail for a
+tagged entry, between `matchMs` and `bodyReadMs`; absent or 0 for an untagged
+entry or a per-request memo hit), and `bodyReadMs` (the L1 body read). A
+persistently large `markerMs` signals a degraded KV namespace; on a healthy
+deployment KV keeps markers hot in its per-colo edge cache, so it stays a few
+milliseconds. `match-error` (a transient `cache.match` rejection that falls
+through to L2) is kept distinct from a plain `l1-miss`.
+
 ## Cache purity & tainted objects
 
 A `cache()` boundary caches everything except loaders, so anything read inside a
@@ -248,6 +450,12 @@ is **not** guarded. `ctx.use()` is a server-side escape hatch for non-rendered
 uses (set a ctx var, make a routing decision); never render its result inside a
 cached handler.
 
+This is the **consumption-lane rule**, and it holds identically for every
+shared artifact — `cache()`, `"use cache"`, and the PPR shell (`/ppr`):
+handler consumption = baked copy with identity reads permitted; client-side
+`useLoader` = live. Stated once in `/rango` → Invariants; pinned by
+semantic-matrix row PPR3 and the `e2e/cache.test.ts` "baked copy" case.
+
 ```typescript
 // WRONG — throws: cookies() read directly in a cached handler
 cache({ ttl: 60 }, () => [
@@ -325,6 +533,7 @@ cache({ store: checkoutCache }, () => [
 ```typescript
 import { urls } from "@rangojs/router";
 import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+import * as CartActions from "./actions/cart";
 
 // Custom store for checkout (short TTL)
 const checkoutCache = new MemorySegmentCacheStore({
@@ -353,7 +562,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader, revalidate }) =>
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
       loader(ProductLoader, () => [cache({ ttl: 120 })]),
       loader(CartLoader, () => [
-        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+        revalidate((ctx) => ctx.isAction(CartActions) || undefined),
       ]),
     ]),
   ]),

package/skills/catalog.json

@@ -0,0 +1,271 @@
+{
+  "$schema-note": "Generated by tools/generate-skills-catalog.mjs — do not edit by hand.",
+  "package": "@rangojs/router",
+  "entry": "rango",
+  "skills": [
+    {
+      "name": "api-client",
+      "description": "Build a typed client for consuming your own response-route JSON APIs (no codegen). Use when calling your own JSON endpoints from another service or script, or you want typed fetch calls without a codegen step.",
+      "argumentHint": "",
+      "path": "skills/api-client/SKILL.md"
+    },
+    {
+      "name": "breadcrumbs",
+      "description": "Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments. Use when building a breadcrumb trail for nested routes, or asking how to show the current navigation path in a layout.",
+      "argumentHint": "[setup]",
+      "path": "skills/breadcrumbs/SKILL.md"
+    },
+    {
+      "name": "bundle-analysis",
+      "description": "Audit a Rango app's production bundle for server-side code leaking into the client, dev/prod React duplication, oversized chunks, and inefficient client-reference grouping. Use when investigating bundle size growth, before a production deploy, or when the client/SSR/RSC output suddenly balloons.",
+      "argumentHint": "<app-dir>",
+      "path": "skills/bundle-analysis/SKILL.md"
+    },
+    {
+      "name": "cache-guide",
+      "description": "When to use cache() DSL vs \"use cache\" directive — key differences and decision guide. Use when unsure which caching mechanism fits a given problem, comparing route/segment caching, function-level caching, and document-level caching, or asking \"which cache API should I use\".",
+      "argumentHint": "",
+      "path": "skills/cache-guide/SKILL.md"
+    },
+    {
+      "name": "caching",
+      "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.",
+      "argumentHint": "[setup]",
+      "path": "skills/caching/SKILL.md"
+    },
+    {
+      "name": "comparison",
+      "description": "Compare Rango with Next.js App Router, TanStack Start, and Waku. Use when evaluating React frameworks, explaining why Rango, writing positioning or adoption guidance, answering migration questions, or checking claims about Rango's routing, loaders, caching, rendering, prefetching, safety, testing, observability, and production behavior.",
+      "argumentHint": "",
+      "path": "skills/comparison/SKILL.md"
+    },
+    {
+      "name": "composability",
+      "description": "Reusable composition patterns with globally importable route helpers in @rangojs/router. Use when sharing loaders, middleware, or handler logic across multiple route files, or avoiding copy-pasting the same route setup everywhere.",
+      "argumentHint": "pattern-name",
+      "path": "skills/composability/SKILL.md"
+    },
+    {
+      "name": "css",
+      "description": "Import and apply CSS in a Rango app. Render document/app stylesheets in the Document `<head>` with Vite's `?url` import plus a `precedence`-managed `<link rel=\"stylesheet\">` (React 19 resource model — deduped, ordered, loaded before paint). Use when wiring global/app CSS or a Document `<head>` stylesheet, or when deciding between `?url` + `<link>` and side-effect imports. Cross-app (host-router) navigation is a full document load, so each app's document CSS is always re-established by its own load.",
+      "argumentHint": "",
+      "path": "skills/css/SKILL.md"
+    },
+    {
+      "name": "debug-manifest",
+      "description": "Debug and inspect route manifest structure. Use when routes aren't matching as expected, you need to see the generated route tree, or a path resolves to the wrong handler.",
+      "argumentHint": "",
+      "path": "skills/debug-manifest/SKILL.md"
+    },
+    {
+      "name": "defer-hydration",
+      "description": "Keep the full body HTML in a PPR shell's first paint while moving a heavy subtree's hydration off the initial main-thread task — a gated Suspense boundary with the content as its own fallback, released on first idle. Use when a shell HIT paints fast but one long hydration task blocks the main thread, TTI/INP is poor despite instant paint, or a plain Suspense boundary left an empty hole in the frozen prelude.",
+      "argumentHint": "",
+      "path": "skills/defer-hydration/SKILL.md"
+    },
+    {
+      "name": "document-cache",
+      "description": "Cache the whole HTTP response at the edge with Cache-Control headers. Use when caching an entire page or response at a CDN edge, setting Cache-Control headers, or cutting origin hits for public pages — not for caching a single segment or function.",
+      "argumentHint": "[setup]",
+      "path": "skills/document-cache/SKILL.md"
+    },
+    {
+      "name": "fonts",
+      "description": "Load and configure web fonts with preload hints for optimal performance. Use when adding a custom font to a Rango app, fonts flash or swap on load (FOUT/FOIT), or you want font preload for performance.",
+      "argumentHint": "[provider]",
+      "path": "skills/fonts/SKILL.md"
+    },
+    {
+      "name": "handler-use",
+      "description": "Attach default loaders, middleware, parallels, and other use items directly to handlers via handler.use, and compose them with explicit use() at mount sites. Use when a handler needs its own default middleware/loader without repeating use() at every mount site, or deciding between handler-level defaults and per-route use().",
+      "argumentHint": "[handler]",
+      "path": "skills/handler-use/SKILL.md"
+    },
+    {
+      "name": "hooks",
+      "description": "Client-side React hooks for navigation, loaders, and state in @rangojs/router. Use when a client component needs the current URL, params, search params, navigation state, or loader data — e.g. \"how do I read the route param in a component\".",
+      "argumentHint": "[hook-name]",
+      "path": "skills/hooks/SKILL.md"
+    },
+    {
+      "name": "host-router",
+      "description": "Multi-app host routing with domain/subdomain patterns. Use when running multiple apps behind one domain or across subdomains, or routing requests to different apps based on hostname.",
+      "argumentHint": "",
+      "path": "skills/host-router/SKILL.md"
+    },
+    {
+      "name": "i18n",
+      "description": "Locale-aware routing with `include(\"/:locale?\", ...)`, locale resolution chains, and react-intl integration. Use when building a multi-language app, routes need a locale segment, or wiring up react-intl translations.",
+      "argumentHint": "[topic]",
+      "path": "skills/i18n/SKILL.md"
+    },
+    {
+      "name": "intercept",
+      "description": "Define intercept routes for modals, slide-overs, and soft navigation patterns in @rangojs/router. Use when opening a route as a modal/overlay on top of the current page while keeping the URL shareable, or asking \"how do I show this page in a modal\".",
+      "argumentHint": "[@slot-name] [route-to-intercept]",
+      "path": "skills/intercept/SKILL.md"
+    },
+    {
+      "name": "layout",
+      "description": "Define layout routes that wrap child routes in @rangojs/router. Use when sharing a persistent UI shell (nav, sidebar) across nested routes, or asking how to wrap child pages with a common layout.",
+      "argumentHint": "[component]",
+      "path": "skills/layout/SKILL.md"
+    },
+    {
+      "name": "links",
+      "description": "URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse. Use when generating a link to a route by name instead of hardcoding a path, or a link breaks after routes move or get mounted elsewhere.",
+      "argumentHint": "[ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]",
+      "path": "skills/links/SKILL.md"
+    },
+    {
+      "name": "loader",
+      "description": "Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, or client components need reactive server data.",
+      "argumentHint": "[loader]",
+      "path": "skills/loader/SKILL.md"
+    },
+    {
+      "name": "middleware",
+      "description": "Define middleware for authentication, logging, and request processing in @rangojs/router. Use when gating routes behind auth checks, logging requests, or running shared logic before a handler runs.",
+      "argumentHint": "[middleware-name]",
+      "path": "skills/middleware/SKILL.md"
+    },
+    {
+      "name": "migrate-nextjs",
+      "description": "Migrate a Next.js App Router project to @rangojs/router. Use when the user asks to \"migrate from Next.js\", \"convert Next.js to Rango\", \"replace Next.js\", or has a Next.js app they want to port.",
+      "argumentHint": "[path-to-nextjs-app]",
+      "path": "skills/migrate-nextjs/SKILL.md"
+    },
+    {
+      "name": "migrate-react-router",
+      "description": "Migrate a React Router v7/v6 project to @rangojs/router. Use when the user asks to \"migrate from React Router\", \"convert React Router to Rango\", \"replace React Router\", \"move from Remix to Rango\", or has a React Router / Remix app they want to port.",
+      "argumentHint": "path-to-react-router-app",
+      "path": "skills/migrate-react-router/SKILL.md"
+    },
+    {
+      "name": "mime-routes",
+      "description": "Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header. Use when the same URL needs to return JSON for API clients and HTML/RSC for browsers, or branching a handler on the Accept header.",
+      "argumentHint": "[negotiate|vary|accept]",
+      "path": "skills/mime-routes/SKILL.md"
+    },
+    {
+      "name": "observability",
+      "description": "Debug Rango request performance with debugPerformance, Server-Timing, structured telemetry, and tracing. Use when a request feels slow and you need to see where time is spent, or wiring up tracing/telemetry for production requests.",
+      "argumentHint": "",
+      "path": "skills/observability/SKILL.md"
+    },
+    {
+      "name": "parallel",
+      "description": "Define parallel routes for multi-column layouts, sidebars, and modal slots in @rangojs/router. Use when a layout needs multiple independently-loading regions (e.g. a sidebar and main panel), or rendering more than one route segment at the same URL.",
+      "argumentHint": "[@slot-name]",
+      "path": "skills/parallel/SKILL.md"
+    },
+    {
+      "name": "ppr",
+      "description": "PPR shell caching — opt a page route in with the `ppr` path option; the router serves the cached HTML shell instantly and resumes the live holes. Use when a page should render instantly from a cached shell while specific parts stay live, or asking about partial prerendering in Rango.",
+      "argumentHint": "[setup]",
+      "path": "skills/ppr/SKILL.md"
+    },
+    {
+      "name": "prerender",
+      "description": "Pre-render route segments at build time with Prerender and Passthrough live fallback. Use when a page's content is mostly static and shouldn't render on every request, speeding up cold responses, or deciding which routes to prerender vs render live.",
+      "argumentHint": "[passthrough]",
+      "path": "skills/prerender/SKILL.md"
+    },
+    {
+      "name": "rango",
+      "description": "Overview of @rangojs/router and available skills. Use when unsure which skill to reach for, starting a new task in a Rango app, or asking \"what can this router do\".",
+      "argumentHint": "",
+      "path": "skills/rango/SKILL.md"
+    },
+    {
+      "name": "react-compiler",
+      "description": "Enable the React Compiler in a Rango app the @vitejs/plugin-rsc way — a separate @rolldown/plugin-babel running reactCompilerPreset(), ordered after react() and before the plugin that supplies @vitejs/plugin-rsc. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, or is unsure why server components aren't being compiled.",
+      "argumentHint": "",
+      "path": "skills/react-compiler/SKILL.md"
+    },
+    {
+      "name": "response-routes",
+      "description": "Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses. Use when building a JSON/text API endpoint alongside your pages, or asking how to return raw JSON instead of RSC from a route.",
+      "argumentHint": "[json|text|html|xml|md|image|stream]",
+      "path": "skills/response-routes/SKILL.md"
+    },
+    {
+      "name": "route",
+      "description": "Define routes with path() in @rangojs/router. Use when creating a new page or route, or asking how to define a URL path and its handler.",
+      "argumentHint": "[pattern]",
+      "path": "skills/route/SKILL.md"
+    },
+    {
+      "name": "router-setup",
+      "description": "Create and configure the RSC router with createRouter. Use when bootstrapping a new Rango app, or configuring top-level router options like base path, cache store, or environment.",
+      "argumentHint": "[option]",
+      "path": "skills/router-setup/SKILL.md"
+    },
+    {
+      "name": "scripts",
+      "description": "Inject third-party scripts (GTM, analytics, widgets) into the document head/body via the Script handle. Use when adding Google Tag Manager, an analytics snippet, or a third-party widget script to the page.",
+      "argumentHint": "[vendor]",
+      "path": "skills/scripts/SKILL.md"
+    },
+    {
+      "name": "server-actions",
+      "description": "Define and call server actions (`\"use server\"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation. Use when handling a form submission on the server, calling a server function from a client component, or needing optimistic UI after a mutation.",
+      "argumentHint": "[action]",
+      "path": "skills/server-actions/SKILL.md"
+    },
+    {
+      "name": "shell-manifest",
+      "description": "Shell manifest pattern — replayed handles as cache metadata that live loaders read, e.g. a prerendered product list with batched live prices. Use when a cached/prerendered shell needs to feed IDs or metadata to a live loader for freshly-fetched data.",
+      "argumentHint": "",
+      "path": "skills/shell-manifest/SKILL.md"
+    },
+    {
+      "name": "streams-and-websockets",
+      "description": "Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats. Use when streaming live updates to the browser, or opening a WebSocket connection from a route on Cloudflare Workers.",
+      "argumentHint": "[sse | websocket | agents]",
+      "path": "skills/streams-and-websockets/SKILL.md"
+    },
+    {
+      "name": "tailwind",
+      "description": "Set up Tailwind CSS v4 with the Document component and CSS imports. Use when adding Tailwind CSS to a Rango app, or Tailwind classes aren't being applied or generated.",
+      "argumentHint": "[setup]",
+      "path": "skills/tailwind/SKILL.md"
+    },
+    {
+      "name": "testing",
+      "description": "Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader or middleware, or asking how to test a route end-to-end in dev and production.",
+      "argumentHint": "[layer]",
+      "path": "skills/testing/SKILL.md"
+    },
+    {
+      "name": "theme",
+      "description": "Opt-in theme system with FOUC prevention for light/dark mode. Use when adding a light/dark mode toggle, or the page flashes the wrong theme on load (FOUC).",
+      "argumentHint": "[setup]",
+      "path": "skills/theme/SKILL.md"
+    },
+    {
+      "name": "typesafety",
+      "description": "Set up type-safe routes, params, and environment types in @rangojs/router. Use when route or search params aren't typed, TypeScript can't infer a loader's return type, or wiring up typed environment bindings.",
+      "argumentHint": "[setup]",
+      "path": "skills/typesafety/SKILL.md"
+    },
+    {
+      "name": "use-cache",
+      "description": "Function-level caching with the \"use cache\" directive for RSC data functions and components in @rangojs/router. Use when a single function or component should memoize its own output, not a whole route/segment subtree or HTTP response.",
+      "argumentHint": "[profile-name]",
+      "path": "skills/use-cache/SKILL.md"
+    },
+    {
+      "name": "vercel",
+      "description": "Deploy a Rango app to Vercel Functions (Build Output API v3). Use when deploying a Rango app to Vercel, or asking how the router works with Vercel Functions and the Build Output API.",
+      "argumentHint": "",
+      "path": "skills/vercel/SKILL.md"
+    },
+    {
+      "name": "view-transitions",
+      "description": "Configure React View Transitions on layouts, routes, and parallel slots in @rangojs/router. Use when navigation should animate smoothly between pages, or wiring up React View Transitions on a route or layout.",
+      "argumentHint": "[layout|route|parallel|intercept]",
+      "path": "skills/view-transitions/SKILL.md"
+    }
+  ]
+}

package/skills/comparison/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: comparison
+description: Compare Rango with Next.js App Router, TanStack Start, and Waku. Use when evaluating React frameworks, explaining why Rango, writing positioning or adoption guidance, answering migration questions, or checking claims about Rango's routing, loaders, caching, rendering, prefetching, safety, testing, observability, and production behavior.
+---
+
+# Compare Rango with other React frameworks
+
+Use the canonical [framework comparison](references/framework-comparison.md) as
+the factual baseline. Read the sections relevant to the question; read the full
+reference when producing an overall evaluation or editing the comparison itself.
+
+## Comparison rules
+
+1. Compare capabilities and architecture separately from ecosystem size, hiring,
+   integrations, and organizational familiarity.
+2. Present Rango's range clearly: start with `path()` and a component, then add
+   named routes, `include()`, loaders, caching, `revalidate()`, slots, intercepts,
+   safety, and diagnostics in the same declared route graph.
+3. Do not confuse Rango's `revalidate()` with cache invalidation. Cache APIs decide
+   stored-value freshness; `revalidate()` decides client render selection.
+4. Describe loaders as live-by-default RSC data slots beneath cached or prerendered
+   UI, not as renamed Remix or TanStack route loaders.
+5. Include production correctness where relevant: Rango State, userland client-cache
+   invalidation, deployment-skew recovery, tainted request context, CSP nonce
+   propagation, default CSRF origin checks, prefetch guards, testing, and timing.
+6. State boundaries and tradeoffs. In particular, distinguish origin checking from
+   token-based CSRF protection, nonce plumbing from application-owned CSP policy,
+   and reload-based skew recovery from Vercel deployment pinning.
+7. Credit competing frameworks where they lead. Next.js leads in ecosystem and
+   hiring, TanStack in search-param ergonomics and client/data devtools, and Waku
+   in minimal surface area.
+
+## Currency and evidence
+
+- Treat Rango identifiers and behavior as source-verifiable. Check the current
+  package source or the relevant Rango skill when changing a precise claim.
+- Competitor details age quickly. Before publishing or materially revising a claim,
+  verify it against current official documentation and link that primary source.
+- Do not weaken a current, sourced claim merely because an older model remembers a
+  previous release. Check first: examples include TanStack Start's Rsbuild support,
+  Next.js `proxy.ts` and Cache Components, and Waku handler interceptors.
+- Avoid declaring a framework universally "better." State which model fits the
+  application's constraints and why.
+
+## Output shape
+
+Lead with the decision or differentiator. For a short answer, use the TL;DR and the
+relevant framework-specific paragraph from the reference. For a decision memo,
+cover the at-a-glance table, the simple-to-complex growth path, substantive runtime
+differences, and the section where competitors still lead.

package/skills/comparison/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Rango Comparison"
+  short_description: "Compare Rango with other React frameworks"
+  default_prompt: "Use $comparison to compare Rango with Next.js, TanStack Start, and Waku."