@rangojs/router 0.0.0-experimental.141 → 0.0.0-experimental.143

package/skills/ppr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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
+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.
 argument-hint: "[setup]"
 ---
 
@@ -17,6 +17,14 @@ Compare `/document-cache`, which freezes the WHOLE response including loader
 output. Shell caching is for pages that mix a stable shell with live data: the
 shell is shared per host+URL, the holes are per request.
 
+## Not this skill if…
+
+- You want the WHOLE response frozen, loader output included — see
+  `/document-cache`.
+- You want routes rendered at build time with `Static()`/`Prerender()` — the
+  `ppr` path option captures at runtime; see `/prerender`.
+- You are unsure which cache layer you need — start at `/cache-guide`.
+
 ## Setup: one path option, no middleware
 
 PPR is a DOCUMENT-level property declared on the page route via the `ppr` path
@@ -41,7 +49,7 @@ export const urlpatterns = urls(({ path, layout, loader, loading }) => [
       { name: "product", ppr: { ttl: 600, swr: 120 } },
       () => [
         loader(LivePriceLoader),
-        loading(<PriceSkeleton />), // the structural hole boundary
+        loading(<PriceSkeleton />), // structural hole: the loader subtree stays live
       ],
     ),
   ]),
@@ -57,6 +65,60 @@ const router = createRouter<AppBindings>({
 export default router;
 ```
 
+That is ONE of two hole mechanisms — the loader one. Do not conclude PPR
+requires a loader:
+
+### The same opt-in with NO loader and NO loading() — promise holes
+
+A route (or its layouts) whose live regions are pending promises under
+`<Suspense>` PPRs with no `loader()` and no `loading()` anywhere. Hand the
+un-awaited promise over as a prop; the consumer suspends under its OWN
+boundary; the boundary postpones at capture and becomes the hole:
+
+```typescript
+// Handler: kick off the fetch, do NOT await it.
+function ProductPage(ctx: HandlerContext) {
+  const reviews = fetchReviews(ctx.params.id); // Promise<Review[]> — pending
+  return (
+    <main>
+      <h1>Product {ctx.params.id}</h1> {/* shell — baked into the prelude */}
+      <ReviewsSection promise={reviews} /> {/* hole — resumes per request */}
+    </main>
+  );
+}
+```
+
+```tsx
+// ReviewsSection.tsx — the consumer owns its Suspense boundary.
+"use client";
+
+import { Suspense, use } from "react";
+
+function Inner({ promise }: { promise: Promise<Review[]> }) {
+  return <ReviewList reviews={use(promise)} />;
+}
+export function ReviewsSection({ promise }: { promise: Promise<Review[]> }) {
+  return (
+    <Suspense fallback={<ReviewsSkeleton />}>
+      <Inner promise={promise} />
+    </Suspense>
+  );
+}
+```
+
+```typescript
+path("/products/:id", ProductPage, { name: "product", ppr: true });
+// No use() list at all: no loader, no loading, still a shell + live hole.
+```
+
+At capture the pending fetch cannot win the task-quantized quiet window, so
+the boundary postpones — fallback in the frozen prelude, value resumed fresh
+on every HIT. This is the PHYSICS class from the hole doctrine below, and it
+is exactly how an existing Suspense-shaped tree (e.g. migrated from Next.js
+PPR) works with zero restructuring. The e2e proof is
+`e2e/test-app/src/components/ShellPhysicsValue.tsx` — a promise hole living in
+a LAYOUT with no loader registration at all.
+
 A route WITHOUT the `ppr` option is pure axis 1: no store read, no capture, no
 logs, zero cost. `ppr` is per page route — declaring it on a layout is not
 supported (subtree inheritance is a possible follow-up).
@@ -107,21 +169,100 @@ On a document GET to a ppr route the router runs:
 point is after the chain, an unauthorized request NEVER sees shell bytes — put
 auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
+## Verifying it works
+
+The header exists on DOCUMENT responses only. A bare `curl` (no `Accept`)
+content-negotiates a Flight payload (`text/x-component`) with NO
+`x-rango-shell` header at all — which reads as "PPR is off" but is only the
+wrong request shape:
+
+```
+curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/products/1 | grep -i x-rango-shell
+```
+
+- First document GET: `MISS`, plus a background capture.
+- Production (workerd/node): the SECOND request is a `HIT`.
+- Dev: expect a few extra MISSes — cold module transforms abort the capture
+  window (per-attempt breadcrumbs: start the server with
+  `INTERNAL_RANGO_DEBUG=1`). This self-heals; only a route that NEVER flips
+  has a real hole/eligibility problem (the once-per-key warning tells the two
+  apart).
+- A HIT is one ordinary document: the frozen prelude first (view-source shows
+  your baked shell, with hole fallbacks in place), then
+  `<div hidden id="S:0">…` segments as the holes resume, per request.
+- A ppr-declared route that CANNOT be honored (missing shell store family,
+  per-request nonce) serves plain axis 1 with NO header and warns once per
+  key — no header + a declared `ppr` means look for that warning.
+
 ## The hole doctrine (encode this in your head)
 
 Holes are **render-defined**, decided by the shape of the tree, on three rules:
 
 | Class          | What makes the hole                                                                                                                                                                | At capture                                                                             | At serve                           |
 | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------- |
-| **STRUCTURAL** | the ENTIRE segment subtree under a `loading()` registration                                                                                                                        | loaders masked; the LoaderBoundary postpones; the fallback bakes in as route structure | loaders run fresh; resume fills it |
+| **STRUCTURAL** | the ENTIRE segment subtree under a `loading()` registration — the loader LIVE lane                                                                                                 | loaders masked; the LoaderBoundary postpones; the fallback bakes in as route structure | loaders run fresh; resume fills it |
 | **PHYSICS**    | any promise NESTED in handed-over data still pending at capture, under the consumer's own `<Suspense>` — handler props, handle containers (`push({ x: promise })`), loader-carried | real I/O cannot win the task-quantized quiet window; the boundary postpones            | the promise settles and streams in |
-| **SHELL**      | awaited handler data, TOP-LEVEL `push(promise)` (awaited before SSR), resolved promises, replayed `cache()` segments                                                               | baked into the prelude                                                                 | served from the frozen prelude     |
+| **SHELL**      | awaited handler data, TOP-LEVEL `push(promise)` (awaited before SSR), resolved promises, replayed `cache()` segments, BAKE-lane loader containers                                  | baked into the prelude                                                                 | served from the frozen prelude     |
+
+ONE rule for promises, every lane — handlers, handles, AND loaders: **a promise
+nested inside your data is never baked; the container settles.** A loader
+without `loading()` is the BAKE lane (see below): its settled container is
+shell material, exactly like awaited handler data and top-level handle pushes.
+
+**`loading()` is NOT the gate for holes — it is the LANE SELECTOR for loader
+data.** A pending promise under any plain `<Suspense>` postpones and is a hole
+at whatever level it suspends — the PHYSICS row needs no `loading()` anywhere
+(the e2e fixture's physics and nested-handle holes sit in a layout with none).
+A route without a loader PPRs on pure promise/Suspense holes. For loaders,
+`loading()` picks the lane: present = the GUARANTEED live lane (masked at
+capture, fresh every serve, immune to fast resolution); absent = the bake lane
+(the container is shell material, nested promises stay live).
+
+The three promise positions, side by side:
+
+```typescript
+async function Handler(ctx: HandlerContext) {
+  const push = ctx.use(MyHandle);
+
+  push(fetchBadge());                    // TOP-LEVEL push: awaited pre-SSR → BAKED
+  push({ label: "x", stat: fetchStat() }); // NESTED in container → container baked,
+                                           //   stat streams → HOLE (consumer Suspends it)
+
+  const data = await fetchHeader(ctx);   // awaited by the handler → BAKED
+
+  return (
+    <section>
+      <Header data={data} />                       {/* shell */}
+      <StatsPanel promise={fetchStats(ctx)} />     {/* un-awaited prop + own
+                                                       <Suspense> + use() → HOLE */}
+    </section>
+  );
+}
+```
 
-The unified rule for promises: **a promise nested inside your data is never
-baked; the container settles.** The one asymmetry to remember versus loaders: a
-LOADER container is a hole via `loading()` (the whole loader value is live),
-while a HANDLE container is shell via root consumption (the handles generator
-is drained before SSR) — only the promises nested inside it stay live.
+### Choosing the hole mechanism
+
+| Your live region is…                            | Use                                                               | Why                                                                                              |
+| ----------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| loader data, must be fresh EVERY serve          | `loader()` + `loading()` (the live lane)                          | the guaranteed structural hole — masked at capture, fresh every serve, immune to fast resolution |
+| loader data, shell container + live parts       | bake-lane loader (no `loading()`): `{ static, dynamic: promise }` | container bakes (snapshot-pinned per shell); nested promises hole at the consumer's `<Suspense>` |
+| handler-fetched real I/O (db, fetch)            | un-awaited promise prop + consumer `<Suspense>` + `use()`         | no loader needed; real latency postpones by physics                                              |
+| per-segment metadata consumed elsewhere         | handle container with a NESTED promise + consumer `<Suspense>`    | container is shell, nested value streams — "nesting = liveness"                                  |
+| already-resolved / instant / synchronous values | `loader(() => Promise.resolve(x))` + `loading()`                  | a raw promise that settles inside the quiet window BAKES; only the live lane guarantees live     |
+| none of the above                               | nothing                                                           | it bakes — that is what the shell is for                                                         |
+
+The physics caveat in one line: promise holes are holes because the I/O is
+genuinely pending at capture. If the value can resolve near-instantly (memory
+read, warmed cache), it may bake into the shell — when liveness must be
+guaranteed rather than probable, use the live lane (`loading()`). The same
+physics governs bake-lane nested promises, with one shape guarantee: a nested
+promise that settles inside the window pins its VALUE, but the container key
+KEEPS its promise shape on HITs (the snapshot rehydrates a
+`Promise.resolve(pinned)`), so an unconditional `use(data.x)` consumer never
+breaks — it just reads the pinned value. Note the timing consequence: whether
+such a value is pinned or live can vary per capture (concurrent loader traffic
+extends the quiet window), so treat "fast-resolving promise on the bake lane"
+as PINNED for correctness purposes.
 
 ### Handles: "nesting = liveness"
 
@@ -139,13 +280,104 @@ Put it in a loader: `loader(() => Promise.resolve(x))` + `loading()`. Loaders
 are always the live lane — masked at capture, fresh on every serve — no matter
 how fast the value settles.
 
-### The structural negative: a loader route without loading()
+### The bake lane: loaders without loading() on THEIR entry
+
+A loader on an entry with no renderable `loading()` EXECUTES during capture
+(the capture gate holds open for its real latency, bounded by the 5s guard).
+Its settled container bakes into the prelude; every promise still nested in it
+postpones at the consumer's own `<Suspense>` — a hole. On every HIT the
+capture snapshot's loader family overlays the recorded container onto the
+fresh run, so the payload matches the frozen prelude byte-for-byte while the
+nested promises run fresh. The return shape is the declaration:
+
+```typescript
+export const StorefrontContextLoader = createLoader(async (ctx) => {
+  const config = await loadSiteConfig(ctx.params.locale); // bakes (pinned per shell)
+  return {
+    config, // shell material
+    basket: fetchBasket(ctx), // hole — consumer <Suspense>s it, fresh per request
+  };
+});
+```
 
-The loading-less branch awaits loader data at TREE-BUILD, above every Suspense
-boundary, so under capture's masked loaders the whole tree pins above `<body>`,
-the prelude comes back trivial, and the sanity gate refuses to store. Observable
-symptom: `x-rango-shell: MISS` forever plus a once-per-key worker warning. Add
-`loading()` to the loader route and keep shell material in a layout.
+The lane is decided PER TREE NODE, at the entry that REGISTERS the loaders —
+`loading()` on a CHILD route does not change a parent layout's lane, and
+`loading()` IS valid on layout and parallel entries, not just routes.
+
+Three hard edges (each e2e/unit-pinned):
+
+- **Identity refuses.** `cookies()`/`headers()` inside a bake-lane loader
+  throws during capture and the capture REFUSES (deterministic, once-per-key
+  warned) — identity can never bake into the shared shell. Give that loader's
+  entry `loading()` (the live lane is exempt) or move the identity-dependent
+  part into a nested promise. The guard's scope is EXACTLY those two calls:
+  per-user state read from a middleware-provided object (`ctx.get("session")`)
+  does NOT refuse — it bakes silently as the capturing user's data (see
+  Pitfalls: the session-object bake trap).
+- **A rejecting bake-lane loader refuses.** Error UI never bakes.
+- **Baked containers show CAPTURE-time data** for the shell's lifetime on
+  document GETs (client navigations stay fresh — axis 1). That IS the bake
+  lane's meaning; if a value must be fresh on every serve, it belongs on the
+  live lane (`loading()`) or in a nested promise.
+
+### The layout-with-loaders playbook (the storefront case)
+
+The most common real-app shape: an app-wide layout registers per-user loaders
+(session context, basket, wishlist) and the page under it declares `ppr`.
+Those loaders are on the BAKE lane (no `loading()` on the layout), so the page
+captures and HITs — the question is which parts of their data should bake vs
+stay live. Your levers, in order of preference:
+
+1. **Shape the return value.** Shared/config data returns as plain values
+   (bakes, pinned per shell); per-request data returns as NESTED promises
+   consumed under the widget's own `<Suspense>` (live holes). No `loading()`,
+   no restructuring. One wall: a bake-lane loader that reads
+   `cookies()`/`headers()` refuses the capture — identity belongs in a nested
+   promise or on the live lane.
+2. **Do NOT put `loading()` on the layout itself** — that flips the WHOLE
+   layout to the live lane and the LoaderBoundary fallback wraps the layout's
+   ENTIRE subtree: chrome (header, nav, footer) falls out of the shell into
+   the skeleton. Technically PPR, practically pointless.
+3. **Guaranteed-fresh widgets: a parallel slot with its OWN `loading()`.**
+   Parallel-owned loaders get their own per-slot boundary (`fresh.ts` tags
+   them with the slot's loading; `segment-system.tsx` builds a per-slot
+   LoaderBoundary), so the chrome bakes into the shell and each widget is an
+   independent, widget-sized hole:
+
+   ```typescript
+   layout(StoreChrome, () => [
+     // chrome renders NO loader data itself — it bakes into the shell
+     parallel({ "@basket": BasketBadge }, () => [
+       loader(BasketLoader),
+       loading(<BadgeSkeleton />), // hole the size of a badge, not a page
+     ]),
+     // Descriptor form when the slot handler needs ctx (annotate it —
+     // StaticHandlerDefinition in the union blocks inference there):
+     parallel({
+       "@wishlist": {
+         handler: (ctx: HandlerContext) => (
+           <WishlistBadge listUrl={ctx.reverse("wishlist")} />
+         ),
+         use: () => [loader(WishlistLoader), loading(<BadgeSkeleton />)],
+       },
+     }),
+     path("/", HomePage, { name: "home", ppr: true }),
+   ]),
+   ```
+
+   Slot-owned loaders are masked at capture and GUARANTEED fresh per serve —
+   use this where the bake lane's physics (a fast resolve bakes) or pinning
+   (capture-time data for the shell's lifetime) is not acceptable, at the cost
+   of a widget-sized fallback in the shell.
+
+4. **Shared layout data can also leave the loader lane entirely**: an
+   un-awaited handler promise under the consumer's `<Suspense>` (a physics
+   hole) or `cache()`/`"use cache"` to bake it with tag-invalidation.
+
+The identity rule, stated once: per-user data on a PPR page lives in a NESTED
+promise (a hole, fresh per request) or behind `loading()` (the live lane).
+Reading `cookies()`/`headers()` where the value would bake — handler shell
+material or a bake-lane container — refuses the capture by construction.
 
 ## Execution matrix
 
@@ -154,7 +386,7 @@ symptom: `x-rango-shell: MISS` forever plus a once-per-key worker warning. Add
 | Middleware chain | runs (full)            | **NOT re-run** — inherits the request's post-middleware context    | runs (full) — commit point is after it                      |
 | `router.match`   | runs                   | re-runs under a derived context                                    | runs (behind the flushed prelude)                           |
 | Handlers         | run                    | run on UNCACHED segments; `cache()`d segments replay (mixed-chain) | run (same mixed-chain rules as any render)                  |
-| Loaders          | run **fresh**          | **MASKED** (never execute) — the structural holes                  | run **fresh**                                               |
+| Loaders          | run **fresh**          | LIVE lane (`loading()`): MASKED; BAKE lane: execute + snapshot-pin | run **fresh** (bake containers overlaid from the snapshot)  |
 | Flight render    | full                   | full                                                               | full (hydration needs the whole payload — no Flight resume) |
 | HTML production  | full fizz              | `prerender` + abort → prelude + postponed                          | `resume` only the holes — O(paths to holes)                 |
 | Shell store      | schedules a bg capture | `putShell(key, …)`                                                 | `getShell(key)`; a stale/SWR hit also schedules a recapture |
@@ -166,10 +398,11 @@ post-middleware state (`ctx` variables included, which is what makes
 middleware-derived shell content photograph correctly). Guarding is
 serve-time: the commit point runs the full chain on EVERY serve.
 
-Because handlers on uncached segments EXECUTE during capture, the
-`cookies()`/`headers()` capture guard is load-bearing: those reads THROW during
-a capture render (`assertNotInsideShellCapture`), so identity can never leak
-into a shared shell through them. Loaders are exempt (always fresh).
+Because handlers on uncached segments EXECUTE during capture — and BAKE-lane
+loaders now do too — the `cookies()`/`headers()` capture guard is load-bearing:
+those reads THROW during a capture render (`assertNotInsideShellCapture`), so
+identity can never leak into a shared shell through them. Live-lane loaders
+(behind `loading()`) are exempt: masked at capture, they never run there.
 
 ## allReady: the SEO/bot story
 
@@ -188,15 +421,21 @@ middleware on every serve. A 401/redirect short-circuit returns before any
 shell byte.
 
 **(b) Identity can't leak via cookies/headers.** `cookies()` and `headers()`
-THROW during the background capture render. A shell that reads them is
-PPR-ineligible by construction.
+THROW during the background capture render — in handlers AND in bake-lane
+loaders (whose containers would bake). A shell that reads them is
+PPR-ineligible by construction; the live lane (`loading()`) stays exempt.
 
 **(c) Residual hazard — middleware-derived per-user state.** A `ctx` variable
 set by an upstream auth middleware and rendered by shell material is
 photographed into the SHARED shell (the capture inherits post-middleware
-state). That is scope fidelity working as designed — for shared values. If the
-value is per-user: shell-cache only public/shared pages, put per-user content
-in loaders, or key per variant at the CDN tier.
+state). That is scope fidelity working as designed — for shared values. The
+same hazard reaches BAKE-LANE LOADERS: a loader reading a middleware-provided
+session object (`ctx.get("session")`) never calls `cookies()` itself, so the
+guard cannot see it — whatever it returns as settled container data is
+photographed as the CAPTURING user's state. If the
+value is per-user: shell-cache only public/shared pages, keep per-user content
+in nested pending promises or live-lane (`loading()`) loaders — NOT in a
+bake-lane container — or key per variant at the CDN tier.
 
 ## What always stays on axis 1
 
@@ -206,6 +445,38 @@ and any store without the shell family. A stored shell is invalidated when
 `React.version` changes (postponed state is build-coupled), so deploys
 self-heal via recapture.
 
+The per-request CSP nonce guarantee covers BOTH ways a nonce arrives — the
+`createRouter({ nonce })` provider AND a direct `ctx.set(nonce, value)` token
+write in middleware (the `nonce` token from `@rangojs/router`). Either way the
+nonce ends up rendered into the document (`useNonce()` puts the provider nonce
+on every nonced script/style/meta; a token nonce is rendered by whatever app
+code reads `ctx.get(nonce)`), so a shell shared per host+URL cannot bake it
+without freezing one request's nonce for every visitor (the browser's CSP
+would then reject the frozen nonce for all but the capture request). The serve
+gate reads the token off the post-middleware request variables at the commit
+point (which runs after the whole middleware chain), so a middleware-set nonce
+blocks capture the same as a provider one. Because the route DECLARED `ppr`
+but cannot be honored, it logs a once-per-key worker warning (same
+declared-intent-cannot-be-honored doctrine as the missing-store warning) and
+serves pure axis 1 with no `x-rango-shell` header. An undeclared route stays
+silent.
+
+### The proper way to supply a nonce
+
+`createRouter({ nonce })` is the canonical path — supply the nonce THERE, not
+via a token write. The provider value is threaded into the router's own SSR
+machinery: `NonceContext`/`useNonce()`, automatic nonce attributes on
+`<Scripts />` and `<MetaTags />` output, and the inlined Flight payload
+scripts. It ALSO sets the `nonce` token, so `ctx.get(nonce)` works in
+middleware and handlers for the CSP response header. A direct
+`ctx.set(nonce, value)` write in middleware is app-managed only: the router
+resolves its SSR nonce BEFORE middleware runs, so a token-set value is
+readable via `ctx.get(nonce)` and gates PPR (this section), but the router
+will NOT apply it to its own scripts — `useNonce()` stays undefined and the
+Flight payload scripts carry no nonce, which a nonce-only `script-src` policy
+would then block. If you need a per-request nonce, use the provider; reserve
+the token for READING the value.
+
 ## Options: PartialPrerenderProps
 
 ```typescript
@@ -247,12 +518,38 @@ know (a tenant id, a deploy marker).
 
 ## Pitfalls
 
-- **Loader route without `loading()`**: eternal MISS plus a once-per-key
-  console warning (see "The structural negative").
+- **A bake-lane loader that reads `cookies()`/`headers()`**: the capture is
+  REFUSED (deterministic, once-per-key warned) — the route stays on axis 1.
+  Move identity into a nested promise or behind `loading()`.
+- **A bake-lane container that must be fresh per document GET**: it is
+  snapshot-pinned for the shell's lifetime by design. Use the live lane
+  (`loading()`) or a nested promise instead.
+- **A bake-lane loader slower than the capture guard (~5s)**: the capture
+  cannot hold for it — eternal MISS with the once-per-key warning.
 - **Per-user value in shell material**: baked into the shared shell —
   deterministically, not by race (handler promises deep-settle at the ring-3
   write on cached chains; awaited/resolved values bake everywhere). Put
-  per-user data in a loader.
+  per-user data in a nested pending promise or a live-lane (`loading()`)
+  loader — a BAKE-lane loader container bakes just like handler material.
+- **The session-object bake trap (the guard cannot save you here)**: the
+  capture guard sees `cookies()`/`headers()` calls ONLY. A bake-lane loader
+  reading a middleware-provided session object (`ctx.get("session")`) refuses
+  nothing — and its FAST-RESOLVE branch is the killer:
+
+  ```typescript
+  const CartLoader = createLoader(async (ctx) => {
+    const basketId = ctx.get("session")!.get("basketId");
+    if (!basketId) return { cart: Promise.resolve(null) }; // SETTLED → BAKES
+    return { cart: fetchBasket(basketId) }; // pending → hole
+  });
+  ```
+
+  If the capturing request is anonymous (it usually is), `cart: null` bakes
+  and is snapshot-pinned: every logged-in user gets the anonymous badge on
+  every HIT. The branch asymmetry makes it nondeterministic per capture. Any
+  loader whose data is per-user belongs on the live lane — for a header
+  widget, a parallel slot with its own `loading()` (playbook lever 3).
+
 - **Theme on a HIT is capture-then-corrected**: the resume tree replays the
   CAPTURE's `initialTheme` (resume requires it to match the frozen prelude);
   the visitor's cookie theme is applied pre-paint by the FOUC script and
@@ -264,15 +561,17 @@ cache"` value baked into the shell is PINNED at capture (the capture data
   snapshot) and replayed on every HIT, so the shell stays byte-identical to the
   frozen prelude even after that cache entry expires, gets recomputed, or is
   tag-invalidated. This is deliberate — parity beats freshness inside the shell.
-  If a shell region needs to be fresh, put it under a `loading()` hole (holes are
-  never pinned) or make the SHELL itself invalidatable by adding the tag to
-  `ppr.tags`. Ring-1/ring-3 tag invalidation does NOT drop the shell.
+  If a shell region needs to be fresh, put it under a hole — `loading()` for
+  loader data, or an un-awaited promise under the consumer's `<Suspense>`
+  (holes are never pinned) — or make the SHELL itself invalidatable by adding
+  the tag to `ppr.tags`. Ring-1/ring-3 tag invalidation does NOT drop the shell.
 - **Uncached nondeterminism in the shell is a hydration hazard**: a raw
   `Date.now()` / `Math.random()` / uncached `fetch` rendered directly in shell
   material (outside any cache ring) drifts between capture and hit and the
   snapshot CANNOT pin it — it was never a cache read. It will mismatch the frozen
   prelude and detonate hydration. Wrap it in `cache()`/`"use cache"` (then it is
-  pinned) or move it under a `loading()` hole.
+  pinned) or move it under a hole (`loading()`, or a pending-promise
+  `<Suspense>` region).
 - **Stacking with `/document-cache`**: pick one per route — the document cache
   would cache the composite.
 - **Dev + HMR**: works, but edits produce stale shells until TTL/recapture.

