stitchkit 0.41.0 → 0.43.0

package/llms-full.txt

@@ -44,7 +44,7 @@ keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
 | `stitchkit/node` | server (Node ≥ 22) | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
 | `stitchkit/cli` | server | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
-| `stitchkit/observability` | server | the audit layer — `createAuditHook`, trace context, sanitisation |
+| `stitchkit/observability` | server | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
@@ -168,7 +168,9 @@ actionable error naming the package and the install command — not a bare
 - [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).
+For a complete production-shaped app, run `bun create stitchkit my-app`. The
+canonical generated topology is maintained in
+[`packages/create-stitchkit/template`](../../packages/create-stitchkit/template).
 
 
 ==============================================================================
@@ -339,6 +341,19 @@ tools. Narrow it with `expose`:
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
 - omit `expose` — all transports.
 
+For a curated or security-sensitive tool surface, opt into explicit tool
+exposure at the scoped factory:
+
+```ts
+const { defineContract } = createContractFactory<AppScope>({
+  toolExposure: 'explicit',
+})
+```
+
+With this policy, omitting `expose` materializes `['HTTP']` on the returned
+endpoint. MCP, Agent and CLI then require an explicit endpoint array. The plain
+factory and `defineContract` keep the default-on behaviour above.
+
 Tool transports (`MCP`, `AGENT`) skip three kinds of endpoint automatically:
 `multipart` (a file upload is not a tool call) and
 [`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
@@ -542,9 +557,11 @@ export const { defineContract } = createContractFactory<'public' | 'user' | 'adm
 export const users = defineContract({ prefix: 'users', scope: 'user' }, { … })
 ```
 
-The vocabulary is yours; each returned `ContractDef` retains its concrete scope
-literal, so scope-aware registries select the exact config without another
-wrapper.
+The vocabulary is yours; each returned `ScopedContractDef` retains its concrete
+scope literal as a required `meta.scope` field, so scope-aware registries select
+the exact config without `NonNullable` or another wrapper. Plain `ContractDef`
+keeps optional scope because ordinary `defineContract` still supports its
+default-public overload.
 
 ## One source of truth
 
@@ -1664,6 +1681,11 @@ The server side is [`streamSSE`](./server.md#sse-streaming).
 
 # MCP & AI agents
 
+The application generated by `bun create stitchkit` includes a working
+stateless MCP endpoint and a separate `bun run tools` manifest command. Both
+are assembled from the same implemented project contracts as HTTP and CLI, so
+the generated project is the canonical end-to-end example for this chapter.
+
 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
@@ -1703,16 +1725,16 @@ call —
 ### Pinning tool names — `listToolNames`
 
 Derived tool names are part of your public surface — an MCP client config or an
-agent prompt refers to them by string. `listToolNames(services)` resolves every
-tool name your services expose (the exact resolver the mounts use), with its
-`(service, method)` identity and transports, sorted — a stable shape to
-snapshot:
+agent prompt refers to them by string. `listToolNames({ services, runtimeTools })`
+resolves the complete mixed surface (the exact resolver the mounts use), with
+its origin, `(service, method)` identity and transports, sorted — a stable shape
+to snapshot:
 
 ```ts
 import { listToolNames } from 'stitchkit/tools'
 
 test('tool names have not drifted', () => {
-  expect(listToolNames(services)).toMatchSnapshot()
+  expect(listToolNames({ services, runtimeTools })).toMatchSnapshot()
 })
 ```
 
@@ -1806,13 +1828,16 @@ createServer({
 | `serverInfo` | MCP server identity — `{ name, version }` |
 | `auth` | `(req) => identity \| null` — `null` rejects with 401 |
 | `services` | the services to expose — an array, or `(auth) => ServiceDef[]` |
+| `runtimeTools` | managed pathless operations — an array, or `(auth) => RuntimeToolDefinition[]` |
+| `surfaces` | finite `{ key: { services, runtimeTools } }` registry prepared eagerly |
+| `selectSurface` | `(auth) => declaredKey` — required with `surfaces` |
 | `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 |
 | `extend` | extra advertised arguments resolved into handler context |
 | `schemaValidation` | compatibility policy, typed-property guard and portable-format guard |
 | `logger` | a `StitchLogger` for the `'warn'` policy |
-| `nativeTools` | `({ registerTool, rawServer }, auth) => …` — protected native registration plus an explicit raw SDK escape hatch |
+| `rawTools` | `(server, auth) => …` — explicit SDK registration without framework guarantees |
 | `resources` | MCP Apps `ui://` resources mounted on every server |
 | `instructions` | a short host-facing usage hint, surfaced to MCP tool-search |
 | `coerceJsonArgs` | coerce JSON-stringified object/array arguments (default `true`) |
@@ -1822,14 +1847,37 @@ createServer({
 | `protectedResource` | RFC 9728 metadata used by HTTP `401` responses |
 | `sessionMode` | `'stateless'` (default) or explicit `'stateful'` session/SSE continuity |
 
-`services`, `context` and `nativeTools` all receive the resolved identity, so a
-tenant can be shown only its own tools and every handler can read `ctx.tenantId`.
+Direct `services` / `runtimeTools` factories, `context`, `selectSurface` and
+`rawTools` receive the resolved identity, so a tenant can be shown only its own
+tools and every handler can read `ctx.tenantId`.
+
+Use direct factories only when the definitions are genuinely arbitrary per
+identity. For a bounded role/plan set, declare a finite registry instead:
+
+```ts
+const handleMcp = createMcpHandler({
+  serverInfo,
+  auth,
+  surfaces: {
+    admin: { services: allServices, runtimeTools: [renderPreview] },
+    member: { services: memberServices, runtimeTools: [renderPreview] },
+  },
+  selectSurface: (identity) => identity.isAdmin ? 'admin' : 'member',
+  context: (identity) => ({ identity }),
+})
+```
+
+Every declared entry is schema-validated and prepared once when the handler is
+constructed. The selected immutable descriptors are shared; the SDK server,
+transport, auth-derived context, lifecycle runner and tool-call context are
+fresh for every stateless request (or every stateful session). Unknown keys
+fail before the server connects. The registry never retains auth values.
 
 ### Stateless by default; stateful only when required
 
 The default `sessionMode: 'stateless'` creates a fresh SDK server, transport,
-resolved auth/context and runner for each HTTP request. Static contract schemas
-are still prepared once when the handler is constructed. There is no session
+resolved auth/context and runner for each HTTP request. Static direct and finite
+registry schemas are still prepared once when the handler is constructed. There is no session
 map, event store, sweep timer or `Mcp-Session-Id`, so process replacement and
 load balancing cannot strand a client on an in-memory session.
 
@@ -1952,8 +2000,14 @@ as one thing. Where they agree, that is what you get; where they disagree — a
 `.refine()` only one of them carries, two different bounds on the same number, an
 enum against a free string — the *constraint* is dropped and the **type** is not.
 A field that is a number in every variant is advertised as a number, not as a
-bare description. Only genuinely different kinds (a string in one variant, a
-number in another) fall back to unconstrained. → ADR 0044
+bare description. When the kinds genuinely differ, the flat projection keeps
+every provable kind in a deterministic JSON Schema type array — for example
+`type: ['string', 'array']` — while dropping constraints that are not sound for
+all branches. Nested `oneOf` / `anyOf` values still contribute their provable
+base kinds without reintroducing union keywords. Only a branch whose kind is
+actually unknowable, such as a free-form schema or unresolved reference, leaves
+the collision unconstrained. → ADRs [0044](../decisions/0044-a-collided-field-keeps-its-type.md)
+and [0065](../decisions/0065-flat-collisions-preserve-every-known-kind.md)
 
 It is **deep** because the projection walks the generated JSON Schema document,
 including objects, arrays, tuples and schema-definition nodes. Structurally
@@ -1961,6 +2015,10 @@ identifiable discriminated object unions are flattened wherever they occur.
 Plain unions and unions hidden behind unresolved external references remain
 unions because Stitchkit cannot soundly invent a discriminator.
 
+Use the default `flattenUnionInput: false` when the model must see the exact
+relationship between a discriminator and each branch. The flat type array is a
+sound set of possible JSON kinds, not a reconstruction of those correlations.
+
 The flattened form is **lossy but never executable**. Per-variant refinements
 and incompatible constraints are widened in the presentation document; the
 original Zod contract enforces them exactly once inside `executeToolMethod`.
@@ -2006,8 +2064,8 @@ 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`.
+contract/runtime pipeline, same surface selection, context, hooks, raw escape
+hatch and instructions.
 
 ## OAuth 2.1 — a native remote connector
 
@@ -2249,9 +2307,9 @@ const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth,
   services: [service],
+  runtimeTools: [renderPreview],
   lifecycle: { beforeHandle: authHook },
   hooks: audit.toolCall,
-  nativeTools: ({ registerTool }) => registerTool(renderPreview),
 })
 
 const agentTools = mountAgent([service], {
@@ -2261,6 +2319,33 @@ const agentTools = mountAgent([service], {
 })
 ```
 
+When several runtime tools share application context and identity, bind both
+once with `createRuntimeToolFactory`. Its Zod context schema is parsed once per
+call inside the same runner; the authored handler receives validated context and
+parsed `input`, while lifecycle, hooks, output validation and presenters remain
+unchanged:
+
+```ts
+const knowledgeTools = createRuntimeToolFactory({
+  serviceName: 'agentKnowledge',
+  scope: 'user',
+  context: z.object({ userId: z.string(), tz: z.string() }),
+})
+
+const countRecords = knowledgeTools.define({
+  name: 'count_records',
+  action: 'countRecords',
+  method: 'GET',
+  description: 'Count records',
+  input: z.object({ kind: z.string() }),
+  output: z.object({ count: z.number() }),
+  handler: async ({ userId, tz, input }) => countFor(userId, tz, input.kind),
+})
+```
+
+`serviceName` and `scope` cannot be overridden by one definition. Use standalone
+`defineRuntimeTool` when tools do not share a context schema or identity.
+
 `transports` defaults to `['MCP', 'AGENT']`; set an explicit subset when an
 operation belongs on only one surface. The configured identity becomes the
 hook/lifecycle `OperationIdentity` and the tool `RequestEvent`
@@ -2281,7 +2366,7 @@ use the same validation, lifecycle and hook path as contract tools.
 
 ### Explicit raw SDK registration
 
-`rawServer` is deliberately named as an escape hatch. A tool registered there
+`rawTools` is deliberately named as an escape hatch. A tool registered there
 does **not** receive stitchkit schema policy, lifecycle, per-call context or
 hooks. The built-in `mountViewFile` helper remains raw for callers that choose
 that boundary; it fetches media with SSRF and path-traversal defenses:
@@ -2293,14 +2378,51 @@ const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth,
   services: [service],
-  nativeTools: ({ rawServer }) =>
-    mountViewFile(rawServer, { baseDir: '/srv/uploads' }),
+  rawTools: (server) => mountViewFile(server, { baseDir: '/srv/uploads' }),
 })
 ```
 
 Use raw registration only when opting out is intentional. For a protected
-`view_file`, define it through `registerTool` and call the exported
-`resolveMedia` core from its handler.
+`view_file`, define it with `defineRuntimeTool`, include it in `runtimeTools`,
+and call the exported `resolveMedia` core from its handler.
+
+## Introspecting the complete tool surface
+
+Deferred tool search, name snapshots and boot diagnostics accept the same
+object-shaped surface as the mounts. Contract operations are followed by
+runtime definitions, matching mount order; exposure filters and collisions are
+resolved by Stitchkit rather than by consumer code:
+
+```ts
+import {
+  buildToolManifest,
+  listToolNames,
+  summarizeTransports,
+} from 'stitchkit/tools'
+
+const surface = { services, runtimeTools: [renderPreview] }
+
+const manifest = buildToolManifest({
+  ...surface,
+  transport: 'AGENT',
+  flattenUnionInput: true,
+})
+
+const names = listToolNames(surface)
+const summary = summarizeTransports(surface)
+```
+
+`buildToolManifest` returns the exact immutable presentation schema shown to
+the selected MCP or Agent transport. It does not execute validation effects and
+fails first on duplicate contract/runtime names. There is no runtime-only
+manifest helper or public mount adapter: the framework owns merging and schema
+projection.
+
+`listToolNames` remains diagnostic and reports `kind: 'contract' | 'runtime'`
+for every identity. `summarizeTransports` returns `contractServices`,
+`runtimeTools`, aggregate `totals`, and a `sources` breakdown. Runtime tools
+contribute only to MCP/Agent according to their `transports`; they never inflate
+HTTP or CLI counts.
 
 ## Logging tool calls — `createToolLogger`
 
@@ -2320,9 +2442,9 @@ Pass `log` to redirect the line, or `onRecord` to feed a metrics sink the
 structured `ToolCallRecord`. That record carries `traceId` whenever an
 observability context is active, so a tool call made inside an HTTP request
 joins that request's log line on one key — see
-[Observability](./observability.md). For a boot-time picture of what is exposed where,
-`summarizeTransports(services)` returns per-transport operation counts (HTTP /
-MCP / AGENT / CLI) for you to log.
+[Observability](./observability.md). For a boot-time picture of what is exposed
+where, `summarizeTransports({ services, runtimeTools })` returns the mixed
+per-transport counts for you to log.
 
 ## One handler, three callers
 
@@ -3253,27 +3375,46 @@ onError: (ctx, err) => {
 
 ## Domain errors — `defineErrors`
 
-Declaring your app's error codes once gives you typed throwers on the server and
-a code table the client matches with autocomplete — instead of reading the raw
-`message` string (which breaks the moment a code expects a string but gets an
-object):
+Declare each domain code, HTTP status and optional structured-details schema in
+one immutable registry. The generated functions construct typed branded
+`AppError` instances; ordinary `throw` remains explicit at the call site:
 
 ```ts
-export const { errors, codes, isCode } = defineErrors({
-  SESSION_NOT_FOUND: 404,
-  QUOTA_EXCEEDED: 429,
+import { z } from 'zod'
+
+export const { errors, codes, definitions, isCode } = defineErrors({
+  SESSION_NOT_FOUND: { status: 404 },
+  QUOTA_EXCEEDED: {
+    status: 429,
+    details: z.object({ retryAfterSeconds: z.number().int().positive() }),
+  },
+})
+
+throw errors.SESSION_NOT_FOUND({ message: 'No such session' })
+throw errors.QUOTA_EXCEEDED({
+  message: 'Try later',
+  details: { retryAfterSeconds: 30 },
+  hint: 'Wait for the current window to expire',
 })
 
-// server — a typed thrower, the right HTTP status baked in
-throw errors.SESSION_NOT_FOUND('no such session')
+// Construction without throwing is useful for composition or inspection.
+const error = errors.QUOTA_EXCEEDED({ details: { retryAfterSeconds: 30 } })
+definitions.QUOTA_EXCEEDED.status // 429 — same source, no copied status map
 
 // client — match the code, never a magic string
 if (err instanceof ApiError && err.code === codes.SESSION_NOT_FOUND) { … }
 ```
 
-The `code` rides through unchanged in both the HTTP envelope and the MCP tool
-result, so one vocabulary covers every transport. The codes are yours; the core
-stays domain-free.
+With no `details` schema, the options object forbids `details`. A required
+`z.object` makes `details` required; `z.object(...).optional()` makes it
+optional. Supplied details are parsed when the error is constructed, before any
+transport sees them. `code` remains literal and the parsed details type is
+retained on the returned `AppError`.
+
+HTTP renders the complete code/status/message/details/hint. Tool transports keep
+their established model-facing projection (code/details/hint, without HTTP
+status), while `invokeOrThrow` recovers the exact normalized `AppError`. The
+codes and schemas remain application-owned; Stitchkit stays domain-free.
 
 ## `createErrorHook`
 
@@ -3305,6 +3446,27 @@ createServer({ services, hooks: { onError } })
 Codes you threw yourself (not stitchkit's) pass through `codeMap` unchanged; the
 `satisfies Record<StitchErrorCode, …>` keeps the map exhaustive across upgrades.
 
+Both `onError` and `render` may be asynchronous and receive the matched endpoint
+as their final argument. The observer is awaited before rendering, so it can
+resolve identity or enrich the request context even for failures raised before
+`beforeHandle`:
+
+```ts
+const onError = createErrorHook({
+  onError: async (_error, _info, ctx, endpoint) => {
+    await attributeFailedRequest(ctx, endpoint)
+  },
+  render: (info, ctx) => ({
+    error: { code: info.code },
+    actorId: ctx.actorId,
+  }),
+})
+```
+
+`endpoint` is `undefined` when the failure happened before route resolution.
+Synchronous callbacks and renderers that declare fewer parameters continue to
+work normally.
+
 Invalid input (a `ZodError`) is classified as `VALIDATION_ERROR` 400 before it
 reaches `render` — a client fault is an honest 400, not a 500 — and the
 offending fields arrive as structured `info.details.issues`, so your `render`
@@ -3340,10 +3502,10 @@ 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/observability`** — framework-owned HTTP completion plus canonical
+  tool hooks: W3C trace context, an `AsyncLocalStorage` request context, payload
+  sanitisation and `createObservability` with independent request/tool sinks.
+  [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,
@@ -3352,52 +3514,55 @@ 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
-    }})
+a request context, and event projections — and you usually touch only the last.
+
+### createObservability
+
+`createObservability` configures request and tool projections independently.
+Every completed call is normalised into one `RequestEvent`; HTTP completion is
+owned directly by `createHandler`, while MCP/Agent completion uses the canonical
+`ToolCallHooks` runner. There is no nested HTTP audit wrapper.
+
+```ts
+import { createObservability } from 'stitchkit/observability'
+
+const write = (event) => db.auditLog.create({ data: {
+  traceId: event.traceId,
+  source: event.source,
+  method: event.method,
+  path: event.path,
+  ok: event.ok,
+  statusCode: event.statusCode,
+  durationMs: event.durationMs,
+  userId: event.userId,
+  payload: event.payload,
+}})
+
+export const observability = createObservability({
+  request: {
+    write,
+    includePayload: false, // default: no Request.clone(), payload is null
+    filter: (event) => event.method !== 'GET',
+  },
+  tools: {
+    write,
+    filter: (event) => event.source === 'mcp' || event.source === 'agent',
   },
-  // Optional — keep only the events you care about.
-  filter: (event) => event.source !== 'http' || event.method !== 'GET',
 })
 ```
 
-It returns an [`AuditHook`](#audithook) — `{ http, toolCall }`:
+Wire each projection where its completion is owned:
 
 ```ts
-// HTTP — wrap the fetch handler, inside wrapInRequestContext.
-Bun.serve({ fetch: wrapInRequestContext(audit.http(handler)) })
+createServer({ services, observability: observability.request })
 
-// MCP & agents — pass as the tool-call hooks.
-createMcpHandler({ /* … */ hooks: audit.toolCall })
-mountAgent(service, { hooks: audit.toolCall })
+createMcpHandler({ /* … */ hooks: observability.toolCall })
+mountAgent(service, { hooks: observability.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.
+Each sink runs fire-and-forget and fails independently: a slow or broken request
+sink cannot block the response, suppress operational logging or break the tool
+sink.
 
 ### RequestEvent
 
@@ -3416,32 +3581,26 @@ queryable across all three:
 | `ok` / `statusCode` | outcome — real HTTP status, or `200`/`400` for a tool |
 | `durationMs` / `startedAt` | timing |
 | `errorCode` / `errorMessage` / `errorDetail` | failures only — `errorDetail` carries the structure the message flattens (e.g. Zod issues) |
-| `payload` | the request body / tool arguments — sanitised |
+| `payload` | sanitised tool arguments; HTTP is `null` unless request `includePayload` is enabled |
 | `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:
+When request observability is configured, `createHandler` establishes the
+`AsyncLocalStorage` request context itself and uses the same completion snapshot
+for operational logging and `RequestEvent`. No `wrapFetch` composition is
+needed:
 
 ```ts
-import { getTraceId, wrapInRequestContext } from 'stitchkit/observability'
-
-Bun.serve({
-  fetch: wrapInRequestContext(audit.http(handler)),
-})
+createServer({ services, logging, observability: observability.request })
 ```
 
-`createServer` and `serveNode` build their own `fetch`, so compose through
-**`wrapFetch`** instead — same order, the context outermost:
+`wrapInRequestContext` remains available for a custom fetch pipeline that does
+not use `createHandler`; it is no longer part of built-in HTTP audit wiring:
 
 ```ts
-createServer({
-  services,
-  wrapFetch: (fetch) => wrapInRequestContext(audit.http(fetch)),
-})
+Bun.serve({ fetch: wrapInRequestContext(customFetch) })
 ```
 
 Some fields are filled in late. Set them from the hooks that know:
@@ -3477,6 +3636,12 @@ context carries nothing yet, so your value always wins.
 `event.serviceName` / `event.action` are present on every event, including a
 pre-handler 400. Nothing to wire.
 
+When failure attribution itself is asynchronous, use `createErrorHook`'s
+`onError(error, info, ctx, endpoint)` observer. The framework awaits it before
+calling `render`, so identity or audit enrichment is visible to both the final
+error envelope and the request event. `endpoint` is the matched `MethodDef`, or
+`undefined` when routing failed before a method was selected.
+
 **Domain dimensions** — attach your own tenant / project / entity id with
 `setRequestDimensions`. It is an opaque `Record<string, string>` the core gives no
 meaning to (→ ADR 0021). Resolve it cheaply from `ctx.params` / headers in
@@ -3570,8 +3735,8 @@ 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`,
+You rarely call the trace functions directly — `createHandler` request
+observability and `wrapInRequestContext` use them for you. They are exported (`resolveTraceContext`,
 `parseTraceparent`, `formatTraceparent`, `childSpan`) for when you need to
 propagate a `traceparent` onward to another service.
 
@@ -3606,12 +3771,19 @@ A payload goes into an audit row only after `sanitizePayload`:
   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`:
+`createObservability` runs it on every emitted event; tune each sink separately:
 
 ```ts
-createAuditHook({
-  write,
-  sanitize: { maxBytes: 8_000, sensitiveKeys: /password|token|pin/i },
+createObservability({
+  request: {
+    write,
+    includePayload: true,
+    sanitize: { maxBytes: 8_000, sensitiveKeys: /password|token|pin/i },
+  },
+  tools: {
+    write,
+    sanitize: { maxBytes: 8_000, sensitiveKeys: /password|token|pin/i },
+  },
 })
 ```
 
@@ -3620,7 +3792,7 @@ 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
+Tool observability 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 |
@@ -3694,7 +3866,7 @@ observe. (This is also why it lives on `ToolCallHooks` rather than being an
 object must stay assignable to `ToolLifecycle`.)
 
 **Do not reach for `setRequestError` here.** It writes to the *request* context,
-which `createAuditHook`'s **tool** row does not read: a tool event takes
+which the built-in **tool** row does not read: a tool event takes
 `errorCode` / `errorMessage` / `errorDetail` from the `ToolResult`, and only
 identity and `dimensions` from the context. Calling it in `onToolError` would
 leave the tool row exactly as scrubbed as before. It is right for the **HTTP**
@@ -3720,7 +3892,7 @@ validation failure or a `beforeToolCall` rejection leaves it `undefined`, becaus
 neither ever had a raw value to lose. Consumers destructure only the fields they
 use; future optional fields do not change callback arity.
 
-`createAuditHook` uses it already. Where the envelope was scrubbed to
+`createObservability({ tools })` uses it already. Where the envelope was scrubbed to
 `INTERNAL_SERVER_ERROR`, the row's `errorMessage` becomes the real message
 instead of the placeholder; a truthful envelope (a thrown `AppError`, a
 `ZodError`) is left alone, `errorCode` and `errorDetail` are untouched, and the
@@ -3733,7 +3905,7 @@ sink of your own (a tracker, a stack, an alert), `afterToolCall` for the record.
 
 ### Keying a row on (service, action)
 
-`createAuditHook` already keys every event by **service** and **action**
+Built-in observability keys every event by **service** and **action**
 (`event.serviceName` / `event.action`, → ADR 0029) — reach for the raw hook only
 when you also need the handler **output**, which the audit wrapper never sees. For
 that, read the endpoint identity off the `OperationIdentity` the tool hook
@@ -3761,11 +3933,11 @@ hooks: {
 }
 ```
 
-> **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.
+> **Why HTTP observability is framework-owned, not a lifecycle hook.**
+> `LifecycleHooks` has a single `onError`; an audit built on it would compete
+> with the app's error renderer and miss raw/unmatched exits. `createHandler`
+> sees the final response on every path and emits one completion without
+> consuming an application hook.
 
 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.
@@ -3914,7 +4086,8 @@ Notes for a Node host:
 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.
+a whole app). `bun create stitchkit my-app` demonstrates the supported split:
+an independently built Next.js frontend and Bun/Stitchkit API.
 
 ### MCP
 
@@ -4051,6 +4224,76 @@ rule read it the same way on both surfaces — one contract, every surface, no
 per-transport tenant plumbing.
 
 
+==============================================================================
+# Guide: Frontend integrations  (docs/guide/frontend-integrations.md)
+==============================================================================
+
+---
+title: Frontend integrations
+description: Compose Stitchkit with Next.js, React Router or a separate Vite development server
+type: architecture
+status: active
+created: 2026-08-08
+updated: 2026-08-08
+---
+
+# Frontend integrations
+
+The official `bun create stitchkit` application uses Next.js with a separate
+Bun API. Stitchkit remains a Fetch-native backend and does not own frontend
+routing, SSR or HMR.
+
+## Theme boundary in the official starter
+
+The generated Next.js application uses `@wrksz/themes`, not a Stitchkit-owned
+theme abstraction. Its root `ThemeProvider` comes from `@wrksz/themes/next` and
+lives directly in the server layout so Next 16 can inject the first-paint script
+through `useServerInsertedHTML`. The default `hybrid` storage reads a cookie
+during SSR and mirrors changes to localStorage for cross-tab synchronization.
+
+Client components import typed hooks from the fine-grained
+`@wrksz/themes/client/*` entrypoints. Nested visual examples use
+`ClientThemeProvider` with a scoped target and `storage="none"`; they never
+become a second global provider. Applications may add account-backed theme
+preferences, CSP nonces or consent-aware storage, but those policies remain
+application concerns.
+
+Theme state and theme animation are intentionally separate. `@wrksz/themes`
+owns selection, resolution, SSR prepaint and persistence. The generated app's
+`theme/transition.ts` wraps an interactive `setTheme` call with the native View
+Transition API and exposes typed style, duration, easing and origin settings.
+The default 250 ms crossfade matches the starter's visual language; the
+catalogue also demonstrates a radial reveal. The runner bypasses animation when
+the browser lacks the API or `prefers-reduced-motion: reduce` is active.
+
+## React Router
+
+Mount a `createHandler()` result in a catch-all resource route and pass the
+incoming `Request` through unchanged. Mount MCP as a second resource route. An
+SSR request creates its own typed client using that request's origin and auth;
+do not share request identity in a module singleton.
+
+```ts
+export async function loader({ request }: LoaderFunctionArgs) {
+  return apiHandler(request);
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  return apiHandler(request);
+}
+```
+
+## Vite
+
+Run Vite and the Stitchkit API as separate development processes. Declare one
+proxy for `/api`, `/mcp` and `/socket.io`; browser code still calls the typed
+client with same-origin paths. Production serves the static Vite output from a
+static host or reverse proxy and routes those backend paths to Stitchkit.
+
+Do not duplicate DTOs or handwritten API wrappers in either integration. The
+shared contract remains the only transport schema source.
+
+
 ==============================================================================
 # Guide: Upgrading  (docs/guide/upgrading.md)
 ==============================================================================
@@ -4119,6 +4362,123 @@ current one *up to* your target, and apply each snippet.
 
 ## Unreleased breaking migrations
 
+HTTP observability now completes inside the framework handler instead of a
+nested fetch wrapper. Configure request and tool sinks explicitly:
+
+```ts
+// before
+const audit = createAuditHook({ write })
+createServer({
+  services,
+  wrapFetch: (handler) => wrapInRequestContext(audit.http(handler)),
+})
+mountAgent(services, { hooks: audit.toolCall })
+
+// after
+const observability = createObservability({
+  request: { write, includePayload: true },
+  tools: { write },
+})
+createServer({ services, observability: observability.request })
+mountAgent(services, { hooks: observability.toolCall })
+```
+
+Body capture changed from always-on for body methods to opt-in. Set
+`includePayload: true` only when the request sink needs the sanitized JSON body.
+There is no `createAuditHook` or `audit.http` compatibility path;
+`wrapInRequestContext` remains only for custom fetch pipelines.
+
+Tool introspection now accepts one object-shaped contract/runtime surface. Stop
+calling the internal contract collector or merging a locally converted runtime
+manifest:
+
+```ts
+// before
+buildToolManifest(services.flatMap((service) => collectTools(service, 'AGENT')))
+listToolNames(services)
+summarizeTransports(services)
+
+// after
+const surface = { services, runtimeTools }
+buildToolManifest({ ...surface, transport: 'AGENT' })
+listToolNames(surface)
+summarizeTransports(surface)
+```
+
+`ToolNameEntry` adds `kind: 'contract' | 'runtime'`. `TransportSummary` is now
+`{ contractServices, runtimeTools, totals, sources }`; replace `services` and
+`perService` reads with the explicit counts and mixed-source breakdown. There
+is no positional overload and no `buildRuntimeToolManifest`: Stitchkit owns the
+combined order, transport filtering, canonical presentation schema and
+cross-origin collision checks.
+
+`defineErrors` now uses one Zod-first definition object and returns constructors
+instead of positional throwers. Add explicit `throw`, move message/details/hint
+into one options object, and declare a details schema when that code carries
+structured context:
+
+```ts
+// before
+const { errors } = defineErrors({ QUOTA_EXCEEDED: 429 })
+errors.QUOTA_EXCEEDED('Try later', { retryAfterSeconds: 30 }, 'Wait')
+
+// after
+const { errors, definitions } = defineErrors({
+  QUOTA_EXCEEDED: {
+    status: 429,
+    details: z.object({ retryAfterSeconds: z.number().positive() }),
+  },
+})
+throw errors.QUOTA_EXCEEDED({
+  message: 'Try later',
+  details: { retryAfterSeconds: 30 },
+  hint: 'Wait',
+})
+```
+
+There is no positional overload. A code without `details` forbids them; use an
+optional object schema when the details object itself is optional. Read status
+and schemas from the frozen `definitions` registry instead of maintaining a
+parallel map.
+
+Managed MCP runtime tools are now declared as immutable data. Move protected
+registrar calls to `runtimeTools`; rename deliberate raw SDK registration to
+`rawTools`. There is no registrar alias:
+
+```ts
+// before — protected
+createMcpHandler({
+  services,
+  nativeTools: ({ registerTool }) => registerTool(preview),
+})
+
+// after — protected and prepared with the rest of the surface
+createMcpHandler({ services, runtimeTools: [preview] })
+
+// before — deliberate raw SDK opt-out
+nativeTools: ({ rawServer }, auth) => mountRaw(rawServer, auth)
+
+// after — still a deliberate raw SDK opt-out
+rawTools: (server, auth) => mountRaw(server, auth)
+```
+
+When identity selects from a bounded set, replace a repeatedly prepared
+`services(auth)` factory with a finite registry:
+
+```ts
+createMcpHandler({
+  surfaces: {
+    admin: { services: allServices, runtimeTools: [preview] },
+    member: { services: memberServices, runtimeTools: [preview] },
+  },
+  selectSurface: (auth) => auth.isAdmin ? 'admin' : 'member',
+})
+```
+
+Keep direct `services(auth)` / `runtimeTools(auth)` only for genuinely
+unbounded definitions; Stitchkit intentionally does not cache arbitrary auth
+values.
+
 Contract success bodies are now determined by the presence of `output`, not by
 the handler's runtime value. A nullable output returns JSON `null` with status
 `200`; `undefined` with a declared output and non-null data without an output
@@ -4222,7 +4582,7 @@ const preview = defineRuntimeTool({
     }),
   },
 })
-nativeTools: ({ registerTool }) => registerTool(preview)
+runtimeTools: [preview]
 ```
 
 The removed `NativeMcp*` types have no aliases. Use `RuntimeToolDefinition`,
@@ -4421,7 +4781,7 @@ name derivation, diff them mechanically:
 
 ```ts
 import { listToolNames } from 'stitchkit/tools'
-console.log(JSON.stringify(listToolNames(services), null, 2))
+console.log(JSON.stringify(listToolNames({ services, runtimeTools }), null, 2))
 ```
 
 `listToolNames` never throws on an illegal name — that is deliberate, so it can
@@ -4529,6 +4889,11 @@ from the root `stitchkit`.
 |--------|------|---------|
 | `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
 | `createContractFactory` | function | a `defineContract` with a required allowed scope that retains each concrete literal — [guide](../guide/contracts.md#scope) |
+| `ContractFactoryConfig` | _type_ | optional scoped-factory policy, including explicit tool exposure |
+| `ContractFactoryToolExposure` | _type_ | `'explicit'` — omitted endpoint exposure materializes as HTTP-only |
+| `ExplicitScopedDefineContract` | _type_ | scoped factory authoring with explicit tool opt-in |
+| `ExplicitToolExposureEndpoints` | _type_ | endpoint map after missing exposure is materialized as `['HTTP']` |
+| `ScopedContractDef` | _type_ | a factory-defined contract whose `meta.scope` is the required concrete literal |
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns |
 | `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
 | `ContractDef` | _type_ | a defined contract |
@@ -4570,9 +4935,17 @@ from the root `stitchkit`.
 | `conflict` | function | throw `409 CONFLICT` |
 | `rateLimited` | function | throw `429 RATE_LIMITED` |
 | `appError` | function | throw an `AppError` for any code |
-| `defineErrors` | function | declare domain error codes → typed throwers + a code table — [guide](../guide/auth-and-errors.md#domain-errors--defineerrors) |
-| `DefinedErrors` | _type_ | the `{ errors, codes, isCode }` handle `defineErrors` returns |
-| `ErrorThrower` | _type_ | one `defineErrors` thrower — `(message?, details?, hint?) => never` |
+| `defineErrors` | function | declare immutable domain error definitions → typed `AppError` constructors, codes and schemas — [guide](../guide/auth-and-errors.md#domain-errors--defineerrors) |
+| `DefinedErrors` | _type_ | the `{ errors, codes, definitions, isCode }` handle `defineErrors` returns |
+| `DefinedAppError` | _type_ | literal-code error instance with schema-refined details |
+| `ErrorDefinition` | _type_ | `{ status, details? }` definition for one domain code |
+| `ErrorDefinitions` | _type_ | string-keyed domain error definition registry |
+| `ErrorDetailsSchema` | _type_ | required or optional Zod object accepted for structured details |
+| `ErrorDetailsOutput` | _type_ | parsed details inferred from one definition |
+| `ErrorFactoryArguments` | _type_ | options tuple with forbidden/required/optional details inferred per code |
+| `ErrorFactory` | _type_ | one typed `AppError` constructor |
+| `ErrorFactories` | _type_ | mapped constructor registry derived from all definitions |
+| `FrozenErrorDefinitions` | _type_ | read-only definition registry returned to consumers |
 | `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? |
@@ -4640,8 +5013,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createAuthHook` | function | a scope-enforcing `beforeHandle` hook — [guide](../guide/auth-and-errors.md#createauthhook) |
-| `createErrorHook` | function | an `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
-| `ErrorHookConfig` | _type_ | config for `createErrorHook` |
+| `createErrorHook` | function | an async-capable, endpoint-aware `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
+| `ErrorHookConfig` | _type_ | async observer/renderer config for `createErrorHook` |
 | `ResolvedError` | _type_ | the normalised error handed to `createErrorHook`'s `render` |
 | `createBearerResolver` | function | a bearer-token identity resolver |
 | `signJwt` | function | sign an HS256 JWT |
@@ -4731,14 +5104,18 @@ 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
+### Events
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createAuditHook` | function | wire both surfaces into one sink — [guide](../guide/observability.md#createaudithook) |
+| `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink |
-| `AuditConfig` | _type_ | config for `createAuditHook` |
-| `AuditHook` | _type_ | the `{ http, toolCall }` the hook returns |
+| `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
+| `Observability` | _type_ | the `{ request?, toolCall }` wiring result |
+| `RequestEventSinkConfig` | _type_ | `write`, `filter` and sanitisation for one event surface |
+| `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture |
+| `HttpRequestCompletion` | _type_ | the single framework-owned HTTP outcome projected to logging and request events |
+| `HttpRequestObserver` | _type_ | server-facing projection consumed by `HandlerConfig.observability` |
 
 ### Request context
 
@@ -4790,31 +5167,44 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 |--------|------|---------|
 | `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 |
+| `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces — 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) |
 | `defineRuntimeTool` | function | define one validated pathless operation for MCP, Agent or both — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
+| `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
 | `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 | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
-| `listToolNames` | function | every mounted tool name with its `(service, method)` identity — for name-baseline snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
+| `listToolNames` | function | every contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
 | `McpHandlerConfig` | _type_ | config for `createMcpHandler` |
+| `McpHttpConfig` | _type_ | HTTP auth, protected-resource and session options composed into `McpHandlerConfig` |
 | `McpSessionMode` | _type_ | `'stateless' \| 'stateful'`; HTTP defaults to request-isolated stateless mode |
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
+| `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
+| `DirectMcpSurfaceConfig` | _type_ | static or identity-dynamic `services` / `runtimeTools` source |
+| `FiniteMcpSurfaceConfig` | _type_ | bounded `surfaces` registry plus typed selector |
+| `McpSurfaceDefinition` | _type_ | one immutable `{ services, runtimeTools }` MCP surface |
+| `McpSurfaceRegistry` | _type_ | finite keyed surface registry for eager preparation |
+| `StdioAuthConfig` | _type_ | startup identity composed into `StdioMcpServerConfig` |
 | `ImplementRemoteOptions` | _type_ | options for `implementRemote` |
 | `McpMountConfig` | _type_ | config for `mountMcp` |
 | `McpSchemaValidationConfig` | _type_ | shared `{ policy, requireTypedProperties, allowUntyped, requirePortableFormats, allowFormats }` profile |
 | `ValidateMcpSchemasConfig` | _type_ | standalone validation profile plus `services`, `extend`, flattening and logger |
-| `NativeMcpRegistrar` | _type_ | protected `registerTool` plus explicit unprotected `rawServer` access |
 | `RuntimeToolDefinition` | _type_ | transport-neutral pathless operation with identity, schemas, handler and optional presenters |
 | `RuntimeToolDefinitionBase` | _type_ | common name, identity, input, exposure and MCP metadata fields |
 | `RuntimeToolDefinitionWithOutput` | _type_ | runtime definition whose handler and presenters share a validated output type |
 | `RuntimeToolDefinitionWithoutOutput` | _type_ | runtime definition with a void handler and no presentation callbacks |
+| `RuntimeToolFactory` | _type_ | identity/context-bound runtime-tool definition factory |
+| `RuntimeToolFactoryConfig` | _type_ | factory service identity and context schema |
+| `RuntimeToolFactoryDefinitionWithOutput` | _type_ | factory-authored runtime tool with a validated output schema |
+| `RuntimeToolFactoryDefinitionWithoutOutput` | _type_ | factory-authored void runtime tool without presenters |
+| `RuntimeToolFactoryHandlerContext` | _type_ | parsed factory context plus parsed tool input |
+| `RuntimeToolFactoryIdentityFields` | _type_ | per-tool action, semantic method and optional identity metadata |
 | `RuntimeToolIdentity` | _type_ | `{ serviceName, action, scope?, method, meta? }` for runtime lifecycle/audit |
 | `RuntimeToolHandlerContext` | _type_ | runtime context with the definition's parsed input |
 | `RuntimeToolOutput` | _type_ | output inferred from a runtime tool's optional Zod schema |
@@ -4850,7 +5240,7 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `findNonPortableFormats` | function | deep finder for formats outside the portable MCP/AJV baseline |
 | `NonPortableFormat` | _type_ | one `{ path, format }` portability finding |
 | `PORTABLE_JSON_SCHEMA_FORMATS` | constant | portable-format baseline used by MCP validation |
-| `ToolNameEntry` | _type_ | one `listToolNames` row — `{ name, service, method, transports }` |
+| `ToolNameEntry` | _type_ | one `listToolNames` row — `{ kind, name, service, method, transports }` |
 | `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
 | `McpMediaContent` | _type_ | a multimodal MCP content item |
 
@@ -4909,14 +5299,17 @@ Advanced building blocks — the shared machinery the mounts are built on.
 |--------|------|---------|
 | `collectTools` | function | resolve a service's methods to mountable tools (the shared resolver) |
 | `createToolLogger` | function | a ready `afterToolCall` that logs every tool call — [guide](../guide/mcp-and-agents.md#logging-tool-calls--createtoollogger) |
-| `summarizeTransports` | function | per-transport operation counts for a boot-time summary |
-| `buildToolManifest` | function | a searchable `{ name, description, inputSchema }` manifest for a `tool_search` tool |
+| `summarizeTransports` | function | mixed contract/runtime operation counts and per-source breakdown for a boot-time summary |
+| `buildToolManifest` | function | transport-aware searchable `{ name, description, inputSchema }` rows from a mixed surface |
 | `ToolLoggerConfig` | _type_ | config for `createToolLogger` |
 | `ToolCallRecord` | _type_ | the structured record `createToolLogger` passes to `onRecord` |
-| `TransportSummary` | _type_ | the result of `summarizeTransports` |
+| `TransportSummary` | _type_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
+| `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
+| `ToolSurfaceTransport` | _type_ | tool collector transport: `'MCP' \| 'AGENT' \| 'CLI'` |
+| `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
-| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions in a JSON Schema document into conservative object joins; never executes validation |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; divergent fields retain every provable base kind in a deterministic `type` array, and the projection never executes validation |
 | `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
 | `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
 | `ToolManifestEntry` | _type_ | one `buildToolManifest` row |