@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.d98a8e9d

package/skills/mime-routes/SKILL.md

@@ -108,6 +108,33 @@ path.text("/api/data", () => "plain text version", { name: "dataText" }),
 Without an RSC primary, there is no `text/html` candidate — the Accept header
 picks among the response-type candidates directly.
 
+## Type Safety For Negotiated Paths
+
+`router.named-routes.gen.ts` validates route names, params, search, `href()`, and
+the `Rango.Path` type, but it does not carry response payload metadata. For MIME or
+response payload types, use one of these surfaces:
+
+- `RouteResponse<typeof patterns, "routeName">` for a specific response variant
+  by route name. This is the clearest option when several MIME variants share
+  one URL pattern.
+- `Rango.PathResponse<"/products/:id">` (ambient, no import) for global lookup by URL pattern or concrete path after the app
+  registers `typeof router.routeMap`:
+
+```typescript
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+`RegisteredRoutes` is what exposes the richer routeMap entries containing
+response payload metadata. Without it, URL-pattern response lookup has paths but
+no payloads, so response types resolve to `never`.
+
 ## How It Works
 
 1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.

package/skills/observability/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: observability
+description: Debug Rango request performance with debugPerformance, Server-Timing, structured telemetry, and tracing
+argument-hint:
+---
+
+# Observability
+
+Use this when you need to understand request latency, cache decisions,
+revalidation behavior, loader overlap, or production traces.
+
+Rango exposes two complementary observability surfaces:
+
+1. **Performance timeline** (`debugPerformance`) — per-request waterfall for
+   local or targeted debugging. It prints to the console and emits
+   `Server-Timing`.
+2. **Structured telemetry** (`telemetry`) — lifecycle events sent to a pluggable
+   sink for production monitoring, OpenTelemetry, or custom metrics.
+
+The essentials are below. The exported `TelemetryEvent` union type
+(`import type { TelemetryEvent } from "@rangojs/router"`) is the full event
+contract — every event kind and its fields are typed there.
+
+## Performance timeline
+
+Enable globally while debugging:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  debugPerformance: true,
+});
+```
+
+Or enable for selected requests from middleware:
+
+```typescript
+middleware(async (ctx, next) => {
+  if (ctx.url.searchParams.has("debug")) {
+    ctx.debugPerformance();
+  }
+  await next();
+});
+```
+
+Call `ctx.debugPerformance()` before `await next()`. The request then prints a
+shared-axis waterfall and adds a `Server-Timing` header.
+
+Read the timeline as intervals:
+
+- `handler:total` is the whole router request.
+- `render:total` / `ssr-render-html` show the render pass.
+- `loader:*` rows should overlap render work. If a loader starts only after the
+  render bar, it is serialized latency.
+- Cache, route matching, middleware pre/post, RSC serialization, and SSR phases
+  appear as separate spans, so the slow phase is visible without guessing.
+
+## Structured telemetry
+
+Use telemetry when you want durable production events rather than a one-request
+debug waterfall.
+
+```typescript
+import { createRouter, createConsoleSink } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createConsoleSink(),
+});
+```
+
+For OpenTelemetry:
+
+```typescript
+import { createRouter, createOTelSink } from "@rangojs/router";
+import { trace } from "@opentelemetry/api";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createOTelSink(trace.getTracer("my-app")),
+});
+```
+
+Custom sinks implement `emit(event)`:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: {
+    emit(event) {
+      myMetrics.record(event);
+    },
+  },
+});
+```
+
+Events include `request.start/end/error`, `loader.start/end/error`,
+`handler.error`, `cache.decision`, and `revalidation.decision`.
+
+## Debugging revalidation and stale data
+
+When stale UI or unexpected partial renders are the question, use all three
+layers together:
+
+```typescript
+import { createConsoleSink, createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  debugPerformance: true,
+  telemetry: createConsoleSink(),
+});
+```
+
+Then inspect:
+
+- `revalidation.decision` telemetry to see which segment re-ran or skipped.
+- cache spans / `cache.decision` events to see hit, miss, stale, and background
+  revalidation behavior.
+- loader spans to confirm live loaders overlap the render rather than blocking
+  first paint.
+- the `Server-Timing` header to compare local logs with browser-network timing.
+
+## Zero-overhead defaults
+
+`debugPerformance` is off by default, and `telemetry` emits nothing unless a sink
+is configured. Per-request `ctx.debugPerformance()` lets you turn on the
+waterfall only for the route, user, or query param you are investigating.

package/skills/parallel/SKILL.md

@@ -8,9 +8,6 @@ argument-hint: [@slot-name]
 
 Parallel routes render multiple components simultaneously in named slots.
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Basic Parallel Routes
 
 ```typescript
