@nifrajs/cli 3.1.0 → 3.3.0

package/docs/llms-full.txt

@@ -958,15 +958,48 @@ function Row({ id }: { id: string }) {
 const anyPending = useFetchers().some((f) => f.snapshot().pending)
 ```
 
-## Nifra - Rendering: SSG & ISR
+## Nifra - Rendering: SSR, streaming, SSG & ISR
 
-> Prerender static routes, enumerate dynamic ones, and cache rendered pages with stale-while-revalidate - on every runtime including the edge.
+> Render critical HTML first, stream deferred data progressively, prerender static routes, and cache rendered pages with stale-while-revalidate - on every runtime including the edge.
 
 Nifra renders on one framework-agnostic seam, so the same app can be server-rendered per
-request (the default), **prerendered** to static files at build (SSG), or cached and served
+request (the default), streamed progressively, **prerendered** to static files at build (SSG), or cached and served
 **stale-while-revalidate** (ISR) - and every strategy works on Bun, Node, Deno, **and**
 the edge.
 
+### Progressive rendering with `defer()`
+
+Keep critical loader data in the first HTML shell and mark slower, non-critical values with
+`defer()`. Nifra flushes the document shell and the adapter's rendered stream first,
+then sends each deferred resolution through `<Await>` without a second data
+fetch. The same protocol works for actions and soft navigations, including NDJSON on the client
+side.
+
+```ts
+import { defer } from "@nifrajs/web"
+
+export async function loader({ api }: LoaderArgs<typeof app>) {
+  return {
+    product: (await api.products.get()).data, // critical: rendered in the first shell
+    reviews: defer(api.reviews.get()),        // non-critical: streamed when ready
+  }
+}
+
+export default function Product(props: { data: LoaderData<typeof loader> }) {
+  return (
+    <>
+      <ProductSummary product={props.data.product} />
+      <Await resolve={props.data.reviews} fallback={<p>Loading reviews…</p>}>
+        {(reviews) => <Reviews items={reviews} />}
+      </Await>
+    </>
+  )
+}
+```
+
+This is request-time progressive SSR/partial rendering. It is distinct from build-time SSG:
+the shell is not a precomputed PPR artifact, and deferred values remain request-scoped.
+
 ### SSG - prerender at build
 
 Opt a static route into prerendering with `export const prerender = true`. Its
@@ -1225,6 +1258,374 @@ if (document.documentElement.hasAttribute("data-nifra-hydrated")) start()
 else document.addEventListener("nifra:hydrated", start, { once: true })
 ```
 
+## Nifra - Islands: the AI-safe interactivity lane
+
+> Add interactivity to a zero-runtime vanilla page with islands - imperative DOM enhancers, no framework runtime, no hydration. Explicit code an AI (or a human) gets right first try: mount, coordinate over a typed bus, always return cleanup.
+
+A `@nifrajs/web-vanilla` page ships zero framework runtime. When one corner needs
+to be interactive, you don&apos;t turn on hydration - you mount an **island**: a
+small, plain-DOM enhancer over a server-rendered element. Explicit imperative code with no
+hidden reactivity - the shape an AI agent (or a human) gets right on the first try.
+
+### Why islands, not hydration
+
+Vanilla routes set `export const hydrate = false` - there is no client framework
+to hydrate with, and that is the point. The five framework adapters give you a reactive
+runtime and pay for it in client JS and in the subtle failure modes (stale closures,
+hydration mismatch, what-re-runs-when) that trip up generated code. Islands take the other
+trade: no runtime, no reactivity to get wrong. You wire the DOM by hand and hand back a
+teardown. Reach for a framework adapter when you genuinely need a stateful app UI; reach for
+islands for widgets on an otherwise-static page.
+
+### Mount an island
+
+Render a `<nifra-island>` marker in your page (props are inline JSON), then
+bundle one entry that calls `mountIslands`. Load it via the route&apos;s
+`islandScripts`.
+
+```ts
+// doc-check: skip - server-rendered island marker (HTML, not a checkable module).
+// In your @nifrajs/web-vanilla page, render the host element with inline JSON props:
+html`<nifra-island data-id="counter" data-props=${JSON.stringify({ start: 0 })}>
+  <output>0</output>
+  <button type="button">+1</button>
+</nifra-island>`
+```
+
+```ts
+// doc-check: skip - browser DOM enhancer, typechecked in @nifrajs/web under its DOM lib.
+import { defineIsland, mountIslands } from "@nifrajs/web/islands"
+
+// defineIsland pins the data-props type; the body is plain imperative DOM. ALWAYS return the
+// teardown for anything you wire - mountIslands calls it on soft-nav (NF-C020 warns if you forget).
+const counter = defineIsland<{ start: number }>((el, props) => {
+  let n = props.start
+  const out = el.querySelector("output")!
+  const onClick = () => { out.textContent = String(++n) }
+  el.querySelector("button")?.addEventListener("click", onClick)
+  return () => el.querySelector("button")?.removeEventListener("click", onClick)
+})
+
+// One bundle entry, loaded via the route's `islandScripts`.
+mountIslands({ counter })
+```
+
+`defineIsland<Props>` is a zero-cost identity helper - its only job is to
+type `props` and `el` so the body needs no cast. Keep the body
+imperative: read the DOM, add listeners, **return the cleanup**. The returned
+function runs on soft-nav teardown; forget it and every navigation leaks the listener -
+`nifra check` flags exactly that as `NF-C020`.
+
+### Coordinate islands with a typed bus
+
+Islands are isolated by design - each enhances one element and shares no state. When two must
+talk (an &ldquo;add to cart&rdquo; button and a cart badge), use a
+`createIslandBus`: one typed channel, created once and closed over by each
+enhancer. No implicit global, so concurrent renders and tests never cross-talk.
+
+```ts
+import { createIslandBus } from "@nifrajs/web/islands"
+
+// One typed channel, created once and closed over by every enhancer that needs it.
+type CartEvents = { "cart:add": { sku: string }; "cart:count": number }
+const bus = createIslandBus<CartEvents>()
+
+const off = bus.on("cart:count", (n) => console.log("cart now has", n, "items"))
+bus.emit("cart:add", { sku: "ABC-1" })
+off() // unsubscribe - also usable directly as an island's cleanup
+```
+
+The bus is synchronous, in-memory, and carries no history - a subscriber sees only events
+emitted after it subscribes. A throwing handler is isolated from the others. Because
+`on()` returns its own unsubscribe, an enhancer whose only job is to listen can
+return it directly as its cleanup:
+
+```ts
+// doc-check: skip - browser DOM enhancer, typechecked in @nifrajs/web under its DOM lib.
+import { createIslandBus, defineIsland, mountIslands } from "@nifrajs/web/islands"
+
+type CartEvents = { "cart:add": { sku: string }; "cart:count": number }
+const bus = createIslandBus<CartEvents>()
+
+// Two islands that never import each other - they meet only on the bus.
+const addButton = defineIsland<{ sku: string }>((el, props) => {
+  const onClick = () => bus.emit("cart:add", { sku: props.sku })
+  el.addEventListener("click", onClick)
+  return () => el.removeEventListener("click", onClick)
+})
+
+let count = 0
+const badge = defineIsland((el) => {
+  const unsubscribe = bus.on("cart:add", () => {
+    count += 1
+    el.textContent = String(count)
+    bus.emit("cart:count", count)
+  })
+  return unsubscribe // the on() unsubscribe IS the cleanup
+})
+
+mountIslands({ addButton, badge })
+```
+
+### Pattern: filter drives results
+
+The same shape scales to any &ldquo;one island changes, another reacts&rdquo; case. Each
+island owns only its own DOM; they meet on the channel, never in a shared store.
+
+```ts
+// doc-check: skip - browser DOM enhancer, typechecked in @nifrajs/web under its DOM lib.
+import { createIslandBus, defineIsland, mountIslands } from "@nifrajs/web/islands"
+
+// filter -> results, one directional channel. The results island owns its own DOM; the filter
+// island owns none of it. No shared store, no reactive tree - a message and two enhancers.
+const bus = createIslandBus<{ "filter:set": string }>()
+
+const filter = defineIsland((el) => {
+  const input = el.querySelector("input")!
+  const onInput = () => bus.emit("filter:set", input.value.toLowerCase())
+  input.addEventListener("input", onInput)
+  return () => input.removeEventListener("input", onInput)
+})
+
+const results = defineIsland((el) =>
+  bus.on("filter:set", (q) => {
+    for (const row of el.querySelectorAll<HTMLElement>("[data-name]")) {
+      const name = row.dataset.name ?? ""
+      row.hidden = q !== "" && !name.toLowerCase().includes(q)
+    }
+  }),
+)
+
+mountIslands({ filter, results })
+```
+
+### Load strategies
+
+A marker&apos;s `data-strategy` defers its enhancer: `load` (default),
+`idle`, `visible` (mount when it scrolls into view), or a
+`media` query. An island with no matching enhancer, or an invalid strategy, stays
+inert server-rendered HTML - forward-compatible, never a runtime error.
+
+## Nifra - nano: explicit reactivity for small apps
+
+> nano is the AI-safe small-app lane: signal + computed(fn, [deps]) + keyed bindList, no VDOM, no auto-tracking. Every reactive edge is a visible call, so its three mistakes are static lints (NF-C021/C022/C023) with a fix recipe - the same closed loop that makes the backend AI-safe, now on the frontend.
+
+`@nifrajs/web/nano` is the middle lane between a static
+[island](/docs/islands) and a full framework adapter. It gives you a signal, a
+derived `computed`, and a keyed list - enough to build a small app with local
+state a human edits - and nothing else. No virtual DOM, no template compiler, no
+auto-tracking. Every reactive edge is a call you write, which is exactly what lets a tool
+catch the mistakes before runtime.
+
+### Why a fourth lane
+
+A framework fails generated code not because it is unfamiliar but because its reactivity is
+_implicit_: an effect silently tracks what it read, a stale closure captures the wrong
+value, a render mismatches hydration - all silent, all runtime. Preact fixes the
+**size** of that model (3 KB) but copies its footguns faithfully. nano
+fixes the **failure model** for the small-app band: dependencies are an explicit
+array, list keys are a required argument, cleanups are a returned value. Each of those is a
+thing a static check can see. Reach for nano when a page needs local state and a keyed list;
+reach for a [framework adapter](/docs/frameworks) the moment you need client
+routing, nested view state, or suspense.
+
+### Signals and computed
+
+A `signal` holds a value; `.get()` reads it and `.set(...)`
+replaces it (deduped with `Object.is`). A `computed` derives a value and
+declares its sources as an explicit deps array - it recomputes when a listed source changes,
+never by magic. Both are synchronous and framework-free.
+
+```ts
+import { signal, computed } from "@nifrajs/web/nano"
+
+// State is a signal: reads are .get(), writes are .set(...). Every edge is a call you can see.
+const count = signal(0)
+
+// Derived state declares its dependencies EXPLICITLY - the array is the whole contract. It
+// recomputes when (and only when) a listed source changes. Object.is-deduped, like signal.
+const doubled = computed(() => count.get() * 2, [count])
+
+const off = doubled.subscribe((v) => console.log("doubled is now", v))
+count.set(5) // logs: doubled is now 10
+off()        // unsubscribe
+```
+
+The deps array is the whole contract, and its one failure mode is catchable: a
+`computed` whose body reads a signal the array omits will never recompute when that
+signal changes. `nifra check` flags exactly that as `NF-C023` - the
+check reads which signals the body calls `.get()` on and compares them to the
+array. A framework&apos;s auto-tracked effect gives a tool nothing to compare, which is why
+the equivalent lint elsewhere is a best-effort warning, not a gate.
+
+### Bind a signal to the DOM
+
+`bind` is the one-value edge: it applies your function immediately and on every
+change, and returns a disposer. **Collect the disposer.** A bare
+`bind(...)` whose return value is discarded leaks its subscription on soft-nav -
+`nifra check` flags it as `NF-C021`.
+
+```ts
+// doc-check: skip - browser DOM enhancer, typechecked in @nifrajs/web under its DOM lib.
+import { signal, bind } from "@nifrajs/web/nano"
+
+const label = signal("hello")
+
+// bind applies immediately AND on every change; it returns the disposer. COLLECT it - a bare
+// bind(...) that drops its return leaks the subscription on soft-nav (nifra check flags NF-C021).
+const off = bind(document.querySelector("h1")!, label, (el, v) => { el.textContent = v })
+label.set("world") // the <h1> updates synchronously
+// ...on teardown: off()
+```
+
+### Keyed lists with bindList
+
+`bindList` keeps a container&apos;s children in sync with an array by key - a keyed
+reconcile like a framework&apos;s list diff, but you spell the key out. Add, remove, and
+reorder reuse the matching node (preserving focus and scroll) instead of rebuilding the list.
+Key by a **stable id** on the item; keying by the array index reuses the wrong
+node on reorder, and `nifra check` flags it as `NF-C022`.
+
+```ts
+// doc-check: skip - browser DOM enhancer, typechecked in @nifrajs/web under its DOM lib.
+import { signal, bindList } from "@nifrajs/web/nano"
+
+interface Todo { id: string; text: string; done: boolean }
+const todos = signal<Todo[]>([])
+
+// bindList keeps a container's children in sync with an array by KEY - a keyed reconcile, like a
+// framework's list diff, but explicit. Add/remove/reorder reuse the right node instead of rebuilding.
+const off = bindList(todos, document.querySelector("ul")!, {
+  key: (t) => t.id, // a STABLE id on the item. Keying by the array index is NF-C022 - reorder breaks.
+  create: (t) => { const li = document.createElement("li"); li.dataset.id = t.id; return li },
+  update: (li, t) => { li.textContent = t.text; li.classList.toggle("done", t.done) },
+})
+
+todos.set([...todos.get(), { id: crypto.randomUUID(), text: "buy milk", done: false }])
+// ...on teardown: off()
+```
+
+### Async state with resource
+
+`resource(fetcher, [deps])` is nano&apos;s answer to &ldquo;suspense&rdquo; - an
+async cell whose value is an explicit `&#123; status, value, error &#125;` union.
+It runs the fetcher immediately and again whenever a declared dep changes, and it handles the
+two things people get wrong by hand: the fetcher receives an `AbortSignal`, and a
+superseded request is aborted with its late result dropped, so the newest fetch always wins -
+no stale-response flicker. There is no thrown promise and no magic boundary; it is a value you
+read or bind like any other.
+
+```ts
+import { signal, resource } from "@nifrajs/web/nano"
+
+const userId = signal(1)
+
+// resource(fetcher, [deps]) is an async cell: it fetches immediately and again whenever a declared
+// dep changes. The fetcher gets an AbortSignal; a superseded fetch is aborted and its late result
+// dropped, so the newest request always wins - no stale-response flicker to hand-guard.
+const user = resource(async (sig) => {
+  const res = await fetch(`/api/users/${userId.get()}`, { signal: sig })
+  return (await res.json()) as { name: string }
+}, [userId])
+
+// The value is an explicit union - status is "pending" | "error" | "ready", never a secret undefined.
+const off = user.subscribe((s) => {
+  if (s.status === "ready") console.log("got", s.value.name)
+})
+userId.set(2) // refetches; the deps array is what NF-C023 checks against the fetcher's .get() reads
+// ...on teardown: off()
+```
+
+The deps array is checked exactly like `computed`: a `resource` whose
+fetcher reads a signal the array omits won&apos;t refetch when it changes, and
+`nifra check` flags it as `NF-C023`. Bind it to the DOM with
+`bindResource`, which dispatches on `status` - one handler per state,
+`ready` required, so a still-loading value can never render as a stray
+`undefined`.
+
+```ts
+// doc-check: skip - browser DOM enhancer, typechecked in @nifrajs/web under its DOM lib.
+import { signal, resource, bindResource } from "@nifrajs/web/nano"
+
+const userId = signal(1)
+const user = resource(async (sig) => {
+  const res = await fetch(`/api/users/${userId.get()}`, { signal: sig })
+  return (await res.json()) as { name: string }
+}, [userId])
+
+// bindResource dispatches on status - one handler per state, ready required. Like bind it returns a
+// disposer (a bare bindResource(...) that drops it is NF-C021).
+const off = bindResource(document.querySelector("[data-user]")!, user, {
+  pending: (el) => { el.textContent = "Loading…" },
+  ready: (el, u) => { el.textContent = u.name },
+  error: (el) => { el.textContent = "Could not load user" },
+})
+// ...on teardown: off()
+```
+
+### nano inside an island
+
+nano owns state and DOM edges; an [island](/docs/islands) owns mount and teardown.
+Put the signals in the enhancer, collect every disposer, and return one cleanup that calls
+them all. Scaffold this shape with
+`nifra_scaffold &#123; path, variant: "stateful" &#125;` on a vanilla
+project - it emits the golden pattern below.
+
+```ts
+// doc-check: skip - browser DOM enhancer, typechecked in @nifrajs/web under its DOM lib.
+import { defineIsland, mountIslands } from "@nifrajs/web/islands"
+import { signal, computed, bind, bindList } from "@nifrajs/web/nano"
+
+interface Todo { id: string; text: string; done: boolean }
+
+// nano lives INSIDE an island - the island owns mount/teardown, nano owns the state and the DOM edges.
+const todos = defineIsland<{ items: Todo[] }>((el, props) => {
+  const items = signal<Todo[]>(props.items)
+  const remaining = computed(() => items.get().filter((t) => !t.done).length, [items])
+
+  // Collect every disposer; the island's cleanup calls them all (this is what NF-C021 protects).
+  const cleanups: Array<() => void> = []
+  cleanups.push(bind(el.querySelector("[data-count]")!, remaining, (n, v) => {
+    n.textContent = String(v) + " left"
+  }))
+  cleanups.push(bindList(items, el.querySelector("[data-list]")!, {
+    key: (t) => t.id,
+    create: (t) => { const li = document.createElement("li"); li.dataset.id = t.id; return li },
+    update: (li, t) => { li.textContent = t.text; li.classList.toggle("done", t.done) },
+  }))
+
+  const add = (text: string) =>
+    items.set([...items.get(), { id: crypto.randomUUID(), text, done: false }])
+  void add
+
+  return () => { for (const off of cleanups) off() }
+})
+
+mountIslands({ todos })
+```
+
+### The three checks
+
+nano&apos;s explicitness is the whole point: because each reactive edge is a visible call, its
+three mistakes are static lints with a fix recipe - the same closed loop (`scaffold`
+&rarr; `check` &rarr; `fix` &rarr; `verify`) that makes the
+backend AI-safe, now on the frontend.
+
+-
+`NF-C021` - a `bind`/`bindList` whose disposer is
+discarded. Collect it; call it on teardown.
+
+-
+`NF-C022` - a `bindList` keyed by the array index. Key by a stable id.
+
+-
+`NF-C023` - a `computed` that reads a signal its deps omit. Add it to
+the deps array.
+
+All three _warn_ - a false positive must never fail a build - and each carries a fix
+recipe an agent can apply. Where nano stops (client routing, nested views, suspense), stop
+adding nano and reach for `@nifrajs/web-preact` or another framework adapter.
+
 ## Nifra - Streaming
 
 > Streaming SSR, Suspense, and defer() in Nifra - on every runtime including the edge.
@@ -2967,6 +3368,7 @@ const image = createImageHandler({
   root: "./public",                          // local sources resolve under here (traversal+symlink guarded)
   allowedOrigins: ["https://cdn.example"],   // remote sources: allowlist only (omit ⇒ none)
   // maxWidth, maxSourceBytes, maxSourcePixels, concurrency, cacheMaxAge - all tunable
+  // immutable: true, // only for content-versioned source URLs
 })
 
 // mount it in your router:
@@ -2989,9 +3391,10 @@ probe), and a concurrency semaphore bounding the CPU-heavy codec work.
 
 -
 **Correct + cacheable.** Never upscales past the intrinsic width; negotiates WebP via
