stitchkit 0.7.0 → 0.8.1

package/llms-full.txt

@@ -0,0 +1,3025 @@
+# stitchkit — full documentation
+
+> The complete guide + API reference, inlined for offline agent use. Generated
+> from the `docs/` tree (the source of truth) by `bun run gen:llms`.
+
+
+==============================================================================
+# Guide: Getting started  (docs/guide/getting-started.md)
+==============================================================================
+
+# Getting started
+
+stitchkit turns one contract into an HTTP API, MCP tools, AI-agent tools and a
+typed client. This page gets a working app running; the rest of the guide goes
+deep on each piece.
+
+## Requirements
+
+- [Bun](https://bun.sh) `>= 1.2` (recommended) or [Node.js](https://nodejs.org)
+  `>= 22`. Bun is first-class; Node is supported via `stitchkit/node`.
+
+## Install
+
+```bash
+bun add stitchkit zod
+```
+
+`zod` is a required peer — schemas are the source of truth everywhere. Other
+peers are optional and pulled in only when you use the matching feature
+(`@modelcontextprotocol/sdk` for MCP, `ai` for agents, `socket.io*` for
+realtime, `@tanstack/react-query` + `react-query-kit` for React). See
+[deps](#dependencies) below.
+
+## Entrypoints
+
+stitchkit ships five entrypoints. Each is import-safe for one environment —
+keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
+
+| Import | Use in | Holds |
+|--------|--------|-------|
+| `stitchkit` | browser **and** server | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
+| `stitchkit/contract` | browser **and** server | the contract layer alone — `defineContract`, errors, pagination |
+| `stitchkit/server` | server | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
+| `stitchkit/tools` | server | `createMcpHandler`, `mountMcp`, `mountAgent` |
+| `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
+
+Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
+code adds `stitchkit/server` and `stitchkit/tools`.
+
+## Project layout
+
+A contract is shared by both sides, so it lives in its own folder:
+
+```
+src/
+├── shared/contracts.ts   the contract — imported by server and client
+├── server/index.ts       implement() + createServer()
+└── client/api.ts         createClient()
+```
+
+## A first app
+
+### 1. Define the contract
+
+```ts
+// src/shared/contracts.ts
+import { defineContract } from 'stitchkit'
+import { z } from 'zod'
+
+const Note = z.object({ id: z.string(), text: z.string() })
+
+export const notes = defineContract({ prefix: 'notes' }, {
+  list:   { method: 'GET',  path: '/',    desc: 'List notes',  output: z.array(Note) },
+  create: { method: 'POST', path: '/',    desc: 'Create note', input: z.object({ text: z.string() }), output: Note },
+  get:    { method: 'GET',  path: '/:id', desc: 'Get a note',  params: z.object({ id: z.string() }), output: Note },
+})
+```
+
+### 2. Implement and serve
+
+```ts
+// src/server/index.ts
+import { implement, createServer } from 'stitchkit/server'
+import { notes } from '../shared/contracts'
+
+const service = implement(notes, {
+  list:   ()    => db.list(),
+  create: (ctx) => db.create(ctx.input.text),   // ctx.input is typed
+  get:    (ctx) => db.get(ctx.params.id),       // ctx.params is typed
+})
+
+createServer({ services: [service], port: 3000 })
+```
+
+### 3. Call it, typed
+
+```ts
+// src/client/api.ts
+import { createClient, createHttpClient } from 'stitchkit'
+import { notes } from '../shared/contracts'
+
+export const api = createClient(notes, createHttpClient({ baseUrl: '/api' }))
+
+await api.list()                   // GET  /notes      → Note[]
+await api.create({ text: 'hi' })   // POST /notes      → Note
+await api.get({ id: '1' })         // GET  /notes/1    → Note
+```
+
+Run the server with `bun run src/server/index.ts`. The contract is the single
+source of truth — change it and both the handler and the client are re-typed at
+once.
+
+#### On Node
+
+`createServer` is Bun's `Bun.serve`. On **Node ≥ 22**, swap it for `serveNode`
+(from `stitchkit/node`, built on `srvx`) — the contract, `implement` and the
+client are identical:
+
+```ts
+import { serveNode } from 'stitchkit/node'
+
+serveNode({ services: [service], port: 3000 })
+```
+
+Add `@types/bun` as a dev dependency on Node (an optional peer — it types the
+shared `stitchkit/server` surface). See [deployment](./testing-and-deployment.md#deploy-on-node).
+
+## Dependencies
+
+`ky` is the **only** bundled runtime dependency. Everything else is an *optional
+peer* — your app installs only what the features it uses need, and owns the
+version (one shared instance, no dual-version skew). This matrix is the install
+map — feature → packages:
+
+| Feature you use | Install |
+|-----------------|---------|
+| anything (validation) | `zod` |
+| `createServer` (Bun) | — (uses `Bun.serve`) |
+| `serveNode` (Node ≥ 22) | `srvx` (+ `@types/bun` dev) |
+| MCP tools (`stitchkit/tools`) | `@modelcontextprotocol/sdk` |
+| MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
+| agent tools (`stitchkit/tools`) | `ai` |
+| React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
+| **Socket.IO server on Bun** | `socket.io` `@socket.io/bun-engine` |
+| **Socket.IO server on Node** | `socket.io` |
+| Socket.IO client | `socket.io-client` |
+
+```bash
+bun add socket.io @socket.io/bun-engine    # e.g. the Socket.IO server on Bun
+```
+
+If an optional peer is missing, the feature that needs it fails with an
+actionable error naming the package and the install command — not a bare
+`Cannot find module`.
+
+## Next
+
+- [Contracts](./contracts.md) — every endpoint field, in depth.
+- [HTTP server](./server.md) — `createServer`, hooks, raw routes, primitives.
+- [Typed client](./client.md) — the client, React data layer, SSE.
+- [MCP & agents](./mcp-and-agents.md) — contracts as AI tools.
+- [Realtime](./realtime.md) — Socket.IO and the cache bridge.
+- [Auth & errors](./auth-and-errors.md) — scopes, auth hooks, the error model.
+- [Testing & deployment](./testing-and-deployment.md).
+- [API reference](../api/reference.md) — every export, by entrypoint.
+
+A complete runnable app is in [`packages/starter`](../../packages/starter).
+
+
+==============================================================================
+# Guide: Contracts  (docs/guide/contracts.md)
+==============================================================================
+
+# Contracts
+
+A **contract** describes a set of operations once — method, path, schemas,
+scope, which transports each is exposed on. From it stitchkit derives the HTTP
+route, the MCP tool, the agent tool and the typed client. One declaration; the
+surfaces cannot drift.
+
+## `defineContract`
+
+```ts
+import { defineContract } from 'stitchkit'
+
+const contract = defineContract(meta, endpoints)
+```
+
+- **`meta`** — `{ prefix: string }`, or `{ prefix: string, scope: string }` to
+  give every endpoint a default scope.
+- **`endpoints`** — a map of `key → endpoint definition`. The key becomes the
+  client method name and the handler name.
+
+`defineContract` throws at definition time if two endpoints declare the same
+`toolName` on the same transport — a tool-name clash is a bug, caught early.
+
+## An endpoint
+
+```ts
+export const users = defineContract({ prefix: 'users' }, {
+  list: {
+    method: 'GET',
+    path: '/',
+    desc: 'List all users',
+    output: z.array(UserSchema),
+  },
+  create: {
+    method: 'POST',
+    path: '/',
+    desc: 'Create a user',
+    input: CreateUserSchema,
+    output: UserSchema,
+  },
+  get: {
+    method: 'GET',
+    path: '/:id',
+    desc: 'Get a user by id',
+    params: z.object({ id: z.string() }),
+    output: UserSchema,
+  },
+})
+```
+
+### Fields
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `method` | yes | `GET` · `POST` · `PUT` · `PATCH` · `DELETE` |
+| `path` | yes | route path under the contract `prefix`; `:name` marks a path param |
+| `desc` | yes | human description — also the MCP / agent tool description |
+| `params` | no | Zod schema for **path params** (`:id`, …) |
+| `input` | no | Zod schema for the **request body** (or query, for GET/DELETE) |
+| `output` | no | Zod schema for the **response body** |
+| `scope` | no | access scope for this endpoint — see [Auth & errors](./auth-and-errors.md) |
+| `expose` | no | which transports carry this endpoint — see [below](#transports) |
+| `toolName` | no | explicit MCP / agent tool name (defaults to `prefix_key`) |
+| `multipart` | no | field name of a file upload — see [below](#file-uploads) |
+| `timeout` | no | per-endpoint client timeout in ms, for slow endpoints |
+| `meta` | no | opaque app metadata — read in hooks / on tool mounts, never in OpenAPI ([below](#endpoint-metadata-meta)) |
+
+## `params` vs `input` vs `output`
+
+The three schemas are distinct on purpose:
+
+- **`params`** — values in the URL path. `path: '/:id'` ⇒
+  `params: z.object({ id: z.string() })`. The client takes them from the call
+  argument and substitutes them into the URL.
+- **`input`** — the request payload. For `POST` / `PUT` / `PATCH` it is the JSON
+  body; for `GET` / `DELETE` it is the query string. The handler reads it as
+  `ctx.input`.
+- **`output`** — the response shape. When set, the client parses the response
+  through it; the handler's return value is type-checked against it.
+
+The typed client merges `params` and `input` into one argument object — the
+caller passes a single flat object, the client routes each field to the path or
+the body.
+
+```ts
+// path: '/:id', params: { id }, input: { text }
+await api.update({ id: '1', text: 'new' })   // PUT /users/1  body: { text: 'new' }
+```
+
+### Input vs. output types
+
+For the client, an endpoint's argument type is the schema's **input** type
+(pre-parse). A field with `.default()` is therefore optional for the caller but
+present (required) in the handler's parsed `ctx.input`. The contract handles the
+two type views; you do not.
+
+## Transports
+
+By default an endpoint is exposed on **every** surface — HTTP, MCP and agent
+tools. Narrow it with `expose`:
+
+```ts
+{
+  method: 'POST', path: '/', desc: 'Internal sync',
+  expose: ['HTTP'],            // HTTP only — not an MCP or agent tool
+}
+{
+  method: 'GET', path: '/search', desc: 'Search the catalog',
+  expose: ['HTTP', 'MCP', 'AGENT'],   // explicit — all three
+}
+```
+
+- `expose: ['HTTP']` — HTTP only. The endpoint never becomes a tool.
+- `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
+- omit `expose` — all transports.
+
+Tool transports (`MCP`, `AGENT`) skip `multipart` endpoints automatically — a
+file upload is not a tool call.
+
+## `toolName`
+
+When an endpoint is exposed as a tool, its name defaults to `prefix_key`
+(`users` + `create` ⇒ `users_create`). Set `toolName` for an explicit, stable
+name:
+
+```ts
+{ method: 'POST', path: '/', desc: 'Create a user', toolName: 'create_user', /* … */ }
+```
+
+## Endpoint metadata (`meta`)
+
+`meta` is an **opaque, app-defined** bag the core attaches no meaning to — the
+same escape-hatch spirit as `scope` being a free string ([ADR 0002](../decisions/0002-generic-core.md) /
+[ADR 0021](../decisions/0021-endpoint-meta-passthrough.md)). Declare app concerns
+the generic core does not model — a feature gate, a rate tier, a cache hint, a
+doc/owner tag — right next to the endpoint:
+
+```ts
+broadcast: {
+  method: 'POST', path: '/broadcast', desc: 'Send a broadcast',
+  input: BroadcastInput, output: Broadcast,
+  meta: { requiredFeature: 'broadcasts' },   // opaque to the core
+}
+```
+
+It rides through to `MethodDef.meta`, readable in lifecycle hooks (the second
+argument is the endpoint) and on tool mounts. The consumer narrows the type when
+reading:
+
+```ts
+beforeHandle: (ctx, endpoint) => {
+  const feature = endpoint.meta?.requiredFeature
+  if (typeof feature === 'string' && !ctx.user?.features?.includes(feature)) {
+    throw forbidden('feature not enabled')
+  }
+}
+```
+
+`meta` is **app-private** — it is never serialized into the OpenAPI document.
+
+> **Declare a meta type as a `type`, an inline literal, or with `satisfies` — not
+> an `interface`.** A TS `interface` has no implicit index signature (it can be
+> augmented by declaration merging), so it is not assignable to `meta`'s
+> `Record<string, unknown>` — and on the overloaded `defineContract` the error
+> misleadingly surfaces as a `scope` mismatch. Use
+> `type EndpointMeta = { requiredFeature?: PlanFeature }`, or
+> `meta: { requiredFeature: 'x' } satisfies EndpointMeta`. The read side is
+> unchanged — `endpoint.meta?.x` is `unknown`, narrow it in the hook.
+
+## File uploads
+
+`multipart` names the form field carrying a file. The handler receives it as
+`ctx.file`:
+
+```ts
+upload: {
+  method: 'POST',
+  path: '/avatar',
+  desc: 'Upload an avatar',
+  multipart: 'file',
+  output: z.object({ url: z.string() }),
+}
+```
+
+The client sends a `multipart/form-data` request; the field value must be a
+`Blob`. See [HTTP server → multipart](./server.md#multipart).
+
+## Pagination
+
+Every list endpoint should return the cursor envelope — one shape, one infinite-
+query helper:
+
+```ts
+import { paginatedSchema } from 'stitchkit'
+
+feed: {
+  method: 'GET',
+  path: '/',
+  desc: 'Paginated feed',
+  input: z.object({ limit: z.coerce.number().default(20) }),
+  output: paginatedSchema(PostSchema),   // { items: Post[], nextCursor: string | null }
+}
+```
+
+`paginatedSchema(itemSchema)` produces `{ items, nextCursor }`. The page size
+default lives in the contract (`limit`'s `.default()`), never on the client —
+the two cannot diverge. The client side is [`createCursorQuery`](./client.md#cursor-pagination).
+
+The **format** of `nextCursor` is the server's choice — keep it opaque. For the
+usual keyset cursor (resume after the last row's `(sortValue, id)`), encode it
+with **`encodeCursor`** and read it back with **`decodeCursor`** (Zod-validated;
+a missing or garbage cursor decodes to `null`, i.e. "start from the top"):
+
+```ts
+import { encodeCursor, decodeCursor } from 'stitchkit'
+
+const Cursor = z.object({ v: z.string(), id: z.string() })   // your keyset shape
+
+const after = decodeCursor(ctx.input.cursor, Cursor)         // { v, id } | null
+const rows = await db.list({ after, take: limit + 1 })        // your keyset WHERE
+const nextCursor =
+  rows.length > limit ? encodeCursor({ v: last.createdAt, id: last.id }) : null
+```
+
+The codec is base64url over UTF-8 (`btoa`/`atob`, not Node `Buffer`) — server,
+client and browser safe, and a non-ASCII sort value round-trips. The keyset
+WHERE clause is yours (it's ORM-specific); stitchkit only carries the string.
+
+## Scope
+
+An endpoint may carry a `scope` string; the contract `meta.scope` is the default
+for every endpoint that declares none. Scopes are free strings — the framework
+attaches no meaning, your auth hook does. See
+[Auth & errors](./auth-and-errors.md).
+
+## One source of truth
+
+A contract is plain data — no classes, no decorators, no codegen. It is imported
+by the server (to `implement`), by the client (to `createClient`) and by the
+tool layer (to `mountMcp` / `mountAgent`). Change an endpoint and every surface
+is re-typed by the compiler at once.
+
+
+==============================================================================
+# Guide: HTTP server  (docs/guide/server.md)
+==============================================================================
+
+# HTTP server
+
+stitchkit serves contracts on `Bun.serve()` directly — no Hono, no Elysia, no
+Express. You bind a contract to handlers with `implement()`, then mount the
+result on `createServer()`.
+
+## `implement`
+
+`implement(contract, handlers)` type-checks each handler against its endpoint's
+schemas and returns a `ServiceDef` to mount.
+
+```ts
+import { implement } from 'stitchkit/server'
+import { users } from '../shared/contracts'
+
+const usersService = implement(users, {
+  list:   ()    => db.users.findMany(),
+  create: (ctx) => db.users.create(ctx.input),       // ctx.input: typed
+  get:    (ctx) => db.users.findById(ctx.params.id), // ctx.params: typed
+  delete: (ctx) => db.users.delete(ctx.params.id),
+})
+```
+
+A handler may be sync or async. Its return value is checked against the
+endpoint's `output` schema; an endpoint without `output` returns nothing.
+
+### The handler context
+
+Every handler receives one `ctx` argument:
+
+| `ctx` field | Type | Source |
+|-------------|------|--------|
+| `params` | inferred from `params` schema | parsed path params |
+| `input` | inferred from `input` schema | parsed body / query |
+| `file` | `File` | the `multipart` upload, if any |
+| `source` | `'http' \| 'mcp' \| 'agent'` | the transport that invoked the handler |
+| `traceId` | `string` | per-request trace id |
+| `ipAddress` | `string` | caller IP |
+| `userAgent` | `string` | caller user-agent |
+
+The same handler runs for HTTP, MCP and agent calls — `ctx.source` tells you
+which. Anything an auth hook attaches (e.g. the resolved user) is also on `ctx`.
+
+### `createImplement` — a fixed context type
+
+To type `ctx` with your app's extras (the user an auth hook injects), fix the
+context type once:
+
+```ts
+import { createImplement } from 'stitchkit/server'
+
+interface AppContext extends RuntimeContext { user: User | null }
+
+export const implement = createImplement<AppContext>()
+// every implement() call now has ctx.user typed
+```
+
+## `createServer`
+
+`createServer(config)` builds the router and starts `Bun.serve()`. It returns
+the Bun server instance.
+
+```ts
+import { createServer } from 'stitchkit/server'
+
+createServer({
+  services: [usersService, postsService],
+  port: 3000,
+  cors: { origin: 'https://app.example.com' },
+  hooks: { /* … */ },
+  logging: true,
+})
+```
+
+`createHandler(config)` is the same router as a bare `(req) => Promise<Response>`
+function — no `Bun.serve`. Use it in tests, or to embed stitchkit in another
+server. See [Testing & deployment](./testing-and-deployment.md).
+
+### `ServerConfig`
+
+| Field | Purpose |
+|-------|---------|
+| `services` | `ServiceDef[]` mounted at the root |
+| `groups` | route groups — a shared path prefix and hooks (see below) |
+| `scopePrefixes` | `scope → path prefix` map — mount `services` by `service.scope` (see below) |
+| `rawRoutes` | non-contract routes (see below) |
+| `maxUploadBytes` | default multipart upload cap (bytes); per-route `EndpointDef.maxUploadBytes` overrides |
+| `port` / `hostname` | listen address — port defaults to `3000` |
+| `cors` | CORS policy — `{ origin, … }` |
+| `hooks` | lifecycle hooks (see below) |
+| `logging` | `true` for built-in request logs, or a custom `StitchLogger` |
+| `traceId` | override per-request trace-id resolution |
+| `websocket` | Bun WebSocket handlers — e.g. from `createSocketIOServer` |
+| `routes` / `development` / `bun` | passthrough to `Bun.serve` |
+
+## Route groups
+
+A group gives a set of services a shared path prefix and its own hooks:
+
+```ts
+createServer({
+  groups: [
+    { pathPrefix: '/api',       services: [usersService, postsService] },
+    { pathPrefix: '/api/admin', services: [adminService], hooks: { beforeHandle: adminAuth } },
+  ],
+})
+```
+
+Each service's own `prefix` is appended to the group prefix — `usersService`
+above is served at `/api/users`.
+
+### Param prefixes (resource-scoped paths)
+
+A group `pathPrefix` may contain `:param` segments — the spine of a multi-tenant
+or resource-scoped API:
+
+```ts
+createServer({
+  groups: [
+    { pathPrefix: '/tenants/:tenantId', services: [widgetsService], hooks: { beforeHandle: auth } },
+  ],
+})
+// widgetsService (prefix 'widgets') → /tenants/:tenantId/widgets/...
+```
+
+**Where the prefix param lands.** The router matches the *full* path (group
+prefix + service prefix + endpoint path) and collects every `:param` — from the
+prefix and from the endpoint alike — into one set. Each is spread onto the
+context root, so it is available as **`ctx.tenantId`** (a raw `string`) in both
+the handler and `beforeHandle`/`afterHandle`/`onError`:
+
+```ts
+beforeHandle: (ctx) => {
+  const tenantId = ctx.tenantId   // string — from the group prefix
+}
+```
+
+`ctx.tenantId` is typed `unknown` (it rides the context index signature) — narrow
+it (`String(ctx.tenantId)` / a guard) at the read site.
+
+**Relation to the endpoint `params` schema.** `ctx.params` is the endpoint's
+`params` schema **parsed against all collected path params** (prefix + endpoint).
+So to get the prefix param *inside* typed `ctx.params`, add it to that schema:
+
+```ts
+// endpoint under /tenants/:tenantId
+{ method: 'GET', path: '/:widgetId', desc: 'Get a widget',
+  params: z.object({ tenantId: z.string(), widgetId: z.string() }) }
+// → ctx.params.tenantId and ctx.params.widgetId both typed
+```
+
+⚠️ A **`z.strictObject`** params schema that omits the prefix param **rejects the
+request** (the extra `tenantId` key fails the strict parse). Either include every
+prefix param in the schema, use a non-strict `z.object` (extra keys are dropped
+from `ctx.params`, but `ctx.tenantId` still works), or read the param off the
+context root.
+
+### Scope-driven mounting (`scopePrefixes`)
+
+With several scopes, hand-partitioning services into `groups` duplicates the
+scope↔prefix mapping. Instead, map `scope → prefix` once and pass the flat
+`services` list — each entry mounts under `scopePrefixes[service.scope]`:
+
+```ts
+createServer({
+  services,   // mixed scopes, listed once
+  scopePrefixes: { tenant: 'tenants/:tenantId', project: 'projects/:projectId' },
+})
+// scope 'tenant'  → /tenants/:tenantId/<prefix>/...
+// scope 'project' → /projects/:projectId/<prefix>/...
+// unmapped scope  → mounted flat
+```
+
+A prefix may carry `:param` segments (they land on the context exactly as above).
+Services listed under explicit `groups` are unaffected — the group prefix wins.
+Scope stays a free string; the core attaches no meaning beyond this lookup
+(→ ADR 0024). When each scope needs a different handler-context shape, declare one
+`createImplement<Ctx>()` per scope rather than a single superset context.
+
+## Lifecycle hooks
+
+Four hooks wrap every contract request, in order:
+
+```ts
+createServer({
+  services,
+  hooks: {
+    onRequest(req)               { /* logging, global rate limit — may return a Response to short-circuit */ },
+    beforeHandle(ctx, endpoint)  { /* auth, scope checks — throw to reject */ },
+    afterHandle(ctx, result, ep) { /* transform the result, set cache headers */ },
+    onError(ctx, error, ep)      { /* custom error response — return a Response */ },
+  },
+})
+```
+
+- **`onRequest`** — runs first, with the raw `Request`. Return a `Response` to
+  short-circuit (a rate-limit 429, a redirect); return nothing to continue.
+- **`beforeHandle`** — runs after the context is built, before the handler.
+  Throw an `AppError` to reject. This is where auth lives —
+  [`createAuthHook`](./auth-and-errors.md#createauthhook) is a `beforeHandle`.
+- **`afterHandle`** — receives the handler result; return a replacement to
+  transform it.
+- **`onError`** — receives any thrown error; return a `Response` to customise
+  the error body. Without it, errors render through the standard envelope.
+
+Hooks see `RuntimeContext` (loose types); handlers see `HandlerContext` (typed).
+That split is deliberate — see [ADR 0003](../decisions/0003-two-context-types.md).
+
+## Raw routes
+
+Some routes cannot be a clean JSON contract — an OAuth redirect, a webhook with
+signature verification, static files, the Socket.IO endpoint. `rawRoutes` are
+plain `Request → Response` handlers, matched by the same router (shared CORS and
+`onRequest`) but with no schema parsing and no `beforeHandle` gate — a raw route
+authorises itself.
+
+```ts
+createServer({
+  services,
+  rawRoutes: [
+    {
+      method: 'GET',
+      path: '/health',
+      handler: () => Response.json({ status: 'ok' }),
+    },
+    {
+      method: 'POST',
+      path: '/webhooks/:provider',
+      handler: (req, ctx) => handleWebhook(ctx.params.provider, req),
+    },
+  ],
+})
+```
+
+A path may be exact, carry `:param` segments, or end in `/*` for a prefix
+wildcard — and the two combine: `/app/:slug/*` matches `/app/x/a/b` with
+`ctx.params.slug === 'x'` and the remainder in `ctx.params['*']` (a SPA
+deep-link fallback). List more specific routes before the wildcard — the first
+match wins. `staticRoute()` builds a raw route that serves a directory.
+
+### Raw-route helpers
+
+A raw route gives up the contract pipeline, so three things get re-implemented in
+every one. `stitchkit/server` ships them — conveniences, not a second pipeline
+(no auth, no schema gate beyond `parseBody`):
+
+```ts
+import { respondJson, errorResponse, parseBody, badRequest } from 'stitchkit/server'
+
+handler: async (req) => {
+  try {
+    const body = await parseBody(req, MySchema)      // typed value, or null (no throw)
+    if (!body) throw badRequest('invalid body')      // helpers THROW an AppError
+    return respondJson(await myService(body))         // JSON; 204 when null/undefined
+  } catch (err) {
+    return errorResponse(err)                         // same envelope as a contract route
+  }
+}
+```
+
+The error helpers (`badRequest`, `notFound`, …) **throw** an `AppError`, so raise
+them inside the `try` and let `errorResponse(err)` render it — that runs any
+thrown value through the framework's `normalizeError`, so a raw route returns the
+**identical** `{ error: { code, message, … } }` shape (and `x-request-id`) a
+contract route does.
+
+### Serving files & Range requests
+
+`staticRoute` is basic on purpose — it reads the whole file into memory and has
+no `Range` or conditional support; put a CDN in front, or use it for small web
+assets. To serve **media** (video / audio / large downloads) that a browser must
+seek and cache, use **`serveFile`** (Bun) — it streams the requested byte range
+and speaks the conditional-request half of RFC 7233 / 9110:
+
+```ts
+import { serveFile } from 'stitchkit/server'
+
+createServer({
+  services,
+  rawRoutes: [
+    {
+      // `ALL` — so a HEAD probe also reaches serveFile (raw routes match the
+      // method exactly, and `HEAD` is not a contract `HttpMethod`); serveFile
+      // itself handles GET + HEAD and answers 405 for anything else.
+      method: 'ALL',
+      path: '/media/:id',
+      handler: (req, ctx) =>
+        serveFile(req, { path: pathForId(ctx.params.id), filename: 'clip.mp4' }),
+    },
+  ],
+})
+```
+
+`serveFile` returns `206` (range, with `Content-Range` + `Content-Length`), `200`
+(full), `416` (unsatisfiable, `Content-Range: bytes */size`), `304`
+(`If-None-Match` / `If-Modified-Since`), `404` (missing) or `405` (non GET/HEAD).
+It always sets `Accept-Ranges: bytes`, a weak `ETag` and `Last-Modified` (so
+`If-Range` keeps a changing file from being stitched from stale + fresh bytes),
+and `nosniff`. `Content-Type` is auto-detected from the path — override it, or
+pass `disposition` / `cacheControl` / `etag: false`, via the options.
+
+`serveFile` takes an explicit `path` and trusts it — **the caller owns
+containment**. For a URL-derived path use `staticRoute` (which enforces it) or
+`isWithinDir` first. The byte-range parser is exported on its own as
+`parseByteRange(header, size)` for direct use and testing. → ADR 0023.
+
+## Server primitives
+
+`stitchkit/server` also exports the primitives most APIs need. Each is a small,
+focused helper — not a sub-framework.
+
+| Helper | Does |
+|--------|------|
+| `serveFile()` | serve a file with `Range` / `304` / `HEAD` (media seeking) |
+| `streamSSE()` | turn an `AsyncGenerator` into a Server-Sent-Events `Response` |
+| `parseMultipart()` | parse a `multipart/form-data` request with a size cap |
+| `createRateLimiter()` | per-key token-bucket rate limiting |
+| `createCache()` + `cacheHeaders()` | in-memory TTL cache; `Cache-Control` builder |
+| `createEventBus<EventMap>()` | typed in-process pub/sub |
+
+### SSE streaming
+
+```ts
+import { streamSSE } from 'stitchkit/server'
+
+async function* tokens() { yield 'a'; yield 'b' }
+return streamSSE(tokens())            // → a text/event-stream Response
+```
+
+The client side is [`parseSSE`](./client.md#sse).
+
+### Multipart
+
+```ts
+import { parseMultipart } from 'stitchkit/server'
+
+const { file, fields } = await parseMultipart(req, { maxBytes: 10_000_000 })
+```
+
+When an endpoint declares `multipart`, the framework parses the upload for you
+and the file arrives as `ctx.file` — call `parseMultipart` directly only from a
+raw route.
+
+The upload cap defaults to **25 MB**. Raise it per route with
+`EndpointDef.maxUploadBytes`, or set a server-wide default with
+`createServer({ maxUploadBytes })` — a per-route value wins over the global:
+
+```ts
+// contract
+upload: { method: 'POST', path: '/', desc: 'Upload a video',
+          multipart: 'file', maxUploadBytes: 200 * 1024 * 1024 }
+
+// server — default for every multipart route that declares no own cap
+createServer({ services, maxUploadBytes: 50 * 1024 * 1024 })
+```
+
+### Rate limiting
+
+```ts
+import { createRateLimiter } from 'stitchkit/server'
+
+const limiter = createRateLimiter({ capacity: 60, refillPerSecond: 1 })
+// in onRequest: if (!limiter.take(ip)) return new Response('Too many', { status: 429 })
+```
+
+### Event bus
+
+```ts
+import { createEventBus } from 'stitchkit/server'
+
+const bus = createEventBus<{ 'user.created': { id: string } }>()
+bus.on('user.created', ({ id }) => sendWelcome(id))
+bus.emit('user.created', { id: '1' })
+```
+
+A typed in-process pub/sub — decouple a handler from the side effects of its
+write without reaching for an external queue.
+
+
+==============================================================================
+# Guide: Typed client  (docs/guide/client.md)
+==============================================================================
+
+# Typed client
+
+From a contract, `createClient` builds a fully-typed client — one method per
+endpoint, arguments and result inferred from the schemas. There is no codegen
+step: the types come straight from the contract import.
+
+## `createHttpClient`
+
+The HTTP client is the transport. It wraps [`ky`](https://github.com/sindresorhus/ky)
+and adds cookie auth, SSR cookie forwarding, error parsing into `ApiError`, a
+`401 → unauthorized` event stream and safe transport retry.
+
+```ts
+import { createHttpClient } from 'stitchkit'
+
+const http = createHttpClient({ baseUrl: '/api' })
+```
+
+### `HttpClientConfig`
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `baseUrl` | — | URL prefix for every request |
+| `timeout` | `30000` | request timeout, ms |
+| `credentials` | `'include'` | fetch credentials mode |
+| `retry` | 2× GET, network errors only | transport retry policy |
+| `headers` | — | extra headers — an object, or a function re-run per request |
+| `authEndpoints` | `['auth/']` | paths that should **not** emit `unauthorized` on 401 |
+| `parseError` | built-in | map an error body to `{ code, message, details, hint }` |
+
+`headers` as a function is the hook for runtime tokens — a bearer token or any
+short-lived credential — re-evaluated on every request.
+
+Retry is deliberately conservative: only a connection that never landed (a
+network error), only on idempotent `GET`. A server that *responded* with a 5xx
+is the data layer's call (TanStack Query), not the transport's — retrying in
+both places multiplies attempts.
+
+## `createClient`
+
+```ts
+import { createClient } from 'stitchkit'
+import { users } from '../shared/contracts'
+
+export const api = createClient(users, http)
+
+await api.list()                   // GET    /users
+await api.create({ name: 'Max' })  // POST   /users      body: { name }
+await api.get({ id: '1' })         // GET    /users/1
+await api.update({ id: '1', name: 'M' })  // PUT /users/1  body: { name }
+await api.delete({ id: '1' })      // DELETE /users/1
+```
+
+Each call takes one argument object. The client routes each field by the
+contract:
+
+- a **path param** (`:id`) is substituted into the URL,
+- for `GET` / `DELETE`, the remaining fields become the **query string**
+  (arrays become repeated keys),
+- for `POST` / `PUT` / `PATCH`, they become the **JSON body**,
+- a `multipart` field must be a `Blob` and is sent as `form-data`.
+
+### Many contracts at once
+
+```ts
+import { createClients } from 'stitchkit'
+
+export const api = createClients({ users, posts, billing }, http)
+await api.users.list()
+await api.posts.create({ title: 'Hi' })
+```
+
+`createClients` builds one typed client per contract from a registry — list the
+contracts once, get the whole API typed.
+
+## `ApiError`
+
+A non-2xx response is thrown as an `ApiError`:
+
+```ts
+import { ApiError } from 'stitchkit'
+
+try {
+  await api.get({ id: 'missing' })
+} catch (err) {
+  if (ApiError.is(err)) {
+    err.code     // 'NOT_FOUND'
+    err.status   // 404
+    err.message  // 'Note not found'
+    err.details  // structured details, if any
+    err.hint     // optional hint
+  }
+}
+```
+
+The error model is shared with the server — see [Auth & errors](./auth-and-errors.md).
+
+## Auth events
+
+The HTTP client emits events your app can react to globally:
+
+```ts
+const unsubscribe = http.subscribe((event) => {
+  if (event.type === 'unauthorized') redirectToLogin()  // a 401 outside authEndpoints
+  if (event.type === 'network_error') showOfflineBanner()
+})
+
+http.logout()            // mark logged out — suppresses further unauthorized events
+http.resetLogoutState()  // clear it after a fresh login
+```
+
+## Server-side rendering
+
+For SSR, forward the incoming request's cookies so the API call runs as the
+logged-in user:
+
+```ts
+http.setServerContext(request.headers.get('cookie') ?? '')
+```
+
+## A bare fetch client
+
+If you do not need cookie auth, retry or the event stream, pass a plain config
+instead of an `HttpClient` — `createClient` then builds a minimal `fetch`-based
+client:
+
+```ts
+const api = createClient(users, {
+  baseUrl: 'https://api.example.com',
+  headers: () => ({ Authorization: `Bearer ${token()}` }),
+  onError: (status, body) => console.warn(status, body),
+})
+```
+
+## `ContractClientConfig` — per-tenant / resource-scoped clients
+
+`createClient` takes an optional **third** argument that prepends a dynamic
+segment to every URL — the client half of a multi-tenant API
+([Route groups → param prefixes](./server.md#param-prefixes-resource-scoped-paths)):
+
+```ts
+interface ContractClientConfig {
+  /** Prepended to every request URL. A function is called per request with the
+   *  call's argument object, so the prefix can depend on the arguments. */
+  pathPrefix?: string | ((args: Record<string, unknown>) => string)
+  /** Argument keys consumed by `pathPrefix` — stripped from the query/body so
+   *  they are not also sent there (the endpoint's own path `:params` are
+   *  stripped automatically; list any *extra* keys here). */
+  stripPrefixKeys?: string[]
+}
+```
+
+A per-tenant client — `tenantId` goes into the URL, not the body:
+
+```ts
+const widgets = createClient(widgetsContract, http, {
+  pathPrefix: (args) => `tenants/${args.tenantId}/`,
+  stripPrefixKeys: ['tenantId'],
+})
+
+widgets.list({ tenantId: 't_123' })            // GET  /tenants/t_123/widgets
+widgets.create({ tenantId: 't_123', name: 'A' }) // POST /tenants/t_123/widgets  body: { name }
+```
+
+"Keys it consumes" = a key the `pathPrefix` function reads (here `tenantId`).
+List it in `stripPrefixKeys` so it lands in the URL **and is removed from the
+query/body** — otherwise it would be sent twice. Endpoint path `:params` are
+stripped for you; only extra prefix keys need listing.
+
+## React data layer
+
+stitchkit does not ship a hook engine. Pair the typed client with
+[`react-query-kit`](https://github.com/liaoliao666/react-query-kit) — wrap the
+client methods directly:
+
+```ts
+import { createQuery, createMutation } from 'react-query-kit'
+import { api } from './api'
+
+export const useUsers      = createQuery({ queryKey: ['users'], fetcher: () => api.list() })
+export const useCreateUser = createMutation({ mutationFn: api.create })
+```
+
+### Cursor pagination
+
+For a cursor-paginated list, `createCursorQuery` is the canonical helper:
+
+```ts
+import { createCursorQuery } from 'stitchkit/react'
+import { api } from './api'
+
+export const useFeed = createCursorQuery({
+  queryKey: ['feed'],
+  endpoint: api.feed,     // the contract method
+})
+```
+
+It injects `cursor` from the page param and bakes in `getNextPageParam` /
+`initialPageParam` — an infinite hook is just `queryKey + endpoint`. The page
+size is the server's call (the contract's `limit` default); the client never
+sends one. The result keeps the full `react-query-kit` surface (`.getKey()`,
+`useSuspenseInfiniteQuery`, every option). The endpoint must return the
+`{ items, nextCursor }` envelope — see [Contracts → pagination](./contracts.md#pagination).
+
+## SSE
+
+For a streaming endpoint, consume the response with `parseSSE`:
+
+```ts
+import { parseSSE } from 'stitchkit'
+
+const res = await fetch('/api/chat/stream', { method: 'POST', body })
+for await (const event of parseSSE(res)) {
+  console.log(event.data)
+}
+```
+
+The server side is [`streamSSE`](./server.md#sse-streaming).
+
+
+==============================================================================
+# Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
+==============================================================================
+
+# MCP & AI agents
+
+The same contract that drives the HTTP API also drives AI tooling. An endpoint
+exposed on `MCP` becomes a [Model Context Protocol](https://modelcontextprotocol.io)
+tool — callable from Claude, Cursor and other MCP clients. An endpoint exposed on
+`AGENT` becomes a [Vercel AI SDK](https://sdk.vercel.ai) tool — callable from an
+agent loop. No tool is hand-written; both come from the contract.
+
+## Which endpoints become tools
+
+By default every endpoint is a tool on every transport. `expose` narrows it:
+
+```ts
+{ method: 'GET', path: '/search', desc: 'Search the catalog' }                  // HTTP + MCP + AGENT
+{ method: 'POST', path: '/sync', desc: 'Internal sync', expose: ['HTTP'] }       // HTTP only
+{ method: 'GET', path: '/lookup', desc: 'Look up a price', expose: ['MCP'] }     // MCP tool only
+```
+
+`desc` is the tool description the model reads — write it for the model, not
+just for a human. A `multipart` endpoint is never a tool. The tool name defaults
+to a verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
+`get_widget`); set `toolName` for an explicit one. See
+[Contracts → transports](./contracts.md#transports).
+
+## MCP — `createMcpHandler`
+
+`createMcpHandler` builds a complete Streamable-HTTP MCP server as a single
+`Request → Response` handler. It owns the whole MCP lifecycle — the SSE event
+store, per-session transports, the server instances — so your app never imports
+`@modelcontextprotocol/sdk` itself.
+
+```ts
+import { createMcpHandler } from 'stitchkit/tools'
+
+const handleMcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: (req) => resolveApiKey(req),   // → an identity, or null for 401
+  services: [usersService, catalogService],
+})
+```
+
+Mount the returned handler on a raw route — typically `/mcp`:
+
+```ts
+createServer({
+  services,
+  rawRoutes: [{ method: 'ALL', path: '/mcp', handler: (req) => handleMcp(req) }],
+})
+```
+
+### `McpHandlerConfig`
+
+| Field | Purpose |
+|-------|---------|
+| `serverInfo` | MCP server identity — `{ name, version }` |
+| `auth` | `(req) => identity \| null` — `null` rejects with 401 |
+| `services` | the services to expose — an array, or `(auth) => ServiceDef[]` |
+| `context` | `(auth) => {…}` — values merged into every tool handler's `ctx` |
+| `lifecycle` | `beforeHandle` / `afterHandle` — the tool-side auth gate (see below) |
+| `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
+| `onIncompatibleSchema` | `'throw'` (default) · `'skip'` · `'warn'` — see below |
+| `logger` | a `StitchLogger` for the `'warn'` policy |
+| `nativeTools` | register non-contract tools directly on the `McpServer` |
+| `instructions` | a short host-facing usage hint, surfaced to MCP tool-search |
+
+`services` and `context` receive the resolved identity, so a tenant can be
+shown only its own tools and every handler can read `ctx.tenantId`.
+
+### Guarding tools — `lifecycle`
+
+A tool call runs the same handler an HTTP request would. `lifecycle` makes it
+run the same gate: a `beforeHandle` (throw to reject) and an `afterHandle`
+(transform the result) — the tool-side twin of `createServer`'s hooks. Pass the
+**same** [`createAuthHook`](./auth-and-errors.md#createauthhook) result you give
+the HTTP server and tool calls are scope-checked by the identical rules:
+
+```ts
+createMcpHandler({ serverInfo, auth, services, lifecycle: { beforeHandle: authHook } })
+```
+
+Without it, a tool call bypasses the HTTP `beforeHandle` — the contract's
+`scope` is not enforced on the MCP / agent surface. `mountMcp`, `mountAgent` and
+`buildMcpServer` take `lifecycle` too.
+
+The observability `hooks` are symmetric with the HTTP side too: `beforeToolCall`
+and `afterToolCall` receive the resolved **`MethodDef`** as their last argument —
+the tool-side twin of `afterHandle(ctx, result, endpoint)`. Read
+`endpoint.serviceName` / `.key` / `.meta` directly for an audit row; you do not
+need to rebuild a `toolName → identity` map:
+
+```ts
+hooks: {
+  afterToolCall: (toolName, args, result, ms, ctx, endpoint) => {
+    audit({ service: endpoint.serviceName, action: endpoint.key, ok: result.ok, ms })
+  },
+}
+```
+
+> **Tool-path identity.** A tool call has no `req`, so `createAuthHook` resolves
+> identity through `resolveFromContext`, not `resolve`. Set it (read the
+> identity your `auth` / `context` injected) — without it a scoped tool call
+> has no identity and **fails closed**. See
+> [Auth on the tool surface](./auth-and-errors.md#auth-on-the-tool-surface--resolvefromcontext).
+
+### Incompatible schemas — `onIncompatibleSchema`
+
+A contract schema that JSON Schema cannot represent (a `z.date()`, a `z.map()`)
+cannot become a tool. `onIncompatibleSchema` decides what happens:
+
+- `'throw'` (default) — fail the build, listing every offending tool. A static
+  `services` array is checked when `createMcpHandler` is constructed, so a bad
+  schema fails the deploy, not the first request. Better than a tool that
+  silently vanishes from the surface.
+- `'warn'` — log through `logger` and drop the tool.
+- `'skip'` — drop the tool silently.
+
+`validateMcpSchemas(services)` runs the same check on its own — useful in a
+startup assertion or a test.
+
+## `mountMcp`
+
+If you already run an `McpServer` from the SDK, `mountMcp` adds contract tools
+to it instead of owning the lifecycle:
+
+```ts
+import { mountMcp } from 'stitchkit/tools'
+
+mountMcp(mcpServer, [usersService], { context: { source: 'mcp' } })
+```
+
+`createMcpHandler` is the batteries-included path; `mountMcp` is the building
+block under it.
+
+## MCP over stdio — `createStdioMcpServer`
+
+`createMcpHandler` serves MCP over HTTP. `createStdioMcpServer` serves the same
+contract tools over **stdio** — the server runs as a subprocess of the MCP
+client (Claude Desktop, Claude Code, Cursor, Codex), on the user's machine, so
+it can reach the local filesystem.
+
+```ts
+import { createStdioMcpServer } from 'stitchkit/tools'
+
+await createStdioMcpServer({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: resolveIdentity(),          // resolved once at startup, not per request
+  services: [usersService],
+})
+```
+
+A stdio server is a single process serving one client, so `auth` is a value (or
+a promise of one) resolved once at startup — typically from an env var — rather
+than a per-request `(req) => …`. Keep all logging on **stderr**: stdout is the
+JSON-RPC channel.
+
+Both transports build the server through the shared `buildMcpServer` — same
+contract pipeline, same `services` / `context` / `hooks` / `nativeTools` /
+`instructions`.
+
+## OAuth 2.1 — a native remote connector
+
+A remote MCP server is connectable from Claude (Desktop / web "custom
+connector") only through the MCP authorization spec: OAuth 2.1 with PKCE, plus
+the discovery documents (RFC 9728 / 8414), Dynamic Client Registration
+(RFC 7591) and resource indicators (RFC 8707). A Bearer-only server returns a
+bare `401` and the connector never establishes.
+
+stitchkit ships the OAuth **protocol mechanics**; the app supplies only
+**identity and storage**. Three pieces wire it together:
+
+```ts
+import { createMcpHandler, mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
+import { createServer } from 'stitchkit/server'
+
+const resource = 'https://api.example.com/mcp'
+const issuer = 'https://api.example.com'
+
+// 1. Resource server — the 401 now points at the metadata.
+const handleMcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: resolveOAuthToken,        // validate the Bearer JWT (verifyJwt + audience)
+  services,
+  protectedResource: { resource, authorizationServers: [issuer] },
+})
+
+// 2. Authorization server — DCR, /authorize (PKCE), /token.
+const oauthRoutes = mountOAuthProvider({
+  issuer,
+  resource,
+  signingSecret: env.OAUTH_SECRET,
+  clients, codes, refreshTokens,  // your stores (DB or in-memory)
+  authorizeUser,                  // your login + consent → { userId } | Response
+})
+
+createServer({
+  services,
+  rawRoutes: [
+    { method: 'ALL', path: '/mcp', handler: (req) => handleMcp(req) },
+    oauthProtectedResourceRoute({ resource, authorizationServers: [issuer] }),
+    ...oauthRoutes,
+  ],
+})
+```
+
+Access tokens are signed HS256 JWTs (`signJwt`) whose `aud` is the resource —
+validate them in `auth` with `verifyJwt(token, secret, { audience: resource })`.
+`authorizeUser` is where the app authenticates the user (reuse an existing
+session) and records consent; return `{ userId }` to issue a code, or a
+`Response` to redirect the browser to a login page first. The AS and resource
+server can co-locate or live on separate origins. See
+[ADR 0015](../decisions/0015-oauth-resource-server.md).
+
+## Proxying a remote API — `implementRemote`
+
+`implement` binds a contract to local handlers. `implementRemote` binds it to a
+remote HTTP API instead — every handler forwards the call to a deployed server
+through the contract's typed client:
+
+```ts
+import { createHttpClient } from 'stitchkit'
+import { createStdioMcpServer, implementRemote } from 'stitchkit/tools'
+
+const http = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  headers: () => ({ Authorization: `Bearer ${apiKey}` }),
+})
+
+await createStdioMcpServer({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: null,
+  services: contracts.map((c) => implementRemote(c, http)),
+})
+```
+
+This is how you ship a thin **local** MCP server for an API that already runs in
+the cloud: the local process owns only the transport and any filesystem-facing
+native tools, while every contract tool proxies to the remote API. One contract,
+no duplicated business logic.
+
+`implementRemote(contract, http, { transformArgs })` takes an optional
+`transformArgs` hook that rewrites a call's arguments before they are forwarded
+— e.g. to upload a local file referenced in the args and swap in its URL.
+
+## Structured output
+
+When a contract endpoint declares an object `output`, its MCP tool registers
+that as the tool `outputSchema` and the result carries `structuredContent`
+alongside the text block — the structured payload an MCP App UI consumes.
+
+## AI agents — `mountAgent`
+
+`mountAgent` turns a service into a Vercel AI SDK `ToolSet`, ready for
+`generateText` / `streamText`:
+
+```ts
+import { mountAgent } from 'stitchkit/tools'
+import { generateText } from 'ai'
+
+const tools = mountAgent(usersService, { context: { userId: 'agent-1' } })
+
+const result = await generateText({
+  model,
+  tools,
+  prompt: 'Create a user named Max',
+})
+```
+
+Each contract endpoint exposed on `AGENT` becomes a tool whose input schema is
+the merged `params` + `input`. `context` is merged into every tool handler's
+`ctx`, alongside `source: 'agent'`.
+
+### `AgentMountConfig`
+
+| Field | Purpose |
+|-------|---------|
+| `context` | values merged into every tool handler's `ctx` |
+| `lifecycle` | `beforeHandle` / `afterHandle` — the tool-side auth gate (see [Guarding tools](#guarding-tools--lifecycle)) |
+| `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
+| `extend` | add extra args resolved before the handler runs (see below) |
+
+`lifecycle` works the same as on the MCP server — without it an agent tool call
+bypasses the HTTP `beforeHandle` auth gate. Pass your `createAuthHook` result.
+
+### Adding tool-only args — `extend`
+
+`extend` adds **tool-only** arguments — fields the model fills that are resolved
+into context, then stripped before the contract handler sees them. Use it when a
+tool needs an argument the HTTP endpoint does not — the classic case being a
+**multi-tenant** server reached by one API key, where the model passes `tenantId`
+on every call. It is the same `ToolExtend` shape on `mountMcp`, `createMcpHandler`
+and `mountAgent`:
+
+```ts
+interface ToolExtend {
+  /** Extra Zod fields added to every matching tool's input schema. */
+  schema: Record<string, z.ZodType>
+  /** Turn the extra args into context merged into the handler's ctx. */
+  resolve: (args: Record<string, unknown>) => Partial<Ctx> | Promise<Partial<Ctx>>
+  /** Limit the extension to specific methods — default: every method. */
+  filter?: (service: ServiceDef, method: MethodDef) => boolean
+}
+```
+
+On the MCP server — add `tenantId` to each tool, validate access in `resolve`,
+inject the resolved tenant into `ctx`, and `filter` to the tenant-scoped tools:
+
+```ts
+createMcpHandler({
+  serverInfo, auth,
+  services: [widgetsService],
+  extend: {
+    schema: { tenantId: z.string().describe('Tenant to act on') },
+    resolve: async ({ tenantId }) => {
+      const id = String(tenantId)
+      if (!(await tenantExists(id))) throw new Error(`unknown tenant ${id}`)
+      return { tenantId: id }          // merged into ctx → ctx.tenantId
+    },
+    filter: (_service, method) => method.scope === 'tenant',
+  },
+})
+```
+
+The model calls `widgets_list({ tenantId: 't_123' })`; `resolve` checks access and
+puts `tenantId` on `ctx`; the contract handler reads `ctx.tenantId` (same place
+as the HTTP prefix param — see
+[Route groups → param prefixes](./server.md#param-prefixes-resource-scoped-paths)),
+so one handler serves both surfaces. Pair `extend` with `lifecycle` (your
+`createAuthHook`) so the tool call is still scope-gated.
+
+## Native multimodal tools
+
+Contract tools return JSON. For a tool that returns an image or other
+multimodal content, register a native tool. `mountViewFile` is the built-in one
+— it lets a model fetch and view a file (with SSRF and path-traversal
+defenses):
+
+```ts
+import { createMcpHandler, mountViewFile } from 'stitchkit/tools'
+
+const handleMcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth,
+  services: [service],
+  nativeTools: (server) => mountViewFile(server, { baseDir: '/srv/uploads' }),
+})
+```
+
+## One handler, three callers
+
+A contract handler runs the same for an HTTP request, an MCP tool call and an
+agent tool call. `ctx.source` (`'http'` · `'mcp'` · `'agent'`) tells it which —
+the rest of the context (`params`, `input`, anything `context` injects) is
+identical. Write the handler once; it serves every surface.
+
+
+==============================================================================
+# Guide: CLI  (docs/guide/cli.md)
+==============================================================================
+
+# CLI
+
+The same contract that drives the HTTP API, MCP tools and agent tools also
+drives a command-line program. `createCli` turns contract methods into commands
+— `myapp generate "a fox" --wait`, `myapp models list --json | jq …` — run
+through the very same validation, auth gate and error model as every other
+surface (HTTP ≡ MCP ≡ agent ≡ CLI, [ADR 0014](../decisions/0014-tool-http-parity.md)).
+
+It exists for what the other three surfaces cannot do: a generation kicked off
+with `Bash(run_in_background)` that notifies on exit, a `SKILL.md` that shells
+out in one line, a pipeable terminal command.
+
+## Exposure is opt-in
+
+Unlike MCP and agent — where an endpoint with no `expose` is a tool by default —
+**a method becomes a CLI command only when its `expose` lists `'CLI'`.** Adding
+the CLI never silently turns your existing API tools into shell commands.
+
+```ts
+{ method: 'POST', path: '/', desc: 'Generate media', toolName: 'generate',
+  expose: ['CLI', 'MCP', 'AGENT'], input: GenerateInput, output: Generation }   // CLI + MCP + agent
+{ method: 'GET', path: '/models', desc: 'List models', toolName: 'list_models',
+  expose: ['CLI'] }                                                             // CLI only
+{ method: 'GET', path: '/search', desc: 'Search' }                              // HTTP + MCP + AGENT — NOT CLI
+```
+
+A fresh contract shows **zero** CLI commands until methods opt in — that is the
+design, not a bug. The command name is the tool name — `toolName` if set, else a
+verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
+`get_widget`), not a literal `prefix_key`.
+
+## A minimal CLI
+
+stitchkit ships no binary — you write the executable and point your app's `bin`
+at it:
+
+```ts
+#!/usr/bin/env node
+// src/cli.ts
+import { createCli } from 'stitchkit/cli'
+import { catalogService, generateService } from './services'
+
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  services: [catalogService, generateService],
+  auth: process.env.MYAPP_TOKEN,            // resolved ONCE, like a stdio MCP server
+})
+```
+
+```json
+// package.json
+{ "bin": { "myapp": "./dist/cli.js" } }
+```
+
+`stitchkit/cli` pulls in neither the MCP SDK nor `ai`, so a CLI binary needs no
+MCP/agent peer dependencies.
+
+## Calling commands
+
+```
+<app> <command> [positional] [--flags]
+```
+
+Arguments are coerced to the contract schema's types — every argv token is a
+string, the schema says what it should be:
+
+| Zod field            | CLI                                            |
+| -------------------- | ---------------------------------------------- |
+| `z.string()`         | `--name "box"` or a positional                 |
+| `z.number()`         | `--count 3` → `3`                              |
+| `z.boolean()`        | `--active` (presence) / `--no-active`          |
+| `z.enum([...])`      | `--size large`                                 |
+| `z.array(z.string())`| `--tag a --tag b` → `["a","b"]`                |
+| `z.object({...})`    | `--opts '{"k":"v"}'` (JSON) or `--opts.k v`    |
+| `.optional()` / `.default()` | not required                           |
+
+Positional arguments fill non-boolean fields in declaration order, so
+`myapp generate "a fox"` is `--prompt "a fox"`. A piped value fills the first
+unset field: `echo "a fox" | myapp generate`.
+
+The advertised schema is never mutated — a CLI call validates against the exact
+same Zod schema an HTTP or MCP call does.
+
+## Global flags
+
+| Flag                  | Effect                                                     |
+| --------------------- | ---------------------------------------------------------- |
+| `--json`              | Raw JSON on stdout for piping / scripts                    |
+| `--wait`              | Block-poll an async result to a terminal state             |
+| `--wait-timeout <s>`  | Override the `--wait` timeout                              |
+| `--output-dir <dir>`  | Download result media into a directory                     |
+| `--quiet`             | Suppress non-essential stderr output                       |
+| `--dry-run`           | Print the resolved call without executing                  |
+| `--help`, `-h`        | Usage — top-level or per-command flag table                |
+
+stdout carries the result; errors and progress go to stderr, so `--json` stays
+pipeable and `2>/dev/null` stays clean. The process exit code carries the error
+class (`0` ok, `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`,
+`NOT_FOUND → 4`, …) — override per app with `exitCodes`.
+
+## `--wait` — background-friendly generation
+
+`--wait` polls an async result until it is done. It is generic — the core knows
+nothing about "generations": you say how to read the poll target, which command
+to re-call and when it is done.
+
+```ts
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  services,
+  wait: {
+    generate: {
+      tool: 'get_generation',
+      poll: (r) => (isRecord(r) && typeof r.id === 'string' ? { id: r.id } : null),
+      done: (r) => isRecord(r) && r.status === 'COMPLETED',
+    },
+  },
+})
+```
+
+```bash
+# foreground
+myapp generate "a fox" --wait --output-dir ./out
+
+# background — frees the agent; a notification fires on exit
+myapp generate "a fox" --wait --json > result.json &
+```
+
+## Auth parity
+
+A scoped command is guarded by the same `createAuthHook` your HTTP server uses —
+pass it as `lifecycle`, and inject the identity through `context` so
+`resolveFromContext` can read it:
+
+```ts
+const authHook = createAuthHook({ /* resolve, resolveFromContext, rules */ })
+
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  auth: await resolveIdentityFromToken(process.env.MYAPP_TOKEN),
+  context: (identity) => ({ user: identity }),   // resolveFromContext reads this
+  lifecycle: { beforeHandle: authHook },          // same gate as HTTP
+  services,
+})
+```
+
+Without `lifecycle`, a scoped command runs **unguarded** — the scope check lives
+entirely inside the `createAuthHook` result, so with no hook wired in there is
+nothing to enforce a method's `scope`. This matches the MCP / agent surfaces
+exactly ([ADR 0014](../decisions/0014-tool-http-parity.md)): on every tool
+transport the auth gate is opt-in, so a contract with scoped methods **must** be
+given a `lifecycle` (and `context` identity) to be protected. The gate only
+*fails closed* once the hook **is** present but `resolveFromContext` is missing —
+then a scoped call has no identity and is rejected.
+
+## Typed context
+
+Use `createToolkit<AppContext>()` to type the injected `context` against your
+app's context shape — the tool-side mirror of `createImplement`
+([ADR 0017](../decisions/0017-typed-tool-context.md)):
+
+```ts
+const tools = createToolkit<{ user: User }>()
+await tools.createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  services,
+  context: (identity) => ({ user: identity }),   // checked against { user: User }
+})
+```
+
+## Not in v1
+
+File-upload (`multipart`) endpoints are CLI-invisible, the same as on MCP /
+agent — a dedicated upload command (auto-uploading local paths) is future work.
+Streaming (SSE) output is not yet piped to stdout.
+
+
+==============================================================================
+# Guide: Realtime  (docs/guide/realtime.md)
+==============================================================================
+
+# Realtime
+
+stitchkit's realtime layer is [Socket.IO](https://socket.io) — `polling`
+fallback, heartbeats, acks, a mature client. stitchkit does not ship its own
+WebSocket engine; it ships thin, typed wrappers over Socket.IO and a bridge that
+syncs socket events into the TanStack Query cache. See
+[ADR 0008](../decisions/0008-thin-wrappers.md).
+
+## Typed events
+
+Declare the event maps once, in the shared module — both sides import them:
+
+```ts
+// shared/contracts.ts
+export interface ServerToClientEvents {
+  'note:created': (note: Note) => void
+  'note:deleted': (id: string) => void
+}
+export interface ClientToServerEvents {
+  'room:join': (room: string) => void
+}
+```
+
+Every `emit` and `on` on both the server and client wrapper is typed against
+these maps.
+
+## Server — `createSocketIOServer`
+
+```ts
+import { createServer, createSocketIOServer } from 'stitchkit/server'
+
+const socket = await createSocketIOServer<ServerToClientEvents, ClientToServerEvents>({
+  cors: { origin: 'https://app.example.com' },
+})
+
+socket.io.on('connection', (s) => {
+  s.on('room:join', (room) => s.join(room))   // rooms, handshake auth — your logic
+})
+```
+
+It returns a handle with three pieces, all wired into `createServer`:
+
+```ts
+createServer({
+  services,
+  websocket: socket.websocket,   // → Bun.serve websocket handlers
+  rawRoutes: [socket.route],     // ready-made /socket.io/* route
+})
+
+// elsewhere — broadcast:
+socket.io.emit('note:created', note)
+```
+
+| Handle field | Purpose |
+|--------------|---------|
+| `io` | the typed Socket.IO server — attach `connection` handlers, broadcast |
+| `websocket` | Bun WebSocket handlers — pass to `createServer({ websocket })` |
+| `route` | the `/socket.io/*` raw route — pass to `createServer({ rawRoutes })` |
+
+`SocketIOServerConfig` also takes `path`, `transports`, `pingTimeout` and
+`pingInterval`. For anything else socket.io's `ServerOptions` exposes, use the
+typed **`serverOptions`** passthrough — most often `maxHttpBufferSize` to lift the
+1 MB default for large emits:
+
+```ts
+await createSocketIOServer({
+  cors: { origin: 'https://app.example.com' },
+  serverOptions: { maxHttpBufferSize: 5 * 1024 * 1024 }, // 5 MB
+})
+```
+
+The wrapper-owned fields (`cors` / `path` / `transports` / `ping*`) take
+precedence over the same keys in `serverOptions`. On Bun the engine-level options
+(`maxHttpBufferSize`, the ping heartbeat, `upgradeTimeout`) are forwarded to
+`@socket.io/bun-engine` too — so a configured `maxHttpBufferSize` actually applies
+instead of silently truncating at 1 MB.
+
+## Client — `createSocketIOClient`
+
+```ts
+import { createSocketIOClient } from 'stitchkit'
+
+const socket = createSocketIOClient<ServerToClientEvents, ClientToServerEvents>({
+  url: 'https://api.example.com',
+})
+
+socket.connect()
+socket.on('note:created', (note) => { /* typed note */ })
+socket.emit('room:join', 'general')   // typed
+```
+
+### Durable subscriptions
+
+`socket.on(...)` returns an unsubscribe and is **durable** — the handler is
+re-attached to every socket the client builds, so it survives a reconnect. You
+subscribe once; reconnection is the wrapper's problem, not yours.
+
+`SocketIOClientConfig` takes `url`, `path`, `withCredentials` (cookies on the
+handshake — default `true`), `auth`, `query`, `extraHeaders`, `transports`,
+`reconnectionAttempts` and `reconnectionDelay`.
+
+### Handshake auth — cookie or token
+
+By default the handshake carries cookies (`withCredentials: true`) — the right
+fit for a browser app with a session cookie. A client that holds a token
+explicitly (desktop, mobile, CLI, server-to-server) authenticates the
+handshake with **`auth`** instead — the token reaches the server as
+`socket.handshake.auth`:
+
+```ts
+// client — a function is re-read on every (re)connect, so a rotated token is
+// picked up automatically; no need to recreate the client (or lose durable
+// subscriptions). It may be async.
+const socket = createSocketIOClient<ServerToClientEvents, ClientToServerEvents>({
+  url: 'https://api.example.com',
+  auth: () => ({ token: getAccessToken() }),
+})
+```
+
+```ts
+// server — the gate is your logic, on socket.handshake.auth
+import { verifyJwt } from 'stitchkit/server'
+
+socket.io.use(async (s, next) => {
+  const token = s.handshake.auth.token
+  if (typeof token !== 'string') return next(new Error('unauthorized'))
+  try {
+    s.data.user = await verifyJwt(token, secret)
+    next()
+  } catch {
+    next(new Error('unauthorized'))
+  }
+})
+```
+
+A static object (`auth: { token }`) works too, but only the function form
+re-reads on reconnect — prefer it for rotating tokens. `query` adds handshake
+URL params (`socket.handshake.query`); `extraHeaders` adds handshake headers,
+but in a browser those apply to the **polling** transport only (a WebSocket
+upgrade cannot set request headers) — for browser WebSocket auth use `auth`.
+If an auth producer throws or rejects, the wrapper sends an empty auth object so
+the server gate can reject it instead of leaving the handshake waiting forever.
+
+On a hard auth failure Socket.IO emits `connect_error` and keeps retrying
+(`reconnectionAttempts` defaults to `Infinity`) — set a finite value if a
+rejected token should stop hammering the server.
+
+## Cache bridge
+
+`createCacheBridge` syncs socket events into the TanStack Query cache — a server
+push updates the UI with no refetch. It is transport-agnostic: it takes any
+emitter with `on(event, handler) => unsubscribe`, which the
+`createSocketIOClient` result satisfies.
+
+```ts
+import { createCacheBridge } from 'stitchkit/react'
+
+const bridge = createCacheBridge({
+  socket,
+  queryClient,
+  handlers: {
+    'note:created': (note, ctx) => {
+      if (ctx.isFresh(['notes'])) return   // skip the echo of our own mutation
+      ctx.queryClient.invalidateQueries({ queryKey: ['notes'] })
+    },
+  },
+})
+bridge.connect()
+```
+
+### The echo problem
+
+When the client makes a mutation, it updates the cache itself — and the server
+also broadcasts the change back over the socket. Without care the UI updates
+twice. `markFresh` plus a short freshness window solves it: mark a key fresh
+right after a local mutation, and the bridge handler skips the echo.
+
+```ts
+// in the mutation:
+onSuccess: () => bridge.markFresh(['notes'])
+// in the handler:  if (ctx.isFresh(['notes'])) return
+```
+
+`createCacheBridge` is a convenience, not a requirement — any code can subscribe
+to the socket and call `queryClient` directly. The bridge just centralises the
+event-to-cache mapping and the echo guard.
+
+## Raw binary lane (Bun)
+
+Socket.IO carries binary fine — for most streams a binary event (`pcm(frame)`)
+is enough. But a *truly* high-throughput binary channel (video, large
+transfers) may want a raw WebSocket with no Socket.IO framing, on the **same**
+port. On Bun that is awkward: `Bun.serve` has a single `websocket` handler, and
+`createSocketIOServer().websocket` claims it.
+
+`composeWebSocketHandlers` composes that one handler from several lanes. A raw
+lane stamps its own marker onto `ws.data` at upgrade and is matched positively;
+Socket.IO is the catch-all (`socketIoLane`, placed last) — so the engine's
+opaque `ws.data` is never inspected, and the whole thing stays cast-free.
+
+```ts
+import {
+  composeWebSocketHandlers,
+  createServer,
+  createSocketIOServer,
+  socketIoLane,
+  webSocketLane,
+} from 'stitchkit/server'
+import type { RawRoute } from 'stitchkit/server'
+import type { ServerWebSocket, WebSocketHandler } from 'bun'
+
+const socket = await createSocketIOServer<ServerToClientEvents, ClientToServerEvents>({
+  cors: { origin: 'https://app.example.com' },
+})
+
+// 1. Discriminate the raw lane by a marker on ws.data (a type guard, cast-free
+//    — the `in` operator narrows, no `as`).
+interface PcmData { lane: 'pcm'; roomId: string }
+function isPcm(ws: ServerWebSocket<unknown>): ws is ServerWebSocket<PcmData> {
+  const data = ws.data
+  return typeof data === 'object' && data !== null && 'lane' in data && data.lane === 'pcm'
+}
+
+// 2. Raw handlers — ws.data is typed PcmData, no casts.
+const pcmHandlers: WebSocketHandler<PcmData> = {
+  message(ws, frame) { ws.publish(ws.data.roomId, frame) },
+}
+
+// 3. An upgrade route stamps the marker (your auth + data live here).
+const pcmRoute: RawRoute = {
+  method: 'GET',
+  path: '/ws/pcm',
+  handler: (req, ctx) => {
+    if (!ctx.server) throw new Error('needs a running Bun server')
+    const ok = ctx.server.upgrade(req, { data: { lane: 'pcm', roomId: '…' } })
+    return ok ? new Response(null) : new Response(null, { status: 400 })
+  },
+}
+
+// 4. Compose — raw lane first, Socket.IO last. The tuning is server-wide, so
+//    set maxPayloadLength to the most permissive lane (Socket.IO's default is
+//    1 MB, its maxHttpBufferSize).
+const websocket = composeWebSocketHandlers(
+  [webSocketLane({ match: isPcm, handlers: pcmHandlers }), socketIoLane(socket.websocket)],
+  { maxPayloadLength: 16 * 1024 * 1024 },
+)
+
+createServer({
+  services,
+  websocket,
+  rawRoutes: [socket.route, pcmRoute],
+})
+```
+
+Notes:
+
+- **Bun-only.** On Node, Socket.IO attaches to the `node:http.Server` `upgrade`
+  event (`serveNode({ socket })`); a raw lane there is a separate upgrade
+  handler, not this composition. See [ADR 0020](../decisions/0020-raw-websocket-lane.md).
+- The upgrade path must not collide with `/socket.io/*`.
+- The tuning (`maxPayloadLength`, `idleTimeout`, `backpressureLimit`, …) is
+  global — keep `idleTimeout` ≥ Socket.IO needs (> 2 × `pingInterval`).
+- For high throughput, handle backpressure in the raw lane: `ws.send()` returns
+  `-1` under pressure; resume on the `drain` callback.
+
+
+==============================================================================
+# Guide: Auth & errors  (docs/guide/auth-and-errors.md)
+==============================================================================
+
+# Auth & errors
+
+stitchkit carries no domain model — it does not know what a user is. What it
+provides is the *control flow*: a scope on every endpoint, one hook that
+enforces it, and one error model shared by every transport. The identity and
+the scope vocabulary are yours.
+
+## Scopes
+
+An endpoint declares a `scope` — a free string. The contract `meta.scope` is the
+default for endpoints that declare none.
+
+```ts
+export const posts = defineContract({ prefix: 'posts', scope: 'user' }, {
+  list:   { method: 'GET',    path: '/',    desc: 'List posts', scope: 'public', output: /* … */ },
+  create: { method: 'POST',   path: '/',    desc: 'Create',     /* inherits 'user' */ },
+  remove: { method: 'DELETE', path: '/:id', desc: 'Delete',     scope: 'admin' },
+})
+```
+
+The framework attaches no meaning to the strings — `'public'`, `'user'`,
+`'admin'` mean whatever your auth hook decides.
+
+## `createAuthHook`
+
+`createAuthHook` builds a `beforeHandle` hook that enforces `endpoint.scope`.
+Every request runs the same three steps — resolve the identity, read the scope,
+allow / 401 / 403 — so the flow lives in the framework and you supply only
+`resolve` and a `rules` map.
+
+```ts
+import { createAuthHook, createServer } from 'stitchkit/server'
+
+const authHook = createAuthHook<User>({
+  resolve: (ctx) => resolveSession(ctx),     // → a User, or null
+  rules: {
+    public: 'public',                        // always pass
+    user:   'authenticated',                 // any resolved identity passes
+    admin:  (user) => user.isAdmin,          // custom predicate
+  },
+  inject: (ctx, user) => { ctx.user = user },
+})
+
+createServer({ services, hooks: { beforeHandle: authHook } })
+```
+
+### `AuthRule`
+
+The value of each `rules` entry, keyed by scope:
+
+- **`'public'`** — always passes; the identity is attached if present.
+- **`'authenticated'`** — any resolved identity passes; no identity ⇒ 401.
+- **a function** `(identity, ctx) => boolean | Promise<boolean>` — a custom
+  check. It receives the full context, so a resource-scoped rule can read the
+  request's path params and do a DB lookup. May be async.
+
+#### Resource-scoped rule — reading a path/prefix param
+
+For a multi-tenant API (`pathPrefix: '/tenants/:tenantId'`, see
+[Route groups → param prefixes](./server.md#param-prefixes-resource-scoped-paths)),
+the rule gates access to the tenant in the path. A `:param` from the group prefix
+or the endpoint is on the **context root** as `ctx.<name>` (a raw `string`):
+
+```ts
+const authHook = createAuthHook<User>({
+  resolve: sessionResolver,
+  rules: {
+    public: 'public',
+    // gate the tenant in the path — ctx.tenantId comes from the group prefix
+    tenant: async (user, ctx) => userCanAccessTenant(user.id, String(ctx.tenantId)),
+  } satisfies Record<Scope, AuthRule<User>>,
+  // derive per-request facts onto ctx for handlers (role within this tenant, …)
+  inject: async (ctx, user) => {
+    ctx.user = user
+    if (user) ctx.tenantRole = await roleInTenant(user.id, String(ctx.tenantId))
+  },
+})
+```
+
+`inject` runs on every request (identity may be `null`) — use it to put the
+identity *and* any derived values (role, parent-id) on `ctx` for handlers. Read
+them back as `ctx.tenantRole` (typed `unknown` — narrow at the read site). The
+endpoints under the group declare `scope: 'tenant'`.
+
+### `AuthHookConfig`
+
+| Field | Purpose |
+|-------|---------|
+| `resolve` | `(ctx) => identity \| null` — HTTP identity from `ctx.req` (cookie / bearer + lookup) |
+| `resolveFromContext` | `(ctx) => identity \| null` — identity on a tool call (no `req`) |
+| `rules` | access rule per scope; `endpoint.scope` is the key |
+| `defaultScope` | scope applied when an endpoint declares none |
+| `inject` | write the resolved identity onto `ctx` for handlers |
+| `onAnonymous` | thrown when a scope needs an identity and there is none (default 401) |
+| `onForbidden` | thrown when an identity is present but the rule rejects it (default 403) |
+
+Annotate `rules` with `satisfies Record<MyScope, AuthRule<User>>` so the compiler
+catches a scope you forgot to cover.
+
+### Auth on the tool surface — `resolveFromContext`
+
+The hook runs in `beforeHandle`, so it guards **every transport** — HTTP, MCP
+and agent calls all pass through it. But identity is resolved differently per
+surface:
+
+- **HTTP** — `resolve(ctx)` reads `ctx.req` (a cookie or bearer token).
+- **Tool calls (MCP / agent)** — there is no `req`. The transport authenticated
+  the caller (an MCP API key) and `buildMcpServer`'s `context` injected the
+  identity into `ctx`. `resolveFromContext(ctx)` locates it.
+
+```ts
+const authHook = createAuthHook<User>({
+  resolve: (ctx) => resolveSession(ctx),          // HTTP — from ctx.req
+  resolveFromContext: (ctx) => ctx.user ?? null,  // tool — from injected ctx
+  rules: { public: 'public', user: 'authenticated', admin: (u) => u.isAdmin },
+})
+```
+
+The **scope check is identical** on both surfaces — only identity resolution
+differs. If you omit `resolveFromContext`, a scoped tool call has no identity
+and **fails closed** (rejected by `onAnonymous`) — the hook never silently
+passes a tool call it cannot authenticate. → [ADR 0014](../decisions/0014-tool-http-parity.md)
+
+## `createBearerResolver`
+
+For API-key or bearer-token auth (the usual MCP case), `createBearerResolver`
+strips `Authorization: Bearer <token>` and hands the raw token to your lookup:
+
+```ts
+import { createBearerResolver } from 'stitchkit/server'
+
+const resolve = createBearerResolver<User>({
+  lookup: (token, req) => db.apiKeys.resolve(token),   // → User, or null
+})
+```
+
+Use it as `createMcpHandler`'s `auth`, or inside `createAuthHook`'s `resolve`.
+
+## JWT
+
+`verifyJwt(token, secret)` verifies an HS256 JWT and returns its payload, or
+throws `unauthorized`. It pins the algorithm (the token's own `alg` can never
+pick the scheme), and checks `exp` and `nbf`.
+
+```ts
+import { verifyJwt, extractToken } from 'stitchkit/server'
+
+const token = extractToken(req)           // from Authorization, or a cookie name
+const payload = await verifyJwt(token, process.env.JWT_SECRET!)
+```
+
+`extractToken(req, cookieName?)` reads a bearer token from the `Authorization`
+header, or from the named cookie.
+
+## Cookies
+
+```ts
+import { defineCookie } from 'stitchkit/server'
+
+const session = defineCookie({ name: 'sid', httpOnly: true, secure: true, sameSite: 'Lax', path: '/' })
+
+session.get(req)        // string | undefined
+session.set('abc123')   // → a Set-Cookie header value
+session.clear()         // → a Set-Cookie value that expires it
+```
+
+`defineCookie` bundles a cookie's name and options into a typed handle, so the
+config is not repeated at every call site. `parseCookies(header)` and
+`serializeCookie(name, value, opts)` are the lower-level primitives.
+
+## The error model
+
+One error type, `AppError`, is shared by the contract, the server and the
+client. It carries a stable `code`, an HTTP `status`, and optional structured
+`details` and a `hint`.
+
+### Throwing errors
+
+Throw `AppError` directly, or use a typed helper — the idiomatic path:
+
+| Helper | Status | Code |
+|--------|--------|------|
+| `notFound(message?)` | 404 | `NOT_FOUND` |
+| `badRequest(message, details?)` | 400 | `BAD_REQUEST` |
+| `unauthorized(message?)` | 401 | `UNAUTHORIZED` |
+| `forbidden(message?)` | 403 | `FORBIDDEN` |
+| `conflict(message?, details?)` | 409 | `CONFLICT` |
+| `rateLimited(message?)` | 429 | `RATE_LIMITED` |
+| `appError(code, message?, details?)` | mapped, else 500 | any `code` |
+
+```ts
+import { notFound, badRequest } from 'stitchkit/server'
+
+const note = db.get(ctx.params.id)
+if (!note) notFound('Note not found')
+if (ctx.input.title.length > 200) badRequest('Title too long', { max: 200 })
+```
+
+Each helper has a `never` return type — TypeScript knows execution stops, so the
+code after it is correctly narrowed.
+
+### The error envelope
+
+`AppError.toJSON()` renders the public envelope every transport returns:
+
+```json
+{ "error": { "code": "NOT_FOUND", "message": "Note not found" } }
+```
+
+`details` and `hint` are included when present. On HTTP this is the response
+body with the matching status; for an MCP or agent call the same `code` and
+`details` come back as a tool error. A schema-validation failure on the request
+is turned into a `400 VALIDATION_ERROR` automatically.
+
+### On the client
+
+The client parses that envelope back into an `ApiError` with the same `code`,
+`status`, `details` and `hint` — see [Typed client → ApiError](./client.md#apierror).
+The error round-trips: one model, server to client.
+
+### Stitch codes vs your codes
+
+A `code` is a free string — your app codes (`BOT_NOT_FOUND`, …) are yours and the
+core never models them (ADR 0002). But stitchkit itself emits a fixed set:
+`BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`,
+`CONFLICT`, `RATE_LIMITED`, `VALIDATION_ERROR`, `INTERNAL_SERVER_ERROR`. They are
+published as **`STITCH_ERROR_STATUS`** (the `code → status` map) and
+**`StitchErrorCode`** (its `keyof`), with **`isStitchErrorCode()`** (→ ADR 0026).
+
+If you translate stitch's framework errors into your own wire codes in an
+`onError` hook, key the map by `StitchErrorCode` so it stays exhaustive — a code
+stitch adds or renames becomes a compile error, not a silent `500`:
+
+```ts
+const STITCH_TO_APP: Record<StitchErrorCode, AppCode> = {
+  NOT_FOUND: 'NOT_FOUND', METHOD_NOT_ALLOWED: 'METHOD_NOT_ALLOWED',
+  BAD_REQUEST: 'VALIDATION_ERROR', VALIDATION_ERROR: 'VALIDATION_ERROR',
+  UNAUTHORIZED: 'UNAUTHORIZED', FORBIDDEN: 'FORBIDDEN', CONFLICT: 'CONFLICT',
+  RATE_LIMITED: 'RATE_LIMITED', INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR',
+}
+onError: (ctx, err) => {
+  if (AppError.is(err) && isStitchErrorCode(err.code)) {
+    return jsonError(STITCH_TO_APP[err.code], err.status)   // keep stitch's status
+  }
+  // … your own AppError / normalizeError path
+}
+```
+
+
+==============================================================================
+# Guide: Observability  (docs/guide/observability.md)
+==============================================================================
+
+# Observability
+
+A request reaches your app through one of two surfaces — an HTTP route or a
+tool call (MCP / agent). Observability is the same question on both: *what
+happened, how long did it take, who made it, did it fail.*
+
+stitchkit answers this at two levels.
+
+- **The raw hooks** — `LifecycleHooks` and `ToolCallHooks`. Every request and
+  every tool call passes through a point you can observe. The lowest level;
+  always available. [Jump ↓](#the-raw-hooks)
+- **`stitchkit/observability`** — the audit layer built on those hooks: W3C
+  trace context, an `AsyncLocalStorage` request context, payload sanitisation,
+  and `createAuditHook` to wire it all into one sink. Your logging becomes a
+  table plus a `write` function. [Start here ↓](#the-observability-module)
+
+stitchkit still ships no logger and no audit store — those are the app's choice.
+What it ships is the machinery that turns a completed call into a clean,
+normalised record.
+
+## The observability module
+
+`stitchkit/observability` is server-only. It has three parts — a trace context,
+a request context, and the audit hook — and you usually touch only the last.
+
+### createAuditHook
+
+`createAuditHook` is the whole module in one call. You give it a `write` sink;
+it gives you back a wrapper for each surface. Every completed call — HTTP
+request, MCP tool call, agent tool call — is normalised into one `RequestEvent`
+and handed to `write`.
+
+```ts
+import { createAuditHook } from 'stitchkit/observability'
+
+export const audit = createAuditHook({
+  // The only thing the app supplies — persist one row.
+  write: (event) => {
+    db.auditLog.create({ data: {
+      traceId:    event.traceId,
+      source:     event.source,      // 'http' | 'mcp' | 'agent'
+      method:     event.method,      // verb, or 'TOOL'
+      path:       event.path,
+      ok:         event.ok,
+      statusCode: event.statusCode,
+      durationMs: event.durationMs,
+      userId:     event.userId,
+      payload:    event.payload,     // already sanitised
+    }})
+  },
+  // Optional — keep only the events you care about.
+  filter: (event) => event.source !== 'http' || event.method !== 'GET',
+})
+```
+
+It returns an [`AuditHook`](#audithook) — `{ http, toolCall }`:
+
+```ts
+// HTTP — wrap the fetch handler, inside wrapInRequestContext.
+Bun.serve({ fetch: wrapInRequestContext(audit.http(handler)) })
+
+// MCP & agents — pass as the tool-call hooks.
+createMcpHandler({ /* … */ hooks: audit.toolCall })
+mountAgent(service, { hooks: audit.toolCall })
+```
+
+One `createAuditHook`, one sink, every surface. The sink runs
+fire-and-forget and its errors are swallowed — a slow or failing audit write
+can never block or break the request it observes.
+
+### RequestEvent
+
+Every surface produces the same shape — so a single audit table stays
+queryable across all three:
+
+| Field | Notes |
+|-------|-------|
+| `source` | `http` \| `mcp` \| `agent` |
+| `method` / `path` | the verb + path, or `TOOL` + `/{source}/{tool}` |
+| `toolName` | tool calls only |
+| `traceId` / `spanId` / `parentSpanId` | [W3C trace context](#trace-context) |
+| `ok` / `statusCode` | outcome — real HTTP status, or `200`/`400` for a tool |
+| `durationMs` / `startedAt` | timing |
+| `errorCode` / `errorMessage` | failures only |
+| `payload` | the request body / tool arguments — sanitised |
+| `resultSize` / `responseBytes` | result item count + serialised size |
+| `userId` / `ipAddress` / `userAgent` | identity |
+
+### Request context
+
+`createAuditHook`'s `http` wrapper reads a request context — trace ids, timing,
+identity — from `AsyncLocalStorage`. `wrapInRequestContext` establishes it, and
+must be the **outermost** wrapper of your fetch handler:
+
+```ts
+import { getTraceId, wrapInRequestContext } from 'stitchkit/observability'
+
+Bun.serve({
+  fetch: wrapInRequestContext(audit.http(handler)),
+})
+```
+
+Two fields are filled in late — the resolved user, and the error outcome. Set
+them from the hooks that know:
+
+```ts
+import { setRequestError, setRequestUser } from 'stitchkit/observability'
+
+createAuthHook({ /* … */ inject: (ctx, user) => user && setRequestUser(user.id) })
+// in your onError hook:
+setRequestError({ code: err.code, message: err.message })
+```
+
+Make the framework router share this trace id — so request logs and your
+application logs carry one id — by passing `getTraceId` as the resolver:
+
+```ts
+createHandler({ /* … */ traceId: getTraceId })
+```
+
+`getRequestContext()` / `getTraceId()` then return the active values from
+anywhere in the call — stamp `getTraceId()` onto every line your logger writes.
+
+### Trace context
+
+stitchkit speaks [W3C Trace Context](https://www.w3.org/TR/trace-context/). An
+inbound `traceparent` header is continued — its trace id is kept, its span
+becomes the parent — so a trace spans the front-end call, your HTTP handler and
+every tool call underneath it. With no inbound header a fresh root trace is
+minted. Each tool call opens a [`childSpan`](#trace-context) of the request it
+runs in.
+
+You rarely call the trace functions directly — `wrapInRequestContext` and
+`createAuditHook` use them for you. They are exported (`resolveTraceContext`,
+`parseTraceparent`, `formatTraceparent`, `childSpan`) for when you need to
+propagate a `traceparent` onward to another service.
+
+> **Span ids live in the request context, not on `ctx`.** The handler `ctx`
+> carries a single `traceId`; the full `{ traceId, spanId, parentSpanId }` is on
+> the observability request context. To stamp `spanId` / `parentSpanId` into an
+> audit row read `getRequestContext()?.trace`, not `ctx.spanId`:
+>
+> ```ts
+> const trace = getRequestContext()?.trace
+> audit({ traceId: trace?.traceId, spanId: trace?.spanId, parentSpanId: trace?.parentSpanId })
+> ```
+
+### Sanitisation
+
+A payload goes into an audit row only after `sanitizePayload`:
+
+- **secret-named keys are masked** — `password`, `token`, `apiKey`, `secret`,
+  `authorization`, `cookie`, … (value → `[redacted]`);
+- **binary blobs** (`Uint8Array`, `Blob`, `FormData`) collapse to metadata —
+  never the bytes;
+- the result is **capped** — anything over the byte limit becomes a preview.
+
+`createAuditHook` runs it on every event; tune it through `sanitize`:
+
+```ts
+createAuditHook({
+  write,
+  sanitize: { maxBytes: 8_000, sensitiveKeys: /password|token|pin/i },
+})
+```
+
+`redact`, `truncatePreview` and `measureSize` are exported on their own if you
+need to sanitise something outside the audit path.
+
+## The raw hooks
+
+`createAuditHook` is built on hooks you can also use directly — for a one-off
+metric, a custom log line, anything that is not a full audit row.
+
+| Surface | Hook | Fires |
+|---------|------|-------|
+| HTTP | `LifecycleHooks.afterHandle` / `onError` | after each HTTP request |
+| MCP & agent tools | `ToolCallHooks.afterToolCall` | after each tool call |
+
+`afterHandle(ctx, result, endpoint)` runs after a handler returns;
+`onError(ctx, error, endpoint)` when one throws. `afterToolCall(toolName, args,
+result, durationMs, context)` runs after every tool call — success and error
+alike — carrying the tool name, the arguments, the result, the duration and the
+call context.
+
+```ts
+createMcpHandler({
+  serverInfo, auth, services,
+  hooks: {
+    afterToolCall: (toolName, _args, result, durationMs, context) => {
+      metrics.timing(`tool.${toolName}`, durationMs, { ok: String(result.ok) })
+    },
+  },
+})
+```
+
+Log **after** completion — a record is of a *finished* call; you need the
+outcome and the duration, neither of which exists before the handler runs.
+
+### Keying a row on (service, action)
+
+For a per-endpoint audit row keyed by **service** and **action**, read the
+endpoint identity off the `MethodDef` the hook receives — `endpoint.serviceName`
+(the contract prefix) and `endpoint.key` (the endpoint key, e.g. `updatePartial`).
+They are stable and always present (→ ADR 0022); the action is not in the URL and
+`toolName` is absent on HTTP-only endpoints, so this is the only reliable pair.
+`afterHandle` also gives you the handler `result` — so it, not `createAuditHook`'s
+HTTP wrapper (which never sees the response body), is the home for a rich mutation
+audit that records output:
+
+```ts
+hooks: {
+  afterHandle: (ctx, result, endpoint) => {
+    void logMutation({
+      service: endpoint.serviceName,
+      action: endpoint.key,
+      input: ctx.input,
+      output: result,
+      userId: ctx.userId,
+      traceId: ctx.traceId,
+    })
+    return result   // don't transform
+  },
+}
+```
+
+> **Why the HTTP audit is a wrapper, not a lifecycle hook.** `LifecycleHooks`
+> has a single `onError` — an audit built on it would compete with the app's own
+> error handler. `createAuditHook`'s `http` wrapper sees the final `Response`
+> instead, success and error alike, and never contends for a hook. The raw
+> lifecycle hooks remain yours for everything else.
+
+Keep any sink **asynchronous and self-contained**: a slow or failing write must
+never block or break the request. Swallow the sink's own errors.
+
+
+==============================================================================
+# Guide: Testing & deployment  (docs/guide/testing-and-deployment.md)
+==============================================================================
+
+# Testing & deployment
+
+## Testing
+
+stitchkit's own test suite runs on `bun:test`. The contract makes most of an
+API testable without a live socket.
+
+### Test handlers in process
+
+`createHandler` is the router as a plain `(req) => Promise<Response>` function —
+no `Bun.serve`, no port. Drive it with a `Request`:
+
+```ts
+import { test, expect } from 'bun:test'
+import { createHandler } from 'stitchkit/server'
+import { implement } from 'stitchkit/server'
+import { notes } from '../shared/contracts'
+
+const handler = createHandler({
+  services: [implement(notes, {
+    list:   () => [],
+    create: (ctx) => ({ id: '1', text: ctx.input.text }),
+    get:    (ctx) => ({ id: ctx.params.id, text: 'x' }),
+  })],
+})
+
+test('create returns the note', async () => {
+  const res = await handler(new Request('http://test/notes', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ text: 'hi' }),
+  }))
+  expect(res.status).toBe(200)
+  expect(await res.json()).toEqual({ id: '1', text: 'hi' })
+})
+```
+
+This exercises the full pipeline — routing, schema parsing, hooks, the error
+envelope — with no network.
+
+### Test handlers directly
+
+A handler is a plain function of `ctx`. For pure handler logic, call it with a
+context object directly — no HTTP at all. The contract's types keep the test
+`ctx` honest.
+
+### Validation and errors
+
+A bad request body comes back as `400 VALIDATION_ERROR`; a thrown `AppError`
+comes back with its `code` and `status`. Assert on the envelope:
+
+```ts
+const res = await handler(new Request('http://test/notes/missing'))
+expect(res.status).toBe(404)
+expect(await res.json()).toEqual({ error: { code: 'NOT_FOUND', message: 'Note not found' } })
+```
+
+stitchkit's own suite — 143 tests in `packages/core/tests` — is the working
+reference for testing each piece.
+
+## Deployment
+
+### Build
+
+A stitchkit app is a Bun program — there is no framework build step. Bundle it
+however the project already does (`bun build`, or run the entry file directly).
+The `stitchkit` package itself ships pre-built; you consume `dist/`, not `src/`.
+
+### Runtime
+
+The recommended target is **Bun ≥ 1.2** — `createServer` is `Bun.serve`. **Node
+≥ 22** is also supported via `stitchkit/node` (see below).
+
+```ts
+createServer({
+  services,
+  port: Number(process.env.PORT ?? 3000),
+  hostname: '0.0.0.0',
+})
+```
+
+`createServer` returns the `Bun.serve` instance — keep the reference if you need
+`.stop()` for a graceful shutdown.
+
+### Deploy on Node
+
+The contract, `implement`, hooks, auth and the client are runtime-agnostic. Only
+the listener differs: replace `createServer` with **`serveNode`** (from
+`stitchkit/node`, built on `srvx`) — same `HandlerConfig`:
+
+```ts
+import { serveNode } from 'stitchkit/node'
+
+serveNode({
+  services,
+  port: Number(process.env.PORT ?? 3000),
+})
+```
+
+Notes for a Node host:
+
+- Add **`@types/bun`** as a dev dependency — it is an optional peer that types the
+  shared `stitchkit/server` surface (without it `tsc` reports a missing `Bun`
+  namespace).
+- **Socket.IO** attaches to the Node HTTP server via `serveNode({ socket })`, and
+  on Node the default transport is `['websocket']` — set the client to match
+  (`transports: ['websocket']`). See [realtime](./realtime.md).
+- **Bun-only helpers** do not run on Node: `serveFile` (uses `Bun.file`) and the
+  raw WebSocket lane. `staticRoute` is runtime-neutral (`node:fs`) and works on
+  both, but in production prefer a CDN / the static front-end below.
+
+### Production checklist
+
+- **CORS** — set `cors.origin` to your real front-end origin(s). Do not ship
+  `origin: '*'` with credentials.
+- **Logging** — `logging: true` for built-in request logs, or pass a
+  `StitchLogger` to route them into your logging stack.
+- **Trace ids** — override `traceId` to reuse an id your platform already
+  assigns, so request logs and application logs share one id.
+- **Rate limiting** — `createRateLimiter` in `onRequest` for a global limit;
+  per-route limits belong in `beforeHandle`.
+- **Auth** — a `createAuthHook` `beforeHandle` guards every transport at once;
+  do not re-check auth per handler.
+- **Errors** — handlers throw `AppError`; let the standard envelope render them.
+  Add an `onError` hook only to integrate an error tracker.
+- **Secrets** — read them from the environment; never commit them.
+
+### The static front-end
+
+stitchkit serves the API. A SPA front-end is built and hosted separately — a
+static host or CDN in production, its own dev server in development. The backend
+does not serve static files (`staticRoute` exists for the occasional asset, not
+a whole app). See [`packages/starter`](../../packages/starter) for the split.
+
+### MCP
+
+If the app exposes MCP tools, `createMcpHandler` is mounted as a raw route
+(`/mcp`). It needs the `@modelcontextprotocol/sdk` peer installed in production —
+it is optional only for apps that do not use MCP.
+
+
+==============================================================================
+# Guide: Multi-tenant  (docs/guide/multi-tenant.md)
+==============================================================================
+
+# Multi-tenant / resource-scoped paths
+
+A walkthrough of one mainstream scenario end-to-end: a SaaS API scoped by a path
+segment — `/tenants/:tenantId/widgets/...` — where the same `tenantId` gates
+access in auth and is injected into tool calls (one API key → many tenants).
+
+Every piece below already exists; this recipe wires them into one flow. Each step
+links to its reference section.
+
+## 1. The contract — tenant-agnostic
+
+Endpoints know nothing about the tenant; the path segment lives on the group, not
+the endpoint:
+
+```ts
+export const widgets = defineContract(
+  { prefix: 'widgets', scope: 'tenant' },
+  {
+    list: { method: 'GET', path: '/', desc: 'List widgets', output: WidgetList },
+    create: { method: 'POST', path: '/', desc: 'Create a widget', input: NewWidget, output: Widget },
+  },
+)
+```
+
+## 2. The server — a param prefix
+
+Mount the service under a group whose `pathPrefix` carries `:tenantId`. The
+matched value is on the context root as `ctx.tenantId`
+([details](./server.md#param-prefixes-resource-scoped-paths)):
+
+```ts
+createServer({
+  groups: [
+    { pathPrefix: '/tenants/:tenantId', services: [widgetsService], hooks: { beforeHandle: authHook } },
+  ],
+})
+// → /tenants/:tenantId/widgets
+```
+
+With more than one scope, let **`scopePrefixes`** map `scope → prefix` and mount
+the flat `services` list — no hand-partitioning, the mapping lives in one place
+([details](./server.md#scope-driven-mounting-scopeprefixes), → ADR 0024):
+
+```ts
+createServer({
+  services,                                  // mixed scopes, listed once
+  scopePrefixes: { tenant: 'tenants/:tenantId', project: 'projects/:projectId' },
+  hooks: { beforeHandle: authHook },
+})
+// `tenant`-scoped → /tenants/:tenantId/..., `project` → /projects/:projectId/..., the rest flat
+```
+
+Handlers read `ctx.tenantId` (a raw `string` — narrow it). To get it typed inside
+`ctx.params`, add `tenantId` to the endpoint's `params` schema (a `z.strictObject`
+that omits it will reject the request). When each scope guarantees different
+injected fields, call `createImplement<TenantCtx>()` / `createImplement<BaseCtx>()`
+**once per scope** and implement each contract with the matching factory — every
+handler is typed to its scope, with no superset context that lies about a
+`tenantId` a `public` handler never has.
+
+## 3. Auth — gate the tenant in the path
+
+The `tenant` scope rule reads the prefix param and checks access; `inject` puts
+the identity and derived facts on `ctx`
+([details](./auth-and-errors.md#resource-scoped-rule--reading-a-pathprefix-param)):
+
+```ts
+const authHook = createAuthHook<User>({
+  resolve: sessionResolver,
+  rules: {
+    public: 'public',
+    tenant: (user, ctx) => userCanAccessTenant(user.id, String(ctx.tenantId)),
+  } satisfies Record<Scope, AuthRule<User>>,
+  inject: (ctx, user) => { ctx.user = user },
+})
+```
+
+## 4. The client — a per-tenant `pathPrefix`
+
+`createClient`'s third argument prepends the tenant segment; `stripPrefixKeys`
+keeps `tenantId` out of the body/query
+([details](./client.md#contractclientconfig--per-tenant--resource-scoped-clients)):
+
+```ts
+const widgetsApi = createClient(widgets, http, {
+  pathPrefix: (args) => `tenants/${args.tenantId}/`,
+  stripPrefixKeys: ['tenantId'],
+})
+
+widgetsApi.list({ tenantId: 't_123' })   // GET /tenants/t_123/widgets
+```
+
+`stripPrefixKeys` (a `const` tuple) also makes the consumed keys **typed,
+required args** on every method — `tenantId` above is type-checked, not a runtime
+surprise — so no hand-written scoped-client wrapper is needed (→ ADR 0025).
+
+## 5. The AI surface — `extend` injects the tenant
+
+One API key serves every tenant: the model passes `tenantId` per call, `resolve`
+validates it and puts it on `ctx` — so the *same* handler that reads `ctx.tenantId`
+over HTTP serves the tool call
+([details](./mcp-and-agents.md#adding-tool-only-args--extend)):
+
+```ts
+createMcpHandler({
+  serverInfo, auth,
+  services: [widgetsService],
+  lifecycle: { beforeHandle: authHook },
+  extend: {
+    schema: { tenantId: z.string().describe('Tenant to act on') },
+    resolve: async ({ tenantId }) => ({ tenantId: String(tenantId) }),
+    filter: (_s, m) => m.scope === 'tenant',
+  },
+})
+```
+
+## The through-line
+
+`ctx.tenantId` is the single join point: the **prefix param** puts it there on
+HTTP, `extend`'s **resolve** puts it there on a tool call. Handlers and the auth
+rule read it the same way on both surfaces — one contract, every surface, no
+per-transport tenant plumbing.
+
+
+==============================================================================
+# Guide: Upgrading  (docs/guide/upgrading.md)
+==============================================================================
+
+# Upgrading stitchkit
+
+How to move a consuming project from one stitchkit version to another — including
+across many versions at once (a project frozen on an old version, then jumped
+forward). The process is mechanical: stitchkit marks every breaking change in one
+place and one format, so you can recover the full migration from the version diff.
+
+## The one rule that makes this work
+
+A release that breaks a public API leads its `CHANGELOG.md` entry with a
+**`### ⚠️ Breaking changes`** section (exact heading), each item carrying a
+**before → after** snippet. A version with **no** such section is **purely
+additive** — adopting it changes nothing in your code. (See
+[`AGENTS.md` → Breaking changes](../../AGENTS.md).)
+
+So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
+current one *up to* your target, and apply each snippet.
+
+## Flow (agent or human)
+
+1. **Find the current version.** In the consumer: the resolved `stitchkit` in
+   `bun.lock` (authoritative), or `node_modules/stitchkit/package.json`. The range
+   in `package.json` (`^0.6.0`) is intent, not the installed truth.
+   > A `file:` link (`"stitchkit": "file:…"`) means the consumer tracks a **local
+   > checkout**, not a published version — its effective version is whatever that
+   > checkout's `package.json` says, and a plain `install` will not relink it after
+   > the local version moves (`bun install --force` does). Prefer a real
+   > `^x.y.z` range for reproducibility.
+
+2. **Pick the target.** Latest published (`bun pm view stitchkit version`) or a
+   specific `x.y.z`.
+
+3. **Read the breaking sections in range.** In stitchkit's
+   [`CHANGELOG.md`](../../CHANGELOG.md), for every version `> current` and
+   `<= target`, read its `### ⚠️ Breaking changes`. Versions without that section
+   are additive — skip them. (Fast scan: `grep -n "Breaking changes" CHANGELOG.md`.)
+
+4. **Apply each migration** — the before → after snippet tells you exactly what to
+   change at each call site. There are no deprecation shims to lean on; the old
+   shape is gone, so every site must move.
+
+5. **Bump and install.** `bun add stitchkit@<target>` (or update the range), then
+   `bun install`. Note the caret: `^0.7.0` is `< 0.8.0`, so crossing a breaking
+   minor is always an explicit version bump, never automatic.
+
+6. **Verify.** `bun run check` (or per-package typecheck) — TypeScript catches the
+   removed/renamed/retyped surfaces. Then a **runtime smoke** (typecheck ≠
+   runtime): bootstrap the server, one HTTP request, and any feature you rely on
+   (Socket.IO connect, an MCP tool call, a multipart upload, …).
+
+## Worked example — frozen on 0.3, jumping to 0.7
+
+1. `bun.lock` → consumer resolves `stitchkit@0.3.x`.
+2. Target: `0.7.0`.
+3. Scan CHANGELOG `### ⚠️ Breaking changes` for 0.4.0 … 0.7.0 → **none** (every
+   release was additive — new exports, an extra hook argument, opt-in fields).
+4. Nothing to migrate.
+5. `bun add stitchkit@^0.7.0`, `bun install`.
+6. `bun run check` green → runtime smoke → done. New surfaces
+   (`STITCH_ERROR_STATUS`, `serveFile`, `scopePrefixes`, `afterToolCall`'s
+   `MethodDef`, `maxUploadBytes`) are available to adopt, not required.
+
+## When you author a breaking change in stitchkit
+
+You are on the other side of this flow — see
+[`AGENTS.md` → Breaking changes & migration](../../AGENTS.md). In short: it is
+allowed; write the `### ⚠️ Breaking changes` block with a before → after snippet,
+bump the minor (pre-1.0), and migrate the controlled consumers in the same pass.
+
+
+==============================================================================
+# API reference  (docs/api/reference.md)
+==============================================================================
+
+# API reference
+
+Every public export of stitchkit, grouped by entrypoint. Each entry links to the
+guide page that explains it in context. Types are marked _type_; everything else
+is a value (a function, a class, a constant).
+
+The root `stitchkit` entrypoint is browser-safe; `stitchkit/server` and
+`stitchkit/tools` are server-only. See
+[Getting started → entrypoints](../guide/getting-started.md#entrypoints).
+
+---
+
+## `stitchkit`
+
+The browser-and-server entrypoint. Re-exports everything from
+[`stitchkit/contract`](#stitchkitcontract), plus the client and browser realtime.
+
+### Client
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
+| `createClients` | function | build one typed client per contract from a registry |
+| `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
+| `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
+| `createHttpClient` | function | the Ky-based HTTP transport — [guide](../guide/client.md#createhttpclient) |
+| `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` |
+| `HttpClient` | _type_ | the transport interface `createClient` builds on |
+| `HttpClientConfig` | _type_ | config for `createHttpClient` |
+| `RequestOptions` | _type_ | per-call options — params, timeout, response type |
+| `HeaderProvider` | _type_ | static or per-request headers |
+| `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
+| `ApiEventListener` | _type_ | an `ApiEvent` handler |
+
+### Realtime (client) & streaming
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createSocketIOClient` | function | the typed Socket.IO client — [guide](../guide/realtime.md#client--createsocketioclient) |
+| `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
+| `SocketIOClient` | _type_ | the client handle |
+| `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` |
+| `SocketEventMap` | _type_ | the shape of an event map |
+| `ParseSSEOptions` | _type_ | options for `parseSSE` |
+
+---
+
+## `stitchkit/contract`
+
+The contract layer alone — browser-and-server safe. All of this is also exported
+from the root `stitchkit`.
+
+### Contract
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
+| `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
+| `ContractDef` | _type_ | a defined contract |
+| `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` |
+| `EndpointDef` | _type_ | a single endpoint definition |
+| `HttpMethod` | _type_ | `GET \| POST \| PUT \| PATCH \| DELETE` |
+| `Transport` | _type_ | `HTTP \| MCP \| AGENT \| CLI` |
+| `TransportSource` | _type_ | `http \| mcp \| agent \| cli` — the value of `ctx.source` |
+| `RuntimeContext` | _type_ | the loose context seen by transport and hooks |
+| `HandlerContext` | _type_ | the typed context seen by a handler |
+| `EndpointFn` | _type_ | the call signature of one client method |
+| `TypedClient` | _type_ | the full typed client for a contract |
+| `TypedHttpClient` | _type_ | the typed client, HTTP endpoints only (`= ScopedHttpClient<C, unknown>`) |
+| `ScopedHttpClient` | _type_ | a client whose `stripPrefixKeys` become required args ([guide](../guide/multi-tenant.md)) |
+| `ScopedEndpointFn` | _type_ | one method's signature with the consumed keys folded in |
+
+### Errors
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `AppError` | class | the framework error — `code` / `status` / `details` / `hint` |
+| `ErrorEnvelope` | _type_ | the JSON shape of an error response |
+| `notFound` | function | throw `404 NOT_FOUND` — [guide](../guide/auth-and-errors.md#throwing-errors) |
+| `badRequest` | function | throw `400 BAD_REQUEST` |
+| `unauthorized` | function | throw `401 UNAUTHORIZED` |
+| `forbidden` | function | throw `403 FORBIDDEN` |
+| `conflict` | function | throw `409 CONFLICT` |
+| `rateLimited` | function | throw `429 RATE_LIMITED` |
+| `appError` | function | throw an `AppError` for any code |
+| `STITCH_ERROR_STATUS` | const | `code → HTTP status` map for stitchkit's own error codes — [guide](../guide/auth-and-errors.md#stitch-codes-vs-your-codes) |
+| `StitchErrorCode` | _type_ | a code stitchkit itself emits (`keyof STITCH_ERROR_STATUS`) |
+| `isStitchErrorCode` | function | type guard — is a code one of stitchkit's own? |
+
+### Pagination
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `paginatedSchema` | function | the `{ items, nextCursor }` Zod schema — [guide](../guide/contracts.md#pagination) |
+| `Paginated` | _type_ | the cursor-pagination envelope |
+| `encodeCursor` | function | encode a keyset value into an opaque `nextCursor` string (base64url, UTF-8-safe) |
+| `decodeCursor` | function | decode + Zod-validate a cursor back to its value (`null` if missing/invalid) |
+
+---
+
+## `stitchkit/server`
+
+Server-only. Builds and runs the HTTP server, and carries the server primitives.
+Also re-exports the error helpers from `stitchkit/contract`.
+
+### Server & handlers
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createServer` | function | build the router and start `Bun.serve` — [guide](../guide/server.md#createserver) |
+| `createHandler` | function | the router as a bare `(req) => Response` — [guide](../guide/server.md#createserver) |
+| `implement` | function | bind a contract to typed handlers — [guide](../guide/server.md#implement) |
+| `createImplement` | function | fix the handler context type once |
+| `staticRoute` | function | a raw route that serves a directory |
+| `serveFile` | function | serve a file with `Range` / `304` / `HEAD` — [guide](../guide/server.md#serving-files--range-requests) |
+| `parseByteRange` | function | parse a single `Range` header → range / `unsatisfiable` / `null` |
+| `weakETag` | function | a weak `ETag` from size + mtime |
+| `ServeFileOptions` | _type_ | options for `serveFile` |
+| `ByteRange` | _type_ | an inclusive `{ start, end }` byte range |
+| `respondJson` | function | a raw route's JSON response (`204` for null/undefined) |
+| `errorResponse` | function | any thrown value → the framework error envelope + `x-request-id` |
+| `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
+| `HandlerConfig` | _type_ | config for `createHandler` (runtime-agnostic) |
+| `BunServerConfig` | _type_ | config for `createServer` (Bun) |
+| `ServiceDef` | _type_ | the result of `implement` |
+| `MethodDef` | _type_ | one resolved endpoint inside a service |
+| `Handlers` | _type_ | the typed handler map `implement` expects |
+| `LifecycleHooks` | _type_ | `onRequest` / `beforeHandle` / `afterHandle` / `onError` |
+| `RouteGroup` | _type_ | a prefixed group of services with its own hooks |
+| `RawRoute` | _type_ | a non-contract `Request → Response` route |
+| `RawRouteContext` | _type_ | the routing context a raw handler receives |
+| `BunServer` | _type_ | the `Bun.serve` instance type |
+| `ServerPassthrough` | _type_ | extra `Bun.serve` options |
+| `StitchLogger` | _type_ | the custom-logger interface |
+
+### Auth
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createAuthHook` | function | a scope-enforcing `beforeHandle` hook — [guide](../guide/auth-and-errors.md#createauthhook) |
+| `createBearerResolver` | function | a bearer-token identity resolver |
+| `verifyJwt` | function | verify an HS256 JWT |
+| `extractToken` | function | read a bearer token from header or cookie |
+| `AuthHook` | _type_ | the hook `createAuthHook` returns |
+| `AuthHookConfig` | _type_ | config for `createAuthHook` |
+| `AuthRule` | _type_ | `'public' \| 'authenticated' \| predicate` |
+| `BearerResolverConfig` | _type_ | config for `createBearerResolver` |
+| `JwtPayload` | _type_ | a decoded JWT payload |
+
+### Cookies & CORS
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineCookie` | function | a typed cookie `get` / `set` / `clear` handle — [guide](../guide/auth-and-errors.md#cookies) |
+| `parseCookies` | function | parse a `Cookie` header to a record |
+| `serializeCookie` | function | build a `Set-Cookie` value |
+| `corsHeaders` | function | compute CORS response headers |
+| `corsPreflightResponse` | function | build a preflight `Response` |
+| `CookieDef` | _type_ | the `defineCookie` handle |
+| `CookieOptions` | _type_ | cookie attributes |
+| `CorsConfig` | _type_ | CORS policy |
+
+### Realtime (server)
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createSocketIOServer` | function | the typed Socket.IO server — [guide](../guide/realtime.md#server--createsocketioserver) |
+| `SocketIOServerConfig` | _type_ | config for `createSocketIOServer` |
+| `SocketIOServerHandle` | _type_ | the `{ io, websocket, route }` handle |
+| `composeWebSocketHandlers` | function | compose one Bun `websocket` from N lanes — a raw binary lane beside Socket.IO ([guide](../guide/realtime.md#raw-binary-lane-bun)) |
+| `webSocketLane` | function | a typed, cast-free lane for `composeWebSocketHandlers` |
+| `socketIoLane` | function | the Socket.IO catch-all lane for `composeWebSocketHandlers` |
+| `ComposedLane` | _type_ | a lane bridged to the loose data type |
+| `WebSocketLane` | _type_ | a typed lane (`{ match, handlers }`) |
+| `WebSocketComposeConfig` | _type_ | server-wide tuning for the composed handler |
+
+### Primitives
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `streamSSE` | function | an async generator → SSE `Response` — [guide](../guide/server.md#sse-streaming) |
+| `parseSSE` | function | parse an SSE `Response` (also on the root entrypoint) |
+| `parseMultipart` | function | parse a `multipart/form-data` request — [guide](../guide/server.md#multipart) |
+| `createRateLimiter` | function | token-bucket rate limiting — [guide](../guide/server.md#rate-limiting) |
+| `createCache` | function | an in-memory TTL cache |
+| `cacheHeaders` | function | build a `Cache-Control` header |
+| `createEventBus` | function | typed in-process pub/sub — [guide](../guide/server.md#event-bus) |
+| `generateTraceId` | function | a fresh trace id |
+| `resolveTraceId` | function | the default per-request trace-id resolver |
+| `extractIp` | function | the caller IP from a request |
+| `getClientInfo` | function | caller IP + user-agent |
+| `EventBus` | _type_ | the `createEventBus` handle |
+| `RateLimitConfig` | _type_ | config for `createRateLimiter` |
+| `ParseSSEOptions` | _type_ | options for `parseSSE` |
+
+### OpenAPI
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `generateOpenApiDocument` | function | an OpenAPI 3.1 document from contract services — [ADR 0018](../decisions/0018-openapi-generation.md) |
+| `openApiRoute` | function | a `RawRoute` that serves the document as JSON |
+| `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` |
+| `OpenApiDocument` | _type_ | the generated document |
+| `OpenApiInfo` | _type_ | the spec `info` block |
+| `OpenApiServer` | _type_ | a spec `servers` entry |
+
+---
+
+## `stitchkit/observability`
+
+Server-only. The audit layer one level above the raw hooks — W3C trace context,
+an `AsyncLocalStorage` request context, payload sanitisation and a normalised
+audit event. See the [Observability guide](../guide/observability.md).
+
+### Audit
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createAuditHook` | function | wire both surfaces into one sink — [guide](../guide/observability.md#createaudithook) |
+| `RequestEvent` | _type_ | the normalised audit event handed to the sink |
+| `AuditConfig` | _type_ | config for `createAuditHook` |
+| `AuditHook` | _type_ | the `{ http, toolCall }` the hook returns |
+
+### Request context
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `wrapInRequestContext` | function | run a fetch handler inside a request context — [guide](../guide/observability.md#request-context) |
+| `getRequestContext` | function | the active request context |
+| `getTraceId` | function | the active trace id — pass as `traceId` to `createServer` |
+| `getUserId` | function | the active user id, once auth has resolved it |
+| `setRequestUser` | function | attach the resolved user to the active context |
+| `setRequestError` | function | record the error outcome on the active context |
+| `runWithRequestContext` | function | run a function inside a given context |
+| `RequestContext` | _type_ | the per-request record |
+
+### Trace context
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `resolveTraceContext` | function | the trace for a request — `traceparent` continued or fresh |
+| `parseTraceparent` | function | parse a `traceparent` header |
+| `formatTraceparent` | function | render a `traceparent` header value |
+| `createTraceContext` | function | a fresh root trace |
+| `childSpan` | function | a child span of a parent trace |
+| `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId? }` |
+
+### Sanitisation
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `sanitizePayload` | function | redact secrets and cap size — [guide](../guide/observability.md#sanitisation) |
+| `redact` | function | mask secret-named keys, drop binary blobs |
+| `truncatePreview` | function | cap a value by serialised size |
+| `measureSize` | function | item count + byte size of a result |
+| `JsonValue` | _type_ | a JSON-serialisable value |
+| `SanitizeOptions` | _type_ | tuning for `redact` / `sanitizePayload` |
+| `SizeMeasure` | _type_ | the result of `measureSize` |
+
+---
+
+## `stitchkit/tools`
+
+Server-only. Turns contracts into MCP and AI-agent tools. Needs the
+`@modelcontextprotocol/sdk` peer (for MCP) and the `ai` peer (for agents).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createMcpHandler` | function | a complete Streamable-HTTP MCP server — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
+| `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
+| `buildMcpServer` | function | build an `McpServer` from contracts — the transport-neutral core |
+| `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
+| `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
+| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
+| `createCli` | function | a command-line program from contracts — [guide](../guide/cli.md) (also on `stitchkit/cli`) |
+| `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
+| `mountViewFile` | function | a native multimodal "view file" MCP tool |
+| `resolveMedia` | function | resolve a media reference for a tool result |
+| `validateMcpSchemas` | function | assert every tool schema is JSON Schema-compatible — [guide](../guide/mcp-and-agents.md#incompatible-schemas--onincompatibleschema) |
+| `McpHandlerConfig` | _type_ | config for `createMcpHandler` |
+| `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
+| `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
+| `ImplementRemoteOptions` | _type_ | options for `implementRemote` |
+| `McpMountConfig` | _type_ | config for `mountMcp` |
+| `AgentMountConfig` | _type_ | config for `mountAgent` |
+| `AgentContext` | _type_ | the context merged into agent tool handlers |
+| `CliConfig` | _type_ | config for `createCli` |
+| `CliWaitConfig` | _type_ | `--wait` polling config |
+| `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
+| `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
+| `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
+| `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
+| `ToolCallHooks` | _type_ | `beforeToolCall` / `afterToolCall` observability hooks |
+| `ToolResult` | _type_ | the result of one tool call |
+| `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
+| `McpMediaContent` | _type_ | a multimodal MCP content item |
+
+---
+
+## `stitchkit/cli`
+
+Server-only. Turns contracts into a command-line program — the fourth transport.
+Light by design: needs neither the MCP SDK nor the `ai` peer.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
+| `pollUntilDone` | function | the generic `--wait` poller (advanced) |
+| `emitResult` | function | write a `ToolResult` to stdout/stderr + exit code (advanced) |
+| `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
+| `CliConfig` | _type_ | config for `createCli` |
+| `CliRunOptions` | _type_ | parsed global flags (`--json`, `--wait`, …) |
+| `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
+| `CliWaitConfig` | _type_ | per-command `--wait` polling config |
+| `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
+| `PollParams` | _type_ | params for `pollUntilDone` |
+| `CliWriters` | _type_ | stdout/stderr sinks for `emitResult` |
+| `EmitOptions` | _type_ | options for `emitResult` |
+
+---
+
+## `stitchkit/react`
+
+Browser-only. The React data-layer helpers. Needs the `@tanstack/react-query`
+and `react-query-kit` peers.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createCursorQuery` | function | a cursor-paginated infinite query — [guide](../guide/client.md#cursor-pagination) |
+| `createCacheBridge` | function | sync socket events into the Query cache — [guide](../guide/realtime.md#cache-bridge) |
+| `CursorQueryConfig` | _type_ | config for `createCursorQuery` |
+| `CacheBridge` | _type_ | the `createCacheBridge` handle |
+| `CacheBridgeConfig` | _type_ | config for `createCacheBridge` |
+| `CacheBridgeContext` | _type_ | the `ctx` a bridge handler receives |
+| `CacheBridgeHandler` | _type_ | one event-to-cache handler |
+| `CacheBridgeHandlers` | _type_ | the handler map |
+| `CacheBridgeSocket` | _type_ | the minimal emitter a bridge accepts |
+
+---
+
+For the rationale behind these APIs — why `Bun.serve` and not a framework, why
+two context types, why thin wrappers — see the
+[Architecture Decisions](../decisions/).