@nifrajs/cli 0.1.0-alpha.1 → 0.1.0-alpha.2

package/docs/llms-full.txt

@@ -361,6 +361,7 @@ and `c.query` are the _validated_ types, and a bad request gets a structured
 `422` automatically. Path params (`:id`) are typed from the pattern.
 
 ```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 { z } from "zod"   // any Standard Schema works: zod, valibot, arktype…
 
@@ -412,6 +413,7 @@ body, or return type is a compile error. The result is the same `app` the inline
 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 { z } from "zod"
 
@@ -574,6 +576,7 @@ and the UI reflects it immediately. When the action resolves the real data takes
 failed submit **reverts** automatically — no manual rollback bookkeeping.
 
 ```ts
+// doc-check: skip — component-body fragment: `id` and `todo` are the row's props.
 import { useFetcher } from "@nifrajs/web-react/fetcher"
 
 // Optimistic UI: while a submit is in flight, read the expected value from the in-flight
@@ -691,8 +694,10 @@ carries an `x-nifra-isr: hit | stale | miss` header.
 ```ts
 // server.ts — wrap the app with Incremental Static Regeneration.
 import { createWebApp, withISR, MemoryCacheStore } from "@nifrajs/web"
+import { reactAdapter } from "@nifrajs/web-react"
+import { clientEntry, manifest } from "./server-manifest" // generated by buildServer
 
-const app = createWebApp({ adapter, manifest, clientEntry, api })
+const app = createWebApp({ adapter: reactAdapter, manifest, clientEntry })
 const store = new MemoryCacheStore() // dev / single-instance only
 
 // GET text/html responses are cached + served stale-while-revalidate. Default freshness 60s.
@@ -719,6 +724,7 @@ before it's trusted, so a corrupt or version-skewed entry is treated as a miss,
 broken.
 
 ```ts
+// doc-check: skip — Workers entry: `Env`/`ExecutionContext` globals + your `app` from server.ts.
 // worker.ts — production uses a SHARED store so the cache + purges hold across instances.
 import { withISR, KVCacheStore, revalidateEndpoint } from "@nifrajs/web"
 
@@ -760,6 +766,7 @@ cache. Pass the same `draftSecret` to `createWebApp` and
 `withISR`; a forged or tampered cookie fails the constant-time signature check.
 
 ```ts
+// doc-check: skip — fragment spanning three files: your `app`, `env`, `redirect`, and route `slug`.
 // 1. A route you gate yourself flips draft mode on for the editor.
 import { enableDraft, disableDraft } from "@nifrajs/web"
 
@@ -860,7 +867,11 @@ resolves, you call `stream.close()`, or the client disconnects (
 Node, Deno, and the edge — no `new Function`, no per-runtime API.
 
 ```ts