package/skills/prerender/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prerender
-description: Pre-render route segments at build time with Prerender and Passthrough live fallback
+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.
 argument-hint: [passthrough]
 ---
 
@@ -11,6 +11,13 @@ deserialization path, same segment system. The worker handles every request --
 there are NO static .html or .rsc files served from assets. The worker reads
 pre-computed Flight payloads instead of executing handler code.
 
+## Not this skill if…
+
+- You want a cached HTML shell captured at runtime, with holes and loaders
+  staying live per request — see `/ppr`.
+- You want runtime segment caching with TTL/SWR — that is the `cache()` DSL:
+  see `/caching`. Prerender is the same cache filled at build time.
+
 ## API: Prerender
 
 ### Static Route (no params)

package/skills/rango/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rango
-description: Overview of @rangojs/router and available skills
+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".
 argument-hint:
 ---
 
@@ -249,17 +249,17 @@ Grouped by concern — read when you need to…
 
 **Data & caching** — fetch, mutate, and cache:
 
-| Skill             | Description                                                                                  |
-| ----------------- | -------------------------------------------------------------------------------------------- |
-| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                                        |
-| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation                      |
-| `/caching`        | Segment caching with memory or KV stores                                                     |
-| `/use-cache`      | Function-level caching with `"use cache"` directive                                          |
-| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide                      |
-| `/document-cache` | Edge caching with Cache-Control headers                                                      |
-| `/ppr`            | PPR shell caching: cached HTML shell served instantly, live loader holes resumed per request |
-| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)                          |
-| `/shell-manifest` | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)   |
+| Skill             | Description                                                                                                                                                       |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                                                                                                             |
+| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                           |
+| `/caching`        | Segment caching with memory or KV stores                                                                                                                          |
+| `/use-cache`      | Function-level caching with `"use cache"` directive                                                                                                               |
+| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                           |
+| `/document-cache` | Edge caching with Cache-Control headers                                                                                                                           |
+| `/ppr`            | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a `loading()` subtree OR a pending promise under `<Suspense>` (no loader needed) |
+| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)                                                                                               |
+| `/shell-manifest` | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                        |
 
 **Client & presentation** — build the client-side UX:
 