-`Accept` (with `Vary: Accept`); serves
-`Cache-Control: …, immutable` + a strong `ETag` computed _before_ any
-decode, so a conditional `If-None-Match` short-circuits the whole pipeline.
+`Accept` (with `Vary: Accept`); and hashes the emitted bytes for a strong
+`ETag`, so a changed source at the same URL cannot receive a false `304`.
+The mutable-safe default is a one-hour `max-age`; opt into `immutable` only
+when every source URL is content-versioned.
 
 The handler reads the filesystem, so its _local-source_ path targets **Node/Bun servers**
 - but the codec itself is a pluggable `ImageBackend`, so it runs anywhere (see below).
@@ -3819,6 +4222,48 @@ export const vitePlugins = [react()]          // dev HMR (Fast Refresh)
 //   define        = { __VUE_OPTIONS_API__: "true", ... }   // Vue feature flags
 ```
 
+### Tailwind to StyleX
+
+Nifra includes a conservative codemod for moving static Tailwind classes to StyleX. It is a dry
+run by default, so inspect the proposed edits first:
+
+Supported static `className` attributes become `stylex.props(...)` calls
+backed by a local `stylex.create(...)` table. Responsive breakpoints and
+element-local pseudo-classes such as `hover:` are supported. Dynamic class
+expressions, arbitrary values, parent-dependent variants, and unknown utilities stay unchanged
+and are reported with file/line evidence. A non-zero exit status means manual migration issues
+remain.
+
+StyleX compilation is native to Nifra&apos;s Bun pipeline. Install the runtime and compiler peers,
+then register both the browser and SSR transforms:
+
+```ts
+# Install the runtime and the optional compiler peers.
+bun add @stylexjs/stylex
+bun add -d @babel/core @stylexjs/babel-plugin @babel/plugin-syntax-flow \
+  @babel/plugin-syntax-jsx @babel/plugin-syntax-typescript
+```
+
+```ts
+// nifra.config.ts - Bun's client and SSR build transforms.
+import { stylexBunPlugin } from "@nifrajs/web/plugins/stylex"
+
+export const clientPlugins = [stylexBunPlugin("dom")]
+export const serverPlugins = [stylexBunPlugin("ssr")]
+```
+
+If the project intentionally uses Vite, add the Vite adapter alongside its existing Vite
+transforms. Nifra will use Vite when `vitePlugins` are the app&apos;s only transforms:
+
+```ts
+// doc-check: skip - requires the third-party Vite React plugin
+// If the app intentionally uses Vite, keep StyleX in vitePlugins.
+import react from "@vitejs/plugin-react"
+import { stylexVite } from "@nifrajs/web/plugins/stylex"
+
+export const vitePlugins = [react(), stylexVite()]
+```
+
 ### Scope
 
 `nifra build` defaults to a self-hosted Bun server. Use `--target node`,
@@ -3828,7 +4273,7 @@ the command printed by the build.
 
 ## Nifra - Coding agents
 
-> An MCP server that lets an agent build a Nifra app and then prove it: verified docs and examples, a drift gate to fix against, real requests to check behaviour, and a ladder that says what the project actually holds.
+> Nifra's agent layer: live MCP tools, bounded repairable turns, native approvals, resumable evidence, content-free browser views, capability registry, decision inbox, Run Studio, A2A, and AG-UI.
 
 Nifra ships an MCP server. It is not a documentation lookup bolted onto a framework: an agent
 can read the project, learn the real API, run actual requests against the backend it just
@@ -3912,6 +4357,8 @@ nifra_check             # typecheck + lints, each with a structured fix
 nifra_fix               # applies the mechanical ones
 nifra_run    {request}  # a real request through the backend: status, headers, parsed body
 nifra_render {path}     # SSR a page route, returns the HTML
+nifra_inspect {port}    # recent dev-server request traces: status, duration, ISR hit/miss
+nifra_explain {error}   # turn a failure into a structured diagnostic and fix
 nifra_test              # bun test, bounded structured results
 
 # 4. What does it now prove?
@@ -3993,8 +4440,8 @@ nifra levels --min 1
 
 ### Building agent features, not just serving them
 
-The tools above let an agent work on your app. Three packages are for the opposite case, where
-the app you are building is itself an AI feature.
+The tools above let an agent work on your app. Nifra also provides provider-neutral building
+blocks for the opposite case, where the app you are building is itself an AI feature.
 
 **
 `@nifrajs/prompt`
@@ -4036,6 +4483,139 @@ serves a SQLite database as its own MCP server, fail-closed: allowlisted schema
 default, and read-only queries only when you opt in, with plan verification. Handing a model a
 database connection is not the same as handing it a query tool, and this is the second one.
 
+### Run a coding agent
+
+`@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.
+
+```ts
+bun add @nifrajs/coding-agent @nifrajs/pi
+
+# Interactive, one-shot, JSON, and local RPC modes are available.
+bunx nifra-agent --backend pi
+bunx nifra-agent --backend pi --message "run the checks and explain failures"
+```
+
+The public host keeps live queues and captured evidence bounded, filters verification process
+environments, and treats extensions as an explicit opt-in. Post-turn `check`,
+`assure`, or `test` gates emit `verification.completed` and
+`repair.required`; when enabled, the host sends a bounded repair prompt and reruns
+the gate until it passes or the attempt cap is reached. The local process adapter and extension
+worker are crash-containment helpers, not hostile-code sandboxes.
+
+```ts
+# Post-turn gates are opt-in. A failed gate becomes bounded repair work.
+bunx nifra-agent --backend pi --message "implement the change" \
+  --verify-after-turn check,assure --max-repair-attempts 2
+
+# Set --max-repair-attempts 0 for observe-only verification.
+```
+
+### Native approval protocol
+
+`@nifrajs/coding-agent` can pause a native tool call at the decision boundary and
+emit `approval.required` with an opaque approval id, action, capability, and bounded
+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.
+
+### Expose the same agent to other clients
+
+`@nifrajs/a2a` mounts an A2A 1.0 card and JSON-RPC/SSE binding.
+`@nifrajs/ag-ui` mounts the AG-UI event stream. Both drive the same bounded runner,
+compose step evidence with telemetry, and support typed human-in-the-loop continuation. Model
+ports, state stores, capabilities, and approval transports are injected per request.
+
+```ts
+import { server } from "@nifrajs/core"
+import { mountA2A } from "@nifrajs/a2a"
+import { mountAgUI } from "@nifrajs/ag-ui"
+import type { AgentPorts } from "@nifrajs/agent"
+import { agent } from "./agent"
+
+declare const myModelPort: AgentPorts["model"]
+declare const myStateStore: NonNullable<AgentPorts["state"]>
+
+const app = server()
+const ports = () => ({
+  model: myModelPort,
+  capabilities: ["search.read"],
+  state: myStateStore, // scope this to the request subject
+})
+
+mountA2A(app, {
+  agent,
+  card: { url: "https://api.example.com/a2a", version: "1.0.0" },
+  ports,
+})
+mountAgUI(app, { agent, ports })
+
+// A2A: GET the card, POST JSON-RPC, optional SSE streaming.
+// AG-UI: POST RunAgentInput, receive the event stream over SSE.
+```
+
+These mounts deliberately do not authenticate callers: put the route behind your application's
+auth and authorization middleware, and scope every injected port to the request subject.
+
+### Browser views and the Workbench
+
+`@nifrajs/agent-app` is a backend-free browser SDK for negotiated commands, ordered
+and resumable event streams, approvals, handoffs, and Run Studio projections. It negotiates
+optional features including `approvals`, `checkpoint`,
+`fork`, `handoff`, `inbox`, `reload`,
+`resume`, and `workflows`, so a browser can degrade deliberately when a
+host does not offer one. Its public views contain structure - statuses, counters, coordinates,
+and error codes - rather than prompts, tool payloads, model output, or filesystem paths. The
+optional Workbench uses that same surface: run
+`bun run --filter '@nifrajs/workbench' dev -- --cwd /path/to/project` for the local
+browser client.
+
+```ts
+import { AgentAppClient, HttpAgentTransport } from "@nifrajs/agent-app"
+
+declare function currentToken(): string
+declare function render(view: unknown): void
+
+const client = new AgentAppClient(new HttpAgentTransport({
+  endpoint: "http://127.0.0.1:8787",
+  authorize: () => currentToken(), // minted per request; never stored by the transport
+}))
+
+const session = await client.createSession()
+for await (const view of client.send("summarize the diff")) {
+  render(view) // content-free status, counts, coordinates, and error codes
+}
+```
+
+### Capability registry, decision inbox, and Run Studio
+
+The Workbench's `registry.list` view shows content-free identity cards for admitted
+capabilities: kind, name, version, schema digest, required capability tokens, and approval,
+retry, idempotency, and isolation classes. It never renders a prompt, input schema, tool
+payload, model output, or filesystem path.
+
+The `inbox` feature lists pending approval and handoff boundaries by exact structural
+coordinate - run, node, capability, child vector, request id, and expiry. Every approve, deny,
+assign, resolve, or cancel command carries that coordinate, so stale, mismatched, or expired
+decisions are refused by the host. `run.studio` projects the same bounded evidence
+into a run graph, retry/recovery timeline, eval comparison, and deterministic fault-injection
+view. These are presentation-safe views: content stays in the host.
+
+### Evidence, streaming, and telemetry
+
+`@nifrajs/agent` runs bounded typed turns with tool contracts, budgets, approvals,
+resumable token-only evidence, model deltas, and a transient shared-state channel. Add an
+`evidenceLog` to the HTTP seams for SSE replay after a dropped connection; replay
+resumes evidence and never re-executes the turn. The additive run-lifecycle contract supplies
+content-free snapshots, ordered evidence refs, feature negotiation, handoff state, and cursor
+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.
+
 ### Projects without a web config
 
 A backend-only project - the shape `create-nifra`'s default template produces - has
