@nifrajs/cli 4.0.2 → 5.1.0

package/docs/llms-full.txt

@@ -12,6 +12,7 @@ nifra is a Bun-native, contract-first, framework-agnostic full-stack TypeScript
 - **Secure by default.** Body-size cap, `requestTimeoutMs` + `c.signal`, graceful shutdown, redacting logger, same-origin `redirect()`, constant-time secret comparison, fail-closed middleware.
 - **Money** in integer minor units; **time** parsed to absolute UTC at the boundary.
 - Throwing a `Response` anywhere in the lifecycle is control flow (returned as-is), not an error.
+Optional server components (post-4.0): React, Vue, Svelte and Solid share owner-GET admission, closed input/public-props schemas and private/no-store output. React uses native RSC/Flight. Use *.component.server.ts(x), defineServerComponent, an explicit componentPipeline named config export, native outlets and bindComponentRouter. Await invalidateComponentScope on identity/tenant/permission changes. Component GETs cannot acquire domain write privileges; use validated serverFn/actions for mutations. Native use-server actions are unsupported. Pin the certified compiler tuple documented in /docs/server-components.
 
 ---
 
@@ -212,24 +213,19 @@ The data model (loaders, actions, `defer`, progressive enhancement, fetchers,
 revalidation) is closest to **Remix / React Router** - delivered across five UI libraries instead
 of one.
 
-### Server code on every page - RSC is the one protocol Nifra trades away
-
-Nifra covers the full server side: typed **loaders and actions**, **streaming SSR** with
-out-of-order Suspense, **islands**, and typed
-[server functions](/docs/server-functions) - `serverFn` RPC whose body (DB
-handles, secrets, imports) is _never_ shipped to the browser, callable as a normal typed
-function from any component, on all five UI libraries. Data on the server, mutations on the
-server, minimal client JS: all there, by a framework-agnostic mechanism instead of a
-React-only one.
-
-What Nifra deliberately does not adopt is **React Server Components as a component
-protocol** - `"use server"` / `"use client"` directives and the
-server-only component tree. RSC is React-specific; a core that also serves Vue, Solid,
-Svelte, and Preact can't be built on it. (Nuxt, SvelteKit, and Remix don't ship RSC either -
-this is _Nifra vs. Next App Router specifically_.) So the call is simple: if your app is
-architected around RSC itself, **Next.js App Router is the right tool**. For everything RSC
-is usually reached for - server-side data, secrets off the client, less JS - loaders,
-`defer()`, islands, and server functions cover it here.
+### Server code and server-only views
+
+Nifra provides typed loaders and actions, streaming SSR, islands and typed
+[server functions](/docs/server-functions). Server functions keep their
+implementation, secrets and database handles off the browser and use the same validated
+mutation API across the supported UI libraries.
+
+The optional [server-components pipeline](/docs/server-components) adds
+server-only views and state-preserving refresh. React uses native RSC/Flight; Vue, Svelte
+and Solid use their native islands in validated server-rendered ranges. The feature is
+intended for the release after 4.0.0 and requires all four adapters to pass certification.
+Server functions remain the mutation API; native React `"use server"` actions
+are unsupported.
 
 ### Also a standalone backend (vs. Hono & Elysia)
 
@@ -347,10 +343,10 @@ version-checked examples, which no other framework ships.
 **To start lean and grow** - begin as a typed API, graduate to full-stack on the same core,
 no rewrite.
 
-The one deliberate trade: Nifra is streaming SSR + islands + typed
-[server functions](/docs/server-functions), **not** the RSC component protocol -
-framework-agnostic by design. Apps architected around RSC itself belong on Next App Router;
-everyone else gives up nothing server-side here.
+Nifra provides streaming SSR, islands and typed
+[server functions](/docs/server-functions). The optional
+[server-components pipeline](/docs/server-components) adds native React
+RSC/Flight and corresponding Vue, Svelte and Solid views under a shared execution contract.
 
 ## Nifra - Routing
 
@@ -396,7 +392,8 @@ reaches the browser - see [Project structure](/docs/structure).
 
 -
 `_404.tsx` renders unmatched paths, and whatever a loader answers with
-`notFound()`. At the routes root it renders on its own. In a directory below (
+`notFound()`. At the routes root it renders inside the root layout, as below. In
+a directory below (
 `admin/_404.tsx`) it answers for that part of the app: the unmatched URLs under
 `/admin` and `notFound()` from the routes beneath it, the nearest one
 winning, rendered inside the layouts at or above it with their loader data. Those layouts run
@@ -408,6 +405,21 @@ with a `_404` at one URL prefix are a boot error unless a directory containing
 both has one too. `gone()`, `statusPage()` and the
 `_410.tsx`-style pages stay at the root, as does the 404 of a static export.
 
+-
+A root status page (`_404.tsx`, `_503.tsx`, ...) or an
+`_error.tsx` renders inside the layouts above it with their loader data, and the
+server puts its `meta` in the head. For a request no route ran (an unmatched
+URL) the root middleware and layout loaders run first; otherwise the page reuses the data
+the request already loaded. When those layouts cannot render it - a loader throws, a
+`gate` or the middleware refuses - a root status page renders alone and an
+`_error` inside its layouts without their data, with the same status, so a
+status page never fails into a second error. The response is
+`private, no-store` once a layout loaded data, and a navigation that lands on
+one loads the URL as a document. `export const inLayouts = false` always renders
+the page that way and runs no layout loader for it. A root status page that wraps the root
+layout itself would render it twice; `nifra check` reports one as
+`NF-C034`.
+
 -
 `_loading.tsx` is what the page slot shows while a client navigation loads. A
 navigation still waiting on its data after about 120 ms swaps the page for the target
@@ -429,8 +441,9 @@ renders in its place, wrapped by the layouts at/above that segment, at status 50
 non-hydrated). On the **client** - a render error during navigation/interaction is caught by
 the nearest boundary, which renders `_error` in place (all five adapters). It
 receives the serialized error as `{ data: { name, message } }` (never the
-stack; on the server in production, a generic `Internal Server Error` rather
-than the error's own text); a thrown control-flow value (e.g. a guard
+stack; on the server, a generic `Internal Server Error` rather than the error's
+own text unless `NODE_ENV` is `development` or `test`); a
+thrown control-flow value (e.g. a guard
 `redirect`) passes through.
 
 -
@@ -467,6 +480,13 @@ Each page default-exports a component; an optional `meta` export drives
 `loader` in its `.backend.ts` half - see
 [Loaders & actions](/docs/data).
 
+A layout's `meta` receives its own loader's data as `data`, the value its
+component renders, or `null` when the layout has no loader. The page's data is
+`pageData`, for a layout title template. A layout that loads the locale can set
+`lang` from its data, and a client navigation keeps it. `nifra check`
+reports a layout with no loader whose `meta` reads `data` as
+`NF-C040`.
+
 ```ts
 // routes/users/[id].tsx
 import type { Route } from "./+types/[id]"
@@ -855,7 +875,7 @@ answers `422`.
 
 Other param modifiers (`:id+`, `:id*`, `:id(\\d+)`) are not
 part of the path grammar and match as literal text. Where that text is intended, put
-`// nifra-expect param-modifier` above the registration.
+`// nifra-expect NF-C026: ` above the registration.
 
 ### Param constraints
 
@@ -933,7 +953,7 @@ not look for another split.
 `/users/:id{[0-9]+}` serve no request in common, so `nifra check`
 (`NF-C024`) has nothing to report. A constrained route beside a bare
 `:param` route still overlaps and is still reported; mark the pair with
-`// nifra-expect route-overlap` where it is intended.
+`// nifra-expect NF-C024: ` where it is intended.
 
 -
 **OpenAPI and the typed client use the bare name.** The path is
@@ -993,9 +1013,11 @@ in the same call keep both. Call a custom one with
 `fetch(url, { method: "PURGE" })`.
 
 -
-**An assurance policy selects standard methods only.** A rule with `methods`
-never matches a custom-method route, so classify it with a path rule. Left unmatched, it is
-reported as `unclassified-route`.
+**An assurance rule names standard methods only.** A rule with `methods`
+never matches a custom-method route; one with `exceptMethods` does, unless the
+route is under a method it lists. `securityBaseline()` holds a custom method to
+its mutation rules, CSRF included, and `csrf()` publishes its evidence for one.
+Left unmatched, a route is reported as `unclassified-route`.
 
 Whether a custom method reaches the app is up to the runtime's HTTP parser.
 `PROPFIND`, `REPORT`, `PURGE` and `QUERY` arrive on
@@ -1033,6 +1055,14 @@ return makes the typed client infer `data: never`, so you silently lose drift
 detection for that route (`nifra check` flags it). `c.set` keeps your
 plain-object return fully typed.
 
+A `Response` a handler or hook returns or throws still gets the
+`c.set.headers` it lacks and the queued cookies, so a guard's
+`cache-control: no-store` reaches it. Its own headers win, `content-type`, `content-length`,
+`content-encoding`, `content-range` and `transfer-encoding`
+come from it alone, and `c.set.status` does not change its status. A
+`Response` shared across requests is copied first, so one request's headers never
+reach another.
+
 When you genuinely want a `Response` - an **error short-circuit** from a
 `derive` / `beforeHandle` (auth, rate limits) - `c.json(body, status?)`
 and `c.text(body, status?)` build one in a line:
@@ -1046,6 +1076,42 @@ The request is on `c.req`, also available as `c.request` - the same name a
 page loader/action receives (which in turn also accepts `ctx.req`), so one name works
 in both places.
 
+### Typed error responses
+
+Declare a route's error bodies in `errors`, keyed by status, and answer with
+`status(code, body, { headers })` from `@nifrajs/core/server`. It
+ends the request from a handler or any hook, returned or thrown, without building a
+`Response`: the body is serialized like a plain return, the headers ride with it,
+and queued cookies still apply. On the typed client, checking `res.status === 409`
+narrows `res.data` to the declared 409 body; a status the route does not declare
+falls into one arm whose `data` is `unknown`.
+
+```ts
+import { client } from "@nifrajs/client"
+import { server, status } from "@nifrajs/core/server"
+import { t } from "@nifrajs/schema"
+
+const conflict = t.object({ code: t.literal("conflict"), retryAfter: t.number() })
+const locked = new Set(["7"])
+
+export const app = server().post("/orders/:id/pay", { errors: { 409: conflict } }, (c) => {
+  if (locked.has(c.params.id))
+    // The body is the typed contract; the header serves proxies and plain HTTP clients.
+    return status(409, { code: "conflict", retryAfter: 5 }, { headers: { "retry-after": "5" } })
+  return { paid: true }
+})
+
+const api = client<typeof app>("https://api.example.com")
+const res = await api.orders({ id: "7" }).pay.post()
+if (!res.ok && res.status === 409) {
+  const wait: number = res.data.retryAfter // narrowed to the declared 409 body
+}
+```
+
+The client's `Result` carries the body, not the response headers. A value the
+caller acts on, such as how long to wait, belongs in the declared body; set the matching
+header too when proxies or plain HTTP clients read it.
+
 ### Typed request cookies (schema.cookies)
 
 `c.cookies` is the request's `Cookie` header as a name-to-value record,
@@ -1227,7 +1293,7 @@ same call params use, accepting exactly the colliding segment names. The client
 the dot access at compile time with that guidance, and `nifra check` reports the
 collision (`NF-C018`, advisory). Prefer a verb-free segment
 (e.g. `/api/remove`) when you control the path; mark a route served only to
-non-typed-client consumers with `// nifra-expect reserved-segment` above its
+non-typed-client consumers with `// nifra-expect NF-C018: ` above its
 registration.
 
 ### Results never throw
