@nifrajs/cli 1.13.0 → 2.1.0

package/docs/llms-full.txt

@@ -39,7 +39,7 @@ production backend (routing, validation, middleware, auth, WebSockets). Run it o
 `.listen()`:
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 
 server()
   .get("/", () => ({ hello: "world" }))
@@ -362,7 +362,7 @@ and `c.query` are the _validated_ types, and a bad request gets a structured
 
 ```ts
 // doc-check: skip — uses the third-party `zod` schema lib (any Standard Schema works); install it to run this.
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { z } from "zod"   // any Standard Schema works: zod, valibot, arktype…
 
 export const app = server()
@@ -427,7 +427,7 @@ builder produces.
 
 ```ts
 // doc-check: skip — uses the third-party `zod` schema lib + an illustrative `users` repo; install zod to run this.
-import { defineContract, implement } from "@nifrajs/core"
+import { defineContract, implement } from "@nifrajs/core/contract"
 import { z } from "zod"
 
 // 1. Declare the contract — methods, paths, and input schemas, no handlers.
@@ -945,7 +945,8 @@ resolves, you call `stream.close()`, or the client disconnects (
 Node, Deno, and the edge — no `new Function`, no per-runtime API.
 
 ```ts
-import { server, sse } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
+import { sse } from "@nifrajs/core/sse"
 
 const app = server()
 // Your pub-sub of choice — subscribe returns an unsubscribe function.
@@ -1171,7 +1172,7 @@ plugins both depend on it), it wires its hooks once.
 
 ```ts
 // doc-check: skip — fragment: the outer `app`, `verify`, and `db` are your application's.
-import { definePlugin } from "@nifrajs/core"
+import { definePlugin } from "@nifrajs/core/server"
 
 // A plugin is just (app) => app — call use/derive/decorate or register routes.
 // definePlugin adds a name so applying it twice (even transitively) is a no-op.
@@ -1206,7 +1207,7 @@ client — to `any`, with **no type error and no runtime error**.
 `server().use(betterAuth(auth)).get(...)` keeps every route typed.
 
 ```ts
-import { defineRouterPlugin, server } from "@nifrajs/core"
+import { defineRouterPlugin, server } from "@nifrajs/core/server"
 
 // A plugin that mounts routes/hooks but adds NO context type: defineRouterPlugin (the clearer name for
 // defineIdentityPlugin) keeps app.use()'s return type EXACTLY the caller's server, so routes added after
@@ -1228,7 +1229,7 @@ short-circuit), `beforeHandle`/`afterHandle` (around the handler),
 error, 404). Hardening middleware uses the same hook model:
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { cors, rateLimit, securityHeaders, MemoryStore } from "@nifrajs/middleware"
 
 // Hardening middleware is a hook bundle (context-agnostic) — same app.use():
@@ -1244,7 +1245,7 @@ const app = server()
 `@nifrajs/middleware` seeds a few `definePlugin` plugins to build on:
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { requestId, logger, etag } from "@nifrajs/middleware"
 
 const app = server()
@@ -1309,7 +1310,7 @@ does custom, typed verification.
 clobbering one a handler already set.
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { compression, cacheControl } from "@nifrajs/middleware"
 
 const app = server()
@@ -1356,7 +1357,7 @@ connection. It short-circuits before the handler; a concurrent retry gets a `409
 guidance (shared store + DB constraint), and the `Set-Cookie` rule.
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { idempotency, MemoryIdempotencyStore } from "@nifrajs/middleware"
 
 // A retried POST with the same Idempotency-Key replays the first response instead of
@@ -1376,7 +1377,7 @@ Read the typed claims off the returned plugin — `auth.requireClaims(c.req)` (t
 compares static credentials in **constant time** (or takes a `verify` callback).
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { jwt, jwks, basicAuth } from "@nifrajs/middleware"
 
 // JWT (WebCrypto): an explicit algorithm allowlist is REQUIRED; alg:none and RSA/HMAC confusion are rejected.
@@ -1400,7 +1401,7 @@ user's response to another. `MemoryResponseCache` is per-instance and refuses
 pretty-prints JSON responses (capped, with an optional query toggle).
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { cache, MemoryResponseCache, prettyJson } from "@nifrajs/middleware"
 
 // Full response cache: pluggable store, Vary-aware keys, byte cap. Bypasses Set-Cookie and respects
@@ -1422,7 +1423,7 @@ no open redirect); `language` negotiates `Accept-Language` into
 is opt-in; `combine` bundles several middleware into one.
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { methodOverride, trimTrailingSlash, language, timing, poweredBy, combine } from "@nifrajs/middleware"
 
 const app = server()
@@ -1475,7 +1476,7 @@ bypasses that read path. `c.boundedBody(maxBytes?)` and
 `c.boundedJson<T>(maxBytes?)` extend the **same** cap to those routes.
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 
 const app = server()
 
@@ -1566,7 +1567,7 @@ the verified text for you to parse with your own schema.
 
 ```ts
 // doc-check: skip — fragment: `app`, `env`, `StripeEvent`, and the rotation keys are your application's.
-import { verifyWebhook } from "@nifrajs/core"
+import { verifyWebhook } from "@nifrajs/core/webhook"
 
 app.post("/webhooks/stripe", async (c) => {
   // Reads the raw body BOUNDED (DoS guard), verifies the HMAC CONSTANT-TIME, and only
@@ -1646,7 +1647,7 @@ Transient `5xx` aren't cached, so a failed call stays retryable.
 Every one is constant-time where it compares secrets and **fails closed** by default.
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { jwt, csrf, ipRestriction, bodyLimit } from "@nifrajs/middleware"
 
 const app = server()
@@ -1730,12 +1731,23 @@ treated as a substitute for static provenance.
 
 ```ts
 // doc-check: skip — combines route and assurance-config excerpts.
-// route: exact effect declaration + runtime beacon at the owned adapter seam
-import { useCapability } from "@nifrajs/core/capabilities"
+// route: exact effect declaration + correlated execution at the owned adapter seam
+import { executeCapability } from "@nifrajs/core/capabilities"
+
+app.aroundCapability(async (effect, next) => {
+  // Ask an entitlement service or short-lived approval gate using token-only metadata.
+  // effect.signal aborts on request cancellation or the interceptor timeout.
+  if (!policyAllows(effect.capability, effect.target)) return // deny fail-closed
+  await next()
+}, { timeoutMs: 5_000 })
 
 app.post("/orders", { capabilities: ["db.write"] }, async (c) => {
-  useCapability(c, "db.write") // undeclared use fails before the effect
-  return orders.write(c.body)
+  return executeCapability(
+    c,
+    "db.write",
+    { target: "repo:orders" },
+    ({ signal }) => orders.write(c.body, { signal }),
+  )
 })
 
 // in nifra.assurance.ts, alongside policy:
@@ -1765,6 +1777,51 @@ Domain writes on `GET`/`HEAD` are hard violations. Each write definition may
 require request idempotency or durable command/provider-key evidence. The lockfile contains only
 method, path, and capability tokens—no payloads or tenant data—and CI never rewrites it.
 
+### Durable approval, compensation, and reconciliation
+
+The durable execution subpath turns the capability boundary into a crash-visible workflow.
+Approval resumes are HMAC-signed, expire, bind to the tenant, principal, capability, target, and
+digest, and are consumed atomically once. The effect journal marks execution before the provider
+call, so a crash after an external commit remains `ambiguous` for reconciliation instead
+of being retried blindly. Typed sagas persist compensation arguments separately from the sealed
+token-only ledger and compensate committed steps in reverse order with retry/backoff state.
+
+```ts
+// doc-check: skip — durable store implementations are deployment-specific.
+import {
+  createApprovalCoordinator,
+  createDurableEffectJournal,
+  createSagaEngine,
+} from "@nifrajs/core/durable-execution"
+import { effectTracing } from "@nifrajs/otel/effects"
+
+const effects = effectTracing({ exporter })
+app.use(effects)
+
+const approval = createApprovalCoordinator({
+  store: durableApprovalStore, // must declare durability: "durable"
+  secret: approvalHmacKey,     // 32+ random bytes, stored separately
+})
+const journal = createDurableEffectJournal({ store: durableEffectStore })
+
+await executeCapability(c, "payments.charge", {
+  target: "provider:stripe",
+  digest,
+  journal,
+  approval: {
+    gate: approval,
+    tenantId: c.principal.tenantId,
+    principalId: c.principal.userId,
+    resumeToken,
+  },
+}, ({ effectId, signal }) => payments.charge(input, { idempotencyKey: effectId, signal }))
+
+const sagas = createSagaEngine({
+  store: durableSagaStore,
+  observer: effects.observer,
+})
+```
+
 ### Already built in
 
 These add to Nifra's standing defaults: strict-by-default schema validation (unknown fields
@@ -1782,7 +1839,7 @@ embeds a token), pass opt-in `valuePatterns` — `commonSecretPatterns` covers
 bearer tokens, JWTs, emails, and a few well-known key formats, or supply your own:
 
 ```ts
-import { server, jsonLogger, commonSecretPatterns } from "@nifrajs/core"
+import { server, jsonLogger, commonSecretPatterns } from "@nifrajs/core/server"
 
 // Key-name redaction is always on; valuePatterns adds opt-in value + message scanning.
 const app = server({
@@ -2342,6 +2399,13 @@ Standard Schema
 , you can also bring Zod, Valibot, or ArkType (all eval-free) — only `t` also
 emits OpenAPI from the same definition.
 
+Size is the other edge axis. `t` is TypeBox-backed - it carries the whole JSON
+Schema type system - so a validated app on `t` is heavier than one on a lean
+validator. Validation is per route, so reach for `t` where you want the contract
+(OpenAPI/MCP for free) and Valibot where the Workers cold-start bundle is what matters: a
+Valibot-validated Nifra app measures **~16 KB gzipped**. Both are first-class, and you can
+mix them in one app.
+
 ### Scheduled (cron)
 
 Pass `scheduled` to `toFetchHandler` to also export a Workers cron
@@ -2350,7 +2414,7 @@ typed `env` and `waitUntil` as your request handlers.
 
 ```ts
 // doc-check: skip — `env.KV` is typed by your app's `Env` (the ./app import), supplied by the reader.