@@ -7457,21 +8037,41 @@ isolated fixtures and a test database. Never point a contract laboratory at prod
 
 ## Nifra - Types-first architecture
 
-> One schema is the single source of truth: it drives runtime validation, inferred TypeScript types, the no-codegen typed client, an OpenAPI document, and the MCP contract your agents read.
+> Nifra infers route types from path literals and handlers automatically, with optional Standard Schemas for validation, explicit contracts, OpenAPI, and agent-readable APIs.
+
+Nifra starts with automatic inference. A route's path literal, handler context, and return
+value produce its TypeScript surface; add a Standard Schema when you need runtime validation,
+coercion, or an explicit request/response contract. The same server type then drives the
+no-codegen client and the agent-readable API surface.
+
+### Inline inference first
+
+The chainable builder is fully type-inferred. Path parameters are parsed from the route
+pattern, handler context is typed automatically, and plain return values become the success
+response seen by the client. This is the quick-start style, similar to Elysia's inline route
+inference.
 
-In Nifra a single schema is the **source of truth**. The same definition drives runtime
-validation, inferred TypeScript types, the no-codegen typed client, an OpenAPI document, and
-the contract your coding agents read - so the five never drift apart.
+```ts
+import { server } from "@nifrajs/core/server"
+
+export const app = server()
+  .get("/users/:id", (c) => ({ id: c.params.id, name: "Ada" }))
+  // c.params.id is inferred from the path; the return type becomes the client response.
+  .post("/users", () => ({ created: true }))
+
+// No schema, annotation, or codegen is required for the route types.
+```
 
-### One schema
+### Schemas at the trust boundary
 
-Define request inputs and the response shape once with `t`. Nothing here is
-framework-specific; it's a plain object you attach to a route.
+Attach a Standard Schema when inputs must be validated before the handler runs, or when you
+want an explicit response contract. Path params are already inferred from `:id`;
+the `params` schema below adds runtime constraints/coercion as well.
 
 ```ts
 import { t } from "@nifrajs/schema"
 
-// One contract, defined once. Everything below is derived from it.
+// Add a schema when the boundary needs runtime validation or a declared contract.
 export const GetUser = {
   params: t.object({ id: t.string() }),
   response: t.object({
@@ -7501,9 +8101,10 @@ export const app = server().get("/users/:id", GetUser, (c) => {
 
 ### Inferred types
 
-The same schema types the handler: `c.params.id` is `string`, and the
-return value is checked against `response`. Change the schema and the handler
-stops compiling until it matches - types and validation can't disagree.
+Without a schema, `c.params.id` is still `string` and the handler return
+is captured automatically. With a schema, its output types the handler and its declared
+`response` constrains what the handler may return. Change either the route or the
+contract and the typed client follows at compile time.
 
 ### The typed client
 
@@ -7525,6 +8126,16 @@ if (res.ok) {
 }
 ```
 
+### Contract-first when the surface must be separate
+
+Inline inference is the default. If the API needs to be shared, versioned, or implemented by
+more than one service, declare it with `defineContract` and connect handlers with
+`implement`. That keeps the contract type available without importing a server
+implementation into the client.
+
+See [Framework contract](/docs/contract) for the decoupled form and its scaling
+guidance.
+
 ### OpenAPI
 
 The `openapi()` middleware builds an OpenAPI 3.1 document from your registered
@@ -7674,6 +8285,222 @@ level that regressed comes back with the reason it broke.
 
 # Package reference (READMEs)
 