-import { sse } from "@nifrajs/core"
+import { server, sse } from "@nifrajs/core"
+
+const app = server()
+// Your pub-sub of choice — subscribe returns an unsubscribe function.
+declare const notifications: { subscribe(on: (n: { id: string }) => void): () => void }
 
 // A live feed — push events until the client disconnects.
 app.get("/notifications", (c) =>
@@ -1023,12 +1034,12 @@ routes, data, streaming — runs on a different framework, unchanged.
 // the same routes, loaders, actions, streaming, <Await>, fetchers, query cache.
 import { createWebApp } from "@nifrajs/web"
 import { reactAdapter } from "@nifrajs/web-react"   // ← or web-solid · web-vue · web-preact · web-svelte
+import { clientEntry, manifest } from "./server-manifest" // generated by buildServer
 
 const app = createWebApp({
   adapter: reactAdapter,   // the one line that changes per framework
   manifest,
   clientEntry,             // the built client bundle (from buildClient's manifest)
-  api,
 })
 ```
 
@@ -1081,6 +1092,7 @@ defined after** `app.use(plugin)` — no extra generics. Wrap a plugin with
 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"
 
 // A plugin is just (app) => app — call use/derive/decorate or register routes.
@@ -1130,13 +1142,15 @@ short-circuit), `beforeHandle`/`afterHandle` (around the handler),
 error, 404). Hardening middleware uses the same hook model:
 
 ```ts
-import { cors, rateLimit, securityHeaders } from "@nifrajs/middleware"
+import { server } from "@nifrajs/core"
+import { cors, rateLimit, securityHeaders, MemoryStore } from "@nifrajs/middleware"
 
 // Hardening middleware is a hook bundle (context-agnostic) — same app.use():
-app
+const app = server()
   .use(securityHeaders())
-  .use(cors({ origins: ["https://app.example"] }))
-  .use(rateLimit({ limit: 100, windowMs: 60_000 }))
+  .use(cors({ origin: ["https://app.example"] }))
+  // MemoryStore is dev/single-instance only — use a shared store (Redis, etc.) in production.
+  .use(rateLimit({ store: new MemoryStore(), max: 100, windowMs: 60_000 }))
 ```
 
 ### Official plugins
@@ -1144,9 +1158,10 @@ app
 `@nifrajs/middleware` seeds a few `definePlugin` plugins to build on:
 
 ```ts
+import { server } from "@nifrajs/core"
 import { requestId, logger, etag } from "@nifrajs/middleware"
 
-app
+const app = server()
   .use(requestId())   // reuse/generate x-request-id → c.requestId (typed) + response header
   .use(logger())      // one structured line/request: { method, path, status, ms }
   .use(etag())        // content-hash ETag on GET 200s → 304 on matching If-None-Match
@@ -1175,6 +1190,7 @@ cached. For full session-based auth (OAuth, magic links, 2FA), see
 [Auth & sessions](/docs/auth).
 
 ```ts
+// doc-check: skip — fragment: `app`, `lookupUser`, and the `db` lookup are your application's.
 import { bearer, apiKey } from "@nifrajs/middleware"
 
 // Bearer tokens — verify returns your principal (its type is inferred), 401s missing/invalid:
@@ -1207,9 +1223,10 @@ does custom, typed verification.
 clobbering one a handler already set.
 
 ```ts
+import { server } from "@nifrajs/core"
 import { compression, cacheControl } from "@nifrajs/middleware"
 
-app
+const app = server()
   .use(compression())                                  // gzip compressible responses (Accept-Encoding)
   .use(cacheControl("public, max-age=60"))             // Cache-Control on GET/HEAD 2xx (won't clobber)
   // …or a per-path policy — return undefined to leave a response untouched:
@@ -1234,6 +1251,7 @@ that Standard Schema can't expose. For full request/response _schemas_, generate
 exported for build-time generation too.
 
 ```ts
+// doc-check: skip — fragment: `app`, `db`, and `redis` are your application's clients.
 import { healthcheck, openapi } from "@nifrajs/middleware"
 
 app
@@ -1252,10 +1270,12 @@ 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 { idempotency, MemoryIdempotencyStore } from "@nifrajs/middleware"
 
 // A retried POST with the same Idempotency-Key replays the first response instead of
 // re-running the side effect. Shared store in production (atomic claim); dev-only memory store.
+const app = server()
 app.use(idempotency({ store: new MemoryIdempotencyStore() }))
 ```
 
@@ -1270,11 +1290,12 @@ 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 { jwt, jwks, basicAuth } from "@nifrajs/middleware"
 
 // JWT (WebCrypto): an explicit algorithm allowlist is REQUIRED; alg:none and RSA/HMAC confusion are rejected.
 const auth = jwt({ key: process.env.JWT_SECRET!, algorithms: ["HS256"], issuer: "my-app" })
-app
+const app = server()
   .use(auth)                                       // 401s missing/invalid (optional:true lets them through)
   .get("/me", (c) => auth.requireClaims(c.req))    // typed claims, or throws 401; auth.claims(req) is nullable
 // Asymmetric (rotating keys): key: jwks({ url: "https://issuer/.well-known/jwks.json" }) — https-only, cached.
@@ -1293,10 +1314,12 @@ 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 { cache, MemoryResponseCache, prettyJson } from "@nifrajs/middleware"
 
 // Full response cache: pluggable store, Vary-aware keys, byte cap. Bypasses Set-Cookie and respects
 // Cache-Control (no-store/private). MemoryResponseCache is per-instance — refuses prod unless opted in.
+const app = server()
 app.use(cache({ store: new MemoryResponseCache(), ttlMs: 30_000, vary: ["accept-language"] }))
 app.use(prettyJson())   // pretty-print JSON responses (size-capped; optional ?pretty query toggle)
 ```
@@ -1313,9 +1336,10 @@ no open redirect); `language` negotiates `Accept-Language` into
 is opt-in; `combine` bundles several middleware into one.
 
 ```ts
+import { server } from "@nifrajs/core"
 import { methodOverride, trimTrailingSlash, language, timing, poweredBy, combine } from "@nifrajs/middleware"
 
-app
+const app = server()
   .use(methodOverride())     // POST + X-HTTP-Method-Override → PUT/PATCH/DELETE (a real pre-routing request rewrite)
   .use(trimTrailingSlash())  // canonicalize URLs: 308 redirect (or rewrite), same-origin only, conservative methods
   .use(language({ supported: ["en", "fr"], defaultLanguage: "en" }))  // Accept-Language → c.language + Content-Language
@@ -1365,7 +1389,7 @@ bypasses that read path. `c.boundedBody(maxBytes?)` and
 `c.boundedJson<T>(maxBytes?)` extend the **same** cap to those routes.
 
 ```ts
-import { server, t } from "@nifrajs/core"
+import { server } from "@nifrajs/core"
 
 const app = server()
 
@@ -1378,12 +1402,13 @@ app.post("/import", async (c) => {
   // Responses (caught by the lifecycle like `throw redirect()`), so a handler can't
   // accidentally ignore the cap. The over-cap length is rejected BEFORE buffering;
   // a chunked / length-less body is aborted mid-stream once it crosses the cap.
-  return c.json({ received: bytes.byteLength })
+  return { received: bytes.byteLength } // a returned object is serialized as JSON 200
 })
 
 app.post("/rpc", async (c) => {
   const body = await c.boundedJson<{ method: string }>() // default: the server's maxBodyBytes
   // …bad JSON → 400. Then validate `body` with your schema before trusting it.
+  return { method: body.method }
 })
 ```
 
@@ -1400,12 +1425,13 @@ size cap and sniffs the **real** type from magic bytes — never the client-set
 `Blob` is rejected by its `.size` before it's ever buffered.
 
 ```ts
+// doc-check: skip — fragment: `app`, `save`, `id`, and `env` are your application's.
 import { validateUpload, signDownloadUrl } from "@nifrajs/uploads"
 
 app.post("/avatar", async (c) => {
   const form = await c.req.formData()
   const file = form.get("file")
-  if (!(file instanceof Blob)) return c.json({ ok: false, error: "no_file" }, 400)
+  if (!(file instanceof Blob)) { c.set.status = 400; return { ok: false, error: "no_file" } }
 
   // Size cap + REAL type by magic bytes — a .exe renamed .png (or a spoofed
   // Content-Type) is caught, because the bytes win. An oversized Blob is rejected
@@ -1414,14 +1440,14 @@ app.post("/avatar", async (c) => {
     maxBytes: 2_000_000,
     accept: ["image/png", "image/jpeg"], // exact, or "image/*"
   })
-  if (!result.ok) return c.json({ ok: false, error: result.reason }, 400)
+  if (!result.ok) { c.set.status = 400; return { ok: false, error: result.reason } }
   //  reason: "too_large" | "empty" | "unrecognized" | "type_not_allowed"
 
   await save(result.bytes, `${id}.${result.ext}`) // result.mime / .ext are trustworthy
 
   // Hand back a short-TTL, tamper-evident URL (HMAC over path + expiry):
   const url = await signDownloadUrl(`/files/${id}`, env.FILE_SECRET, { expiresInSeconds: 300 })
-  return c.json({ ok: true, url })
+  return { ok: true, url } // a returned object is serialized as JSON 200
 })
 ```
 
@@ -1435,6 +1461,7 @@ download links (HMAC-SHA256 over the path + expiry, constant-time verify). And
 [@nifrajs/image](/docs/images) backend, with no dependency on it:
 
 ```ts
+// doc-check: skip — fragment: continues the upload handler above (`result.bytes`).
 import { stripImageMetadata } from "@nifrajs/uploads"
 import { bunImageBackend } from "@nifrajs/image/backends"
 
@@ -1452,19 +1479,20 @@ payload. `verifyWebhook` reads the raw body bounded, verifies the HMAC, and hand
 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"
 
 app.post("/webhooks/stripe", async (c) => {
   // Reads the raw body BOUNDED (DoS guard), verifies the HMAC CONSTANT-TIME, and only
   // then returns the payload. Never JSON.parse a webhook before the signature checks out.
   const r = await verifyWebhook(c.req, env.STRIPE_WEBHOOK_SECRET, { provider: "stripe" })
-  if (!r.ok) return c.json({ ok: false, error: r.reason }, 400)
+  if (!r.ok) { c.set.status = 400; return { ok: false, error: r.reason } }
   //  reason: "missing_signature" | "invalid_signature" | "timestamp_out_of_tolerance"
   //        | "malformed_signature" | "payload_too_large" | "invalid_content_length"
 
   const event = StripeEvent.parse(JSON.parse(r.payload)) // validate at the trust boundary
   // …handle event… (pair with idempotency below so a redelivery doesn't double-process)
-  return c.json({ ok: true })
+  return { ok: true }
 })
 
 // GitHub (sha256=…hex), or any provider via the generic preset:
@@ -1488,6 +1516,7 @@ A dropped connection or an impatient double-tap shouldn't double-charge a card.
 re-running the side effect. It short-circuits in `onRequest`, _before_ the handler.
 
 ```ts
+// doc-check: skip — fragment: `app`, `chargeCard`, and `id` are your application's.
 import { idempotency, MemoryIdempotencyStore } from "@nifrajs/middleware"
 
 // Dev / single-instance. In production use a SHARED store (Redis, etc.) with an atomic
@@ -1496,7 +1525,7 @@ app.use(idempotency({ store: new MemoryIdempotencyStore() }))
 
 app.post("/charge", async (c) => {
   await chargeCard(/* … */) // the side effect
-  return c.json({ ok: true, id })
+  return { ok: true, id }
 })
 
 // A client retrying POST /charge with the same `Idempotency-Key` header gets the FIRST
@@ -1531,13 +1560,14 @@ 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 { jwt, csrf, ipRestriction, bodyLimit } from "@nifrajs/middleware"
 
-app
+const app = server()
   // JWT: the algorithm allowlist is REQUIRED; alg:none and RSA/HMAC confusion are rejected; exp enforced.
-  .use(jwt({ key: env.JWT_SECRET, algorithms: ["HS256"], issuer: "my-app" }))
+  .use(jwt({ key: process.env.JWT_SECRET!, algorithms: ["HS256"], issuer: "my-app" }))
   // Signed double-submit CSRF (HMAC) + Origin/Referer check on unsafe methods. Secret must be >= 32 bytes.
-  .use(csrf({ secret: env.CSRF_SECRET }))
+  .use(csrf({ secret: process.env.CSRF_SECRET! }))
   // Allow/deny by IPv4/IPv6 + CIDR. FAILS CLOSED with no trusted client IP; X-Forwarded-For is ignored
   // unless trustedProxies > 0 (set it to the number of proxies you actually run in front of the app).
   .use(ipRestriction({ allow: ["10.0.0.0/8", "::1"], trustedProxies: 1 }))
@@ -1617,6 +1647,7 @@ your nifra server. Read the session with `getSession(auth, request)` (typed
 your tests need no database — and your Better Auth types flow through by inference.
 
 ```ts
+// doc-check: skip — needs the third-party `better-auth` package + your `db`; install it to run this.
 // auth.ts — your configured Better Auth instance (database, providers, …):
 import { betterAuth as createBetterAuth } from "better-auth"
 export const auth = createBetterAuth({ database: db, emailAndPassword: { enabled: true } })
@@ -1648,11 +1679,11 @@ Stores mirror the ISR discipline: `MemorySessionStore` is prod-guarded;
 ```ts
 // auth.ts — one session manager. LAZY so a route module can import it without shipping it to the
 // browser (see the warning below). Store mode keeps data server-side; cookie mode (no store) is stateless.
-import { createSessions, MemorySessionStore, KVSessionStore } from "@nifrajs/auth"
+import { createSessions, MemorySessionStore } from "@nifrajs/auth"
 
-let manager
+let manager: ReturnType<typeof createSessions> | undefined
 export const getSessions = () => (manager ??= createSessions({
-  secret: process.env.SESSION_SECRET,           // ≥ 16 chars; rotating it invalidates all sessions
+  secret: process.env.SESSION_SECRET!,          // ≥ 16 chars; rotating it invalidates all sessions
   store: new MemorySessionStore(),              // prod: new KVSessionStore(env.SESSIONS)
   // cookie: { secure: false },                 // local http dev only
 }))
@@ -1694,6 +1725,7 @@ createWebApp({ /* … */ api: sessions })                  // inject the manager
 as-is, so the guard short-circuits the loader.
 
 ```ts
+// doc-check: skip — fragment: `api` is the session manager createWebApp injected (see setup above).
 // A protected route's loader — reads the session and redirects when absent.
 import { requireUser } from "@nifrajs/auth"   // browser-safe; OK to import in a route module
 
@@ -1900,6 +1932,7 @@ Deno-Deploy), where there's no native codec. `@nifrajs/image/backends` has no
 built in (it never decodes just to read dimensions).
 
 ```ts
+// doc-check: skip — illustrates third-party codecs (sharp, @jsquash/*); install them to run it.
 import { createImageHandler } from "@nifrajs/image/server"
 import { sharpImageBackend, wasmImageBackend } from "@nifrajs/image/backends"
 
@@ -1939,15 +1972,17 @@ loader can sign inline — even on the edge.
 import { selfHostedLoader, signImageUrl } from "@nifrajs/image"
 import { createImageHandler } from "@nifrajs/image/server"
 
-const resize = selfHostedLoader({ endpoint: "/_image", secret: env.IMAGE_SECRET })
+const IMAGE_SECRET = process.env.IMAGE_SECRET! // server-only; on Workers read c.env.IMAGE_SECRET instead
+
+const resize = selfHostedLoader({ endpoint: "/_image", secret: IMAGE_SECRET })
 //  → /_image?src=…&w=800&s=<hmac>   (stable: an SSR-signed URL hydrates + caches identically)
 
-const image = createImageHandler({ root: "./public", signing: { secret: env.IMAGE_SECRET } })
+const image = createImageHandler({ root: "./public", signing: { secret: IMAGE_SECRET } })
 //  any request without a valid &s= (forged / tampered / expired) → 403, before any fetch or decode
 
 // Time-limited links to private images (server-side only):
 const url = signImageUrl("/_image", { src: "/private/a.jpg", width: 800 }, {
-  secret: env.IMAGE_SECRET,
+  secret: IMAGE_SECRET,
   expiresIn: 300, // seconds → adds &exp=
 })
 ```
@@ -1974,8 +2009,10 @@ const info = await readImageDimensions(Bun.file("public/hero.jpg"))
 // → { width: 1200, height: 630, format: "jpeg" }   (null if unrecognized)
 
 // Build-time tooling: pre-read sizes into a manifest so <Image> is CLS-safe
-// without hardcoding width/height at every call site.
-imageDimensions(new Uint8Array(headerBytes))
+// without hardcoding width/height at every call site. The sync variant takes the
+// raw header bytes you already have in memory (no file read):
+const headerBytes = await Bun.file("public/hero.jpg").bytes()
+imageDimensions(headerBytes)
 ```
 
 ### Notes
@@ -2015,7 +2052,7 @@ messages.
 import { negotiateLocale } from "@nifrajs/i18n"
 import { catalogs, locales } from "../catalogs"
 
-export async function loader({ request }) {
+export async function loader({ request }: { request: Request }) {
   const q = new URL(request.url).searchParams.get("lang")
   const locale = q && locales.includes(q) ? q : negotiateLocale(request, { locales, defaultLocale: "en", cookie: "lang" })
   return { locale, messages: catalogs[locale] }   // cookie → Accept-Language → default
@@ -2143,6 +2180,7 @@ handler for a `[triggers]` schedule. It gets the platform controller plus the sa
 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 { app } from "./app"
 
@@ -2302,10 +2340,11 @@ Deploy: `wrangler pages deploy dist` (Pages) or `wrangler deploy`
 `server.ts` to hand-write. (`create-nifra` scaffolds the conventions.)
 
 ```ts
-nifra dev      # true-HMR dev server (Vite middleware + nifra SSR) — http://localhost:3000
+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)
 
+# 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)
 ```
 
@@ -2331,6 +2370,7 @@ required; the plugin/condition fields are extras the compiler frameworks need (R
 JSX is Bun-native, so they need none beyond the Vite plugin for dev HMR).
 
 ```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"
 import { reactAdapter } from "@nifrajs/web-react"
@@ -2389,6 +2429,7 @@ without a full page reload. Pass the official plugin for your UI framework, keep
 Nifra routes and loaders, and run the dev server during local development.
 
 ```ts
+// doc-check: skip — needs the third-party @vitejs/plugin-react + your ./backend; install it to run this.
 // dev.ts — state-preserving HMR for supported UI adapters
 import react from "@vitejs/plugin-react"            // your framework's official Vite plugin
 import { createWebApp } from "@nifrajs/web"
@@ -2403,7 +2444,7 @@ const server = await createViteDevServer({
   routesDir,
   clientModule: "@nifrajs/web-react/client",
   plugins: [react()],                                // Vue: @vitejs/plugin-vue, Svelte: …, etc.
-  port: Number(Bun.env.PORT ?? 3000),
+  port: Number(Bun.env.PORT ?? 4321),                // nifra's default; --port / PORT override it
   createApp: (clientEntry, importQuery) =>
     createWebApp({
       adapter: reactAdapter,
@@ -2509,6 +2550,7 @@ instead.
 serves SSR, watches the routes, and does a full-page reload on change.
 
 ```ts
+// doc-check: skip — fragment: routesDir/outDir/clientModule/createApp are your app's dev config.
 // dev.ts — Bun-native live reload
 import { createDevServer } from "@nifrajs/web/dev"
 // builds the client on boot, serves SSR, watches routes, full-page live-reload on change.
@@ -2584,6 +2626,675 @@ own stylesheet. Pass `manifest.routeStyles` to `createWebApp` alongside
 `styles`, and Nifra links the matched route's CSS during SSR. In
 **dev**, Vite injects per-module CSS.
 
+## Nifra — Troubleshooting
+
+> Fixes keyed on the literal error strings Nifra prints: `reached the client bundle` (a node:/native import in the browser bundle), `server-only module reached the client bundle` (the server-only marker), and `resolveDispatcher` / `Invalid hook call` (duplicate React).
+
+Hit an error? Search this page for the literal message. Each section is keyed on the exact
+string Nifra prints, with what it means and the fix. The build, `nifra check`, and
+the runtime all use the same wording so you can grep for it.
+
+### `reached the client bundle` — a `node:` / native import leaked to the browser
+
+The client build refuses to ship a Node built-in (`node:fs`, `node:crypto`,
+`bun:sqlite`, a native driver like `pg`) to the browser. Bun would
+silently substitute a polyfill that breaks — or leaks server code — at runtime, so Nifra fails
+the build instead. The message names the offending builtin and the **import chain**
+that pulled it in:
+
+[nifra/web] Node built-in(s) in the client bundle — move them behind a server-only path
+
+- node:crypto reached the client bundle via routes/x.tsx → ../data.ts → ../db.ts
+(chunk: x-abc123.js)
+
+Read the chain right-to-left: `../db.ts` imports `node:crypto`, and a
+top-level import in `routes/x.tsx` dragged it into the browser. **Fix it one
+of two ways:**
+
+-
+**Move the code into a `*.server.ts` module** (the recommended
+default). The client build empties `*.server` modules, so their `node:`
+/ native imports never reach the browser. Import the server module only from a loader/action
+(which run on the server).
+
+-
+**Reach the server code from a loader/action, not a route's top level.** A
+loader runs on the server during SSR; importing the `node:` module inside (or via)
+a loader keeps it out of the client graph.
+
+```ts
+// doc-check: skip — illustrative two-file layout (a relative cross-file import).
+// db.server.ts — the `.server` convention: the client build EMPTIES this module, so its
+// `node:` / native imports never ship to the browser. No marker import needed — the filename is it.
+import { Database } from "bun:sqlite"
+export const db = new Database("app.db")
+
+// routes/notes.tsx — import the server module from a loader; it runs only on the server during SSR.
+import type { LoaderContext } from "@nifrajs/web"
+import { db } from "../db.server"
+export async function loader(_ctx: LoaderContext) {
+  return { notes: db.query("select * from notes").all() }
+}
+```
+
+[!TIP]
+
+Run `nifra check` (or `nifra check --json` for agents) to catch this
+_before_ the build: it reports the same transitive chain (
+`routes/x → ../data → ./db → node:crypto`) by walking the local module graph, so
+you see the leak as a lint result, not a failed build.
+
+### `server-only module reached the client bundle` — the server-only marker fired
+
+This is the companion guard for **pure server logic that carries no `node:`
+import** — a secret-bearing constant, a server-only API call — so the node-builtin guard
+above has nothing to catch and the `.server` convention needs the file to be
+_named_ `*.server`. You opt a module in with a side-effect import, and the
+client build fails loud (with the import chain) if it ever lands in a browser chunk:
+
+[nifra/web] server-only module(s) in the client bundle — a module marked
+`import "@nifrajs/web/server-only"` reached the browser.
+
+- server-only module reached the client bundle via routes/x.tsx → ./secrets.ts (marked
+server-only)
+
+There are three markers; reach for them by intent:
+
+marker
+enforcement
+use when
+
+`*.server.ts` filename
+
+client build auto-empties the module
+
+a dedicated server module (a DB client, a `node:` helper) you can name
+`*.server`
+
+`import "@nifrajs/web/server-only"`
+
+client build fails loud, with the chain, if it leaks
+
+pure server logic with **no `node:` import to catch** (a secret,
+a server-only call) that you can't / don't want to rename
+
+`ServerOnly` type
+
+type-level intent only — does NOT keep it out of the bundle
+
+documenting that a value must not cross to the browser; pair it with one of the two
+runtime markers
+
+A worked example — a secret with no `node:` import, marked so a leak fails the build
+rather than shipping the key to every visitor:
+
+```ts
+// secrets.ts — pure server logic: a secret constant, no `node:` import to catch.
+import "@nifrajs/web/server-only"             // ← fails the CLIENT build (loud, with the import chain)
+import type { ServerOnly } from "@nifrajs/web" // ← type-level intent: this value is server-only
+
+// `ServerOnly<string>` is structurally `string` (the brand is an optional phantom field), so it
+// stays assignment-compatible — it documents intent without obstructing real use.
+export const apiKey: ServerOnly<string> = process.env.SECRET_API_KEY!
+
+// If this module ever reaches a browser chunk, buildClient fails with:
+//   server-only module reached the client bundle via routes/x.tsx → ./secrets.ts (marked server-only)
+// Reach it from a loader/action (server-only) instead, and the secret never ships to the client.
+```
+
+**Fix:** reach the module from a loader/action (server-only), or rename it
+`*.server.ts` so the client build empties it. `nifra check` reports the
+same transitive chain pre-build. The `ServerOnly` brand on its own is purely
+type-level (it erases at build), so always back it with the import marker or the
+`.server` filename.
+
+### `resolveDispatcher` / `Invalid hook call` — duplicate React
+
+If SSR throws `Cannot read properties of null (reading 'useState')` inside
+`resolveDispatcher`, or React logs **"Invalid hook call. Hooks can only be
+called inside the body of a function component"**, you almost certainly have
+**two copies of React** in one render. React's hook dispatcher is module-level
+global state; a second copy nulls it out and every hook throws.
+
+Nifra **dedupes React** in both the production build and the Vite dev server, so
+the framework itself won't load two copies. The usual culprit is a
+**`file:`-linked package** (a local component library you
+`bun link` or reference with `file:../lib`) that bundles its own React in
+its own `node_modules`:
+
+-
+Make React a **peer dependency** of the linked package (not a regular
+dependency), so it resolves to the app's single copy.
+
+-
+Ensure one React version across the workspace — pin it in the root
+`package.json` `overrides` (Nifra's own repo pins
+`react` / `react-dom` this way) so every package resolves the same
+copy.
+
+-
+Delete the linked package's nested `node_modules/react` after linking if your
+package manager duplicated it.
+
+[!NOTE]
+
+This applies to every framework with module-global render state, not just React (Preact,
+Vue, Solid, Svelte). Nifra dedupes the active adapter's runtime in build and dev; a
+`file:`-linked package shipping its own copy is the thing to fix. See
+[Dev & HMR](/docs/dev) and the `file:`-linked-package note in
+`AGENTS.md`.
+
+### Still stuck?
+
+Run `nifra check --json` as the done-gate — it surfaces the import-chain leaks,
+typed-client drift, and raw-`Response`-from-a-route issues before you ship. The
+full machine-readable contract is at [/llms-full.txt](/llms-full.txt), and each
+package ships a tight `LLM.md` contract card.
+
+## Nifra — Backends & API (dev and prod)
+
+> How a Nifra backend reaches your app: inProcessClient feeds ctx.api to loaders, and createWebApp auto-mounts the backend over HTTP at /api/* — in `nifra dev` and production alike, no hand-dispatch.
+
+Your `@nifrajs/core` backend reaches a Nifra app two ways from a single wiring.
+`inProcessClient(backend)` is fed to every loader and action as
+`ctx.api` — and `createWebApp` now **auto-mounts** that
+backend over HTTP at `/api/*`, so the browser can call the very same routes. No
+hand-written `if (pathname.startsWith("/api/"))` branch in your server entry.
+
+### One backend, two call paths
+
+Write the backend once. It defines its routes at the full `/api/…` path (the mount
+does no path stripping). Loaders call it _in-process_ during SSR; the browser calls it
+_over HTTP_. Both run the identical lifecycle — validation, middleware, contracts.
+
+```ts
+// backend.ts — a normal @nifrajs/core server. Routes live at the full /api/... path.
+import { server } from "@nifrajs/core"
+import { t } from "@nifrajs/schema"
+
+export const backend = server()
+  .post("/api/sync", { body: t.object({ cursor: t.string() }) }, async (c) => {
+    // validated body; runs the same whether called in-process (a loader) or over HTTP (a client fetch)
+    return { applied: 12, nextCursor: c.body.cursor }
+  })
+  .get("/api/me", (c) => ({ id: c.cookies.session ?? null }))
+```
+
+### ctx.api — the in-process loader client
+
+Pass `inProcessClient(backend)` as `createWebApp`'s `api`.
+Inside a loader or action, `ctx.api` is that typed client, and a call goes
+**straight to the backend's `fetch` in-process** — no network hop, no
+port, the full real lifecycle. This is the SSR data path; it never touches the HTTP mount.
+
+```ts
+// routes/index.tsx — a loader calls the backend IN-PROCESS via ctx.api (no network).
+import type { LoaderContext } from "@nifrajs/web"
+
+export async function loader(ctx: LoaderContext) {
+  const api = ctx.api as { me: { get(): Promise<{ data: { id: string | null } }> } }
+  const res = await api.me.get() // in-process: full validation/middleware, no HTTP round-trip
+  return { me: res.data }
+}
+```
+
+### The auto-mounted /api/* (the new part)
+
+Before, `inProcessClient` fed `ctx.api` but did _not_ serve the
+backend over HTTP — so a browser `POST /api/sync` hit the page router and 404/405'd
+until you hand-wrote a dispatch branch in `server-bun.ts`. Now
+`createWebApp` mounts it for you: a request whose pathname is exactly
+`apiPrefix` (default `/api`) or starts with
+`apiPrefix + "/"` is dispatched to `api.fetch(req.url, req)`
+**before** page routing, and the backend's `Response` is returned
+untouched (the request body is passed through, never pre-read).
+
+```ts
+// server.ts (prod) — createWebApp serves pages AND auto-mounts the backend at /api/*.
+import { inProcessClient } from "@nifrajs/client"
+import { createWebApp } from "@nifrajs/web"
+import { reactAdapter } from "@nifrajs/web-react"
+import { backend } from "./backend"
+import { clientEntry, manifest } from "./server-manifest"
+
+export const app = createWebApp({
+  adapter: reactAdapter,
+  manifest,
+  clientEntry,
+  api: inProcessClient(backend), // → ctx.api in loaders/actions AND auto-mounted at /api/*
+  // apiPrefix: "/api",          // the default; pass "" to disable the HTTP mount (pages only)
+})
+
+// Bun: Bun.serve({ fetch: app.fetch }). No `if (pathname.startsWith("/api/")) …` branch needed —
+// POST /api/sync, GET /api/me, etc. are dispatched to the backend BEFORE the page router sees them.
+```
+
+The dispatch runs in `createWebApp`'s request lifecycle, ahead of the page wildcard,
+for **every method** — so `GET`/`POST`/`PUT`/… all
+reach the backend, and an unknown `/api/…` path returns the _backend's_ 404,
+not the page's. A sibling path that merely shares the prefix string (e.g.
+`/apidocs`) is **not** captured — only the `/api` boundary
+is. Pass `apiPrefix: ""` to turn the mount off and keep `ctx.api` as a
+loader-only client.
+
+[!NOTE] The mount lives in `createWebApp`, and `nifra dev` (the
+Vite-backed dev server) routes every request through that same app's `fetch`. So
+the `/api/*` routes are served identically in development and production — there is
+nothing extra to wire for the dev loop.
+
+### Calling /api/* from the browser
+
+With the routes mounted, a client island or component hits them with the same typed
+`client<typeof backend>` — same-origin, no separate API server.
+
+```ts
+// A browser island / client component hits the mounted HTTP routes with the typed client.
+import { client } from "@nifrajs/client"
+import type { backend } from "./backend"
+
+const api = client<typeof backend>("") // same-origin: /api/sync is served by createWebApp's mount
+export async function runSync(cursor: string) {
+  const { data, error } = await api.api.sync.post({ cursor })
+  return error ? { applied: 0 } : data
+}
+```
+
+### Route actions vs the in-process backend (for mutations)
+
+Two valid ways to mutate; pick by where the call originates.
+
+-
+**Route `action`** — the form/SSR path. A
+`` (or the client submit) runs the route's
+`action(ctx)`, which typically calls `ctx.api` in-process and returns
+`actionData` (or a `redirect`). Progressive-enhancement: works with JS
+off, and the loader revalidates after. Reach for this for page-driven mutations tied to a
+route's UI.
+
+-
+**The mounted `/api/*` backend** — the programmatic path. A browser
+island, a third party, a webhook, or a non-page client calls the HTTP route directly. Reach
+for this when the caller isn't a Nifra route's form — an RPC the page makes on an
+interaction, an external integration, a mobile client.
+
+They share the backend: a route `action` and a browser `fetch` can both
+call `POST /api/sync` — one in-process, one over the mount — and get identical
+validation and behavior.
+
+## 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.
+
+Everything you'd otherwise read the source to learn, on one page: the
+`LoaderContext` shape, the loader / action / meta / head signatures, what runs on
+the server vs the client, the two ways to handle a request, the dynamic-route 404 rule, and
+the build-output contract. Every signature here is verified against the
+`@nifrajs/web` source.
+
+### LoaderContext
+
+One context object is passed to every `loader` and every `action`. The
+same five fields, always — `params`, `request`, `api`,
+`env`, and `draft`.
+
+```ts
+// The single context object passed to every loader AND action (@nifrajs/web).
+interface LoaderContext {
+  params:  Record<string, string>  // matched route params (:id, *path)
+  request: Request                 // the standard Web Request — read headers/body/URL off it
+  api:     unknown                 // the in-process backend client createWebApp was given
+  env:     unknown                 // platform bindings forwarded from c.env (Workers KV/D1/…)
+  draft:   boolean                 // true only when a valid draft cookie is present (draftSecret set)
+}
+
+// api + env are typed per-route via @nifrajs/client's LoaderArgs<Api, Env>; the agnostic core
+// keeps them `unknown`. Branch on `draft` to load unpublished content for preview/editors.
+```
+
+### Loader, action & meta signatures
+
+A route module co-locates its data, mutation, head, and view. Only the
+`default` export (the component) is required; `loader`,
+`action`, `meta`, and `hydrate` are all optional. A
+`loader` runs on **GET** and feeds `props.data`; an
+`action` runs on **POST** and feeds `props.actionData`.
+
+```ts
+// routes/users/[id].tsx — a route module's full contract (every export optional but `default`).
+// doc-check: skip — full-contract sketch; ctx.api's routes and meta's loader-data shape come from
+// the reader's own backend type, so it can't compile standalone (see the typed examples elsewhere).
+import type { LoaderContext } from "@nifrajs/web"
+
+// GET → data for the page. Runs in-process on the server during SSR (no HTTP hop).
+export async function loader(ctx: LoaderContext) {
+  return { user: await ctx.api.users.get({ id: ctx.params.id }) }
+}
+
+// POST → a mutation. Same context. Return a Response (e.g. a redirect — passed straight
+// through) OR data, which reaches the component as `actionData`.
+export async function action(ctx: LoaderContext) {
+  const form = await ctx.request.formData()
+  return { ok: true }
+}
+
+// Static OR a function of { data, params, origin }. Static meta is serialized once; function meta
+// recomputes per request (its content can vary with loader data). `origin` is the request's
+// scheme+host (server-resolved, matches the client's location.origin) — use it for ABSOLUTE
+// canonical / og:url / og:image URLs without threading siteUrl through loader data.
+export const meta = ({ data, params, origin }) => ({
+  title: `User ${data.user.name}`,
+  meta: [{ name: "description", content: data.user.bio }],
+  link: [{ rel: "canonical", href: `${origin}/users/${params.id}` }],
+})
+
+export const hydrate = false   // opt out of full-document hydration (static / island pages)
+export default function User(props) { /* props.data, props.actionData, props.params */ }
+```
+
+[!NOTE] An `action` may return a `Response` (a `redirect()`,
+say) — it's passed through untouched. Any other return is serialized as
+`actionData`.
+
+### Two ways to handle a request
+
+A page's data comes from a `loader` calling the **in-process backend**
+(`ctx.api`) — but that backend is **loaders-only**: it registers
+`GET` handlers, so a `.post()` to `ctx.api` answers
+**405**. A **public POST** (a browser form or `fetch`) is
+a route **action** export, not an `inProcessClient(backend).post()`
+call.
+
+```ts
+// TWO ways to handle a request — pick by who is calling.
+import type { LoaderContext } from "@nifrajs/web"
+
+// (1) A page's own data + mutations → route exports. A PUBLIC POST is a route ACTION
+//     (routes/contact.tsx) — the browser POSTs the route's own URL, nifra runs `action`:
+export async function action(ctx: LoaderContext) {
+  const form = await ctx.request.formData()        // the browser POSTed this route
+  return { ok: true, body: String(form.get("body")) } // → props.actionData on re-render
+}
+
+// (2) ctx.api is the IN-PROCESS backend client (the inProcessClient(server) the app was given).
+//     It is LOADERS-ONLY: the SSR backend registers GET handlers, so a .post() to ctx.api 405s.
+export async function loader(ctx: LoaderContext) {
+  // ✅ a GET in-process — no HTTP hop. (A .post() to ctx.api would 405; write an `action` instead.)
+  return { id: ctx.params.id }
+}
+
+// Rule of thumb: data INTO a page → loader + ctx.api (GET). A mutation FROM the browser
+// (a form/fetch POST) → an `action` export on the route. Don't `inProcessClient(api).post()`.
+```
+
+### Dynamic routes & the 404 / control-flow rule
+
+A `[param]` route's loader runs for _any_ value on plain SSR —
+`getStaticPaths`'s `fallback: "404"` is enforced only by the prerender /
+CDN layer, never by the on-demand worker. So a loader that can't find its record
+**must** 404 itself. The mechanism is the throw contract:
+
+```ts
+// routes/users/[id].tsx — plain SSR runs the loader for ANY :id value. `fallback: "404"`
+// only takes effect under prerender/CDN, so on on-demand SSR you MUST guard and 404 yourself.
+import type { LoaderContext } from "@nifrajs/web"
+
+declare function lookupUser(id: string): Promise<{ id: string } | null>
+
+export async function loader(ctx: LoaderContext) {
+  // ctx.params.id is `string | undefined` (an optional segment) — default it before the lookup.
+  const user = await lookupUser(ctx.params.id ?? "")
+  if (!user) {
+    // CONTROL FLOW: a thrown Response is an INTENTIONAL HTTP response — it propagates untouched
+    // (no _error boundary, no 500). This is how you 404 a missing record.
+    throw new Response("Not Found", { status: 404 })
+  }
+  return { user }
+}
+
+declare function lookupUser(id: string): Promise<{ name: string } | null>
+
+// The throw contract, stated once:
+//   • throw a Response  → that exact HTTP response is sent (404 / redirect() / 403 / …). Control flow.
+//   • throw an Error    → renders the nearest _error boundary if one exists, else a 500. A bug.
+// So NEVER `throw new Error("not found")` to mean 404 — that is a 500. Throw a 404 Response.
+```
+
+**Throwing a `Response` is control flow** — that exact HTTP response
+(a 404, a `redirect()`, a 403) is sent untouched, bypassing the
+`_error` boundary. **Throwing an `Error` is a fault** — it
+renders the nearest `_error` boundary (or a 500 if there is none). Never throw an
+`Error` to signal a 404.
+
+### Meta & head rendering rules
+
+A route's `<head>` is its **layout chain's** head merged with
+the page's — so a `_layout.tsx` can export `meta` to put sitewide tags
+(`hreflang`, `preconnect`, a section `<title>`) on every
+page below it.
+
+```ts
+// routes/_layout.tsx — a layout can export `meta` too. Its tags are SITEWIDE: they land in
+// the <head> of every page below it — the home for hreflang / preconnect / a section <title>.
+export const meta = {
+  link: [
+    { rel: "preconnect", href: "https://cdn.example.com", crossorigin: "anonymous" },
+    { rel: "alternate", hreflang: "es", href: "https://example.com/es" },
+  ],
+  title: "Docs",   // section default — a child page's title overrides it
+}
+
+// The route's final <head> = its LAYOUT CHAIN's meta merged with the page's:
+//   • title (and other scalars): NEAREST-WINS — page overrides inner layout overrides outer.
+//     An undefined page title keeps the layout's.
+//   • meta / link arrays: CONCATENATED outermost-layout → … → page (so the page's canonical
+//     comes after the layout's links).
+// <link> attributes are typed (LinkDescriptor: a partial like { rel, href, hreflang } is assignable),
+// name-validated (any letter/digit/hyphen name) and value-escaped against XSS — so
+// rel/href/hreflang/crossorigin/media/sizes/as/integrity/fetchpriority/… all survive. A boolean
+// attribute (e.g. `disabled: true`) renders bare; `false`/`undefined` is omitted.
+```
+
+The merge is **nearest-wins** for scalars (the page's `title` beats an
+inner layout's, which beats an outer one) and **concatenated** for the
+`meta` / `link` arrays (outermost layout first, page last). A
+`link` entry is a typed `LinkDescriptor` — a partial like
+`{ rel, href, hreflang }` is assignable, custom / `data-*` attrs
+pass through, and every `<link>` attribute with a normal name —
+`rel`, `href`, `hreflang`, `crossorigin`,
+`media`, `sizes`, `type`, `as`,
+`integrity`, `referrerpolicy`, `fetchpriority`,
+`imagesrcset` — survives into the SSR'd tag; values are HTML-escaped against XSS.
+
+### SEO: Open Graph, Twitter cards & JSON-LD
+
+A route's `meta` emits the full social / structured-data head with three public
+helpers — `canonical()`, `openGraph()`, and `jsonLd()` — and
+builds **absolute** URLs from the `origin` argument. Because
+`meta()` runs in **both** SSR and client navigation it has
+**no server env**: never read `process.env` or the request inside it.
+The framework injects `origin` (the site's scheme + host, e.g.
+`https://news.example.com`) from the request on the server and from
+`location.origin` on the client, so the two match and an absolute
+`og:url` / `canonical` / `og:image` never drifts between the
+server-rendered `<head>` and a soft-nav. Anything else server-only (an API
+base, a CDN host) belongs in the `loader`, not `meta()`.
+
+```ts
+// routes/articles/[slug].tsx — a complete SEO head: canonical + Open Graph + Twitter + JSON-LD,
+// with ABSOLUTE URLs built from `origin`. The three helpers (canonical/openGraph/jsonLd) are public
+// exports of @nifrajs/web; `origin` is the third MetaArgs field (after data + params).
+import { canonical, jsonLd, openGraph, type MetaArgs } from "@nifrajs/web"
+
+// CAVEAT: meta() runs in BOTH SSR and client navigation, so it has NO server env — never read
+// `process.env` or the request here. The framework injects `origin` (the site's scheme+host, e.g.
+// "https://news.example.com") server-side from the request AND on the client from location.origin, so
+// the two match and an absolute og:url/canonical/og:image never drifts between SSR and a soft-nav. For
+// anything else server-only (an API base, a CDN host), thread it through the LOADER, not meta().
+export const meta = ({ data, params, origin }: MetaArgs) => {
+  const article = data as { title: string; summary: string; image: string; published: string }
+  const url = `${origin}/articles/${params.slug}`        // absolute, from the injected origin
+  const image = `${origin}${article.image}`              // og:image MUST be absolute for crawlers
+  return {
+    title: article.title,
+    meta: [
+      { name: "description", content: article.summary },
+      // og:* — openGraph emits only the props you pass (+ og:type, here "article").
+      ...openGraph({
+        title: article.title,
+        description: article.summary,
+        url,
+        image,
+        type: "article",
+      }),
+      // twitter:* — a large-image summary card sharing the same absolute image.
+      { name: "twitter:card", content: "summary_large_image" },
+      { name: "twitter:title", content: article.title },
+      { name: "twitter:description", content: article.summary },
+      { name: "twitter:image", content: image },
+    ],
+    link: [canonical(url)],                              // <link rel="canonical"> — the authoritative URL
+    // JSON-LD structured data — escaped for safe <script> embedding by the head renderer.
+    script: [
+      jsonLd({
+        "@context": "https://schema.org",
+        "@type": "NewsArticle",
+        headline: article.title,
+        image,
+        datePublished: article.published,
+        mainEntityOfPage: url,
+      }),
+    ],
+  }
+}
+```
+
+[!NOTE] `og:image` (and the Twitter image) **must be absolute** for
+crawlers — build it from `origin`. `openGraph()` emits only the
+properties you pass (plus `og:type`); `jsonLd()`'s payload is escaped for
+safe `<script>` embedding by the head renderer.
+
+### The client ↔ server boundary
+
+Loaders, actions, and head resolution run on the server. The client receives the loader's
+_return value_ (serialized into the document), never the loader, the `api`,
+or `env`. Keep server-only imports out of a route file's top level.
+
+```ts
+// What runs WHERE:
+//
+//   SERVER (Bun / edge)            CLIENT (browser)
+//   ─────────────────────          ──────────────────────────
+//   loader / action                event handlers, useState/effects
+//   meta / head resolution         soft-nav re-fetch of loader data
+//   SSR of the layout chain        hydration + Fast Refresh (dev)
+//   backend (api, env, draft)      —
+//
+// The client gets the loader's RETURN VALUE (serialized into the document), never the loader
+// itself, the api, or env. So:
+//  1. Never import server-only modules (Bun, a DB client, secrets) at the top level of a route
+//     file — the bundler pulls it into the client chunk and it crashes / leaks. (The build now
+//     FAILS with a named error if a `node:` built-in reaches a client chunk — see below.)
+//  2. A client soft-nav re-runs the loader over the network (X-Nifra-Data) and re-merges the
+//     same layout-chain head, so sitewide tags persist across navigation — no page-only flash.
+```
+
+### The build-output contract
+
+`nifra build` emits a content-hashed `dist/` plus a
+`manifest.json` you 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:
+{
+  "entry": "/assets/_nifra-entry-HASH.js",        // the bootstrap module script
+  "assets": ["/assets/…"],                          // every emitted chunk URL
+  "routes": { "users/[id]": ["/assets/_layout-H.js", "/assets/_slug_-H.js"] },
+  "css": ["/assets/app-H.css"],                     // aggregate stylesheets (fallback)
+  "routeStyles": { "users/[id]": ["/assets/_layout-H.css"] }  // per-route CSS (chain only)
+}
+
+// Invariants worth knowing:
+//  • Chunk names are URL-PATH-SAFE. A dynamic-route file [slug].tsx would emit `[slug]-H.js`,
+//    whose [ ] make a static server 400 the request. The build renames it (`[slug]` → `_slug_`)
+//    and rewrites every reference, so the lazy import resolves and the route hydrates.
+//  • `process.env` is compiled away. `process.env` → `({})` and `process.env.NODE_ENV` → the
+//    build mode; every other `process.env.X` becomes undefined — EXCEPT names you opt in with the
+//    PUBLIC_ prefix (Vite/Next convention), which are baked in with their value (see below). No
+//    `process is not defined` crash, and no unprefixed (secret) env leaking into the client bundle.
+//  • A `node:` built-in in the CLIENT bundle FAILS the build with a named error (move it behind a
+//    loader/action — server-only). It builds via a browser polyfill otherwise, then breaks at runtime.
+//  • Assets are content-hashed + immutable. Serve /assets/* with a long-lived cache header.
+```
+
+### Public env in the client bundle
+
+`process.env` is compiled away in the browser bundle, so a bare read can't crash
+hydration and an unprefixed (secret) var resolves to `undefined` — it never reaches
+the client. To expose a value, give it the `PUBLIC_` prefix (the Vite / Next
+convention) in the build environment and it's baked in by value. The prefix is overridable via
+`buildClient`'s `publicEnvPrefix` (`""` disables it).
+
+```ts
+// process.env in the CLIENT bundle is compiled at build time:
+//   process.env             → ({})          (a bare read won't crash hydration)
+//   process.env.NODE_ENV    → "production"  (the build mode — frameworks' prod/dev branch)
+//   process.env.SECRET_KEY  → undefined     (unprefixed → never exposed; no secret leak)
+//   process.env.PUBLIC_API_URL → "https://api.example.com"  (PUBLIC_-prefixed → baked in by value)
+//
+// So to ship a value to the browser, give it a PUBLIC_ prefix in the BUILD environment:
+//   PUBLIC_API_URL=https://api.example.com  bun run build
+// then read process.env.PUBLIC_API_URL in app code — it becomes a string literal after the build.
+import { buildClient } from "@nifrajs/web/build"
+
+// Override the prefix (or disable auto-exposure) via buildClient:
+await buildClient({
+  routesDir: "./routes",
+  outDir: "./dist",
+  clientModule: "@nifrajs/web-react/client",
+  publicEnvPrefix: "NIFRA_PUBLIC_", // default "PUBLIC_"; "" disables auto-exposure entirely
+})
+```
+
+### Static emit (prerender)
+
+Opt a static route into SSG with `export const prerender = true` (or a dynamic
+route with `export const getStaticPaths`), then call `prerenderRoutes` —
+a **public** export of `@nifrajs/web/build`. It drives the app's own
+`fetch` to write `index.html` + `_data.json` per route;
+`cloudflarePagesRoutes` emits the `_routes.json` for a hybrid CDN +
+worker deploy. No need to boot a server and curl it.
+
+```ts
+// build.ts — emit static HTML for opted-in routes. prerenderRoutes + cloudflarePagesRoutes
+// are PUBLIC (exported from @nifrajs/web/build) — no need to boot a server and curl it.
+import { buildClient, prerenderRoutes, cloudflarePagesRoutes } from "@nifrajs/web/build"
+import { discoverRoutes } from "@nifrajs/web/fs"
+
+// 1. Build the client bundle first (so the app references the hashed entry).
+await buildClient({ routesDir: "./routes", outDir: "./dist", clientModule: "@nifrajs/web-react/client" })
+
+// 2. Drive the app's own fetch to render each opted-in route → dist/<path>/index.html + _data.json.
+//    Static routes opt in with `export const prerender = true`; dynamic routes enumerate concrete
+//    params with `export const getStaticPaths` (+ a `fallback: "ssr" | "404"`).
+const { app } = await import("./server")
+const { prerendered } = await prerenderRoutes({
+  app,                                       // the built createWebApp (a { fetch } is enough)
+  routes: discoverRoutes("./routes").routes,
+  outDir: "./dist",
+})
+
+// 3. Hybrid deploy: a Cloudflare Pages _routes.json that serves the prerendered HTML + _data.json
+//    from the CDN and falls everything else through to the SSR worker.
+const paths = prerendered.map((p) => p.path)
+await Bun.write("./dist/_routes.json", JSON.stringify(cloudflarePagesRoutes({ prerendered: paths })))
+```
+
+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.
+
 ## Nifra — Databases
 
 > Nifra is database-agnostic: use SQLite, Postgres, or any ORM (Drizzle, Prisma, Kysely) from your handlers and loaders, on Bun, Node, Deno, and the edge.
@@ -2644,7 +3355,7 @@ import { Database } from "bun:sqlite"        // Node: better-sqlite3 · edge: Tu
 
 // Open the connection ONCE at module scope (the driver pools internally).
 const db = new Database("app.db")
-const byId = db.query<{ id: number; name: string }>("SELECT * FROM users WHERE id = ?")
+const byId = db.query<{ id: number; name: string }, [number]>("SELECT * FROM users WHERE id = ?")
 
 export const app = server().get("/users/:id", (c) =>
   // Parameterized (?) — never interpolate user input into SQL.
@@ -2772,6 +3483,7 @@ If you prefer parameterized queries over an ORM, use `postgres` or `pg`
 directly:
 
 ```ts
+// doc-check: skip — illustrates a third-party driver (postgres + drizzle); install those to run it.
 import { server } from "@nifrajs/core"
 import { drizzle } from "drizzle-orm/postgres-js"   // or node-postgres / neon-http
 import postgres from "postgres"
@@ -3145,6 +3857,125 @@ backend you can also ship on its own. Start with [Getting started](/docs).
 Moving a backend (Express, Hono, Fastify, Elysia) instead? See
 [Migrating a backend](/docs/migrate-backend).
 
+## 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.
+
+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.
+
+### One schema
+
+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.
+
+```ts
+import { t } from "@nifrajs/schema"
+
+// One contract, defined once. Everything below is derived from it.
+export const GetUser = {
+  params: t.object({ id: t.string() }),
+  response: t.object({
+    id: t.string(),
+    name: t.string(),
+    role: t.union([t.literal("admin"), t.literal("user")]),
+  }),
+}
+```
+
+### Runtime validation
+
+Attach the schema to a route. Path params, query, and body are validated at the runtime
+boundary _before_ your handler runs — invalid input is rejected with a 400, so the
+handler only ever sees well-formed data.
+
+```ts
+import { server } from "@nifrajs/core"
+import { GetUser } from "./schema"
+
+export const app = server().get("/users/:id", GetUser, (c) => {
+  // c.params.id is typed `string` — parsed from the path and validated at the boundary.
+  return { id: c.params.id, name: "Ada", role: "admin" as const }
+  //     ^ the return is checked against GetUser.response — a wrong shape is a tsc error.
+})
+```
+
+### 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.
+
+### The typed client
+
+The client is inferred from the server's _type_ — no generators, no build step, no
+SDK to regenerate. Paths and params autocomplete; the response is typed from the route. A
+backend change that breaks a call is a compile error on the frontend.
+
+```ts
+import { client } from "@nifrajs/client"
+import type { app } from "./server"   // a TYPE import — server code never ships to the client
+
+const api = client<typeof app>("https://api.example.com")
+
+const res = await api.users({ id: "42" }).get()   // path + params autocomplete, no codegen
+if (res.ok) {
+  res.data.name        // typed from the route's response schema
+} else {
+  res.error            // client-call failures are returned, never thrown
+}
+```
+
+### OpenAPI
+
+The `openapi()` middleware builds an OpenAPI 3.1 document from your registered
+routes and their schemas — generated lazily on first request, never hand-written. Pass
+`ui: true` to also serve a Scalar reference page.
+
+```ts
+import { server } from "@nifrajs/core"
+import { openapi } from "@nifrajs/middleware"
+import { GetUser } from "./schema"   // the contract defined above
+
+// Generates an OpenAPI 3.1 document from your registered routes — lazily, on first request.
+export const app = server()
+  .use(openapi({ info: { title: "My API", version: "1.0.0" }, ui: true }))
+  .get("/users/:id", GetUser, (c) => ({ id: c.params.id, name: "Ada", role: "admin" as const }))
+
+// → GET /openapi.json   (the spec, generated from your schemas)
+// → GET /reference      (a Scalar API-reference page, because `ui: true`)
+```
+
+### The MCP contract
+
+The same routes and schemas feed coding agents. `nifra context` prints the live
+API surface as compact text, and `nifra mcp` serves it over the Model Context
+Protocol so Claude Code or Cursor read the real contract instead of guessing.
+
+```ts
+$ nifra context        # the same contract as compact text — pipe into any agent prompt
+  GET /users/:id  →  params { id: string }  response { id, name, role }
+
+$ nifra mcp            # the same data over an MCP server — Claude Code & Cursor read it
+```
+
+### Known limitations
+
+-
+Validation only covers what you put in a schema. A raw-body, file-upload, or
+bring-your-own-validation route reads the body directly — cap and validate those yourself
+(see [Security](/docs/security)'s `c.boundedBody`).
+
+-
+The typed client infers from the server _type_, so it needs an
+`import type` of your app and TypeScript on the frontend. There is no runtime
+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.
+
 ---
 
 # Package reference (READMEs)
@@ -3168,6 +3999,14 @@ bun add @nifrajs/auth
 
 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/better-auth
 
 Mount [better-auth](https://better-auth.com) into a [nifra](https://github.com/nifra) app: one
@@ -3261,6 +4100,14 @@ export const loader = async ({ request }) => {
 
 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/cli
 
 The `nifra` CLI — zero-config dev/build/start for a nifra app, plus the agent surfaces (`nifra context`,
@@ -3361,6 +4208,14 @@ claude mcp add nifra -- nifra mcp
 Run the client from (or point it at) your project root. The protocol is hand-rolled
 (newline-delimited JSON-RPC 2.0) — no SDK dependency.
 
+## 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/client
 
 A browser-safe, **end-to-end-typed** client for [nifra](../../README.md) servers — an
@@ -3392,6 +4247,14 @@ const { ok, status, data, error } = await api.users({ id: "42" }).get()
 
 ESM-only. 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/content
 
 Typed, schema-validated content collections for nifra — Markdown + frontmatter, framework-agnostic.
@@ -3411,6 +4274,14 @@ bun add @nifrajs/content
 
 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/core
 
 The Bun-native, contract-first HTTP framework at the heart of [nifra](../../README.md):
@@ -3447,6 +4318,14 @@ export type App = typeof app // hand this to @nifrajs/client for end-to-end type
 
 ESM-only; requires Bun at runtime. 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/cron
 
 Runtime-agnostic **in-process cron** for long-running nifra servers (Bun / Node / Deno). Standard
@@ -3508,6 +4387,14 @@ Workers has no long-lived process, so in-process cron doesn't apply. Use the pla
 trigger instead: `toFetchHandler(app, { scheduled })` from `@nifrajs/core` + a `[triggers]` cron in
 `wrangler.toml`. This package is for Bun/Node/Deno servers.
 
+## 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/deno
 
 Run a [nifra](../../README.md) app on [Deno](https://deno.com) via `Deno.serve`.
@@ -3544,6 +4431,14 @@ cap live inside `app.fetch`, so they apply through this adapter automatically.
 
 Works with any `{ fetch(req): Promise<Response> }` handler, not just nifra. ESM/TS. MIT.
 
+## 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**
@@ -3612,6 +4507,14 @@ pass the request's bindings: `defineEnv(shape, { source: env })`.
 Error messages name the offending variable and the reason — **never its value** (it may be a
 secret). `defineEnv` returns a frozen object, so a validated config can't be mutated downstream.
 
+## 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.
@@ -3631,6 +4534,14 @@ bun add @nifrajs/i18n
 
 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/image
 
 Image optimization for nifra — a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.
@@ -3650,6 +4561,14 @@ bun add @nifrajs/image
 
 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/islets
 
 Fine-grained signals + declarative DOM bindings for islands — **interactivity in ~1.4 KB gz**, no
@@ -3712,6 +4631,14 @@ into one flush. Island-scale by design: if a widget outgrows this (lists, owners
 async orchestration), that's the signal to use the Solid adapter for that page — both tiers are
 first-class.
 
+## 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
@@ -3792,6 +4719,14 @@ const app = server({ requestTimeoutMs: 5_000 })
 
 `@nifrajs/core` is a peer dependency. ESM-only. 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/node
 
 Run a [nifra](../../README.md) app on Node's `http` server — nifra's ergonomics, deployed
@@ -3855,6 +4790,14 @@ with no extra wiring. Slow-client / slow-loris protection is Node's built-in
 
 Works with any `{ fetch(req): Promise<Response> }` handler, not just nifra. ESM-only. 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/otel
 
 Distributed tracing for nifra. The `tracing()` plugin continues (or starts) a **W3C trace** per
@@ -3907,6 +4850,14 @@ Use `traceparent` and the built-in semantic attributes in every request span, th
 your own collector through an exporter. Keep the package edge-safe by installing the OpenTelemetry
 SDK only in apps that need that exporter.
 
+## 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
@@ -3937,6 +4888,14 @@ It's a **runner, not a security sandbox**: it calls the app you hand it in-proce
 Isolation, when you need it, comes from the host — the browser tab for the playground, your own
 process/CI for the agent runner. Don't feed it code you wouldn't already run.
 
+## 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/schema
 
 The optional, batteries-included schema builder for [nifra](../../README.md): `t` is
@@ -3988,6 +4947,14 @@ are still emitted without body/response detail (Standard Schema exposes no JSON
 
 `@nifrajs/core` is a peer dependency. ESM-only. 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/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.
@@ -4007,6 +4974,14 @@ bun add @nifrajs/uploads
 
 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/web
 
 Framework-agnostic SSR core for nifra — the render seam + HTML document orchestration.
@@ -4026,6 +5001,14 @@ bun add @nifrajs/web
 
 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/web-preact
 
 Preact render adapter for @nifrajs/web — streaming SSR + hydration (no build plugin).
@@ -4045,6 +5028,14 @@ bun add @nifrajs/web-preact
 
 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/web-react
 
 React render adapter for @nifrajs/web — SSR + hydration (Bun-native JSX, no Babel).
@@ -4064,6 +5055,14 @@ bun add @nifrajs/web-react
 
 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/web-solid
 
 Solid render adapter for @nifrajs/web — SSR + hydration + the Solid Babel build plugin.
@@ -4083,6 +5082,14 @@ bun add @nifrajs/web-solid
 
 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/web-svelte
 
 Svelte 5 render adapter for @nifrajs/web — SSR + hydration + the .svelte compiler Bun-plugin.
@@ -4102,6 +5109,14 @@ bun add @nifrajs/web-svelte
 
 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/web-vanilla
 
 Zero-framework render adapter for @nifrajs/web — auto-escaping tagged-template HTML, ~0 KB client JS, interactivity via @nifrajs/web/islands.
@@ -4121,6 +5136,14 @@ bun add @nifrajs/web-vanilla
 
 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/web-vue
 
 Vue render adapter for @nifrajs/web — streaming SSR + hydration, with a .vue SFC compiler Bun plugin (@nifrajs/web-vue/plugin).
@@ -4140,6 +5163,14 @@ bun add @nifrajs/web-vue
 
 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/workers
 
 Cloudflare Workers helpers for nifra — a Durable Object hub for cross-connection WebSocket broadcast.
@@ -4159,6 +5190,14 @@ bun add @nifrajs/workers
 
 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.
+
 ## create-nifra
 
 Scaffold a new [nifra](../../README.md) app.
@@ -4193,6 +5232,14 @@ bun run dev
 
 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.
+
 ## nifra
 
 The unscoped meta-entry for the **nifra** full-stack framework. It re-exports [`@nifrajs/core`](https://www.npmjs.com/package/@nifrajs/core), so:
@@ -4220,6 +5267,14 @@ Docs + an AI-readable reference: [`/llms.txt`](https://nifra.dev/llms.txt) · [`
 
 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.
+
 ---
 
 # Complete export index (generated from each package's src/index.ts)
@@ -4294,7 +5349,7 @@ MIT.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `buildManifest`, `CachedResponse`, `CacheStore`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `defer`, `Deferred`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumeratePrerenderedPaths`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `GetStaticPaths`, `hashQueryKey`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `serializeData`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `Submission`, `SubmitOptions`, `withISR`
+`Action`, `ACTION_GLOBAL`, `apiKey`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumeratePrerenderedPaths`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `GetStaticPaths`, `hashQueryKey`, `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`, `openGraph`, `OpenGraphInput`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `Submission`, `SubmitOptions`, `withISR`
 
 ## @nifrajs/web-preact