-import { toFetchHandler } from "@nifrajs/core"
+import { toFetchHandler } from "@nifrajs/core/server"
 import { app } from "./app"
 
 // Export fetch + a cron handler. Wire the schedule in wrangler.toml: [triggers] crons = ["0 * * * *"]
@@ -2369,15 +2433,18 @@ export default toFetchHandler(app, {
 through a generic — and runs on every runtime nifra serves: Bun, Deno, Node, and Cloudflare
 Workers.
 
-The WebSocket runtime ships as a subpath, so apps that never use it don’t bundle it. Import
-it once at your server entry; `app.ws()` without it fails loud at boot with
-`WS_RUNTIME_MISSING`. (`@nifrajs/workers` imports it for you.)
+The WebSocket runtime ships as an opt-in plugin, so apps that never use it don’t bundle it.
+Enable it with `.use(websocket())` from `@nifrajs/core/ws`;
+`app.ws()` without it fails loud at registration with
+`WS_RUNTIME_MISSING`. It installs on that server instance only — the same
+`.use()` opt-in as `mcp()` and `streaming()`.
 
 ```ts
-import { server } from "@nifrajs/core"
-import "@nifrajs/core/ws" // registers the WebSocket runtime app.ws() needs
+import { server } from "@nifrajs/core/server"
+import { websocket } from "@nifrajs/core/ws" // .use(websocket()) enables app.ws()
 
 const app = server()
+  .use(websocket())
   .get("/", () => ({ ok: true }))
   .ws("/echo", {
     open: (ws) => ws.send("welcome"),
@@ -2665,7 +2732,7 @@ SSR verified on real workerd — **this very site runs there**.
 
 ```ts
 // _worker.ts — the edge SSR entry
-import { toFetchHandler } from "@nifrajs/core"
+import { toFetchHandler } from "@nifrajs/core/server"
 import { createWebApp } from "@nifrajs/web"
 import { reactAdapter } from "@nifrajs/web-react"
 import { clientEntry, manifest } from "./server-manifest"  // generated by buildServer
@@ -2682,7 +2749,7 @@ Deploy: `wrangler pages deploy dist` (Pages) or `wrangler deploy`
 
 ## Nifra — CLI
 
-> The zero-config Nifra CLI (`nifra dev`, `nifra build`, `nifra start`): true HMR, hashed client builds, and SSR serve.
+> The zero-config Nifra CLI (`nifra dev`, `nifra build`, `nifra start`): true HMR and complete target-specific deploy builds.
 
 `Nifra` is zero-config: it reads `routes/`, `framework.ts`, and
 (optionally) `backend.ts` from your project and wires the right
@@ -2691,57 +2758,62 @@ Deploy: `wrangler pages deploy dist` (Pages) or `wrangler deploy`
 
 ```ts
 nifra dev      # true-HMR dev server (Vite middleware + nifra SSR) — http://localhost:4321
-nifra build    # bundle the client (content-hashed, code-split) + write dist/manifest.json (incl. CSS)
-nifra start    # serve the built client + SSR on Bun (assets, <link> stylesheets, matched-route preload)
+nifra build    # full Bun deploy → dist/server.js + content-hashed dist/assets/ (default target: bun)
+nifra start    # run dist/server.js on Bun
+nifra build --target cf-pages  # also: node | deno | vercel | static; add --report for chunk sizes
 
 # dev + start share the default port 4321. Override per run: --port <n> (alias -p) or the PORT env var.
-# flags: --port <n> (dev/start) · --out <dir> (build/start) · --poll (dev; containers/sandboxes)
+# flags: --port <n> (dev/start) · --out <dir> (build/start) · --target <t> (build) · --poll (dev)
 ```
 
 ### The conventions
 
-Three files at the project root. `nifra dev` runs the Vite-backed
+Four conventions at the project root. `nifra dev` runs the Vite-backed
 [HMR dev server](/docs/dev); `nifra build` runs the Bun-native production
-build (content-hashed, code-split, CSS bundled); `nifra start` serves the built
-client and SSRs on Bun — assets with immutable caching + correct MIME, the matched route's
-chunks preloaded, and the CSS bundle linked in every `<head>`.
+build (content-hashed client assets plus a target-specific server); `nifra start`
+runs the default Bun output. The generated server serves assets and SSR with matched-route
+chunks preloaded and route CSS linked in each `<head>`.
 
 ```ts
 my-app/
   routes/            # file-based routes (index.tsx, _layout.tsx, [id].tsx, …)
-  framework.ts       # adapter + clientModule + plugins (above)
+  framework.ts       # deploy-safe render adapter
+  nifra.config.ts    # CLI-only client module + dev/build plugins
   backend.ts         # export const backend = server()...   (optional — the typed contract)
 ```
 
 ### framework.ts — naming the framework once
 
-The single framework-specific file. Only `adapter` + `clientModule` are
-required; the plugin/condition fields are extras the compiler frameworks need (React/Preact's
-JSX is Bun-native, so they need none beyond the Vite plugin for dev HMR).
+Keep the render `adapter` in deploy-safe `framework.ts`. Put
+`clientModule`, Vite plugins, compiler plugins, conditions, and defines in CLI-only
+`nifra.config.ts`. This prevents build tooling and native dependencies from entering
+generated server bundles.
 
 ```ts
-// doc-check: skip — needs the third-party @vitejs/plugin-react; install it to run this.
-// framework.ts — the one place an app names its framework. The CLI reads these:
-import react from "@vitejs/plugin-react"
+// framework.ts — deploy-safe; generated server entries import this file.
 import { reactAdapter } from "@nifrajs/web-react"
 
 export const adapter = reactAdapter
+
+// nifra.config.ts — CLI-only build/dev tooling; never imported by a deployed server.
+// doc-check: skip — needs the third-party @vitejs/plugin-react; install it to run this.
+import react from "@vitejs/plugin-react"
+export { adapter } from "./framework"
 export const clientModule = "@nifrajs/web-react/client"
 export const vitePlugins = [react()]          // dev HMR (Fast Refresh)
 // Vue/Svelte/Solid also export:
 //   clientPlugins = [vueBunPlugin("dom")]     // compile routes for the client build
-//   serverPlugins = [vueBunPlugin("ssr")]     // compile routes for SSR (nifra start registers them)
+//   serverPlugins = [vueBunPlugin("ssr")]     // compile routes into the target's server bundle
 //   conditions    = ["solid"]                 // Solid: resolve solid-js to its source
 //   define        = { __VUE_OPTIONS_API__: "true", ... }   // Vue feature flags
 ```
 
 ### Scope
 
-`nifra build` + `nifra start` target a Bun (or Node) long-running server —
-the common self-hosted case. For the edge (Cloudflare Workers / Vercel Edge / Deno Deploy),
-use the per-target build entries from `create-nifra`'s `site` template (see
-[Deployment](/docs/deployment)) — `buildServer` bundles a disk-less
-worker those targets need. A `nifra build --target` for edge is a future addition.
+`nifra build` defaults to a self-hosted Bun server. Use `--target node`,
+`deno`, `cf-pages`, `vercel`, or `static` for another
+complete deploy shape (see [Deployment](/docs/deployment)). Run non-Bun outputs with
+the command printed by the build.
 
 ## Nifra — Dev & HMR
 
@@ -3170,6 +3242,110 @@ params. The error reads out the fix; add a schema to the route:
 `.get("/thing", { query: z.object({ page: z.string() }) }, h)`. Then
 `c.query` is the validated type and the client accepts a typed `query`.
 
+###
+`TS2589` - "Type instantiation is excessively deep and possibly infinite" (one
+`server()` chain grew past ~95 routes)
+
+The fluent builder's whole value - end-to-end inference, so `c.params.id` is typed
+straight from `:id` and the client is derived from `typeof app` - carries
+an **O(N) type-instantiation cost**. Each `.get(path, handler)` /
+`.post(...)` does two things at once: it computes the handler's context type from the
+path, _and_ it returns a server whose registry is one alias level deeper than the last.
+Neither strains the compiler alone; the **product** - recomputing the handler
+context while re-threading an ever-larger registry at every step - exhausts TypeScript's
+per-expression instantiation budget. A single chain hits `TS2589` at
+**~95-100 routes**.
+
+[!NOTE]
+
+This is a **healthy, growing app's wall, not abuse**. It is inherent to any
+builder that infers handler context _and_ accumulates a typed route registry (Elysia,
+tRPC, and Hono's typed clients cap the same way), so it is not fixable by reshaping the
+internal `AddRoute`. The fix is to use a shape that does not form the product.
+
+**Fix 1 - split into domain groups and `.merge()` them.** Each group is
+its own short `server()` chain, so no single chain approaches the ceiling; a
+`.merge()` is one `R & R2` intersection with no per-call context work,
+so composing groups stays cheap. A 90-route single chain is inside the ceiling; 120 routes as
+four merged 30-route groups typecheck with full per-route fidelity.
+
+```ts
+import { server } from "@nifrajs/core"
+
+// Each domain is its OWN short server() chain, kept well under the ~95-route ceiling.
+const users = server()
+  .get("/users/:id", (c) => ({ id: c.params.id }))
+  .post("/users", () => ({ created: true }))
+
+const orders = server()
+  .get("/orders/:id", (c) => ({ id: c.params.id }))
+  .post("/orders", () => ({ placed: true }))
+
+// merge() adds ONE R & R2 intersection per group - no per-call context recompute - so the whole
+// app stays inside tsc's budget no matter how many groups (or routes) you compose.
+export const app = server()
+  .get("/health", () => ({ ok: true }))
+  .merge(users)
+  .merge(orders)
+```
+
+**Fix 2 - go contract-first, and stay flat at any route count.**
+`defineContract(...)` declares the entire registry as **one object type
+upfront**, and `implement(contract, handlers)` binds handlers to it. Nothing
+grows a registry per call, so there is **no ceiling at all** - this is the path for
+an API that will keep adding routes for years. Handlers stay checked against the contract exactly
+as inline routes are. See [Contract-first](/docs/contract).
+
+```ts
+import { defineContract, implement } from "@nifrajs/core/contract"
+
+// One object type, declared upfront - NOT an N-deep stack of `Server<AddRoute<…>>` aliases.
+const contract = defineContract({
+  getUser:    { method: "GET",  path: "/users/:id" },
+  listUsers:  { method: "GET",  path: "/users" },
+  createUser: { method: "POST", path: "/users" },
+  // ...hundreds more operations stay flat: the registry is one type, not a growing chain.
+})
+
+export const app = implement(contract, {
+  getUser:    (c) => ({ id: c.params.id }),
+  listUsers:  () => ({ users: [] as string[] }),
+  createUser: () => ({ created: true }),
+})
+```
+
+####
+`TS2345` from an unrelated `.merge()` - budget exhausted "at a distance"
+
+Because the budget is per-expression and global to a compilation, a type-heavy construct
+_elsewhere_ in the program can push an otherwise-fine `.merge()` chain over the
+edge. It surfaces not as `TS2589` but as a `TS2345` assignability error
+naming an **uninstantiated** `Server` - the shape
+the server type collapses to when the compiler gives up mid-inference. The usual trigger is a
+**generic higher-order function that wraps the builder** (a
+`withX(app)` that threads the `Server` type through its own type
+parameters); merely having that file in the program can be enough. Treat these as real
+constraints of an inference-first framework:
+
+-
+Keep **service-layer types flat and explicitly annotated** - do not let
+inference-heavy generics thread the `Server` / registry type through your own code.
+
+-
+**Avoid generic HOF wrappers around the builder.** Wrap with a
+`defineRouterPlugin` (identity plugin) or compose with `.merge()` instead
+of a `withX(app)` that re-infers the whole server type.
+
+-
+Put an explicit `Promise` return annotation on async callbacks that thread
+framework types, so the compiler stops re-deriving the awaited type at each use.
+
+[!TIP]
+
+Both fixes preserve full type fidelity - the client derived from `typeof app` is
+exactly as precise after a `.merge()` or an `implement()` as it is for an
+inline route. Splitting or going contract-first costs you nothing at the call site.
+
 ### Still stuck?
 
 Run `nifra check --json` as the done-gate — it surfaces the import-chain leaks,
@@ -3195,7 +3371,7 @@ _over HTTP_. Both run the identical lifecycle — validation, middleware, contra
 
 ```ts
 // backend.ts — a normal @nifrajs/core server. Routes live at the full /api/... path.
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { t } from "@nifrajs/schema"
 
 export const backend = server()
@@ -3269,6 +3445,65 @@ Vite-backed dev server) routes every request through that same app's `fetch`. So
 the `/api/*` routes are served identically in development and production — there is
 nothing extra to wire for the dev loop.
 
+### Mounting, composition & path semantics
+
+A useful thing to know up front, because it is the opposite of some frameworks: in Nifra
+**composition and mounting are prefix-less, and paths stay absolute**. There is no
+per-mount base path, and nothing rewrites the request URL. Two mechanisms are involved and both
+leave the path untouched:
+
+-
+**
+`.merge()` (and contract-first `implement()`)
+**
+- the composition escape hatch for large apps. `merge()` folds another server's
+routes into this one _at the exact paths they were defined_, into a single shared path
+space. It takes no prefix argument; a path+method collision throws a
+`RouteConfigError` at merge time (fail-closed), so groups never silently shadow
+each other. Each domain therefore owns its full absolute paths (`/api/listings`,
+`/api/agents`), exactly as it would standalone.
+
+-
+**the `/api/*` auto-mount** - a path _guard_, not a rewrite.
+`createWebApp` hands the _same_ `Request` (its URL and body
+intact) to the backend when the pathname is exactly `apiPrefix` or under
+`apiPrefix + "/"`. The backend's own router then matches on
+`new URL(c.req.url).pathname` - the full, original path.
+
+The consequence for a handler: **
+`c.req.url` always carries the full, original path
+**
+- the same URL the caller sent. The `/api` prefix is _not_ stripped before a
+merged or mounted route sees it, and there is no `pathOf`-style helper that strips
+it. Whether a route was defined inline, merged in from a group, or reached through the HTTP
+mount, the pathname it observes is the request's own.
+
+```ts
+// backend.ts - compose domains with .merge(). Each group owns its FULL absolute paths.
+import { server } from "@nifrajs/core/server"
+
+const listings = server().get("/api/listings", (c) => {
+  // c.req.url is the ORIGINAL request URL - .merge() and the /api mount never strip the prefix.
+  const path = new URL(c.req.url).pathname // GET /api/listings  ->  "/api/listings"
+  return { path }
+})
+
+const agents = server().get("/api/agents", (c) => ({ ok: new URL(c.req.url).pathname }))
+
+// merge() folds both groups into ONE flat path space at their defined paths; a path+method clash
+// throws a RouteConfigError right here at merge time (fail-closed), never a silent shadow at runtime.
+export const backend = server().merge(listings).merge(agents)
+```
+
+**The one gotcha:** because nothing strips the prefix, a backend that will be
+mounted (or merged) under `/api` must **declare its routes at the full path**
+- `server().post("/api/sync", …)`, _not_ `.post("/sync", …)` in the
+hope that `/api` gets peeled off. Define `/sync` and a browser
+`POST /api/sync` returns the backend's 404: the router looks up
+`/api/sync` and finds only `/sync`. `apiPrefix` chooses
+_which_ requests are handed to the backend; it does not rewrite them, so the route paths
+and the caller's paths are one and the same.
+
 ### Calling /api/* from the browser
 
 With the routes mounted, a client island or component hits them with the same typed
@@ -3318,7 +3553,7 @@ to local policy, and exposes monotonic remaining time beside the existing cancel
 ### Clamp once at admission
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 
 const app = server({
   requestTimeoutMs: 2_000,
@@ -3357,6 +3592,177 @@ Configure a finite `requestTimeoutMs` before handing `c.budget` to a
 production adapter. The no-timeout compatibility path is deliberately unbounded and is not
 written to the wire.
 
+## Nifra - Execution causality
+
+> Carry one bounded, payload-free lineage across the durable seams a trace cannot span: commands, events, workflows, projections, and repairs.
+
+A trace describes one observation tree. Causality survives the seams a trace cannot: a command
+commits an event, a workflow resumes tomorrow, a projection consumes that event, and
+reconciliation repairs the drift. Same execution, four identities that used to stop at the
+boundary.
+
+### Tokens only, by construction
+
+A causality record has **no payload field**. There is nowhere to put a request
+body, a tenant identifier, or a URL, and unknown fields are rejected at every nesting level
+rather than carried along. Identities are bounded tokens, edge relations are bounded tokens,
+and the lineage stays safe to store and read during an incident.
+
+### Start at the boundary
+
+```ts
+import { createMemoryCausalityStore, startCausality } from "@nifrajs/core/causality"
+
+const recorder = createMemoryCausalityStore()
+const requestId = crypto.randomUUID()
+
+// One root node at the ingress boundary. executionId is the graph's identity:
+// generate it once, then propagate it.
+const step = startCausality("request", requestId, { executionId: crypto.randomUUID() })
+
+// step.context propagates; step.record is what a durable adapter appends.
+await recorder.record(step.record)
+```
+
+### Continue across seams
+
+```ts
+import { continueCausality, startCausality } from "@nifrajs/core/causality"
+
+const step = startCausality("request", crypto.randomUUID(), {
+  executionId: crypto.randomUUID(),
+})
+
+// The command this request caused. The edge relation is a bounded token.
+const command = continueCausality(step.context, "command", crypto.randomUUID(), {
+  relation: "caused",
+})
+
+// The event that command emitted, inside the same commit.
+const event = continueCausality(command.context, "event", crypto.randomUUID(), {
+  relation: "emitted",
+})
+```
+
+`joinCausality` merges several parents into one node, and refuses to join contexts
+from different executions: a graph that silently spanned two requests would be worse than no
+graph.
+
+### Propagation is a trust boundary
+
+```ts
+import {
+  causalityHeaders,
+  readCausalityHeaders,
+  startCausality,
+} from "@nifrajs/core/causality"
+
+const step = startCausality("request", crypto.randomUUID(), {
+  executionId: crypto.randomUUID(),
+})
+
+// Outbound: bounded headers only.
+await fetch("https://billing.internal/charge", {
+  headers: causalityHeaders(step.context),
+})
+
+// Inbound: never throws on hostile input.
+const request = new Request("https://api.example/charge")
+const parsed = readCausalityHeaders(request.headers)
+if (!parsed.success) {
+  // "missing" | "incomplete" | "invalid" | "unknown-field" - start a fresh graph.
+}
+```
+
+Inbound headers are **untrusted by default**. A caller does not get to attach
+their request to your graph unless you say so, so a service-to-service seam opts in explicitly
+and anything that fails the check starts a fresh execution instead of being believed.
+
+### Storage is yours
+
+`createMemoryCausalityStore()` is for development and tests. It is bounded, and it
+refuses to construct under `NODE_ENV=production`: in-memory evidence disappears on
+restart, which is exactly when an incident timeline matters. Production supplies a durable
+adapter behind the same `CausalityRecorder` interface, ideally appending in the same
+transaction as the effect it describes.
+
+### Traces still apply
+
+The two models compose. `@nifrajs/otel` turns the nearest observed ancestor into a
+span link, so an event consumed tomorrow links back to the request that emitted it rather than
+inventing a trace identity that never existed.
+
+## Nifra - Adapter certification
+
+> Prove a storage, cache, job, runtime, or event adapter against its interface and emit a hash-verifiable capability matrix.
+
+An interface is a promise. Certification is how an adapter proves it kept it, in a form someone
+else can check.
+
+### Profiles
+
+A profile is a named set of checks written against an interface, not an implementation:
+`cacheStoreCertificationProfile`, `jobStoreCertificationProfile`,
+`storageAdapterCertificationProfile`, `runtimeAdapterCertificationProfile`
+, and `eventDeliveryCertificationProfile`. Domain-specific seams define their own
+with `defineCertificationProfile`, which validates the profile at module load, so a
+check naming an undeclared capability fails before any adapter runs.
+
+### Certify an adapter
+
+```ts
+// doc-check: skip - createRedisCache stands in for the adapter under test
+import { test } from "bun:test"
+import {
+  assertAdapterCertification,
+  cacheStoreCertificationProfile,
+  certifyAdapter,
+} from "@nifrajs/testing/certification"
+
+test("the Redis cache adapter satisfies the cache contract", async () => {
+  const report = await certifyAdapter({
+    profile: cacheStoreCertificationProfile(),
+    adapterId: "redis-cache",
+    // A FRESH adapter per check, so one failure cannot contaminate the next.
+    createAdapter: () => createRedisCache(url),
+    cleanup: (adapter) => adapter.clear(),
+  })
+
+  assertAdapterCertification(report) // throws, naming every failed check
+})
+```
+
+Profiles are structural and dependency-free. A third-party adapter can certify itself in its own
+test suite without adopting anything else, which is the point: trust becomes portable rather
+than something we vouch for.
+
+### The report is the evidence
+
+```ts
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "profile": { "id": "cache-store", "version": 1 },
+  "adapterId": "redis-cache",
+  "capabilities": [
+    { "capability": "read-write", "status": "passed", "checks": ["set-get", "delete"] },
+    { "capability": "tag-invalidation", "status": "passed", "checks": ["invalidate-tag"] }
+  ],
+  "evidenceHash": "9f2c..."
+}
+```
+
+The capability matrix is the useful artifact. It says what an adapter supports, per capability,
+with the checks that back each one. `verifyAdapterCertification` recomputes
+`evidenceHash`, so a stored report can be checked rather than believed.
+
+### Failures carry a class, not a message
+
+A failed check records the error _class_ only. Provider messages routinely carry
+connection strings, tokens, and payload fragments, and evidence is meant to be shared, so it
+never becomes a place credentials leak. Cleanup errors cannot turn a failed functional check
+into a pass.
+
 ## Nifra — Framework contract
 
 > The one-page contract: LoaderContext shape, loader/action/meta/head signatures, the client↔server boundary, and the build-output contract — every signature verified against the source.
@@ -3636,13 +4042,13 @@ or `env`. Keep server-only imports out of a route file's top level.
 
 ### The build-output contract
 
-`nifra build` emits a content-hashed `dist/` plus a
-`manifest.json` you hand to `createWebApp` (`entry`,
+The programmatic `buildClient()` API emits a content-hashed directory plus a
+`manifest.json` you can hand to `createWebApp` (`entry`,
 `routes` for per-route preload, `css` + `routeStyles` for
 `<link>` injection).
 
 ```ts
-// `nifra build` → buildClient (Bun.build) writes dist/ + manifest.json. The contract:
+// buildClient() writes a browser bundle + manifest.json for custom build pipelines:
 {
   "entry": "/assets/_nifra-entry-HASH.js",        // the bootstrap module script
   "assets": ["/assets/…"],                          // every emitted chunk URL
@@ -3727,6 +4133,73 @@ const paths = prerendered.map((p) => p.path)
 await Bun.write("./dist/_routes.json", JSON.stringify(cloudflarePagesRoutes({ prerendered: paths })))
 ```
 
+### Publish a reusable router (library code vs app code)
+
+The fluent `server().get(...).post(...)` builder is **app code**: each
+call both infers the handler's context from the path _and_ returns a
+`Server` whose type has one more route intersected in (`AddRoute` /
+`RouteInfoFor`). That accreting registry type lives happily inside your own program,
+but it does **not** cleanly survive TypeScript's `.d.ts` declaration
+emit - for a router you **publish** as a package, the compiler has to serialize
+the whole inferred chain into your `.d.ts` and chokes (a `TS2883`-class
+error: the inferred type is too large to name), which forces ugly casts on the boundary. So a
+distributable router is written **contract-first** instead.
+
+The recipe: declare the API as a plain `defineContract({…})` object and
+**export it** (it is the consumer's typed-client source), then ship a factory that
+returns `implement(contract, handlers)`. The consumer mounts the router with one
+`.merge(...)` and derives its client straight from the exported contract value -
+`client(contract, url)`, no `typeof app` import crossing the package
+boundary. Pass a preamble as the third arg -
+`implement(contract, handlers, server().use(auth))` - to bake a middleware /
+`derive` chain into the router's routes (captured at registration).
+
+```ts
+// A PUBLISHABLE router - contract-first, so its types survive `.d.ts` emit for consumers.
+import { client } from "@nifrajs/client"
+import { defineContract, implement } from "@nifrajs/core/contract"
+import { server } from "@nifrajs/core/server"
+import { t } from "@nifrajs/schema"
+
+// --- in the package (say @your-org/billing) ---
+// 1. The CONTRACT is ONE plain declared object - methods, paths, schemas, no handlers.
+//    Export it: it is the single type the package publishes, and a consumer's typed client is
+//    built from THIS value (not from `typeof app`), so no internal server type crosses the seam.
+export const billingContract = defineContract({
+  getPlan:   { method: "GET",  path: "/billing/plan" },
+  subscribe: { method: "POST", path: "/billing/subscribe", body: t.object({ plan: t.string() }) },
+})
+
+// 2. A FACTORY closes over the host's dependencies and returns a real, mountable router.
+//    `implement` binds handlers to the contract; each handler's context is typed from the contract
+//    alone (`c.body` is { plan: string } below) - no per-route `AddRoute` inference accreting.
+export interface BillingDeps {
+  charge(plan: string): Promise<{ id: string }>
+}
+export function createBillingRouter(deps: BillingDeps) {
+  return implement(billingContract, {
+    getPlan:   () => ({ plan: "pro" }),
+    subscribe: (c) => deps.charge(c.body.plan),
+  })
+}
+
+// --- in the consuming app ---
+// 3. Mount the router with ONE `.merge()` - no per-route `.get()/.post()` chain to re-infer.
+const app = server().merge(createBillingRouter({ charge: async (plan) => ({ id: plan }) }))
+
+// 4. Build the client from the EXPORTED contract value - decoupled, no `typeof app` import needed.
+const api = client(billingContract, "https://api.example.com")
+const { data } = await api.billing.plan.get()          // GET  /billing/plan
+await api.billing.subscribe.post({ plan: "pro" })      // POST /billing/subscribe, body typed
+```
+
+Why this survives `.d.ts` emit where the fluent chain doesn't: the contract is a
+**plain declared object type** (`ContractShape`), fixed up front - there
+is no grow-the-registry-per-call inference to serialize, so its declaration is small and
+stable. The consumer still gets full end-to-end types both ways -
+`.merge()` threads the router's routes into the host app's registry, and
+`client(contract, url)` types every call from the same exported object.
+
 See [SSG & ISR](/docs/rendering) for prerendering, [Dev & HMR](/docs/dev) for the
 two dev loops and the `--port` flag, and [Loaders & actions](/docs/data) for the
 data layer in depth.
@@ -3767,7 +4240,7 @@ server, and every handler reads it as a typed `c.db`. This is how the scaffold w
 it — and it keeps the client out of each handler's imports.
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { desc } from "drizzle-orm"
 import { db, notes } from "./db"   // your Drizzle client + schema (what the scaffold generates)
 
@@ -3786,7 +4259,7 @@ Node, or `libSQL`/Turso anywhere. Open the connection once and query from your
 routes:
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { Database } from "bun:sqlite"        // Node: better-sqlite3 · edge: Turso/libSQL
 
 // Open the connection ONCE at module scope (the driver pools internally).
@@ -3920,7 +4393,7 @@ directly:
 
 ```ts
 // doc-check: skip — illustrates a third-party driver (postgres + drizzle); install those to run it.
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { drizzle } from "drizzle-orm/postgres-js"   // or node-postgres / neon-http
 import postgres from "postgres"
 import { eq } from "drizzle-orm"
@@ -3994,6 +4467,98 @@ Complete runnable references — a typed CRUD API you can diff your own against:
 `examples/db-sqlite` (the same API on raw `bun:sqlite`, parameterized
 queries, boundary validation).
 
+## Nifra - Failure laboratory
+
+> Replayable durable-failure schedules on virtual time: crash after commit, duplicate delivery, reordering, budget expiry, and checkpoint contention.
+
+Durable systems fail on a schedule you never chose: the crash lands between the commit and the
+publish, the queue delivers twice, the events arrive backwards. The laboratory lets you choose
+that schedule, then replay it exactly.
+
+### Seven failures worth testing
+
+-
+`crash` - stop dead at a named durability seam.
+
+-
+`duplicate-delivery` - deliver the same batch N times.
+
+-
+`reorder-events` - rotate a batch out of order.
+
+-
+`delay` - advance virtual time, with no real sleeping.
+
+-
+`expire-budget` - report zero remaining at a budget seam.
+
+-
+`lose-provider-reply` - run the call, then lose only its reply.
+
+-
+`contend-checkpoint` - make a checkpoint conflict.
+
+### Place the seams, schedule the failure
+
+```ts
+import { createFailureLab } from "@nifrajs/testing"
+
+const lab = createFailureLab({
+  seed: 77,
+  schedule: [
+    { kind: "duplicate-delivery", point: "relay.batch", copies: 3 },
+    { kind: "reorder-events", point: "relay.batch" },
+  ],
+})
+
+// The adapter under test just names its seams. Same seed, same schedule,
+// same result - every run.
+const delivered = lab.deliveries("relay.batch", ["evt-a", "evt-b", "evt-c"])
+```
+
+The controller is an off-hot-path port. Your adapter names its seams; the schedule decides what
+happens at them. Time is virtual, so a 24-hour delay costs nothing and nothing is flaky.
+
+### Assert the invariant, not the output
+
+```ts
+// doc-check: skip - commit/publish/outboxStillPending stand in for the system under test
+import { runFailureScenario } from "@nifrajs/testing"
+
+const report = await runFailureScenario(
+  {
+    name: "crash-after-commit",
+    execute: async (lab) => {
+      await commit()
+      lab.checkpoint("outbox.after-commit") // crashes here, per the schedule
+      await publish()
+      return "published"
+    },
+    // The scenario passes only if the invariant survives the failure.
+    verify: async ({ error }) => error !== undefined && (await outboxStillPending()),
+  },
+  { seed: 1, schedule: [{ kind: "crash", point: "outbox.after-commit" }] },
+)
+
+report.ok // did the invariant hold?
+report.replay // { seed, schedule } - reproduces this exact run
+```
+
+A scenario passes only when `verify` returns true after the failure. Losing the
+provider reply is not a bug; losing the money is. That distinction is the whole point.
+
+### Evidence is tokens only
+
+Injection evidence records the kind, the point, the occurrence, and the virtual time. Never
+payloads, provider results, exception messages, or stacks. A failing report carries the error
+_class_ and the exact `replay` inputs, so it reproduces from the report alone
+without leaking what flowed through the system.
+
+### Where it fits
+
+The same engine backs `nifra levels` L4. Contract invariants fuzz the HTTP surface;
+the laboratory covers the durable paths underneath, where the interesting failures live.
+
 ## Nifra — Fonts
 
 > Self-host web fonts with zero layout shift: a build-time Google Fonts downloader (the next/font equivalent) plus CLS-safe @font-face + preload primitives.
@@ -4096,62 +4661,196 @@ stylesheet can't redirect the download elsewhere — an SSRF gate), and caps eac
 Filenames are derived only from validated tokens plus a content hash, so there's no path
 traversal.
 
-## Nifra — Migrating from Express, Hono, Fastify & Elysia
+## Nifra 2.0 migration guide — upgrade from 1.x
 
-> Move a backend to Nifra: routing, middleware, validation, and body parsing map directly from Express, Hono, Fastify, and Elysia — and you gain a typed client, multi-runtime deploy, and optional SSR.
+> Upgrade a Nifra 1.x application to 2.0: automated package and import moves, opt-in runtime plugins, client and web changes, external auth mounts, and release verification.
 
-Nifra's `server()` is a chainable, Web-standard router — the move from Express, Hono,
-Fastify, or Elysia is mostly mechanical renames. What you gain: an end-to-end-typed client with
-zero codegen, schema validation built into the route, the same app on Bun / Node / Deno / the
-edge, and an SSR frontend whenever you want one.
+Nifra 2.0 removes the compatibility layer retained through 1.x and makes optional runtime
+systems explicit, instance-scoped plugins. The upgrade command handles deterministic package
+and import edits; this guide covers the structural changes it deliberately cannot guess.
 
-### How the concepts map
+### 1. Run the executable upgrade
 
-Express / Hono / Fastify
-Nifra
+```ts
 
-`app.get(path, handler)`
+```
 
-`server().get(path, handler)` — chainable, fully type-inferred
+The command updates existing `@nifrajs/*`, `nifra`, and
+`create-nifra` dependency ranges to `2.0.0` while preserving
+caret/tilde/exact style. It also replaces the removed `@nifrajs/budget` dependency
+with `@nifrajs/core` and moves its imports to
+`@nifrajs/core/budget`. Dry-run is the default; `--write` applies and
+verifies with `nifra check`.
 
-`req` / `res` · Hono `Context`
+### 2. Install optional server systems explicitly
 
-`c` — `c.req`, `c.params`, `c.query`; **return** a value (JSON) or a
-`Response`
+Idempotency, the effect ledger, MCP declarations, SSE, WebSockets, and Node-direct resolution
+are no longer enabled by server options, side-effect imports, or process-global state. Install
+only the systems an app uses with `.use()`; registration fails loudly if a required
+plugin is missing.
 
-`app.use(mw)` · Hono middleware
+```ts
 
-`.use()` + the `@nifrajs/middleware` pack (CORS, auth, rate limit, …)
+```
 
-`express.json()` / body parsing
-built in — declare a schema and the parsed body is typed
+The `@nifrajs/node` adapter installs `nodeDirect()` automatically.
+Only applications calling `app.resolveNode()` directly need to install it.
 
-Fastify JSON schema · `zod` middleware · Elysia `t`
+### 3. Use the lean package entry points
 
-`{ body, query, params }` validated by `t` (TypeBox) or any
-[Standard Schema](https://standardschema.dev)
+The `@nifrajs/core` and `nifra` roots now expose the lean HTTP server
+surface. Prefer `@nifrajs/core/server` for `server()`, and import
+contracts, assurance, capabilities, budgets, manifests, reflection, SSE, WebSockets, and
+other optional systems from their documented subpaths.
 
-`res.json(x)` / `reply.send(x)` / `c.json(x)`
+```ts
 
-`return x`
+```
 
-`app.listen(3000)`
+Contract-generated adversarial testing lives in `@nifrajs/testing`; the deprecated
+core invariant runner is removed.
 
-`app.listen()` (Bun) · `@nifrajs/node` · `@nifrajs/deno` ·
-`toFetchHandler` (edge)
+### 4. Update full-stack backend mounts
 
-OpenAPI plugins / swagger
-generated from the same `t` schemas — no second source of truth
+`createWebApp` now auto-mounts a backend only through the platform-aware,
+symbol-keyed `BackendMount` interface. The old duck-typed
+`api.fetch(url, init)` convention is removed. Normal applications should pass the
+result of `inProcessClient(backend)` or `testClient(backend)`; both
+already implement the interface and forward `env` and `waitUntil`.
 
-### Express → Nifra
+```ts
 
-The handler returns its result instead of calling `res.json`, and validation moves
-onto the route. The client then infers all of this for free.
+```
+
+### 5. Declare external library mounts
+
+Better Auth and similar libraries can own routes such as `/auth/**` outside the
+Nifra typed contract. A relative fetch to that library is intentional, but otherwise resembles
+a hand-rolled own-API call. Declare only the exact mounted prefix in
+`nifra.check.json` so `nifra check` does not keep CI red:
 
 ```ts
-// Express
-app.get("/users/:id", (req, res) => res.json({ id: req.params.id }))
-app.post("/users", express.json(), (req, res) => res.status(201).json(create(req.body)))
+
+```
+
+Prefixes are segment-anchored: `/auth` covers `/auth` and its children,
+never `/authors`. Traversal paths are not suppressed. The normalized allowlist is
+echoed in human, JSON, and MCP check results, so every bypass remains auditable. This option
+affects only the typed-client lint; it does not mount, authorize, or trust the library.
+
+### 6. Narrow typed-client failures by status
+
+Routes with declared error schemas now return a failure union discriminated by HTTP status.
+After checking `!result.ok`, also narrow `result.status` before reading
+typed failure data. Undeclared statuses and transport status `0` remain unknown.
+
+```ts
+
+```
+
+### 7. Apply the remaining web and protocol changes
+
+-
+Redirects accept an options object as their second argument.
+
+```ts
+
+```
+
+-
+Replace the removed prerender wrapper with `enumerateStaticRoutes()`.
+
+- Fragment navigation resolves element IDs only.
+
+-
+MCP Apps metadata uses only `_meta.ui.resourceUri`; remove the deprecated flat
+`ui/resourceUri` key.
+
+-
+Telemetry integrations use `ObservationAdapter`; the
+`AgentSpan`, `AgentSpanExporter`, and `SpanExporter` aliases
+are removed.
+
+- Invalid HTTP method overrides always fail closed with 400.
+
+-
+`nifra build` always emits a complete deploy directory and defaults to Bun;
+`nifra start` runs the generated `server.js`.
+
+### 8. Run the release gates
+
+-
+Run `nifra check --json` and fix every error.
+
+-
+If the project has `nifra.assurance.ts`, run `nifra assure --json`.
+
+-
+If capabilities are configured, review a new snapshot and run
+`nifra capabilities check --json`.
+
+- Run the application test suite and a production build.
+
+-
+Exercise authentication, redirects, backend mounting, SSE/WebSocket routes, and each deploy
+adapter the application uses.
+
+## Nifra — Migrating from Express, Hono, Fastify & Elysia
+
+> Move a backend to Nifra: routing, middleware, validation, and body parsing map directly from Express, Hono, Fastify, and Elysia — and you gain a typed client, multi-runtime deploy, and optional SSR.
+
+Nifra's `server()` is a chainable, Web-standard router — the move from Express, Hono,
+Fastify, or Elysia is mostly mechanical renames. What you gain: an end-to-end-typed client with
+zero codegen, schema validation built into the route, the same app on Bun / Node / Deno / the
+edge, and an SSR frontend whenever you want one.
+
+### How the concepts map
+
+Express / Hono / Fastify
+Nifra
+
+`app.get(path, handler)`
+
+`server().get(path, handler)` — chainable, fully type-inferred
+
+`req` / `res` · Hono `Context`
+
+`c` — `c.req`, `c.params`, `c.query`; **return** a value (JSON) or a
+`Response`
+
+`app.use(mw)` · Hono middleware
+
+`.use()` + the `@nifrajs/middleware` pack (CORS, auth, rate limit, …)
+
+`express.json()` / body parsing
+built in — declare a schema and the parsed body is typed
+
+Fastify JSON schema · `zod` middleware · Elysia `t`
+
+`{ body, query, params }` validated by `t` (TypeBox) or any
+[Standard Schema](https://standardschema.dev)
+
+`res.json(x)` / `reply.send(x)` / `c.json(x)`
+
+`return x`
+
+`app.listen(3000)`
+
+`app.listen()` (Bun) · `@nifrajs/node` · `@nifrajs/deno` ·
+`toFetchHandler` (edge)
+
+OpenAPI plugins / swagger
+generated from the same `t` schemas — no second source of truth
+
+### Express → Nifra
+
+The handler returns its result instead of calling `res.json`, and validation moves
+onto the route. The client then infers all of this for free.
+
+```ts
+// Express
+app.get("/users/:id", (req, res) => res.json({ id: req.params.id }))
+app.post("/users", express.json(), (req, res) => res.status(201).json(create(req.body)))
 
 // nifra — return the value (or a Response); c is Web-standard; the body is parsed + validated
 server()
@@ -4438,7 +5137,7 @@ boundary _before_ your handler runs — invalid input is rejected with a 422, so
 handler only ever sees well-formed data.
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { GetUser } from "./schema"
 
 export const app = server().get("/users/:id", GetUser, (c) => {
@@ -4481,7 +5180,7 @@ routes and their schemas — generated lazily on first request, never hand-writt
 `ui: true` to also serve a Scalar reference page.
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { openapi } from "@nifrajs/middleware"
 import { GetUser } from "./schema"   // the contract defined above
 
@@ -4523,10 +5222,132 @@ coupling — server code never ships to the client.
 The generated OpenAPI document is a structural subset of 3.1 derived from your schemas;
 it reflects exactly what the routes declare, not hand-authored prose.
 
+## Nifra - Verification ladder
+
+> Five cumulative levels, from a typed contract to contract-derived invariant tests, that say what a Nifra project actually proves.
+
+"It compiles" and "it is secure" are different claims. The ladder makes the difference
+legible: five levels, each earned, so a project can state what it proves instead of what it
+hopes.
+
+### The five levels
+
+Levels are **cumulative**. A level only counts when every level below it holds,
+so `achieved` is the highest rung with unbroken support underneath, and it is
+`-1` when even L0 fails.
+
+-
+**L0 typed contract** - `nifra check` passes: the frontend and
+backend cannot have silently diverged.
+
+-
+**L1 route assurance** - every route is classified, and the enforcement a rule
+requires is actually installed.
+
+-
+**L2 capability lockfile** - declared effects match a reviewed lockfile, so a
+route that starts writing to the database shows up in review.
+
+-
+**L3 route manifest** - the committed trust artifact still matches the routes,
+evidence, effects, and response classification it was emitted from.
+
+-
+**L4 invariant-tested** - contract-derived invariants ran against an isolated
+executor with nothing skipped.
+
+### Run it
+
+```ts
+# What does this project prove right now?
+nifra levels
+
+# Fail CI below a level the project already reached.
+nifra levels --min 2
+
+# The same report an agent reads over MCP (nifra_levels).
+nifra levels --json
+```
+
+```ts
+L0  typed contract        ok
+L1  route assurance       ok
+L2  capability lockfile   ok
+L3  route manifest        FAIL  manifest drifted from routes: run `nifra manifest emit`
+L4  invariant-tested      FAIL  no isolated invariant executor configured
+
+achieved: 2
+```
+
+Every level that does not hold explains itself, so the output is a work list rather than a
+verdict. `--min <n>` is the CI floor: pin it to the level you have reached and
+the build fails when a change quietly costs you a rung.
+
+### Wiring the levels
+
+L0 needs nothing. L1 through L4 hang off `nifra.assurance.ts`, and each one you
+configure is a level you can start claiming.
+
+```ts
+// nifra.assurance.ts
+// doc-check: skip - policy rules and the isolated executor are app-specific
+import { defineAssuranceConfig } from "@nifrajs/core/assurance"
+import { backend } from "./backend"
+
+export default defineAssuranceConfig({
+  source: backend,
+  policy: { rules: [/* ... */] },
+  capabilities: { lockfile: "capabilities.lock.json", policy: { /* ... */ } },
+  manifest: { path: "nifra.manifest.json" },
+  invariants: {
+    // L4 fuzzes the contract, so it needs an app you are willing to throw hostile
+    // input at. Point this at an isolated instance, never a live one.
+    executor: (request) => backend.fetch(request),
+  },
+})
+```
+
+L4 requires an **explicit** executor. Invariant runs send deliberately hostile
+input, so nifra will not guess which app to point them at; a level that fuzzed your live
+server by default would be a footgun, and a skipped route is reported rather than passed over
+in silence.
+
+### For coding agents
+
+The `nifra_levels` MCP tool returns the same
+`{ achieved, levels[] }` report. An agent can read what its change proved, and a
+level that regressed comes back with the reason it broke.
+
 ---
 
 # Package reference (READMEs)
 
+## @nifrajs/agent-telemetry
+
+Child-span telemetry for AI tool calls made through Nifra tool and MCP endpoints.
+
+```sh
+bun add @nifrajs/agent-telemetry @nifrajs/otel
+```
+
+```ts
+import { agentTelemetry, consoleAgentExporter } from "@nifrajs/agent-telemetry"
+
+app.use(agentTelemetry({ exporter: consoleAgentExporter() }))
+```
+
+Requests under `/_nifra/tool/*` and requests to `/mcp` receive tool-name, input-size, output-size,
+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.
+
+## 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/auth
 
 Session primitives for nifra — signed-cookie + server-store sessions, CSRF, and route guards. Bring your own identity (Better Auth / Lucia / OAuth); nifra owns the session.
@@ -4586,7 +5407,7 @@ export const auth = createBetterAuth({
 
 ```ts
 // server.ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { betterAuth } from "@nifrajs/better-auth"
 import { auth } from "./auth"
 
@@ -4655,38 +5476,6 @@ 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/budget
-
-Compatibility import for the request-deadline mechanics owned by `@nifrajs/core/budget`. Existing
-Nifra, Hono, and Fetch consumers can keep this import unchanged; new core consumers may use the
-subpath directly. Both paths resolve to the same implementation and classes.
-
-```ts
-import {
-  assertBudgetRemaining,
-  createRequestBudget,
-  withDeadlineHeader,
-} from "@nifrajs/budget"
-
-const budget = createRequestBudget({
-  deadline: Date.now() + 2_000,
-  signal: request.signal,
-})
-
-assertBudgetRemaining(budget, 100)
-await fetch(url, {
-  signal: budget.signal,
-  headers: withDeadlineHeader(undefined, budget.child(50)),
-})
-```
-
-The wire value is an absolute Unix epoch deadline. `remaining()` samples wall time once, then uses a
-monotonic clock so NTP changes cannot extend or shorten admitted work. A budget does not choose retry,
-provider, tenant, or money policy; it only answers how much time remains.
-
-Nifra route handlers receive the same primitive as `c.budget`. `c.signal` remains the cancellation
-signal and aborts at the effective server deadline.
-
 ## @nifrajs/cache
 
 Typed KV cache for nifra — **TTL**, **stale-while-revalidate**, **tag invalidation**, and **single-flight
@@ -4742,6 +5531,14 @@ the Cache API) via a `CacheStore` for anything that should survive across reques
 - `cache.wrap(key, loader, { ttlMs?, swrMs?, tags? })` · `get` · `has` · `set` · `delete` · `invalidateTag` · `clear`.
 - `MemoryCache({ maxEntries?, now? })` — the default store; implement `CacheStore` for your own.
 
+## 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/cli
 
 The `nifra` CLI — zero-config dev/build/start for a nifra app, plus the agent surfaces (`nifra context`,
@@ -4750,8 +5547,8 @@ The `nifra` CLI — zero-config dev/build/start for a nifra app, plus the agent
 
 ```
 nifra dev     [--port <n>] [--poll]       True-HMR dev server (Vite + nifra SSR).
-nifra build   [--out <dir>]               Content-hashed client bundle + manifest.json.
-nifra start   [--port <n>] [--out <dir>]  Serve the built app (client + SSR) on Bun.
+nifra build   [--out <dir>] [--target <t>]  Complete deploy directory; target defaults to Bun.
+nifra start   [--port <n>] [--out <dir>]   Run the generated Bun server at <out>/server.js.
 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.
@@ -4816,6 +5613,17 @@ 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.
 
+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:
+
+```json
+{ "externalMounts": ["/auth"] }
+```
+
+The match is segment-anchored (`/auth` never suppresses `/authors`) and traversal paths are rejected.
+The normalized prefixes are echoed in human, JSON, and MCP results so the lint bypass stays auditable.
+This suppresses only the typed-client diagnostic; it does not mount or authorize the external handler.
+
 ## For AI coding agents
 
 **`nifra context`** prints this project's actual surface — API routes (from `backend.routes()`), page
@@ -4842,6 +5650,10 @@ an agent can act on the project, not just read about it. Core tools:
 - **`nifra_check`** — run the drift gate and get the structured `{ ok, typecheck, diagnostics[] }`
   result with suggestions, so the agent verifies its own work and fixes each diagnostic before finishing.
 - **`nifra_assure`** — evaluate `nifra.assurance.ts` and return the complete per-route evidence report.
+- **`nifra_levels`** - compute the cumulative verification ladder (L0 typed contract, L1 route
+  assurance, L2 capability lockfile, L3 trust manifest, L4 contract invariants) and return
+  `{ achieved, levels[] }`, so an agent can see what its change proves and read why a level it lost
+  no longer holds.
 - **`nifra_doctor`** — catch imported packages missing from `package.json`; with `autoFix:true`, write
   safe dependency entries when a version can be inferred locally and return exact `bun add` commands
   for anything that needs a package-manager decision.
@@ -4959,7 +5771,7 @@ bun add @nifrajs/core
 ```
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 
 const app = server()
   .get("/users/:id", (c) => ({ id: c.params.id }))
@@ -4969,6 +5781,15 @@ const app = server()
 export type App = typeof app // hand this to @nifrajs/client for end-to-end types
 ```
 
+`@nifrajs/core` and `@nifrajs/core/server` expose the same lean common runtime. Optional systems are
+available only from their explicit subpaths, so an ordinary HTTP server never evaluates them:
+
+```ts
+import { defineContract, implement } from "@nifrajs/core/contract"
+import { startCausality } from "@nifrajs/core/causality"
+import { defineAssurancePolicy } from "@nifrajs/core/assurance"
+```
+
 - **Inline or contract-first.** Write routes inline (types inferred from the
   builder), or `defineContract(...)` + `implement(...)` for a decoupled, versionable
   surface — handlers lift over unchanged.
@@ -4989,6 +5810,33 @@ export type App = typeof app // hand this to @nifrajs/client for end-to-end type
   IP-restriction, and security-header modules publish reflection-safe enforcement evidence.
   An ordered `AssurancePolicy` classifies every route and fails closed on missing or forbidden
   evidence without adding work to the request path.
+- **Owned effect execution.** `executeCapability()` correlates intent and terminal evidence with an
+  opaque `effectId`, records outcomes automatically, and forwards request cancellation. Add
+  order-scoped `aroundCapability()` policies for async approval/admission; they receive token-only
+  metadata, have bounded timeouts, and must call `next()` exactly once before the effect can run.
+- **Durable workflows (opt in).** `@nifrajs/core/durable-execution` provides tenant/principal-bound,
+  signed single-use approval resumes; a durable effect journal + reconciliation scanner; and a typed
+  saga state machine with reverse compensation, retry/backoff, and ambiguous-crash detection. Production
+  constructors reject stores that do not declare `durability: "durable"`. Operational scans use bounded
+  cursor pages through `reconcileEffectsPage()` / `reconcileSagasPage()`. Provider-confirmed manual
+  review uses effect-ID-bound `resolveAmbiguity()`, followed by `resume()` or `compensate()`.
+- **Production durable adapters.** `@nifrajs/core/durable-adapters` supplies
+  `PostgresDurableExecutionAdapter`, `SQLiteDurableExecutionAdapter`, and
+  `DurableObjectExecutionAdapter`. Each exposes compatible `effects`, `approvals`, `sagas`, and
+  `leases` stores. Run `runDurableExecutionAdapterConformance()` against the deployment backend.
+- **Bounded reconciliation workers.** `@nifrajs/core/reconciliation-worker` runs effect or saga
+  scans under an atomic lease with durable cursor checkpoints, a finite page budget, bounded handler
+  concurrency, filters, cancellation, and token-only metrics. A worker invocation always terminates.
+- **Rich wire values (opt in).** `@nifrajs/core/wire` round-trips dates, bigints, maps, sets, binary,
+  shared references, and cycles through JSON transports. Decoding validates every reachable shape,
+  preserves owned `__proto__` keys without prototype mutation, and enforces configurable node, depth,
+  collection-entry, and decoded-byte limits.
+- **Versioned transport codecs (opt in).** Add `.use(transportCodecs(registry))` from
+  `@nifrajs/core/transport-plugin` and configure the typed
+  client's `transport` option with the same registry. `@nifrajs/core/transport-codec` negotiates
+  bounded HTTP representations and supplies the same frame/loader adapters for WebSockets and
+  deferred data. Import `richWireCodec()` from `@nifrajs/core/transport-codec-rich`; the separate
+  subpath keeps rich-wire code out of plain JSON bundles.
 
 ```ts
 import { defineAssurancePolicy, evaluateRouteAssurance, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
@@ -5094,7 +5942,7 @@ deno add npm:@nifrajs/deno   # or import npm:@nifrajs/deno directly
 ```
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { serve } from "@nifrajs/deno"
 
 const app = server().get("/users/:id", (c) => ({ id: c.params.id }))
@@ -5129,6 +5977,32 @@ 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/devtools
+
+Interactive request-trace DevTools for `nifra dev`, with a secured SSE stream and browser overlay.
+
+```sh
+bun add -d @nifrajs/devtools
+```
+
+```ts
+import { devtools } from "@nifrajs/devtools"
+
+app.use(devtools())
+```
+
+The plugin is enabled by default only when `NODE_ENV=development`. It records a bounded event buffer
+and serves the overlay stream at `/_nifra/devtools`; remote hosts and cross-origin access stay denied
+unless explicitly allowed. Leave it unregistered in production for zero request-path overhead.
+
+## 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/env
 
 Typed, validated environment variables. Define a schema once at startup; get a **frozen, typed**
@@ -5215,6 +6089,14 @@ lineage metadata.
 
 See the [nifra docs](https://github.com/nifrajs/nifra#readme).
 
+## 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.
@@ -5422,6 +6304,78 @@ export default {
 - `queue.counts()` → `{ pending, active, dead }`. `queue.store` — the underlying store.
 - Stores: `MemoryJobStore`. Backoff: `exponentialBackoff`, `fixedBackoff`, `noBackoff`.
 
+## 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/mcp
+
+Build transport-agnostic MCP servers and interactive MCP Apps for Nifra applications.
+
+```sh
+bun add @nifrajs/mcp
+```
+
+```ts
+import { createMcpServer, defineMcpTool } from "@nifrajs/mcp"
+
+const tools = [
+  defineMcpTool({
+    name: "health",
+    description: "Report service health",
+    handler: () => ({ text: "ok" }),
+  }),
+]
+
+const mcp = createMcpServer({ name: "orders", version: "1.0.0", tools })
+```
+
+Mount `mcp.fetch` at `POST /mcp`. The package also exposes the JSON-RPC protocol and Streamable HTTP
+layers directly, plus `defineMcpWidget` and the React adapter for tool results that render UI in MCP
+hosts.
+
+## 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/mcp-db
+
+Expose an allowlisted SQLite schema as a fail-closed MCP server, with opt-in read-only queries.
+
+```sh
+bun add @nifrajs/mcp-db
+```
+
+```ts
+import { Database } from "bun:sqlite"
+import { serveDatabaseAsMcp } from "@nifrajs/mcp-db"
+
+const mcp = serveDatabaseAsMcp(new Database("app.db"), {
+  tables: ["habits", "entries"],
+})
+```
+
+Only `list_tables` and `describe_table` are exposed by default, restricted to the explicit table
+allowlist. `run_query` requires an authorization hook and is guarded by SQLite query-only mode,
+single-statement/read-only checks, query-plan verification, and bounded output. D1 is not supported
+because it cannot provide the same engine-level read-only guarantee.
+
+## 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/middleware
 
 Composable, dependency-light middleware for [nifra](../../README.md) — CORS, security headers, body
@@ -5433,7 +6387,7 @@ bun add @nifrajs/middleware
 ```
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import {
   bodyLimit,
   cors,
@@ -5510,6 +6464,34 @@ 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/mock
+
+Generate deterministic mock responses from a Nifra application's reflected response contracts.
+
+```sh
+bun add -d @nifrajs/mock
+```
+
+```ts
+import { createMockServer } from "@nifrajs/mock"
+import { app } from "./app"
+
+const mock = createMockServer(app, { seed: 42 })
+const response = await mock.fetch(new Request("http://local.test/users/1"))
+```
+
+The mock server matches reflected routes and synthesizes values from supported JSON Schema keywords.
+Unsupported or unsatisfiable schemas fail explicitly instead of returning known-invalid data. Use a
+fixed seed when responses must be replayable across local development and CI.
+
+## 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/node
 
 Run a [nifra](../../README.md) app on Node's `http` server — nifra's ergonomics, deployed
@@ -5520,7 +6502,7 @@ bun add @nifrajs/node   # or: npm add @nifrajs/node
 ```
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { serve } from "@nifrajs/node"
 
 const app = server().get("/users/:id", (c) => ({ id: c.params.id }))
@@ -5644,8 +6626,7 @@ inventing trace identity.
 
 ## Adapters
 
-Implement `ObservationAdapter` to send spans wherever you collect them. `SpanExporter` remains as a
-backwards-compatible type alias:
+Implement `ObservationAdapter` to send spans wherever you collect them:
 
 ```ts
 interface ObservationAdapter {
@@ -5678,6 +6659,37 @@ 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/prompt
+
+Provider-neutral, type-safe prompts with Standard Schema input and validated structured output.
+
+```sh
+bun add @nifrajs/prompt
+```
+
+```ts
+import { prompt } from "@nifrajs/prompt"
+import { t } from "@nifrajs/schema"
+
+const extract = prompt("Extract the contact from the text.")
+  .input(t.object({ text: t.string() }))
+  .output(t.object({ name: t.string(), email: t.string({ format: "email" }) }))
+
+const contact = await extract.run({ text }, { complete: callYourProvider })
+```
+
+The package imports no vendor SDK. Supply a `complete` adapter for your provider; inputs are validated
+before the call and model output is parsed and validated before it reaches application code. An optional
+`heal` hook can repair and retry invalid structured output.
+
+## 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/runner
 
 Run requests through a nifra app and capture **structured results** — the shared engine behind the
@@ -5727,7 +6739,7 @@ bun add @nifrajs/schema
 ```
 
 ```ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { t, toOpenAPI } from "@nifrajs/schema"
 
 const app = server().post("/users", { body: t.object({ name: t.string(), age: t.integer() }) }, (c) => ({
@@ -5747,6 +6759,22 @@ const openapi = toOpenAPI(app) // OpenAPI 3.1
   `operationId`s); also works on a live app. Routes using a BYO Standard Schema are
   emitted without a detailed schema (Standard Schema exposes no JSON Schema).
 
+### `t` vs bring-your-own (bundle size)
+
+`t` is the batteries-included default because a TypeBox schema *is* a JSON Schema: it gives you
+OpenAPI + MCP `tools/list` for free and compiles to a fast validator. That completeness has a
+cost - TypeBox carries the whole JSON Schema type system, so `t` adds meaningful bytes to a bundle.
+
+nifra validates through **Standard Schema**, so any Standard-Schema validator works on a route with
+no adapter - `{ body: v.object({ ... }) }` with valibot, for instance. A validated app built on a
+lean validator like valibot is a fraction of the size (measured ~16 KB gzipped), which matters for
+edge/Workers cold-starts. The trade is the one noted above: a bring-your-own validator exposes no
+JSON Schema, so those routes carry no OpenAPI/MCP detail.
+
+Rule of thumb: reach for `t` when you want the contract (OpenAPI/MCP) for free; bring valibot (or any
+Standard-Schema validator) when bundle size on the edge is the priority. Both are first-class - the
+choice is per route, and you can mix them in one app.
+
 ### `toOpenAPI` coverage
 
 It emits `paths`, `parameters` (path + object query), `requestBody`, and `responses`, plus:
@@ -5835,6 +6863,14 @@ import { assertSafeKey, StorageKeyError } from "@nifrajs/storage"
 - `assertStorageAdapterConformance({ createAdapter })` — dependency-free executable adapter contract.
 - Optional interfaces: `PagedStorageAdapter` · `PresignableStorageAdapter` · `MovableStorageAdapter`.
 
+## 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/testing
 
 Contract-derived adversarial testing and stateful in-process helpers for Nifra apps.
@@ -6004,6 +7040,14 @@ that every call carries and captures cookies via a shared jar.
 
 For a **stateless** request (no cookies), use `testClient` from `@nifrajs/client` directly.
 
+## 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/uploads
 
 File-upload hardening for nifra — magic-byte MIME detection, size + type validation, short-TTL signed download URLs, and EXIF/metadata stripping. Dependency-free, edge-safe.
@@ -6330,7 +7374,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/agent-telemetry
 
-`AgentSpan`, `AgentSpanExporter`, `agentTelemetry`, `AgentTelemetryOptions`, `consoleAgentExporter`
+`agentTelemetry`, `AgentTelemetryOptions`, `consoleAgentExporter`
 
 ## @nifrajs/auth
 
@@ -6338,7 +7382,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/better-auth
 
-`betterAuth`, `BetterAuthLike`, `BetterAuthOptions`, `getSession`, `requireSession`, `RequireSessionOptions`, `SessionOf`
+`authed`, `AuthedOptions`, `betterAuth`, `BetterAuthLike`, `BetterAuthOptions`, `getSession`, `Principal`, `PrincipalFor`, `requirePrincipal`, `requireSession`, `RequireSessionOptions`, `SessionOf`, `SessionUserOf`, `WithPrincipal`
 
 ## @nifrajs/cache
 
@@ -6346,7 +7390,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/client
 
-`ActionArgs`, `ActionData`, `ApiError`, `ApiProxy`, `client`, `ClientOptions`, `FetchFn`, `inProcessClient`, `InProcessClient`, `Jsonify`, `LoaderArgs`, `LoaderData`, `RegistryOf`, `Result`, `SubscribeOptions`, `Subscription`, `testClient`, `Treaty`, `TreatyFromRegistry`
+`ActionArgs`, `ActionData`, `ApiError`, `ApiProxy`, `client`, `ClientOptions`, `ClientRetryOptions`, `FetchFn`, `inProcessClient`, `InProcessClient`, `InProcessClientOptions`, `Jsonify`, `LoaderArgs`, `LoaderData`, `RegistryOf`, `ResponseContractViolation`, `Result`, `SubscribeOptions`, `Subscription`, `testClient`, `Treaty`, `TreatyFromRegistry`, `WsCallOptions`, `WsHandle`
 
 ## @nifrajs/content
 
@@ -6354,7 +7398,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/core
 
-`AdmissionController`, `AdmissionDecision`, `AnyServer`, `attachWebSocket`, `commonSecretPatterns`, `Context`, `ContextForOp`, `ContractShape`, `CookieOptions`, `defineContract`, `defineIdentityPlugin`, `definePlugin`, `defineRouterPlugin`, `DurableObjectNamespaceLike`, `ExecutionContext`, `FRAMEWORK_NAME`, `FrameworkError`, `FrameworkName`, `Handler`, `HandlersFor`, `IdentityPlugin`, `implement`, `InferInput`, `InferOutput`, `jsonLogger`, `LogFields`, `Logger`, `McpPromptDescriptor`, `McpResourceDescriptor`, `Method`, `METHODS`, `Middleware`, `NifraPlugin`, `NifraWebSocket`, `NodeServeOutcome`, `OnRequestResult`, `OperationDef`, `Params`, `parseCookies`, `Platform`, `Prettify`, `PromptArgument`, `PromptMessage`, `redactLogFields`, `RedactOptions`, `Registry`, `RegistryFor`, `RegistryFromImpl`, `ResponseControls`, `ResponseDef`, `ResponseFinalization`, `robots`, `RobotsOptions`, `RobotsRule`, `RouteConfigError`, `RouteConfigErrorCode`, `RouteDescriptor`, `RouteInfo`, `Router`, `RouterMatch`, `RouteSchema`, `RunningServer`, `ScheduledController`, `ScheduledHandler`, `serializeCookie`, `server`, `Server`, `ServerOptions`, `SignatureEncoding`, `signValue`, `silentLogger`, `sitemap`, `SitemapChangeFreq`, `SitemapEntry`, `SitemapOptions`, `sse`, `SSEContext`, `SSEInit`, `SSEMessage`, `SSEStream`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `StandardTypes`, `StandardWebSocket`, `toFetchHandler`, `ToolAnnotations`, `TopicRegistry`, `typedSSEStream`, `TypedSSEStream`, `unsignValue`, `validateStandard`, `ValidationOutcome`, `verifyWebhook`, `VerifyWebhookOptions`, `Version`, `VERSION`, `WebhookFailureReason`, `WebhookProvider`, `WebhookResult`, `WebSocketContext`, `WebSocketData`, `WebSocketHandler`, `WebSocketUpgradeOutcome`
+`Version`, `VERSION`
 
 ## @nifrajs/cron
 
@@ -6394,7 +7438,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/mcp
 
-`bridgeScript`, `createMcpServer`, `CreateMcpServerOptions`, `defineMcpTool`, `DefineMcpToolOptions`, `defineMcpWidget`, `DefineMcpWidgetOptions`, `McpAppBridge`, `McpHttpOptions`, `McpServer`, `McpToolHandlerResult`, `McpUiIntent`, `McpWidget`, `respondMcpHttp`, `uiResourceMeta`, `widgetDocument`
+`bridgeScript`, `createMcpServer`, `CreateMcpServerOptions`, `defineMcpTool`, `DefineMcpToolOptions`, `defineMcpWidget`, `DefineMcpWidgetOptions`, `InferOutput`, `McpAppBridge`, `McpHttpOptions`, `McpServer`, `McpToolHandlerResult`, `McpUiIntent`, `McpWidget`, `respondMcpHttp`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `uiResourceMeta`, `widgetDocument`
 
 ## @nifrajs/mcp-db
 
@@ -6414,7 +7458,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/otel
 
-`ActiveObservation`, `AttributeValue`, `causalitySpanLink`, `combineObservationAdapters`, `consoleSpanExporter`, `createObservationLifecycle`, `EndObservation`, `formatTraceparent`, `generateSpanId`, `generateTraceId`, `NifraSpan`, `ObservationAdapter`, `ObservationClock`, `ObservationContext`, `ObservationLifecycle`, `ObservationLifecycleOptions`, `ObservationLink`, `ObservationParent`, `ParsedTraceparent`, `parseTraceparent`, `SpanExporter`, `SpanStatus`, `StartObservation`, `TraceContext`, `traceHeaders`, `tracing`, `TracingOptions`
+`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/prompt
 
@@ -6442,7 +7486,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumeratePrerenderedPaths`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `hashQueryKey`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NavigateOptions`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `setBrowserNavigate`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `styles`, `Submission`, `SubmitOptions`, `withISR`
+`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `hashQueryKey`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NavigateOptions`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `setBrowserNavigate`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `styles`, `Submission`, `SubmitOptions`, `withISR`
 
 ## @nifrajs/web-preact