+## @nifrajs/a2a
+
+Mount a nifra agent as an [Agent2Agent (A2A)](https://a2a-protocol.org) protocol server. The agent card is served on GET, the A2A 1.0 JSON-RPC binding on POST: `SendMessage` runs one bounded agent turn, `SendStreamingMessage` streams step evidence over SSE, `GetTask` projects the stored turn state.
+
+A protocol bridge over [`@nifrajs/agent`](../agent) - the request body reuses core's single bounded, prototype-guarded trust boundary, and the model, durable state store, and approval transport are injected per request through the same `ports` factory `mountAgent` uses. Dependency-free beyond the two nifra peers.
+
+## Install
+
+```bash
+bun add @nifrajs/a2a @nifrajs/agent
+```
+
+## Mount
+
+```ts
+import { server } from "@nifrajs/core"
+import { mountA2A } from "@nifrajs/a2a"
+import { agent } from "./agent" // an AgentDefinition
+
+const app = server()
+mountA2A(app, {
+  agent,
+  card: { url: "https://api.example.com/a2a", version: "1.0.0" },
+  ports: (c) => ({
+    model: myModelPort,        // scope to the request subject
+    capabilities: ["search.read"],
+    state: myStateStore,       // required for GetTask and resume
+  }),
+})
+// GET  /.well-known/agent-card.json  - the agent card
+// POST /a2a                          - SendMessage | SendStreamingMessage | GetTask
+```
+
+## Task mapping
+
+One A2A task is one agent turn: `taskId` is the runner's `turnId`.
+
+| Run result | Task state |
+| --- | --- |
+| completed with output | `TASK_STATE_COMPLETED` + an `output` artifact |
+| completed with a typed error | `TASK_STATE_FAILED` (error in `metadata`) |
+| suspended (approval, budget, model, max turns) | `TASK_STATE_INPUT_REQUIRED` |
+| suspended (cancelled) | `TASK_STATE_CANCELED` |
+
+Agent input is `message.metadata.input` when present, otherwise the first `text` part. Structured output returns as a `text` part carrying JSON.
+
+## Human-in-the-loop resume
+
+A suspended task's status message carries the pending continuation in `metadata`. Send it back to continue the same task - the runtime keeps state token-only, so a suspended tool's input must be replayed in `continuation.input`:
+
+```jsonc
+{
+  "jsonrpc": "2.0", "id": 2, "method": "SendMessage",
+  "params": {
+    "message": {
+      "messageId": "m2", "role": "ROLE_USER", "parts": [],
+      "taskId": "<task id from the suspension>",
+      "metadata": {
+        "input": { "prompt": "go" },
+        "resume": {
+          "continuation": { "kind": "approval", "tool": "search.read", "effectId": "…", "input": { "q": "…" } },
+          "approval": { "granted": true }
+        }
+      }
+    }
+  }
+}
+```
+
+Cross-request registries (cancellation, subscription fan-out, push notifications) are deliberately out of scope for the stateless seam; those spec methods answer `UnsupportedOperationError` (-32004).
+
+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.
+
+## Docs
+
+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`.
+
+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.
+
+A protocol bridge over [`@nifrajs/agent`](../agent) - the request body reuses core's single bounded, prototype-guarded trust boundary, and the model, durable state store, and approval transport are injected per request through the same `ports` factory `mountAgent` uses. Dependency-free beyond the two nifra peers.
+
+## Install
+
+```bash
+bun add @nifrajs/ag-ui @nifrajs/agent
+```
+
+## Mount
+
+```ts
+import { server } from "@nifrajs/core"
+import { mountAgUI } from "@nifrajs/ag-ui"
+import { agent } from "./agent" // an AgentDefinition
+
+const app = server()
+mountAgUI(app, {
+  agent,
+  ports: (c) => ({
+    model: myModelPort,        // scope to the request subject
+    capabilities: ["search.read"],
+    state: myStateStore,       // required for resume
+  }),
+})
+// POST /agui - RunAgentInput in, AG-UI events out (SSE)
+```
+
+## Event mapping
+
+| Runner | AG-UI events |
+| --- | --- |
+| run starts | `RUN_STARTED`, then `CUSTOM { name: "nifra.turn" }` announcing the turn id |
+| tool evidence | `TOOL_CALL_START` / `TOOL_CALL_END`, then `TOOL_CALL_RESULT` whose `content` is the token-only outcome `{ "outcome": "committed" \| "failed" \| "denied", "code"? }` |
+| model, approval, budget, state evidence | `STEP_STARTED` / `STEP_FINISHED` |
+| model text deltas | live `TEXT_MESSAGE_START` / `_CONTENT` (see streaming below) |
+| model reasoning deltas | `REASONING_START` / `REASONING_MESSAGE_START` / `_CONTENT` / `_END` / `REASONING_END` |
+| model tool-args deltas | provisional `TOOL_CALL_START` + `TOOL_CALL_ARGS`, closed by the call's tool evidence |
+| shared state | `STATE_SNAPSHOT` on the seed and `STATE_DELTA` (RFC 6902 ops) per patch (see below) |
+| model usage deltas | summed per `(provider, model)` into the `usage: TokenUsage[]` array on `RUN_FINISHED` |
+| completed output | `TEXT_MESSAGE_START` / `_CONTENT` / `_END` (unless text was streamed), an optional `MESSAGES_SNAPSHOT` (see below), then `RUN_FINISHED` with `result` and `outcome: { "type": "success" }` |
+| completed with a typed error | `RUN_ERROR` |
+| suspended | `CUSTOM { name: "nifra.pending" }` with the continuation, then `RUN_FINISHED` with `outcome: { "type": "interrupt", "interrupts": [...] }` |
+
+Evidence-derived events carry the evidence `timestamp`. The runtime is token-only by design - `TOOL_CALL_RESULT` reports the outcome and error code, never the tool's payload.
+
+Agent input is `forwardedProps.input` when present, otherwise the content of the last `role: "user"` message.
+
+## Token streaming
+
+A model port that calls the request's optional `onDelta` callback (see `@nifrajs/agent`'s `AgentModelDelta`) streams live:
+
+- `{ kind: "text", text }` opens a `TEXT_MESSAGE` and streams each chunk as `TEXT_MESSAGE_CONTENT`. When any text was streamed, the terminal text block is suppressed - the streamed text IS the assistant message, so a streaming port must stream all user-visible text. A non-streaming port keeps the single terminal block; nothing changes for it.
+- `{ kind: "reasoning", text }` streams a `REASONING_*` message.
+- `{ kind: "tool-args", name?, argsText }` opens a provisional `TOOL_CALL_START` (id `<turnId>:call:<n>`) and streams `TOOL_CALL_ARGS`. The tool evidence that follows closes the same call - `TOOL_CALL_END` plus the token-only `TOOL_CALL_RESULT` - instead of opening a second one.
+- `{ kind: "usage", provider?, model?, inputTokens?, ... }` never becomes a frame. The counts are summed per `(provider, model)` across the run's model decisions and stamped as the spec `usage: TokenUsage[]` array on the terminal `RUN_FINISHED` (success and interrupt alike); non-finite figures are ignored.
+
+Each stream closes when a different delta kind starts, when tool evidence lands, or at the end of the run. Deltas are transient observer data: a `Last-Event-ID` replay carries evidence frames and the stored, unsuppressed terminal events only - the stored `RUN_FINISHED` keeps its `usage`.
+
+## Shared state
+
+The `ports` factory receives `(c, run)`; `run.sharedState` is the run's `AgentSharedState` channel and `run.turnId` the resolved turn id. `body.state` seeds the document and is announced with an upfront `STATE_SNAPSHOT`; every `patch` from a port or tool executor streams as `STATE_DELTA` carrying the RFC 6902 ops. A first patch on an unseeded document announces itself as a `STATE_SNAPSHOT` instead of a delta against a base the client never saw. The channel is per-run and transient - nothing in it is persisted.
+
+```ts
+mountAgUI(app, {
+  agent,
+  ports: (c, run) => ({
+    model: myStreamingModelPort(run.sharedState), // patch progress as the run advances
+    capabilities: ["search.read"],
+  }),
+})
+```
+
+With `emitMessagesSnapshot: true`, a successful run also emits `MESSAGES_SNAPSHOT` - the request's `messages` echoed back with the assistant output message appended - before `RUN_FINISHED`. It is off by default: the snapshot echoes client message payloads, and terminal events persist to the evidence log when one is configured.
+
+## Human-in-the-loop resume
+
+A suspended run finishes with `outcome: { "type": "interrupt", "interrupts": [interrupt] }` where the interrupt is:
+
+```jsonc
+{
+  "id": "<turnId>",
+  "reason": "approval",                    // approval | budget | model | cancelled | max_turns
+  "toolCallId": "<effectId>",              // present for tool suspensions
+  "responseSchema": { /* JSON Schema for the resume payload */ },
+  "metadata": { "turnId": "…", "continuation": { "kind": "approval", "tool": "…", "effectId": "…" } }
+}
+```
+
+Resume with the AG-UI `resume` array. The runtime keeps state token-only - it holds no interrupt registry - so the payload must echo `metadata.continuation`, with the suspended tool's input replayed in `continuation.input`:
+
+```jsonc
+{
+  "threadId": "thread-1", "runId": "run-2", "messages": [],
+  "forwardedProps": { "input": { "prompt": "go" } },
+  "resume": [{
+    "interruptId": "<interrupt id>",
+    "status": "resolved",                  // "cancelled" without an approval resumes as a denial
+    "payload": {
+      "continuation": { "kind": "approval", "tool": "search.read", "effectId": "…", "input": { "q": "…" } },
+      "approval": { "granted": true }
+    }
+  }]
+}
+```
+
+The pre-interrupt form - the same `{ continuation, approval? }` object in `forwardedProps.resume` plus `forwardedProps.turnId` - keeps working. A resume that fails validation is ignored and the POST starts a fresh run.
+
+## Resumable streams
+
+Pass an `evidenceLog` to make a dropped SSE connection resumable. Evidence-derived frames then
+carry SSE `id: <seq>`; a client reconnects by re-POSTing the same body with a `Last-Event-ID`
+header and receives the missed events, rejoining a still-running turn live or replaying the stored
+terminal events - the run is never re-executed.
+
+```ts
+import { createMemoryAgentEvidenceLog } from "@nifrajs/agent/events"
+
+mountAgUI(app, { agent, ports, evidenceLog: createMemoryAgentEvidenceLog() })
+```
+
+The in-memory log is the single-process dev/test reference; a durable, multi-process log is an
+adapter implementing the same `AgentEvidenceLog` interface.
+
+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.
+
+## Docs
+
+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`.
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).
+
 ## @nifrajs/agent
 
 Provider-neutral, typed, resumable agent turns over Nifra tool contracts.