@@ -206,6 +203,67 @@ parallel(
 )
 ```
 
+## Composable Slots via `handler.use`
+
+Slot handlers can carry their own loader, loading, error/notFound boundaries, revalidation, and transition defaults via `.use`. The mount site then declares **just the slot names** — no per-call data wiring.
+
+```typescript
+const CartSummary: Handler = async (ctx) => {
+  const cart = await ctx.use(CartLoader);
+  return <CartSummaryView cart={cart} />;
+};
+CartSummary.use = () => [
+  loader(CartLoader),
+  loading(<CartSkeleton />),
+  revalidate(revalidateCartData),
+];
+
+// Same slot, no copy-pasted plumbing across layouts.
+layout(<DashboardLayout />, () => [
+  parallel({ "@cart": CartSummary }),
+  path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+]);
+
+layout(<AccountLayout />, () => [
+  parallel({ "@cart": CartSummary }),
+  path("/account", AccountIndex, { name: "account.index" }),
+]);
+```
+
+A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit, exactly as in the **Streaming Behavior** section above.
+
+The `parallel` mount site has the narrowest allow-list for `handler.use` items — slots cannot bring their own middleware or layout, only `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, and `transition`. See [skills/handler-use](../handler-use/SKILL.md) for the full table and merge rules.
+
+`transition` is allowed in the slot allow-list, but slot-level rendering does **not** currently apply a `<ViewTransition>` wrapper — only the layout/route wraps take effect at render time. For a modal-only morph today, use an element-level React `<ViewTransition>` inside the slot's component. The reverse direction is the useful guarantee: a layout-level `transition()` fires when the layout's default outlet content changes but **not** when a `<ParallelOutlet />` mounts new content (modal opens are not subtree updates of the layout VT). See [skills/view-transitions](../view-transitions/SKILL.md) for the wrap rules and the intercept caveat.
+
+### Two scopes for explicit `use`: shared (broadcast) and slot-local
+
+`parallel({...slots}, () => [...use])` runs the shared `use()` callback **once per slot** ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)) — items in that callback land on every slot's entry. That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`). (Slots cannot bring `middleware` or `layout` — see the allowed-types note above.)
+
+For single-assignment items like `loading()`, broadcasting overwrites every slot's `handler.use` default. Pass a **slot descriptor** `{ handler, use }` instead — items in the descriptor's `use` apply only to that slot:
+
+```typescript
+// @cart gets a custom skeleton; @notifs keeps its handler.use default.
+parallel({
+  "@cart": {
+    handler: Cart,
+    use: () => [loading(<CustomCartSkeleton />)],
+  },
+  "@notifs": Notifs,
+});
+
+// Opt one slot out of streaming while siblings still stream the broadcast.
+parallel(
+  {
+    "@cart": { handler: Cart, use: () => [loading(false)] },
+    "@notifs": Notifs,
+  },
+  () => [loading(<BroadcastSkeleton />)],
+);
+```
+
+Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items. See [skills/handler-use § `loading()` is a single-assignment item — scope it correctly](../handler-use/SKILL.md#loading-is-a-single-assignment-item--scope-it-correctly) for the full reasoning.
+
 ## Slot Override Semantics
 
 When multiple `parallel()` calls define the same slot name, **the last
@@ -279,7 +337,7 @@ parallel(
   () => [
     loader(CartLoader),
     // Revalidate when cart actions occur
-    revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+    revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
   ]
 )
 ```
@@ -288,6 +346,13 @@ Revalidating only the parallel does not re-run outer handlers/layouts.
 If the slot reads `ctx.get()` data established above it, opt the outer
 segment into revalidation as well.
 
+A `revalidate()` callback may return a hard `boolean`, a soft
+`{ defaultShouldRevalidate }` object, or nothing (`void` / `null` /
+`undefined`) to defer to the next revalidator. See
+[loader/SKILL.md#revalidate-return-shapes](../loader/SKILL.md#revalidate-return-shapes)
+for the full contract — it's the same across `loader()`, `path()`,
+`layout()`, `parallel()`, and `intercept()`.
+
 ### Revalidation Contracts for Parallel Dependencies
 
 Prefer named revalidation contracts shared by both the upstream producer and
@@ -296,7 +361,7 @@ the parallel consumer:
 ```typescript
 // revalidation-contracts.ts
 export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") ?? false;
+  actionId?.includes("src/actions/cart.ts#") || undefined;
 
 layout(CartLayout, () => [
   revalidate(revalidateCartData), // producer reruns
@@ -414,7 +479,7 @@ export const shopPatterns = urls(({
       () => [
         loader(CartLoader),
         loading(<CartSkeleton />),
-        revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
       ]
     ),
 

package/skills/prerender/SKILL.md

@@ -11,9 +11,6 @@ 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.
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## API: Prerender
 
 ### Static Route (no params)
@@ -361,16 +358,16 @@ Both error types propagate to the router's `onError` callback with phase
 The build produces per-URL timing logs:
 
 ```
-[rsc-router] Pre-rendering 12 URL(s) (concurrency: 4)...
-[rsc-router]   OK   /articles/hello            (42ms)
-[rsc-router]   PASS /articles/remote-only      (5ms) - live fallback
-[rsc-router]   SKIP /articles/draft-post       (3ms) - Article is a draft
-[rsc-router] Pre-render complete: 11 done, 1 skipped (1204ms total)
-
-[rsc-router] Rendering 3 static handler(s)...
-[rsc-router]   OK   DocsLayout                 (28ms)
-[rsc-router]   SKIP TocSidebar                 (1ms) - Not ready
-[rsc-router] Static render complete: 2 done, 1 skipped (120ms total)
+[rango] Pre-rendering 12 URL(s) (concurrency: 4)...
+[rango]   OK   /articles/hello            (42ms)
+[rango]   PASS /articles/remote-only      (5ms) - live fallback
+[rango]   SKIP /articles/draft-post       (3ms) - Article is a draft
+[rango] Pre-render complete: 11 done, 1 skipped (1204ms total)
+
+[rango] Rendering 3 static handler(s)...
+[rango]   OK   DocsLayout                 (28ms)
+[rango]   SKIP TocSidebar                 (1ms) - Not ready
+[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
@@ -466,9 +463,9 @@ export const Product = Passthrough(ProductDef, async (ctx) => {
 Passthrough entries are logged distinctly:
 
 ```
-[rsc-router]   OK   /blog/a                          (42ms)
-[rsc-router]   PASS /blog/b                          (3ms) - live fallback
-[rsc-router]   OK   /blog/c                          (38ms)
+[rango]   OK   /blog/a                          (42ms)
+[rango]   PASS /blog/b                          (3ms) - live fallback
+[rango]   OK   /blog/c                          (38ms)
 ```
 
 ## Edge Cases and Constraints
@@ -640,16 +637,7 @@ At runtime, the cache-lookup middleware uses these flags:
 
 ## Contributor Checklist
 
-Before changing prerender behavior, read these docs and run these tests.
-
-### Docs to re-read
-
-- [Prerender API design](../../docs/prerender-api-design.md) -- canonical
-  architecture: build-time flow, runtime flow, storage, Passthrough, intercept
-- [Execution model](../../docs/internal/execution-model.md) -- handler-first
-  ordering, middleware scope, context visibility rules
-- [Semantic change checklist](../../docs/internal/semantic-change-checklist.md)
-  -- gate for any change to execution semantics
+Before changing prerender behavior, run these tests.
 
 ### Tests to run
 
@@ -676,10 +664,3 @@ pnpm --filter @rangojs/router exec playwright test handler-first
   dev/build-only and do not need a production counterpart.
 - Behavioral assertions (rendered content, loader freshness, Passthrough
   fallback, intercept variant selection) must work in the production build.
-
-## Maintenance References
-
-- [Stability next steps plan](../../docs/internal/stability-next-steps-plan.md)
-  -- completed parity and cleanup pass (reference for decisions made)
-- [Test quality baseline](../../docs/internal/test-quality-baseline.md) --
-  measured test inventory, sleep debt, production coverage gaps

package/skills/rango/SKILL.md

@@ -8,30 +8,242 @@ argument-hint:
 
 Django-inspired RSC router with composable URL patterns, type-safe href, and server components.
 
+This page is the mental model to read **before** the catalog. A flat list of
+skills gives nothing to slot details into, so a reader free-associates from local
+vocabulary — which is exactly how `revalidate()` gets misread as caching. Start
+with the shape, then pick a primitive.
+
+## The shape of rango (read first)
+
+- **Routes are expressed, not configured.** The `urls()` tree shows where every
+  route, layout, loader, and cache lives. No file-system convention, no hunting.
+- **Two freshness axes, orthogonal:**
+  - _stored-value freshness_ — `"use cache"`, `cache()`, loader `cache()`
+    (SWR is first-class where the store supports it; `"use cache"` ships a
+    default SWR window; see `/cache-guide`)
+  - _client-update selection_ — `revalidate()`
+- **Loaders are the live data layer** — fresh every request by default, even
+  inside a cached render. They run **in parallel** right after middleware and
+  **stream**, so data latency overlaps first paint instead of blocking it (a
+  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.
+- **Type-safe end to end** — route names, params, search schemas, loader return
+  types, context vars, and `href` / `reverse` are checked at compile time
+  (`/typesafety`).
+- **See where time goes** — turn on `debugPerformance` early (router option, or
+  `ctx.debugPerformance()` in middleware for per-request opt-in). It prints a
+  per-request waterfall + `Server-Timing` header; loaders should overlap the
+  render bar, not serialize after it. For production, wire `telemetry` to a
+  console, OpenTelemetry, or custom sink. See `/observability`.
+
+Most features are **just-in-time**: the core is `urls()`, `path()`, `layout()`,
+`include()`, and `reverse()`. Caching, parallel routes, intercepts, prerender,
+i18n, themes, and the rest are opt-in — reach for them when a requirement
+appears, not up front.
+
+## Composability: structure vs config
+
+- `path()` / `include()` are **structure** — they define URLs and must stay
+  visible in `urls()`. They cannot be hidden in a factory. `include()` composes
+  whole modules (separation of real concerns); `path()` places a leaf.
+- Everything else — `cache`, `loader`, `loading`, `middleware`, `revalidate`,
+  `parallel`, `intercept`, `errorBoundary`, … — is **config**. It attaches to a
+  node via its `use` callback, is importable, and extracts into factories that
+  return arrays (`withAuth()`, `withCaching()`), flattened automatically.
+
+To decide where something can live: **does it define a URL? structure, stays in
+`urls()`. Does it modify a node? config, compose freely.**
+
+## 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 |
+
+## 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.
+- 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).
+- `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
+  `createVar({ cache: false })` throws on a **direct** read inside a `cache()`
+  boundary (a deliberately non-propagating guard). See `/cache-guide` →
+  "Correctness & invalidation".
+- Nested caches: the outer cache window bounds the inner — an inner shorter TTL
+  only applies when the enclosing cache recomputes; put a value in a loader if it
+  must be fresher. See `/cache-guide` → "Combining Both".
+
+## Don't confuse
+
+- `revalidate()` ≠ cache invalidation — partial-render selection vs value freshness.
+- host router `.lazy()` (lazy import of a handler/sub-app) vs `.map()` (inline Response).
+- `cache()` (segment, in the DSL) vs `"use cache"` (function/component directive).
+- `loader()` registration (server) vs `useLoader()` consumption (client).
+
+### Coming from another framework (false friends)
+
+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.                                                                        |
+
+See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
+`revalidate()` (axis 2), and `/document-cache` for the edge layer.
+
+## Canonical shape
+
+```ts
+export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
+  layout(<ShopLayout />, () => [                 // structure: wraps children
+    loader(CartLoader, () => [                   // config: live data
+      // partial-render axis: re-run on cart actions, defer otherwise.
+      // ctx.isAction() matches by reference (rename-safe), not by string.
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+    ]),
+    path("/shop/:slug", ProductPage, { name: "product" }, () => [  // structure: leaf
+      loader(ProductLoader, () => [cache({ ttl: 60 })]),  // config: cache loader DATA
+      loading(<ProductSkeleton />),              // config
+      withRecs(),                                // composed factory (config array)
+    ]),
+  ]),
+]);
+```
+
+One tree, both axes visible: structure (`layout`/`path`) vs config (everything
+else), freshness (`cache`) vs client-update (`revalidate`). Actions are matched
+by reference with `ctx.isAction(Action)` (rename-safe, where `CartActions` is an
+`import * as CartActions from "./actions/cart"`); see `/typesafety` → "Stable
+identity".
+
+The predicate arg carries the action's full context, not just its identity. Match
+_which_ action with `ctx.isAction(addToCart)` (rename-safe); branch on _what it
+returned_ with `ctx.actionResult` — the value your `"use server"` function
+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).
+
+```ts
+// re-render only when checkout actually succeeded; defer otherwise
+revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
+```
+
+**The source is the source of truth.** Structure, types, and update policy are
+visible and local in the tree — read top-down, no hidden global model to hold in
+your head. A snippet earns its place only if, from the code alone, you can answer:
+_what URLs exist and who owns them?_ (composition), _can I trust this reference
+without leaving the call site?_ (type-safety), _what re-renders after this
+action?_ (partial rendering). If any answer needs another file, it isn't legible
+yet.
+
+**Reading Rango's own source.** Rango is consumed as raw TypeScript — the
+`exports` map resolves `@rangojs/router` and its subpaths to `./src/*.ts` for
+both types and runtime, so a consuming app bundles Rango straight from source.
+Only the `./vite` plugin entry and the CLI `bin` load from `dist/`. To confirm
+any runtime or type detail against an installed copy, read the resolved source
+under `node_modules/@rangojs/router/src/`, not `dist/` — the runtime does not
+resolve `dist/` outside `./vite`, and it may lag `src/`.
+
 ## Skills
 
-| Skill              | Description                                                                |
-| ------------------ | -------------------------------------------------------------------------- |
-| `/router-setup`    | Create and configure the RSC router                                        |
-| `/route`           | Define routes with `urls()` and `path()`                                   |
-| `/layout`          | Layouts that wrap child routes                                             |
-| `/loader`          | Data loaders with `createLoader()`                                         |
-| `/middleware`      | Request processing and authentication                                      |
-| `/intercept`       | Modal/slide-over patterns for soft navigation                              |
-| `/parallel`        | Multi-column layouts and sidebars                                          |
-| `/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                                    |
-| `/theme`           | Light/dark mode with FOUC prevention                                       |
-| `/links`           | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
-| `/hooks`           | Client-side React hooks                                                    |
-| `/typesafety`      | Type-safe routes, params, href, and environment                            |
-| `/host-router`     | Multi-app host routing with domain/subdomain patterns                      |
-| `/tailwind`        | Set up Tailwind CSS v4 with `?url` imports                                 |
-| `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
-| `/mime-routes`     | Content negotiation — same URL, different response types via Accept header |
-| `/fonts`           | Load web fonts with preload hints                                          |
+Grouped by concern — read when you need to…
+
+**Structure & routing** — shape URLs, layouts, navigation, and request processing:
+
+| Skill                     | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `/router-setup`           | Create and configure the RSC router                                        |
+| `/route`                  | Define routes with `urls()`, `path()`, and `include()`                     |
+| `/layout`                 | Layouts that wrap child routes                                             |
+| `/parallel`               | Multi-column layouts and sidebars                                          |
+| `/intercept`              | Modal/slide-over patterns for soft navigation                              |
+| `/middleware`             | Request processing and authentication                                      |
+| `/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`           |
+| `/composability`          | Reusable route-helper factories (structure vs config)                      |
+
+**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)     |
+
+**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        |
+
+**Observability & production health**:
+
+| Skill              | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| `/observability`   | `debugPerformance`, `Server-Timing`, structured telemetry, tracing       |
+| `/bundle-analysis` | Audit your app's production bundle for server leaks and oversized chunks |
+| `/debug-manifest`  | Inspect route manifest structure                                         |
+
+**Testing**:
+
+| Skill      | Description                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `/testing` | Unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement) |
+
+**Setup, types & migration**:
+
+| Skill                   | Description                                     |
+| ----------------------- | ----------------------------------------------- |
+| `/typesafety`           | Type-safe routes, params, href, and environment |
+| `/migrate-nextjs`       | Migrate a Next.js App Router project to Rango   |
+| `/migrate-react-router` | Migrate a React Router / Remix project to Rango |
 
 ## Quick Start
 
@@ -87,6 +299,15 @@ Each file is classified by its contents:
 Directories are scanned recursively for `.ts`/`.tsx` files, skipping `node_modules`,
 dotfiles, and existing `.gen.` files.
 
+> The two generated files are **not interchangeable surfaces**.
+> `router.named-routes.gen.ts` augments the global `GeneratedRouteMap` for
+> named-route typing (`Handler<"name">`, `ctx.reverse("name")`, prerender).
+> Per-module `*.gen.ts` exports a local `routes` map for `useReverse(routes)`
+> and explicit local handler typing (`Handler<".name", routes>`). Neither
+> carries response payloads — response/MIME payload inference comes from
+> `typeof router.routeMap` via `RegisteredRoutes`, not `*.named-routes.gen.ts`.
+> See `/typesafety` for the full surface breakdown.
+
 ### Recursive includes
 
 The generator follows `include()` calls across files, resolving imports to build