@@ -1253,9 +1319,11 @@ if (res.ok) {
 const { data, error } = await api.users.post({ name: "" })  // 422 if the schema rejects it
 ```
 
-A call that gets no HTTP answer has `status: 0` and one of four codes:
-`network_error`, `timeout`, `response_too_large`, or
-`invalid_path`. `invalid_path` means a param value was `.`
+A call that gets no HTTP answer it can read has `status: 0` and one of five
+codes: `network_error`, `timeout`, `response_too_large`,
+`malformed_response`, or `invalid_path`.
+`malformed_response` means the body did not decode as its content type says - a
+proxy's HTML error page labelled JSON, say. `invalid_path` means a param value was `.`
 or `..`: a URL reads those as steps to another path, in every encoding, so the
 client sends nothing rather than reach a route the call does not name.
 `.subscribe()` reports it through `onError` and closes;
@@ -1279,8 +1347,11 @@ the client never throws, it returns `{ data, error }`.
 A route's `loader` runs on the server and calls your backend in-process during
 SSR - no network hop. Its `loaderOutput` schema is the contract with the page:
 the page receives that shape as `data`, and nothing else the loader returns
-leaves the server. A `Date` travels as its ISO string, so declare a timestamp
-column as `t.string()`. A loader without a schema is flagged by
+leaves the server. Declare a timestamp as `t.date()` and the page gets a
+`Date` in the server render and in the browser alike; under
+`t.string()` it travels as its ISO string. `t.json()` declares a
+field that is any JSON value, passed through whole - a tool-call payload or a settings blob
+the page does not pick apart. A loader without a schema is flagged by
 `nifra check`. See
 [Project structure](/docs/structure) for the route pair.
 
@@ -1294,7 +1365,8 @@ import type { Route } from "./+types/[id]"
 // The page receives exactly this shape. Anything else the loader returns stays on the server.
 export const loaderOutput = t.object({ id: t.string(), name: t.string() })
 
-export async function loader({ params, api }: Route.LoaderArgs) {
+// Route.Loader checks what this returns against loaderOutput at compile time.
+export const loader: Route.Loader = async ({ params, api }) => {
   const res = await api.users({ id: params.id }).get()
   if (!res.ok) throw notFound()
   return res.data
@@ -1310,6 +1382,32 @@ export default function User({ data }: Route.ComponentProps) {
 }
 ```
 
+Annotating the loader with `Route.Loader` from the generated
+`./+types/<name>` checks what it returns against `loaderOutput`
+at compile time: a field of the wrong type, a `defer(...)` whose value does not
+match its `t.deferred(...)` field, or any data from a loader with no
+`loaderOutput` is a type error. A redirect, a `Response` and returning
+nothing stay allowed. `Route.Action` does the same against
+`actionOutput`, `revalidate(paths, data)` included. A field the schema
+does not declare is not a type error: the guard drops it before it ships. The annotation
+makes the loader's type the schema's, so `nifra schemas` cannot read what an
+annotated loader returns. It reports a generated schema over one as unchecked: annotate a
+loader whose schema you write, and leave a loader whose schema is generated unannotated.
+
+`nifra schemas` drafts the schemas from your code for review: it reads each
+loader's and action's TypeScript return type, and with `--write` puts a schema
+above every one that has none. It leaves out a field named like a credential and anything
+that is not JSON, says so in a comment, and marks what it wrote with a
+`nifra:generated` line. While that line stays, a later
+`nifra schemas --write` keeps the schema in step with the return type, and
+`nifra check` fails (NF-C033) when the two have drifted apart, or when the schema
+under the line was edited (reformatting it is not an edit); delete the line to own the
+schema by hand. A hand-written schema is never rewritten: the report lists the
+returned fields it drops, by path. Nothing is derived at request time - the schema in the
+file is the one the guard enforces. `nifra fix --code NF-C030` writes the same
+draft for one flagged route, and `nifra migrate layout` drafts one for each
+route it splits whose loader or action returns data without a schema.
+
 A field named like a credential (`password`, `token`,
 `apiKey`) fails the route when it loads unless its schema is wrapped in
 `t.declassified("why it may reach the browser", ...)`; a schema library that
@@ -1333,7 +1431,7 @@ import type { Route } from "./+types/new"
 
 export const actionOutput = t.object({ ok: t.boolean() })
 
-export async function action({ api, request }: Route.ActionArgs) {
+export const action: Route.Action = async ({ api, request }) => {
   const form = await request.formData()
   await api.users.post({ name: String(form.get("name")) })
   return { ok: true }                  // the page's loaders revalidate automatically
@@ -1352,6 +1450,18 @@ export default function NewUser() {
 }
 ```
 
+A form can post to another site and the browser sends that site's cookies with it, so an action
+refuses a POST whose `Origin` is another site's with 403, before middleware, gates or
+the action run. A request without an `Origin`, such as one from a server, passes, and
+so does a form on the app's own page sent under `Referrer-Policy: no-referrer`, which
+arrives as `Origin: null` with `Sec-Fetch-Site: same-origin`.
+Same-origin is judged from the request URL's host, so a proxy in front must forward the
+`Host` header. A route that takes posts from elsewhere, such as an identity
+provider's `form_post` callback, exports `allowedOrigins` from its backend
+file: an array of exact origins, or a function that receives the origin (`null` when
+absent). It checks where the browser says the request comes from, not who sent it, so keep the
+action's own authentication.
+
 ### Layout loaders on navigation
 
 A `_layout.backend.ts` can have a `loader` too; its output reaches the
@@ -1359,7 +1469,11 @@ layout component as `data`. On a client navigation that keeps the layout on scre
 browser already holds that data, so the loader runs again only when a param the layout owns
 changes (`org` for `orgs/[org]/_layout.tsx`) or the query changes. After
 an action, every loader runs. A layout that exports `gate = true` runs on every
-request; a layout loader without it is not an authorization boundary. A
+request; a layout loader without it is not an authorization boundary: a client navigation can
+skip it, and an action below it runs without it. Put a check that refuses access in a gate or
+in middleware. In development, nifra warns the first time a layout loader without
+`gate` refuses a request with a redirect, a `Response`, or a 401 or 403,
+and `nifra check` reports one whose loader refuses in its own body (NF-C042). A
 `_layout.backend.ts` that exports `middleware` guards a directory, with
 or without a layout component - see [Route middleware](/docs/routing#middleware).
 
@@ -1465,8 +1579,9 @@ host - defence in depth behind the JSON requirement, at the cost of one comparis
 Serialising closed-over variables to the browser and back is a class of problem worth not
 having rather than encrypting.
 
-Both content-type rules were measured rather than assumed. A body schema alone still accepts a
-cross-origin urlencoded form - 200, attacker-controlled fields - and a bounded JSON read alone
+Both content-type rules were measured rather than assumed. A body schema alone still reads a
+urlencoded form that carries no `Origin` or one from a site in
+`formOrigins` - 200, attacker-controlled fields - and a bounded JSON read alone
 accepts the `text/plain` trick where a form's `name=value` is crafted to
 parse as valid JSON. Neither is sufficient by itself.
 
@@ -1608,6 +1723,10 @@ Nothing here touches the kernel or the request path. An app that mounts no serve
 pays exactly nothing for the feature - which is the reason it is built as a plugin over the
 public registration API rather than as a bespoke dispatcher.
 
+## Nifra - Server components
+
+> Server-only views with schema-guarded props, owner-route authorization and native React, Vue, Svelte, Solid and Preact hydration.
+
 ## Nifra - Optimistic UI & fetchers
 
 > Optimistic updates and concurrent fetchers in Nifra: instant feedback, row-level mutations.
@@ -1838,7 +1957,9 @@ wouldn't propagate across instances. In production use a shared, durable store.
 `KVCacheStore` wraps a Workers KV namespace; any backend that fits the small
 `CacheStore` interface (Redis, the Cache API) works too. Every read is validated
 before it's trusted, so a corrupt or version-skewed entry is treated as a miss, not served
-broken.
+broken. A store that also implements `fence()` keeps a purge that lands while a
+page renders from being undone when that render stores the page it built from the old data;
+both built-in stores do.
 
 ```ts
 // doc-check: skip - Workers entry: `Env`/`ExecutionContext` globals + your `app` from server.ts.
@@ -1858,6 +1979,13 @@ export default {
 }
 ```
 
+A store outage never fails a page. A read that throws, rejects, or outlives
+`storeTimeoutMs` is a miss and the page renders; a failed write still returns the
+rendered page; a failed background regeneration keeps the stale entry. Each failure goes to
+`onStoreError(error, &#123; op &#125;)`, which by default logs one line per operation
+per minute without the cache key. Set `storeTimeoutMs` for a network store, so a
+hung connection costs a miss rather than the request.
+
 ### On-demand revalidation
 
 Purge a path the moment its data changes (a CMS webhook, an admin action) with
@@ -1872,6 +2000,21 @@ curl -X POST 'https://example.com/__nifra/revalidate?path=/posts/hello' \
 # → { "revalidated": "/posts/hello" }   (the token is checked in constant time)
 ```
 
+A per-request CSP nonce makes a page uncacheable. For a strict policy under ISR, give
+`createWebApp` a `csp` from `createCspPolicy` instead of a
+`nonce`: constant scripts are allowed by hash, so only a page that needs a nonce
+carries one - see [A strict CSP that still caches](/docs/contract#strict-csp).
+
+A page that must not be cached as a whole, because it is personalized or carries a nonce, can
+still cache the data its loader reads. Wrap the expensive call in `cache.wrap` from
+`@nifrajs/cache`, with the same tags the pages use. Concurrent loads of one key run
+once, and a store outage falls through to the loader. Pass that cache to
+`revalidateEndpoint` as `dataCaches: [cache]`. A tag purge then
+invalidates it first, then the page store, then the CDN, so no page is rebuilt from stale
+data. If a data cache fails, the endpoint answers `500` before it touches the page
+store, so a retry purges everything again. `createInvalidator` from
+`@nifrajs/web/cdn` takes the same `dataCaches` for purges from app code.
+
 `revalidateTags` names what a purge by tag reaches. A list tags every page of the
 route alike; a function of the route's params and URL tags each page on its own. Tags travel to
 the CDN and to anyone reading the origin, so build them from params, never from loader data.
@@ -2570,6 +2713,54 @@ stripped from `event`/`id` to prevent frame injection); multi-line
 `data` is split into multiple `data:` lines per the spec; and
 `keepAlive` emits comment pings so idle proxies don't drop the connection.
 
+A client that stops reading is dropped once it has `maxBufferedBytes` (default 1
+MiB) of events unread: `stream.signal` aborts with `sse_client_too_slow`,
+the queued frames are released, and later sends do nothing, so one stalled reader cannot hold
+server memory without limit. Raise it for a burst larger than that sent before the client can
+read, or pass `Infinity` to turn the limit off.
+
+### Typed SSE routes
+
+`app.sse(path, schema, run)` declares the event payload with `sse`, so
+`stream.send()` is type-checked and the typed client grows
+`.subscribe(onEvent)` with the same event type. A route whose schema declares a
+`body` is a POST stream: the body validates as on any POST, and
+`.subscribe(onEvent, &#123; body &#125;)` sends it. A GET stream reconnects after a
+drop and resumes with `Last-Event-ID`; a POST stream does not reconnect unless you
+pass `reconnect: true`, since a reconnect sends the body again. The client&apos;s
+`onRequest` hook runs before each connect, so a refreshed token reaches the stream.
+
+```ts
+import { client } from "@nifrajs/client"
+import { server } from "@nifrajs/core/server"
+import { streaming } from "@nifrajs/core/sse"
+import { t } from "@nifrajs/schema"
+
+declare function generate(prompt: string): AsyncIterable<string>
+
+export const app = server()
+  .use(streaming())
+  // A GET stream: the event payload is contracted by `sse`.
+  .sse("/feed", { sse: t.object({ id: t.integer(), title: t.string() }) }, (_c, stream) => {
+    stream.send({ id: 1, title: "hello" })
+    stream.close()
+  })
+  // A body makes it a POST stream, validated like any POST: a chat that posts its prompt.
+  .sse(
+    "/chat",
+    { body: t.object({ prompt: t.string() }), sse: t.object({ token: t.string() }) },
+    async (c, stream) => {
+      for await (const token of generate(c.body.prompt)) stream.send({ token })
+      stream.close()
+    },
+  )
+
+const api = client<typeof app>("https://example.com")
+const feed = api.feed.subscribe((post) => console.log(post.title))
+api.chat.subscribe((event) => console.log(event.token), { body: { prompt: "Hi" } })
+feed.close()
+```
+
 ## Nifra - Query cache
 
 > Nifra's keyed query cache: useQuery / createQuery, dedup, staleness, invalidation.
@@ -2657,7 +2848,7 @@ than small.
 ```ts
 import { html, vanillaAdapter } from "@nifrajs/web-vanilla"
 
-// routes/hotels.ts - a route file, no .tsx needed.
+// routes/hotels.tsx - a page keeps a route extension even with no JSX in it.
 export default function Hotels({ data }: { data: { hotels: Array<{ name: string }> } }) {
   // Interpolated values are escaped; wrap trusted markup in raw() to opt out deliberately.
   return html`<ul>${data.hotels.map((h) => html`<li>${h.name}</li>`)}</ul>`
@@ -2780,6 +2971,20 @@ Svelte resolve deferred data on the **client**, so JS-off users see the fallback
 deferred boundary. Put critical page data in the route `loader`; use
 `defer()` for slower, non-critical data.
 
+### Markup outside the page
+
+Svelte&apos;s `<svelte:head>` renders into the document&apos;s
+`<head>`, after the tags from the route&apos;s `meta`. The document
+always has a `<title>` of its own and a browser uses the first one, so set the
+title in `meta`.
+
+A Vue `<Teleport>` is server-rendered where Vue hydrates it from, the first
+children of its target. `to="body"` content comes first in
+`<body>`. An `#id` target the app renders empty receives it, and one
+the app does not render gets a container before the app root. Any other selector, a target that
+has children of its own, and every teleport on a page that uses `defer()` render on
+the client, with a warning in development.
+
 ### Dev HMR support
 
 Dev HMR works for all five adapters through `createViteDevServer` and the
@@ -2825,6 +3030,47 @@ app
 app.use((a) => a.decorate("db", db).derive((c) => ({ now: Date.now() })))
 ```
 
+### What a parent&rsquo;s use() covers
+
+A `group()` scope inherits the parent&rsquo;s chain as it stands at the call. A
+`merge()`d server was compiled on its own, so its routes keep _their_ chain. Only
+what the parent installed **before** the `group()` or `merge()` counts.
+
+Installed on the parent
+
+`group()` route
+
+`merge()`d route
+
+`derive`, `decorate`, `authenticate`,
+`beforeHandle`, `afterHandle`, `onError`,
+`around`, route-scoped assurance
+
+yes
+no - wire it on the merged server
+
+`onRequest`, `onResponse`, `responseHeaders`
+
+yes
+yes (app-wide)
+
+`responseContract()`
+
+yes
+yes, when the route declares a response and its own server installed no contract
+
+`effectLedger()`
+
+yes
+yes, when the route declares capabilities and has no ledger of its own
+
+`idempotency()`
+
+yes
+
+the merged server&rsquo;s own - a route declaring `idempotency` without one is
+refused at registration
+
 ### Route/hook plugins: keep types with defineRouterPlugin
 
 A plugin that registers routes or hooks but adds **no context type** - e.g. mounting an auth
@@ -2877,6 +3123,48 @@ const app = server()
   .use(rateLimit({ store: new MemoryStore(), max: 100, windowMs: 60_000 }))
 ```
 
+To refuse a request in `onRequest`, return the same `status()` value a
+route would: `return status(401, { error: "key required" })`. It takes the
+normal response path, so the body is serialized with its content-type, and declared
+`responseHeaders` and every `onResponse` hook apply to it. A hand-built
+`Response` still works.
+
+#### Which hooks run where
+
+Where a hook is registered decides which requests it sees. `nifra routes --hooks`
+prints, for every backend route and for each prefix's unmatched paths, the hooks that run
+and the site that registered them (`app`, `group /admin`,
+`merge #1`, `mount /m`), named by plugin where one registered them:
+
+-
+A **group**'s hooks cover its whole prefix, including that prefix's 404 and 405
+responses.
+
+-
+A **merged** server's `onRequest` runs only for its own routes; its
+response hooks and static headers become app-wide.
+
+-
+A **mount** runs the child's full lifecycle inside the parent's request and response
+hooks.
+
+-
+`around`, `derive`, and `beforeHandle` apply only to
+routes declared after them.
+
+-
+A **WebSocket** route, listed as `WS /path`, runs the request hooks, then the
+authentication stages, `derive`s, `beforeHandle`s and
+`onError` declared before it. Its handshake runs no `around`,
+`afterHandle` or response hooks, but a refused handshake carries the
+app&rsquo;s `responseHeaders()`.
+
+`nifra routes --hooks --json` writes the report; `--since <file>`
+prints what runs differently from a saved one. `nifra upgrade --write` saves the
+report before it edits anything and prints the scope diff, and `nifra check --json`
+includes it as `hooks` when `nifra.assurance.ts` names a
+`source`. Origins are recorded only outside production builds.
+
 ### Header middleware: one portable hook, fast everywhere
 
 Most response middleware only reads or writes **headers** - security headers, CORS
@@ -3071,7 +3359,10 @@ const app = server()
 `healthcheck()` adds liveness (`/health`) and readiness (`/ready`)
 endpoints - apply it **before** any auth guard so they stay public. `openapi()`
 serves an OpenAPI 3.1 document at `/openapi.json`, generated from your routes - add
-`ui: true` for a Scalar API-reference page at `/reference`. Paths,
+`ui: true` for a Scalar API-reference page at `/reference`. The page
+loads an exact Scalar version from jsDelivr under a Subresource Integrity hash; serve your own
+copy with `ui: { cdn, integrity }` to keep a third-party origin out of your
+Content-Security-Policy. Paths,
 methods, and params are introspected; `servers`, `tags`,
 `security`, and `securitySchemes` are document options, and
 `operations` (keyed by `"GET /users/:id"`) supplies per-route bodies/security
@@ -3116,7 +3407,10 @@ app.use(idempotency({ store: new MemoryIdempotencyStore() }))
 enforced by default, and claims (`iss`/`aud`/`nbf`) are checked.
 Read the typed claims off the returned plugin - `auth.requireClaims(c.req)` (throws
 `401`) or `auth.claims(c.req)` (nullable). For rotating keys, pass
-`key: jwks({ url })` (HTTPS-only, cached, size/time-bounded). `basicAuth`
+`key: jwks({ url })` (HTTPS-only, cached, size/time-bounded). A fetch that fails
+or returns no keys is remembered for `failureCooldownMs` (default 5 s), so while the
+identity provider is down a request fails at once instead of waiting on a fetch of its own.
+`basicAuth`
 compares static credentials in **constant time** (or takes a `verify` callback).
 
 ```ts
@@ -3177,6 +3471,36 @@ const app = server()
 // poweredBy() is opt-in (Nifra emits no X-Powered-By by default). combine(a, b, c) bundles several into one plugin.
 ```
 
+### Rate-limit tiers
+
+A `rateLimit()` inside a `group()` still sits under an app-wide one, so a
+group can only be stricter than the app. `rateLimitTiers()` is one limiter that
+charges each request to exactly one bucket - the tier with the longest static
+`prefix` holding the path, else the `floor` - so a public API can allow
+more than the floor while a login path allows less. It runs before routing, so 404s, 405s and
+bodies that fail validation are charged too. Prefixes are checked when the limiter is built
+(static, no trailing slash, no duplicates), and each tier counts in its own keys, so one store
+serves them all. `skip`, on both limiters, leaves a request uncharged.
+
+```ts
+import { server } from "@nifrajs/core/server"
+import { MemoryStore, rateLimitTiers } from "@nifrajs/middleware"
+
+// Each request is charged to ONE bucket: the longest matching prefix, else the floor.
+// A tier may sit above the floor - tiers never stack on it.
+const app = server().use(
+  rateLimitTiers({
+    store: new MemoryStore(),
+    floor: { max: 120, windowMs: 60_000 },
+    tiers: [
+      { prefix: "/api/public", max: 600, windowMs: 60_000 },
+      { prefix: "/auth/login", max: 10, windowMs: 60_000 },
+    ],
+    skip: (req) => new URL(req.url).pathname === "/health", // never charged
+  }),
+)
+```
+
 ### Security middleware
 
 The security set - `csrf` (signed double-submit + Origin/Referer), `jwt`,
@@ -3229,7 +3553,7 @@ const PublicUser = t.object({ id: t.string(), name: t.string() })
 
 // "warn" logs and changes nothing; "enforce" makes the contract the upper bound too.
 // Not installing the plugin is "off" - and keeps the lane out of your bundle entirely.
-export const app = server().use(responseContract("enforce")).get(
+export const app = server().use(responseContract("enforce", { extra: "strip" })).get(
   "/me",
   { response: PublicUser },
   async () => {
@@ -3239,8 +3563,10 @@ export const app = server().use(responseContract("enforce")).get(
   },
 )
 
-// off      -> {"id":"u1","name":"Ada","email":"a@b.c","passwordHash":"..."}
-// enforce  -> {"id":"u1","name":"Ada"}
+// off                          -> 200 {"id":"u1","name":"Ada","email":"a@b.c","passwordHash":"..."}
+// enforce                      -> 500 {"ok":false,"error":"internal_error"}
+//                                 (t.object is closed; the log names email and passwordHash)
+// enforce, { extra: "strip" }  -> 200 {"id":"u1","name":"Ada"}
 ```
 
 Not installing the plugin is &ldquo;off&rdquo;, which is exactly today&rsquo;s behaviour and
@@ -3249,16 +3575,25 @@ keeps the lane out of your bundle rather than shipping a disabled branch to ever
 serves the payload **unchanged** - so turning it on in staging can never be the
 thing that broke production. `"enforce"` serializes the validated value
 instead of the raw result. Both cover a returned value, a `status(...)` result and
-a `c.json(...)` reply alike; only a hand-built `Response` (a redirect, a
-stream) passes unchecked. Install it before the routes it should cover: like
+a `c.json(...)` reply alike, whether the handler returns or throws it, a hook
+returns it early, or `onError` answers with it; only a hand-built
+`Response` (a redirect, a stream) passes unchecked. Install it before the routes it
+should cover: like
 `idempotency()`, the decision is made per route at registration.
 
-Enforcement follows your schema&rsquo;s own semantics, because Standard Schema exposes
-`validate` and no way to enumerate declared keys. A _stripping_ schema (Zod,
-Valibot) yields a cleaned value, so the extra fields are dropped. A _strict_ one
+By default, enforcement follows your schema&rsquo;s own semantics, because Standard Schema
+exposes `validate` and no way to enumerate declared keys. A _stripping_ schema
+(Zod, Valibot) yields a cleaned value, so the extra fields are dropped. A _strict_ one
 (`@nifrajs/schema`&rsquo;s `t.object`) reports them as issues, so the
-response becomes a 500 and the detail goes to the logger, never to the caller. Both are what you
-already declared about extra fields.
+response becomes a 500 and the detail goes to the logger, never to the caller.
+`{ extra: "strip" }` changes that for `t` schemas: they carry their
+JSON Schema, which does list the declared keys, so the payload is projected onto them - nested
+objects, arrays and records included - before it is validated. In `"warn"`
+mode the same option makes the log name the fields `"enforce"` would drop.
+
+A `merge()`d server&rsquo;s routes are covered by a contract the parent installed
+before the merge, as long as the route declares a response and its own server installed none.
+See [what a parent&rsquo;s use() covers](/docs/plugins#parent-use).
 
 The check itself is essentially free: with a compiled validator it measures in the
 ~100ns-per-response range, and a realistic middleware-carrying route benchmarks within noise
@@ -3481,8 +3816,12 @@ one the bytes proved.
 
 -
 **A form post is a simple cross-origin request.** A browser sends
-`multipart/form-data` with cookies and no preflight, so a cookie-authenticated upload
-route needs `csrf()` like any other state change.
+`multipart/form-data`, urlencoded and `text/plain` with cookies and no
+preflight. A body-schema route refuses one whose `Origin` is another site&rsquo;s
+with `403` before reading it; list a site that must post forms to the app in the
+server&rsquo;s `formOrigins`. A request without an `Origin` passes, so
+a cookie-authenticated upload route still needs `csrf()` like any other state
+change.
 
 -
 **The form is held in memory.** Budget roughly twice `bodyLimit` per request in
@@ -3654,14 +3993,21 @@ Verification is **constant-time** - the provider's signature goes straight into
 `crypto.subtle.verify`, so a wrong signature can't be discovered byte-by-byte through
 timing. Presets cover **Stripe** (parses `t=…,v1=…` and enforces a 5-minute replay
 window on the signed timestamp) and **GitHub** (`sha256=…`); the `generic`
-preset takes an explicit header, encoding, and prefix for anything else. Pass an array of secrets to
+preset takes an explicit header, encoding (`"hex"`, `"base64"` or
+`"base64url"`, padded or not), and prefix for anything else. A signature that does not
+decode is refused as `malformed_signature`, never thrown. Pass an array of secrets to
 accept either during a key rotation.
 
 ### Idempotency - `idempotency()` middleware
 
 A dropped connection or an impatient double-tap shouldn't double-charge a card. With an
 `Idempotency-Key` header, a retried unsafe request replays the first response instead of
-re-running the side effect. It short-circuits in `onRequest`, _before_ the handler.
+re-running the side effect. The key is claimed in `onRequest`, so a concurrent retry gets
+a `409`; the stored response is replayed from `beforeHandle`, _after_ the
+route's authentication accepts the retry, so a credential revoked since the first request gets the
+route's current answer. Declare routes after `.use(idempotency())`:
+`beforeHandle` is order-scoped, and a route declared earlier replays from
+`onRequest`.
 
 ```ts
 // doc-check: skip - fragment: `app`, `chargeCard`, and `id` are your application's.
@@ -3786,6 +4132,13 @@ group can apply its own configuration over the app&apos;s - `admin.use(securityH
 inside `app.group("/admin", ...)` - and each header it sets replaces the app&apos;s
 value on the group&apos;s routes only.
 
+A fixed `Content-Security-Policy` here cannot allow nifra&apos;s inline scripts by
+nonce. For a strict `script-src` on web pages, give `createWebApp` a
+`csp` from `createCspPolicy`: it allows the framework&apos;s constant
+scripts by hash and adds a nonce only to a page that needs one, so every other page sends the
+same header and stays cacheable under `withISR` or a CDN. See
+[A strict CSP that still caches](/docs/contract#strict-csp).
+
 ### Route assurance - prove every route is guarded
 
 Installing security middleware is not the same as proving it covers every route. Nifra&apos;s
@@ -3806,11 +4159,15 @@ export default defineAssuranceConfig({
     rules: [
       { name: "health", match: { paths: ["/health"] }, require: [],
         forbid: [NIFRA_ASSURANCE.AUTHENTICATED] },
-      { name: "mutation", match: { methods: ["POST", "PUT", "PATCH", "DELETE"] },
+      // Every method but these, so a custom one such as PURGE is a mutation too.
+      { name: "mutation", match: { exceptMethods: ["GET", "HEAD", "OPTIONS", "WS"] },
         require: [NIFRA_ASSURANCE.AUTHENTICATED, NIFRA_ASSURANCE.CSRF,
           NIFRA_ASSURANCE.BODY_BOUNDED] },
       { name: "read", match: { methods: ["GET", "HEAD"] },
         require: [NIFRA_ASSURANCE.AUTHENTICATED] },
+      // WebSocket routes reflect under the pseudo-method "WS".
+      { name: "socket", match: { methods: ["WS"] },
+        require: [NIFRA_ASSURANCE.AUTHENTICATED] },
     ],
   },
 })
@@ -3824,6 +4181,14 @@ while authentication and other order-scoped hooks cover only routes registered a
 Method and path filters prevent a narrow guard from claiming broader coverage. The evaluation
 runs only through reflection or `nifra assure`, so requests pay no assurance cost.
 
+WebSocket routes are reflected under the pseudo-method `"WS"`, so a policy classifies
+every socket too. A handshake runs the auth guards registered before the socket and the
+app&apos;s request hooks, so a socket carries authentication and rate-limit evidence from them.
+It never claims evidence whose enforcement its message handlers bypass, such as a durable
+command journal. A socket declares its effects with
+`app.ws(path, { capabilities })`, and capability assurance checks them against
+the module that registers it.
+
 ### Effect assurance - declared capability versus provenance
 
 Authentication does not reveal what a route can do. Capability assurance compares an exact
@@ -3887,7 +4252,11 @@ Approval resumes are HMAC-signed, expire, bind to the tenant, principal, capabil
 digest, and are consumed atomically once. The effect journal marks execution before the provider
 call, so a crash after an external commit remains `ambiguous` for reconciliation instead
 of being retried blindly. Typed sagas persist compensation arguments separately from the sealed
-token-only ledger and compensate committed steps in reverse order with retry/backoff state.
+token-only ledger and compensate committed steps in reverse order with retry/backoff state. One
+`resume` or `compensate` call owns a saga at a time through a lease every
+transition renews (`leaseMs`, default 5 minutes): a second call meanwhile throws
+`SagaConcurrencyError` and changes nothing, and a call that died is taken over once its
+lease lapses.
 
 ```ts
 // doc-check: skip - durable store implementations are deployment-specific.
@@ -4109,6 +4478,15 @@ there and grants exactly `db.read` - it never reaches the driver underneath. Kee
 the two halves import-disjoint, at the seam and at the route modules, and every route's
 declaration equals its reach.
 
+The walk starts at the module that registers the route, which Nifra finds by reading the
+source without running it. It reads a path written as a string literal, or as a name bound to
+a module-level `const` string, with or without `as const`. The
+`const` can live in the same file or be exported from a project file it imports.
+The same holds for a WebSocket route's `app.ws(path, ...)`. A path built at runtime, such as a template with `${...}` in it, cannot be read
+this way. `nifra check` names that expression in an NF-C036 finding, because the
+route then has no module to start from. List the module in
+`provenance.routeModules` to give it one.
+
 ### Runtime beacons
 
 Static provenance answers what a _module_ can reach, so its evidence is as broad as the
@@ -4220,6 +4598,33 @@ $ nifra check
 • known gap, not capability-analyzed: /api/auth/* - better-auth's own handler; its effects are its own
 ```
 
+A mount can also state the routes it serves and the capabilities each one exercises. Pass an
+object with the `reason` and a `routes` list. Each path is the full
+request path and must sit under the mount:
+
+```ts
+export const app = server().mount({
+  path: "/api/auth",
+  app: authHandler,
+  opaque: {
+    reason: "better-auth's own handler; its effects are its own",
+    routes: [
+      { method: "POST", path: "/api/auth/sign-in/email", capabilities: ["session.write"] },
+      { method: "GET", path: "/api/auth/get-session", capabilities: ["session.read"] },
+    ],
+  },
+})
+```
+
+Assurance lists these routes with `analysis: "declared"`, apart from the routes it
+analyzed. The mount stays a known gap with its reason. A declared capability the policy does
+not define fails, as it does on a route, and so does a domain write declared on
+`GET`. Nothing else is checked, because there is no evidence to read. The routes
+also appear in the capability lockfile, so a changed declaration shows up in review. They
+appear in the `nifra context` route index too. An L4 run lists them as having no
+contract to test. A malformed entry, or a path outside the mount, stops the analysis with an
+error that names it.
+
 ### The lockfile
 
 Once assurance passes, snapshot the result. The lockfile is a review artifact: a route that
@@ -4352,6 +4757,15 @@ a `SessionStore`; in **cookie mode** (no store) the data is signed into the cook
 Stores mirror the ISR discipline: `MemorySessionStore` is prod-guarded;
 `KVSessionStore` is the durable, shared production store.
 
+The signature covers the cookie name, so two managers that share a secret never read each
+other's cookies; still, give sessions a secret no other signed value uses. A cookie-mode
+session lives at most `maxAge`, whatever expiry its payload names. Upgrading from
+4.x, whose cookies were signed without the name, signs everyone out unless you pass
+`acceptLegacyCookies: true`: keep it for one `maxAge` after the upgrade
+(each such session is re-signed on its next commit), then remove it, since while it is on any
+session-shaped value the app signs with the same secret through `signValue` reads
+as a session.
+
 ```ts
 // backend/auth.ts - one session manager, created on first use so the secret is read at request time.
 // Store mode keeps data server-side; cookie mode (no store) is stateless.
@@ -4417,6 +4831,102 @@ export async function loader({ request }: Route.LoaderArgs) {
 }
 ```
 
+Without `redirectTo`, a guard denies with a 401 JSON
+`{ ok: false, error: "unauthorized" }`. `unauthenticated` sets that
+response's status (400-599), body and headers instead; the same option exists on
+`@nifrajs/better-auth`'s `requireSession`, `requirePrincipal`
+and `authed`, and on `@nifrajs/authjs`'s `requireAuthUser`. A
+guard given both `redirectTo` and `unauthenticated` throws.
+
+```ts
+// doc-check: skip - fragment: `session` is the request's session.
+requireUser(session, "userId", {
+  unauthenticated: { status: 403, body: { error: "login_required" }, headers: { "www-authenticate": "Session" } },
+})
+```
+
+### One request-scoped context from authentication to the handler
+
+`around` wraps everything after routing for the routes declared after it:
+authentication, body validation, `derive` and the handler. An
+`AsyncLocalStorage` frame or a database session setting opened there stays open
+until the response is decided. `authenticate` runs inside that frame before
+validation, resolves the caller once and types it as `c.principal`, so it can write
+what it resolved into the frame instead of a second lookup in a `derive`. Both are
+order-scoped, so inside a `group` they cover only its routes.
+
+```ts
+// doc-check: skip - fragment: `app`, `readSession`, `Note`, and `db` are your application's.
+import { AsyncLocalStorage } from "node:async_hooks"
+import { authenticated, rejected } from "@nifrajs/core"
+
+const frame = new AsyncLocalStorage<{ userId?: string }>()
+
+app.group("/api", (api) =>
+  api
+    // Opens before authentication and closes after the response: validation, derive and the
+    // handler all run inside it, and so does a thrown Response.
+    .around((_c, next) => frame.run({}, next))
+    // Resolves the caller once: typed as c.principal, and written into the open frame.
+    .authenticate({
+      id: "session",
+      run: async (input) => {
+        const session = await readSession(input.headers.get("cookie"))
+        if (session === null) return rejected()
+        const store = frame.getStore()
+        if (store !== undefined) store.userId = session.userId
+        return authenticated(session)
+      },
+    })
+    .post("/notes", { body: Note }, (c) => db.notes.insert({ ...c.body, owner: c.principal.userId })),
+)
+```
+
+### Authentication runs first
+
+`authenticate()` refuses a request before anything reads it: the body is not read,
+no schema runs, and no `derive` or `beforeHandle` sees it. An
+unauthenticated caller gets the 401 (or the refusal `run` returns), never a 413 or a
+422 that describes the route's input. `basicAuth`, `bearer`,
+`apiKey` and `jwt` from `@nifrajs/middleware` run there. With
+`optional: true` they never refuse, so validation answers as usual.
+
+`run` receives the method, pathname, headers, path params, the raw
+`search` and the parsed `query` (frozen, read by the parser
+`c.query` uses; a repeated key is an array), the `request` (never read
+its body), `env`, `clientIp` and an abort `signal`. Every
+field is the caller's and unvalidated. Read the query only for a short-lived, single-use
+ticket, such as one for a WebSocket handshake a browser cannot set a header on: a URL lands in
+proxy and access logs. The dev feed records a query's keys, never its values.
+
+```ts
+// doc-check: skip - fragment: `app` and `tickets` (a single-use store) are your application's.
+import { authenticated, rejected } from "@nifrajs/core"
+
+app
+  .authenticate({
+    id: "socket-ticket",
+    run: async (input) => {
+      // A browser cannot set a header on a WebSocket handshake, so the ticket rides in the URL.
+      const ticket = input.query.ticket
+      if (typeof ticket !== "string") return rejected()
+      const user = await tickets.take(ticket) // single use, expires in seconds
+      return user === null ? rejected() : authenticated(user)
+    },
+  })
+  .ws("/live", { upgrade: (c) => ({ user: c.principal.id }) })
+```
+
+A guard written as a `beforeHandle` runs after validation, so an unauthenticated
+caller reaches the body parser. When `nifra check` loads
+`backend/app.ts` (it does when a `contracts.lock.json` exists), NF-S008
+names each route that claims authentication this way and declares an input schema. Move the
+check into `authenticate()`, or set
+`validationOrder: "auth-before-validation"` on the route to run its hooks first. A
+rate limiter written as a `beforeHandle` behind `authenticate()` does not
+see refused requests; `rateLimit()` runs in `onRequest`, before routing,
+and counts them.
+
 ### Session code stays in the backend
 
 The session manager, an auth instance and their secrets live in `backend/`, and only
@@ -5215,15 +5725,16 @@ app.listen(3000) // Bun
 ### Lifecycle
 
 Every callback is optional - `{ message }` alone is a valid echo server.
-`upgrade` is the only one that runs before the socket opens, so it’s the one place
-to reject a connection.
+`upgrade` is the only callback that runs before the socket opens, so it’s where a
+route rejects a connection or seeds its data.
 
 ```ts
 // doc-check: skip - illustrative lifecycle (empty close/error bodies, cookie shape).
 app.ws<{ user: string }>("/chat", {
-  // upgrade(c) runs in the full HTTP request context, BEFORE the socket opens -
-  // authenticate, check origin, rate-limit. Return the per-connection data (→ ws.data,
-  // typed), or a Response to REJECT the upgrade. A thrown error rejects with 500.
+  // upgrade(c) runs in the full HTTP request context, BEFORE the socket opens, after the
+  // guards registered before this route. Return the per-connection data (→ ws.data, typed),
+  // or a Response or status(...) to REJECT the upgrade. A thrown Response rejects with it;
+  // any other throw goes to onError, then a 500.
   upgrade(c) {
     const user = c.cookies.session
     if (user === undefined) return new Response("unauthorized", { status: 401 })
@@ -5236,6 +5747,37 @@ app.ws<{ user: string }>("/chat", {
 })
 ```
 
+### Guards
+
+A handshake is a `GET`, and it runs the chain an HTTP `GET` registered
+at the same point runs: the `authenticate()` stages, `derive`s and
+`beforeHandle`s added before `app.ws()`, then `upgrade`. So
+auth middleware such as `basicAuth` or `jwt` guards the sockets
+registered after it, any guard can refuse the handshake with the response it would send an
+HTTP request, and `upgrade` reads what the guards derived. The origin check runs
+first. A socket registered before a guard stays public, like an HTTP route there. A browser
+cannot set a header on the handshake, so `authenticate()` can read a short-lived,
+single-use ticket from `input.query` - see
+[Authentication runs first](/docs/auth#auth-first).
+
+```ts
+// doc-check: skip - illustrative: an existing auth guard and session lookup.
+app
+  .ws("/status", {})                       // registered before the guard: public
+  .authenticate(sessionAuth)               // or .use(basicAuth(...)), .derive(...), .beforeHandle(...)
+  .get("/me", (c) => c.principal)
+  .ws("/chat", {
+    // Reached only when sessionAuth accepted the handshake, exactly as GET /me is.
+    upgrade: (c) => ({ user: c.principal.id }),
+  })
+```
+
+A socket declares the effects its code may reach with `capabilities`, as an HTTP
+route does. `nifra capabilities check` compares them with what the registering
+module can reach, and the handshake context carries the runtime guard for
+`upgrade()`. Reflection lists every socket under the pseudo-method
+`"WS"`, so `nifra assure` classifies sockets too.
+
 ### NifraWebSocket
 
 The `ws` handed to each callback is a portable wrapper over the runtime’s native
@@ -5335,7 +5877,9 @@ bridge an external fan-out (Redis pub/sub, NATS, a queue) to broadcast across al
 **Cloudflare Workers**, a stateless isolate can’t broadcast across connections,
 so Nifra ships a Durable Object hub: `createWebSocketHub(app)` holds the
 connections, and `toFetchHandler(app, { webSocketHub })` routes upgrades to it
-- then `ws.subscribe` / `app.publish` behave exactly as on Bun.
+- then `ws.subscribe` / `app.publish` behave exactly as on Bun. An
+upgrade request for a path with no WebSocket route still gets that path's HTTP answer, as on
+every other runtime.
 
 ```ts
 // doc-check: skip - Workers entry: a Durable Object hub holds the connections.
@@ -5388,6 +5932,60 @@ it). Install it when you use `app.ws()`; without it a WS upgrade gets a clean
 npm i ws
 ```
 
+`server({ wsMaxPayloadBytes })` caps one inbound message (default
+`maxBodyBytes`, 1 MB): a socket that sends more is closed with `1009`
+and the message never reaches your handler. Bun and Node refuse it while it arrives. Deno's
+`Deno.upgradeWebSocket` takes no size limit, so Deno receives each message whole
+(up to its own limit, 64 MiB on Deno 2.9) before nifra can check it: the cap still keeps the
+message from your handler, but it does not bound the memory Deno spent receiving it. Where that
+matters, cap message size in a proxy in front of a Deno app.
+
+### In a composed app
+
+`mount({ path, app })` carries WebSocket upgrades as well as HTTP: when the
+serving adapter sees an upgrade under the mount's path, it asks the child's
+`resolveWebSocketUpgrade` and upgrades its own socket with the outcome. Any nifra
+server with `websocket()` installed has one. A child that is not a nifra server can
+implement it too, building the outcome from `@nifrajs/core/ws`:
+`attachWebSocket` wires the socket to a handler and a `TopicRegistry`
+owns its pub/sub. On Bun, install `websocket()` on the parent or on a mounted nifra
+child, or `listen()` refuses to start with `INVALID_WS_RUNTIME`.
+
+Each mounted nifra app keeps its own `wsMaxPayloadBytes`: a message over the
+child's cap closes that socket with `1009`, whether the cap is below or above the
+parent's. On Bun one listener serves them all, so its frame limit is the largest cap among the
+parent and the apps mounted on it, and a socket whose app declares less checks its own.
+
+`mountFetch(path, handler)` and a plain fetch handler carry HTTP only. An upgrade
+request under such a path reaches the handler as an ordinary request and never becomes a
+socket. Serve that path's WebSockets from a mounted child, or keep that server beside nifra.
+
+```ts
+// server.ts - one listener; the chat child and a non-nifra child both take upgrades.
+import { server } from "@nifrajs/core/server"
+import { attachWebSocket, TopicRegistry, websocket, type WebSocketUpgradeOutcome } from "@nifrajs/core/ws"
+
+const chat = server()
+  .use(websocket())
+  .ws("/room", { message: (ws, data) => ws.send(data) })
+
+// Not a nifra server: it answers HTTP through fetch and builds its own upgrade outcome.
+const topics = new TopicRegistry()
+const legacy = {
+  fetch: () => new Response("legacy"),
+  resolveWebSocketUpgrade: (request: Request): WebSocketUpgradeOutcome =>
+    new URL(request.url).pathname === "/feed"
+      ? { kind: "upgrade", handler: { open: (ws) => ws.send("hello") }, data: undefined, pubsub: topics, attach: attachWebSocket }
+      : { kind: "pass" },
+}
+
+server()
+  .use(websocket()) // Bun: the parent holds the socket table every mounted upgrade runs through
+  .mount({ path: "/chat", app: chat, stripPrefix: true })
+  .mount({ path: "/legacy", app: legacy, stripPrefix: true })
+  .listen(3000)
+```
+
 ## Nifra - Deployment
 
 > One Nifra app, one command per target - Bun, Node (Docker), Deno Deploy, Cloudflare Pages, Vercel Edge.
@@ -5518,6 +6116,11 @@ hand one visitor a response produced for another:
 **Only content-hashed assets are precached.** A hashed URL names its bytes, so serving it
 from cache forever is correct by construction. Unhashed URLs are left to the network.
 
+-
+**Only the build's own URLs are answered, from the build's own cache.** Any other request,
+an API call included, goes to the network untouched, and a cache the page or another app
+stored on the origin is never read.
+
 -
 **Documents are never cached.** Only navigations that FAIL are answered, and only with the
 offline page you nominate - which must be static and user-independent, since every visitor
@@ -5529,8 +6132,9 @@ for another.
 straight to the network.
 
 -
-**The cache name carries the build id**, and activation deletes every older cache - so a
-stale worker cannot pin an old build indefinitely.
+**The cache name carries the build id**, and activation deletes every older cache named
+`<cacheName>:<buildId>` - so a stale worker cannot pin an old build
+indefinitely, and the origin's other caches are left alone.
 
 Omit `offlineUrl` and a failed navigation simply fails, which is the honest default:
 an offline page you have not written is not better than a browser error.
@@ -5572,6 +6176,14 @@ content-typed, with an immutable cache - before the app runs, leaving the SSR fa
 untouched: `serve(app, {'{ port, static: { dir: new URL("./assets/", import.meta.url) } }'})`.
 On Cloudflare/Vercel the platform serves assets, so you don't need it there.
 
+Every file under the mount is cached as immutable by default. If the directory also holds
+files that keep their name across deploys, pass the build manifest's `assets` as
+`hashedFiles`: only those URL paths stay immutable, and every other file is sent
+with its validators so the browser revalidates it. The server that
+`nifra build --target bun` or `node` generates does this already. It
+caches only the client build's own content-hashed outputs as immutable. A file copied from
+`public/`, even under `public/assets/`, gets a one-day policy.
+
 ### HTTPS without a proxy
 
 Most deploys end TLS in front of the app - a load balancer, a CDN, the platform - and the app
@@ -5766,6 +6378,43 @@ import { stylexVite } from "@nifrajs/web/plugins/stylex"
 export const vitePlugins = [react(), stylexVite()]
 ```
 
+### Upgrading nifra
+
+Every `@nifrajs/*` package, `nifra` and `create-nifra` ship
+together at one version. Move a workspace between releases with
+`nifra upgrade <version>` rather than by editing pins: it runs every release
+recipe between the oldest version your `package.json` files pin and the target,
+oldest first. A recipe moves a removed package to its replacement, rewrites imports that
+moved, lists comments a release stopped honoring, and pins each group dependency to the
+target, keeping its `^` or `~` unless you pass `--exact`.
+The pins in `overrides`, `resolutions` and
+`pnpm.overrides` move with them, since an override decides what installs.
+
+```ts
+nifra upgrade --list          # the release targets this CLI knows
+nifra upgrade 5.0.0           # dry-run: every planned edit, nothing written
+nifra upgrade 5.0.0 --write   # apply, then nifra check verifies (--no-verify skips it)
+nifra doctor                  # afterwards: no "mixed nifra versions" advisory left
+```
+
+It is a dry-run until `--write`, and the same run twice makes no further edits. An
+unknown version or a target below what is installed is refused (`--allow-downgrade`
+when the rollback is intended); a target newer than the running CLI prints the command for
+that release&apos;s CLI. It edits files under the workspace root only: a symlinked package
+directory or `package.json` is never followed, and a group package installed by a
+link from outside the root is listed under "Left alone" for you to upgrade in its
+own repository. The MCP launch pin in `.mcp.json`, `.cursor/mcp.json`,
+`CLAUDE.md` and `AGENTS.md` moves to the target, the edit
+`nifra init-agents --sync-mcp` makes. Another version pinned outside
+`package.json` is listed with its line: the rest of an agent file, an MCP config
+elsewhere, a Dockerfile or compose file, a CI workflow, and a lockfile other than the
+workspace&apos;s own (an image build&apos;s frozen lockfile, say), which you regenerate after
+installing. With `--write` it also
+prints how hook scope changed across the
+upgrade (`--no-hooks` skips that). `nifra doctor` and
+`nifra check` (NF-D002) point here when a workspace carries more than one version;
+see [mixed nifra versions](/docs/troubleshooting#mixed-versions).
+
 ### Scope
 
 `nifra build` defaults to a self-hosted Bun server. Use `--target node`,
@@ -6310,8 +6959,10 @@ database connection is not the same as handing it a query tool, and this is the
 `@nifrajs/agent-protocol` is the small versioned session and event contract.
 `@nifrajs/coding-agent` provides the standalone `nifra-agent` host with
 bounded sessions, checkpoints, workflows, extensions, verification, and authenticated local
-RPC. `@nifrajs/pi` is an optional Pi backend; other backends implement the same
-protocol port.
+RPC. `@nifrajs/pi` is an optional Pi backend, and `@nifrajs/acp` drives
+any Agent Client Protocol agent (Claude Code, Codex, Gemini CLI) over stdio; other backends
+implement the same protocol port and can prove it with `checkAgentBackend` from
+`@nifrajs/agent-protocol/conformance`.
 
 ```ts
 bun add @nifrajs/coding-agent @nifrajs/pi
@@ -6343,7 +6994,10 @@ emit `approval.required` with an opaque approval id, action, capability, and bou
 coordinates. Resolve it through the host or RPC with `approval.resolve`; the backend
 emits `approval.resolved` and only then executes the tool. Denial, cancellation,
 timeout, and closed sessions all fail closed, and `approvalTimeoutMs` bounds how long
-a pending decision can remain open.
+a pending decision can remain open: 5 minutes by default, at most 24 hours, or
+`"never"` to wait until it is answered, cancelled, its turn ends, or the session
+closes. The host's broker takes the same values as `approvals.timeoutMs` on
+`CodingAgentHost` and `CodingAgentRpcServer`.
 
 ### Expose the same agent to other clients
 
@@ -6440,6 +7094,15 @@ resume. `@nifrajs/agent-telemetry` converts the same constrained evidence into
 fail-open OpenTelemetry run and step spans. Providers, credentials, durable storage, retention,
 and tenant policy remain application-owned ports.
 
+A step that suspends for approval resumes with the decision the caller sends in
+`resume.approval`. On an AG-UI or `mountAgent` route that anyone can
+reach, that caller may be the party asking for the tool. Return
+`resumeApproval: "port"` from `ports` to keep the configured approval
+port authoritative: it is asked again on resume, receives the caller's decision as
+`callerDecision`, and its verdict stands. Without a port, such a resume suspends
+again. A2A does this by default, since the resuming peer is the agent that asked for the
+tool; return `resumeApproval: "caller"` there only when the peer is the approver.
+
 ### Where your code and secrets run
 
 The server your client starts runs none of your project's code. Each tool that loads the app,
@@ -6466,9 +7129,11 @@ values (`nifra mcp --env-file .env.secrets`), reach all of them.
 -
 **No `.env` in the server.** When Bun loaded `.env`
 values into the server at startup, the server hands the session to a copy of itself that
-loads none, keeping the values from the environment and `--env-file`. The process
-the client started stays to forward signals and the exit code: it still holds the values
-Bun loaded, but runs no project code and reads no messages.
+loads none, keeping the values from the environment and `--env-file`. A project
+that installs another release of `@nifrajs/cli` gets the session handed to that
+CLI the same way, with no `.env` loaded. The process the client started stays to
+forward signals and the exit code: it still holds the values Bun loaded, but runs no project
+code and reads no messages.
 
 -
 **A process per call has a cost.** A call that loads the app pays one process
@@ -6766,6 +7431,17 @@ with `export const dev = { indicator: false }` in `nifra.config.ts`,
 or with `indicator: false` on `createDevServer`; the errors still reach
 the feed.
 
+### Host check
+
+The Bun dev server listens on 127.0.0.1 and answers only loopback host names:
+`localhost`, any `*.localhost`, `127.0.0.1` and
+`[::1]`. Any other `Host` gets a 403, so a page on another site whose
+name a DNS rebind points at your machine cannot read your pages, loader data or error overlay.
+To reach the server under another name (a hosts-file entry, a tunnel), list it with
+`export const dev = { allowedHosts: ["app.test"] }` in
+`nifra.config.ts` or `allowedHosts` on `createDevServer`.
+The Vite pipeline applies Vite's own `server.allowedHosts`.
+
 ### Containers & sandboxes
 
 In Docker, networked volumes, and some sandboxes, pass
@@ -7217,7 +7893,12 @@ classes with separate request state. The second copy prints
 
 **The build honours the declaration on its own** -
 `buildClient` and `buildServer` inject the resolver, so bundled output
-already loads one copy. Unbundled phases do not: Bun's _runtime_ resolver never offers a
+already loads one copy, and so does the browser bundle `nifra dev` serves on Bun.
+Listing `singleCopyPlugin()` in `clientPlugins` as well is harmless: dev
+runs that instance in the resolver's place instead of a second one. On Vite, the dev server and
+both Vite builds add each declared package to `resolve.dedupe`, a
+`@scope/*` pattern as every package installed under that scope. Unbundled phases do
+not: Bun's _runtime_ resolver never offers a
 bare specifier to a plugin, so `bun test`, `bun run`, and preloaded
 scripts still load both copies unless you preload the registrar:
 
@@ -7420,6 +8101,23 @@ which the server logs. Read the body in a hook with `c.req.bytes()`,
 instead: they read it once, within the route's body limit, and every reader after the hook
 replays the same bytes.
 
+### "mixed nifra versions in this workspace"
+
+Every `@nifrajs/*` package, `nifra` and `create-nifra` ship
+together at one version. `nifra doctor` (and `nifra check`, as the
+`NF-D002` advisory) reads the versions your `package.json` files pin,
+the versions installed in `node_modules` - followed to their real location, so a
+linked repository reports its own - and the running CLI. When they disagree it names each
+version and where it came from. It only reads files, and it never fails the run.
+
+The fix is [`nifra upgrade <highest>`](/docs/cli#upgrade), not a
+hand edit of the pins: it runs
+every release's migration steps between your oldest pin and the target, then re-pins. Run it
+without `--write` first to see each planned edit. It edits files under the
+workspace root only. A symlinked package directory or `package.json` is never
+followed, and a group package installed by a link from outside the root is listed under
+"Left alone" - upgrade that repository on its own.
+
 ### Still stuck?
 
 Run `nifra check --json` as the done-gate - it surfaces the import-chain leaks,
@@ -7429,13 +8127,14 @@ package ships a tight `LLM.md` contract card.
 
 ## Nifra - Backends & API (dev and prod)
 
-> How a Nifra backend reaches your app: inProcessClient feeds ctx.api to loaders, and createWebApp auto-mounts the backend over HTTP at /api/* - in `nifra dev` and production alike, no hand-dispatch.
+> How a Nifra backend reaches your app: inProcessClient feeds ctx.api to loaders, and createWebApp serves the backend over HTTP at the apiPrefix you set - in `nifra dev` and production alike, no hand-dispatch.
 
 Your `@nifrajs/core` backend reaches a Nifra app two ways from a single wiring.
 `inProcessClient(backend)` is fed to every loader and action as
-`ctx.api` - and `createWebApp` now **auto-mounts** that
-backend over HTTP at `/api/*`, so the browser can call the very same routes. No
-hand-written `if (pathname.startsWith("/api/"))` branch in your server entry.
+`ctx.api` - and, given an `apiPrefix`, `createWebApp`
+**mounts** that backend over HTTP there, so the browser can call the very same
+routes. No hand-written `if (pathname.startsWith("/api/"))` branch in your server
+entry.
 
 ### One backend, two call paths
 
@@ -7475,20 +8174,19 @@ export async function loader({ api }: Route.LoaderArgs) {
 }
 ```
 
-### The auto-mounted /api/* (the new part)
+### The mounted /api/*
 
-Before, `inProcessClient` fed `ctx.api` but did _not_ serve the
-backend over HTTP - so a browser `POST /api/sync` hit the page router and 404/405'd
-until you hand-wrote a dispatch branch in `server-bun.ts`. Now
-`createWebApp` mounts it for you: a request whose pathname is exactly
-`apiPrefix` (default `/api`) or starts with
+Without an `apiPrefix`, `inProcessClient` feeds `ctx.api` but
+the backend is _not_ served over HTTP, so a browser `POST /api/sync` reaches
+the page router. Set `apiPrefix: "/api"` and `createWebApp` mounts it: a
+request whose pathname is exactly `apiPrefix` or starts with
 `apiPrefix + "/"` is dispatched through Nifra's platform-aware backend mount
 interface **before** page routing. The backend receives the same Workers
 `env` bindings and `waitUntil` lifetime as the web app, and its
 `Response` is returned untouched (the request body is passed through, never pre-read).
 
 ```ts
-// backend/server.ts - a hand-written server: createWebApp serves pages AND auto-mounts the
+// backend/server.ts - a hand-written server: createWebApp serves pages AND mounts the
 // backend at /api/*. (`nifra build` emits this wiring for you; write it only for a custom host.)
 import { inProcessClient } from "@nifrajs/client"
 import { createWebApp } from "@nifrajs/web"
@@ -7500,8 +8198,8 @@ export const app = createWebApp({
   adapter: reactAdapter,
   manifest,
   clientEntry,
-  api: inProcessClient(backend), // → ctx.api in loaders/actions AND auto-mounted at /api/*
-  // apiPrefix: "/api",          // the default; pass "" to disable the HTTP mount (pages only)
+  api: inProcessClient(backend), // → ctx.api in loaders/actions
+  apiPrefix: "/api", // AND served over HTTP at /api/*; without it the backend is loader-only
 })
 
 // Bun: Bun.serve({ fetch: app.fetch }). No `if (pathname.startsWith("/api/")) …` branch needed -
@@ -7513,8 +8211,23 @@ for **every method** - so `GET`/`POST`/`PUT`/… all
 reach the backend, and an unknown `/api/…` path returns the _backend's_ 404,
 not the page's. A sibling path that merely shares the prefix string (e.g.
 `/apidocs`) is **not** captured - only the `/api` boundary
-is. Pass `apiPrefix: ""` to turn the mount off and keep `ctx.api` as a
-loader-only client.
+is. Leave `apiPrefix` unset, or set it to `""`, to keep
+`ctx.api` as a loader-only client.
+
+Loader-only is the default because an app that also serves the same backend behind its own
+server - with that server's rate limits and guards - would otherwise get a second path to it
+that skips them. `nifra check` reports `NF-C035` for a
+`backend/framework.ts` that sets no `apiPrefix`, so the choice is
+written down: `nifra fix --code NF-C035` adds
+`export const apiPrefix = "/api"`, which is what 4.x mounted by default, and
+`""` keeps the backend loader-only.
+
+With both files, `nifra dev` and `nifra build` take
+`apiPrefix`, `apiStrip`, `mounts`, `csp`,
+`nonce`, `serverComponents` and `use` from
+`backend/framework.ts` when `nifra.config.ts` does not set them, so the
+server entry and the dev server read one value without a re-export. A hand-written
+`createWebApp` call passes `apiPrefix` itself.
 
 Because the backend answers first and its 404 is final, a page file under the prefix (
 `routes/api/report.tsx`) could never render. Nifra refuses it instead of serving a
@@ -7549,8 +8262,8 @@ export const use = (app: { get(path: string, handler: () => Response): unknown }
 
 [!NOTE] The mount lives in `createWebApp`, and `nifra dev` (the
 Vite-backed dev server) routes every request through that same app's `fetch`. So
-the `/api/*` routes are served identically in development and production - there is
-nothing extra to wire for the dev loop.
+the mounted routes are served identically in development and production - there is nothing
+extra to wire for the dev loop.
 
 ### Events that survive the transport
 
@@ -7650,6 +8363,7 @@ const agents = server().get("/api/agents", (c) => ({ ok: new URL(c.req.url).path
 
 // merge() folds both groups into ONE flat path space at their defined paths; a path+method clash
 // throws a RouteConfigError right here at merge time (fail-closed), never a silent shadow at runtime.
+// A group holding .ws() routes or mount()s is refused the same way: add those on the parent.
 export const backend = server().merge(listings).merge(agents)
 ```
 
@@ -7902,11 +8616,12 @@ than something we vouch for.
 {
   "schemaVersion": 1,
   "ok": true,
-  "profile": { "id": "cache-store", "version": 1 },
+  "profile": { "id": "cache-store", "version": 2 },
   "adapterId": "redis-cache",
   "capabilities": [
-    { "capability": "read-write", "status": "passed", "checks": ["set-get", "delete"] },
-    { "capability": "tag-invalidation", "status": "passed", "checks": ["invalidate-tag"] }
+    { "capability": "roundtrip", "status": "passed", "checks": ["set-get-delete"] },
+    { "capability": "tag-invalidation", "status": "passed", "checks": ["invalidate-tag"] },
+    { "capability": "clear", "status": "passed", "checks": ["clear"] }
   ],
   "evidenceHash": "9f2c..."
 }
@@ -7972,11 +8687,13 @@ A route is two files. The page (`x.tsx`) holds the view and its head:
 // own backend, so it can't compile standalone (see the typed examples elsewhere).
 import type { Route } from "./+types/[id]"
 
-// Static OR a function of { data, params, origin }. Static meta is serialized once; function meta
-// recomputes per request (its content can vary with loader data). `origin` is the request's
-// scheme+host (server-resolved, matches the client's location.origin) - use it for ABSOLUTE
-// canonical / og:url / og:image URLs without threading siteUrl through loader data.
-export const meta = ({ data, params, origin }) => ({
+// Static OR a function of { data, pageData, params, origin }. Static meta is serialized once; function
+// meta recomputes per request (its content can vary with loader data). `data` is the exporting
+// module's own loader data: a layout's meta gets its layout's (null without a loader) and reads the
+// page's as `pageData`. `origin` is the request's scheme+host (server-resolved, matches the
+// client's location.origin) - use it for ABSOLUTE canonical / og:url / og:image URLs without threading
+// siteUrl through loader data.
+export const meta = ({ data, params, origin }: Route.MetaArgs) => ({
   title: `User ${data.name}`,
   meta: [{ name: "description", content: data.bio }],
   link: [{ rel: "canonical", href: `${origin}/users/${params.id}` }],
@@ -8228,7 +8945,9 @@ pass through, and every `<link>` attribute with a normal name -
 
 A route's `meta` emits the full social / structured-data head with three public
 helpers - `canonical()`, `openGraph()`, and `jsonLd()` - and
-builds **absolute** URLs from the `origin` argument. Because
+builds **absolute** URLs from the `origin` argument. Import them from
+`@nifrajs/web/seo`: the entry imports nothing at runtime, so a page's browser bundle
+gets the three helpers and none of the server modules the package root also exports. Because
 `meta()` runs in **both** SSR and client navigation it has
 **no server env**: never read `process.env` or the request inside it.
 The framework injects `origin` (the site's scheme + host, e.g.
@@ -8240,9 +8959,11 @@ base, a CDN host) belongs in the `loader`, not `meta()`.
 
 ```ts
 // routes/articles/[slug].tsx - a complete SEO head: canonical + Open Graph + Twitter + JSON-LD,
-// with ABSOLUTE URLs built from `origin`. The three helpers (canonical/openGraph/jsonLd) are public
-// exports of @nifrajs/web; `origin` is the third MetaArgs field (after data + params).
-import { canonical, jsonLd, openGraph, type MetaArgs } from "@nifrajs/web"
+// with ABSOLUTE URLs built from `origin`. The three helpers (canonical/openGraph/jsonLd) come from
+// @nifrajs/web/seo, which imports nothing at runtime, so the page's browser bundle takes only them;
+// `origin` is a MetaArgs field beside data, pageData and params.
+import type { MetaArgs } from "@nifrajs/web"
+import { canonical, jsonLd, openGraph } from "@nifrajs/web/seo"
 
 // CAVEAT: meta() runs in BOTH SSR and client navigation, so it has NO server env - never read
 // `process.env` or the request here. The framework injects `origin` (the site's scheme+host, e.g.
@@ -8329,6 +9050,8 @@ const page = renderPage({
 })
 ```
 
+#### A strict CSP that still caches
+
 A nonce makes every document unique, so a nonce-bearing page is
 `private, no-store` and no shared cache - `withISR`, a CDN - may store
 it. Page data never needs one: it rides in an inert
@@ -8386,6 +9109,16 @@ file that reaches it.
 //     same layout-chain head, so sitewide tags persist across navigation - no page-only flash.
 ```
 
+### Optional server components
+
+The post-4.0 [server-components pipeline](/docs/server-components) supports
+React, Vue, Svelte and Solid. Declare closed input/public-props schemas and authorization
+in `*.component.server.ts(x)`, register owner instances and export a named
+`componentPipeline` configuration. React uses native RSC/Flight; the other three
+hydrate native islands in validated server ranges. Refresh repeats owner GET admission;
+HTML/data/refresh are private/no-store. Writes use server functions or actions. Bind the
+router and await auth-scope invalidation on identity, tenant or permission changes.
+
 ### The build-output contract
 
 The programmatic `buildClient()` API emits a content-hashed directory plus a
@@ -8554,82 +9287,475 @@ See [SSG & ISR](/docs/rendering) for prerendering, [Dev & HMR](/docs/dev) for th
 two dev loops and the `--port` flag, and [Loaders & actions](/docs/data) for the
 data layer in depth.
 
-## Nifra - Databases
+## Nifra - Control APIs (one schema, every client)
 
-> Nifra is database-agnostic: use SQLite, Postgres, or any ORM (Drizzle, Prisma, Kysely) from your handlers and loaders, on Bun, Node, Deno, and the edge.
+> Build an RPC-style control API on core routes: one schema per method gives request validation, a typed TypeScript client, and an OpenAPI 3.2 document whose SSE events let Swift, Kotlin, or Python clients be generated.
 
-Nifra's core bundles **no database layer**. Like Hono or Elysia, it owns the HTTP boundary -
-routing, validation, the typed client - and your handlers, loaders, and actions are just
-functions. Import any database client or ORM and call it there. SQLite, Postgres, MySQL,
-MongoDB, Drizzle, Prisma, Kysely - all work, because none of them are Nifra's concern.
+A desktop app, a CLI, or a mobile companion that drives a local service needs a control API:
+a set of methods, a stream of events, and clients in more than one language. Write each
+method once as a route with a schema. The schema validates requests, types the TypeScript
+client, and describes the method in an OpenAPI document that generators turn into clients for
+other languages.
 
-### Scaffold it (recommended)
+### One file, three methods
 
-You don't have to wire Drizzle by hand. `bun create Nifra` takes a
-`--db` flag and generates a correct, production-grade data layer - schema, typed
-client, `drizzle.config.ts`, the `db:generate`/`db:migrate`
-scripts, and `.env.example` - plus a Database section in the app's
-`AGENTS.md`, so a human _or a coding agent_ starts from the right setup instead
-of inventing one.
+Two methods take a JSON body and answer JSON. The third is a typed event stream. This file
+typechecks against the current packages.
 
 ```ts
-# Scaffold an app with the Drizzle layer already wired (schema, typed client, migrations, scripts, .env):
-bun create nifra notes-api --db drizzle-libsql     # SQLite everywhere incl. the edge (or Turso)
-bun create nifra notes-api --db drizzle-postgres   # Postgres (postgres.js) on Bun/Node/Deno
-bun create nifra notes-api --db drizzle-sqlite     # Bun's built-in bun:sqlite, local file
+import { timingSafeEqual } from "node:crypto"
+import { server } from "@nifrajs/core"
+import { streaming } from "@nifrajs/core/sse"
+import { t, toOpenAPI } from "@nifrajs/schema"
+
+const token = process.env.CONTROL_TOKEN
+if (token === undefined || token.length < 32) throw new Error("CONTROL_TOKEN must be 32+ characters")
+const expected = Buffer.from(`Bearer ${token}`)
+const authorized = (request: Request): boolean => {
+  const given = Buffer.from(request.headers.get("authorization") ?? "")
+  return given.length === expected.length && timingSafeEqual(given, expected)
+}
+
+const Session = t.object({
+  id: t.string(),
+  status: t.union([t.literal("idle"), t.literal("running")]),
+})
+const TurnEvent = t.object({
+  seq: t.integer({ minimum: 0 }),
+  type: t.string(),
+  text: t.optional(t.string()),
+})
+
+export const app = server()
+  .use(streaming())
+  .onRequest((request) =>
+    authorized(request) ? undefined : Response.json({ error: "unauthorized" }, { status: 401 }),
+  )
+  .post(
+    "/session/create",
+    { body: t.object({ cwd: t.string({ minLength: 1, maxLength: 4096 }) }), response: Session },
+    () => ({ id: crypto.randomUUID(), status: "idle" as const }),
+  )
+  .post(
+    "/turn/send",
+    {
+      body: t.object({
+        sessionId: t.string(),
+        message: t.string({ minLength: 1, maxLength: 256 * 1024 }),
+      }),
+      response: t.object({ turnId: t.string() }),
+      bodyLimit: 512 * 1024,
+    },
+    () => ({ turnId: crypto.randomUUID() }),
+  )
+  .sse(
+    "/turn/events",
+    { query: t.object({ turnId: t.string() }), sse: TurnEvent },
+    (c, stream) => {
+      const after = Number(c.req.headers.get("last-event-id") ?? -1)
+      for (let seq = after + 1; seq < 3; seq++)
+        stream.send({ seq, type: "assistant.delta", text: `part ${seq}` }, { id: String(seq) })
+      stream.close()
+    },
+  )
+
+export const spec = toOpenAPI(app, { openapiVersion: "3.2.0", title: "Control API", version: "1.0.0" })
 ```
 
-`drizzle-libsql` is the default recommendation - it's the one SQLite client that runs
-on every runtime, including the edge (a local file in dev, [Turso](https://turso.tech)
-in prod).
+-
+**Methods are routes.** A method name like `session/create` is a path, so a
+call is `POST /session/create` and the typed client reads
+`api.session.create.post(body)`. Use `POST` for anything that changes
+state; one envelope endpoint that dispatches on a method field would hide every method
+from the schema, the client, and the document.
 
-### Inject the client once, read it as c.db
+-
+**The schema is the validator.** A body that does not match answers `422`
+before the handler runs. `maxLength` bounds each field and
+`bodyLimit` bounds the request as it arrives.
 
-The whole integration is one seam: open the DB client once, `decorate` it onto the
-server, and every handler reads it as a typed `c.db`. This is how the scaffold wires
-it - and it keeps the client out of each handler's imports.
+-
+**Authorization runs first.** An `onRequest` hook that returns a response
+ends the request before routing, so no method is reachable without the token. The
+comparison is constant-time, and the server refuses to start without a long token.
+
+-
+**Retries.** A method that must not run twice declares
+`idempotency` on its route, with `.use(idempotency())` from
+`@nifrajs/core/idempotency-plugin` and a namespace per caller.
+
+### Event streams that resume
+
+`.sse(path, { sse: schema }, run)` declares the type of every event the stream
+sends. Give each event an `id` (here its sequence number). A browser
+`EventSource`, or the typed client's `subscribe`, sends the last id it
+saw as `Last-Event-ID` when it reconnects, so the handler replays only what the
+client missed. Keep the events a reconnect may need in memory or in your own store: core
+sends the header, and what to replay is your service's to decide.
+
+### The TypeScript client
 
 ```ts
-// backend/app.ts
-import { server } from "@nifrajs/core/server"
-import { desc } from "drizzle-orm"
-import { db, notes } from "./db"   // your Drizzle client + schema (what the scaffold generates)
+// doc-check: skip - fragment: app is the control server above, imported from its module.
+import { client } from "@nifrajs/client"
 
-// decorate() hangs the client on the context ONCE - every handler then reads it as `c.db`, fully typed.
-export const backend = server()
-  .decorate("db", db)
-  .get("/notes", async (c) => c.db.select().from(notes).orderBy(desc(notes.createdAt)))
+const api = client<typeof app>("http://127.0.0.1:4100", {
+  headers: { authorization: `Bearer ${token}` },
+})
 
-export type Backend = typeof backend
+const session = await api.session.create.post({ cwd: "/work/repo" })
+if (!session.ok) throw new Error(`create failed: ${session.status}`)
+
+const subscription = api.turn.events.subscribe((event) => render(event.seq, event.text ?? ""), {
+  query: { turnId },
+  // After a dropped connection the client reconnects and sends Last-Event-ID itself.
+})
+// subscription.close() ends it.
 ```
 
-### SQLite
+Every call is typed from the server's routes, with no generated code. A call returns a
+`Result`: check `ok`, then read `data`, or
+`status` and `error`.
 
-`bun:sqlite` is built into Bun (zero install); use `better-sqlite3` on
-Node, or `libSQL`/Turso anywhere. Open the connection once and query from your
-routes:
+### Clients in other languages
+
+`toOpenAPI(app, { openapiVersion: "3.2.0" })` from `@nifrajs/schema`
+describes each method's request and response, and each typed stream as
+`text/event-stream` whose `itemSchema` is the SSE event: a
+`data` field holding JSON that matches the route's event schema, plus
+`event`, `id`, and `retry`. The event schema is also a named
+component (`TurnEventsEvent` here), so a generator emits a type for it. The
+`openapi()` plugin from `@nifrajs/middleware` takes the same option and
+serves the document.
 
 ```ts
-import { server } from "@nifrajs/core/server"
-import { Database } from "bun:sqlite"        // Node: better-sqlite3 · edge: Turso/libSQL
+// doc-check: skip - shell commands, not TypeScript.
+// Write the document at build time, then hand it to any OpenAPI 3.2 generator.
+bun -e 'import { spec } from "./control.ts"; await Bun.write("openapi.json", JSON.stringify(spec, null, 2))'
+```
 
-// Open the connection ONCE at module scope (the driver pools internally).
-const db = new Database("app.db")
-const byId = db.query<{ id: number; name: string }, [number]>("SELECT * FROM users WHERE id = ?")
+OpenAPI 3.1 has no field for the items of a stream. Without `openapiVersion` the
+document stays 3.1, declares the stream as a string, and carries the same item schema as
+`x-itemSchema`; the named event component is there either way. A generator that
+reads only 3.1 still produces the event type, and your code decodes each
+`data` line with it.
 
-export const app = server().get("/users/:id", (c) =>
-  // Parameterized (?) - never interpolate user input into SQL.
-  byId.get(Number(c.params.id)) ?? new Response("Not found", { status: 404 }),
-)
-```
+## Nifra - Custom server (createWebApp)
 
-### Postgres with Drizzle (Recommended)
+> Run a page app from your own server entry with createWebApp: static and hashed files, a strict CSP on nifra's nonce, middleware order, loader error logging, graceful shutdown, and nifra check settings.
 
-Drizzle gives you a **fully typed schema**, auto-generated SQL migrations, and a composable query
-builder. Define your schema once, run `bunx drizzle-kit generate` to create
-migrations, and Nifra's loaders use fully-typed queries:
+The standard project layout gets its server entry from `nifra build`. An app that
+calls `createWebApp` from its own entry wires the same pieces by hand. Each one is an
+option or a single call.
 
-```ts
+### A complete entry
+
+Everything on this page in one file. The sections below explain each part. This file
+typechecks against the current packages.
+
+```ts
+import { fileURLToPath } from "node:url"
+import { createCspPolicy, createWebApp, servePublicDir } from "@nifrajs/web"
+import type { Manifest, RenderAdapter } from "@nifrajs/web"
+
+// From your build: the framework adapter, the route manifest, and what buildClient() returned.
+declare const adapter: RenderAdapter
+declare const manifest: Manifest
+declare const build: {
+  readonly entry: string
+  readonly assets: readonly string[]
+  readonly routes: Readonly<Record<string, readonly string[]>>
+  readonly css?: readonly string[]
+}
+declare const errors: { capture(error: unknown, tags: Record<string, string>): void }
+
+// buildClient({ outDir: "dist/assets" }) writes the chunks where their /assets/ URLs point.
+const bundle = servePublicDir({
+  dir: fileURLToPath(new URL("./dist/", import.meta.url)),
+  hashedFiles: new Set(build.assets),
+})
+const publicFiles = servePublicDir({ dir: fileURLToPath(new URL("./public/", import.meta.url)) })
+
+const csp = createCspPolicy({
+  header: ({ sources }) => `default-src 'self'; script-src 'self' ${sources}; object-src 'none'`,
+})
+
+export const app = createWebApp({
+  adapter,
+  manifest,
+  clientEntry: build.entry,
+  routePreload: build.routes,
+  styles: build.css ?? [],
+  csp,
+  server: { requestTimeoutMs: 15_000, gracefulSignals: { drainMs: 8_000 } },
+  use: (app) => {
+    app.onRequest(async (request) => (await bundle(request)) ?? (await publicFiles(request)))
+  },
+  onLoaderError: (error, { route }) => errors.capture(error, { route }),
+})
+
+app.listen(3000)
+```
+
+### Static and hashed files
+
+`servePublicDir` from `@nifrajs/web` serves a directory on Bun, Node and
+Deno. It answers `GET` and `HEAD` only, refuses paths that leave the
+directory or name a hidden file, sets the content type and `nosniff`, handles range
+requests, and returns `undefined` on a miss so the request falls through to your
+routes.
+
+-
+**Hashed build output.** Pass `buildClient()`'s `assets` as
+`hashedFiles`: those files get `immutable` for a year, and anything
+else in the directory gets one day. Write the build to `outDir: "dist/assets"` so
+a chunk's `/assets/...` URL is also its path under `dist/`.
+
+-
+**Your own files.** A second handler on `public/` serves them at the root,
+with the one-day policy.
+
+-
+**Where it runs.** Register the handlers with `app.onRequest` inside
+`use`, so a static hit never reaches page rendering.
+
+On Node, `serve()` from `@nifrajs/node` can serve the bundle itself before
+the app runs, which keeps the direct request path for everything else:
+
+```ts
+// doc-check: skip - fragment: app and build are the createWebApp app and buildClient() output above.
+import { serve } from "@nifrajs/node"
+
+await serve(app, {
+  port: 3000,
+  static: { dir: new URL("./dist/assets/", import.meta.url), hashedFiles: build.assets },
+  signals: { drainMs: 8_000 },
+})
+```
+
+### A strict CSP on nifra's nonce
+
+Pass `createCspPolicy` as `csp` and nifra writes the
+`Content-Security-Policy` header for each document. You do not stash a nonce or set
+the header yourself. Your `header` function receives `sources`: a hash
+for each constant inline script nifra writes, plus a nonce only when the document carries a
+request-specific script (a `defer()`ed value, or `unsafeInlineScript` in
+`meta`).
+
+A document without a nonce gets the same header on every request, so it can still be cached by
+`withISR` or a CDN. A document with a nonce is sent `private, no-store`.
+The older `nonce` option puts a nonce on every document, so nothing is cacheable.
+`createWebApp` refuses `csp` and `nonce` together.
+
+### Middleware goes in use
+
+`createWebApp` declares every page route, and the `/*` catch-all, before
+it returns. `beforeHandle`, `afterHandle`, `around`,
+`derive`, `decorate` and `onError` are copied into each route
+when the route is declared. One of those hooks added to the returned app would therefore reach
+no page. `requestId()` is a `derive`: added late, no page would see
+`c.requestId`. Outside production, adding one throws a `FrameworkError`
+with code `HOOK_AFTER_PAGES` that names the call site. Hooks added inside
+`app.group(prefix, ...)` are still allowed, because a group is its own scope.
+
+Apply middleware in the `use` option instead. It runs before any page is declared,
+and ahead of `mounts` and the `api` mount, so an `onRequest`
+guard also covers a mounted auth handler:
+
+```ts
+// doc-check: skip - fragment: the use option of the createWebApp call above; @nifrajs/middleware is not installed in the docs sandbox.
+import { requestId, securityHeaders } from "@nifrajs/middleware"
+
+createWebApp({
+  // ...
+  use: (app) => {
+    app.use(securityHeaders())
+    app.use(requestId())
+  },
+})
+```
+
+`onRequest` and `onResponse` are read per request, so those two still
+work when added late. Putting everything in `use` means you never need to remember
+which hooks those are.
+
+A plugin applied in `use` works at runtime but cannot add to the returned app's type.
+To get `c.requestId` typed on routes you declare afterwards, call
+`app.use(requestId())` again on the returned app. Named plugins apply once.
+
+### Loader errors
+
+When a loader or action throws and an `_error` boundary renders the page, the error
+is written to the server's `logger`, at the detail set by
+`server.errorLogDetail`. That is the same log line an unhandled 500 produces, and you
+do not need to configure anything for it. A soft-navigation data request that fails is logged
+the same way. A thrown `Response`, such as `redirect()`, is not an
+error and is not logged.
+
+`onLoaderError` is for an error reporter. It sees every real throw with the request,
+params and route id before the boundary renders. If it throws, the error is ignored so rendering
+continues.
+
+### Graceful shutdown
+
+On Bun, `server: { gracefulSignals: { drainMs } }` makes `listen()`
+handle `SIGTERM` and `SIGINT`. The server gives in-flight requests up
+to `drainMs` (default 10 000) to finish, then stops, closing any that are still
+running. On Bun, new connections can still arrive during that window, so the load balancer
+should stop routing to the instance first, as most platforms do before they send
+`SIGTERM`. Keep `drainMs` under your platform's kill grace period:
+`docker stop` waits 10 seconds. `true` uses the default. On Node and
+Deno, pass
+`signals: { drainMs }` to `serve()` instead, as above.
+
+### Letting check and assure read the app
+
+`nifra check`, `assure`, `routes` and the other commands that
+read the app import it, so everything the app does at module scope runs. A command that only
+reads what the app declares sets `NIFRA_REFLECT` to its own name first:
+`check`, `routes`, `context`, `openapi`,
+`contracts`, `capabilities`, `manifest`, `doctor`
+, `diff`, `sync-routes`, `sync-manifest`, and
+`assure` without `--bundle`, `--strict`,
+`--hydration`, `--interact` or `--out`. Commands that send the
+app requests, such as `smoke`, `prove`, `levels` and the
+`assure` bundle, leave it unset. Check it to skip work a read never needs:
+
+```ts
+// doc-check: skip - fragment: an app module's Redis client; ioredis is not installed in the docs sandbox.
+import Redis from "ioredis"
+
+// Unset when the app really runs; "check", "routes", "assure", ... while nifra only reads it.
+export const redis = process.env.NIFRA_REFLECT ? undefined : new Redis(process.env.REDIS_URL!)
+```
+
+-
+**Environment validation.** An app that validates its environment on import still needs
+values to pass it. Supply them with `--env-file`, for example
+`nifra check --env-file .env.example`. Variables already set in the shell win.
+
+-
+**A process that will not exit.** If something the app opened is still keeping the process
+alive 2 seconds after the command has answered, the command exits with its own result and
+says that the app kept it open.
+
+### nifra check for a custom entry
+
+-
+**Routes nifra cannot see.** A mounted handler such as better-auth answers paths that are
+not in your backend, and no typed client covers them. Declare the mount opaque,
+`
+mounts: [{ path: "/api/auth", app: auth, opaque: "better-auth" }]
+`
+, and when `nifra.assurance.ts` names this app as its `source`, the
+check skips a `fetch` into that prefix by itself. Without that, list the prefixes
+in `nifra.check.json` next to `package.json`:
+
+```ts
+{
+  "externalMounts": ["/api/auth"]
+}
+```
+
+-
+**One call nifra cannot type.** For a single call rather than a whole prefix, such as a
+static file, put `// nifra-expect NF-C002: ` on the line or in the
+comment block above it. The finding stays in the report as info, with your reason. A comment
+with no reason silences nothing.
+
+-
+**Two repositories, one runtime.** When a linked sibling repository brings its own install
+of nifra or React, `nifra check` reports the duplicates. A reinstall in this app
+cannot remove a copy that another project installed. Declare the packages single-copy and
+nifra loads this app's copy for every importer:
+
+```ts
+{
+  "name": "my-app",
+  "nifra": { "singleCopy": ["@nifrajs/*", "react", "react-dom"] }
+}
+```
+
+Packages duplicated the same way are reported as one finding with one combined
+`singleCopy` list. The preload this needs, and the version-skew case it cannot
+cover, are in [Troubleshooting](/docs/troubleshooting).
+
+## Nifra - Databases
+
+> Nifra is database-agnostic: use SQLite, Postgres, or any ORM (Drizzle, Prisma, Kysely) from your handlers and loaders, on Bun, Node, Deno, and the edge.
+
+Nifra's core bundles **no database layer**. Like Hono or Elysia, it owns the HTTP boundary -
+routing, validation, the typed client - and your handlers, loaders, and actions are just
+functions. Import any database client or ORM and call it there. SQLite, Postgres, MySQL,
+MongoDB, Drizzle, Prisma, Kysely - all work, because none of them are Nifra's concern.
+
+### Scaffold it (recommended)
+
+You don't have to wire Drizzle by hand. `bun create Nifra` takes a
+`--db` flag and generates a correct, production-grade data layer - schema, typed
+client, `drizzle.config.ts`, the `db:generate`/`db:migrate`
+scripts, and `.env.example` - plus a Database section in the app's
+`AGENTS.md`, so a human _or a coding agent_ starts from the right setup instead
+of inventing one.
+
+```ts
+# Scaffold an app with the Drizzle layer already wired (schema, typed client, migrations, scripts, .env):
+bun create nifra notes-api --db drizzle-libsql     # SQLite everywhere incl. the edge (or Turso)
+bun create nifra notes-api --db drizzle-postgres   # Postgres (postgres.js) on Bun/Node/Deno
+bun create nifra notes-api --db drizzle-sqlite     # Bun's built-in bun:sqlite, local file
+```
+
+`drizzle-libsql` is the default recommendation - it's the one SQLite client that runs
+on every runtime, including the edge (a local file in dev, [Turso](https://turso.tech)
+in prod).
+
+### Inject the client once, read it as c.db
+
+The whole integration is one seam: open the DB client once, `decorate` it onto the
+server, and every handler reads it as a typed `c.db`. This is how the scaffold wires
+it - and it keeps the client out of each handler's imports.
+
+```ts
+// backend/app.ts
+import { server } from "@nifrajs/core/server"
+import { desc } from "drizzle-orm"
+import { db, notes } from "./db"   // your Drizzle client + schema (what the scaffold generates)
+
+// decorate() hangs the client on the context ONCE - every handler then reads it as `c.db`, fully typed.
+export const backend = server()
+  .decorate("db", db)
+  .get("/notes", async (c) => c.db.select().from(notes).orderBy(desc(notes.createdAt)))
+
+export type Backend = typeof backend
+```
+
+### SQLite
+
+`bun:sqlite` is built into Bun (zero install); use `better-sqlite3` on
+Node, or `libSQL`/Turso anywhere. Open the connection once and query from your
+routes:
+
+```ts
+import { server } from "@nifrajs/core/server"
+import { Database } from "bun:sqlite"        // Node: better-sqlite3 · edge: Turso/libSQL
+
+// Open the connection ONCE at module scope (the driver pools internally).
+const db = new Database("app.db")
+const byId = db.query<{ id: number; name: string }, [number]>("SELECT * FROM users WHERE id = ?")
+
+export const app = server().get("/users/:id", (c) =>
+  // Parameterized (?) - never interpolate user input into SQL.
+  byId.get(Number(c.params.id)) ?? new Response("Not found", { status: 404 }),
+)
+```
+
+### Postgres with Drizzle (Recommended)
+
+Drizzle gives you a **fully typed schema**, auto-generated SQL migrations, and a composable query
+builder. Define your schema once, run `bunx drizzle-kit generate` to create
+migrations, and Nifra's loaders use fully-typed queries:
+
+```ts
 // backend/db/schema.ts - define your schema (source of truth)
 import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core"
 export const users = pgTable("users", {
@@ -8929,7 +10055,11 @@ Route data failed the output guard that stands between loaders/actions and the b
 
 **Fix:** declare `loaderOutput`/`actionOutput` as a Standard
 Schema that describes exactly the fields the page needs. `nifra check` flags routes
-without one (NF-C030).
+without one (NF-C030): an error when the loader's own body returns a literal (an object,
+array, string, number or boolean), since every request that reaches that return fails, and a
+warning when only running it shows what it returns. `nifra schemas --write` drafts
+a schema from the loader's return type for review, and
+`nifra fix --code NF-C030` writes that draft for each flagged route.
 
 ### Rendering and data
 
@@ -8992,6 +10122,26 @@ serving the old page until its freshness runs out. The revalidate endpoint answe
 permission for this zone, project or service; a 5xx or `network_error` is retried on
 its own.
 
+### Silencing a nifra check finding
+
+`nifra check` names each finding with an `NF-` code. Where a finding is
+reviewed and intended, a comment on the flagged line, or anywhere in the comment block directly
+above it, says so and why:
+
+The comment answers only the code it names. A finding that fails the check, and every security
+finding, is silenced only with a reason after the colon; an advisory also accepts the comment
+without one. A blank line or a line of code ends the block, so a comment never reaches the next
+statement. A silenced security finding, interpolated SQL (NF-C006) included, stays in the report
+as information, with the comment and its reason as evidence. Some codes also answer to a name: `sql-dynamic` (NF-C006),
+`raw-response` (NF-C007), `reserved-segment` (NF-C018),
+`route-overlap` (NF-C024 and NF-C025) and `param-modifier` (NF-C026).
+`@nifra-gate-reviewed` silences nothing; a finding under it names the comment to
+write instead.
+
+A fail-open gate (NF-S001) or a non-constant-time comparison (NF-S002) in code that only
+ever runs in a browser is a warning rather than an error: the server's own gate decides
+there.
+
 ## Nifra - Failure laboratory
 
 > Replayable durable-failure schedules on virtual time: crash after commit, duplicate delivery, reordering, budget expiry, and checkpoint contention.
@@ -9511,6 +10661,146 @@ If the project has `nifra.assurance.ts`, run `nifra assure --json`.
 Exercise every redirect path - loader, action, and layout gate - and, if the app proxies,
 each deploy adapter it uses.
 
+## Nifra 5.0 migration guide - upgrade from 3.x or 4.x
+
+> Upgrade a Nifra 3.x or 4.x application to 5.0: the chained upgrade command, the frontend/backend layout move and its follow-ups, drafted output schemas, the backend's HTTP mount, the 5.0 defaults that changed, and the release gates.
+
+Nifra 4.0 split every app into a frontend and a backend half, and 5.0 enforces the split and
+changes a handful of defaults. The upgrade command pins the packages and moves imports; the
+layout migration moves files; this guide covers what each leaves to you and how to tell a
+finished migration from one that needs a decision.
+
+### 1. Run the executable upgrade
+
+```ts
+
+```
+
+Run the command from the release you are moving to. It chains every release recipe between
+the installed version and 5.0, so a 3.x app takes the 4.0 steps (the retired
+`@nifrajs/web/server-only` import moves to `@nifrajs/web/backend-only`)
+and the 5.0 ones in one pass, and prints each release's notes. It lists every
+`@nifra-gate-reviewed` comment, which silences nothing in 5.0: after review, write
+`// nifra-expect : ` with the code `nifra check`
+reports there. The upgrade never writes a reason for you.
+
+### 2. Move onto the frontend/backend layout (from 3.x)
+
+```ts
+
+```
+
+Each route file splits into `x.tsx`, the page, and `x.backend.ts`, which
+holds `loader`, `action`, `middleware` and the other server
+exports. The root `backend.ts` and `framework.ts` move to
+`backend/app.ts` and `backend/framework.ts`, and every other module goes
+to `frontend/`, `backend/` or `shared/` by who imports it at
+runtime. A folder whose imported files all land in one zone moves whole, so a component nothing
+imports yet travels with its folder; a folder split between zones is reported instead.
+
+```ts
+
+```
+
+To keep a folder where it is, declare it a zone before migrating. The migration leaves zoned
+folders in place, and builds, `nifra dev` and `nifra check` enforce them
+like the default folders.
+
+```ts
+
+```
+
+`nifra migrate layout --zones` writes those entries for you: every module the
+layout would move stays where it is, and `package.json` lists the widest folder
+whose files all belong to one side, or the file itself where its folder holds both. Route
+files are still split and the root entries still move. A path nested in another's folder
+overrides it, so a backend file can sit in a frontend folder without moving.
+
+The command exits `0` when nothing needs a decision. A step with a known command,
+such as drafting an output schema for a backend half it did not write, is listed under
+`next` and in `followUps` with `--json`, and does not fail it.
+An issue (an import it could not place, a frontend that still uses a moved name at runtime)
+exits `1`.
+
+5.0 refuses a route file that still exports a server name: `nifra build` and the
+server stop on it, and `nifra check` reports it as NF-C041.
+`nifra fix --code NF-C041` moves the export and the code only it uses into the
+route's backend half.
+
+### 3. Draft and review output schemas
+
+A loader or action that returns data needs `loaderOutput` or
+`actionOutput`; the data is projected through it, so undeclared keys never reach
+the page. `nifra schemas --write` drafts each missing one from the function's return
+type, leaves out credential-like fields and marks it `nifra:generated` so later runs
+keep it current. A value typed `any` or `unknown` drafts as
+`t.json()`, which admits anything: `nifra schemas` lists those paths and
+`nifra check` warns on them (NF-C030). Give the value a type and draft again.
+`nifra schemas --check` fails on a missing, stale or open schema, for CI.
+
+### 4. Choose where the backend is served
+
+3.x and 4.x served `backend/app.ts` at `/api` by default. In 5.0
+`createWebApp` serves it over HTTP only at an `apiPrefix` the app sets;
+without one the backend is loader-only, reached in-process through `ctx.api`, and a
+browser call to `/api` reaches page routing. `nifra migrate layout` adds
+`apiPrefix = "/api"` when it moves a root `backend.ts`, and
+`nifra check` reports a framework config that sets none (NF-C035).
+
+```ts
+
+```
+
+With both `nifra.config.ts` and `backend/framework.ts`, every command
+takes `apiPrefix`, `apiStrip`, `mounts`, `csp`,
+`nonce`, `serverComponents` and `use` from
+`backend/framework.ts` when `nifra.config.ts` leaves them unset. The
+backend sees each request's full path unless `apiStrip` is on, so its routes are
+registered under the prefix; `nifra routes` marks one outside it as in-process
+only, and `nifra dev` and `nifra build` warn about it.
+
+### 5. Review the 5.0 defaults that changed
+
+-
+Root status pages (`_404.tsx`, `_<status>.tsx`) and
+`_error.tsx` render inside the layouts above them. One that imports the root
+layout to wrap itself renders it twice (NF-C034); remove the wrap, or export
+`inLayouts = false`.
+
+-
+A layout's `meta` receives its own loader data as `data` and the page's
+as `pageData` (NF-C040).
+
+-
+A WebSocket handshake runs the route chain an HTTP `GET` at the same point runs, so
+guards added before `app.ws()` apply to it.
+
+-
+A `Response` returned to more than one request is no longer shared; build one per
+request.
+
+-
+`nifra check` fails a secret comparison (NF-S002) outside browser code of a web
+app.
+
+`nifra upgrade` prints the full list with the finding or the one-line change that
+keeps the 4.x behavior for each.
+
+### 6. Run the release gates
+
+-
+Run `nifra check --json` and fix every error. `nifra doctor` lists any
+package still on another release.
+
+-
+If the project has `nifra.assurance.ts`, run `nifra assure --json`.
+
+- Run the application test suite and a production build.
+
+-
+Exercise the pages that load or post data, and every browser call to the backend, under
+`nifra dev` and against the production build.
+
 ## Nifra - Migrating from Express, Hono, Fastify & Elysia
 
 > Move a backend to Nifra: routing, middleware, validation, and body parsing map directly from Express, Hono, Fastify, and Elysia - and you gain a typed client, multi-runtime deploy, and optional SSR.
@@ -10431,6 +11721,80 @@ in its `package.json`:
 `{'"nifra": { "environment": "frontend" | "backend" | "shared" | "library" }'}`.
 A file in no zone is a build error, so nothing is ever classified by accident.
 
+A package whose entries run on different sides gives each export subpath its own:
+
+```ts
+{
+  "name": "@shop/payments",
+  "exports": {
+    ".": "./src/index.ts",
+    "./react": "./src/react.tsx",
+    "./schema": "./src/schema.ts"
+  },
+  "nifra": {
+    "environment": {
+      ".": "backend",
+      "./react": "frontend",
+      "./schema": "library"
+    }
+  }
+}
+```
+
+An import is judged by the entry it names: the exact subpath first, then the most specific
+`*` pattern. Here a page may import `@shop/payments/react` but not
+`@shop/payments`, and backend code may not import the React entry, even when two
+entries are backed by one file. Importing an entry the map leaves out is an error. A file
+reached by path rather than by entry, through a relative or aliased deep import, takes the
+side of every mapped entry whose own imports reach it, and a file no mapped entry reaches is
+an error.
+
+The app's own `package.json` can set sides too, so a folder that has to stay
+where it is, or a family of workspace packages, needs no edit of its own:
+
+```ts
+{
+  "name": "my-app",
+  "nifra": {
+    "zones": {
+      "packages": { "@shop/*": "library", "@shop/db": "backend" },
+      "backend": ["migrations", "src/ui/mailer.ts"],
+      "frontend": ["src/ui"]
+    }
+  }
+}
+```
+
+`packages` gives a side to a package that does not declare one, by exact name or
+by a prefix ending in `*`; a package's own declaration always wins.
+`backend`, `frontend` and `shared` list app folders, or
+single files, that count as that zone. A path inside another's folder overrides it, so the
+most specific entry decides: above, `src/ui/mailer.ts` is backend code in a
+frontend folder. One path listed under two sides is refused. Builds, dev servers,
+`nifra check` and the editor plugin all read this setting.
+
+A project that serves no pages has no browser, so the zones do not apply to it. Declare that
+in its `package.json` with `{'"nifra": { "kind": "api" }'}`:
+`nifra check` then skips the zone checks and the server-only import check there,
+and treats every file as server code. It is read from the nearest `package.json`
+and only takes values `"api"` and `"web"`. A directory with web config
+(`nifra.config.ts` exporting `adapter`, or
+`backend/framework.ts`) keeps its zone checks under it, and
+`nifra check` reports the clash (NF-C037); builds and dev servers never read it.
+
+A directory with `backend/app.ts` and no web config is read as an API-only app
+whether or not it declares the kind: `nifra routes`, `nifra context`,
+`nifra openapi` and `nifra mcp` load `backend/app.ts` alone,
+and the tools, resources and prompts its backend declares reach `nifra mcp`.
+
+Those commands, the contract lock and the route lints see only what
+`backend/app.ts` exports. An API whose app is built by a factory such as
+`createApp(deps)`, with its real dependencies wired in another entry, exports the
+same app from `backend/app.ts` built with stand-in dependencies, so every operation
+is visible without a database or secrets; `nifra check` names an implemented
+operation it does not serve (NF-C039). See
+[the stand-in entry](/docs/types-first#stub-entry).
+
 ### A route is two files
 
 The page renders; its backend half loads. A server-only export (`loader`,
@@ -10461,7 +11825,8 @@ import { notFound } from "@nifrajs/web"
 import type { Route } from "./+types/[id]"
 
 // What the page receives - and the ONLY fields that leave the server. A field the loader returns
-// but the schema does not declare is dropped before rendering.
+// but the schema does not declare is dropped before rendering; in development the console names
+// each dropped field, so a missing declaration never shows up as a silently blank page.
 export const loaderOutput = t.object({ name: t.string(), avatarUrl: t.string() })
 
 export async function loader({ params, api }: Route.LoaderArgs) {
@@ -10522,16 +11887,48 @@ import fails the build with the chain that led to it:
 -
 **Browser code reads only public environment variables** - `NODE_ENV` and
 names with the `PUBLIC_` prefix. Any other `process.env` read in a
-page, `frontend/` or `shared/` fails the build.
+page, `frontend/` or `shared/` fails the build, optional access (
+`process.env?.["SECRET"]`) included.
 
 -
 **The build scans what it emits.** A client bundle, a public file or a prerendered page
-that contains what looks like a credential fails the build.
+that contains what looks like a credential fails the build. A label in a message catalog (
+`{'{ password: "Password" }'}`) and a documented placeholder (
+`your-api-key`) are text, not credentials.
 
 The same rules run in `nifra dev` (a refused module is answered with a 403 before
-its source is sent), in both bundlers, for every framework, and in `nifra check`.
-An app on the older layout moves with `nifra migrate layout`: a dry run that
-reports every move, then `--write`.
+its source is sent), in both bundlers, for every framework, and in `nifra check`,
+which follows the imports the bundler follows: relative paths, tsconfig `paths`
+and `baseUrl`, `package.json` `imports`, and the
+`clientModule` the browser entry loads. An app on the older layout moves with
+`nifra migrate layout`: a dry run that reports every move, then
+`--write`. It follows the same imports, rewrites them and test-runner mocks (an
+alias through the same alias), and moves the config's `clientModule`, any module
+path the config builds from its own folder, and component pipeline entries with their
+modules. A test moves with the file beside it, snapshots included. Each
+`tsconfig*.json` keeps every file in, or out of, its program as before. It adds
+`.nifra/` to `.gitignore` and leaves data files and folders zoned in
+`package.json` where they are.
+
+A route file that holds server code splits into the page and its
+`x.backend.ts`. Data both halves read moves to `x.shared.ts` beside
+them; a value that cannot move is copied into each half and reported. A loader or action
+that returns data without an output schema gets a draft one, typed from what it returns:
+review that the browser may see every field it declares. The migration reports what still
+needs a hand, such as an alias with no target that covers a moved file, a specifier that
+names nothing installed, or a sibling workspace package that names a moved file. It never
+edits files outside the app.
+
+An API-only app, one that declares `{'"nifra": { "kind": "api" }'}` or has no web
+config, no `routes/` and a `backend.ts` that exports
+`backend`, migrates as one: only
+`backend.ts` moves, to `backend/app.ts`, with the imports from it and
+to it. Nothing is split or zoned. The migration adds `backend` to tsconfig
+`include`, `.nifra/` to `.gitignore`, and the declaration
+to `package.json` when it is missing. Web config without `routes/`
+could be either kind of app, so the migration stops and asks which. Until an app moves,
+`nifra check` fails with NF-C038 on its root `backend.ts` or
+`framework.ts`, since no contract gate reads them there.
 
 ## Nifra - Contract-derived adversarial testing
 
@@ -10617,6 +12014,14 @@ await assertAdversarialContract(app, {
 Missing, invalid, or unsynthesizable witnesses become explicit coverage gaps. The default is
 fail-closed; `requireCoverage: false` makes gaps advisory.
 
+Declared `params` and `headers` get witnesses too, validated before any
+case runs, so a body or query case is rejected by the input it mutates. The harness never
+invents credentials: `authorization`, `cookie`, `x-api-key`
+and names that look like a key, token, secret or signature come from the witness and
+`prepareRequest` only, and are never mutated. A route with a `cookies`
+schema needs `headers.cookie` in its witness, and a missing credential is a gap that
+names it.
+
 ### Auth and tenant context
 
 `prepareRequest` runs for every case and runtime. Use it to attach a test session,
@@ -10693,6 +12098,41 @@ await assertAdversarialContract(app, {
 })
 ```
 
+### A web app's routes in a test
+
+Give the test the same route manifest the app serves. `discoverRoutes(dir)` from
+`@nifrajs/web/fs` scans a routes directory the way the build does, so every page
+arrives with its `.backend.ts` half: its loader, action, output schemas and
+middleware. A built app can import the generated `server-manifest` instead, which
+bakes the same pairs into static imports.
+
+```ts
+// test/routes.test.ts - render the real routes in-process, each page with its backend half.
+import { expect, test } from "bun:test"
+import { createWebApp } from "@nifrajs/web"
+import { discoverRoutes } from "@nifrajs/web/fs"
+import { reactAdapter } from "@nifrajs/web-react"
+
+const app = createWebApp({
+  adapter: reactAdapter,
+  // Scans routes/ the way the build does: a page and its .backend.ts half always arrive together.
+  manifest: discoverRoutes(`${import.meta.dir}/../routes`),
+  clientEntry: "/client.js",
+})
+
+test("the users page runs its loader", async () => {
+  const res = await app.fetch(new Request("http://localhost/users/7"))
+  expect(res.status).toBe(200)
+})
+```
+
+`buildManifest(files, load)` pairs a page with its backend half only when both are
+in `files`. It is pure, so it cannot know a half is missing, and a hand-written list
+that names the page alone serves it without its loader and guards: the test passes against a
+route production never runs. `nifra doctor` flags a `buildManifest(...)`
+call whose array literal or `import.meta.glob` patterns reach a page but not the
+backend half beside it.
+
 ### Browser end-to-end
 
 API flows stay in-process through `testSession` - typed, cookie-aware, no
@@ -10826,6 +12266,23 @@ implementation into the client.
 See [Framework contract](/docs/contract) for the decoupled form and its scaling
 guidance.
 
+The tooling reads the backend `backend/app.ts` exports. An app that
+`implement`s a contract somewhere else, such as a `createApp(deps)`
+factory, is invisible to the contract lock and the route lints until that file serves it.
+`nifra check` names each implemented operation the backend does not serve
+(NF-C039), and counts them when there is no `backend/app.ts` at all. Export the
+same app built with stand-in dependencies:
+
+```ts
+// backend/app.ts - the backend nifra's tooling reads
+import { createApp } from "../src/app"
+import { stubDeps } from "../src/stub-deps"
+
+// The real entry builds the app with real dependencies elsewhere. This one builds the same routes with
+// stand-ins, so the contract lock, the typed client checks and `nifra routes` see every operation.
+export const backend = createApp(stubDeps())
+```
+
 ### OpenAPI
 
 The `openapi()` middleware builds an OpenAPI 3.1 document from your registered
@@ -10965,6 +12422,84 @@ input, so Nifra will not guess which app to point them at; a level that fuzzed y
 server by default would be a footgun, and a skipped route is reported rather than passed over
 in silence.
 
+An app that needs a session, real row ids or signed tokens passes them to the runner instead of
+rewriting requests inside the executor: `witnesses`, `prepareRequest`,
+`isRejected`, `include` and `maxMutationsPerInput` on
+`invariants` reach every L4 run, from `nifra levels` and the
+`nifra_levels` MCP tool alike. `setup` provisions a throwaway target only
+when L4 runs: it is called once, before the first L4 request, and its `teardown`
+always runs after the run, a failing one included. The example keeps its target in memory; a
+database or container belongs in your own `setup`.
+
+```ts
+// nifra.assurance.ts
+// doc-check: skip - the backend and its seed data are app-specific
+import { defineAssuranceConfig } from "@nifrajs/core/assurance"
+import { createBackend } from "./backend"
+
+export default defineAssuranceConfig({
+  source: createBackend({ rows: new Map() }),
+  policy: { rules: [/* ... */] },
+  invariants: {
+    // Called once, before the first L4 request - never when this file is imported, so
+    // `nifra check` and `nifra assure` provision nothing.
+    setup: async () => {
+      const rows = new Map([["row_1", { id: "row_1", owner: "fixture" }]])
+      const target = createBackend({ rows })
+      return {
+        executor: (request) => target.fetch(request),
+        teardown: () => rows.clear(), // runs after a failing run too
+      }
+    },
+    // Known-good inputs for schemas L4 cannot synthesize (an opaque validator, a real id).
+    witnesses: { "PATCH /rows/:id": { params: { id: "row_1" }, body: { title: "ok" } } },
+    // Attach what the app needs on every case: a session, a signed token.
+    prepareRequest: (request) => {
+      const headers = new Headers(request.headers)
+      headers.set("cookie", "session=fixture")
+      return new Request(request, { headers })
+    },
+  },
+})
+```
+
+### Response contracts
+
+Next to the ladder, `nifra levels` counts the routes that declare a
+`response` or `errors` schema and how each is held at runtime:
+_enforced_, _warn-only_ (checked, original payload still sent) or _typed-only_
+(no `responseContract()` covers it). A typed-only route is usually registered on a
+server other than the one the plugin is installed on, or before it; the report names the routes
+and says which.
+
+The count does not fail a level on its own. To make L1 require enforcement, add a
+`baseline` rule selecting `hasResponse: true`: unlike
+`rules`, where the first match owns a route, a baseline rule is checked on every
+route it matches, so one entry covers every class. `nifra assure --strict` also fails
+while any declared route is typed-only or warn-only.
+
+```ts
+// nifra.assurance.ts
+// doc-check: skip - the backend is app-specific
+import { defineAssuranceConfig, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
+import { backend } from "./backend"
+
+export default defineAssuranceConfig({
+  source: backend,
+  policy: {
+    rules: [/* first match owns each route: classify by path, method, capability ... */],
+    // Checked on every route it matches, whichever rule owns the route.
+    baseline: [
+      {
+        name: "response-contract",
+        match: { hasResponse: true },
+        require: [NIFRA_ASSURANCE.RESPONSE_CONTRACT],
+      },
+    ],
+  },
+})
+```
+
 ### For coding agents
 
 The `nifra_levels` MCP tool returns the same
@@ -11136,9 +12671,11 @@ A suspended task's status message carries the pending continuation in `metadata`
 }
 ```
 
+The resuming peer is usually the agent that asked for the tool, so it does not approve its own call: the run asks `ports.approval` again and hands it the peer's `approval` as `callerDecision`. With no approval port the task stays `TASK_STATE_INPUT_REQUIRED`. Return `resumeApproval: "caller"` from `ports` only when the peer is the approver, such as a human operator's client.
+
 Cross-request registries (cancellation, subscription fan-out, push notifications) are deliberately out of scope for the stateless seam; those spec methods answer `UnsupportedOperationError` (-32004).
 
-A reply larger than `maxOutputBytes` answers the request with a JSON-RPC internal error (-32603, `output_limit`), the same error a stream sends when it runs out of budget. A request whose ports or store fail answers with -32603 `internal_error`, keeping the request's `id`.
+A reply larger than `maxOutputBytes` answers the request with a JSON-RPC internal error (-32603, `output_limit`), the same error a stream sends when it runs out of budget. A stream that runs out also aborts the run's signal, as a client disconnect does, so the run stops calling the model. A request whose ports or store fail answers with -32603 `internal_error`, keeping the request's `id`.
 
 The seam performs no authentication or authorization - wrap it with your app's route guards and scope every port in `ports(c)` to the caller.
 
@@ -11149,6 +12686,62 @@ Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one
 For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
 [`../../llms-full.txt`](../../llms-full.txt).
 
+## @nifrajs/acp
+
+An `AgentBackend` for agents that speak the [Agent Client Protocol](https://agentclientprotocol.com)
+(version 1) over stdio: Claude Code through `claude-code-acp`, Codex through `codex-acp`, Gemini CLI
+with `--experimental-acp`, or any other ACP agent. A Nifra host, RPC server, or app drives it like any
+other backend.
+
+```ts
+import { AcpBackend } from "@nifrajs/acp"
+import { CodingAgentHost } from "@nifrajs/coding-agent"
+
+const backend = new AcpBackend({
+  command: "claude-code-acp",
+  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
+})
+const host = new CodingAgentHost({ backend })
+```
+
+Each session is one agent process: `initialize` (protocol version 1, refused otherwise), an optional
+`authenticate` with `authMethod`, then `session/new` in the session's absolute `cwd`. A message is a
+`session/prompt`; its updates become protocol events:
+
+| ACP update | Event |
+| --- | --- |
+| `agent_message_chunk` | `assistant.delta`, and the whole reply as `assistant.message` before a tool call and at the end |
+| `agent_thought_chunk` | `reasoning.delta` |
+| `tool_call`, `tool_call_update` | `tool.started`, then `tool.completed` once the status is `completed` or `failed` |
+| `plan` | `plan.updated` |
+| `usage_update` | `context.usage` (`used`, `size`) |
+| anything else | `x-acp.<sessionUpdate>` with a bounded copy of the update |
+
+The stop reason ends the turn: `end_turn`, `max_tokens`, and `max_turn_requests` complete it (any but
+`end_turn` also reported as `x-acp.stop_reason`), `refusal` fails it, and `cancelled` stops it.
+
+`session/request_permission` surfaces as `approval.required` (`capability` is `acp.<tool kind>`).
+`resolveApproval` answers with the agent's `allow_once` or `reject_once` option and never an "always"
+one, so the host's approval policy stays in charge; with no such option it answers `cancelled`. An
+approval the agent withdraws with `$/cancel_request` is answered and reported as `approval.resolved`
+with `approved: false`.
+
+The client offers no filesystem or terminal methods: the agent uses its own tools, and those
+requests get JSON-RPC `-32601`. `cancel` answers open approvals `cancelled` and sends
+`session/cancel`; an agent that has not ended the turn after `cancelGraceMs` (default 2 seconds) is
+stopped, which ends its session.
+
+The agent runs with `PATH`, `HOME`, locale, terminal, user, shell, and temp variables plus what `env`
+adds; nothing else from the parent environment passes, so give it its model credentials explicitly.
+Error text from the agent (a refused request, or the last error-looking stderr line when it exits)
+is cut to a bounded length with those values and common key shapes masked. stdout carries only
+JSON-RPC, one message per line, each at most `maxRecordBytes` (default 1 MiB).
+
+The package passes `@nifrajs/agent-protocol/conformance` against a scripted ACP agent.
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).
+
 ## @nifrajs/ag-ui
 
 Mount a nifra agent as an [AG-UI](https://docs.ag-ui.com) (Agent-User Interaction protocol) endpoint: one POST accepting `RunAgentInput`, a stream of AG-UI events out over SSE - run lifecycle, step and tool-call events projected from the runner's step evidence, text message events for the output, and a typed continuation for human-in-the-loop resume.
@@ -11269,6 +12862,11 @@ terminal events - the run is never re-executed. A disconnected run keeps going a
 real terminal events for that reconnect. Without an `evidenceLog` nothing can rejoin a dropped
 stream, so the disconnect aborts `ports.signal` and the turn suspends as `cancelled`.
 
+Exceeding `maxOutputBytes` detaches the viewer in the same way, including an oversized initial state
+snapshot. The response closes immediately, with an `output_limit` error frame when the remaining
+budget permits it. Without a log the turn is aborted; with a log it continues recording its real
+terminal result for reconnect rather than storing the viewer's output-limit error as the run result.
+
 ```ts
 import { createMemoryAgentEvidenceLog } from "@nifrajs/agent/events"
 
@@ -11281,7 +12879,8 @@ adapter implementing the same `AgentEvidenceLog` interface.
 When more than one caller shares the route, also pass `evidenceOwner: (c) => <the caller's user or
 tenant id>`: turns are recorded and replayed under that owner, so another caller's reconnect or
 reused `runId` finds none of them. Without it a turn id (by default the client's `runId`) works as a
-bearer capability. The owner function runs before any replay; throwing from it refuses the request.
+bearer capability. The owner function runs before any replay; throwing from it refuses the request with `403`, and a
+thrown `Response` answers the request as built, as one thrown from `ports` does.
 
 The seam performs no authentication or authorization - wrap it with your app's route guards and scope every port in `ports(c)` to the caller.
 
@@ -11367,10 +12966,17 @@ dropped stream, so the disconnect aborts `ports.signal` and the turn suspends as
 `createMemoryAgentEvidenceLog` (from `@nifrajs/agent/events`) is the single-process dev/test
 reference; a durable, multi-process log is an adapter implementing the same `AgentEvidenceLog`
 interface.
+
+One SSE response emits at most `maxOutputBytes` (default 4 MiB), so a client that stops reading
+cannot make the server queue a whole run. Past the cap the response ends with an `error` frame
+(`output_limit`): with an `evidenceLog` the run keeps recording and a `Last-Event-ID` reconnect reads
+on from where the response stopped; without one the run is cancelled.
 When more than one caller shares the route, also pass `evidenceOwner: (c) => <the caller's user or
 tenant id>`: turns are recorded and replayed under that owner, so another caller's reconnect or
 reused `turnId` finds none of them. Without it a turn id works as a bearer capability. The owner
-function runs before any replay; throwing from it refuses the request.
+function runs before any replay; throwing from it refuses the request with `403`, and a thrown
+`Response` answers the request as built, as one thrown from `ports` does. A JSON-mode run that
+throws answers `500 run_failed`, or `409 resume_unavailable` when the POST resumed a turn.
 
 Execution policies can be required by a tool contract. `createLocalProcessAdapter` applies cwd and
 environment filtering, timeouts, and cancellation to child processes. On POSIX each run leads its
@@ -11404,6 +13010,11 @@ counts.
 - **Ordered, deduplicated streaming.** A turn arrives as an ordered stream of `AgentEventView`s.
   Out-of-order and redelivered frames are reordered and de-duplicated by sequence; a bounded buffer
   skips an unfilled gap rather than stalling.
+- **Turns that survive a dropped connection.** When a turn's stream breaks mid-turn, `send` follows
+  the turn again with `turn.attach` from the last seq it received (`resumeAttempts`, default 3;
+  `resumeDelayMs`, default 250), so the views continue without a gap or a repeat. The host must keep
+  turns (`resumableTurns` on `CodingAgentRpcServer`); one that cannot resume refuses, and `send`
+  throws the original break.
 - **Cursor resume.** A persisted log can be replayed from a cursor. A cursor whose next record was
   evicted from the retained window asks the caller to resync.
 - **Approvals and handoffs.** Pending approvals list as identifiers; decisions and handoff outcomes go
@@ -11469,10 +13080,57 @@ const events = createAgentEventStream(256)
 events.push(/* a versioned AgentEvent */)
 ```
 
+`isAgentEvent` refuses an event past the protocol's bounds: 256 KiB characters of `text`, `prompt`, or
+error message, and 64 KiB per string inside `input`, `output`, or `details`. A backend keeps its
+events inside them with `splitAgentText` (a long reply as consecutive events that join back),
+`boundAgentText` (one field, cut with a marker), and `boundAgentValue` (a display copy of a tool's
+input or output; the tool itself still gets the whole value). `agentEventProblem` says why an event
+was refused, naming the field and the limit but never its content.
+
+Three events carry what most coding agents report besides their reply: `reasoning.delta` (a piece
+of the model's reasoning, grouped by an optional `itemId`), `plan.updated` (the whole current plan,
+entries of `content`, `status`, and optional `priority`, each event replacing the last), and
+`context.usage` (`usedTokens` of the latest request, the model's `windowTokens` when known, and
+optional input, output, cached, and reasoning counts).
+
+Any other frame a backend has of its own travels as an extension event:
+`type` is `x-<vendor>.<name>` (lowercase, at most 64 characters), with an optional `turnId` and a
+`data` value inside the same payload bounds. Hosts that do not know the type pass it through; a host
+that does can register a check for it.
+
+```ts
+yield { version: 1, sessionId, seq, at: Date.now(), type: "x-codex.plan", turnId, data: { steps } }
+```
+
 Use `@nifrajs/pi` for the Pi backend or implement `AgentBackend` for another
 runtime. The protocol is intentionally small so CLI, desktop, mobile, and CI
 clients can share it without pulling in the Nifra application framework.
 
+## Conformance kit
+
+`@nifrajs/agent-protocol/conformance` drives an `AgentBackend` through what a host relies on and
+returns a report, so an adapter for another agent can prove itself in any test runner:
+
+```ts
+import { checkAgentBackend } from "@nifrajs/agent-protocol/conformance"
+
+const report = await checkAgentBackend({
+  backend: () => new MyBackend(),
+  cwd: process.cwd(),
+  prompt: "say hi",
+  slowPrompt: "wait until cancelled", // enables turn.busy and turn.cancel
+  approvalPrompt: "write a file", // enables the approval checks
+})
+expect(report.checks.filter((check) => check.status === "failed")).toEqual([])
+```
+
+Each scenario gets a fresh backend and session. The checks: a valid session snapshot; a turn whose
+events are valid, ordered, of one turn, and end with exactly one terminal event; `session.completed`
+for a plain turn and an idle snapshot after it; a second message refused while a turn runs, without
+ending it; a cancel that ends with `session.stopped` and leaves the session usable; approvals allowed
+and denied; `undefined` from `resolveApproval` for an approval it never asked for or whose turn was
+cancelled; and no turn for a closed session.
+
 ## Version 1 compatibility
 
 Version 1 is additive. Hosts advertise capabilities and clients use only the negotiated intersection;
@@ -11690,6 +13348,7 @@ How it holds the line:
 
 - **Post-decode body limits.** The body is decoded (base64 or UTF-8) and its real `byteLength` checked against `maxBodyBytes` (default 1,000,000 - match your app's setting if you changed it) *before* a `Request` is constructed. The event's own length claims are never trusted; over the limit answers a flat `413`.
 - **One header merge site.** Request headers come from the v2 `headers` map plus the separate `cookies` array in exactly one function; the array is canonical, so a `cookie` key smuggled into `headers` never reaches the app. Response `Set-Cookie` values travel in the result's `cookies` array, one entry each - never comma-joined.
+- **Body-less HEAD.** A `HEAD` answer keeps the GET route's status and headers but carries no body, on both handlers. A streaming body is cancelled rather than read, so its producer stops.
 - **Base64 honesty.** Response `isBase64Encoded` is decided by a strict UTF-8 decode of the actual bytes, never by content-type guessing. Binary round-trips exactly; text ships as text.
 - **Client IP.** `event.requestContext.http.sourceIp` feeds core's client-IP seam; `X-Forwarded-For` trust stays where it belongs, in the app's `clientIp` server option.
 - **Flat errors.** Uncaught failures collapse to the same `{"ok":false,"error":"internal_error"}` 500 as every other nifra runtime - the event is never echoed.
@@ -11846,7 +13505,12 @@ await cache.invalidateTag(`user:${id}`)
     **immediately** while a **background** refresh runs (deduped). Latency stays flat; data self-heals.
   - **Miss/expired**: awaits `loader`. Concurrent misses for the same key share **one** call (no stampede).
   - A throwing `loader` is **not** cached (and in the background path goes to `onError`, never rejects the caller).
-- **`set` / `get` / `has` / `delete`**, **`invalidateTag(tag)`**, **`clear()`**.
+  - **Store outage**: a store `get` that throws or rejects is a miss, so the loader answers; a `set` that
+    fails still returns the loaded value, and a `fence` that fails leaves that load uncached. Each
+    failure goes to `onStoreError(error, { op })`, which by default logs one line per operation per
+    minute without the key. The explicit `get`, `set`, `delete`, `invalidateTag` and `clear` still
+    reject, so a failed invalidation is never silent.
+- **`set` / `get` / `has` / `delete`**, **`invalidateTag(tag)`**, **`clear()`**. A `delete`, `invalidateTag`, `clear` or newer `set` also stops a `wrap` load or background refresh already running for that key or tag from storing its result, and the next `wrap` loads afresh. A `delete`, `invalidateTag` or `clear` runs after this cache's own async store writes it covers, so a store that applies requests out of order cannot land one after it.
 - TTL: `ttlMs` (→ stale) + optional `swrMs` (→ served-stale window) + optional `tags`.
 
 ## Stores
@@ -11860,6 +13524,14 @@ opt-in. For a cache shared across instances, implement `CacheStore`
 const cache = createCache({ store: new RedisCacheStore(redis) })
 ```
 
+A store several caches or processes share should also implement the optional `fence(key, tags)` and
+`setIfFence(key, entry, tags, token)`. A `wrap` load takes a fence before it runs and stores its result
+through `setIfFence`, which must refuse, in one atomic step, when a `set` or `delete` of the key, an
+`invalidateTag` of one of its tags, or a `clear` ran since that fence, from any cache. Without them, a
+load running in one process can store a value another process invalidated meanwhile. `MemoryCache`
+implements both, and `cacheStoreCertificationProfile({ fencing: true })` from
+`@nifrajs/testing/certification` checks a store's implementation.
+
 On **Cloudflare Workers** the in-memory cache is per-isolate and short-lived - back it with **CF KV** (or
 the Cache API) via a `CacheStore` for anything that should survive across requests/instances.
 
@@ -11867,7 +13539,8 @@ the Cache API) via a `CacheStore` for anything that should survive across reques
 
 `observer` receives one event per operation after it settles: `{ op, outcome, startedAt, durationMs,
 key, tag, tagCount, context }`. `outcome` is `hit`, `stale` or `miss` for reads, `ok` for writes and a
-finished background refresh (`op: "revalidate"`), `error` when the store or loader threw. An observer
+finished background refresh (`op: "revalidate"`), `error` when the store or loader threw. A `wrap`
+that loaded through a store outage reports `miss`. An observer
 that throws is swallowed; it never changes a result. Without an observer the cache reads no extra clock.
 
 `cache.for(c)` binds a request (or job) context, and every event carries it. That is how
@@ -11890,7 +13563,7 @@ whenever it is set.
 
 ## API
 
-- `createCache(options?)` → `Cache` - `{ store?, defaultTtlMs?, now?, onError?, observer?, beacon?, capabilities? }`.
+- `createCache(options?)` → `Cache` - `{ store?, defaultTtlMs?, now?, onError?, onStoreError?, observer?, beacon?, capabilities? }`.
 - `cache.wrap(key, loader, { ttlMs?, swrMs?, tags? })` · `get` · `has` · `set` · `delete` · `invalidateTag` · `clear`.
 - `cache.for(context)` → the same surface bound to a request or job context.
 - `MemoryCache({ maxEntries?, now? })` - the default store; implement `CacheStore` for your own.
@@ -11927,6 +13600,9 @@ nifra sdk     --lang <python|go> [--strict]
 nifra doctor  [--json] [--auto-fix]       Catch undeclared imports and duplicate Nifra/React installs.
 ```
 
+`nifra dev`, `build` and `start` take a flag's value as `--target vercel` or `--target=vercel`, and refuse
+a flag or argument they do not know instead of ignoring it.
+
 ## `nifra doctor` - dependency health
 
 Doctor diffs source imports against declared dependencies, then resolves identity-sensitive
@@ -11959,12 +13635,16 @@ the frontend asset `dist/manifest.json`.
 ## `nifra verify` - verification tiers
 
 `nifra check` is the fast project done-gate: TypeScript plus static contract and boundary diagnostics.
+It reads source without running it, with one exception: when the project has a `contracts.lock.json`,
+`nifra check` (with `--lints-only` too) imports `backend/app.ts`, running its top-level code, to compare
+the routes it serves against the lock.
 It is not a release claim. `nifra verify` runs the ordered local verification plan; its default mode
 is the feedback plan and reports which release gates it omits. CI and release automation should run
 `nifra verify --release` (or `bun run check:release`), which includes build, coverage, corpus,
 consumer, publish, and cross-runtime gates. Each gate runs a `package.json` script (`bun run lint`,
 `bun run check:docs`, ...); a gate whose script the project does not declare is reported as
-`undeclared` and does not fail the run. Run `nifra port --ci --target <target>` for an app's
+`undeclared` and does not fail the run. The nifra repository's own `bun run verify` and
+`bun run check:release` fail that gate instead, so a renamed script cannot drop it. Run `nifra port --ci --target <target>` for an app's
 resolved deployment target; CI never guesses a target when none is configured.
 
 ## `nifra check` - the drift gate (run as "done")
@@ -11975,7 +13655,8 @@ remember them. It does three things and exits non-zero if any fails:
 1. **Typecheck** (`tsc --noEmit`, using the project's own TypeScript) - the frontend↔backend contract is
    compiler-enforced. `client<typeof app>` derives request inputs **and** `res.data` from your routes, so
    a screen that expects the wrong shape is a type error. Running the typecheck is what turns that latent
-   guarantee into an enforced one.
+   guarantee into an enforced one. TypeScript sources with no `tsconfig.json` beside them fail this step,
+   as a missing `typescript` install does: nothing typechecked them. A JavaScript-only project skips it.
 2. **Typed-client lint** - flags any hand-rolled `fetch()` to your own API (a relative URL like
    `fetch("/users")`), which bypasses the typed client so the compiler can't see the drift. External
    absolute-URL fetches are not flagged.
@@ -12141,8 +13822,11 @@ const { ok, status, data, error } = await api.users({ id: "42" }).get()
   `api.files("report.json").get()`.
 - **Result, never exceptions.** Every call resolves to `{ ok, status, data, error }`,
   so the failure path is in the types. Bodies are positional (`api.users.post({ name })`);
-  pass `{ query, headers, signal }` as call options. A call that gets no HTTP answer has
-  `status: 0` and the code `network_error`, `timeout`, `response_too_large` or `invalid_path`.
+  pass `{ query, headers, signal }` as call options. A DELETE route with a body schema takes
+  its body as an option: `api.items.delete({ body: { ids } })`. A call that gets no HTTP answer it
+  can read has `status: 0` and the code `network_error`, `timeout`, `response_too_large`,
+  `malformed_response` (a body its content type does not decode, like a proxy's HTML error page
+  labelled JSON) or `invalid_path`.
 - **A param value is never a path step.** `.` and `..` are resolved by URL parsing in every
   encoding, so `api.users({ id: ".." }).delete()` sends nothing and returns `invalid_path`
   instead of reaching another route. `.subscribe()` reports it through `onError`; `.ws()` throws.
@@ -12198,6 +13882,22 @@ loopback debugger, set `exposeErrorStacks: true` (or pass
 `--expose-error-stacks` to `nifra-agent --rpc`) to include bounded exception
 stacks. This option is rejected for remote binding.
 
+Each `turn.send` SSE frame carries `id: <seq>`. By default a client that disconnects cancels its
+turn. With `resumableTurns: true` the turn keeps running: a client that comes back calls
+`turn.attach` with `{ afterSeq }` (or a `Last-Event-ID` header) to read the frames it missed and
+follow the rest. A cursor older than the held frames (`replayEvents`, default 1024; `replayBytes`,
+default 8 MiB) answers `409 resync_required`, so read `session.events` instead; a second
+`turn.send` while one runs answers `409 turn_running`; and a turn no client has followed for
+`detachedTimeoutMs` (default 2 minutes) is cancelled.
+
+An approval, or a coding tool's question to the person, is denied once it has waited 5 minutes.
+Pass `approvals: { timeoutMs }` to `CodingAgentHost` or `CodingAgentRpcServer` for up to 24 h, or
+`timeoutMs: "never"` to keep it until it is answered, cancelled, its turn ends, or the session
+closes; `maxPending` (default 32) still bounds how many can wait. `NifraBackend` has its own
+`approvalTimeoutMs`, taking the same values, and the host denies in the backend whatever its broker
+denies, so the shorter of the two applies. A never-expiring approval reports `expiresAt` as
+`APPROVAL_NEVER_EXPIRES_AT`, which survives JSON and stays later than any `Date.now()`.
+
 `nifra-agent` loads `.nifra/extensions/**` from `--cwd` only when started with
 `--extensions`. An extension module's top-level code runs as soon as it is
 imported, before its declared `capabilities` are checked, so pass the flag only
@@ -12211,7 +13911,10 @@ loading code you do not trust.
 an injected model implementation and bounded tools without importing a provider
 SDK. The conversation it sends the model is capped by `maxHistoryChars` (default
 1 MiB): past it, whole earlier turns are dropped, oldest first, and the current
-turn is always sent in full. `ReplayBackend` and `readReplayEvents` provide deterministic protocol
+turn is always sent in full. `maxMessageChars` (default 64 KiB) caps the message `send` accepts and
+`maxReplyChars` (default 1 MiB) the model's reply; a reply longer than one event's text arrives as
+consecutive `assistant.message` events, and a tool's event shows a bounded copy of its input while
+the tool runs with all of it. `ReplayBackend` and `readReplayEvents` provide deterministic protocol
 replays for CI and Workbench regression tests.
 
 ## At-least-once run dispatch
@@ -12233,7 +13936,8 @@ Legacy `FileSessionStore` files remain supported for explicit local compatibilit
 `nifra-agent --migrate-session <id> --migrate-from <legacy-dir> --migrate-to <evidence-dir>` to
 create a separately validated, evidence-only target. The source is left untouched and the command
 does not switch an active configuration pointer: after reviewing its report, point the host at the
-new directory yourself. To roll back, point it at the legacy directory again and remove the new
+new directory yourself. `FileSessionStore` reads the migrated rows as content-free entries whose
+type is the stable event code, and new appends continue the sequence. To roll back, point it at the legacy directory again and remove the new
 target; a failed or interrupted migration leaves the active choice unchanged.
 
 For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
@@ -12413,7 +14117,9 @@ route. Split groups before the compiler reports `TS2589`, rather than weakening
   client's `transport` option with the same registry. `@nifrajs/core/transport-codec` negotiates
   bounded HTTP representations and supplies the same frame/loader adapters for WebSockets and
   deferred data. Import `richWireCodec()` from `@nifrajs/core/transport-codec-rich`; the separate
-  subpath keeps rich-wire code out of plain JSON bundles.
+  subpath keeps rich-wire code out of plain JSON bundles. The plugin decodes a codec body before
+  routing, so a route's `bodyLimit` and its authentication run after the decode; its own `maxBytes`
+  is the bound on that work.
 - **Typed data seam (opt in).** `@nifrajs/core/data` defines token-only operation contracts,
   `db.read`/`db.write` capability names, an opaque request-local `RlsScope`, typed adapter requests,
   drift snapshots, and `createDataPort(contract, adapter, { beacon: useCapability })`, which emits the
@@ -12451,7 +14157,9 @@ contract-first registry.
 
 `response` and `errors` are typed by default but are not runtime enforcement by themselves. Install
 `responseContract("enforce")` before the routes it should cover to validate JSON/status payloads and
-prevent extra fields from reaching the wire. `warn` preserves the original payload during migration.
+prevent extra fields from reaching the wire. That covers a `status(...)` or `c.json(...)` reply a
+handler returns or throws, a hook returns, or `onError` answers with. `warn` preserves the original
+payload during migration.
 Raw `Response`, streams, redirects, and `mountFetch` remain explicit transport escape hatches and
 must be governed by assurance/static review.
 
@@ -12498,8 +14206,11 @@ cron.stop()            // graceful - in-flight handlers finish
 
 Macros: `@hourly` `@daily` (`@midnight`) `@weekly` `@monthly` `@yearly` (`@annually`).
 
+Day-of-week runs 0-6 from Sunday, and 7 is Sunday too.
+
 Day-of-month + day-of-week follow the **standard OR rule**: when both are restricted, a match on
-either fires the job.
+either fires the job. A field that starts with `*` is not restricted, a step like `*/2` included,
+so `0 0 */2 * 1` fires on an odd day that is also a Monday, as in Vixie cron.
 
 ## Guarantees
 
@@ -12559,6 +14270,7 @@ a Bun-`listen()`-style graceful `stop()` and opt-in signals.
 
 ```ts
 await serve(app, { port: 3000, signals: true }) // SIGTERM/SIGINT → graceful stop()
+await serve(app, { port: 3000, signals: { drainMs: 8_000 } }) // the same, with an 8 s drain window
 ```
 
 ## What you get for free
@@ -12568,6 +14280,14 @@ cap live inside `app.fetch`, so they apply through this adapter automatically.
 
 Works with any `{ fetch(req): Promise<Response> }` handler, not just nifra. ESM/TS. MIT.
 
+## WebSocket message size
+
+`app.ws()` routes upgrade through `Deno.upgradeWebSocket`, which takes no size limit: Deno receives
+each inbound message whole (up to its own limit, 64 MiB on Deno 2.9) before the app sees it.
+`server({ wsMaxPayloadBytes })` then closes the socket with `1009` and keeps the message from your
+handler, but it cannot bound the memory Deno spent receiving it. Where that matters, cap message
+size in a proxy in front of the app. On Bun and Node the cap is enforced while the message arrives.
+
 ## For AI agents
 
 Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
@@ -12594,6 +14314,13 @@ The plugin is enabled by default only when `NODE_ENV=development`. It records a
 and serves the overlay stream at `/_nifra/devtools`; remote hosts and cross-origin access stay denied
 unless explicitly allowed. Leave it unregistered in production for zero request-path overhead.
 
+Each SSE connection also has a finite pending-byte budget (`maxPendingBytes`, default 64 KiB),
+including keep-alive frames. A slow reader that fills that budget is closed and releases its
+connection slot. Already queued frames drain before EOF; the overflow frame is dropped. Browser
+`EventSource` reconnects automatically. Initial delivery includes only the newest history suffix
+that fits the byte budget. This is a recent trace view, so reconnects can have event-id gaps when
+older events no longer fit the history or connection budget; it does not guarantee lossless replay.
+
 ## For AI agents
 
 Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
@@ -12780,7 +14507,11 @@ pass the request's bindings: `defineEnv(shape, { source: env })`.
 ## Secret safety
 
 Error messages name the offending variable and the reason - **never its value** (it may be a
-secret). `defineEnv` returns a frozen object, so a validated config can't be mutated downstream.
+secret). A BYO validator such as valibot or zod may quote the value in its message, escaped or
+cut short, so when it refuses a set value `defineEnv` reports the variable as invalid without the
+validator's message. For an unset variable the message is shown, since there is no value to quote.
+Use the `env.*` helpers when you want the reason as well. `defineEnv` returns a frozen object, so a
+validated config can't be mutated downstream.
 
 ## For AI agents
 
@@ -12875,6 +14606,15 @@ Resolvers read it as their third argument.
 
 Subscriptions run over the same route via `graphql-transport-ws`. Bring a subscription source - the bundled in-memory `createPubSub` is the reference implementation; swap in a durable bus (Redis, a Durable Object, NATS) that exposes the same `{ publish, subscribe }` shape for multi-instance deploys.
 
+Each reference subscriber queues at most 1024 events by default. If publication outruns consumption,
+the overloaded iterator detaches, clears its queued values, and its next pull rejects with
+`GraphqlPubSubOverflowError` (`code: "graphql_pubsub_overflow"`). Configure
+`createPubSub({ maxQueuedEvents: 256, overflow: "error" })` to change the finite limit. Explicit
+`"drop-oldest"` and `"drop-newest"` policies support consumers that accept missing events. Returning or
+throwing into an iterator clears its queue and terminates delivery. This is an event-count bound;
+publishers remain responsible for payload sizes. Synchronous `publish` does not provide producer
+backpressure or cross-instance delivery.
+
 ```ts
 import { server } from "@nifrajs/core"
 import { websocket } from "@nifrajs/core/ws"
@@ -12897,6 +14637,8 @@ pubsub.publish("count", 1)
 
 The route must negotiate the `graphql-transport-ws` subprotocol at the WebSocket layer for a browser `graphql-ws` client to connect.
 
+With `subscriptions: true`, a socket is admitted only when `authorize` accepts its upgrade request, and operations over it get the same query limits as HTTP. A browser cannot set headers on a WebSocket upgrade, so cookie auth carries over and bearer-header auth does not; for a token sent in `connection_init`, pass WS options with `onConnect` instead. When `authorize` is set, WS options must have their own `authorize` or `onConnect` (`onConnect: () => true` admits every socket on purpose), or `mountGraphql` throws.
+
 ## Options
 
 | Option | Default | Purpose |
@@ -12909,12 +14651,13 @@ The route must negotiate the `graphql-transport-ws` subprotocol at the WebSocket
 | `allowedOrigins` | reflect `*` | CORS origin allowlist. |
 | `authorize` | - | Per-request guard; return `false` for 401. |
 | `enableGet` | `true` | Serve `GET /graphql` (queries only). |
-| `subscriptions` | `false` | `true` (reuse schema/context) or explicit WS options. |
+| `introspection` | `true` | `false` refuses `__schema` and `__type` as a validation error (400 over HTTP, an `error` frame over WS); `__typename` still resolves. Subscriptions inherit it unless their own options set it. |
+| `subscriptions` | `false` | `true` (reuse schema, context, `authorize` and limits) or explicit WS options. |
 | `legacyJsonResponse` | `false` | Old always-200 `application/json` shape. |
 
 ## Responses
 
-By default responses use the `application/graphql-response+json` media type with spec status codes: `200` for an executed result (including field errors in `errors`), `400` for a parse or validation failure, `401` for a rejected `authorize`, `405` for a mutation attempted over GET. Set `legacyJsonResponse: true` for the older always-`200` `application/json` behavior some clients expect.
+By default responses use the `application/graphql-response+json` media type with spec status codes: `200` for an executed result (including field errors in `errors`), `400` for a parse or validation failure, `401` for a rejected `authorize`, `405` for a mutation attempted over GET, `415` for a POST whose body is not `application/json` (or another `+json` type). The last keeps a cross-site HTML form, which can send only urlencoded, multipart or plain-text bodies, from posting a mutation with the visitor's cookies. Set `legacyJsonResponse: true` for the older always-`200` `application/json` behavior some clients expect.
 
 ## License
 
@@ -13110,7 +14853,7 @@ framework runtime. The client companion to `@nifrajs/web-vanilla`: the server re
 (zero framework JS); islands attach behavior to it in place. No VDOM, no hydration re-render -
 the markup the server sent IS the initial state.
 
-The full island bundle is just under 2 KB gzipped, and a size test keeps it there. Use
+The full island bundle is about 2 KB gzipped (2,080 B at most), and a size test keeps it there. Use
 it for small interactive widgets where a full framework runtime would be overkill.
 
 ## Server side (any adapter - `@nifrajs/web-vanilla` shown)
@@ -13176,7 +14919,10 @@ bind it, for example to show or hide the nested island.
 
 `signal(initial)` / `computed(fn)` / `effect(fn) → dispose` / `batch(fn)` - auto-tracking with
 per-run re-tracking, `Object.is` skips, synchronous updates; `batch` coalesces multiple writes
-into one flush. Island-scale by design: if a widget outgrows this (lists, ownership trees,
+into one flush. A `computed` runs on first read and stops by itself once nothing reads it: the
+next change to its inputs stops it instead of recomputing, and reading it again computes it afresh.
+Every effect an island's setup creates stops when `mountIslands`' disposer unmounts it; one created
+outside an island runs until its disposer is called. Island-scale by design: if a widget outgrows this (lists, ownership trees,
 async orchestration), that's the signal to use the Solid adapter for that page - both tiers are
 first-class.
 
@@ -13225,6 +14971,8 @@ fails at the call site, not three retries later.
 
 Per-job: `retries: number` (attempts) or `{ attempts, backoff }`. A handler that throws is routed to
 `onError`, then retried with the backoff delay; after the last attempt it's **dead-lettered**, not lost.
+An attempt count (and `createQueue({ defaultAttempts })`) must be a whole number; `NaN`, `Infinity` or
+a fraction throws a `RangeError`, and a count below 1 means one attempt.
 
 ```ts
 import { exponentialBackoff, fixedBackoff } from "@nifrajs/jobs"
@@ -13246,6 +14994,23 @@ const q = createQueue({ store: new RedisJobStore(redis) })
 Leasing is at-least-once: a leased job is hidden for `leaseMs`; a worker that dies mid-job releases it
 back automatically. Make handlers **idempotent**.
 
+While a handler runs, the worker renews its lease about three times per `leaseMs` through the store's
+optional `renew(id, until, lease)`, so a job that runs longer than `leaseMs` is not handed to another
+worker. A store without `renew` cannot do that: such a job may then run twice, on two workers, though
+never twice on the same queue. Each `lease` may also return a `lease` token on the job; the queue
+passes it back to `complete` / `retry` / `deadLetter` / `renew`, so a store can ignore a worker whose
+lease another worker has since taken. `MemoryJobStore` does both.
+
+A job's `timeoutMs` bounds each attempt: one still running after that many ms fails with a
+`JobTimeoutError` (then retries or dead-letters), frees its worker slot, and aborts `ctx.signal`. Pass the
+signal on to `fetch` or your driver, since a handler that ignores it keeps running unobserved.
+`timeoutMs` must be below the worker's `leaseMs`: `start()` (and a later `define()`) throws a
+`RangeError` otherwise.
+
+```ts
+q.define("render", { timeoutMs: 10_000, async handler(id, ctx) { await fetch(url(id), { signal: ctx.signal }) } })
+```
+
 `enqueue` may pass an optional `traceparent` (the producer's W3C trace context); a store should persist
 it and hand it back on every `lease`. A store that drops it still runs every job - a traced run only
 loses its link to the producer. `jobStoreCertificationProfile({ traceparent: true })` from
@@ -13309,10 +15074,10 @@ the run stays in the producer's trace.
 ## API
 
 - `createQueue(options?)` → `Queue` - `{ store?, onError?, now?, defaultAttempts?, backoff?, beacon?, capabilities?, instrument? }`.
-- `queue.define(name, { handler, input?, retries? })` → typed `JobHandle` with `.enqueue(payload, { delayMs? | runAt?, traceparent? })` and `.for(context)`.
+- `queue.define(name, { handler, input?, retries?, timeoutMs? })` → typed `JobHandle` with `.enqueue(payload, { delayMs? | runAt?, traceparent? })` and `.for(context)`.
 - `queue.enqueue(name, payload, options?)` - enqueue by name.
-- `queue.start({ concurrency?, pollIntervalMs?, leaseMs? })` → `Worker` (`.stop()` drains gracefully).
-- `queue.process()` - run one poll round (for Workers / custom drivers). `queue.drain()` - process until empty.
+- `queue.start({ concurrency?, pollIntervalMs?, leaseMs? })` → `Worker` (`.stop()` drains gracefully). Each poll fills the slots free at that moment, so one slow job holds only its own slot.
+- `queue.process()` - run one poll round (for Workers / custom drivers). `queue.drain()` - process until nothing is due or in flight.
 - `queue.counts()` → `{ pending, active, dead }`. `queue.store` - the underlying store.
 - Stores: `MemoryJobStore`. Backoff: `exponentialBackoff`, `fixedBackoff`, `noBackoff`.
 
@@ -13477,8 +15242,8 @@ Each layer refuses on its own, in this order:
 
 `explainPostgres` returns the plan (with `analyze`, executed inside the same transaction),
 `readPostgresSchema` reads tables, columns, keys and indexes from `pg_catalog`, and `postgresRoleSql`
-writes the SQL for a read-only role (`pg_read_all_data` on 14+, or `GRANT SELECT` per schema with a
-`REVOKE` for each excluded table and its partitions) without running it.
+writes the SQL for a read-only role (`GRANT SELECT` on each allowed schema, with a `REVOKE` for each
+excluded table and its partitions) without running it.
 
 The live tests run against a throwaway server: set `NIFRA_TEST_POSTGRES_URL` to its superuser URL.
 
@@ -13533,6 +15298,9 @@ const app = server()
 - **`basicAuth(options)`** - Basic Auth plugin with constant-time static credential comparison or
   a custom verifier.
 - **`bearer(options)` / `apiKey(options)`** - token auth plugins with typed principals.
+- Required `basicAuth`, `bearer`, `apiKey` and `jwt` refuse in the core `authenticate()` stage:
+  before the body is read or validated and before any `derive` or `beforeHandle`. A rate limiter
+  that must count refused requests belongs in `onRequest`, where `rateLimit()` runs.
 - **`csrf({ secret })`** - signed double-submit CSRF protection plus Origin/Referer checking. The
   token travels in the `x-csrf-token` header; set `field: "_csrf"` to also accept it from a plain
   HTML form's hidden input (urlencoded or multipart, bodies up to `fieldMaxBytes`, default 64 KiB).
@@ -13636,9 +15404,10 @@ The mock server matches reflected routes and synthesizes values from supported J
 Unsupported or unsatisfiable schemas fail explicitly instead of returning known-invalid data. Use a
 fixed seed when responses must be replayable across local development and CI.
 
-Routes whose response validator exposes no JSON Schema (zod, valibot, arktype) mock as `{}` by default.
-Pass `reflectJsonSchema` to derive a schema from such a validator so those routes mock real data; for zod,
-use the bridge shipped as `@nifrajs/testing/zod`:
+A validator that implements Standard JSON Schema (`~standard.jsonSchema`, zod 4.2+ among them) mocks
+real data with no wiring, and an older zod 4 is converted with `z.toJSONSchema`. Routes whose response
+validator exposes neither mock as `{}` by default. Pass `reflectJsonSchema` to derive a schema from such
+a validator; for zod, the bridge ships as `@nifrajs/testing/zod`:
 
 ```ts
 import { zodJsonSchema } from "@nifrajs/testing/zod"
@@ -13709,10 +15478,12 @@ The optional `static` root is served before `app.fetch` for GET and HEAD request
 public asset directory and must contain nothing private: no secrets, source maps, build
 metadata, or user uploads. The directory and its ancestor path must be read-only and owned by
 the service (or otherwise protected from untrusted local writers). Nifra resolves and confines
-the file before opening it and refuses symlinked final files, but Node does not expose a native
-per-component `openat` primitive; a process that can mutate the tree concurrently can still
-create a local TOCTOU race. Mutable or attacker-writable static trees are therefore outside the
-adapter's guarantee. Store user-controlled files outside the static root and serve them through
+the file before opening it, and refuses it when its final file or any directory on its path became
+a symlink in the meantime: on macOS the open itself refuses such a path, and on Linux the opened
+descriptor's path is checked. On Windows and other platforms no file API can open without following a
+middle link, so a process that swaps a directory concurrently can still win a local TOCTOU race;
+the check there only makes it need repeated swaps. Mutable or attacker-writable static trees are
+therefore outside the adapter's guarantee on those platforms. Store user-controlled files outside the static root and serve them through
 an application or object-storage path with its own validation policy.
 
 Every file carries a strong `ETag` (from mtime and size), `Last-Modified`, and
@@ -13730,6 +15501,13 @@ process signals should be a deliberate choice):
 await serve(app, { port: 3000, signals: true })
 ```
 
+In-flight requests get 10 s to finish before the stop forces them closed. Set the window to fit
+the platform's kill grace period:
+
+```ts
+await serve(app, { port: 3000, signals: { drainMs: 8_000 } })
+```
+
 ## What you get for free
 
 The request timeout (`server({ requestTimeoutMs })` → `503 request_timeout`) and body-size
@@ -13737,6 +15515,10 @@ cap live **inside `app.fetch`**, not Bun's `listen()` - so they apply through th
 with no extra wiring. Slow-client / slow-loris protection is Node's built-in
 `requestTimeout` (300s) and `headersTimeout` (60s) defaults.
 
+A hook that throws past `app.fetch`, or a response Node refuses to write (a header value carrying
+CR/LF, say), answers `500` and is logged through the app's own `logger`, as Bun's `listen()` logs it. The `req` a hook sees is a lazy stand-in for Node's request: copy it
+with `req.clone()`, not `new Request(req)`, which Node's `Request` constructor refuses.
+
 Works with any `{ fetch(req): Promise<Response> }` handler, not just nifra. ESM-only. MIT.
 
 ## For AI agents
@@ -13773,7 +15555,9 @@ const app = server()
   the inbound span as the parent. No inbound header → starts a fresh trace.
 - **Opens a span** with HTTP semantic-convention attributes (`http.request.method`, `url.path`,
   `http.response.status_code`, optional `service.name`), ended on response with duration + status
-  (`error` for 5xx, `ok` otherwise).
+  (`error` for 5xx, `ok` otherwise). A request that matched a route reports the route template as
+  `url.path`, so an id or a token in the path stays out of the trace backend; `rawUrlPath: true`
+  reports the raw path instead.
 - **Exposes `c.trace`** (`{ traceId, spanId, parentSpanId?, sampled, traceparent }`) - spread
   `traceHeaders(c.trace)` into any downstream `fetch`/`ctx.api` call to continue the trace.
 - **Exposes `c.causality`** - a bounded, payload-free request node that survives durable command,
@@ -14026,7 +15810,7 @@ const upstream = createProxy({ upstream: "http://127.0.0.1:8081" })
 const app = server().mountFetch("/api", upstream, { stripPrefix: true })
 ```
 
-The upstream is a **bare origin** fixed at construction - the forwarded URL is built by mutating a clone of that origin, never by resolving request-derived strings, so no request input can change which host is dialed. Hop-by-hop and `Connection`-nominated headers are stripped in both directions. Caller IP/protocol metadata is dropped unless `forwardClientIp: true`; the inbound Host is never trusted, and `X-Forwarded-Host` is emitted only from a fixed `forwardedHost`. Upstream redirects are never followed, and TLS verification has no off switch. Unreachable upstreams answer a flat `502`; the deadline (`timeoutMs`, default 30s) answers `504`.
+The upstream is a **bare origin** fixed at construction - the forwarded URL is built by mutating a clone of that origin, never by resolving request-derived strings, so no request input can change which host is dialed. Hop-by-hop and `Connection`-nominated headers are stripped in both directions. Every inbound `Forwarded` and `X-Forwarded-*` header is dropped; caller IP/protocol metadata is re-added only under `forwardClientIp: true`, and any other forwarding header only as a fixed `headers` entry. The inbound Host is never trusted, and `X-Forwarded-Host` is emitted only from a fixed `forwardedHost`. Upstream redirects are never followed, and TLS verification has no off switch. Unreachable upstreams answer a flat `502`; the deadline (`timeoutMs`, default 30s) answers `504`.
 
 ## Docs
 
@@ -14296,7 +16080,7 @@ const keys = await storage.list({ prefix: "avatars/" })
 | Adapter | Use | Notes |
 |---|---|---|
 | `MemoryStorage` | dev / tests | not durable, not shared across instances |
-| `FileStorage(root)` | a long-running server (Bun/Node/Deno) | persists content type + custom metadata in an adjacent sidecar tree; legacy objects still infer MIME from extension |
+| `FileStorage(root)` | a long-running server (Bun/Node/Deno) | writes each object whole (staged in `<root>.nifra-state`, then renamed into place); persists content type + custom metadata in a sidecar tree there; reads older `<root>.nifra-metadata` sidecars; objects with none infer MIME from extension |
 | `R2Storage(env.BUCKET)` | the edge (Cloudflare R2) | round-trips `contentType` + metadata; binding typed structurally (no `@cloudflare/workers-types`) |
 
 Implement `StorageAdapter` (`put` / `get` / `delete` / `exists` / `list`) for **S3 / GCS / anything else** -
@@ -14394,6 +16178,16 @@ The validator still decides which generated mutations are truly invalid; the sup
 weaken validation. A missing/invalid witness is a coverage gap, not a silent pass. Set
 `requireCoverage: false` only when gaps are intentionally advisory.
 
+Declared `params` and `headers` get witnesses too, validated before any case runs, so a body or query
+case is rejected by the input it mutates rather than by a placeholder param or a missing header. A `t`
+schema synthesizes them, the witness's `params` and `headers` override, and a route param the schema
+leaves out keeps a placeholder its pattern accepts. The harness never invents credentials:
+`authorization`, `proxy-authorization`, `cookie`, `x-api-key`, and names ending in `-key` or containing
+`token`, `secret` or `signature` come from the witness (and `prepareRequest`) only, and are never
+mutated; a schema that requires one the witness lacks is a `NO_WITNESS` gap that names it. Cookies are
+never synthesized either: a route with a `cookies` schema needs `headers.cookie` in its witness. A
+params or header field typed as bare text accepts any text, so it is not a `NO_REJECTED_MUTATION` gap.
+
 To exercise adapter parity, pass runtime fetch targets. The reflected `app` remains the one source of
 the contract:
 
@@ -14415,10 +16209,13 @@ laboratory at production.
 ### Opaque validators (zod / valibot / arktype)
 
 A `t` schema exposes JSON Schema, so witnesses and constraint-driven mutations are synthesized
-automatically. A Standard Schema validator that carries no JSON Schema (zod, valibot, arktype) validates
-requests fine, but the laboratory can't inspect it - those routes report `NO_WITNESS` and get only
-type-confusion mutations. Pass `reflectJsonSchema` to convert such a validator; for zod, use the shipped
-bridge:
+automatically. So does any validator that implements Standard JSON Schema (`~standard.jsonSchema`,
+zod 4.2+ among them): the laboratory calls the schema's own converter, so nothing is resolved from disk
+and a monorepo run from its root reads an app's zod schemas too. An older zod 4 is converted with
+`z.toJSONSchema`, resolved from the project directory first, then from this package. A validator with
+neither validates requests fine, but the laboratory can't inspect it - those routes report `NO_WITNESS`
+and get only type-confusion mutations, and the gap says why when a conversion was tried and failed.
+Pass `reflectJsonSchema` to convert any other validator, or to choose the zod bridge explicitly:
 
 ```ts
 import { zodJsonSchema } from "@nifrajs/testing/zod"
@@ -14654,10 +16451,29 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
+Optional server components are implemented for React, Vue, Svelte and Solid in the post-4.0
+feature branch. React uses native RSC/Flight; the other adapters use native islands in validated
+server ranges. Definitions require closed input/public-props schemas and authorization. Refresh
+executes the actual owner GET, preserving admission, read capabilities, budgets and cancellation;
+output is private/no-store. Mutate through validated server functions or actions.
+
+Use the `/server-components`, `/server-components/client`, `/server-components/islands` and
+`/server-components/build` exports with an explicit `componentPipeline` named config export.
+See [the server-components guide](https://nifra.dev/docs/server-components) and the four runnable
+repository examples for complete entries, native outlets, exact compiler pins and rollback.
+
 Framework-agnostic SSR core for nifra - the render seam + HTML document orchestration.
 
 Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
 
+## Guarding pages
+
+A `_layout.backend.ts` loader is data, not a guard: a client navigation can skip it while the browser
+keeps the layout's data, and an action below it runs without it. Refuse access in that file's
+`middleware`, or export `gate = true` so its loader runs on every request and before every action,
+ahead of the page loader. In development, nifra warns when a layout loader without `gate` refuses a
+request, and `nifra check` reports one whose refusal it can read (NF-C042). See [Layout loaders on navigation](https://nifra.dev/docs/data).
+
 ## Install
 
 ```sh
@@ -14885,7 +16701,8 @@ const registration = await registerWebMcpTools([addItem])
 
 The returned WebMCP `execute` function runs Nifra's existing input validation, capability, approval,
 idempotency, budget, cancellation, output validation, and evidence path. By default it returns a bounded
-receipt envelope so an agent can verify whether the operation committed. The normal human UI remains the
+receipt envelope so an agent can verify whether the operation committed. A `signal` the host passes as
+`execute`'s second argument reaches the executor as `ctx.signal`. The normal human UI remains the
 source of page rendering and works when WebMCP is absent.
 
 Receipt output is retained only while its JSON encoding stays within the bounded `maxReceiptBytes`
@@ -15094,6 +16911,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `A2AAgentCard`, `A2AAgentSkill`, `A2ACardInfo`, `A2AMountableApp`, `A2ARouteContext`, `A2ATaskState`, `A2A_ERROR_CODES`, `A2A_PROTOCOL_VERSION`, `AGENT_CARD_WELL_KNOWN_PATH`, `MountA2AOptions`, `agentCard`, `mountA2A`
 
+## @nifrajs/acp
+
+`AcpBackend`, `AcpBackendOptions`, `AcpClientInfo`
+
 ## @nifrajs/ag-ui
 
 `AgUIMountableApp`, `AgUIRouteContext`, `AgUIRunContext`, `AgUIRunUsage`, `MountAgUIOptions`, `mountAgUI`
@@ -15104,11 +16925,11 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/agent-app
 
-`AGENT_APP_FEATURES`, `AgentAppClient`, `AgentAppClientOptions`, `AgentAppError`, `AgentEventView`, `AgentTransport`, `AgentTransportError`, `AgentTransportRequest`, `ApprovalRequiredView`, `ApprovalResolvedView`, `AssistantChunkView`, `AuthProvider`, `BoundaryDecisionResult`, `BoundaryItemView`, `BoundaryStateView`, `CommandOutcome`, `CreateSessionInput`, `EvalComparisonView`, `EvidenceTimelineView`, `ExtensionReloadedView`, `FaultInjectionView`, `HandoffView`, `HttpAgentTransport`, `HttpAgentTransportOptions`, `MemoryCompactedView`, `OrderedEventBuffer`, `PendingApprovalView`, `RegistryCapabilityView`, `RepairRequiredView`, `ReplayEntryView`, `ReplayResult`, `ResolveHandoffInput`, `ResumeInput`, `ReviewView`, `ReviewViewCheck`, `ReviewViewEvidence`, `ReviewViewFinding`, `ReviewViewStatus`, `RunStudioNodeState`, `RunStudioNodeView`, `RunStudioView`, `RunView`, `SessionFailedView`, `SessionLifecycleView`, `SessionStoppedView`, `SessionView`, `ToolCompletedView`, `ToolDeltaView`, `ToolStartedView`, `TurnStartedView`, `VerificationCompletedView`, `boundaryCommands`, `boundaryIsStale`, `parseEventStream`, `toEvalComparisonView`, `toEventView`, `toEvidenceTimelineView`, `toFaultInjectionViews`, `toHandoffView`, `toRegistryCapabilityView`, `toReviewView`, `toRunStudioView`, `toRunView`, `toSessionView`, `virtualizeEvidenceRows`
+`AGENT_APP_FEATURES`, `AgentAppClient`, `AgentAppClientOptions`, `AgentAppError`, `AgentEventView`, `AgentTransport`, `AgentTransportError`, `AgentTransportRequest`, `ApprovalRequiredView`, `ApprovalResolvedView`, `AssistantChunkView`, `AuthProvider`, `BoundaryDecisionResult`, `BoundaryItemView`, `BoundaryStateView`, `CommandOutcome`, `ContextUsageView`, `CreateSessionInput`, `EvalComparisonView`, `EvidenceTimelineView`, `ExtensionEventView`, `ExtensionReloadedView`, `FaultInjectionView`, `HandoffView`, `HttpAgentTransport`, `HttpAgentTransportOptions`, `MemoryCompactedView`, `OrderedEventBuffer`, `PendingApprovalView`, `PlanUpdatedView`, `ReasoningDeltaView`, `RegistryCapabilityView`, `RepairRequiredView`, `ReplayEntryView`, `ReplayResult`, `ResolveHandoffInput`, `ResumeInput`, `ReviewView`, `ReviewViewCheck`, `ReviewViewEvidence`, `ReviewViewFinding`, `ReviewViewStatus`, `RunStudioNodeState`, `RunStudioNodeView`, `RunStudioView`, `RunView`, `SessionFailedView`, `SessionLifecycleView`, `SessionStoppedView`, `SessionView`, `ToolCompletedView`, `ToolDeltaView`, `ToolStartedView`, `TurnStartedView`, `VerificationCompletedView`, `boundaryCommands`, `boundaryIsStale`, `parseEventStream`, `toEvalComparisonView`, `toEventView`, `toEvidenceTimelineView`, `toFaultInjectionViews`, `toHandoffView`, `toRegistryCapabilityView`, `toReviewView`, `toRunStudioView`, `toRunView`, `toSessionView`, `virtualizeEvidenceRows`
 
 ## @nifrajs/agent-protocol
 
-`AGENT_PROTOCOL_VERSION`, `AgentApprovalRequiredEvent`, `AgentApprovalResolvedEvent`, `AgentAssistantDeltaEvent`, `AgentAssistantMessageEvent`, `AgentBackend`, `AgentBackendInfo`, `AgentError`, `AgentEvent`, `AgentEventPayload`, `AgentEventSink`, `AgentEventStream`, `AgentEventType`, `AgentExtensionReloadedEvent`, `AgentMemoryCompactedEvent`, `AgentRepairRequiredEvent`, `AgentRepairTask`, `AgentSessionCheckpoint`, `AgentSessionCompletedEvent`, `AgentSessionEventBase`, `AgentSessionFailedEvent`, `AgentSessionSnapshot`, `AgentSessionStartedEvent`, `AgentSessionStatus`, `AgentSessionStoppedEvent`, `AgentSessionUpdatedEvent`, `AgentToolCompletedEvent`, `AgentToolDeltaEvent`, `AgentToolStartedEvent`, `AgentTurnStartedEvent`, `AgentVerificationCompletedEvent`, `CreateSessionInput`, `ForkSessionInput`, `ForkSessionResult`, `ReloadResult`, `SendMessageInput`, `agentError`, `createAgentEventStream`, `isAgentEvent`
+`AGENT_MAX_EVENT_TEXT`, `AGENT_MAX_PAYLOAD_STRING`, `AGENT_PROTOCOL_VERSION`, `AgentApprovalRequiredEvent`, `AgentApprovalResolvedEvent`, `AgentAssistantDeltaEvent`, `AgentAssistantMessageEvent`, `AgentBackend`, `AgentBackendInfo`, `AgentContextUsageEvent`, `AgentError`, `AgentEvent`, `AgentEventPayload`, `AgentEventSink`, `AgentEventStream`, `AgentEventType`, `AgentExtensionEvent`, `AgentExtensionEventType`, `AgentExtensionReloadedEvent`, `AgentMemoryCompactedEvent`, `AgentPlanEntry`, `AgentPlanEntryStatus`, `AgentPlanUpdatedEvent`, `AgentReasoningDeltaEvent`, `AgentRepairRequiredEvent`, `AgentRepairTask`, `AgentSessionCheckpoint`, `AgentSessionCompletedEvent`, `AgentSessionEventBase`, `AgentSessionFailedEvent`, `AgentSessionSnapshot`, `AgentSessionStartedEvent`, `AgentSessionStatus`, `AgentSessionStoppedEvent`, `AgentSessionUpdatedEvent`, `AgentToolCompletedEvent`, `AgentToolDeltaEvent`, `AgentToolStartedEvent`, `AgentTurnStartedEvent`, `AgentVerificationCompletedEvent`, `CreateSessionInput`, `ForkSessionInput`, `ForkSessionResult`, `ReloadResult`, `SendMessageInput`, `agentError`, `agentEventProblem`, `boundAgentText`, `boundAgentValue`, `createAgentEventStream`, `isAgentEvent`, `isAgentExtensionEventType`, `splitAgentText`
 
 ## @nifrajs/agent-review
 
@@ -15120,11 +16941,11 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/auth
 
-`AuthorizationRequest`, `Authorizer`, `CsrfOptions`, `GuardOptions`, `KVNamespaceLike`, `KVSessionStore`, `MemorySessionStore`, `MemorySessionStoreOptions`, `Session`, `SessionContext`, `SessionCookieOptions`, `SessionManager`, `SessionOptions`, `SessionRecord`, `SessionStore`, `createSessions`, `csrf`, `isAuthorized`, `requireAuthorization`, `requireSession`, `requireUser`
+`AuthorizationRequest`, `Authorizer`, `CsrfOptions`, `GuardOptions`, `KVNamespaceLike`, `KVSessionStore`, `MemorySessionStore`, `MemorySessionStoreOptions`, `Session`, `SessionContext`, `SessionCookieOptions`, `SessionManager`, `SessionOptions`, `SessionRecord`, `SessionStore`, `UnauthenticatedResponse`, `createSessions`, `csrf`, `isAuthorized`, `requireAuthorization`, `requireSession`, `requireUser`
 
 ## @nifrajs/authjs
 
-`AuthGuardOptions`, `AuthJSConfig`, `AuthJSOptions`, `Session`, `app`, `authjs`, `getSession`, `requireAuthUser`
+`AuthGuardOptions`, `AuthJSConfig`, `AuthJSOptions`, `Session`, `UnauthenticatedResponse`, `app`, `authjs`, `getSession`, `requireAuthUser`
 
 ## @nifrajs/aws-lambda
 
@@ -15132,19 +16953,19 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/better-auth
 
-`AuthedOptions`, `BetterAuthLike`, `BetterAuthOptions`, `Principal`, `PrincipalFor`, `RequireSessionOptions`, `SessionOf`, `SessionUserOf`, `WithPrincipal`, `authed`, `betterAuth`, `getSession`, `requirePrincipal`, `requireSession`
+`AuthedOptions`, `BetterAuthLike`, `BetterAuthOptions`, `Principal`, `PrincipalFor`, `RequireSessionOptions`, `SessionOf`, `SessionUserOf`, `UnauthenticatedResponse`, `WithPrincipal`, `authed`, `betterAuth`, `getSession`, `requirePrincipal`, `requireSession`
 
 ## @nifrajs/cache
 
-`Cache`, `CacheCapabilities`, `CacheEvent`, `CacheObserver`, `CacheOperation`, `CacheOptions`, `CacheOutcome`, `CacheStore`, `CapabilityBeacon`, `MemoryCache`, `MemoryCacheOptions`, `SetOptions`, `StoredEntry`, `WrapOptions`, `createCache`
+`Cache`, `CacheCapabilities`, `CacheEvent`, `CacheObserver`, `CacheOperation`, `CacheOptions`, `CacheOutcome`, `CacheStore`, `CacheStoreOp`, `CapabilityBeacon`, `MemoryCache`, `MemoryCacheOptions`, `SetOptions`, `StoredEntry`, `WrapOptions`, `createCache`
 
 ## @nifrajs/client
 
-`ActionArgs`, `ActionData`, `ApiError`, `ApiProxy`, `ClientOptions`, `ClientRetryOptions`, `FetchFn`, `InProcessClient`, `InProcessClientOptions`, `Jsonify`, `LoaderArgs`, `LoaderData`, `LoaderResponseControls`, `OutputOf`, `RESERVED_EXACT_KEYS`, `RESERVED_KEY_READOUT`, `RESERVED_VERB_KEYS`, `Register`, `RegisteredBackend`, `RegisteredEnv`, `RegistryOf`, `ResponseContractViolation`, `Result`, `RouteLoaderArgs`, `SearchSchemaOf`, `SubscribeOptions`, `Subscription`, `TestClientOptions`, `Treaty`, `TreatyFromRegistry`, `WsCallOptions`, `WsHandle`, `client`, `inProcessClient`, `reservedKeyFor`, `testClient`
+`ActionArgs`, `ActionData`, `ApiError`, `ApiProxy`, `ClientOptions`, `ClientRetryOptions`, `FetchFn`, `InProcessClient`, `InProcessClientOptions`, `InputOf`, `Jsonify`, `LoaderArgs`, `LoaderData`, `LoaderResponseControls`, `OutputOf`, `RESERVED_EXACT_KEYS`, `RESERVED_KEY_READOUT`, `RESERVED_VERB_KEYS`, `Register`, `RegisteredBackend`, `RegisteredEnv`, `RegistryOf`, `ResponseContractViolation`, `Result`, `RouteActionReturn`, `RouteLoaderArgs`, `RouteLoaderReturn`, `SearchSchemaOf`, `SubscribeOptions`, `Subscription`, `TestClientOptions`, `Treaty`, `TreatyFromRegistry`, `WsCallOptions`, `WsHandle`, `client`, `inProcessClient`, `reservedKeyFor`, `testClient`
 
 ## @nifrajs/coding-agent
 
-`AGENT_CAPABILITY_MANIFEST_VERSION`, `AGENT_PRESETS`, `AgentCapability`, `AgentCapabilityManifest`, `AgentPlan`, `AgentPreset`, `AgentPresetName`, `ApprovalDecision`, `ApprovalManager`, `ApprovalManagerOptions`, `ApprovalMatchRejection`, `ApprovalMatchResult`, `ApprovalRequest`, `BoundedSubagentRunner`, `BoundedText`, `CapabilityDescriptor`, `CiDeploymentAdapter`, `CodingAgentExtension`, `CodingAgentHost`, `CodingAgentHostOptions`, `CodingAgentRpcServer`, `CodingAgentRpcServerHandle`, `CodingAgentRpcServerOptions`, `CompactionReport`, `ContextRecord`, `ContextWindow`, `ContextWindowOptions`, `DEPLOYMENT_REFERENCE_PROFILES`, `ExtensionCommand`, `ExtensionContext`, `ExtensionDescriptorOptions`, `ExtensionDescriptorSource`, `ExtensionEventHandler`, `ExtensionHost`, `ExtensionHostOptions`, `ExtensionProvider`, `ExtensionReloadResult`, `ExtensionSubagent`, `ExtensionTool`, `FileSessionStore`, `FileSessionStoreOptions`, `HandoffCoordinator`, `HandoffCoordinatorOptions`, `HandoffDecision`, `HandoffError`, `HandoffRejection`, `HandoffView`, `HealingEvent`, `HealingOptions`, `HealingResult`, `IsolatedExtensionSnapshot`, `IsolatedExtensionTool`, `IsolatedExtensionWorker`, `IsolatedExtensionWorkerOptions`, `LocalProcessDeploymentAdapter`, `MigrateLegacySessionOptions`, `NIFRA_AGENT_INSTRUCTIONS`, `NativeApprovalPort`, `NativeGatewayModelPortOptions`, `NativeMessage`, `NativeModelChunk`, `NativeModelPort`, `NativeModelRequest`, `NativeModelResponse`, `NativeTool`, `NifraAgentTool`, `NifraBackend`, `NifraBackendOptions`, `NifraContextOptions`, `NifraContextResult`, `OpenHandoffInput`, `PiBackend`, `PiBackendOptions`, `PlanEvent`, `PlanPhase`, `PlanResult`, `PlanRunner`, `PlanRunnerOptions`, `ProjectDiffOptions`, `ProjectDiffResult`, `RepairProposal`, `ReplayBackend`, `ReplayBackendOptions`, `ReplayDeploymentAdapter`, `ReviewExecutionErrorCode`, `ReviewExecutionResult`, `ReviewOptions`, `SESSION_EVIDENCE_VERSION`, `SelfHealingController`, `SessionEvidenceRecord`, `SessionLogEntry`, `SessionMigrationError`, `SessionMigrationReport`, `SessionStore`, `SubagentAbandonment`, `SubagentAbandonmentLedger`, `SubagentExecutor`, `SubagentResult`, `SubagentRunnerOptions`, `SubagentSpec`, `UiExtensionHost`, `UiExtensionHostOptions`, `UiExtensionManifest`, `UiExtensionSlot`, `UiReloadResult`, `UiStatusWidget`, `UiThemeDescriptor`, `VerificationOptions`, `VerificationRepairTask`, `VerificationResult`, `WorkflowContext`, `WorkflowEvent`, `WorkflowResult`, `WorkflowRunner`, `WorkflowRunnerOptions`, `WorkflowStep`, `approvalRequestFromEvent`, `approvalResolvedEvent`, `createCapabilityManifest`, `createCiDeploymentAdapter`, `createLocalProcessDeploymentAdapter`, `createNativeGatewayModelPort`, `createNifraTools`, `createPresetSpec`, `createReplayDeploymentAdapter`, `createVerificationRepairTask`, `deniedCapabilities`, `discoverExtensions`, `extensionDescriptor`, `extensionDescriptors`, `getAgentPreset`, `isSafeReviewDiff`, `migrateLegacySession`, `parseCapabilityManifest`, `parseSessionEvidenceRecord`, `readBoundedText`, `readProjectDiff`, `readReplayEvents`, `runNifraContext`, `runNifraReview`, `runNifraVerification`, `stableSessionEventCode`, `validateExtensionModule`
+`AGENT_CAPABILITY_MANIFEST_VERSION`, `AGENT_PRESETS`, `APPROVAL_NEVER_EXPIRES_AT`, `AgentCapability`, `AgentCapabilityManifest`, `AgentPlan`, `AgentPreset`, `AgentPresetName`, `ApprovalDecision`, `ApprovalManager`, `ApprovalManagerOptions`, `ApprovalMatchRejection`, `ApprovalMatchResult`, `ApprovalRequest`, `ApprovalTimeout`, `BoundedSubagentRunner`, `BoundedText`, `CapabilityDescriptor`, `CiDeploymentAdapter`, `CodingAgentExtension`, `CodingAgentHost`, `CodingAgentHostOptions`, `CodingAgentRpcServer`, `CodingAgentRpcServerHandle`, `CodingAgentRpcServerOptions`, `CompactionReport`, `ContextRecord`, `ContextWindow`, `ContextWindowOptions`, `DEPLOYMENT_REFERENCE_PROFILES`, `ExtensionCommand`, `ExtensionContext`, `ExtensionDescriptorOptions`, `ExtensionDescriptorSource`, `ExtensionEventHandler`, `ExtensionHost`, `ExtensionHostOptions`, `ExtensionProvider`, `ExtensionReloadResult`, `ExtensionSubagent`, `ExtensionTool`, `FileSessionStore`, `FileSessionStoreOptions`, `HandoffCoordinator`, `HandoffCoordinatorOptions`, `HandoffDecision`, `HandoffError`, `HandoffRejection`, `HandoffView`, `HealingEvent`, `HealingOptions`, `HealingResult`, `IsolatedExtensionSnapshot`, `IsolatedExtensionTool`, `IsolatedExtensionWorker`, `IsolatedExtensionWorkerOptions`, `LocalProcessDeploymentAdapter`, `MigrateLegacySessionOptions`, `NIFRA_AGENT_INSTRUCTIONS`, `NativeApprovalPort`, `NativeGatewayModelPortOptions`, `NativeMessage`, `NativeModelChunk`, `NativeModelPort`, `NativeModelRequest`, `NativeModelResponse`, `NativeTool`, `NifraAgentTool`, `NifraBackend`, `NifraBackendOptions`, `NifraContextOptions`, `NifraContextResult`, `OpenHandoffInput`, `PiBackend`, `PiBackendOptions`, `PlanEvent`, `PlanPhase`, `PlanResult`, `PlanRunner`, `PlanRunnerOptions`, `ProjectDiffOptions`, `ProjectDiffResult`, `RepairProposal`, `ReplayBackend`, `ReplayBackendOptions`, `ReplayDeploymentAdapter`, `ReviewExecutionErrorCode`, `ReviewExecutionResult`, `ReviewOptions`, `SESSION_EVIDENCE_VERSION`, `SelfHealingController`, `SessionEvidenceRecord`, `SessionLogEntry`, `SessionMigrationError`, `SessionMigrationReport`, `SessionStore`, `SubagentAbandonment`, `SubagentAbandonmentLedger`, `SubagentExecutor`, `SubagentResult`, `SubagentRunnerOptions`, `SubagentSpec`, `UiExtensionHost`, `UiExtensionHostOptions`, `UiExtensionManifest`, `UiExtensionSlot`, `UiReloadResult`, `UiStatusWidget`, `UiThemeDescriptor`, `VerificationOptions`, `VerificationRepairTask`, `VerificationResult`, `WorkflowContext`, `WorkflowEvent`, `WorkflowResult`, `WorkflowRunner`, `WorkflowRunnerOptions`, `WorkflowStep`, `approvalRequestFromEvent`, `approvalResolvedEvent`, `createCapabilityManifest`, `createCiDeploymentAdapter`, `createLocalProcessDeploymentAdapter`, `createNativeGatewayModelPort`, `createNifraTools`, `createPresetSpec`, `createReplayDeploymentAdapter`, `createVerificationRepairTask`, `deniedCapabilities`, `discoverExtensions`, `extensionDescriptor`, `extensionDescriptors`, `getAgentPreset`, `isSafeReviewDiff`, `isVerificationAvailable`, `migrateLegacySession`, `parseCapabilityManifest`, `parseSessionEvidenceRecord`, `readBoundedText`, `readProjectDiff`, `readReplayEvents`, `runNifraContext`, `runNifraReview`, `runNifraVerification`, `stableSessionEventCode`, `validateExtensionModule`
 
 ## @nifrajs/content
 
@@ -15152,7 +16973,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/core
 
-`AdmissionController`, `AdmissionDecision`, `AnyServer`, `AuthHeaders`, `AuthMaybePromise`, `AuthenticationFailure`, `AuthenticationFailureReason`, `AuthenticationInput`, `AuthenticationResult`, `AuthenticationStage`, `AuthenticationSuccess`, `Context`, `ContextPlugin`, `CookieOptions`, `CookieSecret`, `DefinePluginResult`, `DurableObjectNamespaceLike`, `ExecutionContext`, `FRAMEWORK_NAME`, `FetchApp`, `FrameworkError`, `FrameworkName`, `Handler`, `IdentityPlugin`, `InferInput`, `InferOutput`, `JoinRoutePath`, `LambdaEvent`, `LambdaHandler`, `LambdaResponse`, `LambdaV1Event`, `LambdaV2Event`, `ListenTlsOptions`, `LogFields`, `Logger`, `METHODS`, `McpPromptDescriptor`, `McpResourceDescriptor`, `Method`, `Middleware`, `MountFetchOptions`, `MountOptions`, `MountableApp`, `NetlifyEvent`, `NetlifyHandler`, `NifraFeatureVersion`, `NifraPlugin`, `NifraWebSocket`, `NodeRequestContext`, `NodeRequestHook`, `NodeResponseBodyHook`, `NodeResponseContext`, `NodeResponseHook`, `NodeServeOutcome`, `OnRequestResult`, `Params`, `PlainRender`, `Platform`, `PlatformResponse`, `PluginTypeCollapsed`, `PrefixRegistry`, `Prettify`, `PromptArgument`, `PromptMessage`, `ROUTE_PATTERN_OVERLAP_MAX_STATES`, `RedactOptions`, `Registry`, `RequestPath`, `ResponseBodyHook`, `ResponseBodyReplacement`, `ResponseControls`, `ResponseFinalization`, `ResponseHeadersHook`, `ResponseHeadersView`, `ResponseMapFor`, `ResponseResult`, `RouteConfigError`, `RouteConfigErrorCode`, `RouteDescriptor`, `RouteInfo`, `RouteInfoFor`, `RouteMethod`, `RoutePatternOverlapLimitError`, `RouteSchema`, `Router`, `RouterMatch`, `RunningServer`, `SSEContext`, `SSEInit`, `SSEMessage`, `SSEStream`, `ScheduledController`, `ScheduledHandler`, `Server`, `ServerOptions`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `StandardTypes`, `StandardWebSocket`, `StatusResponse`, `ToolAnnotations`, `TypedSSEStream`, `UrlParts`, `VERSION`, `ValidationOutcome`, `VercelHandler`, `Version`, `WebSocketContext`, `WebSocketData`, `WebSocketHandler`, `WebSocketUpgradeOutcome`, `authenticated`, `commonSecretPatterns`, `cookieNamePrefix`, `defineContextPlugin`, `defineIdentityPlugin`, `definePlugin`, `defineRouterPlugin`, `hasDuplicateCookie`, `isSameOriginPath`, `isSameOriginRequest`, `jsonLogger`, `parseCookies`, `pathnameOf`, `redactLogFields`, `rejected`, `replacedRequestOf`, `routePatternOverlap`, `serializeCookie`, `server`, `signValue`, `silentLogger`, `status`, `toFetchHandler`, `toLambdaHandler`, `toNetlifyHandler`, `toVercelHandler`, `unsignValue`, `urlPartsOf`
+`AdmissionController`, `AdmissionDecision`, `AnyServer`, `AuthHeaders`, `AuthMaybePromise`, `AuthenticationFailure`, `AuthenticationFailureReason`, `AuthenticationInput`, `AuthenticationResult`, `AuthenticationStage`, `AuthenticationSuccess`, `Context`, `ContextPlugin`, `CookieOptions`, `CookieSecret`, `DeclaredMountRoute`, `DefinePluginResult`, `DurableObjectNamespaceLike`, `ExecutionContext`, `FRAMEWORK_NAME`, `FetchApp`, `FrameworkError`, `FrameworkName`, `Handler`, `IdentityPlugin`, `InferInput`, `InferOutput`, `JoinRoutePath`, `LambdaEvent`, `LambdaHandler`, `LambdaResponse`, `LambdaV1Event`, `LambdaV2Event`, `ListenTlsOptions`, `LogFields`, `Logger`, `METHODS`, `McpPromptDescriptor`, `McpResourceDescriptor`, `Method`, `Middleware`, `MountFetchOptions`, `MountOptions`, `MountableApp`, `NetlifyEvent`, `NetlifyHandler`, `NifraFeatureVersion`, `NifraPlugin`, `NifraWebSocket`, `NodeRequestContext`, `NodeRequestHook`, `NodeResponseBodyHook`, `NodeResponseContext`, `NodeResponseHook`, `NodeServeOutcome`, `OnRequestResult`, `OpaqueMountDeclaration`, `Params`, `PlainRender`, `Platform`, `PlatformResponse`, `PluginTypeCollapsed`, `PrefixRegistry`, `Prettify`, `PromptArgument`, `PromptMessage`, `ROUTE_PATTERN_OVERLAP_MAX_STATES`, `RedactOptions`, `Registry`, `RequestPath`, `ResponseBodyHook`, `ResponseBodyReplacement`, `ResponseControls`, `ResponseFinalization`, `ResponseHeadersHook`, `ResponseHeadersView`, `ResponseMapFor`, `ResponseResult`, `RouteConfigError`, `RouteConfigErrorCode`, `RouteDescriptor`, `RouteInfo`, `RouteInfoFor`, `RouteMethod`, `RoutePatternOverlapLimitError`, `RouteSchema`, `Router`, `RouterMatch`, `RunningServer`, `SSEContext`, `SSEInit`, `SSEMessage`, `SSEStream`, `ScheduledController`, `ScheduledHandler`, `Server`, `ServerOptions`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `StandardTypes`, `StandardWebSocket`, `StatusResponse`, `ToolAnnotations`, `TypedSSEStream`, `UrlParts`, `VERSION`, `ValidationOutcome`, `VercelHandler`, `Version`, `WebSocketContext`, `WebSocketData`, `WebSocketHandler`, `WebSocketUpgradeOutcome`, `authenticated`, `commonSecretPatterns`, `cookieNamePrefix`, `defineContextPlugin`, `defineIdentityPlugin`, `definePlugin`, `defineRouterPlugin`, `hasDuplicateCookie`, `isAuthenticatedRequest`, `isSameOriginForm`, `isSameOriginPath`, `isSameOriginRequest`, `jsonLogger`, `markAuthenticatedRequest`, `parseCookies`, `pathnameOf`, `redactLogFields`, `rejected`, `replacedRequestOf`, `routePatternOverlap`, `serializeCookie`, `server`, `signValue`, `silentLogger`, `status`, `toFetchHandler`, `toLambdaHandler`, `toNetlifyHandler`, `toVercelHandler`, `unsignValue`, `urlPartsOf`, `writableResponse`
 
 ## @nifrajs/cron
 
@@ -15180,7 +17001,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/graphql
 
-`GraphqlContextBuilder`, `GraphqlContextInput`, `GraphqlHttpOptions`, `GraphqlPubSub`, `GraphqlWsOptions`, `MountGraphqlOptions`, `NifraContextLike`, `buildContext`, `createPubSub`, `graphqlWebSocket`, `mountGraphql`, `respondGraphql`
+`GraphqlContextBuilder`, `GraphqlContextInput`, `GraphqlHttpOptions`, `GraphqlPubSub`, `GraphqlPubSubOptions`, `GraphqlPubSubOverflowError`, `GraphqlWsOptions`, `MountGraphqlOptions`, `NifraContextLike`, `buildContext`, `createPubSub`, `graphqlWebSocket`, `mountGraphql`, `respondGraphql`
 
 ## @nifrajs/i18n
 
@@ -15196,11 +17017,11 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/islets
 
-`BindableElement`, `BindableRoot`, `IslandContext`, `IslandHost`, `IslandScope`, `IslandSetup`, `IslandStrategy`, `MountIslandOptions`, `Signal`, `batch`, `bindScope`, `computed`, `effect`, `island`, `islandState`, `mountIslands`, `signal`
+`BindableElement`, `BindableRoot`, `Computed`, `IslandContext`, `IslandHost`, `IslandScope`, `IslandSetup`, `IslandStrategy`, `MountIslandOptions`, `Signal`, `batch`, `bindScope`, `computed`, `effect`, `island`, `islandState`, `mountIslands`, `signal`
 
 ## @nifrajs/jobs
 
-`Backoff`, `CapabilityBeacon`, `DeadLetterRecord`, `DeadLetterView`, `EnqueueOptions`, `ExponentialOptions`, `JobContext`, `JobCounts`, `JobDefinition`, `JobEnqueueInfo`, `JobError`, `JobHandle`, `JobHandler`, `JobRunInfo`, `JobRunOutcome`, `JobStore`, `JobTraceContext`, `JobValidationError`, `MemoryJobStore`, `Queue`, `QueueHealth`, `QueueInstrument`, `QueueOptions`, `RetryPolicy`, `StandardResult`, `StandardSchemaV1`, `StoredJob`, `Worker`, `WorkerOptions`, `createQueue`, `exponentialBackoff`, `fixedBackoff`, `noBackoff`, `toDeadLetterView`, `toQueueHealth`
+`Backoff`, `CapabilityBeacon`, `DeadLetterRecord`, `DeadLetterView`, `EnqueueOptions`, `ExponentialOptions`, `JobContext`, `JobCounts`, `JobDefinition`, `JobEnqueueInfo`, `JobError`, `JobHandle`, `JobHandler`, `JobRunInfo`, `JobRunOutcome`, `JobStore`, `JobTimeoutError`, `JobTraceContext`, `JobValidationError`, `MemoryJobStore`, `Queue`, `QueueHealth`, `QueueInstrument`, `QueueOptions`, `RetryPolicy`, `StandardResult`, `StandardSchemaV1`, `StoredJob`, `Worker`, `WorkerOptions`, `createQueue`, `exponentialBackoff`, `fixedBackoff`, `noBackoff`, `toDeadLetterView`, `toQueueHealth`
 
 ## @nifrajs/mcp
 
@@ -15212,11 +17033,11 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/middleware
 
-`AdmissionControllerHandle`, `AdmissionEvidence`, `AdmissionOptions`, `AdmissionPolicy`, `AdmissionSnapshot`, `ApiKeyStaticOptions`, `ApiKeyVerifyOptions`, `AuthPlugin`, `BasicAuthPlugin`, `BasicAuthStaticOptions`, `BasicAuthVerifyOptions`, `BearerOptions`, `BodyLimitOptions`, `ByteRange`, `ByteRangeResult`, `CacheControlOptions`, `CacheOptions`, `CachedResponse`, `Composable`, `CompressionOptions`, `ConditionalResponseOptions`, `ContentPreference`, `CorsOptions`, `CsrfOptions`, `DurableCommandOptions`, `ETagOptions`, `HealthcheckOptions`, `IdempotencyClaim`, `IdempotencyOptions`, `IdempotencyRecord`, `IdempotencyStore`, `IpMatcher`, `IpRestrictionOptions`, `JwkKey`, `JwksOptions`, `JwtAlgorithm`, `JwtClaims`, `JwtHeader`, `JwtKeyResolver`, `JwtOptions`, `JwtPlugin`, `JwtVerificationKey`, `LanguageMatch`, `LanguageOptions`, `LoggerOptions`, `LoopDelayHistogram`, `LoopDelayMonitor`, `MemoryIdempotencyStore`, `MemoryIdempotencyStoreOptions`, `MemoryResponseCache`, `MemoryResponseCacheOptions`, `MemoryStore`, `MemoryStoreOptions`, `MethodOverrideOptions`, `MultipartBody`, `MultipartHeadersInit`, `MultipartPart`, `MultipartResponseOptions`, `OpenApiInfo`, `OpenApiOptions`, `OpenApiServer`, `OpenApiTag`, `OpenApiUiOptions`, `PoweredByOptions`, `PrettyJsonOptions`, `ProblemDetailsOptions`, `RangeResponseOptions`, `RateLimitOptions`, `RateLimitResult`, `RateLimitStore`, `RequestIdOptions`, `RequestLogFields`, `ResponseCacheStore`, `RouteLike`, `SecurityHeadersOptions`, `SecurityRequirement`, `ShedReason`, `TimingControls`, `TimingMetric`, `TimingOptions`, `TrailingSlashOptions`, `VerifiedJwt`, `VerifyJwtOptions`, `VerifyJwtResult`, `apiKey`, `appendTrailingSlash`, `basicAuth`, `bearer`, `bodyLimit`, `buildOpenApiDocument`, `cache`, `cacheControl`, `combine`, `compression`, `conditionalResponse`, `cors`, `createAdmissionController`, `createCsrfToken`, `createEventLoopLagSampler`, `csrf`, `durableCommand`, `etag`, `healthcheck`, `idempotency`, `ipRestriction`, `jwk`, `jwks`, `jwt`, `language`, `logger`, `methodOverride`, `multipartResponse`, `namedCombine`, `negotiateContentType`, `openapi`, `parseAcceptHeader`, `parseByteRange`, `pickLanguage`, `poweredBy`, `prettyJson`, `problemDetails`, `rangeResponse`, `rateLimit`, `requestId`, `responseCache`, `securityHeaders`, `timing`, `trimTrailingSlash`, `tryVerifyJwt`, `verifyCsrfToken`, `verifyJwt`
+`AdmissionControllerHandle`, `AdmissionEvidence`, `AdmissionOptions`, `AdmissionPolicy`, `AdmissionSnapshot`, `ApiKeyStaticOptions`, `ApiKeyVerifyOptions`, `AuthPlugin`, `BasicAuthPlugin`, `BasicAuthStaticOptions`, `BasicAuthVerifyOptions`, `BearerOptions`, `BodyLimitOptions`, `ByteRange`, `ByteRangeResult`, `CacheControlOptions`, `CacheOptions`, `CachedResponse`, `Composable`, `CompressionOptions`, `ConditionalResponseOptions`, `ContentPreference`, `CorsOptions`, `CsrfOptions`, `DurableCommandOptions`, `ETagOptions`, `HealthcheckOptions`, `IdempotencyClaim`, `IdempotencyOptions`, `IdempotencyRecord`, `IdempotencyStore`, `IpMatcher`, `IpRestrictionOptions`, `JwkKey`, `JwksOptions`, `JwtAlgorithm`, `JwtClaims`, `JwtHeader`, `JwtKeyResolver`, `JwtOptions`, `JwtPlugin`, `JwtVerificationKey`, `LanguageMatch`, `LanguageOptions`, `LoggerOptions`, `LoopDelayHistogram`, `LoopDelayMonitor`, `MemoryIdempotencyStore`, `MemoryIdempotencyStoreOptions`, `MemoryResponseCache`, `MemoryResponseCacheOptions`, `MemoryStore`, `MemoryStoreOptions`, `MethodOverrideOptions`, `MultipartBody`, `MultipartHeadersInit`, `MultipartPart`, `MultipartResponseOptions`, `OpenApiInfo`, `OpenApiOptions`, `OpenApiServer`, `OpenApiTag`, `OpenApiUiOptions`, `PoweredByOptions`, `PrettyJsonOptions`, `ProblemDetailsOptions`, `RangeResponseOptions`, `RateLimitOptions`, `RateLimitResult`, `RateLimitStore`, `RateLimitTier`, `RateLimitTiersOptions`, `RequestIdOptions`, `RequestLogFields`, `ResponseCacheStore`, `RouteLike`, `SecurityHeadersOptions`, `SecurityRequirement`, `ShedReason`, `TimingControls`, `TimingMetric`, `TimingOptions`, `TrailingSlashOptions`, `VerifiedJwt`, `VerifyJwtOptions`, `VerifyJwtResult`, `apiKey`, `appendTrailingSlash`, `basicAuth`, `bearer`, `bodyLimit`, `buildOpenApiDocument`, `cache`, `cacheControl`, `combine`, `compression`, `conditionalResponse`, `cors`, `createAdmissionController`, `createCsrfToken`, `createEventLoopLagSampler`, `csrf`, `durableCommand`, `etag`, `healthcheck`, `idempotency`, `ipRestriction`, `jwk`, `jwks`, `jwt`, `language`, `logger`, `methodOverride`, `multipartResponse`, `namedCombine`, `negotiateContentType`, `openapi`, `parseAcceptHeader`, `parseByteRange`, `pickLanguage`, `poweredBy`, `prettyJson`, `problemDetails`, `rangeResponse`, `rateLimit`, `rateLimitTiers`, `requestId`, `responseCache`, `securityHeaders`, `timing`, `trimTrailingSlash`, `tryVerifyJwt`, `verifyCsrfToken`, `verifyJwt`
 
 ## @nifrajs/mock
 
-`MockServer`, `MockServerOptions`, `MockableApp`, `MockableRoute`, `UnsupportedMockSchemaError`, `autoReflectJsonSchema`, `createMockServer`, `generateMockValue`
+`MockServer`, `MockServerOptions`, `MockableApp`, `MockableRoute`, `UnsupportedMockSchemaError`, `autoReflectJsonSchema`, `createMockServer`, `explainAutoReflectJsonSchema`, `generateMockValue`
 
 ## @nifrajs/node
 
@@ -15244,7 +17065,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/schema
 
-`DeferredValue`, `ImportOpenAPIOptions`, `ImportedApiInventory`, `ImportedRoute`, `ImportedRouteQuery`, `NifraSchema`, `OpenAPIDocument`, `OpenAPIImportError`, `OpenAPIInfo`, `OpenApiInventoryDrift`, `Page`, `decodeCursor`, `diffOpenApiInventory`, `encodeCursor`, `fromTypeBox`, `importOpenAPI`, `paginate`, `registerFormat`, `t`, `toOpenAPI`, `toOpenAPIFromEvidence`
+`DeferredValue`, `ImportOpenAPIOptions`, `ImportedApiInventory`, `ImportedRoute`, `ImportedRouteQuery`, `JsonValue`, `NifraSchema`, `OpenAPIDocument`, `OpenAPIImportError`, `OpenAPIInfo`, `OpenAPIVersion`, `OpenApiInventoryDrift`, `Page`, `decodeCursor`, `diffOpenApiInventory`, `encodeCursor`, `fromTypeBox`, `importOpenAPI`, `paginate`, `registerFormat`, `t`, `toOpenAPI`, `toOpenAPIFromEvidence`
 
 ## @nifrajs/storage
 
@@ -15252,7 +17073,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/testing
 
-`AdapterCertificationError`, `AdapterCertificationProfile`, `AdapterCertificationReport`, `AdversarialContractError`, `AdversarialContractOptions`, `AdversarialContractReport`, `AdversarialContractResult`, `AgentEvalCase`, `AgentEvalComponentEvidence`, `AgentEvalCompositionOptions`, `AgentEvalCompositionReport`, `AgentEvalRegressionError`, `AgentEvalReport`, `AgentEvalSuite`, `AgentEvalSuiteSpec`, `AgentFailureMatrixCase`, `AgentFailureMatrixError`, `AgentFailureMatrixKind`, `AgentFailureMatrixReport`, `AppLike`, `BaselineComparison`, `BaselineOptions`, `CaptureIncidentOptions`, `CapturedRequest`, `CapturedRequestInput`, `CaseComparison`, `CaseResult`, `CertifiableCacheEntry`, `CertifiableCacheStore`, `CertifiableDeploymentAdapter`, `CertifiableDescriptorAdapter`, `CertifiableDomainEvent`, `CertifiableEventDeliveryAdapter`, `CertifiableEventRecord`, `CertifiableJobStore`, `CertifiableModelGateway`, `CertifiableRuntimeAdapter`, `CertifiableRuntimeServer`, `CertifiableStorageAdapter`, `CertificationCapabilityEvidence`, `CertificationCheck`, `CertificationCheckEvidence`, `CertificationTarget`, `ComparisonCode`, `ContractAuthContext`, `ContractCaseContext`, `ContractCaseKind`, `ContractCoverageGap`, `ContractCoverageGapCode`, `ContractExpectedResponse`, `ContractLabHandler`, `ContractLabRuntimeAdapter`, `ContractLabServer`, `ContractLabWitness`, `ContractReplay`, `ContractRuntime`, `ContractTarget`, `ContractTestApp`, `ContractWitness`, `CookieJar`, `CreateTrajectoryTranscriptOptions`, `DataAdapterConformanceError`, `DataAdapterConformanceReport`, `DataAdapterConformanceTarget`, `DataConformanceCheck`, `DataConformanceFailure`, `DataConformancePage`, `DataConformanceScope`, `DataConformanceTransaction`, `EffectLedger`, `FailureDirective`, `FailureEvidence`, `FailureInjectedError`, `FailureKind`, `FailureLab`, `FailureLabOptions`, `FailureReplay`, `FailureScenario`, `FailureScenarioReport`, `FaultProfile`, `FaultProfileFault`, `FaultProfileFaultKind`, `FaultProfileReport`, `FaultProfileScenario`, `FaultProfileScenarioReport`, `GenerateRegressionTestOptions`, `IdempotencyDivergence`, `IdempotencyProof`, `IncidentCapsule`, `IncidentReplayError`, `IncidentReplayResult`, `PREDICTION_LAB_SEED`, `PredictionLabContext`, `PredictionLabOptions`, `PredictionLabReplay`, `PredictionLabReport`, `PredictionLabResult`, `PredictionLabTarget`, `ReplayIncidentOptions`, `ReplayTrajectoryOptions`, `RubricShape`, `RubricSpec`, `RubricVerdict`, `RunFaultProfileOptions`, `ScoreTolerance`, `TestSession`, `TestSessionOptions`, `TrajectoryInvariantId`, `TrajectoryInvariantOptions`, `TrajectoryInvariantResult`, `TrajectoryReplayResult`, `TrajectoryRun`, `TrajectoryTranscript`, `assertAdapterCertification`, `assertAdversarialContract`, `assertAgentEval`, `assertAgentEvalBaseline`, `assertAgentFailureMatrix`, `assertDataAdapterConformance`, `assertIncidentReplays`, `assertPredictionLab`, `assertTrajectoryInvariants`, `cacheStoreCertificationProfile`, `captureIncident`, `certifyAdapter`, `checkTrajectoryInvariants`, `compareAgentEvalBaseline`, `contractLabWitnesses`, `cookieJar`, `createFailureLab`, `createReferenceContractLabHandler`, `createTrajectoryTranscript`, `defineAgentEvalSuite`, `defineCertificationProfile`, `defineFaultProfile`, `deploymentAdapterCertificationProfile`, `deploymentCertificationProfile`, `eventDeliveryCertificationProfile`, `gatewayCertificationProfile`, `generateRegressionTest`, `httpToolAdapter`, `inProcessToolAdapter`, `jobStoreCertificationProfile`, `mcpToolAdapter`, `modelGatewayCertificationProfile`, `parseRubricVerdict`, `predictionLabCaseIds`, `proveIdempotency`, `recordTrajectory`, `redactForEmission`, `referenceFaultProfile`, `registryCertificationProfile`, `replayIncident`, `replayTrajectory`, `runAdversarialContract`, `runAgentEvalComposition`, `runAgentFailureMatrix`, `runContractLab`, `runContractLabOverHttp`, `runContractLabThroughAdapter`, `runDataAdapterConformance`, `runFailureScenario`, `runFaultProfile`, `runPredictionLab`, `runTrajectory`, `runtimeAdapterCertificationProfile`, `shapeOf`, `storageAdapterCertificationProfile`, `testSession`, `testToolAdapter`, `toPredictionLabContext`, `trajectoryRegressionId`, `verifyAdapterCertification`
+`AdapterCertificationError`, `AdapterCertificationProfile`, `AdapterCertificationReport`, `AdversarialContractError`, `AdversarialContractOptions`, `AdversarialContractReport`, `AdversarialContractResult`, `AgentEvalCase`, `AgentEvalComponentEvidence`, `AgentEvalCompositionOptions`, `AgentEvalCompositionReport`, `AgentEvalRegressionError`, `AgentEvalReport`, `AgentEvalSuite`, `AgentEvalSuiteSpec`, `AgentFailureMatrixCase`, `AgentFailureMatrixError`, `AgentFailureMatrixKind`, `AgentFailureMatrixOptions`, `AgentFailureMatrixReport`, `AppLike`, `BaselineComparison`, `BaselineOptions`, `CaptureIncidentOptions`, `CapturedRequest`, `CapturedRequestInput`, `CaseComparison`, `CaseResult`, `CertifiableCacheEntry`, `CertifiableCacheStore`, `CertifiableDeploymentAdapter`, `CertifiableDescriptorAdapter`, `CertifiableDomainEvent`, `CertifiableEventDeliveryAdapter`, `CertifiableEventRecord`, `CertifiableJobStore`, `CertifiableModelGateway`, `CertifiableRuntimeAdapter`, `CertifiableRuntimeServer`, `CertifiableStorageAdapter`, `CertificationCapabilityEvidence`, `CertificationCheck`, `CertificationCheckEvidence`, `CertificationTarget`, `ComparisonCode`, `ContractAuthContext`, `ContractCaseContext`, `ContractCaseKind`, `ContractCoverageGap`, `ContractCoverageGapCode`, `ContractExpectedResponse`, `ContractLabHandler`, `ContractLabRuntimeAdapter`, `ContractLabServer`, `ContractLabWitness`, `ContractReplay`, `ContractRuntime`, `ContractTarget`, `ContractTestApp`, `ContractWitness`, `CookieJar`, `CreateTrajectoryTranscriptOptions`, `DataAdapterConformanceError`, `DataAdapterConformanceReport`, `DataAdapterConformanceTarget`, `DataConformanceCheck`, `DataConformanceFailure`, `DataConformancePage`, `DataConformanceScope`, `DataConformanceTransaction`, `EffectLedger`, `FailureDirective`, `FailureEvidence`, `FailureInjectedError`, `FailureKind`, `FailureLab`, `FailureLabOptions`, `FailureReplay`, `FailureScenario`, `FailureScenarioReport`, `FaultProfile`, `FaultProfileFault`, `FaultProfileFaultKind`, `FaultProfileReport`, `FaultProfileScenario`, `FaultProfileScenarioReport`, `GenerateRegressionTestOptions`, `IdempotencyDivergence`, `IdempotencyProof`, `IncidentCapsule`, `IncidentReplayError`, `IncidentReplayResult`, `PREDICTION_LAB_SEED`, `PredictionLabContext`, `PredictionLabOptions`, `PredictionLabReplay`, `PredictionLabReport`, `PredictionLabResult`, `PredictionLabTarget`, `ReplayIncidentOptions`, `ReplayTrajectoryOptions`, `RubricShape`, `RubricSpec`, `RubricVerdict`, `RunFaultProfileOptions`, `ScoreTolerance`, `TestSession`, `TestSessionOptions`, `TrajectoryInvariantId`, `TrajectoryInvariantOptions`, `TrajectoryInvariantResult`, `TrajectoryReplayResult`, `TrajectoryRun`, `TrajectoryTranscript`, `assertAdapterCertification`, `assertAdversarialContract`, `assertAgentEval`, `assertAgentEvalBaseline`, `assertAgentFailureMatrix`, `assertDataAdapterConformance`, `assertIncidentReplays`, `assertPredictionLab`, `assertTrajectoryInvariants`, `cacheStoreCertificationProfile`, `captureIncident`, `certifyAdapter`, `checkTrajectoryInvariants`, `compareAgentEvalBaseline`, `contractLabWitnesses`, `cookieJar`, `createFailureLab`, `createReferenceContractLabHandler`, `createTrajectoryTranscript`, `defineAgentEvalSuite`, `defineCertificationProfile`, `defineFaultProfile`, `deploymentAdapterCertificationProfile`, `deploymentCertificationProfile`, `eventDeliveryCertificationProfile`, `gatewayCertificationProfile`, `generateRegressionTest`, `httpToolAdapter`, `inProcessToolAdapter`, `jobStoreCertificationProfile`, `mcpToolAdapter`, `modelGatewayCertificationProfile`, `parseRubricVerdict`, `predictionLabCaseIds`, `proveIdempotency`, `recordTrajectory`, `redactForEmission`, `referenceFaultProfile`, `registryCertificationProfile`, `replayIncident`, `replayTrajectory`, `runAdversarialContract`, `runAgentEvalComposition`, `runAgentFailureMatrix`, `runContractLab`, `runContractLabOverHttp`, `runContractLabThroughAdapter`, `runDataAdapterConformance`, `runFailureScenario`, `runFaultProfile`, `runPredictionLab`, `runTrajectory`, `runtimeAdapterCertificationProfile`, `shapeOf`, `storageAdapterCertificationProfile`, `testSession`, `testToolAdapter`, `toPredictionLabContext`, `trajectoryRegressionId`, `verifyAdapterCertification`
 
 ## @nifrajs/ts-plugin
 
@@ -15264,7 +17085,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`ACTION_GLOBAL`, `Action`, `BOUNDARY_GLOBAL`, `BackendOnly`, `Blocker`, `BlockerController`, `BlockerFunction`, `BlockerLocation`, `BlockerState`, `Boundary`, `BoundaryDescriptor`, `BoundaryError`, `BoundaryMode`, `BoundaryRegistration`, `BoundaryRequestCtx`, `BoundaryState`, `BoundaryStates`, `BoundaryStatus`, `BrowserNavigate`, `CacheStore`, `CachedResponse`, `CdnPurgeOutcome`, `CdnPurgeTarget`, `ClientAction`, `ClientActionArgs`, `ClientActionResult`, `ClientLoader`, `ClientLoaderArgs`, `ClientRequestBody`, `ClientRouteHooks`, `ClientRouter`, `ClientRouterOptions`, `CreateCspPolicyOptions`, `CreateNonceResolverOptions`, `CreateWebAppOptions`, `CspHeaderContext`, `CspPolicy`, `CssLoadingMode`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_CSS_LOADING`, `DEFAULT_DEV_PORT`, `DRAFT_COOKIE`, `Deferred`, `DehydratedState`, `DraftCookieControls`, `DynamicBoundary`, `DynamicBoundaryBatch`, `EnableDraftOptions`, `FetchRouteData`, `Fetcher`, `FetcherState`, `FontDisplay`, `FontFace`, `FontPreloadInput`, `FontSource`, `GenerateClientEntryOptions`, `GenerateRouteSearchTypesOptions`, `GenerateServerManifestOptions`, `GetStaticPaths`, `HANDOVER_ID`, `HtmlSanitizer`, `IDLE_BLOCKER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `ISRQuery`, `ISR_REVALIDATE_HEADER`, `ISR_REVALIDATE_TAGS_HEADER`, `ISR_STATUS_HEADER`, `InertScriptType`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `InterceptBoundary`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `LoaderResponseControls`, `LoadingEntry`, `Manifest`, `MatchChain`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `MemoryStaticBoundaryCache`, `Meta`, `MetaArgs`, `MetaDescriptor`, `MetaInput`, `MiddlewareOutcome`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateFunction`, `NavigateOptions`, `NavigateSearchOf`, `NavigateTargetInput`, `NonceContext`, `NonceGenerator`, `NonceHeader`, `NonceHeaderContext`, `NonceResolver`, `NotFoundEntry`, `NotFoundScope`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `PendingBoundary`, `PrefetchMode`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `REDIRECT_HEADER`, `RETAIN_HEADER`, `REVALIDATE_HEADER`, `ROOT_ATTRIBUTE`, `ROUTE_GLOBAL`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderAssemblyCache`, `RenderPageInput`, `RenderPageOptions`, `RenderProps`, `RenderStreamOptions`, `RenderedPage`, `RevalidateEndpointOptions`, `RevalidateResult`, `RevalidateTags`, `RevalidateTagsInput`, `RouteEntry`, `RouteMatch`, `RouteMiddleware`, `RouteModule`, `RoutePattern`, `RouteSearch`, `RouterState`, `SERVER_FN_MODULE`, `STATUS_HEADER`, `SanitizedHtml`, `ScriptDescriptor`, `SearchOf`, `ServePublicDirOptions`, `ShouldRevalidate`, `ShouldRevalidateArgs`, `SsrModuleLoader`, `StaticBoundary`, `StaticBoundaryCache`, `StaticBoundaryImportEdge`, `StaticBoundaryRoot`, `StaticCtx`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `StatusPageOptions`, `Submission`, `SubmitOptions`, `TrustedHtml`, `UIMatch`, `UnsafeScriptDescriptor`, `assertCssLoadingCompatible`, `assertRenderAdapterConformance`, `assertStaticBoundaryImports`, `boundaryDescriptors`, `boundaryModeKey`, `buildManifest`, `canonical`, `createClientRouter`, `createCspPolicy`, `createMatcher`, `createMutation`, `createNonceResolver`, `createQueryClient`, `createWebApp`, `defer`, `disableDraft`, `enableDraft`, `enumerateStaticRoutes`, `filePathToPattern`, `filePathToPatterns`, `fontFace`, `fontPreload`, `generateClientEntry`, `generateRouteSearchTypes`, `generateServerManifest`, `getBrowserNavigate`, `gone`, `hashQueryKey`, `isCacheablePage`, `isDraftEnabled`, `jsonLd`, `mergeHeads`, `nifraScriptHashes`, `normalizeCssLoading`, `notFound`, `openGraph`, `previewEndpoint`, `redirect`, `registerBlocker`, `renderPage`, `renderPageResult`, `resolveDynamicBoundaries`, `resolveMeta`, `resolveNavigate`, `resolvePublicPath`, `resolveStaticBoundaries`, `revalidate`, `revalidateEndpoint`, `sanitizeHtml`, `sanitizedHtml`, `searchOf`, `searchOfChain`, `serializeData`, `serializeSearch`, `servePublicDir`, `setBlockerController`, `setBrowserNavigate`, `setSsrModuleLoader`, `ssrModuleLoader`, `startDynamicBoundaries`, `statusPage`, `trustHtml`, `unsafeInlineScript`, `webProjectEvidence`, `withISR`
+`ACTION_GLOBAL`, `Action`, `BOUNDARY_GLOBAL`, `BackendOnly`, `Blocker`, `BlockerController`, `BlockerFunction`, `BlockerLocation`, `BlockerState`, `Boundary`, `BoundaryDescriptor`, `BoundaryError`, `BoundaryMode`, `BoundaryRegistration`, `BoundaryRequestCtx`, `BoundaryState`, `BoundaryStates`, `BoundaryStatus`, `BrowserNavigate`, `CacheStore`, `CachedResponse`, `CdnPurgeOutcome`, `CdnPurgeTarget`, `ClientAction`, `ClientActionArgs`, `ClientActionResult`, `ClientLoader`, `ClientLoaderArgs`, `ClientRequestBody`, `ClientRouteHooks`, `ClientRouter`, `ClientRouterOptions`, `CreateCspPolicyOptions`, `CreateNonceResolverOptions`, `CreateWebAppOptions`, `CspHeaderContext`, `CspPolicy`, `CssLoadingMode`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_CSS_LOADING`, `DEFAULT_DEV_PORT`, `DRAFT_COOKIE`, `Deferred`, `DehydratedState`, `DocumentParts`, `DraftCookieControls`, `DynamicBoundary`, `DynamicBoundaryBatch`, `EnableDraftOptions`, `FetchRouteData`, `Fetcher`, `FetcherState`, `FontDisplay`, `FontFace`, `FontPreloadInput`, `FontSource`, `GenerateClientEntryOptions`, `GenerateRouteSearchTypesOptions`, `GenerateServerManifestOptions`, `GetStaticPaths`, `HANDOVER_ID`, `HtmlSanitizer`, `IDLE_BLOCKER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `ISRQuery`, `ISRStoreOp`, `ISR_REVALIDATE_HEADER`, `ISR_REVALIDATE_TAGS_HEADER`, `ISR_STATUS_HEADER`, `InertScriptType`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `InterceptBoundary`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `LoaderResponseControls`, `LoadingEntry`, `Manifest`, `MatchChain`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `MemoryStaticBoundaryCache`, `Meta`, `MetaArgs`, `MetaDescriptor`, `MetaInput`, `MiddlewareOutcome`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateFunction`, `NavigateOptions`, `NavigateSearchOf`, `NavigateTargetInput`, `NonceContext`, `NonceGenerator`, `NonceHeader`, `NonceHeaderContext`, `NonceResolver`, `NotFoundEntry`, `NotFoundScope`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `PendingBoundary`, `PrefetchMode`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `REDIRECT_HEADER`, `RETAIN_HEADER`, `REVALIDATE_HEADER`, `ROOT_ATTRIBUTE`, `ROUTE_GLOBAL`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderAssemblyCache`, `RenderPageInput`, `RenderPageOptions`, `RenderProps`, `RenderStreamOptions`, `RenderedPage`, `RevalidateEndpointOptions`, `RevalidateResult`, `RevalidateTags`, `RevalidateTagsInput`, `RouteEntry`, `RouteMatch`, `RouteMiddleware`, `RouteModule`, `RoutePattern`, `RouteSearch`, `RouterState`, `SERVER_FN_MODULE`, `STATUS_HEADER`, `SanitizedHtml`, `ScriptDescriptor`, `SearchOf`, `ServePublicDirOptions`, `ShouldRevalidate`, `ShouldRevalidateArgs`, `SsrModuleLoader`, `StaticBoundary`, `StaticBoundaryCache`, `StaticBoundaryImportEdge`, `StaticBoundaryRoot`, `StaticCtx`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `StatusPageOptions`, `Submission`, `SubmitOptions`, `TrustedHtml`, `UIMatch`, `UnsafeScriptDescriptor`, `assertCssLoadingCompatible`, `assertRenderAdapterConformance`, `assertStaticBoundaryImports`, `boundaryDescriptors`, `boundaryModeKey`, `buildManifest`, `canonical`, `createClientRouter`, `createCspPolicy`, `createMatcher`, `createMutation`, `createNonceResolver`, `createQueryClient`, `createWebApp`, `defer`, `disableDraft`, `enableDraft`, `enumerateStaticRoutes`, `filePathToPattern`, `filePathToPatterns`, `fontFace`, `fontPreload`, `generateClientEntry`, `generateRouteSearchTypes`, `generateServerManifest`, `getBrowserNavigate`, `gone`, `hashQueryKey`, `isCacheablePage`, `isDraftEnabled`, `jsonLd`, `mergeHeads`, `nifraScriptHashes`, `normalizeCssLoading`, `notFound`, `openGraph`, `previewEndpoint`, `redirect`, `registerBlocker`, `renderPage`, `renderPageResult`, `resolveChainMeta`, `resolveDynamicBoundaries`, `resolveMeta`, `resolveNavigate`, `resolvePublicPath`, `resolveStaticBoundaries`, `revalidate`, `revalidateEndpoint`, `sanitizeHtml`, `sanitizedHtml`, `searchOf`, `searchOfChain`, `serializeData`, `serializeSearch`, `servePublicDir`, `setBlockerController`, `setBrowserNavigate`, `setSsrModuleLoader`, `ssrModuleLoader`, `startDynamicBoundaries`, `statusPage`, `trustHtml`, `unsafeInlineScript`, `webProjectEvidence`, `withISR`
 
 ## @nifrajs/web-preact
 
@@ -15292,7 +17113,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/webmcp
 
-`AgentCapability`, `AgentCapabilityReference`, `AgentSurfaceAuthoritativeState`, `AgentSurfaceConformanceCase`, `AgentSurfaceConformanceOptions`, `AgentSurfaceConformanceResult`, `AgentSurfaceDescriptor`, `AgentSurfacePrediction`, `AgentSurfacePredictionContext`, `AgentSurfacePredictor`, `AgentSurfaceReconcileContext`, `AgentSurfaceReconciler`, `AgentSurfaceScope`, `AgentSurfaceSnapshot`, `DefineAgentCapabilityOptions`, `ExecutePredictedOptions`, `PredictedExecutionResult`, `PredictionCommitOptions`, `PredictionPatchOperation`, `PredictionStore`, `PredictionStoreEvent`, `PredictionStoreResult`, `PredictionStoreSnapshot`, `ReconciliationMode`, `ToolApproval`, `ToolCallOptions`, `ToolCallResult`, `ToolContract`, `ToolContractOptions`, `ToolError`, `ToolEvidence`, `WebMcpExecutionOptions`, `WebMcpModelContext`, `WebMcpReceipt`, `WebMcpRegistrationFailure`, `WebMcpRegistrationReport`, `WebMcpTarget`, `WebMcpToolDefinition`, `createPredictionStore`, `defineAgentCapability`, `executeAgentCapability`, `executePredicted`, `registerWebMcpTools`, `runAgentSurfaceConformance`, `toWebMcpTool`
+`AgentCapability`, `AgentCapabilityReference`, `AgentSurfaceAuthoritativeState`, `AgentSurfaceConformanceCase`, `AgentSurfaceConformanceOptions`, `AgentSurfaceConformanceResult`, `AgentSurfaceDescriptor`, `AgentSurfacePrediction`, `AgentSurfacePredictionContext`, `AgentSurfacePredictor`, `AgentSurfaceReconcileContext`, `AgentSurfaceReconciler`, `AgentSurfaceScope`, `AgentSurfaceSnapshot`, `DefineAgentCapabilityOptions`, `ExecutePredictedOptions`, `PredictedExecutionResult`, `PredictionCommitOptions`, `PredictionPatchOperation`, `PredictionStore`, `PredictionStoreEvent`, `PredictionStoreResult`, `PredictionStoreSnapshot`, `ReconciliationMode`, `ToolApproval`, `ToolCallOptions`, `ToolCallResult`, `ToolContract`, `ToolContractOptions`, `ToolError`, `ToolEvidence`, `WebMcpExecuteContext`, `WebMcpExecutionOptions`, `WebMcpModelContext`, `WebMcpReceipt`, `WebMcpRegistrationFailure`, `WebMcpRegistrationReport`, `WebMcpTarget`, `WebMcpToolDefinition`, `createPredictionStore`, `defineAgentCapability`, `executeAgentCapability`, `executePredicted`, `registerWebMcpTools`, `runAgentSurfaceConformance`, `toWebMcpTool`
 
 ## @nifrajs/workers