@@ -7694,6 +8521,42 @@ const result = await runAgent(definition, { value: input }, ports, {
 The public in-memory adapters are for local development and tests. Durable state, provider
 credentials, and operated policy remain adapter concerns.
 
+Gateway and deployment contracts are deliberately provider-neutral. Retry, fallback, budget,
+deadline, workspace, and hostile-code isolation claims are admitted only from a host-approved
+capability report. The local and replay reference profiles are not hostile-code sandboxes, and no
+public package loads provider credentials or promises durable execution.
+
+Several telemetry consumers can observe the same run: `combineAgentTelemetry(a, b, ...)` fans step
+evidence out to every port in order, so an SSE evidence stream and an exporter (for example
+`@nifrajs/agent-telemetry`'s `traceAgentRun`) compose instead of displacing each other. The HTTP
+seams (`mountAgent`, `@nifrajs/a2a`, `@nifrajs/ag-ui`) compose their streaming evidence with any
+telemetry port supplied through `ports`.
+
+A model port can stream: when the caller wires an `AgentDeltaSink` into `ports.deltas`, every model
+request carries an optional `onDelta` callback the port may call per chunk - user-visible text,
+reasoning text, the raw argument text of the tool call being formed, or a `usage` delta reporting
+the decision's settled token counts (optionally attributed to a provider and model, for observers
+to sum across the run). Deltas are transient
+observer data for live UIs (`@nifrajs/ag-ui` projects them onto `TEXT_MESSAGE_*`, `REASONING_*`,
+and `TOOL_CALL_ARGS` frames): they are never validated, persisted, or replayed, and a failing sink
+never fails the model step. `combineAgentDeltaSinks(a, b, ...)` fans deltas out the way
+`combineAgentTelemetry` fans evidence.
+
+`createAgentSharedState(initial)` is the run's shared UI state channel: a JSON document any port or
+tool executor patches with RFC 6902 operations (`add`, `replace`, `remove`), with subscribers
+observing every applied batch. Patches apply atomically - an invalid op rejects the whole batch -
+and prototype-grafting pointer segments are refused. The document is per-run observer data, not
+turn state: nothing in it is persisted by the runtime. `@nifrajs/ag-ui` projects the channel onto
+AG-UI `STATE_SNAPSHOT`/`STATE_DELTA` events.
+
+SSE streams are resumable: give `mountAgent` (or `@nifrajs/ag-ui`'s `mountAgUI`) an `evidenceLog`
+and `step` frames carry `id: <seq>`. A client that loses the connection re-POSTs the same `turnId`
+with a `Last-Event-ID` header and receives the missed evidence, rejoining a still-running turn live
+or replaying the stored terminal frame - the run is never re-executed.
+`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.
+
 Execution policies can be required by a tool contract. `createLocalProcessAdapter` applies cwd and
 environment filtering, timeouts, and cancellation to child processes. The local adapter is NOT a
 security boundary. Without OS-level sandboxing it contains crashes and accidents, not hostile code.
@@ -7701,6 +8564,111 @@ security boundary. Without OS-level sandboxing it contains crashes and accidents
 For the compact agent contract, see [`LLM.md`](./LLM.md). The full machine-readable corpus is
 [`../../llms-full.txt`](../../llms-full.txt).
 
+## @nifrajs/agent-app
+
+A presentation-safe browser SDK for Nifra agent hosts.
+
+This package depends on **only** `@nifrajs/agent-protocol`. It pulls in no backend, model provider,
+storage, or UI framework, so it can be bundled into browser-facing code without dragging a private
+engine or payload content across the boundary. Everything it surfaces upward is a content-free view
+model: identifiers, lifecycle statuses, counters, and opaque references. A prompt becomes a character
+count; a tool result becomes an `ok` flag and an error *code*; a compaction becomes before/after token
+counts.
+
+## What it does
+
+- **Feature negotiation.** On session creation the client intersects the features it can drive with the
+  capabilities the host advertises, and gates the matching operations behind `requireFeature`.
+- **Caller auth.** An optional `authorize` hook mints a bearer token per request. The token is placed
+  on the outgoing `Authorization` header and never stored on the transport, copied into a result, or
+  written to a log.
+- **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.
+- **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
+  back through negotiated commands.
+- **Run Studio views.** Run graphs, retry/recovery timelines, eval comparisons, and fault-injection
+  rows consume only protocol evidence and bounded replay references.
+- **Escape hatch.** `command()` reaches host-specific surfaces outside the negotiated contract and
+  still returns a bounded `CommandOutcome` - it never throws the credential.
+
+## Usage
+
+```ts
+import { AgentAppClient, HttpAgentTransport } from "@nifrajs/agent-app"
+
+const transport = new HttpAgentTransport({
+  endpoint: "http://127.0.0.1:8787",
+  authorize: () => currentToken(), // per-request; never stored
+})
+const client = new AgentAppClient(transport)
+
+const session = await client.createSession()
+if (client.supports("resume")) {
+  const replay = await client.resume({ cursor: lastCursor })
+  // replay.entries: { seq, at, type }[] - no payloads
+}
+
+for await (const view of client.send("summarize the diff")) {
+  // view is content-free: e.g. { kind: "assistant.delta", seq, chars }
+}
+```
+
+## Boundary
+
+The transport receives the host's full event stream in order to derive counts, but the client's public
+output is projected to content-free view models. That projection is the seam: an application built on
+this SDK can render progress and resolve interactions, and cannot reconstruct a prompt, tool payload,
+model completion, diagnostic report, or filesystem path. The `scripts/check-agent-boundary.ts` gate
+enforces that this package imports nothing but `@nifrajs/agent-protocol`.
+
+The SDK is transport-neutral and opt-in: it does not retain payloads, provide identity or tenancy,
+claim a remote security boundary, or imply durable delivery. Production hosts own authorization,
+retention, and adapter policy.
+
+## License
+
+MIT
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).
+
+## @nifrajs/agent-protocol
+
+Small, backend-neutral contracts for local coding-agent sessions.
+
+The package contains versioned session snapshots, streamed assistant/tool/approval
+events, bounded live event streams, and backend interfaces. It has no runtime
+dependencies and does not import Nifra framework packages, model SDKs, or UI code.
+
+```ts
+import { createAgentEventStream } from "@nifrajs/agent-protocol"
+
+const events = createAgentEventStream(256)
+events.push(/* a versioned AgentEvent */)
+```
+
+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.
+
+## Version 1 compatibility
+
+Version 1 is additive. Hosts advertise capabilities and clients use only the negotiated intersection;
+an unsupported command is a stable `feature_unsupported` result. Optional fields are ignored by older
+peers, while a cursor gap returns `resync_required` instead of silently skipping evidence. A future
+major requires a recorded semantic incompatibility, dual decoders, cross-version fixtures, and an
+approved migration plan.
+
+Run evidence and lifecycle values are structural only: identifiers, statuses, counters, timestamps,
+digests, and opaque references. Prompts, model output, tool arguments, and filesystem paths do not
+belong in these public contracts.
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).
+
 ## @nifrajs/agent-telemetry
 
 Child-span telemetry for AI tool calls made through Nifra tool and MCP endpoints.
@@ -7719,6 +8687,35 @@ Requests under `/_nifra/tool/*` and requests to `/mcp` receive tool-name, input-
 duration, and status observations. When `@nifrajs/otel` owns the request observation, tool spans are
 attached as children; otherwise the plugin creates a standalone observation. Other routes pass through.
 
+## Tracing agent runs
+
+`traceAgentRun` turns a `@nifrajs/agent` run's step evidence into an OpenTelemetry trace: one
+`nifra.agent.run` span per run, one child span per evidence item, with tool names, effect ids, error
+codes, and effect-ledger heads carried as span attributes. Only the runner's constrained evidence
+fields are exported - prompts, tool inputs, and outputs cannot enter a trace.
+
+Orchestration correlation is opt-in and cardinality-bounded. Allowed attributes are run, plan, node,
+attempt, evidence, replay, and trace coordinates plus bounded status/error codes. Content-bearing or
+unbounded attributes are rejected; the exporter is not a payload retention sink.
+
+```ts
+import { traceAgentRun } from "@nifrajs/agent-telemetry"
+import { combineAgentTelemetry, runAgent } from "@nifrajs/agent"
+
+const trace = traceAgentRun({ agent: agent.name, turnId, exporter })
+const result = await runAgent(agent, input, {
+  ...ports,
+  telemetry: combineAgentTelemetry(ports.telemetry, trace.telemetry),
+})
+trace.end(result)
+```
+
+Model evidence arrives as a started/terminal pair and becomes one timed `nifra.agent.model` span;
+tool, approval, budget, and state evidence are terminal-only and become instant children. Pass
+`parent` (for example the enclosing request observation's `context`) to nest runs under the HTTP
+span, or `traceparent` to continue an inbound W3C trace; `trace.context` is the run span's identity,
+forwardable with `traceHeaders`. Telemetry is fail-open: a throwing exporter never fails the turn.
+
 ## For AI agents
 
 Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
@@ -7949,8 +8946,9 @@ await cache.invalidateTag(`user:${id}`)
 
 ## Stores
 
-The default `MemoryCache` is in-process with lazy expiry, a tag index, and an optional LRU cap
-(`new MemoryCache({ maxEntries: 10_000 })`). For a cache shared across instances, implement `CacheStore`
+The default `MemoryCache` is in-process with incremental expiry, a tag index, and a 10,000-entry LRU
+cap. Tune it with `new MemoryCache({ maxEntries: 2_000 })`; `maxEntries: 0` is the explicit unbounded
+opt-in. For a cache shared across instances, implement `CacheStore`
 (`get` / `set` / `delete` / `invalidateTag` / `clear`) over CF KV, Redis, etc.:
 
 ```ts
@@ -7987,6 +8985,7 @@ nifra start   [--port <n>] [--out <dir>]   Run the generated Bun server at <out>
 nifra context                             Print this project's API + page routes + conventions.
 nifra mcp                                 MCP server (stdio) exposing this project to a coding agent.
 nifra check   [--json]                    Gate: typecheck + lints; --json includes fixes/suggestions.
+nifra migrate --from tailwind --to stylex  Dry-run safe static Tailwind → StyleX migration; --write applies it.
 nifra assure  [--config <file>] [--json]  Gate reflected routes against enforcement evidence.
 nifra capabilities check [--json]        Gate effect provenance + the reviewed capability lockfile.
 nifra manifest emit [--sign <key-ref>]   Emit the hash-verified route trust artifact after assurance.
@@ -8049,6 +9048,15 @@ For hand-rolled own-API `fetch()` calls, `nifra check` stays conservative: simpl
 that match a statically visible Nifra route get an exact typed-client rewrite diff; dynamic URLs, custom
 headers, bodies, query strings, or ambiguous routes fall back to manual steps.
 
+## `nifra migrate --from tailwind --to stylex`
+
+This command is a dry run by default. It rewrites static `className` attributes whose utilities have a
+direct StyleX equivalent into `stylex.props(...)` plus a local `stylex.create(...)` table. Use
+`--write` to apply the safe changes, and `--dir` to scan a project subdirectory. Responsive breakpoints
+and element-local pseudo-classes are supported; dynamic expressions, arbitrary values, parent-dependent
+variants, and unknown utilities are left untouched and reported with file and line evidence. A non-zero
+exit status means manual migration issues remain.
+
 When a library such as Better Auth intentionally owns a mounted prefix outside the Nifra contract,
 declare that prefix in `nifra.check.json` so its relative calls do not keep CI red:
 
@@ -8175,6 +9183,76 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/coding-agent
+
+Standalone, extensible Nifra coding-agent host and CLI.
+
+The package provides `nifra-agent` in interactive, one-shot, JSON, and local
+loopback RPC modes. It adds sessions, checkpoints, bounded compaction,
+transactional TypeScript extensions, self-healing repair stages, workflows,
+bounded subagents, and Nifra verification descriptors without changing Nifra's
+framework runtime.
+
+Extensions can register bounded workflows that are listed and run through the
+authenticated RPC surface. Capability manifests, project workspace policies,
+optional isolated-worktree leases, and a pre-activation syntax gate keep those
+customizations explicit and replaceable.
+
+```sh
+bunx nifra-agent --backend pi
+bunx nifra-agent --backend pi --message "run the checks and explain failures"
+bunx nifra-agent --backend pi --verify-after-turn check --max-repair-attempts 2
+bunx nifra-agent --backend replay --replay ./session-events.jsonl --json
+```
+
+When --verify-after-turn is enabled, a failed gate becomes a bounded repair turn: the host sends
+the failure diagnostics back to the agent, runs the gate again, and stops on success or after the
+configured attempt cap. Use --max-repair-attempts 0 for observe-only verification.
+
+For embedding, use `CodingAgentHost` or `CodingAgentRpcServer`. The host keeps
+live event queues bounded, filters verification subprocess environments, and
+requires explicit local RPC authorization. Install this package only when an
+application wants the agent product.
+
+RPC failures return actionable bounded error messages by default. For a trusted
+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.
+
+`IsolatedExtensionWorker` is an opt-in process-backed crash-containment seam for
+extensions. It is not a hostile-code sandbox; use OS-level isolation before
+loading code you do not trust.
+
+`NifraBackend` is a small provider port for a future native backend. It accepts
+an injected model implementation and bounded tools without importing a provider
+SDK. `ReplayBackend` and `readReplayEvents` provide deterministic protocol
+replays for CI and Workbench regression tests.
+
+## At-least-once run dispatch
+
+`@nifrajs/coding-agent/orchestration` also exports an evidence-only run dispatch port and an adapter
+over `@nifrajs/jobs`. Dispatch is at-least-once: a lease may be delivered again after worker loss or
+lease expiry. Every logical node attempt receives a stable idempotency key derived from the plan,
+run, node, and attempt boundary. Effects must provide a matching proof before recovery can settle a
+completed boundary; an unproven post-effect failure is dead-lettered rather than guessed safe.
+
+`createMemoryRunDispatchStore()` is disposable single-process test infrastructure. It makes no
+durability, hosted-worker, retention, tenant-authorization, or exactly-once guarantee. Durable
+operated adapters implement the exported `RunDispatchStore` and `DurableDispatchAdapter` ports in
+their own data layer, including authorization, row policy, retention, reconciliation, and worker
+health. The public package does not store prompts, model output, tool arguments, or job payloads in
+its dispatch evidence.
+
+Legacy `FileSessionStore` files remain supported for explicit local compatibility. Use
+`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; see
+[`docs/agent-platform/protocol-and-session-migration.md`](../../docs/agent-platform/protocol-and-session-migration.md)
+for rollback and protocol compatibility details.
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).
+
 ## @nifrajs/content
 
 Typed, schema-validated content collections for nifra - Markdown + frontmatter, framework-agnostic.
@@ -8267,6 +9345,27 @@ import { defineChannel, memoryChannelHub } from "@nifrajs/core/channel"
 - **Inline or contract-first.** Write routes inline (types inferred from the
   builder), or `defineContract(...)` + `implement(...)` for a decoupled, versionable
   surface - handlers lift over unchanged.
+
+### Scaling route tables
+
+Fluent chains are the best fit for a small route surface. TypeScript's type-instantiation budget
+usually becomes the limiting factor around 95-100 chained routes because every call both infers its
+handler context and re-threads the growing typed registry. The runtime router is not the limit, and
+the routes remain fully typed when you compose them as short domain groups:
+
+```ts
+const listings = server()
+  .get("/listings", () => ({ ok: true }))
+  .get("/listings/:id", (c) => ({ id: c.params.id }))
+const agents = server().get("/agents/:id", (c) => ({ id: c.params.id }))
+
+const app = server().get("/health", () => ({ ok: true })).merge(listings).merge(agents)
+```
+
+Each group's routes keep the middleware and assurance captured when that group was defined. For a
+contract-owned surface, `defineContract(...)` + `implement(...)` is the other escape hatch: the
+registry is declared as one object type, so it does not grow one fluent-instantiation level per
+route. Split groups before the compiler reports `TS2589`, rather than weakening the route types.
 - **Validation at the boundary.** Per-route `body`/`query` is any
   [Standard Schema](https://standardschema.dev) (zod/valibot/arktype, or `@nifrajs/schema`'s
   `t`); invalid input is rejected with a structured `422` before the handler runs.
@@ -8677,6 +9776,126 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/graphql
+
+Mount a GraphQL endpoint on a nifra app. A spec-compliant [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/) handler, `graphql-transport-ws` subscriptions over nifra's native WebSocket lane, and your typed nifra context piped straight into resolvers.
+
+It executes with the `graphql` package's own `parse`/`validate`/`execute`/`subscribe` - no HTTP framework is re-bundled, the request body reuses core's single bounded, prototype-guarded trust boundary, and the query text is never logged.
+
+## Install
+
+```bash
+bun add @nifrajs/graphql graphql
+# subscriptions also need:
+bun add graphql-ws
+```
+
+`graphql` is a required peer; `graphql-ws` is optional (only for subscriptions).
+
+## Queries and mutations
+
+```ts
+import { server } from "@nifrajs/core"
+import { mountGraphql } from "@nifrajs/graphql"
+import { buildSchema } from "graphql"
+
+const schema = buildSchema(`
+  type Query { hello: String }
+  type Mutation { echo(msg: String!): String }
+`)
+
+const rootValue = {
+  hello: () => "world",
+  echo: ({ msg }: { msg: string }) => msg,
+}
+
+const app = server()
+mountGraphql(app, { schema, rootValue })
+// POST /graphql  - queries + mutations
+// GET  /graphql  - queries only (idempotent, cacheable)
+```
+
+Prefer the handler directly? Mount it yourself:
+
+```ts
+import { respondGraphql } from "@nifrajs/graphql"
+
+app.post("/graphql", (c) => respondGraphql(c.req, { schema, rootValue }))
+```
+
+## Context injection
+
+The one thing a plain third-party mount cannot do: derive the resolver `contextValue` from what your nifra handler already resolved (auth subject, env, params).
+
+```ts
+mountGraphql(app, {
+  schema,
+  context: ({ request, nifra }) => ({
+    user: nifra?.env,           // nifra route context, when mounted via mountGraphql
+    ip: request.headers.get("x-forwarded-for"),
+  }),
+})
+```
+
+Resolvers read it as their third argument.
+
+## Subscriptions
+
+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.
+
+```ts
+import { server } from "@nifrajs/core"
+import { websocket } from "@nifrajs/core/ws"
+import { mountGraphql, createPubSub } from "@nifrajs/graphql"
+
+const pubsub = createPubSub<number>()
+
+const app = server().use(websocket())
+mountGraphql(app, {
+  schema,
+  context: () => ({ pubsub }),
+  subscriptions: true,
+})
+
+// A resolver:
+//   count: { subscribe: (_, __, ctx) => ctx.pubsub.subscribe("count"), resolve: (n) => n }
+// Push an event from anywhere:
+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.
+
+## Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `schema` | - | Executable `GraphQLSchema` (required). |
+| `context` | `{}` | Build the resolver `contextValue` per operation. |
+| `rootValue` | - | Root value passed to the executor. |
+| `maxBodyBytes` | `1_000_000` | Request body cap; larger bodies answer 413. |
+| `protoPoisoning` | `"reject"` | Prototype-pollution policy for the JSON body. |
+| `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. |
+| `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.
+
+## License
+
+MIT
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.
+
 ## @nifrajs/i18n
 
 Framework-agnostic i18n for nifra - locale negotiation + a tiny ICU message formatter on the platform Intl. Dependency-free.
@@ -8917,6 +10136,12 @@ 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**.
 
+The queue remains agent-agnostic. `@nifrajs/coding-agent` can place content-free run-dispatch
+identities in a dedicated `JobStore`, but this package does not import or define agent concepts. A
+`MemoryJobStore` is disposable single-process storage; production durability, authorization,
+retention, reconciliation, and worker coordination belong to the caller's operated adapter. No
+exactly-once delivery guarantee is implied by a lease.
+
 ## Cloudflare Workers
 
 Workers has no long-lived process, so don't call `start()`. Back the queue with a durable store and a
@@ -8976,6 +10201,10 @@ Mount `mcp.fetch` at `POST /mcp`. The package also exposes the JSON-RPC protocol
 layers directly, plus `defineMcpWidget` and the React adapter for tool results that render UI in MCP
 hosts.
 
+Clients that include `text/event-stream` in `Accept` receive progress notifications as they happen,
+followed by the final JSON-RPC response in the same stream. An SSE `GET /mcp` opens a cancellable
+server-message connection; a plain `GET /mcp` remains a health page.
+
 ## For AI agents
 
 Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
@@ -9357,6 +10586,43 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/pi
+
+Lightweight Pi JSONL/RPC adapter for the Nifra agent protocol.
+
+It starts Pi in headless RPC mode, maps Pi lifecycle, assistant, tool,
+compaction, extension, and error events into `@nifrajs/agent-protocol`, and
+supports cancellation, reload, session identity, and bounded event buffering.
+
+Reload defaults to a process restart with the same Pi session ID. This is the
+reliable reload primitive in Pi's documented RPC protocol: the transcript stays
+in Pi's session store while the new process loads changed extensions. The tiny
+public-API bridge is still loaded for interactive Pi use. Set
+`reloadCommand: "prompt"` only for an RPC implementation that dispatches slash
+commands, or `reloadCommand: "rpc"` for one that provides a top-level reload
+command. Set `enableReloadBridge: false` when supplying a custom bridge.
+
+Set `enableNifraTools: true` to load the separately packaged Pi extension with
+`nifra_context`, `nifra_check`, `nifra_assure`, and `nifra_test` tools. The
+default is off so embedding Pi stays minimal.
+
+```ts
+import { PiBackend } from "@nifrajs/pi"
+
+const backend = new PiBackend()
+const session = await backend.createSession({ cwd: process.cwd() })
+for await (const event of backend.send({ sessionId: session.id, message: "inspect this project" })) {
+  console.log(event.type)
+}
+```
+
+Pi stays an optional dependency of the agent product. Nothing in this package is
+reachable from `@nifrajs/core`, `@nifrajs/client`, `@nifrajs/web`, or
+`@nifrajs/schema`.
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).
+
 ## @nifrajs/prompt
 
 Provider-neutral, type-safe prompts with Standard Schema input and validated structured output.
@@ -9410,7 +10676,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, forwarding metadata (`X-Forwarded-*`) is dropped unless `forwardClientIp: true`, 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. 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`.
 
 ## Docs
 
@@ -9572,6 +10838,11 @@ pi install npm:@nifrajs/skills
 /plugin install nifra@nifra
 ```
 
+The plugin registers the Nifra MCP server as well as the skills, so a fresh install has the live tools
+the skills tell it to prefer. Its launch spec is deliberately unpinned - a plugin is installed once and
+opened against many projects, so the CLI resolves per project and the server reports version skew
+itself rather than freezing one version across all of them.
+
 **Anything that reads a skills directory** (Cursor, `.agents/skills`, a project `.pi/skills`)
 
 ```sh
@@ -9588,6 +10859,9 @@ against the version installed in the project being edited:
 bunx @nifrajs/cli init-agents      # register the MCP server in an existing app
 ```
 
+The Claude Code plugin brings its own copy of that server, so `init-agents` is for the other surfaces -
+and for committing a version-pinned `.mcp.json` that every contributor on the project shares.
+
 Not in a Nifra project? The docs tools are hosted at `https://mcp.nifra.dev`.
 
 That split is the anti-drift design: a skill that restated the API would rot on the next release,
@@ -9867,6 +11141,14 @@ that every call carries and captures cookies via a shared jar.
 
 For a **stateless** request (no cookies), use `testClient` from `@nifrajs/client` directly.
 
+### Agent evaluation and failure matrix
+
+`runAgentEvalComposition` composes trajectory replay, fault profiles, contract invariants,
+idempotency proofs, and adapter certification. Reports expose explicit invariant and rubric cases,
+stable regression IDs, schedule tokens, and digests; they do not retain prompts, tool payloads,
+model output, labels, or a single opaque quality score. The failure matrix covers model, tool,
+approval, cancellation, lease, cursor, registry, and deployment boundaries.
+
 ## For AI agents
 
 Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
@@ -10077,6 +11359,14 @@ Zero-framework render adapter for @nifrajs/web - auto-escaping tagged-template H
 
 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`.
 
+## The AI-safe lane
+
+Vanilla is the render adapter an agent gets right on the first try. It ships no framework runtime, so there is no hydration, no reactivity, and none of the failure modes (stale closures, hydration mismatch, what-re-runs-when) that trip up generated code. You get true SSR plus every server feature - loaders, actions, ISR/SSG, streaming, head management - unchanged from `@nifrajs/web`; those live in the core, not the view layer.
+
+Interactivity is added with **islands**, not hydration: small imperative DOM enhancers over server-rendered elements. `defineIsland` types the props, `createIslandBus` coordinates islands over a typed channel, and every enhancer returns its cleanup - the one rule `nifra check` enforces (`NF-C020`). See the [islands cookbook](https://nifra.dev/docs/islands) for the counter, cart-badge, and filter patterns, or run `nifra scaffold` on a vanilla route for the golden stub.
+
+Need a stateful app UI with reactive components? That is what the five framework adapters are for - reach for `@nifrajs/web-preact` or `@nifrajs/web-solid` when you want a small reactive runtime.
+
 ## Install
 
 ```sh
@@ -10237,13 +11527,29 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 # Complete export index (generated from each package's src/index.ts)
 
+## @nifrajs/a2a
+
+`A2A_ERROR_CODES`, `A2A_PROTOCOL_VERSION`, `A2AAgentCard`, `A2AAgentSkill`, `A2ACardInfo`, `A2AMountableApp`, `A2ARouteContext`, `A2ATaskState`, `AGENT_CARD_WELL_KNOWN_PATH`, `agentCard`, `mountA2A`, `MountA2AOptions`
+
+## @nifrajs/ag-ui
+
+`AgUIMountableApp`, `AgUIRouteContext`, `AgUIRunContext`, `AgUIRunUsage`, `mountAgUI`, `MountAgUIOptions`
+
 ## @nifrajs/agent
 
-`AgentApprovalPort`, `AgentApprovalResult`, `AgentDefinition`, `AgentModelPort`, `AgentModelRequest`, `AgentModelResponse`, `AgentPendingContinuation`, `AgentPendingKind`, `AgentPorts`, `AgentRunResult`, `AgentStateStore`, `AgentStatus`, `AgentStepEvidence`, `AgentTelemetryPort`, `AgentToolContract`, `AgentToolDescriptor`, `AgentToolResult`, `AgentTranscript`, `AgentTurnBaseResult`, `AgentTurnError`, `AgentTurnInput`, `AgentTurnResult`, `AgentTurnState`, `createAgentState`, `createLocalProcessAdapter`, `ExecutionPolicy`, `ExecutionPolicyAdapter`, `LOCAL_PROCESS_LIMITATION`, `LocalProcessAdapter`, `LocalProcessAdapterOptions`, `LocalProcessPolicyError`, `LocalProcessRequest`, `LocalProcessResult`, `MemoryAgentStateStore`, `replayAgent`, `resumeAgent`, `runAgent`, `RunAgentOptions`, `turn`
+`AgentApprovalPort`, `AgentApprovalResult`, `AgentDefinition`, `AgentDeltaSink`, `AgentDeployment`, `AgentDeploymentAdapter`, `AgentDeploymentPlan`, `AgentModelDelta`, `AgentModelPort`, `AgentModelRequest`, `AgentModelResponse`, `AgentPendingContinuation`, `AgentPendingKind`, `AgentPorts`, `AgentRunResult`, `AgentSharedState`, `AgentStatePatchOp`, `AgentStateStore`, `AgentStatus`, `AgentStepEvidence`, `AgentTelemetryPort`, `AgentToolContract`, `AgentToolDescriptor`, `AgentToolResult`, `AgentTranscript`, `AgentTurnBaseResult`, `AgentTurnError`, `AgentTurnInput`, `AgentTurnResult`, `AgentTurnState`, `ApprovalClass`, `assertDeploymentAuthorityMonotonic`, `CAPABILITY_DESCRIPTOR_VERSION`, `CapabilityDescriptor`, `CapabilityKind`, `combineAgentDeltaSinks`, `combineAgentTelemetry`, `composeDescriptor`, `composeRegistrySnapshot`, `createAgentSharedState`, `createAgentState`, `createDeploymentAuthority`, `createLocalProcessAdapter`, `createStructuredOutputParser`, `DeploymentActivationOptions`, `DeploymentAuthority`, `DeploymentCancellation`, `DeploymentCancelRequest`, `DeploymentCancelResult`, `DeploymentCapabilities`, `DeploymentCapabilityReport`, `DeploymentDisposeRequest`, `DeploymentDisposeResult`, `DeploymentError`, `DeploymentErrorCode`, `DeploymentEvidence`, `DeploymentFilesystem`, `DeploymentInspection`, `DeploymentInspectRequest`, `DeploymentNetwork`, `DeploymentPrepareRequest`, `DeploymentPrepareResult`, `DeploymentProcess`, `DeploymentRuntime`, `DeploymentSecrets`, `DeploymentStartRequest`, `DeploymentStartResult`, `DeploymentState`, `descriptorFromTool`, `DescriptorInput`, `ExecutionPolicy`, `ExecutionPolicyAdapter`, `FakeModelGateway`, `FakeModelGatewayOptions`, `HostileCodeIsolation`, `IdempotencyClass`, `isModelGatewayErrorCode`, `IsolationClass`, `LOCAL_PROCESS_LIMITATION`, `LocalProcessAdapter`, `LocalProcessAdapterOptions`, `LocalProcessPolicyError`, `LocalProcessRequest`, `LocalProcessResult`, `MemoryAgentStateStore`, `MODEL_GATEWAY_ERROR_CODES`, `ModelGateway`, `ModelGatewayAttemptRequest`, `ModelGatewayBudget`, `ModelGatewayEnvelope`, `ModelGatewayError`, `ModelGatewayErrorCode`, `ModelGatewayEvidence`, `ModelGatewayExecutionResult`, `ModelGatewayFailure`, `ModelGatewayFailureError`, `ModelGatewayRawResult`, `ModelGatewayRequest`, `ModelGatewayResult`, `ModelGatewaySuccess`, `ModelGatewayTerminalFailure`, `ModelGatewayUsage`, `ModelRoute`, `ModelRoutePolicy`, `ModelRouteRef`, `parseCapabilityDescriptor`, `parseDeploymentCapabilityReport`, `parseDeploymentPlan`, `parseModelGatewayError`, `parseModelGatewayResult`, `REGISTRY_SNAPSHOT_VERSION`, `RegistryError`, `RegistryErrorCode`, `RegistrySnapshot`, `replayAgent`, `ReplayModelGateway`, `ReplayModelGatewayOptions`, `resumeAgent`, `RetryClass`, `runAgent`, `RunAgentOptions`, `runModelGateway`, `structuredOutputParser`, `StructuredOutputParser`, `ToolDescriptorOptions`, `turn`
+
+## @nifrajs/agent-app
+
+`AGENT_APP_FEATURES`, `AgentAppClient`, `AgentAppClientOptions`, `AgentAppError`, `AgentEventView`, `AgentTransport`, `AgentTransportError`, `AgentTransportRequest`, `ApprovalRequiredView`, `ApprovalResolvedView`, `AssistantChunkView`, `AuthProvider`, `boundaryCommands`, `BoundaryDecisionResult`, `boundaryIsStale`, `BoundaryItemView`, `BoundaryStateView`, `CommandOutcome`, `CreateSessionInput`, `EvalComparisonView`, `EvidenceTimelineView`, `ExtensionReloadedView`, `FaultInjectionView`, `HandoffView`, `HttpAgentTransport`, `HttpAgentTransportOptions`, `MemoryCompactedView`, `OrderedEventBuffer`, `parseEventStream`, `PendingApprovalView`, `RegistryCapabilityView`, `RepairRequiredView`, `ReplayEntryView`, `ReplayResult`, `ResolveHandoffInput`, `ResumeInput`, `RunStudioNodeState`, `RunStudioNodeView`, `RunStudioView`, `RunView`, `SessionFailedView`, `SessionLifecycleView`, `SessionStoppedView`, `SessionView`, `toEvalComparisonView`, `toEventView`, `toEvidenceTimelineView`, `toFaultInjectionViews`, `toHandoffView`, `ToolCompletedView`, `ToolDeltaView`, `ToolStartedView`, `toRegistryCapabilityView`, `toRunStudioView`, `toRunView`, `toSessionView`, `TurnStartedView`, `VerificationCompletedView`, `virtualizeEvidenceRows`
+
+## @nifrajs/agent-protocol
+
+`AGENT_PROTOCOL_VERSION`, `AgentApprovalRequiredEvent`, `AgentApprovalResolvedEvent`, `AgentAssistantDeltaEvent`, `AgentAssistantMessageEvent`, `AgentBackend`, `AgentBackendInfo`, `agentError`, `AgentError`, `AgentEvent`, `AgentEventPayload`, `AgentEventSink`, `AgentEventStream`, `AgentEventType`, `AgentExtensionReloadedEvent`, `AgentMemoryCompactedEvent`, `AgentRepairRequiredEvent`, `AgentRepairTask`, `AgentSessionCheckpoint`, `AgentSessionCompletedEvent`, `AgentSessionEventBase`, `AgentSessionFailedEvent`, `AgentSessionSnapshot`, `AgentSessionStartedEvent`, `AgentSessionStatus`, `AgentSessionStoppedEvent`, `AgentSessionUpdatedEvent`, `AgentToolCompletedEvent`, `AgentToolDeltaEvent`, `AgentToolStartedEvent`, `AgentTurnStartedEvent`, `AgentVerificationCompletedEvent`, `createAgentEventStream`, `CreateSessionInput`, `ForkSessionInput`, `ForkSessionResult`, `isAgentEvent`, `ReloadResult`, `SendMessageInput`
 
 ## @nifrajs/agent-telemetry
 
-`agentTelemetry`, `AgentTelemetryOptions`, `consoleAgentExporter`
+`AgentRunEvidence`, `AgentRunOutcome`, `AgentRunTrace`, `agentTelemetry`, `AgentTelemetryOptions`, `consoleAgentExporter`, `orchestrationTelemetry`, `OrchestrationTelemetry`, `OrchestrationTelemetryEvent`, `OrchestrationTelemetryKind`, `OrchestrationTelemetryOptions`, `traceAgentRun`, `TraceAgentRunOptions`
 
 ## @nifrajs/auth
 
@@ -10265,13 +11571,17 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `ActionArgs`, `ActionData`, `ApiError`, `ApiProxy`, `client`, `ClientOptions`, `ClientRetryOptions`, `FetchFn`, `inProcessClient`, `InProcessClient`, `InProcessClientOptions`, `Jsonify`, `LoaderArgs`, `LoaderData`, `RegistryOf`, `RESERVED_EXACT_KEYS`, `RESERVED_KEY_READOUT`, `RESERVED_VERB_KEYS`, `reservedKeyFor`, `ResponseContractViolation`, `Result`, `SubscribeOptions`, `Subscription`, `testClient`, `Treaty`, `TreatyFromRegistry`, `WsCallOptions`, `WsHandle`
 
+## @nifrajs/coding-agent
+
+`AGENT_CAPABILITY_MANIFEST_VERSION`, `AGENT_PRESETS`, `AgentCapability`, `AgentCapabilityManifest`, `AgentPlan`, `AgentPreset`, `AgentPresetName`, `ApprovalDecision`, `ApprovalManager`, `ApprovalManagerOptions`, `ApprovalMatchRejection`, `ApprovalMatchResult`, `ApprovalRequest`, `approvalRequestFromEvent`, `approvalResolvedEvent`, `BoundedSubagentRunner`, `BoundedText`, `CapabilityDescriptor`, `CiDeploymentAdapter`, `CodingAgentExtension`, `CodingAgentHost`, `CodingAgentHostOptions`, `CodingAgentRpcServer`, `CodingAgentRpcServerHandle`, `CodingAgentRpcServerOptions`, `CompactionReport`, `ContextRecord`, `ContextWindow`, `ContextWindowOptions`, `createCapabilityManifest`, `createCiDeploymentAdapter`, `createLocalProcessDeploymentAdapter`, `createNativeGatewayModelPort`, `createNifraTools`, `createPresetSpec`, `createReplayDeploymentAdapter`, `createVerificationRepairTask`, `deniedCapabilities`, `DEPLOYMENT_REFERENCE_PROFILES`, `discoverExtensions`, `ExtensionCommand`, `ExtensionContext`, `extensionDescriptor`, `ExtensionDescriptorOptions`, `extensionDescriptors`, `ExtensionDescriptorSource`, `ExtensionEventHandler`, `ExtensionHost`, `ExtensionHostOptions`, `ExtensionProvider`, `ExtensionReloadResult`, `ExtensionSubagent`, `ExtensionTool`, `FileSessionStore`, `FileSessionStoreOptions`, `getAgentPreset`, `HandoffCoordinator`, `HandoffCoordinatorOptions`, `HandoffDecision`, `HandoffError`, `HandoffRejection`, `HandoffView`, `HealingEvent`, `HealingOptions`, `HealingResult`, `IsolatedExtensionSnapshot`, `IsolatedExtensionTool`, `IsolatedExtensionWorker`, `IsolatedExtensionWorkerOptions`, `LocalProcessDeploymentAdapter`, `migrateLegacySession`, `MigrateLegacySessionOptions`, `NativeApprovalPort`, `NativeGatewayModelPortOptions`, `NativeMessage`, `NativeModelChunk`, `NativeModelPort`, `NativeModelRequest`, `NativeModelResponse`, `NativeTool`, `NIFRA_AGENT_INSTRUCTIONS`, `NifraAgentTool`, `NifraBackend`, `NifraBackendOptions`, `NifraContextOptions`, `NifraContextResult`, `OpenHandoffInput`, `parseCapabilityManifest`, `parseSessionEvidenceRecord`, `PiBackend`, `PiBackendOptions`, `PlanEvent`, `PlanPhase`, `PlanResult`, `PlanRunner`, `PlanRunnerOptions`, `ProjectDiffOptions`, `ProjectDiffResult`, `readBoundedText`, `readProjectDiff`, `readReplayEvents`, `RepairProposal`, `ReplayBackend`, `ReplayBackendOptions`, `ReplayDeploymentAdapter`, `runNifraContext`, `runNifraVerification`, `SelfHealingController`, `SESSION_EVIDENCE_VERSION`, `SessionEvidenceRecord`, `SessionLogEntry`, `SessionMigrationError`, `SessionMigrationReport`, `SessionStore`, `stableSessionEventCode`, `SubagentExecutor`, `SubagentResult`, `SubagentRunnerOptions`, `SubagentSpec`, `UiExtensionHost`, `UiExtensionHostOptions`, `UiExtensionManifest`, `UiExtensionSlot`, `UiReloadResult`, `UiStatusWidget`, `UiThemeDescriptor`, `validateExtensionModule`, `VerificationOptions`, `VerificationRepairTask`, `VerificationResult`, `WorkflowContext`, `WorkflowEvent`, `WorkflowResult`, `WorkflowRunner`, `WorkflowRunnerOptions`, `WorkflowStep`
+
 ## @nifrajs/content
 
 `bakeCollection`, `BakedCollection`, `BakedCollectionIndex`, `BakedCollectionJoin`, `BakedIndexBucket`, `ContentFieldKey`, `Entry`, `fromBaked`, `fromBakedIndex`, `fromBakedJoin`, `indexCollection`, `IndexedCollection`, `IndexedJoin`, `IndexOptions`, `IndexPage`, `IndexQueryOptions`, `IndexRange`, `IndexRanges`, `IndexSort`, `IndexWhere`, `InferSchema`, `JoinCardinality`, `joinCollections`, `JoinedRow`, `parseEntry`, `ParseEntryOptions`, `parseFrontmatter`, `SharedKey`, `StandardSchemaV1`, `StaticCollection`
 
 ## @nifrajs/core
 
-`Version`, `VERSION`
+`AdmissionController`, `AdmissionDecision`, `AnyServer`, `commonSecretPatterns`, `Context`, `ContextPlugin`, `cookieNamePrefix`, `CookieOptions`, `CookieSecret`, `defineContextPlugin`, `defineIdentityPlugin`, `definePlugin`, `DefinePluginResult`, `defineRouterPlugin`, `DurableObjectNamespaceLike`, `ExecutionContext`, `FetchApp`, `FRAMEWORK_NAME`, `FrameworkError`, `FrameworkName`, `Handler`, `IdentityPlugin`, `InferInput`, `InferOutput`, `isSameOriginPath`, `isSameOriginRequest`, `jsonLogger`, `LambdaEvent`, `LambdaHandler`, `LambdaResponse`, `LambdaV1Event`, `LambdaV2Event`, `LogFields`, `Logger`, `McpPromptDescriptor`, `McpResourceDescriptor`, `Method`, `METHODS`, `Middleware`, `NetlifyEvent`, `NetlifyHandler`, `NifraFeatureVersion`, `NifraPlugin`, `NifraWebSocket`, `NodeRequestContext`, `NodeRequestHook`, `NodeResponseContext`, `NodeResponseHook`, `NodeServeOutcome`, `OnRequestResult`, `Params`, `parseCookies`, `pathnameOf`, `PlainRender`, `Platform`, `PlatformResponse`, `PluginTypeCollapsed`, `Prettify`, `PromptArgument`, `PromptMessage`, `redactLogFields`, `RedactOptions`, `Registry`, `ResponseBodyHook`, `ResponseBodyReplacement`, `ResponseControls`, `ResponseFinalization`, `ResponseHeadersHook`, `ResponseHeadersView`, `ResponseMapFor`, `ResponseResult`, `RouteConfigError`, `RouteConfigErrorCode`, `RouteDescriptor`, `RouteInfo`, `RouteInfoFor`, `Router`, `RouterMatch`, `RouteSchema`, `RunningServer`, `ScheduledController`, `ScheduledHandler`, `serializeCookie`, `server`, `Server`, `ServerOptions`, `signValue`, `silentLogger`, `SSEContext`, `SSEInit`, `SSEMessage`, `SSEStream`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `StandardTypes`, `StandardWebSocket`, `status`, `StatusResponse`, `toFetchHandler`, `toLambdaHandler`, `toNetlifyHandler`, `ToolAnnotations`, `toVercelHandler`, `TypedSSEStream`, `unsignValue`, `UrlParts`, `urlPartsOf`, `ValidationOutcome`, `VercelHandler`, `Version`, `VERSION`, `WebSocketContext`, `WebSocketData`, `WebSocketHandler`, `WebSocketUpgradeOutcome`
 
 ## @nifrajs/cron
 
@@ -10297,6 +11607,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `createEventRegistry`, `defineEventContract`, `EventContract`, `EventContractError`, `EventEnvelope`, `EventParseResult`, `EventRegistry`, `RegistryParseResult`
 
+## @nifrajs/graphql
+
+`buildContext`, `createPubSub`, `GraphqlContextBuilder`, `GraphqlContextInput`, `GraphqlHttpOptions`, `GraphqlPubSub`, `graphqlWebSocket`, `GraphqlWsOptions`, `mountGraphql`, `MountGraphqlOptions`, `NifraContextLike`, `respondGraphql`
+
 ## @nifrajs/i18n
 
 `createFormatter`, `Formatter`, `Locale`, `LocaleParts`, `LocaleSource`, `Messages`, `negotiateLocale`, `NegotiateOptions`, `ResolvedLocale`, `resolveLocale`
@@ -10341,6 +11655,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `ActiveObservation`, `AttributeValue`, `causalitySpanLink`, `combineObservationAdapters`, `consoleSpanExporter`, `createObservationLifecycle`, `effectTracing`, `EffectTracingOptions`, `EffectTracingPlugin`, `EndObservation`, `formatTraceparent`, `generateSpanId`, `generateTraceId`, `NifraSpan`, `ObservationAdapter`, `ObservationClock`, `ObservationContext`, `ObservationLifecycle`, `ObservationLifecycleOptions`, `ObservationLink`, `ObservationParent`, `otlpExporter`, `OtlpExporter`, `OtlpExporterOptions`, `ParsedTraceparent`, `parseTraceparent`, `SpanStatus`, `StartObservation`, `TraceContext`, `traceHeaders`, `tracing`, `TracingOptions`
 
+## @nifrajs/pi
+
+`PiBackend`, `PiBackendOptions`
+
 ## @nifrajs/prompt
 
 `prompt`, `Prompt`, `PromptInputError`, `PromptMessage`, `PromptOutputError`, `PromptRequest`, `PromptResponseFormat`, `RunOptions`
@@ -10363,7 +11681,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/testing
 
-`AdapterCertificationError`, `AdapterCertificationProfile`, `AdapterCertificationReport`, `AdversarialContractError`, `AdversarialContractOptions`, `AdversarialContractReport`, `AdversarialContractResult`, `AppLike`, `assertAdapterCertification`, `assertAdversarialContract`, `assertIncidentReplays`, `assertTrajectoryInvariants`, `cacheStoreCertificationProfile`, `CapturedRequest`, `CapturedRequestInput`, `captureIncident`, `CaptureIncidentOptions`, `CertifiableCacheEntry`, `CertifiableCacheStore`, `CertifiableDomainEvent`, `CertifiableEventDeliveryAdapter`, `CertifiableEventRecord`, `CertifiableJobStore`, `CertifiableRuntimeAdapter`, `CertifiableRuntimeServer`, `CertifiableStorageAdapter`, `CertificationCapabilityEvidence`, `CertificationCheck`, `CertificationCheckEvidence`, `certifyAdapter`, `checkTrajectoryInvariants`, `ContractCaseContext`, `ContractCaseKind`, `ContractCoverageGap`, `ContractCoverageGapCode`, `ContractReplay`, `ContractRuntime`, `ContractTarget`, `ContractTestApp`, `ContractWitness`, `cookieJar`, `CookieJar`, `createFailureLab`, `createTrajectoryTranscript`, `CreateTrajectoryTranscriptOptions`, `defineCertificationProfile`, `defineFaultProfile`, `EffectLedger`, `eventDeliveryCertificationProfile`, `FailureDirective`, `FailureEvidence`, `FailureInjectedError`, `FailureKind`, `FailureLab`, `FailureLabOptions`, `FailureReplay`, `FailureScenario`, `FailureScenarioReport`, `FaultProfile`, `FaultProfileFault`, `FaultProfileFaultKind`, `FaultProfileReport`, `FaultProfileScenario`, `FaultProfileScenarioReport`, `generateRegressionTest`, `GenerateRegressionTestOptions`, `httpToolAdapter`, `IdempotencyDivergence`, `IdempotencyProof`, `IncidentCapsule`, `IncidentReplayError`, `IncidentReplayResult`, `inProcessToolAdapter`, `jobStoreCertificationProfile`, `mcpToolAdapter`, `proveIdempotency`, `recordTrajectory`, `redactForEmission`, `referenceFaultProfile`, `replayIncident`, `ReplayIncidentOptions`, `replayTrajectory`, `ReplayTrajectoryOptions`, `runAdversarialContract`, `runFailureScenario`, `runFaultProfile`, `RunFaultProfileOptions`, `runtimeAdapterCertificationProfile`, `runTrajectory`, `shapeOf`, `storageAdapterCertificationProfile`, `testSession`, `TestSession`, `TestSessionOptions`, `testToolAdapter`, `TrajectoryInvariantId`, `TrajectoryInvariantOptions`, `TrajectoryInvariantResult`, `trajectoryRegressionId`, `TrajectoryReplayResult`, `TrajectoryRun`, `TrajectoryTranscript`, `verifyAdapterCertification`
+`AdapterCertificationError`, `AdapterCertificationProfile`, `AdapterCertificationReport`, `AdversarialContractError`, `AdversarialContractOptions`, `AdversarialContractReport`, `AdversarialContractResult`, `AgentEvalCase`, `AgentEvalComponentEvidence`, `AgentEvalCompositionOptions`, `AgentEvalCompositionReport`, `AgentEvalRegressionError`, `AgentEvalReport`, `AgentEvalSuite`, `AgentEvalSuiteSpec`, `AgentFailureMatrixCase`, `AgentFailureMatrixError`, `AgentFailureMatrixKind`, `AgentFailureMatrixReport`, `AppLike`, `assertAdapterCertification`, `assertAdversarialContract`, `assertAgentEval`, `assertAgentEvalBaseline`, `assertAgentFailureMatrix`, `assertIncidentReplays`, `assertTrajectoryInvariants`, `BaselineComparison`, `BaselineOptions`, `cacheStoreCertificationProfile`, `CapturedRequest`, `CapturedRequestInput`, `captureIncident`, `CaptureIncidentOptions`, `CaseComparison`, `CaseResult`, `CertifiableCacheEntry`, `CertifiableCacheStore`, `CertifiableDeploymentAdapter`, `CertifiableDescriptorAdapter`, `CertifiableDomainEvent`, `CertifiableEventDeliveryAdapter`, `CertifiableEventRecord`, `CertifiableJobStore`, `CertifiableModelGateway`, `CertifiableRuntimeAdapter`, `CertifiableRuntimeServer`, `CertifiableStorageAdapter`, `CertificationCapabilityEvidence`, `CertificationCheck`, `CertificationCheckEvidence`, `certifyAdapter`, `checkTrajectoryInvariants`, `compareAgentEvalBaseline`, `ComparisonCode`, `ContractCaseContext`, `ContractCaseKind`, `ContractCoverageGap`, `ContractCoverageGapCode`, `ContractLabHandler`, `ContractLabRuntimeAdapter`, `ContractLabServer`, `ContractLabWitness`, `contractLabWitnesses`, `ContractReplay`, `ContractRuntime`, `ContractTarget`, `ContractTestApp`, `ContractWitness`, `cookieJar`, `CookieJar`, `createFailureLab`, `createReferenceContractLabHandler`, `createTrajectoryTranscript`, `CreateTrajectoryTranscriptOptions`, `defineAgentEvalSuite`, `defineCertificationProfile`, `defineFaultProfile`, `deploymentAdapterCertificationProfile`, `deploymentCertificationProfile`, `EffectLedger`, `eventDeliveryCertificationProfile`, `FailureDirective`, `FailureEvidence`, `FailureInjectedError`, `FailureKind`, `FailureLab`, `FailureLabOptions`, `FailureReplay`, `FailureScenario`, `FailureScenarioReport`, `FaultProfile`, `FaultProfileFault`, `FaultProfileFaultKind`, `FaultProfileReport`, `FaultProfileScenario`, `FaultProfileScenarioReport`, `gatewayCertificationProfile`, `generateRegressionTest`, `GenerateRegressionTestOptions`, `httpToolAdapter`, `IdempotencyDivergence`, `IdempotencyProof`, `IncidentCapsule`, `IncidentReplayError`, `IncidentReplayResult`, `inProcessToolAdapter`, `jobStoreCertificationProfile`, `mcpToolAdapter`, `modelGatewayCertificationProfile`, `parseRubricVerdict`, `proveIdempotency`, `recordTrajectory`, `redactForEmission`, `referenceFaultProfile`, `registryCertificationProfile`, `replayIncident`, `ReplayIncidentOptions`, `replayTrajectory`, `ReplayTrajectoryOptions`, `RubricShape`, `RubricSpec`, `RubricVerdict`, `runAdversarialContract`, `runAgentEvalComposition`, `runAgentFailureMatrix`, `runContractLab`, `runContractLabOverHttp`, `runContractLabThroughAdapter`, `runFailureScenario`, `runFaultProfile`, `RunFaultProfileOptions`, `runtimeAdapterCertificationProfile`, `runTrajectory`, `ScoreTolerance`, `shapeOf`, `storageAdapterCertificationProfile`, `testSession`, `TestSession`, `TestSessionOptions`, `testToolAdapter`, `TrajectoryInvariantId`, `TrajectoryInvariantOptions`, `TrajectoryInvariantResult`, `trajectoryRegressionId`, `TrajectoryReplayResult`, `TrajectoryRun`, `TrajectoryTranscript`, `verifyAdapterCertification`
 
 ## @nifrajs/ts-plugin
 
@@ -10375,7 +11693,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `assertStaticBoundaryImports`, `Blocker`, `BlockerController`, `BlockerFunction`, `BlockerLocation`, `BlockerState`, `Boundary`, `BOUNDARY_GLOBAL`, `BoundaryDescriptor`, `boundaryDescriptors`, `BoundaryError`, `BoundaryMode`, `boundaryModeKey`, `BoundaryRegistration`, `BoundaryRequestCtx`, `BoundaryState`, `BoundaryStates`, `BoundaryStatus`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `ClientAction`, `ClientActionArgs`, `ClientActionResult`, `clientEntry`, `ClientLoader`, `ClientLoaderArgs`, `ClientRequestBody`, `ClientRouteHooks`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `DynamicBoundary`, `DynamicBoundaryBatch`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `gate`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateRouteSearchTypes`, `GenerateRouteSearchTypesOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `gone`, `hashQueryKey`, `IDLE_BLOCKER`, `InertScriptType`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `InterceptBoundary`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_REVALIDATE_TAGS_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `MemoryStaticBoundaryCache`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaDescriptor`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateFunction`, `NavigateOptions`, `NavigateSearchOf`, `NavigateTargetInput`, `notFound`, `openGraph`, `OpenGraphInput`, `PendingBoundary`, `PRE_HYDRATION_GUARD`, `previewEndpoint`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `registerBlocker`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderAssemblyCache`, `RenderedPage`, `renderPage`, `RenderPageInput`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveDynamicBoundaries`, `resolveMeta`, `resolveNavigate`, `resolvePublicPath`, `resolveStaticBoundaries`, `RETAIN_HEADER`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROOT_ATTRIBUTE`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `RouteSearch`, `routeStyles`, `ScriptDescriptor`, `searchOf`, `SearchOf`, `searchOfChain`, `serializeData`, `serializeSearch`, `servePublicDir`, `ServePublicDirOptions`, `SERVER_FN_MODULE`, `SERVER_ONLY_MODULE`, `ServerOnly`, `setBlockerController`, `setBrowserNavigate`, `setSsrModuleLoader`, `ssrModuleLoader`, `SsrModuleLoader`, `startDynamicBoundaries`, `StaticBoundary`, `StaticBoundaryCache`, `StaticBoundaryImportEdge`, `StaticBoundaryRoot`, `StaticCtx`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `STATUS_HEADER`, `statusPage`, `StatusPageOptions`, `styles`, `Submission`, `SubmitOptions`, `unsafeInlineScript`, `UnsafeScriptDescriptor`, `withISR`
+`Action`, `ACTION_GLOBAL`, `assertRenderAdapterConformance`, `assertStaticBoundaryImports`, `Blocker`, `BlockerController`, `BlockerFunction`, `BlockerLocation`, `BlockerState`, `Boundary`, `BOUNDARY_GLOBAL`, `BoundaryDescriptor`, `boundaryDescriptors`, `BoundaryError`, `BoundaryMode`, `boundaryModeKey`, `BoundaryRegistration`, `BoundaryRequestCtx`, `BoundaryState`, `BoundaryStates`, `BoundaryStatus`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `ClientAction`, `ClientActionArgs`, `ClientActionResult`, `ClientLoader`, `ClientLoaderArgs`, `ClientRequestBody`, `ClientRouteHooks`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `DynamicBoundary`, `DynamicBoundaryBatch`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateRouteSearchTypes`, `GenerateRouteSearchTypesOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `gone`, `hashQueryKey`, `IDLE_BLOCKER`, `InertScriptType`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `InterceptBoundary`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_REVALIDATE_TAGS_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `MemoryStaticBoundaryCache`, `mergeHeads`, `Meta`, `MetaArgs`, `MetaDescriptor`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateFunction`, `NavigateOptions`, `NavigateSearchOf`, `NavigateTargetInput`, `notFound`, `openGraph`, `OpenGraphInput`, `PendingBoundary`, `PRE_HYDRATION_GUARD`, `previewEndpoint`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `registerBlocker`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderAssemblyCache`, `RenderedPage`, `renderPage`, `RenderPageInput`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveDynamicBoundaries`, `resolveMeta`, `resolveNavigate`, `resolvePublicPath`, `resolveStaticBoundaries`, `RETAIN_HEADER`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROOT_ATTRIBUTE`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `RouteSearch`, `ScriptDescriptor`, `searchOf`, `SearchOf`, `searchOfChain`, `serializeData`, `serializeSearch`, `servePublicDir`, `ServePublicDirOptions`, `SERVER_FN_MODULE`, `SERVER_ONLY_MODULE`, `ServerOnly`, `setBlockerController`, `setBrowserNavigate`, `setSsrModuleLoader`, `ssrModuleLoader`, `SsrModuleLoader`, `startDynamicBoundaries`, `StaticBoundary`, `StaticBoundaryCache`, `StaticBoundaryImportEdge`, `StaticBoundaryRoot`, `StaticCtx`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `STATUS_HEADER`, `statusPage`, `StatusPageOptions`, `Submission`, `SubmitOptions`, `unsafeInlineScript`, `UnsafeScriptDescriptor`, `withISR`
 
 ## @nifrajs/web-preact