package/skills/response-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: response-routes
-description: Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses
+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.
 argument-hint: [json|text|html|xml|md|image|stream]
 ---
 

package/skills/route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: route
-description: Define routes with path() in @rangojs/router
+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.
 argument-hint: [pattern]
 ---
 
@@ -479,6 +479,14 @@ urls(({ path, layout }) => [
 ])
 ```
 
+For composing whole route MODULES, reach for `include()` — and prefer the
+code-split form `include("/shop", () => import("./shop-patterns"))` for any
+group that is a natural unit: it keeps the group off the cold-start path, and
+measured first-hit cost scales with routes-per-chunk, so many small groups
+beat one giant one. Sizing rules and the numbers behind them:
+[skills/composability](../composability/SKILL.md) → "Sizing async include
+groups (measured)".
+
 ## View Transitions
 
 A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.

package/skills/router-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: router-setup
-description: Create and configure the RSC router with createRouter
+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.
 argument-hint: [option]
 ---
 

package/skills/scripts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scripts
-description: Inject third-party scripts (GTM, analytics, widgets) into the document head/body via the Script handle
+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.
 argument-hint: "[vendor]"
 ---
 

package/skills/server-actions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-actions
-description: Define and call server actions (`"use server"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation
+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.
 argument-hint: "[action]"
 ---
 
@@ -24,7 +24,8 @@ with no framework wrapper. All standard React hooks (`useActionState`,
 Use loaders and route handlers for reads. Use actions for writes. After an
 action runs, the matched route tree can partially re-render so handlers and
 loaders that opt into revalidation see the new state — see "Revalidation"
-below.
+below. For the read-side APIs (`createLoader`, `useLoader`, `useFetchLoader`),
+see `/loader`.
 
 ## Revalidation Model
 

package/skills/shell-manifest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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
+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.
 argument-hint:
 ---
 

package/skills/streams-and-websockets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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.
 argument-hint: "[sse | websocket | agents]"
 ---
 

package/skills/tailwind/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tailwind
-description: Set up Tailwind CSS v4 with the Document component and CSS imports
+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.
 argument-hint: [setup]
 ---
 

package/skills/testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing
-description: Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement)
+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.
 argument-hint: [layer]
 ---