diff --git a/AUDIT_REPORT.md b/AUDIT_REPORT.md
new file mode 100644
index 0000000..acda943
--- /dev/null
+++ b/AUDIT_REPORT.md
@@ -0,0 +1,654 @@
+# Askr Docs/Marketing Accuracy Audit
+
+Scope: every marketing page (`/`, `/platform`, `/application-model`, `/rendering`,
+`/full-stack`, `/themes`, `/tooling`, `/production`, `/contribute`), the full
+`/docs` nav tree, and the top-level READMEs (`website/README.md`,
+`askr/README.md`), checked against real source in `askrjs/askr`,
+`askrjs/askr-ui`, `askrjs/askr-themes`, `askrjs/askr-server`,
+`askrjs/askr-auth`, `askrjs/askr-cli`, `askrjs/askr-fetch`,
+`askrjs/askr-schema`, `askrjs/askr-node`, `askrjs/askr-otel`,
+`askrjs/askr-i18n`, `askrjs/askr-charts`, `askrjs/askr-monaco`,
+`askrjs/askr-lucide`, `askrjs/askr-testing`, `askrjs/askr-vite`.
+
+All content in this site is generated from typed data files, not per-page
+markdown — the prose lives in `src/pages/docs/content-overrides.ts`
+(`headingOverrides` + `descriptionOverrides`, keyed by route and heading),
+`src/pages/docs/usage-guide.ts` (`routeExamples`, hand-written code
+snippets), and `src/pages/docs/catalog.ts` (titles, headings, `status`
+flags). All fixes below are edits to those three files, plus two marketing
+`.tsx` files and the `askr` repo's `README.md`. **Nothing has been
+committed** — all changes are left in the working tree for review, split
+across two repos:
+
+- `askrjs/website` (branch `docs-audit-accuracy`, not pushed)
+- `askrjs/askr` (uncommitted `README.md` change; that repo also has an
+  unrelated pre-existing uncommitted change in
+  `benches/tier2/tier2-subsystem-hydration-defer-until-idle.tsx` that I did
+  not make and left untouched)
+
+## Method
+
+I did not treat every page as equally likely to be wrong. Before touching
+content I ran `tests/package-snapshot-contract.test.ts`, which derives every
+`@askrjs/*` package's real exported entrypoints, signatures, CLI help text,
+and peer dependencies straight from installed `node_modules` and fails CI on
+any drift — confirmed green. That means raw API-surface claims on
+`/docs/reference/*` pages (exports exist, signatures match, CLI flags match)
+are already mechanically guarded and were **not** the focus of manual
+re-verification. The actual risk surface is **behavioral/narrative prose** —
+what something _does_, not just that it exists — which nothing checks
+automatically. I audited that: six parallel read-only passes (one per major
+nav section) each read the real implementation for every checkable claim,
+then I applied the confirmed findings myself, sequentially, to avoid
+conflicting edits to the same shared files.
+
+Every fix below cites the exact source file/line I verified against before
+editing (not the framework's own docs, which can also be stale — I read the
+implementation).
+
+## Highest-priority finding: reactivity-model misdescription (fixed)
+
+**Bucket: Inaccurate.** The known issue described in the brief was real and
+still present. `/docs/guides/migration-from-react` (four headings) and the
+`render-purity` heading on `/docs/core-concepts/determinism` described
+`state()`/`derive()` in Solid-style fine-grained-reactivity terms:
+"components are not re-executed on every state change," reads "subscribe
+that specific expression" instead of re-running the component, "no
+`useMemo`/`useCallback` tax... because there's no re-render to guard
+against." None of that is true.
+
+**Verified against:** `askr/src/runtime/component-internal.ts`
+(`executeComponentSync` calls `instance.fn` again on every update — a full
+re-invocation, not a per-expression patch) and `askr/src/renderer/reconcile.ts`
+(the re-run's output is diffed/patched as a VNode tree). Also verified the
+real, useful distinction that _was_ getting lost: subscriptions are tracked
+per component instance (a component only re-runs if it actually read a
+changed source last render — no top-down cascade the way an unmemoized React
+tree re-renders every child), and `<For>` genuinely does patch per-row
+without re-invoking the render callback for unchanged rows (confirmed
+`INSERT_ONE`/`REMOVE_ONE`/`SWAP`/`FULL_KEYED` commit strategies in
+`askr/src/runtime/for-reconcile.ts`). Rewrote all five headings to state this
+accurately — components re-run, output is reconciled, not per-node
+signal-based updates — without borrowing Solid's vocabulary for a mechanism
+that works differently, and without implying speed parity with (or against)
+Solid either way.
+
+Also added a load-bearing caveat the page never mentioned: hook-order
+enforcement and the "state cannot be mutated during render" runtime check
+(`askr/src/runtime/state.ts:170`, exact string `[Askr] state.set() cannot be
+called during component render.`; ordering rule from
+`askr/docs/concepts/runtime-enforcement.md`, confirmed live in
+`component-internal.ts`). These are real React-like constraints nothing on
+the site mentioned.
+
+**Landing page / READMEs:** the website's own `home.tsx` and README do
+_not_ currently make the false claim (they only describe routing, not
+reactivity mechanics) — the false claims were concentrated in the migration
+guide and one core-concepts heading, both now fixed. The `askr` repo's own
+top-level `README.md` reactivity section was already conservative (getter/
+setter description only, no re-render-model claim) and needed no change on
+that front — but see the separate ErrorBoundary fix below, found in the same
+file.
+
+## Bucket classification by section
+
+### Marketing pages — mostly Accurate; one fixed
+
+- `/` (home.tsx) — **Accurate.** No reactivity-model claims present; routing
+  claims checked against `askr/src/router/authoring.ts` and `askr-cli`
+  templates.
+- `/platform` — **Inaccurate → fixed.** Claimed `@askrjs/fetch` clients are
+  "generated from an OpenAPI document." Backwards: `@askrjs/fetch` is
+  hand-authored (`defineApi`, `.query()`, `.returns()`, etc. —
+  `askr-fetch/README.md:16-30`); OpenAPI-driven _generation_ is a separate
+  `askr-cli` command (`askr generate`) that the `/tooling` page already
+  described correctly. Fixed the sentence to describe both paths accurately.
+  Also fixed the ErrorBoundary dev/prod claim shared with the README (below).
+- `/application-model`, `/rendering`, `/full-stack`, `/themes`, `/tooling`,
+  `/production`, `/contribute` — **Accurate.** Spot-checked against
+  `askr/src/router/authoring.ts`, `askr/src/data/query-cell.ts`,
+  `askr/src/data/invalidation.ts`, `askr/src/boot/index.ts`,
+  `askr-server/src/askr/action-stages.ts`, `askr-schema/src/index.ts`,
+  `askr-cli/src/bin/cli.ts` + `templates/*`, `askr-server/src/contracts.ts`,
+  `askr-i18n/src/index.ts`, `askr-otel/src/index.ts` (the "OTel field
+  allowlist has no room for bodies/cookies/tokens" claim checks out exactly
+  — `TelemetryFields` is a closed 8-field interface).
+
+### `website/README.md` and `askr/README.md`
+
+- `website/README.md` — **Accurate.** Describes this repo's own build
+  pipeline; all referenced scripts/paths exist.
+- `askr/README.md` — **Inaccurate → fixed.** The "Developer error
+  boundaries" section claimed the visible fallback UI only renders "in
+  development." Verified against `askr/src/renderer/error-boundary-dom.ts`:
+  the default fallback renders in _every_ environment; only its `<details>`
+  panel's `open` state is dev-specific (`details.open =
+isDevelopmentEnvironment()`). Fixed the README and the matching
+  `/docs/core-concepts/error-boundaries` `reporting` heading, which had the
+  identical error.
+
+### Getting Started — Accurate-but-incomplete → fixed
+
+Four findings, all about template-shape assumptions baked into prose as if
+universal:
+
+- `/docs/getting-started/installation` (`install-packages-directly`) claimed
+  the CLI has zero subpath exports; `@askrjs/cli/ssg` is real
+  (`askr-cli/package.json` exports). Fixed.
+- `/docs/getting-started/project-structure` (`pages-and-routes`) and
+  `/docs/getting-started/first-application` (`create-the-project`) both
+  called `src/pages/**/_routes.tsx` "the CLI's default shape." Actual
+  default template is `startkit`, which uses `src/router.tsx` +
+  `src/routes/*.ts` — `_routes.tsx` is specific to the `spa` template.
+  Verified against `askr-cli/src/bin/create.ts:905` and the templates
+  directory. Fixed both to name the real per-template shape.
+- `/docs/getting-started/first-application` (`build-the-application`)
+  grouped SPA and full-stack together as producing "a client bundle only" —
+  full-stack also builds a server bundle, same as SSR. Fixed.
+
+### Core Concepts — Accurate-but-incomplete / Inaccurate → fixed
+
+- `state-and-derived-values`, `components-and-jsx`, `lists-with-for`,
+  `conditional-rendering`, `scopes`, `lifecycle-work`, `error-boundaries` —
+  mostly accurate; two real errors found and fixed:
+  - `determinism` (`hydration-diagnostics`): claimed dev diagnostics use
+    `devWarningsEmitted` to point at "which subtree diverged" with "a
+    specific warning." `devWarningsEmitted` is unrelated (used only for
+    unused-state/slow-render warnings — `component-internal.ts:125`); the
+    real check (`askr/src/ssr/verify-hydration.ts`) is a whole-document
+    string comparison producing exactly one generic message (quoted
+    verbatim from `askr/src/boot/index.ts:362`). Fixed.
+  - `lifecycle-work` (`events-and-streams`): claimed `stream()` returns "the
+    same `{ value, pending, error }` shape as `resource`." Actual shape
+    (`askr/src/runtime/stream-operation.ts:20-29`) is `{ value, status,
+pending, stale, error, restart(), close() }` — meaningfully richer.
+    Fixed.
+  - `scopes` description (`descriptionOverrides`): claimed "scopes own
+    effects and resources, and dispose of them with their lexical owner."
+    `Scope<T>` (`askr/src/runtime/context.ts`) is a pure context-provider —
+    no effect/resource ownership exists there; that's the component
+    instance's `cleanupFns`, unrelated to `defineScope`. Rewrote to describe
+    what scopes actually do (pass a value down the tree).
+
+### Routing — Accurate-but-incomplete / Inaccurate → fixed
+
+Six findings, all fixed:
+
+- `definitions-and-layouts` (`fallback-routes`): "exactly one fallback per
+  `RouteRegistry`" — actually one per _scope_; `page()` sections can each
+  register their own (`askr/src/router/authoring.ts:482-514`).
+- `paths-and-parameters` (`static-and-dynamic-segments`): conflated
+  `wildcard` (a bare `*` after a static prefix) with `catchall` (reserved
+  for the bare path `/*` alone, what `fallback()` uses internally) — verified
+  against `askr/src/router/match.ts`.
+- `navigation-and-url-state` (`active-route-state`): described
+  `currentRoute()`'s render-only requirement as a style suggestion ("call it
+  during render rather than..."); it's an enforced throw
+  (`askr/src/router/activity.ts:315-324`).
+- `navigation-and-url-state` (`history-and-scroll`): claimed
+  `ScrollRestorationOptions` is per-navigation configurable; it's app-wide,
+  set once via `configureScrollRestoration()`
+  (`askr/src/router/navigation-scroll.ts`). `NavigateOptions.scroll` is the
+  real (narrower) per-call override, confirmed to actually exist.
+- `route-metadata` (`head-reconciliation`, `ssg-metadata`) — **real product
+  gap, not just a docs error.** `resolveRouteMeta`/`serializeRouteMeta`/
+  `reconcileRouteMeta` are real, working functions, but they're **only ever
+  called from the router's client-side navigation code** — grepped
+  `askr/src/ssr/**` and `askr/src/ssg/**` for all three names: zero hits.
+  There is no automatic wiring of route metadata into an SSR or SSG
+  document's `<head>`. Rewrote both headings to say so explicitly and added
+  `status: 'limited'` in `catalog.ts` with an inline comment explaining why
+  — this is exactly the "Published limitation" pattern the brief asked me to
+  extend consistently.
+
+### Data — Inaccurate → fixed (one significant)
+
+- `actions-and-forms` (`redirects-and-revalidation`): claimed "there's no
+  separate redirect API in the actions module itself." False — there's a
+  dedicated, security-checked redirect pipeline end to end: server
+  `ActionOutcome.redirect` → same-origin validation
+  (`askr/src/actions/index.tsx:97-105`) → `location.assign()` on the
+  enhanced path, or a real HTTP 303 on the no-JS form-post path
+  (`askr-server/src/askr/action-stages.ts`). This also directly contradicted
+  the page's own `descriptionOverrides` entry, which already got it right.
+  Fixed the prose to match reality (and the rest of the page).
+- `queries-and-consistency` (`refresh-behavior`, `define-a-query`): both
+  claimed `reconcile()` decides whether fetched data replaces the cache.
+  Traced `askr/src/data/query-cell.ts:395-451`: fetched data is written to
+  state _before_ `reconcile()` even runs; `reconcile()`'s return value only
+  controls whether an automatic retry is scheduled. Out-of-order responses
+  are guarded separately by generation/controller-identity checks. Fixed
+  both headings.
+- `/docs/data` + `mutations-and-invalidation` (`writes-and-invalidation`,
+  `targeted-invalidation`): both said `affects()` "automatically triggers
+  invalidate()" without the actual gate — it only fires when
+  `afterSuccess === 'invalidate'` (`askr/src/data/mutation-cell.ts:116-123`).
+  Fixed both.
+- `server-queries` (`prefetch`): claimed `prefetchQuery` "runs that query
+  against the registered handler," unqualified. Only true in `'ssr'` mode;
+  `'spa'` mode (the default) never consults the registry and calls the
+  query's own `fetch()` instead (`askr/src/data/query-registry.ts:83-114`).
+  Fixed.
+
+### Rendering, Server, Authentication, HTTP Contracts — Inaccurate/Incomplete → fixed (20 findings)
+
+The largest cluster of concrete errors, all fixed:
+
+- **Rendering:** `shared-application-model` claimed `RouteHandler`/
+  `RouteRegistry` are re-exported identically from `/ssr`, `/ssg`, and
+  `/boot` — they're defined once in `/router` and imported from there, not
+  redeclared per module. `island-ownership` misattributed a doc comment to
+  the wrong symbol. `hydration` (`mismatch-diagnostics`) claimed
+  `skipSelectors` exempts a region from markup verification — it only
+  exempts listener attachment/deferred tracking, not `verifyMarkup`'s
+  comparison (`askr/src/renderer/dom-internal.ts` vs `verify-hydration.ts`).
+- **Server:** `onError`/`error-handling` (two pages) claimed
+  `ServerAppOptions.onError` is _the_ single funnel for unhandled
+  exceptions — several framework-recognized failures (oversized body,
+  malformed path param, `ctx.bind()` failure) are converted to a fixed
+  problem+json response _before_ `onError` runs (`askr-server/src/application.ts:60-72`).
+  `problem-details` cited RFC 7807; the real implementation self-identifies
+  as RFC 9457 (`askr-server/src/contracts.ts`, `http/responses.ts`).
+  `server-actions` (`action-responses`) omitted that `ActionOutcome` also
+  carries cookie instructions (`askr-server/src/askr/action-types.ts`).
+- **Authentication (7 findings, the weakest section before this pass):**
+  malformed-token handling claimed uniform throw behavior — bearer JWTs
+  throw, but a malformed JWT _cookie_ is caught internally and falls through
+  silently (`askr-auth/src/auth-resolver.ts:31-67`). Session expiry claimed
+  "no built-in expiry enforcement beyond your store" — `createAuth` actually
+  checks `expiresAt`/`revokedAt` itself against `clock()`
+  (`auth-resolver.ts:12-13,71-72`). The `usage-guide.ts` authorization
+  example called `auth.permissions` — `AuthContext` has no such field, it's
+  `principal.permissions` and `principal` can be `null`; the example would
+  throw at runtime — fixed. JWT `clock` default was described as raw
+  `Date.now` (milliseconds); it's `Math.floor(Date.now()/1000)` (Unix
+  seconds) — and it's a _different_ clock from the session-side
+  `AuthOptions.clock`, both sharing the name "clock" across pages, now
+  called out explicitly. OIDC `callback-validation` described
+  `exchangeCode()` as returning a raw, unvalidated token response requiring
+  a separate `validateOidcIdToken()` call — it already validates internally
+  and returns `{ tokens, principal }` (`askr-auth/src/oidc-client.ts:54-86`).
+  `framework-routes`: the `/auth/v1` prefix was described as a convention;
+  it's hardcoded inside `registerAuthRoutes` (`askr-server/src/auth.ts:171`).
+  A throttled `allowAttempt` was described as surfacing via `AuthRouteError`
+  429; it actually short-circuits straight to `tooManyRequests()` —
+  `AuthRouteError` exists for the caller's own register/authenticate
+  callbacks to throw instead.
+- **HTTP Contracts (6 findings):** `open-api` `client-generation` claimed no
+  code-generation path exists for consuming an API — `askr generate` is a
+  real CLI command that does exactly that (`askr-cli/src/bin/generate.ts`).
+  `generate-and-check` overstated `toOpenApiDocument()`'s validation — the
+  missing-operationId/undocumented-response checks are gated behind
+  `metadata: 'authored'`, not on by default (`askr-server/src/openapi/validate.ts`).
+  `results-and-errors` (`retries`) attributed upload-retry exclusion to "has
+  a body" — the real cause is POST simply not being in retry's default
+  eligible-methods list; only a genuinely streaming body is permanently
+  excluded (`askr-fetch/src/middleware.ts:93-111`). `typed-clients`
+  (`typed-input`) said query/headers become required only when _every_
+  field is required — it's _any_ required field
+  (`askr-fetch/src/client.ts:386-392`). `typed-output` omitted the
+  `'request'` failure kind. `schemas` (`safe-parsing`) described
+  `schema.record()` as the mechanism for extra-key validation on
+  `schema.object()`; the real mechanism is `additionalProperties: <schema>`
+  — `schema.record()` builds an unrelated standalone schema.
+
+### MCP, Platform Services, Tooling — Inaccurate/Incomplete → fixed (11 findings)
+
+- **MCP:** session-store description flatly wrong — claimed an unbounded,
+  no-TTL in-memory `Set`; the real default (`askr-server/src/mcp/http.ts`)
+  is a TTL- and capacity-bounded `Map` (`sessionTtlMs` default 30 min,
+  `maxSessions` default 1,000, returns 503 at capacity) — fixed across three
+  headings (`deployment`, `http-requests`, `sessions/expiry`,
+  `sessions/state-ownership`). The `Accept` header requirement was described
+  as OR (`application/json` _or_ `text/event-stream`); the code requires
+  both, else 406 (`askr-server/src/mcp/http.ts:158-160`) — fixed. Removed a
+  reference to a nonexistent `initialized: true` session field.
+- **Platform Services:** `createNodeHandler(app, options?)` — `options` is
+  required, not optional (`askr-node/src/handler.ts:84`). OTel `span()`
+  described as accepting a "custom operation" — it's restricted to a closed
+  set of `askr.*` names, no escape hatch (`askr-otel/src/index.ts:19-27`).
+  Exception-capture behavior was undocumented: `createTelemetry` only
+  exports an exception if you supply `sanitizeException` and it returns a
+  value — by default, nothing is captured at all, not auto-redacted.
+- **Tooling:** SSG document composition was claimed to share machinery with
+  `@askrjs/vite`'s dev-server plugin (different mechanisms — a plain
+  `DocumentRenderer` function vs. HTML-comment marker replacement,
+  `askr-vite/src/server/document.ts`). `askr create` was described as
+  triggering interactive template selection whenever no template name is
+  given; it silently defaults to `startkit` unless the _name_ is also
+  omitted or `--prompt` is passed (`askr-cli/src/bin/create.ts:905-963`).
+  `askr upgrade`'s major-bump behavior was described as "next-version" —
+  there's no per-run cap at one major version; the target is whatever the
+  registry's `latest` tag resolves to (`askr-cli/src/update/planner.ts`,
+  `range.ts`). Also fixed a repeated `invalidationKeys`/`cache-hit` error
+  (below).
+
+### Guides section — Inaccurate/Incomplete → fixed (≈25 findings across 15 routes)
+
+`/docs/guides/migration-from-react` was fixed as part of the top-priority
+finding above. Every other guide route was checked; findings and fixes:
+
+- **`generate-a-static-site`:** `result.routes[].reason` was said to include
+  a `'cache-hit'` value — the real `RouteRenderReason` union
+  (`askr/src/ssg/types.ts:24-32`) has no such value; `'unchanged'` is what a
+  correctly-skipped route reports. The CLI's incremental flags were named
+  `invalidationKeys`/`changedRoutes` in prose; the real names are
+  `--changed-key`/`--changed-route`, forwarded internally as
+  `changedKeys`/`changedRoutes` (`invalidationKeys` doesn't exist anywhere
+  in `askr-cli`). Fixed in three places (this guide, the `/docs/data` SSG
+  summary, and `rendering/static-site-generation`).
+- **`protected-routes-and-permissions`** (worst-scoring guide before this
+  pass): claimed a nested `auth.check` field — no such field exists;
+  the real per-route option is a sibling field simply named `auth`
+  (`askr/src/common/router.ts:131-144`). Claimed `deny('forbidden' |
+'unauthorized' | ...)` takes a string reason — `deny()` takes a numeric
+  HTTP status (`401 | 403 | 404`, `askr/src/common/router.ts:82`). The
+  `AuthContext` example omitted its `authenticated` field. All three fixed.
+- **`build-an-authenticated-full-stack-app`:** `route(path, Component,
+{ policy })` — the real field is plural, `policies: [...]`
+  (`askr/src/common/router.ts:141-144`). Fixed.
+- **`add-ssr-to-an-spa`:** claimed `RouteRenderOptions` (the SSR-side type)
+  carries an `auth` field the way the SSG side's `RouteConfig.auth` does —
+  it doesn't (`askr/src/ssr/route-render.ts:38-53`); auth for SSR lives on
+  `resolveRequest({ auth })` instead. Also claimed the user's server entry
+  module calls `createDocumentApp()` itself — the Vite plugin does that
+  internally; the entry module only exports a plain `ServerApp`. Both fixed.
+- **`accessibility`:** claimed `Dialog`, `Popover`, _and_ `Menu` all build
+  on `FocusScope` — `Menu` uses its own roving-focus mechanism, not
+  `FocusScope`. Claimed a `.a11y.d.ts` file is what you'd read — the real
+  source files are `.a11y.ts` (`.d.ts` only exists in compiled `dist/`).
+  Softened an overclaim that `FOCUS_RULES` exists on every contract (only
+  some do). Fixed.
+- **`dashboards-charts-and-polling`:** shown `invalidateOnInterval({...})`
+  without its required `prefix` argument
+  (`askr/src/data/invalidation.ts:40-42`) — fixed to a working call.
+  Claimed cross-`createPlot()`-factory mixing is a compile-time type error;
+  it's a runtime `TypeError` via factory-identity branding
+  (`askr-charts/src/descriptors.ts:87-91`) that TypeScript often won't catch
+  structurally — fixed.
+- **`file-uploads-and-artifacts`:** attributed upload-retry exclusion to "by
+  design" rather than the real mechanism (POST not in retry's default
+  method list; only streaming bodies are permanently excluded) — fixed,
+  consistent with the same correction on `/docs/http-contracts/results-and-errors`.
+- **`forms-actions-and-crud`:** "nothing in `action()` serializes concurrent
+  submissions for you" was true but incomplete — a generation counter
+  silently discards a stale response's effect on UI state even though the
+  earlier write completed server-side (`askr/src/actions/index.tsx:12,123-181`).
+  Fixed to explain the actual behavior, not just "no guarantee."
+- **`loading-empty-error-and-pending-states`:** `mockQuery`/`queryState`
+  constructor list omitted `.pendingWrite()`, the one that actually exercises
+  the `pending-write` consistency state the same page's `goal-and-architecture`
+  heading mentions. Fixed.
+- **`testing-deterministic-applications`:** conflated `mockQuery` builder
+  method names with the real (narrower, hyphenated) `consistency` field
+  values — `loading`/`error` aren't `consistency` values at all. Claimed
+  `retry()` and `debounce()` both expose `cancel()`/`flush()` — `retry()`
+  returns a plain `Promise` with nothing to drive; `debounce`/`throttle`
+  have `.cancel()` only, no `.flush()` (that's on the separate
+  `debounceEvent`/`throttleEvent` variants). Both headings fixed.
+- **`testing-http-applications`:** "It is Node-only" — no Node-specific
+  dependency exists anywhere in `askr-testing/src/**` (built entirely on
+  standard Web APIs); reworded to describe this as a publishing/testing
+  scope statement, not a technical restriction.
+- **`build-an-api-only-server`:** `ctx.bind()`'s merge-priority description
+  was self-contradictory (listed body first, then said params are
+  authoritative). Fixed to state the real order: params, then query, then
+  body.
+- **Guides landing page** (`choose-a-guide`): called `createSPA`,
+  `hydrateSPA`, and `createStaticGen` "mutually exclusive entry points."
+  The first two really are (`askr/src/runtime/execution-model.ts:10-21`
+  throws on mixing them); `createStaticGen` is a separate build-time step
+  routinely _paired_ with `hydrateSPA`, not a fourth exclusive option.
+  Fixed.
+- All other guide routes (`build-an-spa`, `build-an-mcp-server`,
+  `environment-configuration`, `production-readiness`, `realtime-streams`,
+  `tables-filters-and-url-state`, `api-integration-and-error-handling`) —
+  **Accurate**, no changes.
+
+### UI & Components, Charts, Integrations
+
+This section had the largest raw finding count (~50 across 34 routes) —
+almost entirely narrative/behavioral overclaims about specific components,
+not export-existence problems (those are already covered by the contract
+test). Given the volume, I prioritized and fixed the highest-severity class
+— capability claims that materially overstate what ships, and examples/
+import paths that are flatly broken — and I'm disclosing the rest here
+rather than silently leaving them unflagged.
+
+**Fixed (bucket: Inaccurate, verified against source):**
+
+- `/docs/components/toast-and-sonner` — **Inaccurate, needs Published
+  limitation → fixed.** Sonner (`themes/sonner`, aliasing `Toaster`) was
+  described as "a drop-in notifier." It's a bare presentational div wrapper
+  (`askr-themes/src/components/catalog.tsx:798-800`) with no imperative
+  `toast()` API, queueing, stacking, timing, or dismiss logic — despite
+  sharing a name with the standalone Sonner library, it doesn't reproduce
+  its behavior. Set `status: 'limited'` in `catalog.ts` with an explanatory
+  comment and rewrote `purpose`, `anatomy`, and `live-examples` to say so
+  plainly; pointed readers at the real `Toast`/`ToastHost` primitive instead.
+- `/docs/components/advanced-layout` — **Inaccurate, needs Published
+  limitation → fixed.** Claimed `SidebarScope` "coordinates open/closed and
+  rail-expanded state." Verified `SidebarScope` is `sidebarPart(props,
+"sidebar-scope")` — a pure styling wrapper with zero state logic
+  (`askr-themes/src/components/sidebar/sidebar.tsx:74-77`). Set `status:
+'limited'` and rewrote `state-model` to say the app owns all collapse
+  state itself.
+- `/docs/components/button-and-button-group` (`install-and-import`) —
+  example implied `import { Button, ButtonGroup } from
+'@askrjs/themes/button'` works as one statement. `@askrjs/themes/button`
+  only re-exports `Button`; `ButtonGroup` requires the separate
+  `@askrjs/themes/button-group` entrypoint (`askr-themes/src/entries/button.ts`
+  vs `button-group.ts`) — as written, the combined import fails. Fixed.
+- `/docs/components/application-layout`, `/docs/components/advanced-layout`
+  (`install-and-import`, both pages) — both cited `@askrjs/themes/core`,
+  which does not exist anywhere in the package's real exports (confirmed
+  against `package.json` and the `dist/entries/*` wildcard target — no
+  `block.ts`/`header.ts`/`main.ts`/`core.ts` entry files exist). The real
+  path is `@askrjs/themes/components`. Fixed both.
+- `/docs/components/table` (`install-and-import`) — claimed `/table`,
+  `/data-table`, and `/scroll-area` "all resolve to the same
+  `dist/components.js` barrel." They're three separate entry files
+  (`askr-themes/src/entries/{table,data-table,scroll-area}.ts`); `data-table`
+  in particular pulls a completely different, presentational-only component
+  off an internal catalog module, not the same `@askrjs/ui/table`
+  primitives `table` re-exports. Fixed.
+- `/docs/components/virtual-list`, `/docs/components/virtual-table`
+  (`install-and-import`) — both claimed "no themed counterpart... no styled
+  wrapper component" exists in `@askrjs/themes`. Both components are in
+  fact re-exported through the `@askrjs/themes/components` barrel
+  (`askr-themes/src/components.ts:161-180`) — there's no _dedicated_
+  `/virtual-list` subpath, but the "no themed counterpart at all" framing
+  overstated the gap. Fixed both to describe the real (narrower) situation.
+- `/docs/integrations` (`editor-integration`) — claimed the Monaco wrapper
+  "keeps the host div sized." No resize/sizing logic exists anywhere in
+  `askr-monaco/src/components/monaco-editor/monaco-editor.tsx`. Fixed to
+  say sizing is the caller's responsibility.
+- `usage-guide.ts` Monaco Editor example — passed an `onChange` prop that
+  doesn't exist on `MonacoEditorProps` (`askr-monaco/src/components/monaco-editor/monaco-editor.types.ts`
+  only has `onMount`/`onUnmount`). This example would not compile. Fixed to
+  use the real pattern: `onMount` + `editor.onDidChangeModelContent()`.
+
+**Update — second pass, all of the below are now fixed too.** Every item
+that was listed here as "identified but not yet fixed" in the first pass
+has since been verified against source and corrected:
+
+- `/docs/components/interaction-policies` — `edge-cases` wrongly claimed
+  Input/Textarea/Label ship no `_A11Y_CONTRACT` (all three do — confirmed
+  `askr-ui/src/components/{input,textarea,label}/*.a11y.ts`); `state-model`
+  conflated `DISABLED_ATTRIBUTES.asChild` (just the string `'aria-disabled'`,
+  confirmed in `button.a11y.ts`) with a bundled `tabindex="-1"` that's
+  actually separate component behavior. Fixed both.
+- `/docs/components/portals-and-layers` — wrong `--ak-z-dropdown` value
+  (claimed 1000; real token in `askr-themes/src/themes/default/tokens.css`
+  is 1500, tied with `--ak-z-popover`). Fixed the whole z-index ladder to
+  match source exactly.
+- `/docs/components/aria-and-ref-utilities` — `asChild` ref claimed typed as
+  `Ref<unknown>`; verified `button.types.ts` types it `Ref<Element>`. Fixed
+  in both the `api` and `edge-cases` headings.
+- `/docs/components/textarea` — claimed `asChild` on a non-`<textarea>` host
+  silently drops props "as with Input"; verified `textarea.tsx` actually
+  throws `Textarea \`asChild\` requires a native <textarea> host.` — a real
+  behavioral difference from Input (which has no such guard). Fixed.
+- `/docs/components/switch` — verified `switch.tsx`: the hidden `<input>`
+  renders unconditionally off `name` regardless of `asChild` (not removed by
+  it as claimed), `aria-disabled` comes from the same `pressable()` call on
+  both branches (not something you wire yourself for `asChild`), and the
+  thumb is a `::after` pseudo-element with no `data-slot` of its own (not a
+  separately targetable node as claimed). Also pointed `FieldLabel` at the
+  `@askrjs/themes/components` barrel, since `@askrjs/themes/field` doesn't
+  export it (confirmed against `field.ts`/`catalog.tsx`). Fixed all four.
+- `/docs/components/select`, `/docs/components/slider` — confirmed both
+  `select.ts`/`slider.ts` are JS-only re-exports (no CSS in the subpath).
+  Select's claimed `data-side`/`data-align` styling hooks don't exist in the
+  real CSS (`select.css`); actual attributes are `data-placeholder` (on
+  `SelectValue`) and `data-size` (on `SelectTrigger`, values `sm`/`md`/`lg`
+  — `md` has no dedicated rule since it's the unstyled default). Fixed.
+  Slider: fixed the registry-key claim (`WeakMap` on an identity object, not
+  a string `sliderId`, confirmed in `slider.tsx`) and the clamp/snap order
+  (source snaps first, then clamps — the reverse of what was documented,
+  confirmed in `_internal/range.ts`).
+- `/docs/components/toggle-family` — clarified there's no dedicated
+  `toggle.css` (only `toggle-group.css` exists; both JS subpaths are
+  confirmed real, just sharing one stylesheet).
+- `/docs/components/form-label-field-and-input-group` — `Field`'s `invalid`
+  prop does set a real `data-invalid` attribute (confirmed in
+  `field.tsx`), but `field.css` has zero rules keyed to it — fixed to say
+  the hook exists but ships no default visual treatment. Also added that
+  `FieldError` renders with `role="alert"` (confirmed in `field.tsx`),
+  which the page had called "purely presentational."
+- `/docs/components/dialog` — fixed the surface token (`--ak-color-bg`
+  claimed; real token in `dialog.css` is `--ak-color-surface-raised`) and
+  the animation-duration claim (open/close aren't symmetric: `normal` vs.
+  `fast`, confirmed in `dialog.css`).
+- `/docs/components/alert-dialog` — fixed four related overclaims, all
+  checked against `askr-ui/src/components/alert-dialog/*.tsx` and the
+  7-line real `alert-dialog.css`: `role="alertdialog"` is not applied
+  automatically (defaults to Dialog's own role); the trigger and content
+  aren't bare re-exports (both wrap real dismissal-guarding logic, verified
+  in `alert-dialog-trigger.tsx`/`alert-dialog-content.tsx`); the theme layer
+  doesn't style an "action row" or apply a destructive button variant
+  automatically — the real CSS only strengthens the content's border.
+- `/docs/components/popover` — fixed the focus-trap claim (`FocusScope` is
+  used without `trapped`, confirmed default `trapped = false` in
+  `focus-scope.tsx` and the actual call site) and the z-index claim (tied
+  with dropdown at 1500, above modal at 1400 — not "below modals").
+- `/docs/components/tooltip` — fixed `data-disabled` attribution (it's set
+  on `TooltipTrigger`, not `TooltipContent`, confirmed in
+  `tooltip-trigger.tsx`) and removed a claimed CSS fallback value for
+  `--ak-z-tooltip` that doesn't exist in the real stylesheet.
+- `/docs/components/hover-card` — rewrote two headings after finding real
+  Tab/Escape/focus-on-open support in `hover-card-trigger.tsx` and
+  `hover-card-content.tsx` (Tab from the trigger moves into the content,
+  Escape returns focus, Tab cycling is handled) — the page's flat "keyboard
+  users can't reach the content" was wrong; what's actually missing is only
+  a hard focus trap.
+- `/docs/components/tabs` — fixed the `role="tab"` claim (verified
+  `TabsTrigger` is built on `buttonPart()`, whose third argument is a CSS
+  class name, not a role — no role is set) and the "fully manual active
+  state" claim (`Tab`'s active styling is computed automatically from the
+  current route via the same `isActiveNavLink` machinery the rest of the
+  nav components use, confirmed in `nav.tsx`).
+- `/docs/components/navbar-and-navigation-menu` — fixed the `as`-on-trigger
+  claim (`NavigationMenuTrigger` is built on the same `buttonPart()` helper,
+  which explicitly discards `as` — `void as;` in `catalog.tsx`) and the
+  "collapse menu uses Dropdown" claim (the mobile hamburger collapse is
+  built on `Collapsible`/`CollapsibleTrigger`; `Dropdown` is used for a
+  separate per-item flyout, confirmed in `navbar.tsx`).
+- `/docs/components/sidebar` — fixed the "every part accepts `as`" claim;
+  confirmed `SidebarProps` and `SidebarButtonProps` (used by
+  `SidebarMenuButton`/`SidebarMenuAction`/`SidebarTrigger`/`SidebarRail`)
+  both omit `as` in `sidebar.types.ts`, while only the plain layout parts
+  take it.
+- `/docs/components/scroll-area` — the biggest single correction in this
+  pass. Read the full `scroll-area.tsx`: `ScrollAreaScrollbar` renders with
+  `role="scrollbar"`, `aria-valuenow`/`aria-valuemin`/`aria-valuemax` kept
+  live via a `ResizeObserver` and scroll listener, and its own `onKeyDown`
+  handling Arrow/PageUp/PageDown/Home/End that calls back into the real
+  `scrollTop`/`scrollLeft`. Four headings (`edge-cases`,
+  `keyboard-and-accessibility`, `state-model`, `styling-and-tokens`) had
+  described this as `aria-hidden`, unwired, and "a static visual accent" —
+  rewrote all four to describe the real, working custom scrollbar.
+- `/docs/components/card` — added the missing `titleAs` prop (confirmed in
+  `card.tsx`/`card.types.ts`: `CardTitle` defaults to `h3` but accepts
+  `titleAs?: 'h1'-'h6'`) across three headings that had said it "always
+  renders as h3." Also fixed a token-family mix-up: confirmed in
+  `catalog.css` that Card's internal spacing reads `--ak-space-*`, not a
+  `--ak-density-*` family (which does exist, but is scoped to form-control
+  sizing per `tokens.css` — not what Card uses).
+- `/docs/components/avatar-and-item` — same `--ak-density-*`/`--ak-space-*`
+  correction for `Item`'s `size`/`variant` styling, confirmed against the
+  real `[data-slot="item"]` rules in `catalog.css`.
+- `/docs/components/typography-and-display-primitives` — fixed a
+  fabricated `--ak-type-*` token family (real tokens are `--ak-font-size-*`)
+  and the `TypographyMuted` color token name (`--ak-color-text-subtle`, not
+  "muted-foreground" — confirmed in `catalog.css`).
+- `/docs/components/alert-badge-empty-skeleton-spinner-and-stat` — the page
+  was conflating two separate real components: `Empty` (the compound
+  `EmptyHeader`/`EmptyMedia`/`EmptyTitle`/`EmptyDescription`/`EmptyContent`
+  family, confirmed in `catalog.tsx`) and `EmptyState` (a separate,
+  single all-in-one component in its own `empty-state/` directory with
+  `icon`/`title`/`titleAs`/`description`/`action` props). Rewrote `anatomy`
+  and `api` to name both correctly instead of using the names
+  interchangeably.
+- `/docs/charts/channels-and-transforms` (`row-lineage`) — confirmed in
+  `askr-charts/src/transforms.ts` (`applyRowTransforms`) that a fresh,
+  frozen array is allocated as soon as any transform is configured at all,
+  even a no-op one — not only "when they change something" as claimed.
+  Fixed.
+- `/docs/charts/interactions` (`zoom`) — confirmed in
+  `askr-charts/src/controller.ts` that plain arrow keys move mark focus,
+  and panning requires `Shift`+arrow specifically (`event.shiftKey &&
+zoom?.pan`) — the page claimed plain arrows pan. Fixed, and cross-checked
+  against the page's own `crosshair` heading, which was already correct
+  about arrow keys driving inspection focus.
+- `/docs/charts/accessibility-and-ssr` (`ssr-output`) — confirmed in
+  `controller.ts` (`requireCanvas(host, "plot-canvas-chrome" |
+"-marks" | "-overlay")`) that hydration mounts three canvases (chrome,
+  marks, overlay), not the two the page described. Fixed.
+
+None of these needed a `status` downgrade — they're wrong details on real,
+shipped things, not missing capability. Combined with the earlier pass,
+every item flagged by the six original audit agents has now been either
+fixed or explicitly reasoned through and left as-is with a stated reason
+(see "Unverified," below, for the small remainder that's genuinely open).
+
+**Unrelated finding during this pass:** one of the six original read-only
+audit agents ignored its "do NOT edit any files" instruction and created a
+top-level `AGENTS.md` file in this repo. It wasn't part of any requested
+deliverable, so I deleted it rather than let it ship as an unreviewed
+side effect.
+
+## Unverified
+
+- `/docs/server/probes` (`readiness`) — the readyz/startupz semantic split
+  is presented as app-author convention, which the source supports
+  (`askr-server/src/dispatch.ts` dispatches all four probes identically) —
+  I judged the existing wording already frames this correctly and made no
+  change, but flagging that the underlying claim rests on absence-of-enforcement
+  rather than a positive guarantee.
+- `/docs/guides/build-an-mcp-server` — "signal cancellation actually aborts
+  the underlying work" was not traced to individual tool-dispatch code;
+  plausible but not directly confirmed.
+- A handful of "middleware executes outward in declaration order"-style
+  claims in `/docs/http-contracts/client-middleware` and
+  `/docs/guides/api-integration-and-error-handling` — the composition
+  function itself wasn't traced line-by-line; the behavior is standard for
+  this kind of middleware array and consistent with how it's used elsewhere,
+  but I'm not marking it independently confirmed.
+
+## Verification of the edits themselves
+
+- `npx tsc --noEmit` — clean after both passes (found and fixed two
+  string-escaping syntax errors during the first pass, and one dropped
+  object key — an `api:` prefix accidentally deleted during an edit —
+  during the second; all three resolved and reverified clean).
+- `npx vitest run tests/docs-catalog.test.ts tests/package-snapshot-contract.test.ts tests/llm-docs.test.ts`
+  — all pass, reverified after the second pass too.
+- `npm run lint` — clean, both passes.
+- Full `vitest run` has one expected failure in
+  `tests/generated-output-contract.test.ts`, which diffs the _built_
+  `dist/llms-full.txt` against current source — that's comparing against a
+  stale pre-edit build artifact, not a regression; it will pass again after
+  the next `npm run build`. I did not run a full production build as part
+  of this pass since the instruction was to leave everything uncommitted
+  for review, not to publish.
diff --git a/public/llms.txt b/public/llms.txt
index f76d3f0..93d5fe5 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -1,6 +1,8 @@
 # Askr
 
-> Askr is a full-stack TypeScript framework with explicit route registries, reactive state, accessible UI, server APIs, and shared SPA, SSR, hydration, and static-generation primitives.
+> Askr is an opinionated, batteries-included TypeScript framework for building applications that stay understandable — to the human who owns them and the agent that edits them — as both keep changing the code. Routes, rendering mode, server boundaries, and data ownership are explicit registries and typed contracts you read end to end, not conventions you infer from file placement.
+
+That legibility is the actual value prop, not raw performance or ecosystem size: a state update re-runs the owning component and reconciles its output (a traceable "this function ran, this output changed" story you can follow without holding a dependency graph in your head), runtime misuse is caught with an error that names what broke and how to fix it, and a documented surface that ships narrower than it reads is marked `experimental` or `limited` rather than left ambiguous. Askr is not chasing Solid's fine-grained-reactivity performance or React's ecosystem flexibility — don't describe it in either vocabulary. If you are an agent building with Askr: prefer the explicit primitive over a clever shortcut, read a page's status marker before depending on what it describes, and when a familiar-framework assumption (from React, Next.js, or anywhere else) would fill a gap in what you just read, treat that as a sign to go verify the actual behavior rather than carry the assumption over.
 
 Use the documentation links below as the primary source for Askr APIs and usage. Each documentation link is clean Markdown; its human-facing HTML page is the enclosing directory URL. Askr packages use the `@askrjs/*` npm scope, and the command-line tool is invoked as `askr`.
 
@@ -20,6 +22,15 @@ Use the documentation links below as the primary source for Askr APIs and usage.
 - [Tooling](https://askrjs.com/docs/tooling/index.md): CLI workflows for creating, analyzing, generating, checking, and upgrading projects.
 - [API reference](https://askrjs.com/docs/reference/index.md): Package entry points, exported APIs, CLI reference, and release notes.
 
+## Deliver excellent developer experience
+
+The docs treat "it works" and "it's ready to ship" as different bars — these pages are where the second bar is spelled out explicitly, not left implicit in example code.
+
+- [Guides: production finish bar](https://askrjs.com/docs/guides/index.md): The checklist every task-oriented guide ends on — error boundaries around what can fail, mutations invalidating the right query keys, auth-gated routes marked runtime-only, `askr openapi --check` passing in CI.
+- [Production readiness](https://askrjs.com/docs/guides/production-readiness/index.md): Wiring `onError`, health probes, and OpenTelemetry so a broken deploy fails loudly instead of serving errors quietly.
+- [Accessibility](https://askrjs.com/docs/guides/accessibility/index.md): Using `@askrjs/ui`'s typed `*_A11Y_CONTRACT` exports to verify keyboard behavior, focus handling, and ARIA roles instead of trusting a component's look.
+- [Determinism and runtime rules](https://askrjs.com/docs/core-concepts/determinism/index.md): The render-purity, hook-order, and no-mutation-during-render rules the runtime enforces with a specific thrown error, not silent misbehavior.
+
 ## Platform overview
 
 - [Platform](https://askrjs.com/platform): How the runtime, router, UI, server, rendering, and tooling fit together.
diff --git a/src/pages/docs/catalog.ts b/src/pages/docs/catalog.ts
index b7d6e5d..9d1632b 100644
--- a/src/pages/docs/catalog.ts
+++ b/src/pages/docs/catalog.ts
@@ -393,6 +393,14 @@ const routing = sectionPages('Routing & Data', 'Routing', 'routing', [
   },
   {
     title: 'Route Metadata',
+    // resolveRouteMeta/serializeRouteMeta/reconcileRouteMeta are real,
+    // working functions, but they're only ever called from the router's
+    // client-side navigation path — nothing in @askrjs/askr/ssr or
+    // @askrjs/askr/ssg calls them, so there's no automatic wiring of
+    // RouteMeta into a server-rendered or statically generated <head>.
+    // That's a real gap between what the primitives can do and what SSR/SSG
+    // do with them automatically, not just a docs omission.
+    status: 'limited',
     headings: [
       'Static metadata',
       'Dynamic metadata',
@@ -1086,7 +1094,16 @@ const dataLayout = componentPages('Data and layout', [
     themes: ['typography'],
   },
   { title: 'Application Layout', ui: [], themes: [] },
-  { title: 'Advanced Layout', ui: [], themes: [] },
+  {
+    title: 'Advanced Layout',
+    // SidebarScope is a pure styling wrapper — it carries no open/closed/rail
+    // state of its own. State management for these patterns is entirely the
+    // consuming application's responsibility, not something this package
+    // coordinates.
+    status: 'limited',
+    ui: [],
+    themes: [],
+  },
 ]);
 const feedback = componentPages('Disclosure and feedback', [
   {
@@ -1099,7 +1116,18 @@ const feedback = componentPages('Disclosure and feedback', [
     ui: ['progress', 'progress-circle'],
     themes: ['progress'],
   },
-  { title: 'Toast and Sonner', ui: ['toast'], themes: ['toast', 'sonner'] },
+  {
+    title: 'Toast and Sonner',
+    // Toast (from @askrjs/ui) is a real, working headless primitive. Sonner
+    // (themes/sonner, aliasing Toaster) is not a queueing/stacking/dismiss
+    // notifier system the way shadcn's sonner or the original Sonner library
+    // is — it's a bare presentational div wrapper with no imperative toast()
+    // API, timing, or stacking logic of its own. Don't let the shared name
+    // imply parity with those.
+    status: 'limited',
+    ui: ['toast'],
+    themes: ['toast', 'sonner'],
+  },
   {
     // Stat (Stat/StatLabel/StatValue/StatDescription) IS a real export, but
     // unlike its siblings on this page it has no dedicated subpath — it's
diff --git a/src/pages/docs/content-overrides.ts b/src/pages/docs/content-overrides.ts
index fedd190..7f5de41 100644
--- a/src/pages/docs/content-overrides.ts
+++ b/src/pages/docs/content-overrides.ts
@@ -18,7 +18,7 @@ export const headingOverrides: Readonly<
     'browser-and-api-clients':
       "Because AuthOptions can hold both a sessionCookie-based session lookup and a jwt or jwtCookie validator at the same time, one createAuth() call can serve cookie-carrying browsers and bearer-token API clients without standing up two separate resolvers. @askrjs/server exposes the resolved value as ctx.auth on every request, so route code written against ctx.auth.principal doesn't need to know which path produced it. That's also what lets the same requirePermission()/requireUser() checks apply uniformly to both kinds of caller.",
     'failure-behavior':
-      "A lookup that fails to identify anyone resolves to authenticated: false with principal and session set to null rather than throwing, so handlers can inspect ctx.auth without try/catch. Turning that into an actual accept/reject decision is the job of the requirement functions covered under Authorization Requirements, which map it to an AuthDecision of {allowed: false, reason: 'unauthenticated' | 'forbidden' | 'already_authenticated'}. Malformed tokens are the one case that does throw, surfacing as a JwtValidationError from the JWT validator rather than silently falling through to an anonymous context.",
+      "A lookup that fails to identify anyone resolves to authenticated: false with principal and session set to null rather than throwing, so handlers can inspect ctx.auth without try/catch. Turning that into an actual accept/reject decision is the job of the requirement functions covered under Authorization Requirements, which map it to an AuthDecision of {allowed: false, reason: 'unauthenticated' | 'forbidden' | 'already_authenticated'}. A malformed bearer-header JWT does throw, surfacing as a JwtValidationError from the JWT validator — but a malformed JWT cookie is caught internally and resolution falls through to an anonymous context instead, so the two malformed-token paths don't behave the same way.",
     'identity-model':
       "A Principal (id, subject?, roles?, permissions?) and an AuthSession (id, subject, expiresAt?, revokedAt?) are separate types in @askrjs/auth, both extending a Claim base of Record<string, unknown> so you can attach whatever custom fields your provider sends. createAuth(options) builds an AuthResolver whose resolve(request) returns one AuthContext per request, bundling authenticated, principal, session, tenant, and an optional scopes list into a single object. Route handlers and requirement functions both read from that same AuthContext, so there's one shape to reason about regardless of how the principal was established.",
     'session-boundary':
@@ -36,17 +36,17 @@ export const headingOverrides: Readonly<
   },
   '/docs/authentication/framework-routes': {
     'auth-v1-contract':
-      "registerAuthRoutes(api, options) from @askrjs/server/auth attaches register, login, session, and logout endpoints onto an ApiDefinition group you create yourself with api.group(...). The package doesn't hardcode a path prefix - the /auth/v1 naming used throughout this guide is just the mount point convention, not something baked into registerAuthRoutes.",
+      "registerAuthRoutes(api, options) from @askrjs/server/auth attaches register, login, session, and logout endpoints. It mounts them under a fixed /auth/v1 group it creates internally by calling api.group('/auth/v1') itself - the prefix used throughout this guide is not a convention you're choosing, it's what the function does.",
     'login-and-callback':
       'AuthRouteOptions.register(context, credentials) and authenticate(context, credentials) are functions you supply to create or verify a Principal from an AuthCredentials {email, password} pair - registerAuthRoutes calls whichever matches the route being hit. allowAttempt(context, operation, normalizedEmail) runs before either of them, letting you reject or throttle repeated attempts against the same address before register or authenticate ever executes.',
     'safe-redirects':
-      "safeRedirect(fallback, options?: {allowHash?}) returns a validator function that only accepts same-origin redirect targets, falling back to the given default for anything it doesn't recognize as safe - use it on a redirect or next query parameter before honoring it, since forwarding an unvalidated one is an open-redirect vulnerability. Other failures in the flow - a duplicate email on register, or a throttled attempt from allowAttempt - surface as an AuthRouteError with a fixed status of 401, 409, or 429 rather than a generic error.",
+      "safeRedirect(fallback, options?: {allowHash?}) returns a validator function that only accepts same-origin redirect targets, falling back to the given default for anything it doesn't recognize as safe - use it on a redirect or next query parameter before honoring it, since forwarding an unvalidated one is an open-redirect vulnerability. A duplicate email on register or a failed authenticate() call surfaces as an AuthRouteError with a fixed status of 401 or 409 rather than a generic error; a throttled attempt is a separate path - allowAttempt returning false short-circuits straight to a 429 response without going through AuthRouteError at all.",
     'session-and-logout':
       'On a successful register or authenticate, options.issuer.issue(principal) - a TokenIssuer<P> you provide - produces the token that gets written to the cookie described by options.cookie (standard CookieOptions plus a name). An optional redirect(context, operation, principal) callback can return a URL to send the client to instead of a bare JSON response, which is how the built-in routes support both API and browser-form flows from the same registration.',
   },
   '/docs/authentication/jwt': {
     'claims-and-clocks':
-      "JwtValidatorOptions requires issuer and jwks; audience is optional and can be a single string or a list of accepted values. clock defaults to Date.now but can be overridden - useful for tests - and clockSkewSeconds gives exp/nbf checks tolerance for clock drift between services. OidcIdTokenOptions reuses this exact shape and adds a required nonce, which is what validateOidcIdToken() checks the ID token's nonce claim against to catch replay.",
+      "JwtValidatorOptions requires issuer and jwks; audience is optional and can be a single string or a list of accepted values. clock defaults to () => Math.floor(Date.now() / 1000) - Unix seconds, matching the exp/nbf claims it's compared against - and can be overridden for tests; clockSkewSeconds gives those checks tolerance for clock drift between services. (This is a different clock than AuthOptions.clock on the session-resolution side, which is plain milliseconds - don't assume the two are interchangeable.) OidcIdTokenOptions reuses this exact shape and adds a required nonce, which is what validateOidcIdToken() checks the ID token's nonce claim against to catch replay.",
     'failure-handling':
       "Validation failures throw a JwtValidationError carrying a typed code - malformed_token, unsupported_algorithm, unknown_key, invalid_signature, or invalid_claim - so calling code can tell a garbled client token apart from a JWKS endpoint that's missing the key it needs. createJwtIssuer(options: JwtIssuerOptions) is the write side: give it privateKey, kid, issuer, audience, and ttlSeconds, and the returned JwtIssuer exposes issue(principal) to sign tokens plus a validator property already configured to check tokens it issued.",
     'key-selection':
@@ -62,13 +62,13 @@ export const headingOverrides: Readonly<
     'session-storage':
       "SessionStore<S> has exactly one method to implement: get(id, {request, signal}), returning S | null synchronously or as a promise. You pass it in as AuthOptions.sessions, and createAuth calls it during resolve() with the id it pulls from the configured sessionCookie. There's no built-in in-memory or database-backed implementation shipped with @askrjs/auth - you own storage, TTL, and any indexing it needs.",
     'sign-out-and-expiry':
-      "AuthSession carries optional expiresAt and revokedAt timestamps, which you compare against AuthOptions.clock() (Date.now by default, overridable for tests) when deciding whether a stored session is still good. There's no built-in expiry enforcement inside createAuth beyond what your SessionStore.get() implements - if it returns a session that's already past expiresAt, the resolver will still treat it as valid unless your store filters it out itself. Sign-out is likewise entirely your store's responsibility: mark the row revoked or delete it, and the next get() for that id should return null so resolve() falls back to an unauthenticated context.",
+      "AuthSession carries optional expiresAt and revokedAt timestamps. createAuth checks both itself, against AuthOptions.clock() (Date.now by default, overridable for tests), before treating a returned session as authenticated - a session your SessionStore.get() hands back past its expiresAt or with revokedAt set is rejected by the resolver even if the store still returns it. Your store only needs to return null for sessions it wants gone entirely (rotated out, deleted); it doesn't have to filter on expiry or revocation itself, though there's nothing stopping it from doing that too. Sign-out is your store's responsibility: mark the row revoked or delete it, and the next get() for that id should return null (or an already-expired/revoked session, which resolve() will now also reject on its own) so resolve() falls back to an unauthenticated context.",
   },
   '/docs/authentication/oidc': {
     'authorization-flow':
       "createAuthorizationRequest(options?: {state?, nonce?, codeVerifier?, loginHint?}) builds the redirect URL for the provider's authorization endpoint and returns it alongside the state, nonce, and PKCE codeVerifier it used - generating any of the three for you if you don't supply them. The caller's only job is to persist those values (typically in a short-lived cookie) so they're available when the browser comes back to the callback route.",
     'callback-validation':
-      "Once the browser returns with a code, exchangeCode({code, state, request: {state, nonce, codeVerifier}}) posts to the provider's token endpoint and resolves to an OidcTokenResponse with access_token, token_type, and optionally id_token, refresh_token, and expires_in. If an id_token comes back, pass it to validateOidcIdToken() from @askrjs/auth/jwt along with the nonce you stored earlier to confirm the token is both correctly signed and tied to this specific authorization request rather than a replayed one.",
+      "Once the browser returns with a code, exchangeCode({code, state, request: {state, nonce, codeVerifier}}) posts to the provider's token endpoint and resolves to { tokens, principal } - it already validates the ID token internally (signature, issuer, audience, and the nonce you stored earlier) as part of the exchange, rejecting with an OidcClientError('invalid-id-token', ...) if any of those checks fail. There's no separate validateOidcIdToken() call to make on this path; that function exists for validating an ID token you obtained some other way, not as a required second step after exchangeCode().",
     discovery:
       "createOidcClient(options: OidcClientOptions) takes issuer, clientId, an optional clientSecret, redirectUri, scopes, and an injectable fetch, and returns an OidcClient. Its discover() method fetches the provider's OidcProviderMetadata - authorization_endpoint, token_endpoint, jwks_uri, and the optional userinfo_endpoint and end_session_endpoint - so you don't hardcode those URLs per provider.",
     'session-establishment':
@@ -92,7 +92,7 @@ export const headingOverrides: Readonly<
     'motion-and-color':
       'Without JavaScript, users still get the semantic label, summary, legend, and instructions, just not the graphical marks or the on-demand table — so no essential information should live only in a tooltip or a canvas pixel. The renderer respects reduced-motion preferences by disabling nonessential transitions while still reflecting real state changes, and series color comes from theme tokens (`--ak-chart-series-1` through `--ak-chart-series-10`) rather than hardcoded values, so contrast follows whatever theme is active.',
     'ssr-output':
-      'Server rendering emits the reserved region, title, description, legend, summary, empty state, and keyboard/data instructions — but no graphical marks, since Canvas 2D has nothing to paint before hydration. After hydration, the root mounts a base canvas for the scene and a separate overlay canvas for transient interaction, and a "View data" control materializes the full transformed table on demand rather than duplicating every row into the initial document.',
+      'Server rendering emits the reserved region, title, description, legend, summary, empty state, and keyboard/data instructions — but no graphical marks, since Canvas 2D has nothing to paint before hydration. After hydration, the root mounts three separate canvases, not one: a chrome canvas (axes, grid, static decoration), a marks canvas (the actual data drawing), and an overlay canvas for transient interaction (crosshair, brush, hover) — kept apart so redrawing a hover state doesn\'t force repainting the whole scene. A "View data" control materializes the full transformed table on demand rather than duplicating every row into the initial document.',
   },
   '/docs/charts/cartesian-marks': {
     axes: 'Cartesian marks get default axes and tooltip behavior automatically; add explicit `Axis` children only when you need something different. `AxisProps` lets you pick which named `scale` to draw from, the `orient` (`top`, `right`, `bottom`, `left`), `tickCount`, a `tickFormat` function, and whether to draw the accompanying `grid` lines.',
@@ -109,7 +109,7 @@ export const headingOverrides: Readonly<
     channels:
       'A channel on any mark accepts a bare row-field name, an accessor `(row, index) => value`, or a channel expression — nothing else. Bare strings are always interpreted as field names, so a literal string value (a fixed color, a fixed label) has to be wrapped in `constant("...")` or it will be read as a field lookup instead. Accessors can derive values inline, as in `y={(row) => row.value / 1_000}`.',
     'row-lineage':
-      "Mark-level `transform` runs before layout and never mutates the source rows — `filterRows(predicate)`, `sortRows({ by, direction? })`, and `partition({ id, parentId?, children?, value, padding? })` each produce a fresh, frozen row set when they change anything, or hand back the original array untouched when they don't. Because rendering is driven off this transformed output, stable row keys are what let selection, transitions, and live updates track a row across filtering, sorting, or re-partitioning.",
+      'Mark-level `transform` runs before layout and never mutates the source rows — `filterRows(predicate)`, `sortRows({ by, direction? })`, and `partition({ id, parentId?, children?, value, padding? })` each produce a fresh, frozen row set. That copy happens as soon as any transform is configured at all, not just when a transform actually changes something — a `filterRows` predicate that happens to keep every row still gets a newly allocated, frozen array back, not the original reference; only marks with no `transform` configured at all skip the copy and pass the original array through untouched. Because rendering is driven off this transformed output, stable row keys are what let selection, transitions, and live updates track a row across filtering, sorting, or re-partitioning.',
     'window-transforms':
       '`movingWindow(input, { window, operation?, partial? })` computes a rolling `sum`, `mean`, `min`, or `max` over a fixed row count, and `movingAverage(input, { window })` is the rolling-mean shorthand of the same helper. `regression(input, options?)` fits a linear trend either against row index or an explicit x channel. All three skip missing numeric values rather than treating them as zero, which keeps trend lines honest over sparse data.',
   },
@@ -139,7 +139,7 @@ export const headingOverrides: Readonly<
       '`Crosshair` draws an inspection guide along `x`, `y`, or `xy` that tracks pointer or keyboard focus without changing the underlying view or selection state. It shares the same hit-testing records as tooltip and keyboard navigation, so whatever a viewer inspects with the mouse is exactly what arrow-key navigation lands on.',
     selections:
       "`PlotSelection` is just `{ keys: readonly (string | number)[] }`, tracked against each row's stable `rowKey` rather than its position — so a selection survives sorting, filtering, or new rows arriving. Use `defaultSelection` for local, uncontrolled state, or `selection` plus `onSelectionChange` when a route or sibling component needs to drive it. With brushing enabled, Shift+Space toggles the currently focused row into the selection from the keyboard.",
-    zoom: '`Zoom` enables `wheel`, `pinch`, and `pan` independently across the chosen `axes` (`x`, `y`, or `xy`), with `min`/`max` bounding how far the viewer can zoom. Wheel and pinch scale the enabled axes directly; a plain drag pans when `pan` is on. Keyboard users get the same control through plus/minus to zoom, arrow keys to pan, and Home to reset the view.',
+    zoom: "`Zoom` enables `wheel`, `pinch`, and `pan` independently across the chosen `axes` (`x`, `y`, or `xy`), with `min`/`max` bounding how far the viewer can zoom. Wheel and pinch scale the enabled axes directly; a plain drag pans when `pan` is on. Keyboard users get `+`/`-` to zoom and `Home` to reset the view — but plain arrow keys move mark focus (the same navigation Crosshair tracks), not the pan; panning needs `Shift`+arrow specifically, so a plain arrow press won't move the view even with `pan` enabled.",
   },
   '/docs/charts/live-and-view-state': {
     'append-and-upsert':
@@ -228,7 +228,7 @@ export const headingOverrides: Readonly<
     'edge-cases':
       "A `collapsible=\"none\"` sidebar ignores `SidebarTrigger` entirely from a visual standpoint, so don't render a trigger for a sidebar that isn't meant to collapse — it'll be misleading UI. Deeply nested `SidebarGroup`s inside `SidebarGroup`s aren't part of the documented shape; keep groups to one level and use `SidebarMenu`/`SidebarMenuItem` for the actual hierarchy of links within a group.",
     'install-and-import':
-      '`Sidebar`, `SidebarContent`, `SidebarHeader`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupContent`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarMenuAction`, `SidebarMenuBadge`, `SidebarRail`, `SidebarScope`, `SidebarInset`, and `SidebarTrigger` all come from `@askrjs/themes/sidebar` (also available through the `@askrjs/themes/components` barrel). Combine them with `Block`, `Header`, and `Main` from `@askrjs/themes/core` for the surrounding shell.',
+      "`Sidebar`, `SidebarContent`, `SidebarHeader`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupContent`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarMenuAction`, `SidebarMenuBadge`, `SidebarRail`, `SidebarScope`, `SidebarInset`, and `SidebarTrigger` all come from `@askrjs/themes/sidebar` (also available through the `@askrjs/themes/components` barrel). Combine them with `Block`, `Header`, and `Main` from that same `@askrjs/themes/components` barrel for the surrounding shell — there is no separate `@askrjs/themes/core` subpath; that name doesn't exist in the package.",
     'keyboard-and-accessibility':
       '`SidebarMenuButton` and `SidebarTrigger` accept `tooltip` and `tooltipSide` props, which matter most in the collapsed icon-rail state where the label text is hidden — always set a `tooltip` so icon-only buttons still communicate their purpose to sighted users and, indirectly, screen reader users relying on the accessible name. As with any nav structure, keep `SidebarMenuButton` rendered as real buttons or links rather than divs with click handlers, so keyboard and screen reader navigation work without extra effort.',
     'live-examples':
@@ -238,14 +238,14 @@ export const headingOverrides: Readonly<
     'related-pages':
       "Application Layout covers the simpler header-and-main shell this page builds on top of. NavigationMenu and Navbar are worth comparing for top-nav-driven apps that don't need a persistent side panel. Item and ItemGroup are a reasonable alternative to `SidebarMenu` when you need list rows that aren't specifically navigation.",
     'state-model':
-      'Collapse state lives with `SidebarScope`, which coordinates open/closed and (on `variant="icon"`) expanded/rail state across the `Sidebar` and its `SidebarTrigger` — you don\'t need to track that boolean yourself. Individual `SidebarMenuButton`s and `SidebarMenuAction`s take an `active?: boolean` prop for marking the current route, which is a value you compute from your router, not something the component derives on its own.',
+      "`SidebarScope` is a pure styling/CSS-boundary wrapper — it renders a plain part with no state of its own. It does **not** coordinate open/closed or rail-expanded state across `Sidebar` and `SidebarTrigger`; there's no built-in mechanism tracking that. You own collapse state yourself (a `state()` cell, driven by clicking `SidebarTrigger`, controlling whatever prop or class toggles the collapsed styling) the same way you would with any other composable primitive here — don't assume wrapping things in `SidebarScope` gets you that behavior for free. Individual `SidebarMenuButton`s and `SidebarMenuAction`s take an `active?: boolean` prop for marking the current route, which is a value you compute from your router, not something the component derives on its own.",
     'styling-and-tokens':
       "The `variant` prop's three values — `sidebar`, `floating`, `inset` — control fairly different visual treatments (attached, elevated-and-detached, or content-inset), and switching between them is a token-driven style change rather than a structural one. `SidebarMenuButton`'s `size` (`'default' | 'sm' | 'lg'`) and `variant` (`'default' | 'outline'`) follow the same density and variant conventions as `Button`, so a sidebar built from these components looks native next to the rest of the theme rather than like a separate design language.",
   },
   '/docs/components/alert-badge-empty-skeleton-spinner-and-stat': {
     anatomy:
-      "Alert is a single component with `icon`, `title`, `description`, and `actions` slots plus a `titleAs` heading tag; Badge and Skeleton are similarly flat, single components with no compound parts. Empty is the exception — it's compound, with EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, and EmptyContent slotting into an EmptyState wrapper, closer in shape to Card than to Alert or Badge. Spinner has no compound structure either; it's a themed wrapper around ProgressCircle's indeterminate presentation. Stat is compound too: a `Stat` wrapper composes with `StatLabel`, `StatValue`, and `StatDescription` children.",
-    api: "Badge supports `asChild` to render as something other than a `span`, and Skeleton supports the same pattern for its wrapping `div`. Alert's props are `title`, `description`, `icon`, `actions`, `titleAs`, `dismissLabel`, `onDismiss`, and `variant`; EmptyState's are `icon`, `title`, `titleAs`, `description`, and `action`.",
+      "Alert is a single component with `icon`, `title`, `description`, and `actions` slots plus a `titleAs` heading tag; Badge and Skeleton are similarly flat, single components with no compound parts. This group actually ships two different empty-state components, not one — don't conflate them: `Empty` is the compound one, with `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, and `EmptyContent` slotting into an `Empty` wrapper (closer in shape to Card than to Alert or Badge), while `EmptyState` is a separate, single all-in-one component (`icon`/`title`/`titleAs`/`description`/`action` props, no compound parts of its own) for the common case where you don't need to hand-assemble the pieces. Spinner has no compound structure either; it's a themed wrapper around ProgressCircle's indeterminate presentation. Stat is compound too: a `Stat` wrapper composes with `StatLabel`, `StatValue`, and `StatDescription` children.",
+    api: "Badge supports `asChild` to render as something other than a `span`, and Skeleton supports the same pattern for its wrapping `div`. Alert's props are `title`, `description`, `icon`, `actions`, `titleAs`, `dismissLabel`, `onDismiss`, and `variant`. `EmptyState` (the single all-in-one component, not the compound `Empty`/`EmptyHeader`/`EmptyMedia`/`EmptyTitle`/`EmptyDescription`/`EmptyContent` family) takes `icon`, `title`, `titleAs`, `description`, and `action`.",
     'edge-cases':
       "Stat has no dedicated subpath, so a `@askrjs/themes/stat` import will fail — reach for `@askrjs/themes/components` instead, which is easy to miss if you're used to every other component here having its own subpath. Skeleton has no built-in timeout, so pair it with the real loading/error state next to it instead of letting it sit on screen indefinitely if a request stalls.",
     'install-and-import':
@@ -265,14 +265,14 @@ export const headingOverrides: Readonly<
   },
   '/docs/components/alert-dialog': {
     anatomy:
-      '`AlertDialogContent` is a dedicated component (not a Dialog re-export) that renders with `role="alertdialog"` baked in rather than the default `dialog` role. Everything else in the tree — trigger, portal, overlay, title, description — is Dialog\'s implementation reused as-is under an alert-dialog-flavored name, since the underlying interaction pattern doesn\'t need to differ.',
+      '`AlertDialogContent` is a dedicated component, but it does not set `role="alertdialog"` for you — it renders through `DialogContent` with the same default role Dialog uses, so pass `role="alertdialog"` explicitly if you want that stronger semantic than plain `role="dialog"`. What `AlertDialogContent` and `AlertDialogTrigger` actually add over a straight Dialog re-export is behavioral, not role-related: the trigger guards against re-activation dismissing an already-open dialog, and the content wraps `onEscapeKeyDown`/`onPointerDownOutside` so outside pointer dismissal is blocked while Escape still works — reflecting the "confirm or explicitly cancel" pattern this component is for.',
     api: "`AlertDialogAction` and `AlertDialogCancel` are both just `DialogClose` — button-like components with `onPress`/`disabled`, no special props of their own beyond what Dialog's close button already supports. `AlertDialogContent` supports the same `forceMount`, `onEscapeKeyDown`, `onPointerDownOutside`, `onInteractOutside`, and `onDismiss` props as `DialogContent`; there's no alert-dialog-specific prop surface beyond the role.",
     'edge-cases':
       'Because `AlertDialogCancel` and `AlertDialogAction` are both plain close buttons under the hood, nothing stops you from wiring `onPress` on `AlertDialogCancel` to do something other than a no-op cancel — resist that, since it breaks the pattern users expect from this component. If the destructive action can fail, keep the dialog open and surface the error inside `AlertDialogContent` rather than letting `AlertDialogAction` close it optimistically.',
     'install-and-import':
-      "Import behavior from `@askrjs/ui/alert-dialog` and styling from `@askrjs/themes/alert-dialog`, both real subpaths. Under the hood most of the pieces — `AlertDialogOverlay`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogAction`, `AlertDialogCancel` — are just `Dialog`'s corresponding parts re-exported under alert-dialog names, so anything you already know about Dialog's props carries over directly.",
+      "Import behavior from `@askrjs/ui/alert-dialog` and styling from `@askrjs/themes/alert-dialog`, both real subpaths. `AlertDialogAction` and `AlertDialogCancel` really are `DialogClose` under alias names with no logic of their own, and `AlertDialogOverlay`/`AlertDialogTitle`/`AlertDialogDescription` pass straight through to Dialog's parts — but `AlertDialogTrigger` and `AlertDialogContent` aren't bare re-exports; both wrap the underlying Dialog part with alert-dialog-specific dismissal guarding, so don't assume every piece in this tree is a zero-logic alias just because most of them are.",
     'keyboard-and-accessibility':
-      'The a11y contract calls for both a primary action and a cancel action to be present — `ALERT_DIALOG_A11Y_CONTRACT.ACTION_REQUIREMENTS` flags both as required, so don\'t ship an alert dialog with only a single button. `role="alertdialog"` combined with `aria-labelledby`/`aria-describedby` tells assistive tech this is an interruption that needs an explicit response, which is stronger messaging than a plain dialog gives.',
+      'The a11y contract calls for both a primary action and a cancel action to be present — `ALERT_DIALOG_A11Y_CONTRACT.ACTION_REQUIREMENTS` flags both as required, so don\'t ship an alert dialog with only a single button. `aria-labelledby`/`aria-describedby` from `DialogTitle`/`DialogDescription` are wired up the same way Dialog does it, but `role="alertdialog"` is not applied automatically — the component defaults to Dialog\'s own role, so set `role="alertdialog"` on `AlertDialogContent` explicitly if you want assistive tech to treat it as an interruption needing an explicit response rather than a plain dialog.',
     'live-examples':
       "Structure mirrors Dialog: `AlertDialog` wraps an `AlertDialogTrigger` and a portal containing `AlertDialogContent`, `AlertDialogTitle`, and `AlertDialogDescription`. The part that's actually distinct is the footer — pair `AlertDialogCancel` with `AlertDialogAction` so there's always an explicit way to back out alongside the destructive action.",
     purpose:
@@ -282,7 +282,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "State is the same open/closed boolean as Dialog, since `AlertDialogProps` is literally `DialogProps` under a type alias — `open`, `defaultOpen`, and `onOpenChange` behave identically. The meaningful difference isn't in the state shape, it's in what the two footer actions are expected to do: `AlertDialogCancel` should always close without side effects, `AlertDialogAction` should perform the action and then close.",
     'styling-and-tokens':
-      'Because the overlay, content surface, and animations are shared with Dialog, alert dialogs pick up the same `--ak-color-backdrop`, `--ak-color-bg`, `--ak-color-border`, and z-index tokens out of the box. The theme layer adds its own `alert-dialog.css` on top mainly to style the action row — typically rendering `AlertDialogAction` with a destructive-leaning button variant and `AlertDialogCancel` as a plain secondary button.',
+      "Because the overlay, content surface, and animations are shared with Dialog, alert dialogs pick up the same `--ak-color-backdrop`, `--ak-color-surface-raised`, `--ak-color-border`, and z-index tokens out of the box. The theme layer's own `alert-dialog.css` is intentionally small — it only strengthens the content's border (`border-width: 1px` against `--ak-color-border`) on top of Dialog's shared styling; it doesn't add its own action-row layout or automatically apply a destructive variant to `AlertDialogAction` — pick that button variant yourself the same way you would on any other `Button`.",
   },
   '/docs/components/application-chrome': {
     anatomy:
@@ -310,7 +310,7 @@ export const headingOverrides: Readonly<
     'edge-cases':
       "Nesting many `Block`s with conflicting `width`/`height` values can produce layouts that don't collapse the way you expect on narrow screens — test at the documented widths (320, 390, 768, 1024, and desktop) rather than assuming a layout that looks right at one size holds at another. `sticky` combined with `zIndex` needs a value from the fixed `BlockZIndex` set (`header`, `sticky`, `fixed`, `dropdown`, `modal`, `popover`, `toast`, `tooltip`) rather than an arbitrary number, so pick the token that matches what the element actually is.",
     'install-and-import':
-      'Pull the pieces you need from `@askrjs/themes/core` or the broader `@askrjs/themes/components` barrel: `Block` for general-purpose flex layout, `Container` for width-constrained content, `Header` and `Main` for semantic page regions, and `Shell`/`ShellNav`/`ShellMain` when you want a pre-composed app frame instead of assembling `Block`s by hand.',
+      "Pull the pieces you need from the `@askrjs/themes/components` barrel (there is no separate `@askrjs/themes/core` subpath — that name isn't a real entrypoint in the package): `Block` for general-purpose flex layout, `Container` for width-constrained content, `Header` and `Main` for semantic page regions, and `Shell`/`ShellNav`/`ShellMain` when you want a pre-composed app frame instead of assembling `Block`s by hand.",
     'keyboard-and-accessibility':
       "Because `Header` and `Main` map to real landmark elements, screen reader users get correct page-region navigation for free as long as you don't override `as` to something non-semantic. Skip-link patterns and focus order are your responsibility to wire up at the app level — the layout primitives don't provide a built-in skip-to-content mechanism.",
     'live-examples':
@@ -327,9 +327,9 @@ export const headingOverrides: Readonly<
   '/docs/components/aria-and-ref-utilities': {
     anatomy:
       'Every polymorphic component ships two prop types — a native variant (e.g. `ButtonNativeProps`, with `asChild?: false` and a native `type` attribute) and an as-child variant (`ButtonAsChildProps`, with `asChild: true`, a required single-element `children`, and `type?: never`) — combined into one discriminated union. `VisuallyHidden` follows the exact same split: `VisuallyHiddenSpanProps` for the default `<span>` and `VisuallyHiddenAsChildProps` for rendering onto something else.',
-    api: "The shared `Ref<T>` type comes from `@askrjs/askr/foundations/utilities` and is used as `ref?: Ref<HTMLButtonElement>` (native branch) or `ref?: Ref<unknown>` (asChild branch, since the underlying element type isn't statically known). `JSXElement`, from `@askrjs/askr/foundations/structures`, types the single required child every `asChild` variant expects.",
+    api: "The shared `Ref<T>` type comes from `@askrjs/askr/foundations/utilities` and is used as `ref?: Ref<HTMLButtonElement>` (native branch) or `ref?: Ref<Element>` (asChild branch — narrower than the native branch's specific element type, but still the base DOM `Element` type, not `unknown`). `JSXElement`, from `@askrjs/askr/foundations/structures`, types the single required child every `asChild` variant expects.",
     'edge-cases':
-      "`asChild` requires exactly one child element — passing text, a fragment, or multiple children where a single element is expected will not compose correctly, since the component clones props onto that one element rather than wrapping a list. Because the asChild branch types `ref` as `Ref<unknown>`, you lose compile-time element-type checking on the ref target; that's a real trade-off of the polymorphism, not an oversight to work around.",
+      "`asChild` requires exactly one child element — passing text, a fragment, or multiple children where a single element is expected will not compose correctly, since the component clones props onto that one element rather than wrapping a list. Because the asChild branch types `ref` as the base `Ref<Element>` rather than the native branch's specific `Ref<HTMLButtonElement>`, you lose the specific-element-type checking on the ref target (methods/properties unique to the concrete element type won't be visible without a cast); that's a real trade-off of the polymorphism, not an oversight to work around.",
     'install-and-import':
       "`asChild` and `ref` aren't separately imported — they're just props defined on every component's prop union, e.g. `ButtonProps = ButtonNativeProps | ButtonAsChildProps`. `VisuallyHidden` is a normal component import: `import { VisuallyHidden } from '@askrjs/ui'`.",
     'keyboard-and-accessibility':
@@ -364,7 +364,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "Avatar tracks one real piece of state: `AvatarLoadingStatus`, typed as `'idle' | 'loading' | 'loaded' | 'error'`, exposed through `AvatarImage`'s `onLoadingStatusChange` callback so you can react to load failures yourself. Item's state is purely presentational — `active?: boolean` and `variant?: 'default' | 'outline' | 'muted'` control appearance, but Item doesn't manage selection or interaction state; if a row needs to respond to clicks or track selected-ness, that logic lives in your own component or in whatever interactive element you put inside it.",
     'styling-and-tokens':
-      "Both components mark their internal parts with `data-slot` hooks — `data-avatar`, `data-avatar-image`, `data-avatar-fallback` for Avatar per its `AVATAR_A11Y_CONTRACT` — which is the surface you should target with CSS rather than reaching into internal structure. Item's `size` prop (`'default' | 'sm' | 'xs'`) and `variant` prop map to token-driven density and background changes, consistent with the rest of the theme's `--ak-density-*` scale, so a compact `Item` list lines up visually with compact buttons and inputs elsewhere.",
+      "Both components mark their internal parts with `data-slot` hooks — `data-avatar`, `data-avatar-image`, `data-avatar-fallback` for Avatar per its `AVATAR_A11Y_CONTRACT` — which is the surface you should target with CSS rather than reaching into internal structure. Item's `size` prop (`'default' | 'sm' | 'xs'`) and `variant` prop map to `data-size`/`data-variant` attributes that drive gap, padding, and background changes off the theme's general `--ak-space-*` scale — not the separate `--ak-density-*` family, which is scoped to form-control sizing rather than list rows — so a compact `Item` list still lines up visually with the rest of the theme's spacing rhythm, just not through that specific token family.",
   },
   '/docs/components/breadcrumb-and-pagination': {
     anatomy:
@@ -392,7 +392,7 @@ export const headingOverrides: Readonly<
     'edge-cases':
       'Because Button defaults to type="button", a Button meant to submit a form has to be given type="submit" explicitly — this is deliberate, to stop buttons inside forms from submitting by accident. asChild requires exactly one child element; passing text or multiple children will not merge correctly since the props are applied directly to that single child. Long button labels wrap rather than overflow (the themed CSS sets white-space: normal and overflow-wrap: anywhere), so very long text grows the button vertically instead of clipping.',
     'install-and-import':
-      "@askrjs/ui and @askrjs/askr provide the headless Button; add @askrjs/themes on top if you want its default visual treatment out of the box. The headless primitive comes from `import { Button } from '@askrjs/ui/button'`, while `import { Button, ButtonGroup } from '@askrjs/themes/button'` (and `'@askrjs/themes/button-group'`) gives you the same component pre-wired to theme tokens. Because @askrjs/themes simply re-exports the @askrjs/ui Button rather than wrapping it, choosing one import path over the other only changes whether default CSS loads — behavior is identical either way.",
+      "@askrjs/ui and @askrjs/askr provide the headless Button; add @askrjs/themes on top if you want its default visual treatment out of the box. The headless primitive comes from `import { Button } from '@askrjs/ui/button'`; `@askrjs/themes/button` re-exports that same Button pre-wired to theme tokens, but it's Button only — ButtonGroup is a separate themed component with its own entrypoint, `import { ButtonGroup } from '@askrjs/themes/button-group'` (`@askrjs/themes/button` doesn't have it, so importing both names from one subpath fails). Because @askrjs/themes simply re-exports the @askrjs/ui Button rather than wrapping it, choosing one import path over the other only changes whether default CSS loads — behavior is identical either way.",
     'keyboard-and-accessibility':
       'Space and Enter both trigger activation through the pressable foundation rather than through any key handlers wired up inside Button itself, keeping behavior aligned with how WAI-ARIA defines the button pattern. Native <button> elements inherit keyboard behavior and focusability from the browser for free, while asChild targets get the same tabindex and ARIA-disabled handling applied by the foundation to non-native elements. Disabling a button removes it from the tab order — the native disabled attribute handles this for real buttons, and aria-disabled plus tabindex="-1" cover the asChild case.',
     'live-examples':
@@ -429,14 +429,14 @@ export const headingOverrides: Readonly<
   },
   '/docs/components/card': {
     anatomy:
-      "The parts map directly to DOM elements: `Card` renders a `div`, `CardTitle` renders an `h3`, and `CardDescription` renders a `p` — the rest (`CardHeader`, `CardContent`, `CardFooter`, `CardAction`) are `div`s. Nesting is flat and predictable: header parts go inside `CardHeader`, and everything else is a direct child of `Card`. There's no required order beyond what makes visual sense — you can omit any part you don't need.",
-    api: "`CardProps` extends native `div` props (minus `children` and `ref`, which are re-typed) with an optional `variant?: CardVariant` and forwards a `ref` to `HTMLDivElement`. `CardHeaderProps`, `CardContentProps`, and `CardFooterProps` are all plain `div`-prop wrappers with their own typed `ref`; `CardTitleProps` types its `ref` as `HTMLHeadingElement` and `CardDescriptionProps` as `HTMLParagraphElement`. None of these parts take special props beyond `children` and standard native attributes — `variant` is the only thing that isn't just passthrough.",
+      "The parts map directly to DOM elements: `Card` renders a `div`, `CardTitle` defaults to an `h3` (override the tag with `titleAs`, typed to `h1`-`h6`, when a card sits somewhere in the page's heading outline that isn't level 3), and `CardDescription` renders a `p` — the rest (`CardHeader`, `CardContent`, `CardFooter`, `CardAction`) are `div`s. Nesting is flat and predictable: header parts go inside `CardHeader`, and everything else is a direct child of `Card`. There's no required order beyond what makes visual sense — you can omit any part you don't need.",
+    api: "`CardProps` extends native `div` props (minus `children` and `ref`, which are re-typed) with an optional `variant?: CardVariant` and forwards a `ref` to `HTMLDivElement`. `CardHeaderProps`, `CardContentProps`, and `CardFooterProps` are all plain `div`-prop wrappers with their own typed `ref`; `CardTitleProps` types its `ref` as `HTMLHeadingElement` and `CardDescriptionProps` as `HTMLParagraphElement`. `CardTitle` is the one part with a real prop of its own beyond `variant`-style styling knobs: `titleAs?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'`, defaulting to `'h3'`, for correcting the heading level in context.",
     'edge-cases':
       "Because every part is just a styled native element, most \"edge cases\" are really just CSS: long titles will wrap by default rather than truncate, so add your own `text-overflow` handling if you need single-line titles. If a card's content can overflow (a long table or list inside `CardContent`), you're responsible for scroll containment — Card doesn't clip or scroll its children automatically. Empty cards render fine but will look sparse; pair with `EmptyState` from the same package if you need a real empty-content pattern.",
     'install-and-import':
       "Card ships from `@askrjs/themes/card`, which also gets pulled in through the broader `@askrjs/themes/components` barrel if you're already importing from there. Pull in `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, and `CardAction` as needed — you don't have to use every part on every card. There's nothing to install from `@askrjs/ui` for this one; `@askrjs/themes` is the whole story.",
     'keyboard-and-accessibility':
-      "Because Card is static markup, there's no keyboard interaction to account for and nothing to manage with focus or ARIA — accessibility here is about what you put inside it, not the container itself. Use `CardTitle`'s heading semantics correctly: keep heading levels consistent with the rest of the page since it always renders as `h3`. If a card as a whole is interactive (say, a clickable card), wrap it in a real button or link rather than adding a click handler to the div.",
+      "Because Card is static markup, there's no keyboard interaction to account for and nothing to manage with focus or ARIA — accessibility here is about what you put inside it, not the container itself. Use `CardTitle`'s heading semantics correctly: it defaults to `h3`, but override it with `titleAs` (`h1`-`h6`) so a card's title lines up with wherever it actually sits in the page's real heading outline, rather than leaving every card at `h3` regardless of context. If a card as a whole is interactive (say, a clickable card), wrap it in a real button or link rather than adding a click handler to the div.",
     'live-examples':
       'A minimal card is just `<Card><CardHeader><CardTitle>...</CardTitle></CardHeader><CardContent>...</CardContent></Card>` — three parts covers most real usage. Add `CardDescription` under the title for a subhead, and `CardFooter` for actions or metadata that should sit visually separate from the body. `CardAction` is meant for a control (a button, a menu trigger) placed inline with the header, like an overflow menu next to a title.',
     purpose:
@@ -446,7 +446,7 @@ export const headingOverrides: Readonly<
     'state-model':
       'Nothing about a Card is tracked internally by the component itself. `variant`, typed as `CardVariant` (`"default" | "raised"`), is the one prop that changes how it looks, toggling between a flat surface and an elevated one. Conditions like loading, selected, or disabled aren\'t modeled here at all — you express those yourself through conditional rendering or a wrapping data attribute.',
     'styling-and-tokens':
-      "Card follows the same public contract as the rest of the theme package: style the `data-slot` hooks and `--ak-*` tokens, not internal structure. The `raised` variant is driven by the shared shadow tokens, so if you're adjusting elevation across the app, change the token rather than overriding `box-shadow` directly on individual cards. Spacing inside `CardHeader`, `CardContent`, and `CardFooter` comes from the same density tokens used everywhere else in the theme, so cards stay visually consistent with buttons, inputs, and other surfaces without extra work.",
+      "Card follows the same public contract as the rest of the theme package: style the `data-slot` hooks and `--ak-*` tokens, not internal structure. The `raised` variant is driven by the shared shadow tokens, so if you're adjusting elevation across the app, change the token rather than overriding `box-shadow` directly on individual cards. Spacing inside `CardHeader`, `CardContent`, and `CardFooter` comes from the general `--ak-space-*` scale (`gap`/`padding` set to `--ak-space-6`), not the separate `--ak-density-*` family — density tokens are scoped to form-control sizing (`--ak-density-control-height-*`/`-padding-x-*`) and aren't what Card's own layout reads from.",
   },
   '/docs/components/checkbox': {
     anatomy:
@@ -612,7 +612,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "A dialog's open state is just a boolean, driven by `open`, `defaultOpen`, and `onOpenChange` on the root `Dialog` component. `modal` controls whether interaction with the rest of the page is blocked while it's open — leave it on unless you have a specific reason to allow background interaction. There's no separate loading or error state baked in; anything beyond open/closed is left to whatever you render inside `DialogContent`.",
     'styling-and-tokens':
-      'The default theme targets the dialog by its `data-slot` values — `dialog-overlay` and `dialog-content` — plus `data-state` for open/closed transitions, so you can override appearance with plain CSS selectors instead of prop soup. The overlay backdrop uses `--ak-color-backdrop` with a blur and sits at `--ak-z-modal-backdrop`, while the content surface sits above it at `--ak-z-modal` and reads `--ak-color-bg` and `--ak-color-border` for its surface and border. Open and close transitions animate opacity and scale using the shared `--ak-duration-fast` and `--ak-ease-standard` tokens.',
+      "The default theme targets the dialog by its `data-slot` values — `dialog-overlay` and `dialog-content` — plus `data-state` for open/closed transitions, so you can override appearance with plain CSS selectors instead of prop soup. The overlay backdrop uses `--ak-color-backdrop` with a blur and sits at `--ak-z-modal-backdrop`, while the content surface sits above it at `--ak-z-modal` and reads `--ak-color-surface-raised` (not the plain `--ak-color-bg` token — dialogs specifically use the raised-surface variant) for its background. The open and close transitions aren't symmetric: opening scales in over `--ak-duration-normal`, while closing scales out faster, over `--ak-duration-fast` — both share the same `--ak-ease-standard` easing, just different durations.",
   },
   '/docs/components/drawer-and-sheet': {
     anatomy:
@@ -659,7 +659,7 @@ export const headingOverrides: Readonly<
   '/docs/components/form-label-field-and-input-group': {
     anatomy:
       '`Form` is just a `<form>` (or, via `asChild`, whatever element you provide) with a `data-slot="form"` attribute — it doesn\'t intercept submission or manage field state. `Label` renders a native `<label>` by default. `Field` is a `<div>` that accepts an `invalid` flag and optionally contains `FieldHint`/`FieldError` paragraph children. `InputGroup` is a `<div>` that visually attaches its children (e.g. an input and a leading icon) via its `attached` prop.',
-    api: "`Form` takes only `children` plus standard `BoxProps<'form'>`. `Label` takes `children` and, in its non-`asChild` form, `htmlFor` plus the rest of native label props. `Field` takes `invalid` and native `div` props; `FieldHint` and `FieldError` take native paragraph props and are purely presentational — the error text itself is whatever you render as children. `InputGroup` takes `attached` and `orientation`; `InputGroupText` renders inline decorative or label text inside the group and supports `asChild` like most other parts in the library.",
+    api: "`Form` takes only `children` plus standard `BoxProps<'form'>`. `Label` takes `children` and, in its non-`asChild` form, `htmlFor` plus the rest of native label props. `Field` takes `invalid` and native `div` props; `FieldHint` and `FieldError` take native paragraph props — the error text itself is whatever you render as children, but `FieldError` isn't purely presentational the way `FieldHint` is: it renders with `role=\"alert\"` baked in, so its content gets announced to assistive tech as soon as it mounts. `InputGroup` takes `attached` and `orientation`; `InputGroupText` renders inline decorative or label text inside the group and supports `asChild` like most other parts in the library.",
     'edge-cases':
       "Because `Field`, `FieldHint`, `FieldError`, and `InputGroup` don't manage any state, there's no automatic wiring between `invalid` on `Field` and the appearance of `FieldError` — if you want the error message to only show when the field is invalid, that's a condition you write yourself in JSX. Note also that the broader `Field*` family you'll see in the styled catalog (`FieldContent`, `FieldGroup`, `FieldLegend`, `FieldSet`, `FieldTitle`, and so on) lives in `@askrjs/themes/components` as additional composition helpers beyond the core `Field`/`FieldHint`/`FieldError` trio documented here.",
     'install-and-import':
@@ -675,7 +675,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "None of these four hold state themselves — `Form` doesn't track field values, and `Field`'s `invalid` prop is something you pass in based on validation you're already running elsewhere, not something the component derives. This is intentional: form state and validation belong to whatever data layer or form library you're using, and these pieces only handle structure and semantics around it.",
     'styling-and-tokens':
-      '`Field` toggles an invalid visual treatment off its `invalid` boolean prop rather than a `data-state` string, so you can drive it directly from your validation result. `InputGroup` takes an `orientation` (`horizontal`/`vertical`) and an `attached` boolean that removes the gap and shared borders between grouped children, which is the look you want for a search box with a leading icon or a trailing button.',
+      "`Field`'s `invalid` boolean prop sets a real `data-invalid=\"true\"` attribute on the root — but the default theme's `field.css` has no rule keyed to `[data-invalid]`, so setting it doesn't change `Field`'s own appearance out of the box. It's there as a stable styling hook for your own CSS or a custom theme to key off, not a treatment `@askrjs/themes` ships pre-wired; any visible invalid state you see in practice comes from styling the control inside the field (e.g. Input's own `aria-invalid` border swap), not from `Field` itself. `InputGroup` takes an `orientation` (`horizontal`/`vertical`) and an `attached` boolean that removes the gap and shared borders between grouped children, which is the look you want for a search box with a leading icon or a trailing button.",
   },
   '/docs/components/headless-versus-themed': {
     anatomy:
@@ -703,11 +703,11 @@ export const headingOverrides: Readonly<
       "The tree is `HoverCard` > `HoverCardTrigger` and `HoverCardPortal` > `HoverCardContent` — deliberately the smallest of the overlay primitives, since it doesn't need an overlay backdrop, a title/description pair, or a close affordance the way Dialog and Alert Dialog do.",
     api: '`HoverCard` takes `open`, `defaultOpen`, `onOpenChange`, `openDelay`, and `closeDelay`. `HoverCardContent` adds `forceMount`, `side`, `align`, and `sideOffset` on top of div props. `HoverCardTrigger` is button-like with `onPress`/`disabled`; note it renders as a real `<button>` by default even though the interaction is hover-driven, so give it `asChild` if you need to trigger from a link or inline text instead.',
     'edge-cases':
-      "Fast mouse movement across multiple triggers in a row can cause hover cards to flicker between open and closed if `closeDelay` is too short — bump it up when triggers are dense, like a list of avatars. Since there's no built-in focus trap, don't rely on Hover Card for anything the user needs to interact with beyond reading; if it needs a form or a button, that's a Popover's job.",
+      "Fast mouse movement across multiple triggers in a row can cause hover cards to flicker between open and closed if `closeDelay` is too short — bump it up when triggers are dense, like a list of avatars. There's no hard focus trap the way Dialog has one, so a `Tab` past the last focusable element inside the content is allowed to leave it rather than cycling back — that's a real gap for content the user needs to fully interact with (a form, a multi-step flow), but it's not the same as having no keyboard support at all: focus-driven open/close and Tab/Escape handling are real and wired up.",
     'install-and-import':
       "Import from `@askrjs/ui/hover-card` for behavior and `@askrjs/themes/hover-card` for the styled version; both are real subpaths in their packages. As with the other overlays, the pieces are also available from each package's root export.",
     'keyboard-and-accessibility':
-      "There's no dedicated a11y contract exported for Hover Card the way there is for Dialog and Popover — it's a hover-triggered convenience, not a primary interactive surface. Because keyboard and touch users can't hover, don't put anything in `HoverCardContent` that a user needs to complete their task; if the content matters, surface it through a click-triggered Popover as well.",
+      "There's no dedicated a11y contract exported for Hover Card the way there is for Dialog and Popover, but it isn't hover-only despite the name: focusing the trigger (via keyboard `Tab`) opens it the same as hovering does, Tab from an open trigger moves into the first focusable element inside `HoverCardContent`, Tab cycling inside the content is handled so it doesn't leak focus back to the page unexpectedly, and Escape returns focus to the trigger and closes it. What it genuinely lacks compared to Popover is a hard focus trap — so still avoid putting something the user *must* interact with in it, but \"keyboard users can't reach the content\" is not accurate; they can tab into it and back out cleanly.",
     'live-examples':
       "`HoverCard` wraps a `HoverCardTrigger` and a `HoverCardPortal` containing `HoverCardContent`; there's no separate close button component, since dismissal is driven by the pointer leaving rather than an explicit action. Tune `openDelay` and `closeDelay` on the root to avoid the card flickering open on quick mouse passes.",
     purpose:
@@ -766,7 +766,7 @@ export const headingOverrides: Readonly<
       'Each contract is a `declare const ..._A11Y_CONTRACT` frozen object with a matching type alias (`ButtonA11yContract`, `SwitchA11yContract`, etc.) derived via `typeof`, so you get autocomplete and type-checking against the literal values rather than a loosely typed record. Fields are grouped by concern — role, keyboard activation, disabled-state attributes, focus rules, and the `DATA_ATTRIBUTES` map of stable `data-*` hooks — and not every component populates every group, since not every component needs one.',
     api: "There's no single generic contract type — each component defines its own, e.g. `ButtonA11yContract`, `AccordionA11yContract`, `SwitchA11yContract`, `DismissableLayerA11yContract`, `FocusScopeA11yContract`. Import the constant when you want the actual values (for tests or docs generation) and the type when you only need to constrain a function parameter to 'something shaped like a contract'.",
     'edge-cases':
-      "Contracts describe intended behavior, not a runtime guarantee enforced by the library — nothing stops a consumer from overriding `role` or stripping a `data-*` attribute via passthrough props, so treat them as documentation-you-can-import rather than a validator. Some simpler components (Input, Textarea, Label) don't export a contract at all because they rely on native HTML semantics that don't need restating.",
+      "Contracts describe intended behavior, not a runtime guarantee enforced by the library — nothing stops a consumer from overriding `role` or stripping a `data-*` attribute via passthrough props, so treat them as documentation-you-can-import rather than a validator. Even the simplest components export one: `INPUT_A11Y_CONTRACT`, `TEXTAREA_A11Y_CONTRACT`, and `LABEL_A11Y_CONTRACT` all exist, alongside every other interactive component in the package — there's no tier of components that skips this.",
     'install-and-import':
       "Contracts are exported alongside their component from the same entrypoint, e.g. `import { Button, BUTTON_A11Y_CONTRACT } from '@askrjs/ui'` or from the per-component subpath `import { BUTTON_A11Y_CONTRACT } from '@askrjs/ui/button'`. You don't need them at runtime to use a component correctly — they're most useful for testing and for verifying your own asChild wrapper preserves the expected behavior.",
     'keyboard-and-accessibility':
@@ -778,7 +778,7 @@ export const headingOverrides: Readonly<
     'related-pages':
       'See ARIA and Ref Utilities for how these contracts relate to the `asChild` pattern and ref forwarding. See Focus and Dismissal for the two components — FocusScope and DismissableLayer — whose entire job is implementing one interaction policy each.',
     'state-model':
-      "The contracts themselves are static — they don't change at runtime and carry no component state. What varies at runtime is which branch of a contract applies: Button's `DISABLED_ATTRIBUTES.native` kicks in for a real `<button>`, while `DISABLED_ATTRIBUTES.asChild` (`aria-disabled` plus `tabindex=\"-1\"`) applies when `asChild` is set and the rendered element isn't natively disableable.",
+      "The contracts themselves are static — they don't change at runtime and carry no component state. What varies at runtime is which branch of a contract applies: Button's `DISABLED_ATTRIBUTES.native` (`'disabled'`) kicks in for a real `<button>`, while `DISABLED_ATTRIBUTES.asChild` (`'aria-disabled'`) applies when `asChild` is set and the rendered element isn't natively disableable — the constant itself only names that one attribute; the accompanying `tabindex=\"-1\"` on a disabled `asChild` element is separate behavior the component applies, not a second value bundled into `DISABLED_ATTRIBUTES.asChild`.",
     'styling-and-tokens':
       '`DATA_ATTRIBUTES` inside each contract is the styling-relevant part: it names the `data-slot`, `data-state`, and `data-disabled` (or similarly-purposed) attributes a component sets on its DOM output. `@askrjs/themes` selectors are written against exactly these attribute names, so if you build a custom theme, the contract tells you which hooks are guaranteed stable rather than incidental implementation detail.',
   },
@@ -848,7 +848,7 @@ export const headingOverrides: Readonly<
   '/docs/components/navbar-and-navigation-menu': {
     anatomy:
       '`NavigationMenu` renders a `<nav>`, `NavigationMenuList` an `<ul>`, and `NavigationMenuItem` an `<li>` — a plain nested list under the hood. `NavigationMenuTrigger` is a real `<button type="button">` (with the `nav-item` class baked in), while `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuViewport`, and `NavigationMenuIndicator` are generic slotted elements (a div, an anchor, a div, and a div respectively) that only exist to give you stable markup and `data-slot` hooks for the flyout panel, its links, the clipping viewport, and an active-tab indicator strip.',
-    api: 'All parts accept the shared `CatalogComponentProps` shape: `as` to render a different tag, `asChild` to hand rendering off to a `Slot` (useful for wrapping your router\'s `Link`), plus `class`, `children`, `ref`, and arbitrary passthrough attributes. `NavigationMenuTrigger` also accepts a `type` override, though it defaults to `"button"` so it never accidentally submits a form.',
+    api: '`NavigationMenu`, `NavigationMenuList`, and `NavigationMenuItem` accept the shared `CatalogComponentProps` shape, including `as` to render a different tag. `NavigationMenuTrigger` is built on the same internal button-part helper as the rest of the catalog\'s button-flavored components, and that helper accepts `asChild` but silently discards `as` — passing it has no effect, it always renders a real `<button>` unless you use `asChild`. `asChild` itself hands rendering off to a `Slot` (useful for wrapping your router\'s `Link`) on every part, plus `class`, `children`, `ref`, and arbitrary passthrough attributes are supported throughout. `NavigationMenuTrigger` also accepts a `type` override, though it defaults to `"button"` so it never accidentally submits a form.',
     'edge-cases':
       "Multi-level or mega-menu content is entirely on you to lay out inside `NavigationMenuContent` — there's no built-in positioning or collision handling in `NavigationMenuViewport`, it's just a slotted div. Since there's no shipped open state, SSR is trivially safe (everything renders closed/static by default), but that also means client hydration has to attach whatever interaction logic you add. If you need real click-outside dismissal or focus trapping for a flyout, reach for `@askrjs/ui`'s dropdown primitives rather than assuming this package provides it.",
     'install-and-import':
@@ -860,7 +860,7 @@ export const headingOverrides: Readonly<
     'related-pages':
       'See Sidebar and Menubar for the other two navigation-chrome building blocks, Application Chrome for how these fit into a full page shell, and Breadcrumb and Pagination for the smaller wayfinding controls that often sit alongside a nav bar.',
     'state-model':
-      "None of these components track open/closed state, active item, or hover intent — there's no internal store or context here at all. You decide which trigger's content is visible, typically with a bit of local state or by composing `NavigationMenuTrigger`/`NavigationMenuContent` with the interaction primitives from `@askrjs/ui` (the same way the themed `Navbar` wires its own collapse menu with `Dropdown`/`DropdownTrigger`). Treat this package as markup, not behavior.",
+      "None of these components track open/closed state, active item, or hover intent — there's no internal store or context here at all. You decide which trigger's content is visible, typically with a bit of local state or by composing `NavigationMenuTrigger`/`NavigationMenuContent` with the interaction primitives from `@askrjs/ui`. The themed `Navbar` gives you two different worked examples of that pattern, for two different jobs: its mobile hamburger collapse is built on `Collapsible`/`CollapsibleTrigger`/`CollapsibleContent`, while a per-item flyout (`NavDropdown`) is built on `Dropdown`/`DropdownTrigger`/`DropdownContent` — pick whichever matches what you're building rather than assuming one mechanism covers both. Treat this package as markup, not behavior.",
     'styling-and-tokens':
       'Every part carries a `data-slot` attribute — `navigation-menu`, `navigation-menu-list`, `navigation-menu-item`, `navigation-menu-trigger`, `navigation-menu-content`, `navigation-menu-link`, `navigation-menu-viewport`, `navigation-menu-indicator` — and the trigger additionally gets the `nav-item` class. Style off those hooks instead of assuming a fixed DOM shape, since `as`/`asChild` let consumers swap the underlying element.',
   },
@@ -873,7 +873,7 @@ export const headingOverrides: Readonly<
     'install-and-import':
       'Import behavior from `@askrjs/ui/popover` and the themed version from `@askrjs/themes/popover`. The root package re-exports the same set — `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverClose` — so use whichever import path fits your bundling setup.',
     'keyboard-and-accessibility':
-      '`PopoverContent` renders with `role="dialog"` and is labelled from the trigger by default, with `aria-labelledby`/`aria-label` as your override if the trigger\'s own text isn\'t descriptive enough. Focus is trapped inside the content while open and restored to the trigger on close, and it sits behind a dismissable layer so outside clicks and Escape close it the way users expect from any transient overlay.',
+      "`PopoverContent` renders with `role=\"dialog\"` and is labelled from the trigger by default, with `aria-labelledby`/`aria-label` as your override if the trigger's own text isn't descriptive enough. It uses `FocusScope` for focus management, but not in trapped mode — Tab can move focus back out to the rest of the page while the popover is open, unlike Dialog's hard trap; what it does give you is restoring focus to the trigger on close. It sits behind a dismissable layer so outside clicks and Escape close it the way users expect from any transient overlay.",
     'live-examples':
       '`Popover` wraps a `PopoverTrigger` and a `PopoverPortal` containing `PopoverContent`; put a `PopoverClose` inside the content if you want an explicit dismiss button rather than relying on outside-click. Pass `side` and `align` on `PopoverContent` to control which edge of the trigger it opens from and how it lines up against it.',
     purpose:
@@ -883,7 +883,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "Open state works exactly like Dialog's — `open`, `defaultOpen`, `onOpenChange` on the root — but there's no `modal` prop, because a popover never blocks the rest of the page by design. Positioning state (which side it actually rendered on, once it's flipped to avoid the viewport edge) is tracked internally and exposed through `data-side`/`data-align` attributes rather than anything you manage yourself.",
     'styling-and-tokens':
-      '`PopoverContent` accepts `side`, `align`, `sideOffset`, and a `width` of `sm`/`md`/`lg`, all of which show up as `data-side`/`data-align` attributes the default theme keys its positioning CSS off of. It sits at `--ak-z-popover` in the shared z-index scale, above dropdowns but below modals and tooltips.',
+      '`PopoverContent` accepts `side`, `align`, `sideOffset`, and a `width` of `sm`/`md`/`lg`, all of which show up as `data-side`/`data-align` attributes the default theme keys its positioning CSS off of. It sits at `--ak-z-popover` (`1500`) in the shared z-index scale — tied with `--ak-z-dropdown` at the same layer, above modals (`1400`) but below toast (`1550`) and tooltip (`1600`).',
   },
   '/docs/components/portals-and-layers': {
     anatomy:
@@ -904,7 +904,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "Portals hold no state of their own — `DialogPortal` returns `JSX.Element | null` depending entirely on whether the parent's `open` state says there's anything to render. There's nothing to track independently; a portal simply reflects whatever its owning component's state already is.",
     'styling-and-tokens':
-      'Stacking order across portaled layers is governed by a real, ordered `--ak-z-*` token ladder: `--ak-z-dropdown: 1000`, `--ak-z-sticky: 1100`, `--ak-z-fixed: 1200`, `--ak-z-modal-backdrop: 1300`, `--ak-z-modal: 1400`, `--ak-z-popover: 1500`, `--ak-z-toast: 1550`, and `--ak-z-tooltip: 1600`. Because every overlay family draws from this same ladder, a tooltip will always render above a popover, which will always render above a modal, without any manual z-index juggling in application code.',
+      "Stacking order across portaled layers is governed by a real, ordered `--ak-z-*` token ladder: `--ak-z-sticky: 1100`, `--ak-z-fixed: 1200`, `--ak-z-modal-backdrop: 1300`, `--ak-z-modal: 1400`, then `--ak-z-dropdown` and `--ak-z-popover` tied at `1500`, `--ak-z-toast: 1550`, and `--ak-z-tooltip: 1600` on top. Dropdown and popover intentionally share a layer rather than one sitting above the other — don't assume a fixed dropdown-under-popover ordering between those two specifically. Because every overlay family draws from this same ladder, a tooltip will always render above a modal, without any manual z-index juggling in application code.",
   },
   '/docs/components/progress': {
     anatomy:
@@ -953,19 +953,19 @@ export const headingOverrides: Readonly<
       "ScrollArea itself renders no DOM — it's a context provider that generates and shares related IDs (viewport, scrollbar, thumb, corner) across its children, and throws if any part is used outside a ScrollArea. ScrollAreaViewport renders the actual overflow: auto element that does the real scrolling; ScrollAreaScrollbar, ScrollAreaThumb, and ScrollAreaCorner are separate divs positioned by CSS, not children of the viewport itself.",
     api: "ScrollAreaProps takes just children and an optional id, used to derive the shared part IDs. ScrollAreaViewportProps, ScrollAreaScrollbarProps (which adds orientation?: 'vertical' | 'horizontal'), ScrollAreaThumbProps, and ScrollAreaCornerProps each extend the native div's props, so every part accepts ordinary HTML attributes plus asChild where the type allows it.",
     'edge-cases':
-      "Every part throws if rendered outside a ScrollArea, since they all read shared IDs from context — you can't reuse ScrollAreaViewport or ScrollAreaThumb standalone. Because ScrollAreaScrollbar and ScrollAreaThumb aren't functionally linked to the viewport's scroll position in the shipped CSS, don't rely on them as your only scroll indicator if precise progress feedback matters — the native thin scrollbar on the viewport is the part that actually reflects how far the user has scrolled.",
+      "Every part throws if rendered outside a ScrollArea, since they all read shared IDs from context — you can't reuse ScrollAreaViewport or ScrollAreaThumb standalone. ScrollAreaScrollbar and ScrollAreaThumb *are* functionally linked to the viewport's scroll position — a `ResizeObserver` plus a scroll listener keep `aria-valuenow` and a `data-state` (`visible`/`hidden`) attribute in sync on every scroll and resize — so it's safe to rely on them as a real scroll indicator, not just a decorative accent.",
     'install-and-import':
       'Import ScrollArea, ScrollAreaViewport, ScrollAreaScrollbar, ScrollAreaThumb, and ScrollAreaCorner from @askrjs/ui/scroll-area, or the same five names pre-styled from @askrjs/themes/scroll-area, which re-exports the ui components as-is and depends entirely on CSS for appearance. Load @askrjs/themes/default for the actual visuals — the components alone only supply structure and shared IDs, no styling.',
     'keyboard-and-accessibility':
-      'Because ScrollAreaViewport is a genuinely scrollable element, arrow keys, Page Up/Down, Home/End, and wheel scrolling all work through native browser behavior once the viewport or its content is focusable — nothing custom is layered on top. ScrollAreaScrollbar and ScrollAreaCorner are marked aria-hidden="true", since they\'re decorative visual elements sitting alongside the real scrollable region rather than a custom scrollbar widget assistive tech needs to know about.',
+      'ScrollAreaViewport is a genuinely scrollable element (`role="region"`, `tabIndex={0}`), so native wheel scrolling and focus-then-arrow-key behavior work there too. But `ScrollAreaScrollbar` is not just a decorative accent alongside it — it renders with `role="scrollbar"`, `aria-controls` pointing at the viewport, `aria-orientation`, and `aria-valuemin`/`aria-valuemax`/`aria-valuenow` kept in sync via a `ResizeObserver` and scroll listener, and it has its own `onKeyDown` handling Arrow/Page Up/Page Down/Home/End that calls back into the viewport\'s actual `scrollTop`/`scrollLeft` — a real, working custom scrollbar widget, not an `aria-hidden` decoration. It only becomes focusable (`tabIndex={0}`) when the content actually overflows.',
     'live-examples':
       "A typical instance is ScrollArea wrapping a ScrollAreaViewport that holds your scrollable content, alongside a ScrollAreaScrollbar containing a ScrollAreaThumb, with an optional ScrollAreaCorner when both axes scroll. It's the shape you'd reach for around a tall settings panel, a chat sidebar, or any fixed-height region where you want scrolling to feel consistent with the theme's tokens rather than the raw OS scrollbar.",
     'related-pages':
       "See Virtual List and Virtual Table if what you actually need is windowed rendering for a large dataset rather than just a styled scroll region. See Table for content commonly placed inside a Scroll Area when it's wider or taller than its container.",
     'state-model':
-      "ScrollAreaViewport is ultimately just a plain scrollable div, so scrollTop and scrollLeft sit in the DOM the same way they would for any natively-scrolled element — the components aren't tracking scroll position themselves. To read or set scroll position from code, attach a ref to ScrollAreaViewport and reach for the standard DOM scroll APIs directly. Unlike Virtual List, there's no apiRef or imperative handle offered here.",
+      "ScrollAreaViewport is ultimately just a plain scrollable div, so scrollTop and scrollLeft sit in the DOM the same way they would for any natively-scrolled element for the purposes of reading/setting position yourself — attach a ref and use the standard DOM scroll APIs directly if you need to drive it from code (there's no `apiRef` or imperative handle the way Virtual List has one). That said, the component does actively track derived scroll state internally: percentage-scrolled and overflow are recomputed on every scroll and resize (via `ResizeObserver`) and pushed onto the scrollbar's `aria-valuenow`/`data-state` attributes — it's not purely passive.",
     'styling-and-tokens':
-      "The default theme's real interactive scrollbar is the native one: [data-slot=\"scroll-area-viewport\"] gets scrollbar-width: thin and scrollbar-color set to --ak-color-border-strong, so the browser's own scrollbar is themed directly. ScrollAreaScrollbar and ScrollAreaThumb get basic track/thumb styling (width, radius, background) from the default CSS but aren't wired up to track actual scroll position or size — there's no JS syncing them to the viewport's scroll offset, so as shipped they read as a static visual accent rather than a functioning custom-drag scrollbar.",
+      'The default theme styles the viewport\'s native scrollbar directly too — [data-slot="scroll-area-viewport"] gets scrollbar-width: thin and scrollbar-color set to --ak-color-border-strong — so you get a themed native scrollbar even before considering the custom one. `ScrollAreaScrollbar` and `ScrollAreaThumb` get track/thumb styling (width, radius, background) from the default CSS, and unlike a purely cosmetic overlay, they *are* synced to the viewport\'s actual scroll position and size at the JS layer (percentage, overflow, and visibility all update live) — the component ships as a real functioning scrollbar, keyboard-operable and all, not just a static visual accent.',
   },
   '/docs/components/select': {
     anatomy:
@@ -986,11 +986,11 @@ export const headingOverrides: Readonly<
     'state-model':
       "`Select` owns two independent pieces of state: the selected `value` and the `open` boolean. Each can run uncontrolled — `value`/`defaultValue`/`onValueChange` for the selection, `open`/`defaultOpen`/`onOpenChange` for the popover — or be handed to you fully controlled when the caller needs to own it. Leave both uncontrolled for a typical form field, or control `value` when the selection needs to sync with data loaded elsewhere. Internally the root also tracks a `currentIndexCandidate` for keyboard highlighting, but that's not something you set from the outside.",
     'styling-and-tokens':
-      '`@askrjs/themes/select` styles every part through `data-slot`, `data-state`, `data-disabled`, `data-side`, and `data-align` attributes rather than baking classes into the DOM structure, so you can restyle a specific state (open, disabled, a given popover side) with an attribute selector instead of overriding a component prop. `SelectTrigger` also exposes a `size` prop (`sm` | `md` | `lg`) for the common case of just needing a bigger or smaller control.',
+      "`@askrjs/themes/select` styles every part through `data-slot`, `data-state`, and `data-disabled` attributes rather than baking classes into the DOM structure — `SelectValue` additionally carries `data-placeholder` when nothing is selected yet, and `SelectTrigger` carries `data-size` for its size variants (there's no `data-side`/`data-align` pair in the real CSS; positioning isn't exposed as a styling hook that way). Restyle a specific state (open, disabled, empty) with an attribute selector instead of overriding a component prop. `SelectTrigger` also exposes a `size` prop (`sm` | `md` | `lg`) for the common case of just needing a bigger or smaller control — `md` is the default and has no dedicated CSS override, since it's what the unstyled base rule already renders.",
   },
   '/docs/components/sidebar': {
     anatomy:
-      'The nesting is SidebarScope > (Sidebar, SidebarInset), with Sidebar itself made of SidebarHeader, SidebarContent > SidebarGroup > (SidebarGroupLabel, SidebarGroupContent > SidebarMenu > SidebarMenuItem), and SidebarFooter. SidebarRail is a thin edge-of-sidebar button for toggling or resizing, and SidebarTrigger is a standalone button meant to live outside the sidebar itself, typically in a top bar. Every part accepts `as` and `asChild` so you can swap the underlying element without losing the styling hooks.',
+      "The nesting is SidebarScope > (Sidebar, SidebarInset), with Sidebar itself made of SidebarHeader, SidebarContent > SidebarGroup > (SidebarGroupLabel, SidebarGroupContent > SidebarMenu > SidebarMenuItem), and SidebarFooter. SidebarRail is a thin edge-of-sidebar button for toggling or resizing, and SidebarTrigger is a standalone button meant to live outside the sidebar itself, typically in a top bar. Coverage for swapping the underlying element isn't uniform: `Sidebar` itself and the button-flavored parts (`SidebarMenuButton`, `SidebarMenuAction`, `SidebarTrigger`, `SidebarRail`) all support `asChild` but explicitly do not accept `as` — only the plain layout parts (`SidebarContent`, `SidebarHeader`, `SidebarFooter`, `SidebarGroup`, and similar) take both.",
     api: 'Sidebar\'s own props are `collapsible` ("offcanvas" | "icon" | "none"), `side` ("left" | "right"), `variant` ("sidebar" | "floating" | "inset"), plus `width` and `shrink` inherited from the underlying Block layout primitive. SidebarMenuButton, SidebarMenuAction, and SidebarTrigger share button-flavored props — `active`, `size` ("default" | "sm" | "lg"), `variant` ("default" | "outline"), `tooltip`, and `tooltipSide` ("top" | "bottom" | "left" | "right"). The remaining parts (SidebarContent, SidebarHeader, SidebarFooter, SidebarGroup, and friends) take generic element props with no component-specific additions.',
     'edge-cases':
       "Because collapse state isn't managed internally, an \"offcanvas\" sidebar that's supposed to slide off-screen only does so if your CSS and state actually respond to whatever flag you're toggling — the `collapsible` prop alone doesn't hide anything by itself beyond setting the data-collapsible attribute. If you use the \"icon\" collapsible mode, you're responsible for swapping label visibility and layout at whatever breakpoint or state change you define; nothing here does that automatically. Nesting multiple SidebarGroup sections is fine, but deeply nested menus aren't part of the shipped structure — SidebarMenuItem doesn't support nested SidebarMenu out of the box.",
@@ -1014,7 +1014,7 @@ export const headingOverrides: Readonly<
       '`Slider` is the state-owning root; inside it you compose `SliderTrack` (the full-length background), `SliderRange` (the filled portion between the minimum and the current value), and `SliderThumb` (the draggable, focusable handle). All three children are plain `div` wrappers with no required props beyond what `BoxProps` already gives you.',
     api: 'Beyond the value props, `Slider` takes `id` and `name` — set `name` if you want the current value to participate in a surrounding `<form>`. Values are snapped to the nearest valid `step` before `onValueChange` fires, and if `max` is configured at or below `min` the library quietly falls back to `min + step` rather than producing a zero-width or inverted track.',
     'edge-cases':
-      "Dragging outside the track's bounding box still resolves to a valid value — pointer coordinates are clamped through `min`/`max` before being snapped, so users don't lose the drag by moving the cursor too far. Because listeners are attached per active drag and torn down on `pointerup`, unmounting a `Slider` mid-drag doesn't leave stray global listeners behind.",
+      "Dragging outside the track's bounding box still resolves to a valid value — the raw pointer position is snapped to the nearest `step` first, then the snapped result is clamped through `min`/`max` (not the other way around), so users don't lose the drag by moving the cursor too far. Because listeners are attached per active drag and torn down on `pointerup`, unmounting a `Slider` mid-drag doesn't leave stray global listeners behind.",
     'install-and-import':
       "Install `@askrjs/ui` for the behavior and `@askrjs/themes` for the default track/range/thumb visuals, then import from `@askrjs/ui/slider` and `@askrjs/themes/slider`. Both subpaths are real exports, so there's no need to pull in the package roots just to use a slider.",
     'keyboard-and-accessibility':
@@ -1026,7 +1026,7 @@ export const headingOverrides: Readonly<
     'related-pages':
       'For a fixed, non-interactive value indicator rather than an input, use Progress instead — Slider is specifically for values the user changes. If you need a numeric input that also supports typing an exact value, pair it with Input rather than trying to make the thumb double as a text field.',
     'state-model':
-      "The numeric `value` can be left uncontrolled with `defaultValue` or driven externally through `value` and `onValueChange`, alongside `min`, `max`, `step`, `orientation` (`horizontal` or `vertical`), and `disabled`. Dragging the thumb or pressing arrow keys calls the same internal setter that feeds `onValueChange`, so there's no separate internal-vs-external value to reconcile. A per-slider registry keyed by `sliderId` tracks the track and thumb DOM nodes needed for pointer math.",
+      "The numeric `value` can be left uncontrolled with `defaultValue` or driven externally through `value` and `onValueChange`, alongside `min`, `max`, `step`, `orientation` (`horizontal` or `vertical`), and `disabled`. Dragging the thumb or pressing arrow keys calls the same internal setter that feeds `onValueChange`, so there's no separate internal-vs-external value to reconcile. A per-slider registry — a `WeakMap` keyed by an internal identity object, not the string `sliderId` — tracks the track and thumb DOM nodes needed for pointer math; `sliderId` itself is only used to derive the track/thumb DOM element ids, not as the registry key.",
     'styling-and-tokens':
       'Track, range, and thumb each expose `data-slot` for targeted styling, and the root forwards `data-disabled` and `data-orientation` so vertical sliders and disabled states can be styled without JavaScript branching. `@askrjs/themes/slider` ships sensible defaults for all of this; override the CSS custom properties rather than fighting the generated class names.',
   },
@@ -1052,7 +1052,7 @@ export const headingOverrides: Readonly<
   '/docs/components/switch': {
     api: "`Switch` accepts `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `required`, `name`, and `value` — the last two exist specifically for the `asChild=false` case where the component ends up participating in native form submission. When `asChild` is true, `Switch` renders through `Slot` onto your own element instead of a `<button>`, and `type` is not accepted in that mode since there's no native button to type.",
     'edge-cases':
-      'Per the package\'s `FORM_INTEGRATION` contract, a Switch backed by a real `<button>` submits through a hidden `checkbox`-type input with value `"on"` when `name` is set — the same convention native checkboxes use, so existing form-handling code that expects checkbox-style submission keeps working. If you render Switch via `asChild` onto a non-button element, that hidden input and the native `disabled` attribute path are no longer available; you\'re responsible for equivalent `aria-disabled` handling.',
+      "Per the package's `FORM_INTEGRATION` contract, Switch submits through a hidden `checkbox`-type input with value `\"on\"` when `name` is set — the same convention native checkboxes use, so existing form-handling code that expects checkbox-style submission keeps working. That hidden input renders unconditionally off `name` being set, independent of `asChild` — rendering via `asChild` onto a non-button element doesn't remove it. `aria-disabled` handling is likewise automatic either way: it comes from the same `pressable()` foundation call regardless of which branch renders, so you don't need to wire it yourself when using `asChild`. What `asChild` does remove is the native `disabled` attribute path specifically, since a non-button host has no such attribute to set.",
     'install-and-import':
       'Import the behavior from `@askrjs/ui/switch` and the default appearance from `@askrjs/themes/switch`. Both are real subpath exports of their respective packages, so you never need to reach into the root barrel just to render a switch.',
     'keyboard-and-accessibility':
@@ -1066,7 +1066,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "`checked` can be left uncontrolled via `defaultChecked`, or driven externally by passing `checked` alongside `onCheckedChange`. There's no separate internal boolean to fight with: whatever value you supply (or the current default) is exactly what renders, and every interaction routes through `onCheckedChange` before anything changes visually in a controlled setup.",
     'styling-and-tokens':
-      'The track and thumb are styled through `data-slot` and `data-state` (`checked`/`unchecked`) rather than boolean class toggles, so a themed override can target `[data-state="checked"]` without needing to know which internal class name maps to which state. `data-disabled` is set the same way for the disabled visual treatment.',
+      'The track is styled through `[data-slot="switch"]` and `data-state` (`checked`/`unchecked`) rather than boolean class toggles, so a themed override can target `[data-state="checked"]` without needing to know which internal class name maps to which state. The thumb has no `data-slot` of its own — it\'s a `::after` pseudo-element on the track, styled with `[data-slot="switch"]::after`, not a separate DOM node you can target directly. `data-disabled` is set on the track the same way for the disabled visual treatment.',
   },
   '/docs/components/table': {
     anatomy:
@@ -1075,7 +1075,7 @@ export const headingOverrides: Readonly<
     'edge-cases':
       "Large row counts will slow down or jank a plain Table because every row is real DOM — there's no windowing built in, so switch to Virtual Table once you're past a few hundred rows at once. If you use asChild on Table itself, the child you pass must already be (or forward props onto) a table-compatible element, or the merged data-slot and ARIA attributes end up somewhere the browser doesn't expect. Empty states aren't handled for you — an empty TableBody renders as a header with no rows — so pair it with your own empty-state markup (Empty from @askrjs/themes fits well) when the row array is empty.",
     'install-and-import':
-      "@askrjs/ui/table ships eight unstyled primitives — Table, TableCaption, TableHead, TableBody, TableFoot, TableRow, TableHeaderCell, and TableCell — each wrapping the matching native element (table, caption, thead, tbody, tfoot, tr, th, td) with no attached behavior. @askrjs/themes/table re-exports those same primitives untouched and layers on CSS keyed to data-slot attributes, so the tree you write is identical whichever package you import from. Styling only shows up once you also load @askrjs/themes/default (or another theme) — the JS subpath alone ships no CSS. Note that @askrjs/themes/table, /data-table, and /scroll-area all resolve to the same dist/components.js barrel, so the subpath you pick is mostly documentation convenience; a bundler still tree-shakes what you don't use.",
+      '@askrjs/ui/table ships eight unstyled primitives — Table, TableCaption, TableHead, TableBody, TableFoot, TableRow, TableHeaderCell, and TableCell — each wrapping the matching native element (table, caption, thead, tbody, tfoot, tr, th, td) with no attached behavior. @askrjs/themes/table re-exports those same primitives untouched and layers on CSS keyed to data-slot attributes, so the tree you write is identical whichever package you import from. Styling only shows up once you also load @askrjs/themes/default (or another theme) — the JS subpath alone ships no CSS. @askrjs/themes/table, /data-table, and /scroll-area are each their own compiled entry file, not aliases pointing at one shared barrel — table simply re-exports @askrjs/ui/table untouched, while data-table pulls its presentational-only DataTable off the internal catalog module instead.',
     'keyboard-and-accessibility':
       "Because each part renders its native HTML counterpart, table navigation and screen-reader row/column announcements come from the browser and platform accessibility tree for free — there's no custom ARIA layer to configure. TableHeaderCell renders a real th, so use it for column (and row, where relevant) headers rather than TableCell, or assistive tech loses the header-to-cell relationship. TableCaption is the right place for a short description of the table's contents; screen readers announce it before reading the grid.",
     'live-examples':
@@ -1089,14 +1089,14 @@ export const headingOverrides: Readonly<
   },
   '/docs/components/tabs': {
     anatomy:
-      'Tabs/Tab is flat: a nav-like Tabs wrapper around any number of Tab links, no content panels involved because it\'s driving navigation rather than showing/hiding content. TabsList/TabsTrigger/TabsContent looks like the ARIA tabs pattern (role="tablist", role="tab", role="tabpanel" are all applied for you) but stops at styling and roles — there\'s no hidden Context tracking a current tab or associating a trigger with its panel.',
+      'Tabs/Tab is flat: a nav-like Tabs wrapper around any number of Tab links, no content panels involved because it\'s driving navigation rather than showing/hiding content. TabsList/TabsTrigger/TabsContent looks like the ARIA tabs pattern, but the role coverage is partial: `TabsList` gets `role="tablist"` and `TabsContent` gets `role="tabpanel"`, but `TabsTrigger` itself sets no `role` at all — you need to add `role="tab"` yourself if you want the full pattern. There\'s no hidden Context tracking a current tab or associating a trigger with its panel either way.',
     api: 'Tab\'s props are LinkProps merged with `active` and `match` ("prefix" | "exact"), so anything your router\'s Link accepts is fair game here too. Tabs itself takes just `children`, plus an `asChild` escape hatch if you need to render a different wrapper element. TabsList, TabsTrigger, and TabsContent are effectively untyped pass-throughs — they accept your usual element props (as, asChild, class, children) with no tabs-specific props at all, which is the clearest signal that the state logic isn\'t included.',
     'edge-cases':
       "Because TabsTrigger/TabsContent don't manage state, if you forget to update data-state or conditionally render the panels, clicking a trigger will change its visual styling only in whatever way your click handler drives — nothing switches automatically. If you need a fully accessible, self-contained tabbed-panel widget with keyboard arrow navigation between tabs, you'll need to build that state and interaction logic on top of these parts yourself; it isn't shipped. For route-driven tabs, make sure `match` is set correctly (\"exact\" vs \"prefix\") or a parent route's tab will stay highlighted on child routes you didn't intend.",
     'install-and-import':
       "Both flavors come from the same place: import Tabs and Tab, or TabsList, TabsTrigger, and TabsContent, from @askrjs/themes/tabs (which, like every themes subpath, is really just the shared components barrel). Tab's props extend your router's LinkProps, so it needs to run inside your app's router context to navigate correctly. TabsList and friends have no such dependency — they're plain elements you can drop anywhere.",
     'keyboard-and-accessibility':
-      "Tab renders as a real link, so keyboard behavior — Tab key to move focus, Enter to navigate — comes for free from the browser and your router, and aria-current=\"page\" on the active link is what screen readers announce as the current section. TabsList/TabsTrigger/TabsContent apply the correct ARIA roles (tablist/tab/tabpanel), but since there's no built-in state, you also own wiring up aria-selected on the active trigger and aria-controls/id pairing between a trigger and its panel if you want full tab-pattern accessibility. Arrow-key navigation between triggers isn't provided — you'd need to add that yourself if the panel pattern requires it.",
+      'Tab renders as a real link, so keyboard behavior — Tab key to move focus, Enter to navigate — comes for free from the browser and your router, and `aria-current="page"` on the active link is what screen readers announce as the current section; that active state is computed automatically off the current route (unless you pass `active` to override it), not something you have to track yourself. TabsList and TabsContent apply `tablist`/`tabpanel` roles, but TabsTrigger gets no role from the component — add `role="tab"` yourself, along with `aria-selected` on the active trigger and `aria-controls`/`id` pairing between a trigger and its panel, if you want full tab-pattern accessibility. Arrow-key navigation between triggers isn\'t provided either — you\'d need to add that yourself if the panel pattern requires it.',
     'live-examples':
       'For route-based tabs, wrap a Tabs (a styled nav element) around a Tab per destination, passing `active` or letting `match="prefix"` decide highlighting based on the current URL. For a panel-switcher, render TabsList containing one TabsTrigger per option, and pair each with a TabsContent — but you\'re responsible for tracking which one is selected and swapping data-state or conditionally rendering the matching panel yourself.',
     purpose:
@@ -1104,7 +1104,7 @@ export const headingOverrides: Readonly<
     'related-pages':
       "If you actually want route-scoped navigation without the tab-strip visual, Navbar and Navigation Menu and the plain NavLink/NavItem primitives are worth a look — Tab is really a styled variant of that same navigation family. For grouping content sections that don't need URL-backed navigation, Accordion and Collapsible cover the show/hide interaction with real built-in state, which Tabs here does not.",
     'state-model':
-      'For Tab, "selected" state is really route state: active styling is driven by aria-current="page" or a `data-active` attribute you set based on your router\'s current location, not by anything the component tracks internally. For TabsTrigger/TabsContent, state is entirely your responsibility — store the selected tab id in your own component state and use it to set data-state="active" on the current trigger and conditionally render (or hide) the matching content.',
+      'For Tab, "selected" state is really route state — but Tab computes it for you: it compares the current URL against its own destination (respecting the `match` prop, `"prefix"` or `"exact"`) and sets `aria-current="page"` automatically when active, the same way the rest of the shared nav-link machinery does. You only need to pass `active` yourself if you want to override that computed value. For TabsTrigger/TabsContent, by contrast, state really is entirely your responsibility — store the selected tab id in your own component state and use it to set data-state="active" on the current trigger and conditionally render (or hide) the matching content.',
     'styling-and-tokens':
       'Tab and Tabs style through .tab/.tabs classes (with [data-slot="tab"]/[data-slot="tabs"] as a fallback), using data-active and aria-current="page" as the hooks for the active-state look. TabsList, TabsTrigger, and TabsContent live in a separate stylesheet keyed off [data-slot="tabs-list"], [data-slot="tabs-trigger"], and [data-slot="tabs-content"], with the active trigger styled off either data-state="active" or data-active="true" — pick whichever attribute your own state logic sets. Both sets read from the same shared --ak-* tokens as the rest of the theme, so they stay visually consistent with everything else.',
   },
@@ -1113,7 +1113,7 @@ export const headingOverrides: Readonly<
       'Textarea renders a single native <textarea> and nothing around it — no counter, no auto-grow wrapper, no label. If you need a character counter or a label/hint layout, compose it with Field and Label rather than expecting Textarea to provide it. With asChild, its props merge onto the one child you supply instead of it rendering its own element.',
     api: "TextareaElementProps extends native <textarea> attributes (minus children and ref) with disabled?: boolean, tabIndex?: number, asChild?: false, and a ref typed to HTMLTextAreaElement; TextareaAsChildProps swaps those for asChild: true and a single required child. There's no Textarea-specific prop beyond what the native element and disabled/tabIndex already cover — everything else is standard HTML textarea behavior (rows, cols, maxLength, and so on).",
     'edge-cases':
-      "Because the min-height is set in CSS rather than the rows attribute, a Textarea with very little content still reserves 5rem of vertical space by default — set rows or override the CSS variable if you need a shorter starting height. As with Input's asChild, wrapping a non-textarea-like element drops the forwarded props with no runtime warning, so keep asChild targets limited to elements that actually accept text input props.",
+      "Because the min-height is set in CSS rather than the rows attribute, a Textarea with very little content still reserves 5rem of vertical space by default — set rows or override the CSS variable if you need a shorter starting height. Unlike Input's asChild, which merges props onto whatever single child you pass with no runtime check, Textarea's asChild actively verifies the child is a native `<textarea>` and throws `Textarea \\`asChild\\` requires a native <textarea> host.` if it isn't — a wrong target fails loudly here instead of silently dropping props.",
     'install-and-import':
       "Textarea needs @askrjs/ui and @askrjs/askr for its headless behavior, with @askrjs/themes as an optional add-on for the default look. Import it headless via `import { Textarea } from '@askrjs/ui/textarea'`, or grab the same component from `@askrjs/themes/textarea` when you want styling included. As with Input, the themes package re-exports the @askrjs/ui Textarea directly instead of wrapping it in its own styled component.",
     'keyboard-and-accessibility':
@@ -1161,9 +1161,9 @@ export const headingOverrides: Readonly<
     'keyboard-and-accessibility':
       'The stack renders with `role="status"` and `aria-live="polite"`, per TOAST_A11Y_CONTRACT, so new toasts get announced without stealing focus, and the viewport carries an accessible "Notifications" label out of the box. ToastAction and ToastClose are ordinary focusable buttons; ToastAction runs its handler and then closes the toast on its own, so there\'s no need to also wire a separate dismiss call after the action fires.',
     'live-examples':
-      "Trigger both systems from this page to see how their stacking, timing, and dismiss behavior actually differ in the browser, not just on paper. Because they're separate implementations, watch the DOM structure each one produces — they don't share markup even when the visual result looks similar.",
+      "Trigger Toast from this page and inspect Sonner's markup separately — they're not offering the same behavior to compare side by side. Toast actually stacks, times out, and dismisses entries through ToastHost's registry; Sonner is a bare styled wrapper with none of that wired up, so there's no live stacking/timing/dismiss behavior to observe from it here.",
     purpose:
-      'Toast is the headless notification primitive: a host component that owns a registry of active entries, plus the individual pieces you compose into each one. Sonner is a themes-only alternate — a single component you mount once, with no `@askrjs/ui` equivalent — for teams who want a drop-in notifier instead of assembling ToastHost, ToastViewport, and Toast by hand.',
+      "Toast is the headless notification primitive: a host component that owns a registry of active entries, plus the individual pieces you compose into each one — this is the real, working notification system. Sonner (aliased from `Toaster`) is not a drop-in replacement for it: it's a bare presentational wrapper with no imperative `toast()` API, queueing, stacking, timing, or dismiss logic of its own — despite sharing a name with the popular standalone Sonner library, it doesn't reproduce that library's behavior. If you need an actual working notification system today, build it on Toast/ToastHost, not Sonner.",
     'related-pages':
       'See Progress for status feedback with a determinate value instead of a transient message, and Alert, Badge, Empty, Skeleton, and Spinner for feedback that should stay on screen rather than time out.',
     'state-model':
@@ -1178,7 +1178,7 @@ export const headingOverrides: Readonly<
     'edge-cases':
       "Disabling `ToggleGroup` at the root disables every item regardless of each item's own `disabled` prop, but the reverse isn't true — you can disable individual items in an otherwise enabled group. Because `ToggleGroupItem`'s `value` is required, forgetting to set one is a compile-time error rather than something that silently breaks selection at runtime.",
     'install-and-import':
-      "Both primitives ship from `@askrjs/ui` with their own subpaths — `@askrjs/ui/toggle` and `@askrjs/ui/toggle-group` — and matching `@askrjs/themes/toggle` and `@askrjs/themes/toggle-group` subpaths for styling. Import only the one you need; a page that just needs a single toggle button doesn't have to pull in the group's item-collection logic.",
+      "Both primitives ship from `@askrjs/ui` with their own subpaths — `@askrjs/ui/toggle` and `@askrjs/ui/toggle-group` — and matching `@askrjs/themes/toggle` and `@askrjs/themes/toggle-group` JS subpaths that re-export the same components; there's no separate `toggle.css` file, just `toggle-group.css` in the default theme covering both, loaded the same way as every other component's styling (via `@askrjs/themes/default`, not per-subpath). Import only the JS subpath you need; a page that just needs a single toggle button doesn't have to pull in the group's item-collection logic.",
     'keyboard-and-accessibility':
       '`Toggle` uses `role="button"` with `aria-pressed` and responds to both Enter and Space, and its types explicitly prohibit `onClick` in favor of `onPress` — the package\'s own docs note this is because `onClick` doesn\'t carry toggle or disabled semantics the way the pressable foundation\'s `onPress` does. `ToggleGroup` exposes a `loop` prop that controls whether arrow-key navigation wraps from the last item back to the first, and the group itself carries `role="group"` while each item keeps `role="button"` with `aria-pressed`.',
     'live-examples':
@@ -1211,7 +1211,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "Openness is a plain boolean on the root: pass `open` and `onOpenChange` to drive it from outside, or let `defaultOpen` seed uncontrolled behavior and manage it internally. There's no separate state for hover versus focus — both funnel into the same `open` value, so you don't need to reconcile two code paths for pointer and keyboard users.",
     'styling-and-tokens':
-      "`TooltipContent` picks up `data-state`, `data-side`, `data-align`, and `data-disabled` attributes, which is what the default theme's CSS hooks into for entrance/exit transitions and directional arrow placement. Stacking is controlled by the shared overlay z-index scale, where tooltips sit above toasts at `var(--ak-z-tooltip, 1600)` so they're never hidden behind other overlay layers.",
+      "`TooltipContent` picks up `data-state`, `data-side`, and `data-align` attributes, which is what the default theme's CSS hooks into for entrance/exit transitions and directional arrow placement — `data-disabled` is set on `TooltipTrigger` instead, reflecting the trigger's disabled state, not the content. Stacking is controlled by the shared overlay z-index scale, where tooltips sit above toasts at `var(--ak-z-tooltip)` (`1600`, no CSS fallback value — the token is expected to always be defined by the loaded theme) so they're never hidden behind other overlay layers.",
   },
   '/docs/components/typography-and-display-primitives': {
     anatomy:
@@ -1232,7 +1232,7 @@ export const headingOverrides: Readonly<
     'state-model':
       "Rendering is all these components do — there's nothing stateful to track once you land on typography and display primitives. Every one of them shares the same generic prop shape, `CatalogComponentProps`, giving you `as` to swap which element gets rendered and `asChild` to merge props onto a child rather than wrap it. That's how, say, `TypographyH2` can render as an `h3` when you need the visual weight of an H2 without breaking your document's heading hierarchy.",
     'styling-and-tokens':
-      "Type scale, weight, and color come from the theme's shared type tokens, so switching themes or overriding `--ak-type-*` variables updates every `Typography` component consistently rather than requiring per-component overrides. `TypographyMuted` pulls from the muted-foreground color token specifically, which keeps secondary text in sync with other de-emphasized UI (helper text, placeholder text) elsewhere in the theme.",
+      "Type scale, weight, and color come from the theme's shared tokens — sizing off `--ak-font-size-*` (there's no separate `--ak-type-*` family; font size is the same scale used everywhere else in the theme), so switching themes updates every `Typography` component consistently rather than requiring per-component overrides. `TypographyMuted` pulls its color from `--ak-color-text-subtle` specifically, which keeps secondary text in sync with other de-emphasized UI (helper text, placeholder text) elsewhere in the theme.",
   },
   '/docs/components/virtual-list': {
     anatomy:
@@ -1241,7 +1241,7 @@ export const headingOverrides: Readonly<
     'edge-cases':
       "rowHeight is fixed — VirtualList doesn't measure variable-height rows, so content that wraps to different heights per item will clip or leave gaps; keep row content a predictable height or pad it to fit. getKey must return stable, unique keys across renders, or scroll position and followBottom tracking can jump when items are added or removed. When followBottom is on and the user scrolls away from the bottom, new items increment pendingUnseenCount instead of forcing a scroll — read that value if you want a 'N new' indicator rather than silently losing the count.",
     'install-and-import':
-      'VirtualList comes from @askrjs/ui/virtual-list, and @askrjs/themes doesn\'t offer a themed counterpart to pair with it — no /virtual-list subpath, no styled wrapper component. Styling still arrives, though: @askrjs/themes/default\'s CSS carries rules for [data-slot="virtual-list"] and [data-slot="virtual-list-row"], both of which VirtualList renders on its own elements. So pairing the headless component with the default theme\'s stylesheet gets you working styles, just without any themes-side props layer sitting on top.',
+      "VirtualList comes from @askrjs/ui/virtual-list; @askrjs/themes doesn't have a dedicated `/virtual-list` subpath or a styled wrapper component layered on top, but the same VirtualList is re-exported as-is through the `@askrjs/themes/components` barrel, so `import { VirtualList } from '@askrjs/themes/components'` is a real, working import — it just isn't wrapped or restyled beyond what the CSS below already covers. Styling arrives the same way regardless of which package you imported it from: @askrjs/themes/default's CSS carries rules for [data-slot=\"virtual-list\"] and [data-slot=\"virtual-list-row\"], both of which VirtualList renders on its own elements.",
     'keyboard-and-accessibility':
       "Rows carry a data-visible attribute, but VirtualList doesn't manage focus or a roving tabindex — keyboard interaction is whatever your rowComponent implements for its own content, such as a focusable button inside a row getting tabbed to normally. Because off-screen rows are unmounted rather than hidden, a screen reader's virtual cursor or the browser's find-in-page won't encounter items scrolled out of view, which is inherent to any virtualized list and worth knowing before you rely on either for browsing the full dataset.",
     'live-examples':
@@ -1260,7 +1260,7 @@ export const headingOverrides: Readonly<
     'edge-cases':
       'Like Virtual List, row height (rowHeight) and header height (headerHeight) are both fixed — variable-height content will clip or misalign the virtualization math. Column width is optional per column (width?: number | string); omit it on every column and layout falls back to normal table sizing, which can fight with fixed-rowHeight virtualization if content forces wrapping. Unstable or colliding getKey values cause the same selection- and scroll-jumping issues Virtual List has, so keep rowKey stable across data refetches.',
     'install-and-import':
-      "VirtualTable is imported from @askrjs/ui/virtual-table; @askrjs/themes has nothing shipped under a matching name, so a /virtual-table subpath or dedicated styled component isn't something you'll find. What does carry over is styling — the default theme's CSS targets [data-slot=\"virtual-table\"] along with its header, row, and cell slots, so loading @askrjs/themes/default is enough to style it even without a themes package component to import. Virtual List follows this same setup, for what it's worth.",
+      'VirtualTable is imported from @askrjs/ui/virtual-table; @askrjs/themes has no dedicated `/virtual-table` subpath or wrapped/restyled version of it, but — like VirtualList — the same component is re-exported through the `@askrjs/themes/components` barrel, so importing it from either package works. What does carry over regardless of which import you use is styling — the default theme\'s CSS targets [data-slot="virtual-table"] along with its header, row, and cell slots, so loading @askrjs/themes/default is enough to style it.',
     'keyboard-and-accessibility':
       "VirtualTable doesn't implement its own keyboard navigation between cells or rows — onRowClick and the imperative selection methods are pointer and programmatic entry points, and any keyboard behavior inside a cell comes from what cellComponent renders. Because rows outside the visible range are unmounted rather than hidden, the same caveat as Virtual List applies: assistive technology and browser find-in-page only see currently-rendered rows, not the full dataset.",
     'live-examples':
@@ -1304,9 +1304,9 @@ export const headingOverrides: Readonly<
     'browser-only-work':
       "Code that touches `window`, `document`, or other browser globals can't run during server rendering, since none of those exist in a Node process. Gate that work behind lifecycle helpers like `task` or `resource`, which only execute after mount on the client, rather than reading browser globals directly in the component body where SSR would throw.",
     'hydration-diagnostics':
-      'Server-side rendering shares a `DocumentRenderContext` — including a `seed` value — with the client so both passes render the same output from the same inputs; when they disagree, the runtime surfaces a hydration mismatch. Development builds emit diagnostics tied to `devWarningsEmitted` on the component instance to help point at which subtree diverged, so a mismatch shows up as a specific warning rather than a generic "hydration failed" message.',
+      'Server-side rendering shares a `DocumentRenderContext` — including a `seed` value — with the client so both passes render the same output from the same inputs; when they disagree, the runtime surfaces a hydration mismatch. The check itself is a whole-document string comparison (server-rendered markup against a fresh server-side re-render, both normalized), so the diagnostic is a single generic message — `[Askr] Hydration mismatch detected. Server HTML does not match expected server-render output.` — rather than a pointer at which specific subtree diverged. `devWarningsEmitted` on the component instance is a separate mechanism entirely, used for unused-state-variable and slow-render warnings, not hydration.',
     'render-purity':
-      'A component function must return the same output for the same props and state on every call — the runtime depends on this to decide what changed and patch only that part of the DOM. Fetching data, subscribing to external events, or mutating shared objects directly inside a component body breaks that guarantee; those belong behind `resource`, `on`, or `task` instead, which run outside the render pass and hand results back through reactive values.',
+      'A component function must return the same output for the same props and state on every call — the runtime depends on this to decide what changed and patch only that part of the DOM. Fetching data, subscribing to external events, or mutating shared objects directly inside a component body breaks that guarantee; those belong behind `resource`, `on`, or `task` instead, which run outside the render pass and hand results back through reactive values. Two rules follow directly from re-running the whole function on every update, and the runtime enforces both at runtime, not just by convention: `state()`, `derive()`, lifecycle calls, and `<For>` must run in the same order on every render of a given component — wrapping one of them in a plain `if` (instead of `<Show>`/`<Case>`) throws once the sequence changes — and calling a state setter during render itself (rather than from an event handler or effect) throws `[Askr] state.set() cannot be called during component render.` because it would recurse into another render of the same component.',
     'stable-initial-state':
       "`state()` initializers run once, on first render, and are expected to be pure — if the seed value depends on something nondeterministic (like `Math.random()` or `Date.now()`), server-rendered markup and the client's first hydration pass will disagree. Deriving that value from a stable input (a route param, a server-supplied seed) instead keeps the first render identical on both sides.",
   },
@@ -1318,13 +1318,13 @@ export const headingOverrides: Readonly<
     recovery:
       'The `reset` function passed into a function-form `fallback` clears the boundary\'s error state and attempts to render the children again, which is how a "Try again" button in the fallback UI is wired up. Because the boundary still tracks `resetKey` internally, either an explicit `reset()` call or a change to `resetKey` from outside can bring the subtree back.',
     reporting:
-      "`onError`, an optional prop on `ErrorBoundary`, fires with the caught error so you can send it to logging or monitoring without that concern living inside the fallback UI itself. In development the boundary renders a visible fallback and still surfaces the underlying error to the console, so failures aren't silently swallowed while you're debugging.",
+      "`onError`, an optional prop on `ErrorBoundary`, fires with the caught error so you can send it to logging or monitoring without that concern living inside the fallback UI itself. The default fallback renders in every environment, not just development — what's development-specific is that its error-details `<details>` panel defaults to open instead of collapsed, so a production build still surfaces a visible fallback (with the raw error text one click away) rather than a blank subtree.",
   },
   '/docs/core-concepts/lifecycle-work': {
     'cancellation-and-cleanup':
       "`resource`'s worker function receives a `{ signal }` argument — an `AbortSignal` that fires when the dependencies change or the component unmounts, so an in-flight `fetch(url, { signal })` cancels itself instead of racing a newer call. `capture(fn)` snapshots the result of a synchronous read at call time and returns a thunk to read it back later, which is the documented way to carry a consistent value into an async continuation without re-reading state that may have moved on.",
     'events-and-streams':
-      "`on(target, event, handler, options?)` attaches a DOM event listener scoped to the component's lifetime — it wraps `addEventListener`/`removeEventListener` so you don't have to write the teardown yourself. `stream(source, options?)` is the equivalent shape for streaming values over time, returning the same `{ value, pending, error }` result shape as `resource` so UI code can treat one-shot and ongoing data sources consistently.",
+      "`on(target, event, handler, options?)` attaches a DOM event listener scoped to the component's lifetime — it wraps `addEventListener`/`removeEventListener` so you don't have to write the teardown yourself. `stream(source, options?)` is the equivalent primitive for values over time, but it's not the same shape as `resource` — it returns `{ value, status, pending, stale, error, restart(), close() }`, adding a `status` for connection state (`connecting`/`connected`/`reconnecting`/`closed`/`error`) and `restart()`/`close()` controls that a one-shot `resource()` call has no equivalent for.",
     'resources-and-tasks':
       "`resource(fn, deps)` from `@askrjs/askr/resources` runs async work tied to a dependency list and returns `{ value, pending, error, refresh() }` — it reruns automatically whenever `deps` changes and exposes a `refresh()` you can call manually. `task(fn)` is the lower-level primitive for scheduling work as part of a component's lifecycle; the function you pass can itself return a cleanup function or a promise resolving to one, which the runtime calls when the task needs to unwind.",
     timers:
@@ -1368,7 +1368,7 @@ export const headingOverrides: Readonly<
     'shared-server-data':
       'Once two or more components need the same server data, a resource() call per component means duplicate requests and no shared cache. createQuery() and defineQuery() solve that by keying data on a string derived from the input, so repeated calls with the same key reuse the same cached entry through a DataRuntime. Consistency is tracked explicitly through states like fresh, stale, refreshing, and pending-write rather than a single boolean loading flag.',
     'writes-and-invalidation':
-      "Writes go through createMutation(), which wraps an async action function and exposes execute(), abort(), and reset() alongside a status field (idle, pending, success, or error). A mutation's affects() option maps its input and result to the query key prefixes it should invalidate, and invalidate() or queryScope().invalidate() can also be called directly wherever a write happens outside a mutation.",
+      "Writes go through createMutation(), which wraps an async action function and exposes execute(), abort(), and reset() alongside a status field (idle, pending, success, or error). A mutation's affects() option maps its input and result to the query key prefixes it should invalidate — gated by afterSuccess: 'invalidate', which is what actually triggers the invalidation, not affects() being present on its own — and invalidate() or queryScope().invalidate() can also be called directly wherever a write happens outside a mutation.",
   },
   '/docs/data/actions-and-forms': {
     'action-contract':
@@ -1376,7 +1376,7 @@ export const headingOverrides: Readonly<
     'form-submission':
       "ActionForm({ action, children, ...props }) renders what the type declarations call a native form bound to a declared action — it's not a synthetic event API layered over fetch, it's a real <form> wired to the ActionDescriptor you pass in. For submitting programmatically instead of through a rendered form, action(descriptor) returns a command handle with a submit(input) method and a state tuple carrying ActionStatus (pending, result, error).",
     'redirects-and-revalidation':
-      "Invalidation after a successful action is driven by the invalidates list on the ActionDescriptor, which clears the matching query prefixes the same way a mutation's affects() option does. There's no separate redirect API in the actions module itself — navigating away after a submission is ordinary router navigation, and any queries feeding the destination route's loaders pick up fresh data through the router's own revalidation rather than anything action-specific.",
+      "Invalidation after a successful action is driven by the invalidates list on the ActionDescriptor, which clears the matching query prefixes the same way a mutation's affects() option does. Redirects, by contrast, do have a dedicated path through the actions module: the server-side ActionOutcome can carry a redirect location, which the enhanced JavaScript path (action()) validates as same-origin before calling location.assign() on it, and which an unenhanced native form submission turns into a real HTTP 303 response instead. It isn't ordinary router navigation wearing an action's clothes — it's a security-checked redirect pipeline that's part of the action contract itself.",
     'validation-failures':
       "When submitted input fails the action's input schema, the failure comes back as an ActionValidationError with kind: 'invalid', the action id, the raw values that were submitted, an issues array from the schema validator, and fieldErrors — a record mapping each field name to its own array of messages. That per-field shape is what you'd use to highlight individual inputs rather than showing one generic error for the whole form.",
   },
@@ -1396,7 +1396,7 @@ export const headingOverrides: Readonly<
     'optimistic-ui':
       "There's no dedicated optimistic-value API on MutationOptions — no optimisticData field to set. Optimistic UI is built by hand: keep local state for the value you're predicting, render it while mutation.status is 'pending', and reconcile or roll it back once status settles to 'success' or 'error'. The afterSuccess: 'invalidate' option can be paired with this to refetch the real data as soon as the write completes, replacing your optimistic guess with the server's actual response.",
     'targeted-invalidation':
-      'The affects(input, result) option on MutationOptions maps a completed write to the list of query key prefixes it should invalidate, so a successful mutation automatically triggers invalidate() on exactly the queries it touched rather than clearing the whole cache. For writes that happen outside a mutation entirely, invalidate(prefix, options) and queryScope().invalidate() are available directly, and invalidateOnInterval() covers periodic invalidation gated by options like visibleOnly or focusedOnly.',
+      "The affects(input, result) option on MutationOptions maps a completed write to the list of query key prefixes it should invalidate — but only when the mutation's afterSuccess option is 'invalidate' (the setting that opts into automatic invalidation at all); with a different afterSuccess setting, affects() is never called and nothing gets invalidated on your behalf. For writes that happen outside a mutation entirely, invalidate(prefix, options) and queryScope().invalidate() are available directly, and invalidateOnInterval() covers periodic invalidation gated by options like visibleOnly or focusedOnly.",
     'write-lifecycle':
       "A mutation's status is always one of 'idle', 'pending', 'success', or 'error', and the pending/error/result fields line up with whichever status you're in — result is only populated once status is 'success', error only once it's 'error'. Calling reset() puts it back to idle, and abort() cancels an in-flight execute() via the signal passed into the action function.",
   },
@@ -1404,11 +1404,11 @@ export const headingOverrides: Readonly<
     'consistency-modes':
       "Instead of a single isLoading flag, a Query<T>'s consistency field is one of 'fresh', 'stale', 'refreshing', or 'pending-write', and each value comes with a matching shape for data, error, and stale flags — a refreshing query still has its previous data available, for instance, while a stale query with an error has both data: null and staleReason: 'error'. Reading consistency first tells you which of those shapes you're dealing with before you touch data or error directly.",
     'define-a-query':
-      "defineQuery() takes a QueryDefinition — a key(input) function that derives a cache key, and a fetch(context) function that does the actual request — and hands back a reusable definition you can pass to createQuery(), serveQuery(), or prefetchQuery(). createQuery() also accepts a plain QueryOptions object directly if you don't need the input/key(input) split. Optional isConsistent() and reconcile() functions on the definition let you decide whether freshly fetched data actually replaces what's cached.",
+      "defineQuery() takes a QueryDefinition — a key(input) function that derives a cache key, and a fetch(context) function that does the actual request — and hands back a reusable definition you can pass to createQuery(), serveQuery(), or prefetchQuery(). createQuery() also accepts a plain QueryOptions object directly if you don't need the input/key(input) split. Optional isConsistent() and reconcile() functions on the definition don't gate whether fetched data reaches the cache — freshly fetched data is written to the query's state either way. What they control is what happens next: isConsistent() returning false marks the result stale (consistency: 'stale', staleReason: 'inconsistent') and triggers reconcile(), whose return value decides whether the query automatically retries.",
     'query-scopes':
       'queryScope(namespace) returns a QueryScope with key() and prefix() helpers that build namespaced cache keys, plus its own invalidate(parts, options) method scoped to that namespace. This is useful once query keys get structured — a scope per resource type keeps key-building consistent and keeps invalidation calls from accidentally matching keys that belong to a different feature.',
     'refresh-behavior':
-      "Every Query<T> carries a refresh() method from QueryControls that re-runs the fetch and returns a promise, independent of whatever caused the original fetch. Whether the refreshed data actually replaces the cached value depends on the definition's reconcile() function, if one is supplied — it gets the new data plus the key and can accept or reject it, which is how a query avoids clobbering good data with a response that arrived out of order.",
+      "Every Query<T> carries a refresh() method from QueryControls that re-runs the fetch and returns a promise, independent of whatever caused the original fetch. reconcile() doesn't decide whether refreshed data replaces the cached value — it's already written by the time reconcile() runs, and reconcile()'s return value only controls whether the query schedules another automatic retry. An out-of-order response arriving late is instead guarded separately, by generation and abort-controller identity checks that discard a stale in-flight fetch's result once a newer one has superseded it.",
   },
   '/docs/data/resources': {
     cancellation:
@@ -1426,7 +1426,7 @@ export const headingOverrides: Readonly<
     'dehydrate-and-hydrate':
       "dehydrateDataRuntime(runtime) serializes a DataRuntime's cached query data into a plain Record<string, unknown> that can be embedded in the server-rendered HTML. hydrateDataRuntime(runtime, data) does the reverse on the client, seeding a fresh runtime with that serialized data so components mounting from createQuery() find their data already cached instead of refetching on first render.",
     prefetch:
-      "createQueryPrefetchContext({ runtime, registry, request, signal, mode }) sets up a context for running queries ahead of render, with mode distinguishing 'ssr' from 'spa' prefetching. prefetchQuery(context, query, input) then runs that query against the registered handler and populates the runtime's cache, returning a boolean promise indicating whether the prefetch succeeded.",
+      "createQueryPrefetchContext({ runtime, registry, request, signal, mode }) sets up a context for running queries ahead of render, with mode distinguishing 'ssr' from 'spa' prefetching. prefetchQuery(context, query, input) populates the runtime's cache, returning a boolean promise indicating whether the prefetch succeeded — but which fetch path it runs depends on mode: only 'ssr' mode looks up and calls the registered ServerQueryHandler (and skips the prefetch with a console warning if none is registered for that query); 'spa' mode never consults the registry at all and calls the query's own client-side fetch() instead.",
     'register-handlers':
       "A ServerQueryHandler receives { input, request, signal } and returns the query's result, giving it access to the incoming Request when the handler needs headers, cookies, or other request context that a client-side fetch wouldn't have. The registry's get(query) method looks up the handler for a given QueryDefinition, so the same query object used on the client is the lookup key on the server.",
   },
@@ -1444,7 +1444,7 @@ export const headingOverrides: Readonly<
     'full-stack-and-startkit':
       "The `full-stack` template pairs SSR-capable pages with backend API routes in the same project, useful when your frontend and API are developed and deployed together. `startkit` is the broader opinionated starter — more conventions and structure pre-wired — and is generally the safest default if you're not certain yet which rendering mode you'll end up needing; you can still layer SSR or SSG entrypoints on afterward.",
     spa: "`createSPA` from `@askrjs/askr/boot` mounts the app client-side against an explicit route registry — no server rendering step, so the first paint happens after JavaScript loads. Use this for internal tools, dashboards, or anything where SEO and first-paint latency aren't primary concerns; it's also the simplest mode to reason about since there's no hydration mismatch to worry about.",
-    ssg: '`createStaticGen()` from `@askrjs/askr/ssg` renders your route table to HTML files ahead of time, writing to an `outputDir` with a `metadata.json` describing the run. It supports incremental regeneration keyed by `invalidationKeys` or changed route paths, so a CI rebuild only re-renders what actually changed. Routes with `auth` requirements or runtime `policies` are treated as runtime-only and skipped during prerendering — they need SSR instead.',
+    ssg: '`createStaticGen()` from `@askrjs/askr/ssg` renders your route table to HTML files ahead of time, writing to an `outputDir` with a `metadata.json` describing the run. It supports incremental regeneration keyed by `changedKeys` or changed route paths, so a CI rebuild only re-renders what actually changed. Routes with `auth` requirements or runtime `policies` are treated as runtime-only and skipped during prerendering — they need SSR instead.',
     ssr: 'Server-side rendering uses `@askrjs/askr/ssr` — `renderRouteRequest` or `resolveRequest` resolve a URL against your route registry and render to HTML on every request, then `hydrateSPA` takes over in the browser. This is the right choice when pages need fresh data on each load or when you need real SEO with dynamic content; it costs a running Node server and more moving parts than SPA or SSG.',
   },
   '/docs/getting-started/choose-a-starter': {
@@ -1461,9 +1461,9 @@ export const headingOverrides: Readonly<
     'add-state':
       "Call `state(initialValue)` inside a component to get a `[getter, setter]` pair — read the current value by calling the getter as a function, and update it by calling the setter, e.g. `setCount((value) => value + 1)`. State reads are tracked automatically wherever they're called, so a component re-renders when the state it read changes.",
     'build-the-application':
-      'Run `npm run build` from the generated project; for SPA and full-stack templates this produces a client bundle, and for SSG it can drive `createStaticGen()` to render every route to HTML in `outputDir`. Check the build output against the application mode you picked — an SSG build should produce static files per route, while an SSR build produces a server bundle you run with Node.',
+      "Run `npm run build` from the generated project; the SPA template's build produces a client bundle only, while `ssr` and `full-stack` both also build a server bundle to run with Node — full-stack isn't client-only the way SPA is. SSG can drive `createStaticGen()` to render every route to HTML in `outputDir`. Check the build output against the application mode you picked — an SSG build should produce static files per route, while an SSR or full-stack build produces a server bundle you run with Node.",
     'create-the-project':
-      'Run `askr create spa my-app` (or another template) and `cd my-app`. Open the generated route registry file — typically `src/pages/**/_routes.tsx` — to see how the starter route is already wired up with `route()`.',
+      'Run `askr create spa my-app` (or another template) and `cd my-app`. Open the generated route registry — `src/pages/**/_routes.tsx` for the `spa` template, or `src/router.tsx` plus `src/routes/*.ts` for `startkit`, `ssr`, `ssg`, and `full-stack` — to see how the starter route is already wired up with `route()`.',
     'register-a-route':
       "Routes are declared with `route(path, Component, options?)` inside a `createRouteRegistry(() => { ... })` callback, which returns the registry your application boots from. Add a new entry — `route('/about', () => <About />)` — inside the existing callback, then confirm the exported registry you pass to `createSPA` picks it up.",
   },
@@ -1471,7 +1471,7 @@ export const headingOverrides: Readonly<
     'create-with-the-cli':
       'Run it without installing anything — `npx @askrjs/cli@latest create <template> <name>` — or install `@askrjs/cli` globally (`npm install -g @askrjs/cli`) to get the `askr` command on your PATH. Template is one of `spa`, `ssr`, `ssg`, `full-stack`, or `startkit`. This scaffolds the project, installs bundled agent skills into `skills/` unless you pass `--no-skills`, and runs the install for you unless you pass `--no-install`.',
     'install-packages-directly':
-      "If you're adding Askr to an existing project instead of scaffolding a new one, install `@askrjs/askr` directly with `npm install @askrjs/askr` and import from its subpaths as needed — `@askrjs/askr` for state and JSX, `@askrjs/askr/boot` for startup, `@askrjs/askr/router` for routing. The CLI itself has no subpath exports beyond `package.json`; it's consumed only as the `askr` binary, not imported into application code.",
+      "If you're adding Askr to an existing project instead of scaffolding a new one, install `@askrjs/askr` directly with `npm install @askrjs/askr` and import from its subpaths as needed — `@askrjs/askr` for state and JSX, `@askrjs/askr/boot` for startup, `@askrjs/askr/router` for routing. The CLI itself is consumed mostly as the `askr` binary, not imported into application code — the one exception is `@askrjs/cli/ssg`, a types-only subpath for typing an `ssg.config.ts` module.",
     'runtime-requirements':
       'You need Node.js 24.15.0 or later and npm to install and run current Askr projects; the CLI\'s `dist/cli.js` is a Node binary invoked as `askr`. Generated projects are ES modules (`"type": "module"`) and expect a modern bundler-driven dev workflow, which the CLI templates already wire up for you.',
     'verify-the-install':
@@ -1489,7 +1489,7 @@ export const headingOverrides: Readonly<
     'composition-root':
       'Askr apps have one obvious place where the app is assembled: the call to `createIsland`, `createSPA`, or `hydrateSPA` from `@askrjs/askr/boot`, which wires the route registry to a DOM root. Keep that call in one file rather than scattering startup configuration across the app.',
     'pages-and-routes':
-      "If the project uses `src/pages/**/_routes.tsx` (the CLI's default shape), keep new routes there rather than inventing a parallel route tree. A page file should own URL-reachable shell and composition; domain logic, queries, and mutations belong in a feature folder (e.g. `src/features/<feature>/`), not inline in the page.",
+      "Where routes live depends on which template you started from: the `spa` template nests route files as `src/pages/**/_routes.tsx`, while `startkit` (the CLI's actual default template) and `ssr`/`ssg`/`full-stack` use a flatter `src/router.tsx` plus `src/routes/*.ts`. Match whichever shape your generated project already has rather than assuming one convention across templates. A page or route file should own URL-reachable shell and composition; domain logic, queries, and mutations belong in a feature folder (e.g. `src/features/<feature>/`), not inline in the route.",
     'server-boundary':
       "Code that talks to request data, auth context, or a database belongs behind the server-facing entrypoints — `@askrjs/askr/ssr`'s `renderRouteRequest` and friends, or route `loader`s — not inside components that also render in the browser. Keep transport and DTO mapping in an adapters layer (`src/adapters/`) so a page component never imports a generated API client directly.",
     'tests-and-generated-artifacts':
@@ -1497,7 +1497,7 @@ export const headingOverrides: Readonly<
   },
   '/docs/guides': {
     'choose-a-guide':
-      "Each recipe in this section targets a specific shape of application: an SPA, an SSR app, an authenticated full-stack app, an API-only server, a static site, or an MCP server. Pick the one that matches your deployment target rather than reading them in order — `createSPA`, `hydrateSPA`, and `createStaticGen` are mutually exclusive entry points, not layers you stack. If you're not sure which fits, start with the SPA guide and add SSR or static generation later; the router and component code barely changes.",
+      "Each recipe in this section targets a specific shape of application: an SPA, an SSR app, an authenticated full-stack app, an API-only server, a static site, or an MCP server. Pick the one that matches your deployment target rather than reading them in order — `createSPA`, `hydrateSPA`, and `createIslands` are mutually exclusive client execution models, not layers you stack. `createStaticGen` is different: it's a build-time step, commonly paired with `hydrateSPA` (generate HTML, then hydrate it), not a fourth option in the same mutually-exclusive set. If you're not sure which fits, start with the SPA guide and add SSR or static generation later; the router and component code barely changes.",
     'keep-boundaries-explicit':
       "Askr's server layer asks you to build dependencies — database handles, auth resolvers, audit loggers — at a single composition root and pass them into route registration functions, not stash them on request context or reach for a service locator. Follow the same pattern on the client: build your route registry with `createRouteRegistry()` once, and pass query and mutation definitions in rather than constructing them ad hoc inside components. It costs a little boilerplate up front and pays off the first time you need to swap a real dependency for a test fake.",
     'production-finish-bar':
@@ -1507,21 +1507,21 @@ export const headingOverrides: Readonly<
   },
   '/docs/guides/accessibility': {
     'failure-states':
-      "A component that does not respond to its documented keyboard shortcuts (Space/Enter for `Button`, arrow keys for `Menu`/`RadioGroup`) is a contract violation, not a style choice — check the component's `.a11y.d.ts` file for the exact keys it commits to before assuming custom behavior is fine. Disabled elements must be genuinely out of the tab order (native `disabled` or `tabindex=\"-1\"` per the contract's `FOCUS_RULES`), so a visually-disabled button a screen reader user can still tab into and activate is a real bug. Overlay components that don't restore focus to their trigger on close break keyboard navigation for the next action — treat that as equivalent to a broken click handler.",
+      "A component that does not respond to its documented keyboard shortcuts (Space/Enter for `Button`, arrow keys for `Menu`/`RadioGroup`) is a contract violation, not a style choice — check the component's `.a11y.ts` source file (compiled to `.a11y.d.ts` in the published package, but the source you'd actually read is `.a11y.ts`) for the exact keys it commits to before assuming custom behavior is fine. Disabled elements must be genuinely out of the tab order (native `disabled` or `tabindex=\"-1\"`) — most contracts declare that explicitly through a `FOCUS_RULES` field, though not every one does, so check the specific contract rather than assuming the field is always there. A visually-disabled button a screen reader user can still tab into and activate is a real bug regardless. Overlay components that don't restore focus to their trigger on close break keyboard navigation for the next action — treat that as equivalent to a broken click handler.",
     'goal-and-architecture':
-      '`@askrjs/ui` bakes accessibility into each component as a documented, typed contract rather than leaving it to the consumer — components like `Button`, `Toast`, `Dropdown`, and `FocusScope` each export an `_A11Y_CONTRACT` constant (e.g. `BUTTON_A11Y_CONTRACT`) describing their ARIA role, keyboard activation keys, disabled-state attributes, and focus rules, following the WAI-ARIA APG patterns. Interaction behavior itself is centralized in shared foundations (the `pressable` foundation drives keyboard activation for `Button`, for instance) so every interactive component gets the same keyboard and focus handling instead of each component reimplementing it slightly differently.',
+      "`@askrjs/ui` bakes accessibility into each component as a documented, typed contract rather than leaving it to the consumer — components like `Button`, `Toast`, `Dropdown`, and `FocusScope` each export an `_A11Y_CONTRACT` constant (e.g. `BUTTON_A11Y_CONTRACT`) describing their ARIA role, keyboard activation keys, disabled-state attributes, and focus rules, following the WAI-ARIA APG patterns. Interaction behavior is centralized in shared foundations for most of the set (the `pressable` foundation drives keyboard activation for `Button`, for instance), which is what keeps behavior consistent across those components — but it's not a blanket guarantee every interactive component funnels through the same foundation, so verify the specific component you're composing with rather than assuming.",
     implementation:
-      'Use the components as designed rather than reaching for `asChild` unless you need to render a different host element — `asChild` mode preserves the child\'s role but switches disabled handling from the native `disabled` attribute to `aria-disabled` plus `tabindex="-1"`, since a non-native element has no built-in disabled state. Compound components like `Dialog`, `Popover`, and `Menu` build on `FocusScope` to trap and restore focus around overlays; let them own that behavior rather than manually managing `tabindex` and `document.activeElement` yourself. For custom interactive elements outside the component set, check the relevant `*_A11Y_CONTRACT` for the closest existing component as a reference for what role, keyboard support, and ARIA attributes are expected.',
+      "Use the components as designed rather than reaching for `asChild` unless you need to render a different host element — `asChild` mode preserves the child's role but switches disabled handling from the native `disabled` attribute to `aria-disabled` plus `tabindex=\"-1\"`, since a non-native element has no built-in disabled state. `Dialog` and `Popover` build on `FocusScope` to trap and restore focus around overlays; `Menu` doesn't — it manages roving focus through its own mechanism rather than `FocusScope`. Let the component you're using own its own focus behavior rather than manually managing `tabindex` and `document.activeElement` yourself, but don't assume every overlay-style component shares one implementation underneath. For custom interactive elements outside the component set, check the relevant `*_A11Y_CONTRACT` for the closest existing component as a reference for what role, keyboard support, and ARIA attributes are expected.",
     verification:
       "Assert against the exported `*_A11Y_CONTRACT` constants directly in tests — e.g. confirm a `Button`'s rendered `role` and keyboard handling match `BUTTON_A11Y_CONTRACT.ROLE` and `.KEYBOARD_ACTIVATION` — so a regression in the component's markup fails a test instead of only showing up in manual screen-reader testing. Run keyboard-only and screen-reader passes on any custom composition of overlay primitives (`Dialog` + `FocusScope`, `Popover` + `DismissableLayer`), since contracts describe the primitives correctly but your composition can still break focus order or announcement timing.",
   },
   '/docs/guides/add-ssr-to-an-spa': {
     'failure-states':
-      "On `hydrateSPA`, set `hydrate.verifyMarkup` during development to catch cases where server-rendered markup doesn't match what the client would produce — silent hydration mismatches are far more expensive to debug than a loud one. If a route has a `loader`, an error there should surface through the same `ErrorBoundary` your client-only errors go through, not a raw 500 with no fallback UI. Watch for routes with `auth` requirements: `RouteRenderOptions` and the SSG's `RouteConfig.auth` field both mark auth-gated routes as runtime-only by default, and SSR needs to resolve that auth context per request rather than reuse a cached one.",
+      "On `hydrateSPA`, set `hydrate.verifyMarkup` during development to catch cases where server-rendered markup doesn't match what the client would produce — silent hydration mismatches are far more expensive to debug than a loud one. If a route has a `loader`, an error there should surface through the same `ErrorBoundary` your client-only errors go through, not a raw 500 with no fallback UI. Watch for routes with `auth` requirements: the SSG's `RouteConfig.auth` field marks auth-gated routes as runtime-only by default — the equivalent `renderToString()`/`RouteRenderOptions` call for SSR doesn't carry its own `auth` field, so that auth-aware runtime-only exclusion is a `resolveRequest({ auth })` concern instead. Either way, SSR needs to resolve auth context per request rather than reuse a cached one.",
     'goal-and-architecture':
       "Adding SSR means the same route registry now renders on the server first and hydrates in the browser, instead of mounting cold. The client swaps `createSPA` for `hydrateSPA({ root, registry })`, and the server calls `renderToString()` with your route registry or a `RouteRenderOptions` object to produce the initial HTML. `@askrjs/vite`'s `askrServer({ entry })` plugin is the piece that's new here — it owns wiring your server entry module into the Vite dev/build pipeline.",
     implementation:
-      "Your HTML template needs exactly one `<!--askr-head-->` marker inside `<head>` and one `<!--askr-app-->` marker where the app mounts — the server plugin validates both and refuses to serve a template missing either one. `insertAskrFragment()` and `composeAskrHead()` are the low-level primitives it uses internally; you normally don't call them directly, you just point `askrServer({ entry: 'src/server/entry-server.ts' })` at a module that exports a request handler built with `createDocumentApp()`. Vite owns the document end to end: it preserves your authored head content and injects only Askr-owned title/meta/link/JSON-LD nodes at the marker.",
+      "Your HTML template needs exactly one `<!--askr-head-->` marker inside `<head>` and one `<!--askr-app-->` marker where the app mounts — the server plugin validates both and refuses to serve a template missing either one. `insertAskrFragment()` and `composeAskrHead()` are the low-level primitives the plugin uses internally to compose the document at those markers. Point `askrServer({ entry: 'src/server/entry-server.ts' })` at a module that exports a plain `ServerApp` — the plugin wraps it with `createDocumentApp()` internally, you don't call that function yourself. Vite owns the document end to end: it preserves your authored head content and injects only Askr-owned title/meta/link/JSON-LD nodes at the marker.",
     verification:
       "View source on a rendered route and confirm the markup is real content, not an empty shell waiting for JS — that's the entire point of doing this work. Throttle the network tab and watch hydration complete without a flash of unstyled or duplicated content. Then disable JavaScript entirely and confirm the initial page is still readable; if it isn't, something in your entry-server module is producing markup the static HTML path never exercises.",
   },
@@ -1541,7 +1541,7 @@ export const headingOverrides: Readonly<
     'goal-and-architecture':
       "`@askrjs/server` is a transport-neutral HTTP layer built directly on Web `Request`/`Response`, with no router-owned UI concerns — appropriate when you're shipping a JSON or OpenAPI backend with no Askr client attached. `createRouter()` plus `createServerApp({ router })` is the whole surface; literal route paths like `/objects/{*key}` infer their param types automatically, including named wildcards for capturing remaining path segments.",
     implementation:
-      "Use `ctx.bind<T>()` to read the request body once into a typed model — it merges JSON/form body, query string, and route params in that priority order, with route params always authoritative. For a published contract, build routes through `@askrjs/server/openapi`'s `createApi()` instead of the bare router: `api.group('/api/users').get('/{id}', handler).operationId(...).summary(...)` gives you the handler, dependency injection, and the OpenAPI document from one fluent definition, and `askr openapi --check` verifies the generated spec hasn't drifted. WebSocket routes are declared the same way with `router.ws(path, handler)`, with the runtime-specific upgrade supplied separately through a `WebSocketAdapter`.",
+      "Use `ctx.bind<T>()` to read the request body once into a typed model — it merges JSON/form body, query string, and route params, with route params overriding a same-named query value and query overriding a same-named body value, so precedence runs params, then query, then body, highest to lowest. For a published contract, build routes through `@askrjs/server/openapi`'s `createApi()` instead of the bare router: `api.group('/api/users').get('/{id}', handler).operationId(...).summary(...)` gives you the handler, dependency injection, and the OpenAPI document from one fluent definition, and `askr openapi --check` verifies the generated spec hasn't drifted. WebSocket routes are declared the same way with `router.ws(path, handler)`, with the runtime-specific upgrade supplied separately through a `WebSocketAdapter`.",
     verification:
       'Hit each probe path directly and confirm they return `503` when a dependency check returns `false` or throws, and `200` otherwise — this is easy to get backwards. Send a request with a duplicate query key and confirm `ctx.bind()` produces the expected array rather than silently dropping one value. If you generated an OpenAPI document, run `askr openapi --check` in CI so a handler change that alters the contract fails the build instead of shipping quietly.',
   },
@@ -1551,7 +1551,7 @@ export const headingOverrides: Readonly<
     'goal-and-architecture':
       "This shape combines `@askrjs/server` for HTTP with `@askrjs/auth` for identity resolution and `@askrjs/askr`'s router for auth-aware client routes. `createAuth({ sessions, principals, jwt })` builds one `AuthResolver` your server middleware calls per request to produce an `AuthContext`; the same shared requirement factories — `requireUser()`, `requireRole()`, `requirePermission()` — gate both server routes and client route policies, so you're not maintaining two separate permission systems.",
     implementation:
-      "On the server, attach `auth: requirePermission('reports:read')` to individual routes and read `ctx.auth.principal` in the handler; `createJwtValidator()` or a JWKS-backed validator plugs into `AuthOptions.jwt` if you're validating bearer tokens rather than cookies. On the client, `route(path, Component, { policy })` with `allow()`/`deny()`/`redirect()` decisions from your policy function keeps navigation from ever rendering a page the user shouldn't see, and `currentAuth()` gives components access to the resolved identity for the route currently rendering.",
+      "On the server, attach `auth: requirePermission('reports:read')` to individual routes and read `ctx.auth.principal` in the handler; `createJwtValidator()` or a JWKS-backed validator plugs into `AuthOptions.jwt` if you're validating bearer tokens rather than cookies. On the client, `route(path, Component, { policies: [...] })` — plural, an array of requirement functions, not a single `policy` field — with `allow()`/`deny()`/`redirect()` decisions from your policy functions keeps navigation from ever rendering a page the user shouldn't see, and `currentAuth()` gives components access to the resolved identity for the route currently rendering.",
     verification:
       'Test all three identity states explicitly: anonymous, authenticated without the required role, and authenticated with it — each should reach a different, correct outcome on both server routes and client-rendered pages. Confirm a token that fails `JwtValidator` verification is rejected with a clear error, not silently treated as anonymous. Finally verify that server-side auth decisions and client-side route policies agree; a route hidden in the nav but reachable directly by URL because only the client checked permissions is a real vulnerability, not just a UX gap.',
   },
@@ -1577,11 +1577,11 @@ export const headingOverrides: Readonly<
   },
   '/docs/guides/dashboards-charts-and-polling': {
     'failure-states':
-      "A polling query that errors mid-interval shouldn't tear down the chart and replace it with an error state on every failed poll — treat a transient poll failure differently from the query's initial load failure, or a flaky network turns a dashboard into a strobe light. Mixing primitives from two different `createPlot()` factories inside one `Root` is a type error by design, not a runtime footgun, so if you hit it the fix is consolidating on one factory per row shape rather than working around the types. Empty data (zero rows) should render an explicit empty state inside `Root`'s children, since an empty canvas with no rows looks identical to a still-loading one.",
+      "A polling query that errors mid-interval shouldn't tear down the chart and replace it with an error state on every failed poll — treat a transient poll failure differently from the query's initial load failure, or a flaky network turns a dashboard into a strobe light. Mixing primitives from two different `createPlot()` factories inside one `Root` is caught at runtime with a thrown `TypeError`, not statically by TypeScript — primitives from different factories can look structurally identical to the type checker, so don't rely on the compiler to catch this one; the fix if you hit the runtime error is the same, consolidating on one factory per row shape. Empty data (zero rows) should render an explicit empty state inside `Root`'s children, since an empty canvas with no rows looks identical to a still-loading one.",
     'goal-and-architecture':
       "Charts come from `@askrjs/charts`, a typed Canvas 2D plotting library with an immutable scene also available for SVG and data export — there's no separate headless/themed split here, `createPlot<Row>()` is the one entry point. A dashboard combines that with `@askrjs/askr/data`'s query layer for live numbers and `invalidateOnInterval()` for polling, so the chart re-renders whenever its backing query refetches rather than on its own timer.",
     implementation:
-      'Call `createPlot<RevenueRow>()` once at module scope to get a typed namespace, then compose marks inside `<RevenuePlot.Root data={...} rowKey="id" label="...">` — `Bar`, `Line`, and `Point` marks reference row fields by name, and the type system rejects a numeric channel bound to a string field. For live data, wrap the query driving the chart with `invalidateOnInterval({ ... })` so it refetches on a schedule, and remember to import `@askrjs/charts/styles` once at the app boundary since the structural and theme-token CSS ships separately from the JS. Import `@askrjs/charts/styles` from a CSS file, not a `.ts`/`.tsx` module — it\'s a CSS export, not a typed module.',
+      'Call `createPlot<RevenueRow>()` once at module scope to get a typed namespace, then compose marks inside `<RevenuePlot.Root data={...} rowKey="id" label="...">` — `Bar`, `Line`, and `Point` marks reference row fields by name, and the type system rejects a numeric channel bound to a string field. For live data, wrap the query driving the chart with `invalidateOnInterval(prefix, { intervalMs, ... })` — `prefix` is a required first argument naming which query keys to invalidate, not an options-object-only call — so it refetches on a schedule, and remember to import `@askrjs/charts/styles` once at the app boundary since the structural and theme-token CSS ships separately from the JS. Import `@askrjs/charts/styles` from a CSS file, not a `.ts`/`.tsx` module — it\'s a CSS export, not a typed module.',
     verification:
       "Watch a polling-driven chart across several interval ticks and confirm it actually updates when the underlying data changes, not just on first load — it's easy to wire `invalidateOnInterval` to the wrong query key and have the chart look live while it's actually static. Resize the container and confirm the plot redraws correctly rather than clipping, since Canvas-backed charts don't get free reflow the way DOM/SVG ones sometimes do. Finally check the page under a throttled connection to confirm polling backs off or queues sensibly rather than piling up overlapping requests.",
   },
@@ -1597,7 +1597,7 @@ export const headingOverrides: Readonly<
   },
   '/docs/guides/file-uploads-and-artifacts': {
     'failure-states':
-      "Enforce size and type limits before the request leaves the browser where you can — the client doesn't reject oversized files for you, so check `file.size` and `file.type` against your limits and surface a specific message rather than letting a large upload fail with a generic transport error partway through. On the server, a request that exceeds your platform's body-size limit or has an unexpected content type should return a typed error response (`context.badRequest(...)` or a codec-declared `413`/`415` in `.errors({...})`) that the client can decode, not a raw 500. Uploads with bodies are excluded from the client's automatic retry middleware by design, so a failed upload needs its own explicit retry action rather than silently resubmitting.",
+      "Enforce size and type limits before the request leaves the browser where you can — the client doesn't reject oversized files for you, so check `file.size` and `file.type` against your limits and surface a specific message rather than letting a large upload fail with a generic transport error partway through. On the server, a request that exceeds your platform's body-size limit or has an unexpected content type should return a typed error response (`context.badRequest(...)` or a codec-declared `413`/`415` in `.errors({...})`) that the client can decode, not a raw 500. An upload usually won't get auto-retried, but not because it's a special-cased exclusion — POST (the method most uploads use) simply isn't in the retry middleware's default eligible-methods list. If you build an upload endpoint on a retry-eligible method like PUT with a buffered (non-streaming) `FormData` body, it would actually be retried; only a genuinely streaming body is permanently excluded, since the middleware can't safely replay a stream it's already consumed. Either way, plan for a failed upload needing its own explicit retry action.",
     'goal-and-architecture':
       "Uploads in Askr go through the same typed-client machinery as any other request: `@askrjs/fetch` ships a `multipart()` codec that types request bodies as `FormData`, so a file upload endpoint is defined the same way as a JSON one, just with a different codec on the request side. There's no separate 'upload manager' abstraction — you build a `FormData`, attach it to a `post()` endpoint typed with `multipart()`, and get back the same discriminated `ClientResult` as any other call.",
     implementation:
@@ -1613,7 +1613,7 @@ export const headingOverrides: Readonly<
     implementation:
       "For a form-first flow, render `<ActionForm action={updateUser}>` with normal form fields inside it — no controlled-input plumbing required, since it's a real form submission the framework intercepts. For a programmatic flow (bulk actions, buttons instead of forms), call `action(updateUserAction)` to get back a `state: StateTuple<ActionStatus<TResult>>` and a `submit(input)` function you invoke directly; `ActionStatus` exposes `pending`, `result`, and `error` so you can drive UI off it without extra state. Either way, list the query keys the action should invalidate — that's what makes the table or detail view refresh after a successful mutation without you calling `invalidate()` by hand.",
     verification:
-      'Submit a form with missing required fields and confirm `fieldErrors` lines up with the actual field names in your schema, not just a generic failure state. After a successful mutation, confirm every query key listed in `invalidates` actually refetches — a key typo here is the single most common cause of "I saved it but the list didn\'t update." Then submit the same action twice quickly and confirm you get the behavior you intended, whether that\'s two writes or a debounced single one; nothing in `action()` serializes concurrent submissions for you.',
+      'Submit a form with missing required fields and confirm `fieldErrors` lines up with the actual field names in your schema, not just a generic failure state. After a successful mutation, confirm every query key listed in `invalidates` actually refetches — a key typo here is the single most common cause of "I saved it but the list didn\'t update." Then submit the same action twice quickly and confirm you get the behavior you intended: both requests actually fire — `action()` doesn\'t serialize or debounce them — but a generation counter discards the effect of anything but the latest response on UI state and invalidation, even though an earlier write already completed server-side. If your form needs to prevent the earlier write entirely (not just its UI effect), disable the submit control yourself while `pending` is true.',
   },
   '/docs/guides/generate-a-static-site': {
     'failure-states':
@@ -1621,9 +1621,9 @@ export const headingOverrides: Readonly<
     'goal-and-architecture':
       "`createStaticGen({ registry, outputDir })` from `@askrjs/askr/ssg` walks the explicit route registry and writes fully rendered HTML per route, plus a `metadata.json` describing the run. Routes carrying real request-auth requirements are excluded from prerendering by default, since there's no request to authenticate against at build time — those stay runtime-only unless you explicitly override that.",
     implementation:
-      'For parameterized paths like `/posts/{slug}`, supply an `entries()` function that returns one param map per page you want generated — `createStaticGen` expands the path template against each entry to produce concrete URLs. `dataOverrides` lets you feed deterministic seed data to resources during generation instead of hitting a live backend, and `assets` copies static files or directories alongside the generated HTML. `askr ssg --config <path> --output <dir> [--incremental]` runs the same generator from the CLI, with incremental mode using `invalidationKeys` and `changedRoutes` to skip unchanged pages.',
+      'For parameterized paths like `/posts/{slug}`, supply an `entries()` function that returns one param map per page you want generated — `createStaticGen` expands the path template against each entry to produce concrete URLs. `dataOverrides` lets you feed deterministic seed data to resources during generation instead of hitting a live backend, and `assets` copies static files or directories alongside the generated HTML. `askr ssg --config <path> --output <dir> [--incremental]` runs the same generator from the CLI, with `--changed-key`/`--changed-route` (forwarded internally as `changedKeys`/`changedRoutes`) marking what changed so incremental mode skips everything else.',
     verification:
-      "Confirm `result.successful` matches `result.totalRoutes` and inspect `result.routes[].reason` — `unchanged`/`cache-hit` routes on an incremental run should genuinely be unchanged, not silently stale because an invalidation key wasn't wired up. Open a generated file directly (not through a dev server) and confirm it's real standalone HTML with no unresolved markers. If you're shipping incrementally, re-run with a deliberately changed key and confirm exactly the expected routes rebuild, not the entire set.",
+      "Confirm `result.successful` matches `result.totalRoutes` and inspect `result.routes[].reason` — a real `RouteRenderReason` is one of `full`, `changed-key`, `changed-route`, `new-route`, `no-keys`, `unchanged`, `deleted`, or `runtime-only` (there's no `cache-hit` value; `unchanged` is what a correctly-skipped route reports). `unchanged` routes on an incremental run should genuinely be unchanged, not silently stale because a changed key wasn't wired up. Open a generated file directly (not through a dev server) and confirm it's real standalone HTML with no unresolved markers. If you're shipping incrementally, re-run with a deliberately changed key and confirm exactly the expected routes rebuild, not the entire set.",
   },
   '/docs/guides/loading-empty-error-and-pending-states': {
     'failure-states':
@@ -1633,17 +1633,17 @@ export const headingOverrides: Readonly<
     implementation:
       'For deferred route data, wrap the value in `<Resolve>` and use its pending/rejected render paths — `isDeferred(value)` lets shared components detect a still-pending `Deferred<T>` versus a resolved value. For query-backed views, read `refreshing` and `consistency` off the query object to show a subtle in-place indicator during a background refresh instead of tearing down the whole view; reserve the `@askrjs/ui` `Progress`/`ProgressCircle` components for genuine first-load states. Render the empty state as a real branch (`data.length === 0`) rather than letting an empty array fall through to whatever your list component does with nothing.',
     verification:
-      '`@askrjs/askr/testing` ships `mockQuery`/`queryState` helpers with `.loading()`, `.error(error, previousData)`, `.refreshing(data)`, and `.stale(data, reason)` constructors, so you can render each branch of a component against a synthetic query without touching the network. Write one test per branch — loading, empty, error, refreshing-with-stale-data — rather than one test that only checks the fresh-data case. For deferred loaders, resolve and reject the underlying promise in tests and assert `<Resolve>` renders the right branch for each outcome.',
+      '`@askrjs/askr/testing` ships `mockQuery`/`queryState` helpers with `.loading()`, `.error(error, previousData)`, `.refreshing(data)`, `.stale(data, reason)`, and `.pendingWrite(data)` constructors — the last of which is the one that actually exercises the `pending-write` consistency state mentioned above — so you can render each branch of a component against a synthetic query without touching the network. Write one test per branch — loading, empty, error, refreshing-with-stale-data, pending-write — rather than one test that only checks the fresh-data case. For deferred loaders, resolve and reject the underlying promise in tests and assert `<Resolve>` renders the right branch for each outcome.',
   },
   '/docs/guides/migration-from-react': {
     'failure-states':
-      "The most common porting mistake is treating a `state()` read like a React value snapshot and destructuring it once at the top of a function — that breaks reactivity, because the fine-grained system needs the read to happen where it's actually used (inside JSX or a `derive()`), not stored in a plain variable ahead of time. Similarly, effects that assumed React's re-render-then-effect ordering may need reworking against Askr's direct reactive update model, since there's no render phase to schedule after.",
+      "The most common porting mistake is assuming Askr is Solid-style fine-grained reactivity because `state()` reads like a signal — it isn't. A `state()` write re-runs the owning component function, the same as a React `setState` call re-runs the function component; reading a stale destructured value from an earlier render is a bug in both frameworks for the same reason. What actually differs from React is *when* that rerun is scheduled and *what happens to its output*: there's no render phase separate from commit to schedule effects after, and the returned JSX is diffed against the previous tree by Askr's own reconciler rather than React's.",
     'goal-and-architecture':
-      "The core mental shift moving from React is that Askr components are not re-executed on every state change — `state()` returns a `StateTuple` backed by fine-grained reactivity, and reading it inside JSX subscribes that specific expression to updates rather than re-running the whole component function. There's no dependency array to get wrong and no `useMemo`/`useCallback` tax for referential stability, because there's no re-render to guard against in the first place; `derive()` and `selector()` compute values reactively instead.",
+      "The core mental shift moving from React is smaller than the getter/setter syntax suggests: Askr components **do** re-execute on every state change that they subscribe to, the same as a React function component re-renders — `executeComponentSync` calls the component function again and its return value is reconciled against the previous output, patching only the DOM that changed. What's different is subscription granularity, not execution model: a component only re-runs when a `state()`/`derive()` value it actually read last render changes, so a state update doesn't cascade into re-running parent or sibling components the way a React state update re-renders a whole subtree by default. `derive()` still avoids a manual dependency array because its sources are tracked automatically, and `selector()` narrows a subscription down to one equality check so a list item doesn't re-run for changes to the parts of a selection it doesn't care about — but the component itself is re-run, not patched node-by-node the way Solid does it.",
     implementation:
-      "Where React code branches with `{condition && <X/>}` or ternaries, Askr provides `<Show when={...}>`, `<Match>`/`<Case>`, and `<For each={...}>` as components specifically because plain JS conditionals inside JSX don't get the same fine-grained update tracking — using them keeps updates scoped to just the changed piece of the tree. Data fetching maps `useQuery`-style hooks onto `createQuery`/`defineQuery`, which return a query object with `consistency`, `refreshing`, and stale-reason fields instead of a `{ data, isLoading, error }` tuple, and route-level data uses `defer()` plus `<Resolve>` in place of a Suspense boundary.",
+      "Where React code branches with `{condition && <X/>}` or ternaries, Askr provides `<Show when={...}>`, `<Match>`/`<Case>`, and `<For each={...}>` as components. For `Show`/`Match`, the main benefit over a plain conditional is mount/unmount lifecycle and a shared `fallback` shape, not a different update model — the containing component still re-runs and these still re-render their active branch along with it. `For` is the one control-flow component with real per-item behavior: it diffs children by key and patches, inserts, removes, or swaps individual DOM nodes without re-invoking the render callback for rows that didn't change, so a list update is closer to fine-grained than the rest of the runtime. Data fetching maps `useQuery`-style hooks onto `createQuery`/`defineQuery`, which return a query object with `consistency`, `refreshing`, and stale-reason fields instead of a `{ data, isLoading, error }` tuple, and route-level data uses `defer()` plus `<Resolve>` in place of a Suspense boundary.",
     verification:
-      "After porting a component, verify that updating one piece of state only touches the DOM nodes that actually depend on it — in React that's an optimization you'd check with a profiler, but in Askr's fine-grained model it's the expected baseline behavior and a good smoke test that the port is wired correctly. Re-run existing behavioral tests (form submission, list filtering, route navigation) unchanged where possible, since Askr's `@askrjs/askr/testing` mocks are designed to slot into the same assertion style as React Testing Library patterns.",
+      "After porting a component, don't expect to see updates land on individual DOM nodes without the owning component's function running again — profile it and you should see the component function re-invoked on each state change it subscribes to, just less often than in an equivalent unoptimized React tree, since Askr doesn't cascade a rerun into components that didn't read the changed value. `For`-rendered lists are the exception worth profiling separately: confirm updating one item in a large list only touches that item's DOM node instead of re-invoking every row's render callback. Re-run existing behavioral tests (form submission, list filtering, route navigation) unchanged where possible, since Askr's `@askrjs/askr/testing` mocks are designed to slot into the same assertion style as React Testing Library patterns.",
   },
   '/docs/guides/production-readiness': {
     'failure-states':
@@ -1659,9 +1659,9 @@ export const headingOverrides: Readonly<
     'failure-states':
       "An unauthenticated visitor hitting a `requireUser()` route should get a `redirect()` decision to your sign-in route, not a bare 401 page — use `safeRedirect(fallback)` to sanitize the `next` query param so you're not building an open redirect. A signed-in user without the right role or permission should get `forbidden()`, which is a distinct case from `unauthorized()` and should render differently (e.g., 'you don't have access' versus 'please sign in'). Rate limit auth endpoints through the `allowAttempt(context, operation, normalizedEmail)` hook in `registerAuthRoutes` so repeated failed logins return `429` via `AuthRouteError` instead of quietly retrying forever.",
     'goal-and-architecture':
-      "Route protection in Askr is split into two layers: `@askrjs/auth` resolves who is making the request into an `AuthContext` (principal, session, tenant, scopes), and the router's `RouteAuthOptions` decides what that context is allowed to see. A route's `auth.resolve` function runs `createAuth(...).resolve(request)` and returns the context; the route or group's `auth.check` (an `AuthRequirement`) inspects that context and returns an `AccessDecision`. Compose requirements with `requireUser()`, `requireRole('admin')`, `requirePermission('billing:write')`, `requireScope(...)`, `allOf(...)`, and `anyOf(...)` rather than writing ad-hoc boolean checks scattered through page components. Because the check runs before a route renders, denied users never see a flash of protected UI.",
+      "Route protection in Askr is split into two layers: `@askrjs/auth` resolves who is making the request into an `AuthContext` (`authenticated`, `principal`, `session`, `tenant`, `scopes`), and the router's `RouteAuthOptions` decides what that context is allowed to see. `RouteAuthOptions.resolve` runs `createAuth(...).resolve(request)` and returns the context — there's no separate `auth.check` field alongside it; the per-route requirement is a sibling option, just named `auth` on the route or group itself (an `AuthRequirement` that inspects the context and returns an `AccessDecision`), not nested under `.check`. Compose requirements with `requireUser()`, `requireRole('admin')`, `requirePermission('billing:write')`, `requireScope(...)`, `allOf(...)`, and `anyOf(...)` rather than writing ad-hoc boolean checks scattered through page components. Because the check runs before a route renders, denied users never see a flash of protected UI.",
     implementation:
-      "Build the resolver once with `createAuth({ sessions, principals, jwtCookie, tenant })` and pass it as the `auth` option in the second argument to `createRouteRegistry` (browser) or to `createServerApp` (server), so every matched route gets the same `AuthContext`. Inside a route's guard, return `allow()` to proceed, `deny('forbidden' | 'unauthorized' | ...)` for a hard stop, or `redirect(to, init)` to bounce anonymous users to a login page while preserving their intended destination. `unauthorized()`, `forbidden()`, and `notFound()` are shorthand `deny()` variants for the common HTTP-flavored cases. On the server, `registerAuthRoutes(api, { issuer, cookie, principalSchema, register, authenticate, allowAttempt })` wires up ready-made register/login endpoints that issue a signed cookie via a `TokenIssuer`, so you don't hand-roll session cookie handling.",
+      "Build the resolver once with `createAuth({ sessions, principals, jwtCookie, tenant })` and pass it as the `auth` option in the second argument to `createRouteRegistry` (browser) or to `createServerApp` (server), so every matched route gets the same `AuthContext`. Inside a route's guard, return `allow()` to proceed, `deny(401 | 403 | 404)` for a hard stop — the argument is a numeric HTTP status, not a string like `'forbidden'` — or `redirect(to, init)` to bounce anonymous users to a login page while preserving their intended destination. `unauthorized()`, `forbidden()`, and `notFound()` are shorthand `deny()` variants for the common HTTP-flavored cases (401, 403, 404 respectively). On the server, `registerAuthRoutes(api, { issuer, cookie, principalSchema, register, authenticate, allowAttempt })` wires up ready-made register/login endpoints that issue a signed cookie via a `TokenIssuer`, so you don't hand-roll session cookie handling — the 429 rate-limit path from a throttled `allowAttempt` goes straight to a `tooManyRequests()` response rather than through `AuthRouteError`, which exists for your own register/authenticate callbacks to throw instead.",
     verification:
       "Test each `AuthRequirement` directly by calling it with hand-built `AuthContext` fixtures (`{ authenticated, principal, session, tenant, scopes }`) and asserting on the returned `AccessDecision` — no HTTP server needed. For end-to-end coverage, hit protected routes with and without a valid session cookie and confirm you get `allow`, `redirect`, or the expected `deny` status, including the `already_authenticated` reason for routes like login that should reject already-signed-in users. Rotate a JWT's `kid` in your JWKS fixture and confirm `createJwtValidator` rejects it with `unknown_key` rather than silently accepting an unverifiable token.",
   },
@@ -1689,9 +1689,9 @@ export const headingOverrides: Readonly<
     'failure-states':
       "A test that mocks a query as `fresh` but never exercises the `loading` or `error` states is testing the easy 80% of the component; use the full `queryState` matrix deliberately so regressions in error and stale-data rendering get caught. Real timers (`setTimeout`, `requestAnimationFrame`) in tests are a common source of flakiness — prefer the `fx` primitives' explicit `cancel()`/`flush()` surface or a fake-timer setup over sprinkling `await timeout(50)` calls that pass locally and flake in CI.",
     'goal-and-architecture':
-      "`@askrjs/askr/testing` and `@askrjs/askr/fx` exist specifically so async and time-based code doesn't make your test suite flaky: `mockQuery`/`queryState` let you construct a query in any state (`fresh`, `loading`, `error`, `refreshing`, `stale`, `pendingWrite`) without a real network call, and the `fx` timing helpers (`debounce`, `throttle`, `retry`, `timeout`) are pure functions you can control directly rather than fighting real timers. The goal is that a test asserts on a specific, reproducible state rather than racing against real I/O or `setTimeout`.",
+      "`@askrjs/askr/testing` and `@askrjs/askr/fx` exist specifically so async and time-based code doesn't make your test suite flaky: `mockQuery`/`queryState` builder methods (`.loading()`, `.error()`, `.refreshing()`, `.stale()`, `.pendingWrite()`, or calling `mockQuery`/`queryState` directly for the fresh case) construct a query in any state without a real network call — these are builder names, not a literal list of `consistency` values; the actual `consistency` field is the narrower `'fresh' | 'stale' | 'refreshing' | 'pending-write'`, with `loading` as its own separate boolean and an errored query landing on `consistency: 'stale', staleReason: 'error'` rather than a `consistency: 'error'` value that doesn't exist. The `fx` timing helpers (`debounce`, `throttle`, `retry`, `timeout`) are pure functions you can control directly rather than fighting real timers, though their controls differ per function — see the implementation notes below.",
     implementation:
-      'Use `mockQuery.error(error, previousData)` and `mockQuery.stale(data, reason)` to exercise UI branches that are otherwise hard to hit reliably, and `createInvalidationRecorder()` to assert exactly which cache prefixes a mutation invalidated instead of re-running real queries to check for side effects. For route logic, `matchRoute(path, { registry })` and `getRouteWarnings({ registry })` let you assert on route resolution and catch route-collision warnings without booting a browser. For timing-dependent code built on `retry()` or `debounce()`, pass an injected `delayMs`/`backoff` or drive the returned `cancel()`/`flush()` handles directly rather than relying on wall-clock waits in tests.',
+      "Use `mockQuery.error(error, previousData)` and `mockQuery.stale(data, reason)` — `reason` here is limited to `'aborted' | 'inconsistent'`, since `'error'` has its own dedicated `.error()` constructor — to exercise UI branches that are otherwise hard to hit reliably, and `createInvalidationRecorder()` to assert exactly which cache prefixes a mutation invalidated instead of re-running real queries to check for side effects. For route logic, `matchRoute(path, { registry })` and `getRouteWarnings({ registry })` let you assert on route resolution and catch route-collision warnings without booting a browser. For timing-dependent code, the controls differ per function: `retry()` just returns a `Promise<T>` you await — there's no handle to drive, only its own `delayMs`/`backoff` options to inject; `debounce()`/`throttle()` return a function with a `.cancel()` you can call directly; `.flush()` isn't on either of those — it's only on the separate `debounceEvent`/`throttleEvent` variants, which is what you want if flushing a pending call synchronously in a test matters to you.",
     verification:
       "Treat `createInvalidationRecorder()` assertions as part of your contract for mutations — a mutation that's supposed to invalidate a `'users'` prefix should have a test asserting exactly that prefix appears in `recorder.calls`, not just that the mutation resolved. Snapshot route warnings from `getRouteWarnings({ registry })` in CI so a newly introduced route collision fails the build instead of surfacing as a confusing 404 in production.",
   },
@@ -1699,7 +1699,7 @@ export const headingOverrides: Readonly<
     'cookie-and-redirect-flows':
       'Cookie handling is opt-in. Pass `cookies: true` for a client-private standards-backed jar, or share a jar created by `createTestCookieJar()` across clients. Redirects are manual by default; use `redirect: "follow"` to exercise cookie capture, relative locations, method rewriting, and cross-origin credential stripping without allowing the test to reach the network.',
     'goal-and-architecture':
-      '`@askrjs/testing` drives an Askr server through its Web `Request`/`Response` boundary without opening a port. It is Node-only, runner-neutral, and deliberately returns native `Response` objects so Vitest, Node test, or another assertion library can inspect the same contract production adapters receive.',
+      "`@askrjs/testing` drives an Askr server through its Web `Request`/`Response` boundary without opening a port. It's built on standard Web APIs (`Request`/`Response`/`Headers`/`URL`/`ReadableStream`/`AbortController`) with no Node-specific dependency inside the package itself, so \"Node-only\" describes how it's published and tested today, not a hard technical restriction baked into the implementation. It's runner-neutral and deliberately returns native `Response` objects so Vitest, Node test, or another assertion library can inspect the same contract production adapters receive.",
     'request-injection':
       'Use `inject(target, input, init?)` for one request, `createTestRequest()` when you need explicit query, JSON, form, header, or abort setup, and `createTestClient(target, options?)` for repeated method calls against one base URL. The target can be a fetch-compatible object or a request handler function; thrown errors and streaming bodies pass through unchanged.',
     verification:
@@ -1739,9 +1739,9 @@ export const headingOverrides: Readonly<
     'authoring-operations':
       'createApi<Dependencies>({ info, securitySchemes, servers, validateResponses }) from @askrjs/server/openapi returns an ApiDefinition you register routes on with .get(), .post(), and the rest, chaining .pathParam(), .queryParam(), .jsonBody(), .ok(), .notFound(), and similar calls to attach both the handler and its documented shape in the same fluent statement. .access(requirement, security) attaches an AuthRequirement from @askrjs/auth alongside the OpenAPI security requirement it maps to, so authorization and documentation stay one declaration instead of two.',
     'client-generation':
-      'There is no separate code-generation step for consuming the API from this stack: the same defineApi() descriptors from @askrjs/fetch that back a typed client are written by hand to mirror the routes registered with createApi(), so both sides of the contract get independent, statically-checked types without a generated intermediate artifact. The OpenAPI YAML that askr openapi produces is still useful as a portable contract for external tooling or generators outside the Askr toolchain.',
+      "There are two paths to a typed client, and they're not the same thing: askr generate <openapi.yml> -o <dir> (from @askrjs/cli) reads an OpenAPI document and code-generates a defineApi()/createClient() client file directly, which is the fastest way to consume an API you don't own or didn't build with createApi(). For an API you do own, hand-writing the defineApi() descriptors to mirror the routes registered with createApi() is the alternative — both sides of the contract get independent, statically-checked types without depending on generated output staying in sync. The OpenAPI YAML that askr openapi produces is also useful as a portable contract for external tooling outside the Askr toolchain.",
     'generate-and-check':
-      'api.toOpenApiDocument() builds a deterministic, deeply frozen OpenAPI 3.1.2 document and refuses to generate one for an incomplete contract — missing or duplicate operationIds, undocumented responses, mismatched path parameters, wildcards, or unresolved schema and security references all fail the call outright. The askr openapi CLI command (askr openapi --entry src/api.ts --output ./openapi.yml) writes that document as YAML, and askr openapi --check performs no writes and exits unsuccessfully if the file is missing or differs by even one byte.',
+      "api.toOpenApiDocument() builds a deterministic, deeply frozen OpenAPI 3.1.2 document. Duplicate operationIds, mismatched path parameters, wildcards, and unresolved schema/security references always fail the call outright; missing operationIds and undocumented responses are only rejected when you set metadata: 'authored' on createApi() — by default those two are auto-inferred/defaulted instead of enforced, so don't rely on toOpenApiDocument() to catch them unless you've opted into authored mode. The askr openapi CLI command (askr openapi --entry src/api.ts --output ./openapi.yml) writes that document as YAML, and askr openapi --check performs no writes and exits unsuccessfully if the file is missing or differs by even one byte.",
     'json-schema-contract':
       'api.schema("Name", schema.object({...})) registers a reusable named component: its jsonSchema is projected into the document\'s components.schemas section, while the original @askrjs/schema parser keeps validating request and response bodies against it at runtime. Reusing the same registered schema across multiple routes keeps the generated document\'s component references consistent instead of duplicating inline schemas.',
   },
@@ -1753,7 +1753,7 @@ export const headingOverrides: Readonly<
     'result-handling':
       'Every client and createFetch() call returns a FetchResult instead of throwing. Check result.ok first, or switch on result.kind — "success", "http", "request", "network", "timeout", "abort", "decode", or "middleware" — to route to the right handling. unwrap(result) is there for call sites that prefer exceptions; it throws a FetchError carrying the original result on its .result property.',
     retries:
-      'Set timeout on the client or on an individual call to bound how long a request waits before failing with kind: "timeout". Actual retry behavior comes from @askrjs/fetch/middleware\'s retry() middleware, which by default retries GET, HEAD, PUT, DELETE, and OPTIONS on 408, 425, 429, 500, 502, 503, and 504, honoring a Retry-After header when the server sends one. Requests carrying a body are skipped by default since the middleware has no way to know they\'re safe to resend.',
+      "Set timeout on the client or on an individual call to bound how long a request waits before failing with kind: 'timeout'. Actual retry behavior comes from @askrjs/fetch/middleware's retry() middleware, which by default retries GET, HEAD, PUT, DELETE, and OPTIONS on 408, 425, 429, 500, 502, 503, and 504, honoring a Retry-After header when the server sends one. POST is excluded by default because it isn't in that default method list, not because of its body — a request with a buffered body (PUT included) is cloned and retried normally; only a streaming (ReadableStream) body is skipped, since the middleware can't safely replay a stream it's already consumed.",
   },
   '/docs/http-contracts/schemas': {
     'error-reporting':
@@ -1761,7 +1761,7 @@ export const headingOverrides: Readonly<
     'json-schema':
       "Each schema carries a readonly jsonSchema property alongside its safeParse() parser, so the exact declaration that validates a value at runtime is also what gets projected into OpenAPI documentation — there's no separate hand-written schema to keep in sync. schema.raw(jsonSchema, safeParse) exists for the rare case where an integration needs to own a custom format outside the built-in vocabulary, and it still requires a real parser rather than accepting a documentation-only stub.",
     'safe-parsing':
-      "Every Schema exposes safeParse(value), returning { success: true, data } on success or { success: false, issues } on failure — never a thrown exception. Objects built with schema.object() reject any key you didn't declare unless you pass additionalProperties: true or cover the extra keys with schema.record().",
+      "Every Schema exposes safeParse(value), returning { success: true, data } on success or { success: false, issues } on failure — never a thrown exception. Objects built with schema.object() reject any key you didn't declare unless you pass additionalProperties: true, or additionalProperties: <schema> to validate the extra keys against a schema instead of just allowing them through untyped. (schema.record() builds a separate standalone object-of-uniform-values schema — it isn't something you pass into additionalProperties.)",
     'schema-construction':
       'schema.object({...}), schema.string(), schema.number(), schema.integer(), schema.boolean(), schema.array(items), schema.enum([...]), schema.literal(value), schema.optional(s), schema.nullable(s), and schema.oneOf/anyOf/allOf(...) compose into a Schema<T> whose runtime type is recovered with InferSchema<typeof s>. schema.object() and schema.record() specifically return an ObjectSchema, the subtype required wherever a schema needs to describe a whole request object — route params, query, and operation inputs in @askrjs/server.',
   },
@@ -1771,15 +1771,15 @@ export const headingOverrides: Readonly<
     'define-endpoints':
       'get(path), post(path), and the other method builders return an EndpointBuilder that you refine by chaining .params<T>(spec?), .query<T>(spec?), .headers<T>(spec?), .body(codec), .returns(codec) or .returns(status, codec), and .errors({status: codec}). defineApi(endpoints, metadata?) accepts a plain object of these builders — or already-built EndpointDescriptor values — and returns the ApiDefinition that createClient() consumes.',
     'typed-input':
-      "Each client method takes a single input object assembled from whichever of params, query, headers, and body the endpoint declared. params and body are required whenever the endpoint has them; query and headers are optional unless every one of their fields is required. When an endpoint needs none of these, its method's input argument itself becomes optional, so client.health() can be called with no arguments at all.",
+      "Each client method takes a single input object assembled from whichever of params, query, headers, and body the endpoint declared. params and body are required whenever the endpoint has them; query and headers become required as soon as at least one of their fields is required, not only when every field is — an object with one required field and several optional ones still makes the whole query or headers object mandatory. When an endpoint needs none of these, its method's input argument itself becomes optional, so client.health() can be called with no arguments at all.",
     'typed-output':
-      'A call resolves to a discriminated ClientResult: a SuccessResult keyed by whichever status you registered with .returns(), an HttpResult keyed by whichever status or default you registered with .errors(), or a FailureResult for anything below the HTTP layer — a network error, a timeout, a caller abort, a decode failure, or a middleware error. Narrowing on result.ok or result.kind gives you the exact typed data or error shape for that branch without a cast.',
+      'A call resolves to a discriminated ClientResult: a SuccessResult keyed by whichever status you registered with .returns(), an HttpResult keyed by whichever status or default you registered with .errors(), or a FailureResult for anything below the HTTP layer — a request-building error (a missing path parameter, for instance), a network error, a timeout, a caller abort, a decode failure, or a middleware error. Narrowing on result.ok or result.kind gives you the exact typed data or error shape for that branch without a cast.',
   },
   '/docs/integrations': {
     'code-splitting':
       "MonacoEditor loads the Monaco namespace lazily by default rather than pulling it into your main bundle. Pass your own loadMonaco function, or an already-resolved monaco namespace via the monaco prop, if you want to control when and how the editor's (large) dependency is fetched. Lucide and logo imports are the opposite problem: each icon is its own module built with preserveModules and sideEffects: false, so a bundler drops anything you don't import without you doing anything special.",
     'editor-integration':
-      "@askrjs/monaco wraps Monaco Editor in a single component, MonacoEditor, instead of building a new editor abstraction on top of it. You get Monaco's real options object, model, and namespace back through props and refs, so anything you already know about Monaco's API still applies. The wrapper's job stops at mounting, disposing, and keeping the host div sized — everything else is Monaco.",
+      "@askrjs/monaco wraps Monaco Editor in a single component, MonacoEditor, instead of building a new editor abstraction on top of it. You get Monaco's real options object, model, and namespace back through props and refs, so anything you already know about Monaco's API still applies. The wrapper's job stops at mounting and disposing — there's no built-in resize handling to keep the host div sized as its container changes, so size the wrapper element yourself (CSS, a `ResizeObserver`, whatever fits your layout) rather than assuming the component tracks that for you.",
     'icons-and-logos':
       '@askrjs/lucide ships one Askr component per Lucide SVG, and @askrjs/logos does the same for a handful of brand marks (GitHub, Facebook, Microsoft, Apple, Google). Both packages generate their components with the same createIcon/createLogo helper over @askrjs/askr/foundations, so every icon and logo shares one SVG contract: consistent data attributes, size tokens, and accessibility behavior. Neither package ships a runtime registry or a string-keyed <Icon name="x" /> API — you import the named component you want.',
     'ssr-constraints':
@@ -1837,9 +1837,9 @@ export const headingOverrides: Readonly<
   },
   '/docs/mcp/http-transport': {
     deployment:
-      "Statefulness is opt-in: pass `stateful: true` to get session IDs, SSE push, and the DELETE-to-terminate flow; omit it and every POST is handled independently with `methodNotAllowed` returned for GET and DELETE. By default sessions live in an in-memory `Set`, which only works for a single process — supply your own `sessionStore` (matching the `create`/`has`/`delete` shape) if you're running more than one instance behind a load balancer. Set `allowedOrigins` and `allowedHosts` for any endpoint reachable from a browser to guard against DNS-rebinding-style requests, and tune `heartbeatInterval` (default 30 seconds) if intermediaries close idle connections faster than that.",
+      "Statefulness is opt-in: pass `stateful: true` to get session IDs, SSE push, and the DELETE-to-terminate flow; omit it and every POST is handled independently with `methodNotAllowed` returned for GET and DELETE. By default sessions live in an in-memory store that's bounded, not unlimited — a session expires after `sessionTtlMs` (30 minutes by default) and the store caps out at `maxSessions` (1,000 by default), returning `503` once that capacity is reached — and it only works for a single process either way, so supply your own `sessionStore` (matching the `create`/`has`/`delete` shape) if you're running more than one instance behind a load balancer. Set `allowedOrigins` and `allowedHosts` for any endpoint reachable from a browser to guard against DNS-rebinding-style requests, and tune `heartbeatInterval` (default 30 seconds) if intermediaries close idle connections faster than that.",
     'http-requests':
-      '`registerMcpRoutes(router, path, mcp, options)` mounts POST, GET, and DELETE handlers for `path` on an existing `Router`. POST requires `content-type: application/json`, an `accept` header including `application/json` or `text/event-stream` (or `*/*`), and a body under `options.maxRequestBytes` (1 MiB by default) — violations return `415`, `406`, and `413` respectively before the body is even parsed. Origin and host checks run first via `options.allowedOrigins` / `options.allowedHosts`, and requests with an unrecognized `mcp-protocol-version` header are rejected with `400` before reaching the MCP server.',
+      '`registerMcpRoutes(router, path, mcp, options)` mounts POST, GET, and DELETE handlers for `path` on an existing `Router`. POST requires `content-type: application/json`, an `accept` header that satisfies **both** `application/json` and `text/event-stream` (not either/or — a client that only sends `Accept: application/json` gets rejected too), and a body under `options.maxRequestBytes` (1 MiB by default) — violations return `415`, `406`, and `413` respectively before the body is even parsed. Origin and host checks run first via `options.allowedOrigins` / `options.allowedHosts`, and requests with an unrecognized `mcp-protocol-version` header are rejected with `400` before reaching the MCP server.',
     'protected-resource-metadata':
       'Pass `resource` (and optionally `authorizationServers`) in the options and the adapter automatically serves `GET /.well-known/oauth-protected-resource`, backed by `protectedResourceMetadata(resource, authorizationServers)`. The returned object is frozen and includes `resource`, `authorization_servers`, and a fixed `bearer_methods_supported: ["header"]`, matching the OAuth protected-resource metadata clients use for discovery. You can also call `protectedResourceMetadata` directly if you need to serve that document from a route the adapter doesn\'t own.',
     responses:
@@ -1857,13 +1857,13 @@ export const headingOverrides: Readonly<
   },
   '/docs/mcp/sessions': {
     expiry:
-      "There's no built-in TTL or idle-timeout on sessions — the default in-memory store keeps an ID valid until it's explicitly deleted via `DELETE path` or the process restarts. If you need sessions to expire on their own, implement that in a custom `sessionStore`: `has(id)` can return `false` once a session has aged out, which the adapter treats identically to an explicitly deleted session (`404 MCP session not found` on the next request).",
+      'The default in-memory session store does expire sessions on its own: `sessionTtlMs` (30 minutes by default) ages an ID out automatically, and `maxSessions` (1,000 by default) bounds how many can be live at once, returning `503` on a new session once that cap is hit. Once a session is gone — aged out, capacity-evicted, or explicitly deleted via `DELETE path` — the adapter treats it the same way: `404 MCP session not found` on the next request that references it. A custom `sessionStore` can implement its own eviction policy the same way, by having `has(id)` return `false` once you consider a session gone.',
     'horizontal-scaling':
       "The default in-memory session store and the server's own initialized-session map are both process-local, so a stateful deployment behind multiple instances needs sticky routing on `mcp-session-id`, a shared `sessionStore` implementation, or both. Because SSE channels (the `Map` of open `send` functions) are also held in the process that accepted the GET request, notifications for a given session can only be pushed by the instance holding that connection — routing by session ID isn't optional if you scale out and want push to keep working, not just request/response.",
     'session-identity':
       'In stateful HTTP mode, a session is identified purely by the `mcp-session-id` header: the server mints one with `crypto.randomUUID()` the moment it sees an `initialize` call with no existing session ID, and the client is expected to send that same header on every subsequent request. Stdio sessions work differently — `connectMcpStdio` generates a single random session ID per process connection and uses it for every message on that stream, since there\'s only ever one "client" per stdio pipe.',
     'state-ownership':
-      'Two separate stores back a session in stateful HTTP mode: the `McpSessionStore` (just `create`/`has`/`delete`, in-memory `Set` by default) tracks which session IDs are currently valid, while the MCP server itself keeps a parallel `Map` of initialized session state — negotiated `client` info, `clientCapabilities`, and `protocolRevision` — keyed by that same ID. The two are meant to stay in sync: a request is only dispatched once `sessions.has(id)` is true at the HTTP layer and the server-side session map shows `initialized: true`, and `terminateSession` clears the server-side entry and any SSE listeners for that ID.',
+      'Two separate stores back a session in stateful HTTP mode: the `McpSessionStore` (`create`/`has`/`delete`, backed by a TTL- and capacity-bounded in-memory `Map` by default — see `sessionTtlMs`/`maxSessions`) tracks which session IDs are currently valid, while the MCP server itself keeps a parallel map of initialized session state — negotiated `client` info, `clientCapabilities`, and `protocolRevision` — keyed by that same ID. The two are meant to stay in sync: a request is only dispatched once `sessions.has(id)` is true at the HTTP layer and the server-side map has an entry for that ID, and `terminateSession` clears the server-side entry and any SSE listeners for that ID.',
   },
   '/docs/mcp/sse-transport': {
     cancellation:
@@ -1911,7 +1911,7 @@ export const headingOverrides: Readonly<
     'mcp-adapter':
       '`connectMcpStdio(mcp, options)`, exported from `@askrjs/node/mcp`, runs an `@askrjs/server` `McpServer` over stdio instead of HTTP — the shape you need when the client is a local MCP host rather than a browser. You supply `dependencies` directly, along with optional `input`/`output`/`diagnostics` streams and an `auth` value or resolver function for authenticating the connection. The returned `McpStdioConnection` exposes a `closed` promise and a `close()` method, so you can shut the process down cleanly instead of just letting the pipes drop.',
     'server-adapter':
-      "`createNodeHandler(app, options?)` converts a `ServerApp` into a Node-compatible `(req, res, next?) => void` handler, so it drops straight into an existing `http.createServer` callback or a Connect/Express-style middleware chain. The optional `baseUrl` lets you tell the adapter where the app is mounted when it isn't serving from the root path. Everything else about request handling — routing, loaders, actions — stays inside the `ServerApp` itself; this layer just bridges Node's I/O types to it.",
+      "`createNodeHandler(app, options)` converts a `ServerApp` into a Node-compatible `(req, res, next?) => void` handler — `options` is a required second argument, not optional, even if you have nothing to configure and pass `{}`, so it drops straight into an existing `http.createServer` callback or a Connect/Express-style middleware chain. The optional `baseUrl` lets you tell the adapter where the app is mounted when it isn't serving from the root path. Everything else about request handling — routing, loaders, actions — stays inside the `ServerApp` itself; this layer just bridges Node's I/O types to it.",
     'signals-and-shutdown':
       "`serve` accepts a `signals` option — an array of `NodeJS.Signals` to listen for, or `false` to disable the behavior entirely — and installs handlers that call your app's optional `close()` and then resolve `serve`'s returned promise. `listen`, the lower-level function, instead accepts a plain `AbortSignal` if you want to control shutdown from your own lifecycle logic rather than OS signals. Either way, the goal is the same: give in-flight requests a chance to finish before the process exits.",
   },
@@ -1923,7 +1923,7 @@ export const headingOverrides: Readonly<
     redaction:
       "Because `TelemetryFields` is a closed interface rather than `Record<string, unknown>`, there's no field for request bodies, submitted form values, cookies, tokens, or arbitrary user attributes — you literally cannot pass them in through the typed API. The `route` field is meant to hold a route pattern like `/projects/{projectId}`, not the raw, potentially sensitive URL a user actually requested. This is what keeps span data safe to forward to third-party backends by default, without a separate scrubbing pass.",
     'spans-and-fields':
-      "The returned `Telemetry` object exposes one helper per lifecycle stage — `request`, `routeMatch`, `loader`, `action`, `apiOperation`, `queryPrefetch`, `ssrRender`, `viteDocument` — each wrapping a unit of work and recording it under a fixed `askr.*` `TelemetryOperation` name. `span(operation, fields, work)` is the general form underneath all of them if you need a custom operation. `TelemetryFields` is a narrow, typed shape — `requestId`, `traceId`, `route`, `action`, `status`, `durationMs` — so there's no open-ended bag of attributes to accidentally overload a span with.",
+      "The returned `Telemetry` object exposes one helper per lifecycle stage — `request`, `routeMatch`, `loader`, `action`, `apiOperation`, `queryPrefetch`, `ssrRender`, `viteDocument` — each wrapping a unit of work and recording it under a fixed `askr.*` `TelemetryOperation` name. `span(operation, fields, work)` is the general form underneath all of them, but `operation` isn't a free-form string — it's restricted to that same closed set of `askr.*` operation names, so there's no custom-operation escape hatch here despite `span` being the lower-level call. `TelemetryFields` is a narrow, typed shape — `requestId`, `traceId`, `route`, `action`, `status`, `durationMs` — so there's no open-ended bag of attributes to accidentally overload a span with; per-field redaction goes through `sanitizeField`, capped further by `maxFieldLength` (256 characters by default). Exceptions are the one thing NOT captured by default: `createTelemetry` only exports an exception on a span if you supply `sanitizeException` and it returns a value — without it, a thrown error inside `telemetry.span(...)` produces no exception record at all, not an auto-redacted one.",
   },
   '/docs/reference': {
     'api-index':
@@ -1949,7 +1949,7 @@ export const headingOverrides: Readonly<
     cancellation:
       'Every component receives an `AbortSignal` through its render context, and `ComponentInstance` holds the backing `AbortController` used to cancel in-flight work when the component unmounts. `resource()` (from @askrjs/askr/resources) is built on this — it passes the signal into your async function so a `fetch` or other cancelable call stops when the component goes away, instead of resolving into a dead component.',
     'delivery-parity':
-      "The same component tree renders through server rendering (SSR), static generation (SSG), and client hydration via a shared `DocumentRenderContext` (mode, url, params, seed, route) — the framework doesn't fork behavior between server and client render paths. Hydration reconciles the server-rendered markup against the client's first render pass rather than re-rendering from scratch, so component output needs to be stable across both invocations for hydration to succeed cleanly.",
+      "The same component tree renders through server rendering (SSR), static generation (SSG), and client hydration — the framework doesn't fork component behavior between server and client render paths. The two sides don't share one context type end to end, though: SSR and SSG document-wrapping share a `DocumentRenderContext` (mode: 'ssr' | 'ssg', url, params, seed, route), while the client's own render pass carries a separate `ActiveRenderContext` (mode: 'ssr' | 'spa') built specifically for hydration and client-only rendering. Hydration reconciles the server-rendered markup against the client's first render pass rather than re-rendering from scratch, so component output needs to be stable across both invocations for hydration to succeed cleanly.",
     ownership:
       'Reactive scope is threaded with `defineScope()`/`readScope()` rather than any global mutable state — `defineScope(defaultValue)` creates a `Scope<T>` you provide via a wrapping element, and `readScope()` reads the nearest value down the component tree. Internally each mounted component tracks its own `ownerFrame`, `stateValues`, and cleanup functions, so state and scope values are torn down with the instance that created them.',
     'render-contract':
@@ -1977,7 +1977,7 @@ export const headingOverrides: Readonly<
   },
   '/docs/reference/fx': {
     cleanup:
-      "The scheduling helpers — `debounce`, `throttle`, `raf` — all return a function augmented with `.cancel()`, so any pending invocation can be stopped explicitly, typically from a component's cleanup path. The event-oriented variants (`debounceEvent`, `throttleEvent`, `rafEvent`, `scheduleTimeout`, `scheduleIdle`, `scheduleRetry`) mirror this: each returns a handle with `cancel()` (and `debounceEvent` also exposes `flush()`) so you can tear down timers deterministically instead of letting them fire after a component is gone.",
+      "The scheduling helpers `debounce` and `throttle` return a function augmented with `.cancel()`, so any pending invocation can be stopped explicitly, typically from a component's cleanup path. `raf` doesn't follow this shape — it auto-coalesces to one `requestAnimationFrame` call per frame and returns a plain wrapped function with no `.cancel()` handle, so don't call `.cancel()` on it. The event-oriented variants (`debounceEvent`, `throttleEvent`, `rafEvent`, `scheduleTimeout`, `scheduleIdle`, `scheduleRetry`) mirror the debounce/throttle shape instead: each returns a handle with `cancel()` (and `debounceEvent` also exposes `flush()`) so you can tear down timers deterministically instead of letting them fire after a component is gone.",
     'clock-contract':
       "@askrjs/askr/fx is a pure, framework-independent set of async helpers — nothing in this subpath reads component state or lifecycle, so every function here works the same whether or not you're inside a render. `timeout(ms)` is the simplest building block: a promise-based delay you can `await` directly in tests or async flows.",
     'deterministic-tests':
@@ -2043,13 +2043,13 @@ export const headingOverrides: Readonly<
     'selection-checklist':
       "Reach for SSG when route output doesn't depend on the requesting user and can be precomputed with `createStaticGen`; reach for SSR (`renderRouteRequest`) when it does. Add streaming (`renderToStream`) once a page has slow data that shouldn't block the rest of the response, and add islands (`createIsland`) when only a fragment of an otherwise static page needs interactivity. Selective hydration is worth reaching for only after profiling shows hydration cost is the bottleneck — it's still a limited feature and shouldn't be the default choice.",
     'shared-application-model':
-      'Routes, components, and data loaders are defined once through the router DSL (`route()`, `group()`, `createRouteRegistry()`) and consumed by whichever renderer you wire up. `RouteHandler` and `RouteRegistry` show up identically in `@askrjs/askr/ssr`, `@askrjs/askr/ssg`, and `@askrjs/askr/boot`, which is why `resolveRequest`, `createStaticGen`, and `createSPA` all accept the same `registry` shape. Swapping SSR for SSG in production means changing which function calls your routes, not restructuring them.',
+      'Routes, components, and data loaders are defined once through the router DSL (`route()`, `group()`, `createRouteRegistry()`) and consumed by whichever renderer you wire up. `RouteRegistry` is defined and exported from `@askrjs/askr/router` alone — `resolveRequest`, `createStaticGen`, and `createSPA` each import it from there and accept the same `registry` shape, rather than each renderer declaring its own competing type. Swapping SSR for SSG in production means changing which function calls your routes, not restructuring them.',
   },
   '/docs/rendering/client-and-islands': {
     'client-boundaries':
       '`hydrateSPA` is the counterpart used when the server already produced markup: it takes the same route source shape as `createSPA` plus a `hydrate` block (`verifyMarkup`, `deferUntilIdle`, `deferBelowFold`, `foldThreshold`, `skipSelectors`) that controls how aggressively hydration is deferred. Both functions live under `@askrjs/askr/boot`, keeping the split between "boot fresh" and "attach to existing DOM" as two distinct, narrow entry points rather than one flag-driven function.',
     'island-ownership':
-      '`createIsland` enhances a single existing DOM node with one component and mounts once — no router involved. `createIslands` does the same for a list of `{ root, component }` pairs in one call and is described in the type as "the only public islands constructor," meaning multi-island pages should go through it rather than calling `createIsland` in a loop. Neither function touches routing state, so islands stay independent of whatever else is on the page.',
+      '`createIsland` enhances a single existing DOM node with one component and mounts once — no router involved. `createIslands` does the same for a list of `{ root, component }` pairs in one call and is documented on the function itself as "the only public islands constructor," meaning multi-island pages should go through it rather than calling `createIsland` in a loop. Neither function touches routing state, so islands stay independent of whatever else is on the page.',
     'spa-boot':
       '`createSPA` from `@askrjs/askr/boot` mounts a fully client-rendered app into a root element and initializes the router from the `registry` you built with `createRouteRegistry()`. It accepts `auth`, `scrollRestoration`, and `cleanupStrict` alongside the registry, and returns a `Promise<void>` that resolves once the initial route has mounted.',
     'when-to-choose-client-rendering':
@@ -2063,7 +2063,7 @@ export const headingOverrides: Readonly<
     'event-attachment':
       'Hydration walks the existing DOM tree and attaches event listeners to the elements the component tree expects, rather than replacing nodes outright. `hydrate.deferUntilIdle` and `hydrate.deferBelowFold` (with `foldThreshold`) on `HydrateSPAConfig` let you push that listener attachment to idle time or until an element scrolls into view, trading immediate interactivity for less main-thread work at load.',
     'mismatch-diagnostics':
-      "Set `hydrate: { verifyMarkup: true }` on `hydrateSPA` to have it check server-rendered markup against what the client would produce before attaching to it, surfacing a mismatch instead of silently adopting the wrong structure. `hydrate.skipSelectors` lets you exclude known-divergent regions (third-party widgets, ads) from that check so they don't produce false positives.",
+      'Set `hydrate: { verifyMarkup: true }` on `hydrateSPA` to have it check server-rendered markup against what the client would produce before attaching to it, surfacing a mismatch instead of silently adopting the wrong structure. `hydrate.skipSelectors` excludes known-divergent regions (third-party widgets, ads) from event-listener attachment and deferred-boundary tracking — it does not exempt those regions from the markup-verification check itself, so a third-party widget that mutates its own markup can still trigger a mismatch there even while listed in `skipSelectors`.',
   },
   '/docs/rendering/selective-hydration': {
     'boundary-selection':
@@ -2127,7 +2127,7 @@ export const headingOverrides: Readonly<
   },
   '/docs/routing/definitions-and-layouts': {
     'fallback-routes':
-      "`fallback(Component)` registers the component Askr renders when no other route matches, and it's marked internally with `isFallback: true` on its `RouteRecord` so the router treats it distinctly from an ordinary catch-all. You get exactly one fallback per `RouteRegistry` — it's meant to be your app's 404 page, not a general-purpose wildcard route. If you need a wildcard that still participates in normal matching and layout composition, use a `*` or `{*splat}` path segment on a regular `route()` instead.",
+      "`fallback(Component)` registers the component Askr renders when no other route matches, and it's marked internally with `isFallback: true` on its `RouteRecord` so the router treats it distinctly from an ordinary catch-all. You get one fallback per scope, not one per `RouteRegistry` overall — a root-level `fallback()` is your app's 404 page, and each `page()` can additionally declare its own `fallback()` scoped to that page's own path prefix (nesting one inside a `group()` instead of directly in a page scope throws). It's meant for 404-style pages, not a general-purpose wildcard route — if you need a wildcard that still participates in normal matching and layout composition, use a `*` or `{*splat}` path segment on a regular `route()` instead.",
     'groups-and-layouts':
       "A layout is just a component with a `children` prop, attached to a group via `GroupHelperOptions.layout` or to a page via the layout argument on `page()`. Askr stores it as a `LayoutScopeRecord` and composes it automatically at render time — you never call the layout component yourself. Layout composition happens outside the page chain: pages inside a group render first through `Outlet`, and the layout wraps that result, so a loading state or error inside a page doesn't require the layout to know anything about it.",
     'nested-pages':
@@ -2147,9 +2147,9 @@ export const headingOverrides: Readonly<
   },
   '/docs/routing/navigation-and-url-state': {
     'active-route-state':
-      '`currentRoute()` returns a `RouteSnapshot` with the matched `path`, typed `params`, `query`, `hash`, and a `matches` array covering every layout and page that contributed to the current render — useful for building breadcrumbs or highlighting the active section of a nav. It\'s synchronous and reflects whatever finished resolving most recently, so call it during render rather than caching it across navigations. Pair it with `aria-current="page"` on `Link` when you need visually distinct "you are here" styling that also communicates correctly to screen readers.',
+      '`currentRoute()` returns a `RouteSnapshot` with the matched `path`, typed `params`, `query`, `hash`, and a `matches` array covering every layout and page that contributed to the current render — useful for building breadcrumbs or highlighting the active section of a nav. It\'s synchronous, reflects whatever finished resolving most recently, and must be called during component render execution — calling it from outside render (a plain callback, module scope) throws rather than returning a stale snapshot. Pair it with `aria-current="page"` on `Link` when you need visually distinct "you are here" styling that also communicates correctly to screen readers.',
     'history-and-scroll':
-      "`NavigateOptions.history` is `'push'` or `'replace'`, controlling whether the navigation adds a new browser-history entry or overwrites the current one; `replace: true` is shorthand for the same thing. Scroll behavior is separate: `NavigationScrollBehavior` (`'top'` or `'preserve'`) governs what a fresh navigation does, while `HistoryScrollBehavior` (`'restore' | 'top' | 'preserve'`) governs back/forward navigation specifically, since users generally expect scroll position to come back on browser-back but not on a forward click to a new page. Both are configurable per-navigation through `ScrollRestorationOptions` rather than being a single global switch.",
+      "`NavigateOptions.history` is `'push'` or `'replace'`, controlling whether the navigation adds a new browser-history entry or overwrites the current one; `replace: true` is shorthand for the same thing. Scroll behavior is separate: `NavigationScrollBehavior` (`'top'` or `'preserve'`) governs what a fresh navigation does, while `HistoryScrollBehavior` (`'restore' | 'top' | 'preserve'`) governs back/forward navigation specifically, since users generally expect scroll position to come back on browser-back but not on a forward click to a new page. `ScrollRestorationOptions` is app-wide configuration set once through `configureScrollRestoration()`, not a per-navigation option — `NavigateOptions` itself has its own narrower `scroll` field for overriding forward-navigation behavior on a single call, but there's no equivalent per-call override for back/forward scroll restoration.",
     'link-and-navigate':
       '`Link` renders a real `<a>` element and intercepts clicks to route through `navigate()` instead of a full page load, while still respecting middle-click, Ctrl/Cmd-click, Shift-click, and Alt-click so the native "open in new tab" and "download" behaviors keep working. It accepts either an `href` string or a typed `to` destination — never both — plus the usual `rel`, `target`, and `aria-current` props. For navigation triggered from code rather than a click — after a form submits, say — call `navigate(path, options)` directly with the same `history` and `scroll` options `Link` uses internally.',
     'search-parameters':
@@ -2161,7 +2161,7 @@ export const headingOverrides: Readonly<
     'route-destinations':
       "Building a link target from a typed route uses `to(routeRef, params, search?)`, which returns a `RouteDestination` — just `{ href: string }` — built from the `RouteRef` that `route()` returned when the route was declared. Because the `RouteRef` carries its param and search types, passing the wrong param name or an invalid search key is a type error before it's a broken link. Pass that `RouteDestination` to `Link`'s `to` prop, or to `navigate()`, instead of hand-assembling a URL string with template literals.",
     'static-and-dynamic-segments':
-      'Askr parses each path into `ParsedSegment` entries tagged as `static` (a literal like `users`), `param` (a `{name}` capture), `wildcard` (a bare `*` matching exactly one segment), `splat` (`{*name}`, capturing the rest of the path into one named param), or `catchall` (a trailing `/*`). This parsing happens once when the route is registered, not on every navigation, and the resulting segment list is what route ranking and matching both run against. Mixing kinds is normal — `/files/{*path}` combines a static prefix with a splat to capture an arbitrarily deep file path in a single param.',
+      "Askr parses each path into `ParsedSegment` entries tagged as `static` (a literal like `users`), `param` (a `{name}` capture), `wildcard` (a bare `*` matching exactly one segment, usable after a static prefix like `/posts/*`), `splat` (`{*name}`, capturing the rest of the path into one named param), or `catchall` — reserved specifically for the bare path `/*` on its own, ranked lowest of all of them and what `fallback()` registers under the hood, not a general 'trailing /*' pattern you'd write yourself on an ordinary route. This parsing happens once when the route is registered, not on every navigation, and the resulting segment list is what route ranking and matching both run against. Mixing kinds is normal — `/files/{*path}` combines a static prefix with a splat to capture an arbitrarily deep file path in a single param.",
     'typed-parameters':
       "`RoutePathParams<Path>` is a template-literal type that extracts param names straight from the path string, so `route('/teams/{teamId}/members/{memberId}', ...)` gives your component a `{ teamId: string; memberId: string }` prop type without you declaring it separately. If a component you're wiring up already has its own prop shape, Askr checks compatibility for you via `CompatibleRouteComponent`, so a mismatched param name fails at the `route()` call site rather than silently passing `undefined` at runtime. All path params come through as strings — parsing a numeric ID or a date out of one is on you, same as reading `location.search`.",
   },
@@ -2169,9 +2169,9 @@ export const headingOverrides: Readonly<
     'dynamic-metadata':
       "`RouteMetaSource` is `RouteMeta | ((context) => RouteMeta | PromiseLike<RouteMeta>)`, so metadata can be computed from the resolved `RouteContext` — pulling a post title out of loader data, for instance — and it can be async if that computation needs to await something. Metadata sources stack: a route's `metaChain` collects sources from outermost group down to the specific route, and `resolveRouteMeta(record, context)` merges them in that order into the final `RouteMeta` used for the response or the client update.",
     'head-reconciliation':
-      'After a client-side navigation, `reconcileRouteMeta(meta, target?)` updates only the `<head>` nodes Askr owns — replacing the title, meta tags, and links from the previous route with the new ones — without touching tags injected by other scripts or the initial HTML shell. That scoping matters for SPA navigations specifically: a full page load already gets the right head from SSR/SSG output, so reconciliation only runs on the client-side transition path.',
+      "After a client-side navigation, `reconcileRouteMeta(meta, target?)` updates only the `<head>` nodes Askr owns — replacing the title, meta tags, and links from the previous route with the new ones — without touching tags injected by other scripts or the initial HTML shell. **This is a client-only mechanism.** `resolveRouteMeta`/`serializeRouteMeta`/`reconcileRouteMeta` are only ever called from the router's client-side navigation code — there's no equivalent wiring in `@askrjs/askr/ssr` or `@askrjs/askr/ssg`, and `DocumentRenderContext` doesn't carry a resolved `RouteMeta` at all. Getting `RouteMeta` into your SSR/SSG document's `<head>` is on you: read it yourself (via the matched route's `meta`/`metaChain`) inside your `document: DocumentRenderer` function, or accept that the initial HTML shell's head only reflects what your document renderer put there, independent of this reconciliation mechanism.",
     'ssg-metadata':
-      "For statically generated routes, `RouteOptions.entries` returns the list of param combinations to pre-render, and metadata for each generated page resolves the same way it would for SSR — through the route's `metaChain` and `resolveRouteMeta()` — so a dynamic `RouteMeta` function keyed on `params.slug` produces correct per-page titles and descriptions across every entry. `serializeRouteMeta(meta)` turns the resolved `RouteMeta` into the actual head markup written into each generated HTML file.",
+      "For statically generated routes, `RouteOptions.entries` returns the list of param combinations to pre-render. `resolveRouteMeta()` and `serializeRouteMeta()` are real, callable functions that will resolve a dynamic `RouteMeta` against `params.slug` and serialize it to markup — but SSG doesn't call them for you: `createStaticGen` never references either function internally, so nothing wires a route's `metaChain` into the generated HTML's `<head>` automatically. If you want per-page titles and descriptions in generated output, call `resolveRouteMeta`/`serializeRouteMeta` yourself from inside your `document: DocumentRenderer` (the same one SSR uses), passed the route and params for the entry currently being rendered.",
     'static-metadata':
       "`RouteMeta` covers `title`, `description`, `canonical`, `robots`, `openGraph`, `links`, `jsonLd`, and an `html` object for `lang`/`dir` — the fields that end up in `<head>` or on the document element. For a page whose metadata never changes, just pass the object directly as `RouteOptions.meta` or `PageHelperOptions.meta`; there's also a plain `title` shorthand on `RouteOptions` for the common case where only the tab title matters.",
   },
@@ -2181,13 +2181,13 @@ export const headingOverrides: Readonly<
     'context-first-handlers':
       'Every handler and every Middleware receives a single ServerContext argument instead of separate request/response objects — request, url, params, headers, query, state, auth, and an AbortSignal all live on ctx. Dependencies like a database client are deliberately not part of that context; the README shows creating them at your composition root and passing them into route registration functions, keeping ctx reserved for request-scoped data. Because the context also carries every response helper (ctx.ok, ctx.notFound, and so on), a handler can build its whole response without importing anything else.',
     'production-boundary':
-      'ServerAppOptions accepts an onError(error, context) hook that runs when a handler throws, so you control exactly what an unhandled exception turns into instead of leaking a stack trace to the client. The OpenAPI layer defaults to validateResponses: false and only turns response validation on when you explicitly opt in outside production, because checking every response against its schema costs real time on every request. The package is published in the 0.0.x line, so pin versions and review release notes before moving a production app between versions.',
+      "ServerAppOptions accepts an onError(error, context) hook that runs for an unhandled exception a handler or middleware throws, so you control what most errors turn into instead of leaking a stack trace to the client — but it's the fallback, not the only path: a few framework-recognized failures (an oversized request body, a malformed path parameter, a ctx.bind() failure) are converted to a fixed problem+json response before onError is ever consulted, so don't rely on it to customize those specific cases. The OpenAPI layer defaults to validateResponses: false and only turns response validation on when you explicitly opt in outside production, because checking every response against its schema costs real time on every request. The package is published in the 0.0.x line, so pin versions and review release notes before moving a production app between versions.",
     'response-helpers':
       'ctx.ok(), ctx.notFound(), ctx.created(), ctx.problem(), and the rest of the status-code helpers are methods on ServerContext, so a handler returns a Response by calling ctx.<name>(value) rather than constructing new Response(...) by hand. The same functions — json, text, redirect, setCookie, clearCookie, challenge, and friends — are also exported standalone from @askrjs/server for use outside a request context, such as inside an onError handler. setCookie() and clearCookie() take a Response and return a modified one; per the README they only touch response headers and have no opinion on session storage or credential validation.',
   },
   '/docs/server/context-and-responses': {
     'problem-details':
-      'ctx.problem(status, detail, options) produces an RFC 7807-shaped application/problem+json body — type, title, status, and an optional detail and instance — with anything extra folded in through options.extensions. The convenience helpers like notFound() and unprocessableEntity() are thin wrappers around the same machinery with sensible type and title defaults already filled in. The binding layer uses this format automatically: invalid JSON, a non-object JSON root, malformed multipart data, or reading an already-consumed body all produce a 400 application/problem+json response without any handler code involved.',
+      'ctx.problem(status, detail, options) produces an RFC 9457-shaped application/problem+json body — type, title, status, and an optional detail and instance — with anything extra folded in through options.extensions. The convenience helpers like notFound() and unprocessableEntity() are thin wrappers around the same machinery with sensible type and title defaults already filled in. The binding layer uses this format automatically: invalid JSON, a non-object JSON root, malformed multipart data, or reading an already-consumed body all produce a 400 application/problem+json response without any handler code involved.',
     'request-state':
       'ctx.state is a plain Record<string, unknown> that exists purely for middleware to pass data forward to the next middleware or the final handler — request-id middleware, for example, might stash a generated ID there. It has no built-in shape or validation; whatever one middleware writes to it, a later stage reads back with its own type assumptions. Because state lives on the context object for the duration of a single request, it never leaks between requests the way a module-level variable would.',
     'response-helpers':
@@ -2209,7 +2209,7 @@ export const headingOverrides: Readonly<
     'cookies-and-redirects':
       'ctx.setCookie(response, name, value, options) and ctx.clearCookie(response, name, options) both take a Response and return a new one with the Set-Cookie header attached — CookieOptions covers domain, path, expires, maxAge, httpOnly, secure, and sameSite ("strict" | "lax" | "none"). Per the README, these only modify the response; they don\'t establish a session or check a password, so pairing setCookie() with an actual auth check is on the caller. ctx.redirect(location, status?) defaults to 302 but accepts 301, 303, 307, or 308, and ctx.challenge(options) is the companion for auth failures — it sets WWW-Authenticate with a configurable scheme and realm and returns 401 by default, or 407 on request.',
     'error-handling':
-      "ServerAppOptions.onError(error, context) is the single place an unhandled exception from any handler or middleware ends up — return a Response from it and that's what the client receives, instead of the framework's default. Because ctx.problem() and its status-helper wrappers are available on the context passed into onError, a typical implementation just logs the error and returns ctx.internalServerError() or a custom problem+json body. The canonical application path registers routes through a Router; defineRoutes() and raw ApiRoute[] values remain lower-level compatibility inputs.",
+      "ServerAppOptions.onError(error, context) is where an unhandled exception from a handler or middleware ends up — return a Response from it and that's what the client receives, instead of the framework's default. It's not the only place errors are turned into responses, though: a handful of framework-recognized failures (an oversized body, a malformed path parameter, a failed ctx.bind()) are converted to a fixed problem+json response before onError runs at all, so treat it as the catch-all for your own thrown errors rather than the single funnel for every failure. Because ctx.problem() and its status-helper wrappers are available on the context passed into onError, a typical implementation just logs the error and returns ctx.internalServerError() or a custom problem+json body. The canonical application path registers routes through a Router; defineRoutes() and raw ApiRoute[] values remain lower-level compatibility inputs.",
     'middleware-order':
       "A Middleware is (ctx, next) => Response | Promise<Response> — call next() to continue down the chain, or return your own Response to short-circuit it. Middleware registered with router.use(...) runs in the order it's added, and because each layer wraps the next one, code written before next() runs on the way in and code written after it runs on the way out, once the inner handler has produced a response. Route-level middleware from ApiRouteOptions.middleware runs closer to the handler than anything registered on the router itself.",
     'security-headers':
@@ -2247,7 +2247,7 @@ export const headingOverrides: Readonly<
   },
   '/docs/server/server-actions': {
     'action-responses':
-      "An ActionHandler returns an ActionOutcome — an optional redirect location, an optional result payload, or both — rather than constructing a Response itself; the framework turns that outcome into the right wire format for whichever kind of request triggered it. defineServerActions({dependencies}, ...entries) captures every handler's dependencies once, up front, and the returned ActionRegistry is frozen — there's no mutation API for adding entries afterward. Enhanced, JavaScript-driven action() calls get back the versioned JSON envelope plus query prefix invalidations mentioned in the README, while unenhanced form posts get the redirect-or-rerender behavior described above.",
+      "An ActionHandler returns an ActionOutcome — an optional redirect location, an optional result payload, optional cookie instructions to set or clear, or any combination of those — rather than constructing a Response itself; the framework turns that outcome into the right wire format for whichever kind of request triggered it. defineServerActions({dependencies}, ...entries) captures every handler's dependencies once, up front, and the returned ActionRegistry is frozen — there's no mutation API for adding entries afterward. Enhanced, JavaScript-driven action() calls get back the versioned JSON envelope plus query prefix invalidations mentioned in the README, while unenhanced form posts get the redirect-or-rerender behavior described above.",
     'binding-and-validation':
       'handleAction(descriptor, handler) pairs an ActionDescriptor from @askrjs/askr/actions with an ActionHandler function; the descriptor defines and validates the input shape, so the handler itself always receives validated input, never a raw FormData or JSON body. ActionHandlerContext gives the handler request, url, params, auth, policies, and an AbortSignal — the same shape as ServerContext minus the response helpers, since an action returns an ActionOutcome instead of a Response directly. When validation fails, the registry reports it as an ActionExecution of kind "invalid" carrying the raw submitted values, a list of Issue objects, and fieldErrors keyed by field name — exactly what a native rerender or an enhanced JSON response needs to show errors next to the right inputs.',
     'native-action-requests':
@@ -2261,7 +2261,7 @@ export const headingOverrides: Readonly<
     'generated-artifacts':
       "CLI commands write real, ready-to-run files rather than TODO-filled stubs. askr create produces a full project tree plus .askr/blueprint.json and .askr/builder-brief.md describing which template was picked and why, and askr add page/add action register new files directly into src/pages/app/_routes.tsx or src/pages/public/_routes.tsx depending on --branch. askr openapi writes a deterministic YAML document by loading a TypeScript module's default export and calling its toOpenApiDocument() method, and askr ssg writes a static HTML tree plus an incremental-build manifest. All of these writes are atomic, so a crash mid-run doesn't leave a half-written artifact behind.",
     'safe-updates':
-      "askr outdated, update, and upgrade are read-only discovery followed by opt-in write: outdated lists what's available without touching anything, update applies only safe range changes, and upgrade additionally allows next-version major bumps for stable packages and breaking minor bumps for 0.x packages. Upgrade enforces peer requirements by default; --force/-f deliberately selects tag targets without those compatibility checks. None of the three commands touches a lockfile, runs installs or lifecycle scripts, or edits overrides, resolutions, catalogs, or packageManager metadata; they only rewrite dependency version strings in package.json.",
+      "askr outdated, update, and upgrade are read-only discovery followed by opt-in write: outdated lists what's available without touching anything, update applies only safe range changes, and upgrade additionally allows major bumps for stable packages and breaking minor bumps for 0.x packages — targeting whatever version the registry's latest tag currently resolves to, with no cap at one major version per run, so a 1.x package can jump straight to 4.x in a single upgrade if that's what's published. Upgrade enforces peer requirements by default; --force/-f deliberately selects tag targets without those compatibility checks. None of the three commands touches a lockfile, runs installs or lifecycle scripts, or edits overrides, resolutions, catalogs, or packageManager metadata; they only rewrite dependency version strings in package.json.",
     'vite-integration':
       "@askrjs/vite supplies the plugin pair that teaches a normal Vite project Askr's JSX and template conventions: askr() handles the browser build, and askrServer({ entry }), imported from the @askrjs/vite/server subpath, wires up server rendering. Both plugins expose only a stable name field in their published types (askr:vite and askr:server) rather than Vite's own recursive Plugin type, so a bundler like vite-plus that inspects plugin arrays doesn't end up comparing two different copies of that type. In practice you list both in vite.config.ts: plugins: [askr(), askrServer({ entry: 'src/server/entry-server.ts' })].",
   },
@@ -2293,7 +2293,7 @@ export const headingOverrides: Readonly<
     'product-prompts':
       'askr create --prompt "<description>" [name] skips template selection entirely: the CLI reads the prompt text and deterministically picks the closest-fitting template, then writes .askr/blueprint.json and .askr/builder-brief.md capturing that decision so you (or an agent) can see the reasoning afterward. The same flag works alongside an explicit template name if you want to pin the template but still get a tailored blueprint. This is the path the docs recommend when you\'re not sure whether you need SSR, SSG, or a full-stack app yet.',
     'published-templates':
-      "askr create [template] <name> accepts one of five bundled templates: startkit, spa, ssr, ssg, and full-stack, stored under the package's templates/ directory. Passing no template name at all triggers interactive or prompt-based selection instead. Each template is a complete, runnable project -- there's no post-generation step where you delete demo code before it resembles a real app.",
+      "askr create [template] <name> accepts one of five bundled templates: startkit, spa, ssr, ssg, and full-stack, stored under the package's templates/ directory. Interactive template selection only triggers when the name is also omitted (`askr create` with nothing) or when `--prompt` is passed — running `askr create my-app` with a name but no template silently defaults to startkit rather than asking, so name it explicitly if you don't want the default. Each template is a complete, runnable project -- there's no post-generation step where you delete demo code before it resembles a real app.",
   },
   '/docs/tooling/dependency-updates': {
     outdated:
@@ -2303,7 +2303,7 @@ export const headingOverrides: Readonly<
     update:
       "askr update applies only safe version-range changes -- bumps that stay within a dependency's already-declared range style. It preserves whichever range style a dependency was already pinned with (exact, caret, tilde, or x-range), can widen one bounded interval, and updates only the highest clause of a simple OR union; anything more complex than that is reported as manual rather than guessed at.",
     upgrade:
-      'askr upgrade does everything update does, plus it permits next-version major bumps for stable (1.0+) packages and breaking minor bumps for 0.x packages, since semver treats 0.x minor bumps as potentially breaking. By default it enforces peer compatibility across selected packages and leaves incompatible targets for manual review. Pass --force/-f only when you intentionally want tag targets without peer compatibility checks, then install and validate the resulting package set yourself.',
+      "askr upgrade does everything update does, plus it permits major bumps for stable (1.0+) packages and breaking minor bumps for 0.x packages, since semver treats 0.x minor bumps as potentially breaking. The target is whatever version the registry tag currently resolves to, not the next major in sequence — there's no per-run cap limiting you to one major version at a time, so a stable package several majors behind latest can jump straight there in one upgrade. By default it enforces peer compatibility across selected packages and leaves incompatible targets for manual review. Pass --force/-f only when you intentionally want tag targets without peer compatibility checks, then install and validate the resulting package set yourself.",
   },
   '/docs/tooling/openapi': {
     'check-drift':
@@ -2329,7 +2329,7 @@ export const headingOverrides: Readonly<
     configuration:
       "askr ssg --config <path> --output <dir> requires both flags explicitly -- there's no default config path the way openapi has one. --config must point at a TypeScript module (a .ts extension is enforced; passing anything else is a validation error), and that module defines which routes get pre-rendered and how.",
     'document-and-assets':
-      "Each pre-rendered route becomes a static HTML document built through the same head/app marker composition that @askrjs/vite's server plugin uses at runtime, so SSG output and SSR output share the same document-assembly logic rather than diverging into two separate template systems.",
+      "Each pre-rendered route becomes a static HTML document built by whatever `DocumentRenderer` function you pass to `createStaticGen` — the same document-composition primitive SSR uses. That's a shared *contract* (a plain function of `{ appHtml, context }`), not shared machinery with `@askrjs/vite`'s dev-server plugin specifically: the Vite plugin composes documents by replacing HTML-comment markers in `index.html` at request time, a different mechanism built for the dev server, not something SSG output goes through.",
     'failure-reporting':
       '--incremental reuses a previous build\'s manifest instead of re-rendering every route from scratch, and --changed-key / --changed-route (both repeatable) let you mark specific invalidation keys or concrete paths as changed so only the affected routes get regenerated. --force-full overrides all of that and forces a complete rebuild even when incremental flags are present. When routes fail to render, the command collects and prints an "Errors encountered" section listing each failure rather than aborting on the first one, so a single bad route doesn\'t hide problems in the rest of the site.',
     'output-directory':
@@ -2358,7 +2358,7 @@ export const lateHeadingOverrides: Readonly<
 > = {
   '/docs/components/switch': {
     anatomy:
-      'Switch has no sub-parts — it is a single control, unlike Accordion or Select. It renders as a button carrying `role="switch"` and `aria-checked`, and takes `checked` with `onCheckedChange` for controlled use or `defaultChecked` for uncontrolled. `name` and `value` make it submit inside a plain form, and `required` and `disabled` behave as they would on a native input. Pair it with `Field` and `FieldLabel` rather than a bare `label`, so the description and error slots line up with the rest of your form controls.',
+      'Switch has no sub-parts — it is a single control, unlike Accordion or Select. It renders as a button carrying `role="switch"` and `aria-checked`, and takes `checked` with `onCheckedChange` for controlled use or `defaultChecked` for uncontrolled. `name` and `value` make it submit inside a plain form, and `required` and `disabled` behave as they would on a native input. Pair it with `Field` from `@askrjs/themes/field` and `FieldLabel` from the `@askrjs/themes/components` barrel (it isn\'t exported from `/field` itself) rather than a bare `label`, so the description and error slots line up with the rest of your form controls.',
   },
   '/docs/components/table': {
     purpose:
@@ -2421,7 +2421,7 @@ export const descriptionOverrides: Readonly<Record<string, string>> = {
   '/docs/core-concepts/conditional-rendering':
     'Branch markup with Show and friends, keeping the mounted and unmounted paths explicit.',
   '/docs/core-concepts/scopes':
-    'Scopes own effects and resources, and dispose of them with their lexical owner rather than on a manual cleanup list.',
+    'Pass a value down the component tree without prop drilling, and have it read back from wherever `readScope()` is called below the provider.',
   '/docs/core-concepts/lifecycle-work':
     'Attach mount, cleanup, and DOM-only work to the component lifecycle so server rendering stays deterministic.',
   '/docs/core-concepts/error-boundaries':
diff --git a/src/pages/docs/usage-guide.ts b/src/pages/docs/usage-guide.ts
index 1680d2e..1e263a0 100644
--- a/src/pages/docs/usage-guide.ts
+++ b/src/pages/docs/usage-guide.ts
@@ -83,7 +83,7 @@ const result = createQuery(project, { id: projectId });`,
   '/docs/authentication/authorization': `route('/admin', AdminPage, {
   auth: requireUser(),
   policies: [({ auth }) =>
-    auth.permissions.includes('admin') ? allow() : forbidden()],
+    auth.principal?.permissions?.includes('admin') ? allow() : forbidden()],
 });`,
   '/docs/http-contracts/schemas': `const project = schema.object({
   id: schema.string(),
@@ -274,10 +274,14 @@ import { ScrollArea, ScrollAreaScrollbar, ScrollAreaThumb, ScrollAreaViewport }
       /Monaco Editor/,
       `import { MonacoEditor } from '@askrjs/monaco';
 
+// MonacoEditorProps has no onChange — subscribe to edits through onMount
+// and the real Monaco editor instance it hands you instead.
 <MonacoEditor
   value={source()}
   language="typescript"
-  onChange={(value) => setSource(value ?? '')}
+  onMount={(editor) => {
+    editor.onDidChangeModelContent(() => setSource(editor.getValue()));
+  }}
   options={{ minimap: { enabled: false } }}
 />`,
     ],
diff --git a/src/pages/marketing/platform.tsx b/src/pages/marketing/platform.tsx
index 0ff7442..0ac79b9 100644
--- a/src/pages/marketing/platform.tsx
+++ b/src/pages/marketing/platform.tsx
@@ -24,7 +24,8 @@ const packagePurpose: Record<string, string> = {
   node: 'The Node adapter that runs the server in production.',
   schema: 'Executable schemas that also project to OpenAPI.',
   auth: 'Identity resolution and route access policies.',
-  fetch: 'Typed HTTP clients, generated from an OpenAPI document.',
+  fetch:
+    'Typed HTTP clients defined in code, or generated from an OpenAPI document via the CLI.',
   i18n: 'Typed message keys that fail the build when a translation is missing.',
   otel: 'Redaction-aware OpenTelemetry instrumentation.',
   testing: 'Request injection and HTTP testing helpers.',