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

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)
@@ -119,6 +126,8 @@ interface BuildContext<TParams> {
   use: <T>(handle: Handle<T>) => (data: T) => void; // Push handle data
   url: URL; // Synthetic URL from pattern + params
   pathname: string; // Pathname from synthetic URL
+  searchParams: URLSearchParams; // URLSearchParams from the synthetic URL (always empty for prerender)
+  search: {}; // Typed search params -- always {} for prerender (no real query string)
   set(key: string, value: any): void; // Set context variable (string key)
   set<T>(contextVar: ContextVar<T>, value: T): void; // Set typed context variable
   get(key: string): any; // Read context variable (string key)
@@ -241,16 +250,16 @@ path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
 
 ## Interaction with DSL Items
 
-| DSL item       | Behavior with Prerender                                                                                                                                                                                                                                             |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                       |
-| `revalidate()` | Not allowed without Passthrough. Allowed with Passthrough.                                                                                                                                                                                                          |
-| `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                    |
-| `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                |
-| `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                        |
-| `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                           |
-| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                              |
-| `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when()` conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
+| DSL item       | Behavior with Prerender                                                                                                                                                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                            |
+| `revalidate()` | Not allowed without Passthrough. Allowed with Passthrough.                                                                                                                                                                                                               |
+| `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                         |
+| `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                     |
+| `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                             |
+| `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                                |
+| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                                   |
+| `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when` config conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
 
 When Passthrough revalidation is enabled, remember that revalidation is
 still partial: opting a child segment into revalidation does not
@@ -343,14 +352,31 @@ export const TocSidebar = Static(() => {
 
 ### Error behavior at build time
 
-| Handler outcome             | Effect                                                |
-| --------------------------- | ----------------------------------------------------- |
-| JSX / `null`                | Normal prerender entry, log OK                        |
-| `return ctx.passthrough()`  | Skip entry, log PASS, continue (Passthrough routes)   |
-| `throw new Skip("reason")`  | Skip entry, log SKIP, continue with remaining entries |
-| `throw new Error("reason")` | Log FAIL, stop ALL pre-rendering, fail the build      |
+When a render throws a non-`Skip` error, it is **surfaced to the build** — never
+baked into a frozen error page served as a 200 (issue #587). What happens next is
+controlled by `prerender.onError` in your `rango()` options:
+
+```ts
+rango({ prerender: { onError: "warn" } }); // default is "fail"
+```
 
-Both error types propagate to the router's `onError` callback with phase
+| Handler outcome             | `onError: "fail"` (default)                  | `onError: "warn"`                |
+| --------------------------- | -------------------------------------------- | -------------------------------- |
+| JSX / `null`                | Normal prerender entry, log OK               | Normal prerender entry, log OK   |
+| `return ctx.passthrough()`  | Skip entry, log PASS (Passthrough routes)    | Skip entry, log PASS             |
+| `throw new Skip("reason")`  | Skip entry, log SKIP, continue               | Skip entry, log SKIP, continue   |
+| `throw new Error("reason")` | Log FAIL, stop ALL pre-rendering, fail build | Log WARN, skip the URL, continue |
+
+With `"warn"` the errored entry is logged and left un-baked (never served as a baked
+200 error page). `"warn"` is a build-unblock, not a runtime contract: the route falls
+through to normal resolution — it may render live (its handler is still bundled) or
+404 (once other baked entries trigger prerender handler eviction), so the outcome
+depends on the rest of the build, and a skipped `Static()` handler's evicted code can
+surface as an error. For DEFINED runtime behavior reach for `Passthrough()` (a live
+fallback) or `throw new Skip()` (an intentional skip — works in the render fn, not
+only `getParams()`); otherwise prefer the default `"fail"`.
+
+Both `Skip` and hard errors propagate to the router's `onError` callback with phase
 `"prerender"` or `"static"`.
 
 ### Build logs
@@ -370,9 +396,11 @@ The build produces per-URL timing logs:
 [rango] Static render complete: 2 done, 1 skipped (120ms total)
 ```
 
-A `FAIL` line is logged per-URL when a handler throws a non-Skip error. The
-error is re-thrown immediately, so no summary line is printed — the build
-stops at the first failure.
+A `FAIL` line is logged per-URL when a handler throws a non-Skip error (with the
+default `prerender.onError: "fail"`). The error is re-thrown immediately, so no
+summary line is printed — the build stops at the first failure. Under
+`prerender.onError: "warn"` the same case logs a `WARN` line, skips that URL, and
+the build continues.
 
 ### Dev mode behavior
 
@@ -588,12 +616,12 @@ At runtime, the cache-lookup middleware checks `ctx.isIntercept`:
   (filtered by `namespace?.startsWith("intercept:")`) and sets up slots.
 - **Direct navigation**: looks up `paramHash` (no suffix). Standard prerender path.
 - **Intercept miss (no `/i` entry)**: falls through to the normal pipeline so
-  intercept-resolution middleware runs live. This handles `when()` conditions
+  intercept-resolution middleware runs live. This handles `when` config conditions
   that prevented pre-rendering.
 
-The `when()` callback receives an `InterceptSelectorContext` with `from.pathname`
+The `when` config selector receives an `InterceptSelectorContext` with `from.pathname`
 which is unknown at build time. All intercepts are pre-rendered unconditionally;
-`when()` is evaluated at runtime by the intercept-resolution middleware.
+`when` is evaluated at runtime by the intercept-resolution middleware.
 
 ### Example: Pre-rendered route with intercept
 
@@ -612,10 +640,13 @@ layout(ShopLayout, () => [
 
   // Intercept detail from shop index into a modal.
   // At build time, this is resolved and stored under the /i key.
-  intercept("@modal", ".detail", <ProductModal />, () => [
-    when(({ from }) => from.pathname === "/shop"),
-    loader(ProductLoader),
-  ]),
+  intercept(
+    "@modal",
+    ".detail",
+    <ProductModal />,
+    { when: ({ from }) => from.pathname === "/shop" },
+    () => [loader(ProductLoader)],
+  ),
 ])
 ```
 

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:
 ---
 
@@ -28,10 +28,10 @@ with the shape, then pick a primitive.
   cache hit streams UI instantly while loaders resolve fresh alongside). Opt into
   caching explicitly. See `/loader` → "Parallel and streaming".
 - **One identity, one store** — loaders, handles, cached fns, and actions are all
-  `path#export`; all caches share one store. Entries expire by TTL/SWR; cache
-  entries accept an optional `tags` field, but built-in stores do not yet index
-  or invalidate by tag, so tag-based invalidation (`revalidateTag`) is a
-  forward-looking API requiring a custom store.
+  `path#export`; all caches share one store. Entries expire by TTL/SWR, and are
+  tagged via `cache({ tags })` or runtime `cacheTag(...tags)`; built-in stores
+  index by tag and invalidate via `updateTag(...tags)` (awaitable, read-your-own-writes)
+  or `revalidateTag(...tags)` (background, non-blocking).
 - **Type-safe end to end** — route names, params, search schemas, loader return
   types, context vars, and `href` / `reverse` are checked at compile time
   (`/typesafety`).
@@ -59,36 +59,81 @@ appears, not up front.
 To decide where something can live: **does it define a URL? structure, stays in
 `urls()`. Does it modify a node? config, compose freely.**
 
+## Passing data down the tree
+
+Four ways to get per-request data to a segment below you, ordered safest-first.
+Reach for the next rung only when the one above doesn't fit — the higher rungs
+are immune to partial-revalidation staleness by construction.
+
+1. **A loader** (`loader()` + `useLoader()`). Loaders resolve fresh on every
+   pass — full renders, action revalidations, cache hits. Nothing to keep in
+   sync. If the data can be a loader, make it a loader.
+2. **Middleware `ctx.set()`**. Route middleware wraps every render pass,
+   including post-action revalidation and PE re-renders, so its variables are
+   never stale. Right for request-shaped context: auth, session, locale.
+3. **Handler `ctx.set()` to its own children** —
+   `path(handler, ..., () => [layout(...)])`. Orphan layouts and their
+   parallels belong to the route entry: on an action the whole entry re-runs
+   together by default (handler-first preserved), so the data stays consistent
+   with zero configuration. Right for data the page must compute anyway —
+   e.g. pagination, where the handler's search decides how many pages the
+   layout chrome renders. One rule: if you narrow the entry's revalidation
+   with a predicate that can return a hard `false`, put the same contract on
+   the entry's children too — a hard `false` on one side of a
+   producer/consumer pair desyncs it.
+4. **Cross-entry sharing** — an outer `layout()` entry feeding descendants.
+   Outer entries do NOT revalidate on actions by default (the revalidation
+   trace calls this `action:parent-chain-skip`), so this rung always requires
+   a shared revalidation contract: the same named `revalidate()` function on
+   the producer and every consumer. See `/layout` → "Revalidation Contracts".
+   Before writing one, check whether the producer can move down a rung.
+
+The failure mode this ladder prevents: a consumer re-runs, its producer
+doesn't, `ctx.get()` reads `undefined`, and fallback UI silently replaces good
+UI after an action. Rungs 1–3 make that unrepresentable; rung 4 makes it a
+stated, greppable contract.
+
 ## Pick a primitive
 
-| I need to…                            | Use                              | Skill                   |
-| ------------------------------------- | -------------------------------- | ----------------------- |
-| render data fresh every request       | `loader()` + `useLoader()`       | /loader                 |
-| cache a rendered subtree              | `cache()` on a segment           | /caching                |
-| cache one function/component's result | `"use cache"`                    | /use-cache              |
-| cache a loader's data                 | `loader(L, () => [cache()])`     | /loader, /caching       |
-| re-render a segment after an action   | `revalidate()`                   | /loader                 |
-| mutate                                | `"use server"` action            | /server-actions         |
-| debug a slow request                  | `debugPerformance` / telemetry   | /observability          |
-| share config across routes            | factory returning a helper array | /composability          |
-| compose a sub-app / module            | `include()`                      | /route                  |
-| modal / soft navigation               | `intercept()`                    | /intercept              |
-| pre-render a route at build time      | `Prerender(...)` wrapper         | /prerender              |
-| stream SSE / upgrade a WebSocket      | `path.stream()` / `path.any()`   | /streams-and-websockets |
+| I need to…                              | Use                                | Skill                   |
+| --------------------------------------- | ---------------------------------- | ----------------------- |
+| render data fresh every request         | `loader()` + `useLoader()`         | /loader                 |
+| cache a rendered subtree                | `cache()` on a segment             | /caching                |
+| cache one function/component's result   | `"use cache"`                      | /use-cache              |
+| cache a loader's data                   | `loader(L, () => [cache()])`       | /loader, /caching       |
+| re-render a segment after an action     | `revalidate()`                     | /loader                 |
+| mutate                                  | `"use server"` action              | /server-actions         |
+| debug a slow request                    | `debugPerformance` / telemetry     | /observability          |
+| share config across routes              | factory returning a helper array   | /composability          |
+| compose a sub-app / module              | `include()`                        | /route                  |
+| modal / soft navigation                 | `intercept()`                      | /intercept              |
+| pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
+| feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
+| cache the HTML shell, keep loaders live | `ppr` path option                  | /ppr                    |
+| stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`     | /streams-and-websockets |
 
 ## Invariants
 
 - `path()`/`include()` are always visible in `urls()`; config helpers are extractable.
 - **Cache decides freshness; `revalidate()` decides client-update.** Orthogonal; compose.
 - Loaders resolve fresh every request (even inside `cache()`) and never run twice/request.
+- **The consumption-lane rule.** For every shared artifact (`cache()`,
+  `"use cache"`, the PPR shell): server-side handler consumption
+  (`await ctx.use(loader)`) yields a BAKED copy — identity reads
+  (`cookies()`/`headers()`) are permitted there and the capture-time value
+  freezes into the shared artifact (a documented footgun; see `/caching` →
+  "Cache purity & tainted objects"). Client-side consumption (`useLoader` in
+  a `"use client"` component) is the LIVE lane. DSL `loader()` segments
+  follow their lane machinery (live under renderable `loading()`, bake
+  otherwise). Pinned by semantic-matrix row PPR3.
 - Inside `"use cache"`: `cookies()`/`headers()` and `ctx` side-effects
   (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`
   is captured on miss and replayed on hit. (The non-cacheable read guard is a
   separate `cache()`-boundary check — see the correctness bullet below.)
-- One identity `path#export` (`functionId`/`$$id`/`actionId`); one store. The
-  cross-cutting freshness mechanism today is TTL/SWR expiry; cache entries accept
-  an optional `tags` field, but built-in stores do not yet index or invalidate by
-  tag, so `revalidateTag` is forward-looking (requires a custom store).
+- One identity `path#export` (`functionId`/`$$id`/`actionId`); one store. Freshness
+  is TTL/SWR expiry plus tag-based invalidation: tag via `cache({ tags })` /
+  `cacheTag(...tags)`, then `updateTag(...tags)` (awaitable) or `revalidateTag(...tags)`
+  (background). Built-in stores index by tag.
 - `useLoader` / `useHandle` / `useFetchLoader` are client-only.
 - Caches are correctness-first: persistent store keys are version-segmented (no
   cross-deploy drift), the forward/back cache is mutation-aware, and
@@ -111,13 +156,14 @@ To decide where something can live: **does it define a URL? structure, stays in
 Same words, different jobs — this is the most common source of the
 `revalidate()`-is-caching misread.
 
-| You may know                               | Maps to Rango axis | Watch out                                                                                                                                                                                                                       |
-| ------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Next.js `export const revalidate = N`      | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                  |
-| Next.js `revalidatePath` / `revalidateTag` | **Axis 1** (cache) | Cache busting. No shipped equivalent: entries accept `tags`, but built-in stores don't yet index/invalidate by tag, so `revalidateTag` is forward-looking (custom store); today entries expire by TTL/SWR. No `revalidatePath`. |
-| React Router / Remix `shouldRevalidate`    | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                    |
-| HTTP `Cache-Control` / ISR                 | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                   |
-| Remix/RR `loader`                          | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                        |
+| You may know                            | Maps to Rango axis | Watch out                                                                                                                                                                                                                                                                               |
+| --------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js `export const revalidate = N`   | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                                                                          |
+| Next.js `revalidateTag` / `updateTag`   | **Axis 1** (cache) | Cache busting by tag. Tag via `cache({ tags })` / `cacheTag(...tags)`; invalidate with `updateTag(...tags)` (awaitable, read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking). Built-in stores index by tag. No `revalidatePath` (path-based busting); use tags. |
+| React Router / Remix `shouldRevalidate` | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                                                                            |
+| HTTP `Cache-Control` / ISR              | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                                                                           |
+| Next.js PPR (partial prerendering)      | HTML shell layer   | Same idea, different wiring: the opt-in `ppr` path option captures at runtime (no build-time default); holes are render-defined — `loading()` subtrees plus pending promises under a consumer's own `<Suspense>`. See `/ppr`.                                                           |
+| Remix/RR `loader`                       | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                                                                                |
 
 See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
 `revalidate()` (axis 2), and `/document-cache` for the edge layer.
@@ -154,6 +200,12 @@ returned, for outcome-conditional revalidation. The arg also exposes `actionId`
 (raw `path#export`), `actionUrl`, `formData`, `method`, and `stale` (cross-tab
 `_rsc_stale` signal). All are `undefined` on plain navigation (no action).
 
+Two idioms, picked by what an _unrelated_ action should do. `ctx.isAction()`
+returns a raw boolean, so combine it with `|| undefined` to **defer** ("mine,
+else let the default decide": `ctx.isAction(CartActions) || undefined`) or leave
+it bare to **suppress** ("mine only": `ctx.isAction(CartActions)`). Prefer the
+defer form unless a sibling segment must own the unrelated-action decision.
+
 ```ts
 // re-render only when checkout actually succeeded; defer otherwise
 revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
@@ -179,6 +231,12 @@ resolve `dist/` outside `./vite`, and it may lag `src/`.
 
 Grouped by concern — read when you need to…
 
+**Positioning & evaluation**:
+
+| Skill         | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `/comparison` | Compare Rango with Next.js, TanStack Start, and Waku fairly. |
+
 **Structure & routing** — shape URLs, layouts, navigation, and request processing:
 
 | Skill                     | Description                                                                |
@@ -192,6 +250,7 @@ Grouped by concern — read when you need to…
 | `/host-router`            | Multi-app host routing with domain/subdomain patterns                      |
 | `/links`                  | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
 | `/response-routes`        | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
+| `/api-client`             | Typed client for consuming your own response-route JSON APIs (recipe)      |
 | `/mime-routes`            | Content negotiation — same URL, different response types via Accept header |
 | `/streams-and-websockets` | SSE via `path.stream` and WebSocket upgrades via `path.any`                |
 | `/handler-use`            | Attach default loaders/middleware to a handler via `handler.use`           |
@@ -199,28 +258,33 @@ 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                                 |
-| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)     |
+| 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:
 
-| Skill               | Description                                                               |
-| ------------------- | ------------------------------------------------------------------------- |
-| `/hooks`            | Client-side React hooks                                                   |
-| `/theme`            | Light/dark mode with FOUC prevention                                      |
-| `/i18n`             | Locale routing with `:locale?`, resolution chains, react-intl integration |
-| `/fonts`            | Load web fonts with preload hints                                         |
-| `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                |
-| `/view-transitions` | React View Transitions on layouts, routes, and parallel slots             |
-| `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                     |
-| `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope        |
+| Skill               | Description                                                                                                                        |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `/hooks`            | Client-side React hooks                                                                                                            |
+| `/theme`            | Light/dark mode with FOUC prevention                                                                                               |
+| `/i18n`             | Locale routing with `:locale?`, resolution chains, react-intl integration                                                          |
+| `/fonts`            | Load web fonts with preload hints                                                                                                  |
+| `/css`              | Import CSS in the Document `<head>` (`?url` + managed `precedence` links)                                                          |
+| `/scripts`          | Inject third-party scripts (GTM/analytics) into head/body via the `Script` handle; nonce auto-applied to document-rendered scripts |
+| `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                                                                         |
+| `/view-transitions` | React View Transitions on layouts, routes, and parallel slots                                                                      |
+| `/defer-hydration`  | Full body HTML in the PPR shell + hydration off the critical path (gated Suspense boundary, content-as-fallback)                   |
+| `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                                                                              |
+| `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope                                                                 |
 
 **Observability & production health**:
 
@@ -230,6 +294,12 @@ Grouped by concern — read when you need to…
 | `/bundle-analysis` | Audit your app's production bundle for server leaks and oversized chunks |
 | `/debug-manifest`  | Inspect route manifest structure                                         |
 
+**Deployment**:
+
+| Skill     | Description                                                                               |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `/vercel` | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing` |
+
 **Testing**:
 
 | Skill      | Description                                                                                                                     |
@@ -310,7 +380,11 @@ dotfiles, and existing `.gen.` files.
 ### Recursive includes
 
 The generator follows `include()` calls across files, resolving imports to build
-the full route tree. Circular includes are detected and warned about.
+the full route tree. It resolves both the eager form `include("/x", patterns)`
+and the code-split async form `include("/x", () => import("./x"))` — for the
+latter it walks the imported module's `export default urls(...)`, including any
+nested `include()`s inside it — so a code-split route group is still fully typed
+(see `/composability`). Circular includes are detected and warned about.
 
 ### First-wins deduplication