stitchkit 0.53.2 → 0.55.0

package/llms-full.txt

@@ -33,7 +33,7 @@ realtime, `@tanstack/react-query` + `react-query-kit` for React). See
 
 ## Entrypoints
 
-stitchkit ships nine entrypoints. Each is import-safe for one environment —
+stitchkit ships eleven 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 |
@@ -44,12 +44,15 @@ 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/remote` | browser **and** server | peer-free `implementRemote` for thin HTTP proxy processes |
+| `stitchkit/files` | server (Bun or Node) | peer-free managed local-file boundary |
 | `stitchkit/observability` | server | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | in-process generated clients over a real Fetch handler, without a TCP port |
 | `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
-code adds `stitchkit/server` (or `stitchkit/node` on Node) and `stitchkit/tools`.
+code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into
+`stitchkit/tools`, `stitchkit/remote` or `stitchkit/files` by capability.
 The full export list of each is in the [API reference](../api/reference.md).
 
 ## Project layout
@@ -2364,8 +2367,9 @@ must not be used as authorization input.
 ### Modern discovery, routing and cache hints
 
 Stitchkit forwards the negotiated protocol era and validated MCP request data
-to `RequestEvent.mcp`; untrusted routing headers never become application
-identity. The SDK validates `MCP-Protocol-Version`, JSON-RPC shape and routing
+to both `RequestEvent.mcp` and the current managed call's typed `context.mcp`;
+untrusted routing headers never become application identity. The SDK validates
+`MCP-Protocol-Version`, JSON-RPC shape and routing
 metadata before lifecycle or tool handlers run. Framework-owned tool and
 resource registration preserves declaration order across HTTP and stdio. Tool
 manifests preserve mount order; `listToolNames` is a sorted diagnostics view.
@@ -2380,6 +2384,30 @@ finite `surfaces` registry when identities share a provably immutable surface.
 Stitchkit never advertises list-change or subscription capabilities
 without an implementation.
 
+### Typed MCP call metadata
+
+Contract handlers, runtime-tool handlers/factories, lifecycle and tool hooks all
+see the same optional `McpCallContext` for the current invocation:
+
+```ts
+const sourceLabel = context.mcp?.clientInfo?.name ?? context.source
+
+context.mcp?.era             // 'modern' | 'legacy'
+context.mcp?.method          // validated MCP method
+context.mcp?.toolName        // resolved framework tool name
+context.mcp?.protocolVersion // when supplied by a modern host
+context.mcp?.clientInfo      // { name, version } when validated
+context.mcp?.outcome         // multi-round attempt outcome
+context.mcp?.round           // multi-round attempt number
+```
+
+The field is absent on HTTP, Agent, CLI and bring-your-own transports. A legacy
+MCP call exposes `era: 'legacy'` but does not invent modern client information.
+`clientInfo` is the host's self-description: use it for labels or analytics,
+never for authentication, RBAC, tenant selection or rate limiting. Verified
+identity still comes from `auth`; the `context(auth)` callback remains the
+application-context factory and receives no protocol metadata.
+
 ### Multi-round tool input (`input_required`)
 
 An MCP-only operation can require typed user input before its final side effect:
@@ -2598,7 +2626,7 @@ 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'
+import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools'
 
 const stdio = await createStdioMcpServer({
   serverInfo: { name: 'my-app', version: '1.0.0' },
@@ -2606,8 +2634,16 @@ const stdio = await createStdioMcpServer({
   services: [usersService],
 })
 
-// During graceful shutdown:
-await stdio.close()
+const signals = bindStdioProcessSignals(stdio, {
+  onClose: () => stopWorkers(),
+  onComplete: () => { process.exitCode = 0 },
+  onError: (_phase, error) => {
+    console.error(error) // stderr only — stdout is JSON-RPC
+    process.exitCode = 1
+  },
+})
+
+await signals.promise
 ```
 
 A stdio server is a single process serving one client, so `auth` is a value (or
@@ -2620,6 +2656,14 @@ through the official stdio adapter. Use `legacy: 'reject'` for a modern-only
 binary. Each invocation builds a fresh server; the returned handle owns
 transport shutdown.
 
+Signal binding is explicit: `createStdioMcpServer` installs no global process
+listeners by itself. The first `SIGINT`/`SIGTERM` starts exactly one official
+`close()` chain. Stdio has no force primitive, so a later signal restores the
+OS default disposition instead of reporting a fictional forced result.
+`signals.close()` removes an idle binding; the framework never calls
+`process.exit()` or chooses the exit code. See
+[deployment lifecycle](./testing-and-deployment.md#stdio-process-signals).
+
 Both transports build the server through the shared `buildMcpServer` — same
 contract/runtime pipeline, same surface selection, context, hooks, raw escape
 hatch and instructions.
@@ -2736,7 +2780,8 @@ through the contract's typed client:
 
 ```ts
 import { createHttpClient } from 'stitchkit'
-import { createStdioMcpServer, implementRemote } from 'stitchkit/tools'
+import { implementRemote } from 'stitchkit/remote'
+import { createStdioMcpServer } from 'stitchkit/tools'
 
 const http = createHttpClient({
   baseUrl: 'https://api.example.com',
@@ -2943,7 +2988,9 @@ const countRecords = knowledgeTools.define({
 `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
+operation belongs on only one surface. Include `'CLI'` explicitly to reuse the
+definition through `createCli({ runtimeTools })`; adding CLI support never
+widens existing definitions silently. The configured identity becomes the
 hook/lifecycle `OperationIdentity` and the tool `RequestEvent`
 (`serviceName`, `action`, `httpMethod`). A runtime operation has no HTTP route,
 so no fake `path` is added.
@@ -2960,12 +3007,186 @@ The MCP registration uses an identity carrier: the SDK advertises the compiled
 JSON Schema but forwards the raw object into Stitchkit. Input failures therefore
 use the same validation, lifecycle and hook path as contract tools.
 
+### Managed wait, download, upload and view-file
+
+The common imperative shapes have typed definition factories. They produce
+ordinary runtime-tool definitions, so one value can enter `runtimeTools` on MCP
+and Agent and receives the same lifecycle, hooks, context, cancellation,
+collision checks and introspection as any `defineRuntimeTool` operation:
+
+```ts
+import {
+  defineDownloadTool,
+  defineUploadTool,
+  defineViewFileTool,
+  defineWaitTool,
+} from 'stitchkit/tools'
+import { createManagedFileBoundary } from 'stitchkit/files'
+import { z } from 'zod'
+
+const files = await createManagedFileBoundary({ root: '/srv/job-media' })
+
+const waitForJob = defineWaitTool({
+  name: 'wait_for_job',
+  description: 'Wait for a job to finish',
+  identity: { serviceName: 'jobs', action: 'waitForJob', scope: 'user' },
+  input: z.object({ id: z.string() }),
+  state: z.object({ id: z.string(), status: z.enum(['RUNNING', 'DONE']) }),
+  poll: ({ id }, context) => getJob(id, context.signal),
+  done: (state) => state.status === 'DONE',
+  backoff: [2, 3, 5],
+  defaultTimeout: 120,
+})
+
+const downloadResult = defineDownloadTool({
+  name: 'download_result',
+  description: 'Download a completed result',
+  identity: { serviceName: 'jobs', action: 'downloadResult', scope: 'user' },
+  input: z.object({ id: z.string() }),
+  resolveUrl: ({ id }) => resolveResultUrl(id),
+  files,
+  pathFromInput: ({ id }) => `results/${id}.bin`,
+})
+
+const uploadInput = defineUploadTool({
+  name: 'upload_input',
+  description: 'Upload a local input file',
+  identity: { serviceName: 'jobs', action: 'uploadInput', scope: 'user' },
+  output: z.object({ url: z.url() }),
+  files,
+  upload: (source, context) => uploadBytes(source.bytes, context.signal),
+})
+
+const viewResult = defineViewFileTool({
+  name: 'view_result',
+  description: 'Inspect generated media',
+  identity: { serviceName: 'jobs', action: 'viewResult', scope: 'user' },
+  // Local files are disabled when files is omitted. URL fetches retain SSRF
+  // protection; use allowPrivateHosts only for an explicitly trusted network.
+  files,
+})
+
+const runtimeTools = [waitForJob, downloadResult, uploadInput, viewResult]
+```
+
+Managed factories return neutral validated data. Expected failures go through
+the standard failed `ToolResult` path rather than masquerading as a successful
+payload with `isError`. Wait sleep is abort-aware, guarded downloads receive the
+active signal, and upload implementations receive it on their typed context.
+Managed view-file accepts one or several paths/URLs, retains successful
+multimodal content beside structured per-item `errors`, and charges every item
+to one total 20 MB batch budget. Its MCP and Agent presenters are built in;
+remote fetch cancellation follows the active call signal.
+
+The older `mountWait`, `mountDownload`, `mountUpload` and `mountViewFile`
+functions remain
+intentional raw MCP adapters with their text-envelope behavior. Use them under
+`rawTools` only when opting out of managed policy is deliberate; they share the
+same neutral mechanics but do not gain lifecycle or hooks. The raw view-file
+adapter preserves its content-only MCP envelope while using the same bounded
+batch operation.
+
+### Async-operation protocol
+
+For a complete long-running operation, define the linked runtime-only surface
+once. Stitchkit owns transport names, validation and wait mechanics; the
+application still owns storage, execution, retries and domain states:
+
+```ts
+import {
+  createAsyncOperationSnapshotSchema,
+  defineAsyncOperation,
+} from 'stitchkit/tools'
+
+const id = z.object({ id: z.string() })
+const state = z.object({
+  phase: z.enum(['pending', 'running', 'succeeded']),
+  value: z.string().optional(),
+})
+const snapshot = createAsyncOperationSnapshotSchema({
+  failure: z.object({ code: z.string() }),
+  progress: z.object({ current: z.number(), total: z.number() }),
+})
+
+const exportOperation = defineAsyncOperation({
+  mode: 'runtime-only',
+  name: 'export',
+  description: 'Export project data',
+  identity: { serviceName: 'exports', action: 'export', scope: 'user' },
+  startInput: z.object({ projectId: z.string() }),
+  id,
+  state,
+  snapshot,
+  start: ({ projectId }) => enqueueExport(projectId),
+  authorize: ({ id }, capability, ctx) => authorizeExport(id, capability, ctx),
+  inspect: ({ id }, ctx) => readExport(id, ctx.signal),
+  classify: (job) => ({ phase: job.phase }),
+  result: {
+    output: z.object({ value: z.string() }),
+    handler: (job) => ({ value: job.value ?? '' }),
+  },
+})
+
+const runtimeTools = exportOperation.runtimeTools
+```
+
+Every follow-up repeats `authorize`; an opaque id is never authority. Aborting
+`wait` only stops waiting and never calls optional domain `cancel`. A
+contract-backed operation uses `bindContractAsyncOperation` with literal methods
+from a dedicated existing contract, so it creates no second HTTP router or
+duplicate schemas. Capability keys are narrowed by schema-compatible TypeScript
+input/output types. At runtime, the binder additionally requires the exact same
+id and snapshot Zod instances; declare each once and reuse it:
+
+```ts
+import { defineContract } from 'stitchkit/contract'
+import { bindContractAsyncOperation } from 'stitchkit/tools'
+import { z } from 'zod'
+
+const operationId = z.object({ id: z.string() })
+const operationSnapshot = z.object({
+  phase: z.enum(['pending', 'running', 'succeeded', 'failed', 'cancelled']),
+})
+
+const operations = defineContract(
+  { prefix: 'exports' },
+  {
+    start: {
+      method: 'POST', path: '/', desc: 'Start export',
+      input: z.object({ projectId: z.string() }), output: operationId,
+    },
+    status: {
+      method: 'POST', path: '/status', desc: 'Read export status',
+      input: operationId, output: operationSnapshot,
+    },
+    wait: {
+      method: 'POST', path: '/wait', desc: 'Wait for export',
+      input: operationId, output: operationSnapshot,
+    },
+  },
+)
+
+const operationHandlers = {
+  start: () => ({ id: 'example' }),
+  status: (): z.output<typeof operationSnapshot> => ({ phase: 'pending' }),
+  wait: (): z.output<typeof operationSnapshot> => ({ phase: 'succeeded' }),
+}
+
+const bound = bindContractAsyncOperation({
+  mode: 'contract-backed',
+  contract: operations,
+  capabilities: { start: 'start', status: 'status', wait: 'wait' },
+  handlers: operationHandlers,
+})
+```
+
 ### Explicit raw SDK registration
 
 `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:
+hooks. The built-in `mountViewFile`, `mountWait`, `mountDownload` and
+`mountUpload` helpers remain raw for callers that choose that boundary; the
+media helper fetches with SSRF and path-traversal defenses:
 
 ```ts
 import { createMcpHandler, mountViewFile } from 'stitchkit/tools'
@@ -2974,13 +3195,15 @@ const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth,
   services: [service],
-  rawTools: (server) => mountViewFile(server, { baseDir: '/srv/uploads' }),
+  rawTools: (server) => mountViewFile(server, { files }),
 })
 ```
 
 Use raw registration only when opting out is intentional. For a protected
-`view_file`, define it with `defineRuntimeTool`, include it in `runtimeTools`,
-and call the exported `resolveMedia` core from its handler.
+`view_file`, use `defineViewFileTool` in `runtimeTools`; it supplies the
+canonical schemas, shared batch budget, structured partial failures and both
+multimodal presenters. `resolveMedia` remains the single-item core for custom
+operations whose contract intentionally differs.
 
 ## Introspecting the complete tool surface
 
@@ -3061,11 +3284,13 @@ identical. Write the handler once; it serves every surface.
 
 # 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)).
+The same contract and managed runtime tools that drive HTTP, MCP and agent
+surfaces can also drive a command-line program. `createCli` composes their
+commands with explicitly local binary commands in one router and help tree.
+Managed commands — `myapp generate "a fox" --wait`,
+`myapp models list --json | jq …` — run through the same validation, auth gate
+and error model as every other managed 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
@@ -3086,8 +3311,10 @@ the CLI never silently turns your existing API tools into shell commands.
 ```
 
 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` →
+design, not a bug. A pathless runtime definition follows the same rule: it must
+explicitly include `'CLI'` in `transports`; the undefined default remains
+`['MCP', 'AGENT']`. 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
@@ -3105,10 +3332,16 @@ await createCli({
   name: 'myapp',
   version: '1.0.0',
   services: [catalogService, generateService],
-  auth: process.env.MYAPP_TOKEN,            // resolved ONCE, like a stdio MCP server
+  resolveAuth: () => resolveToken(process.env.MYAPP_TOKEN), // lazy, at most once
 })
 ```
 
+`createCli({ signal })` and its wait loop honor an explicit caller
+`AbortSignal`. Stitchkit does not install a process-global SIGINT handler for
+ordinary CLI programs: if desired, the application binds SIGINT to an
+`AbortController` and passes its signal. Aborting wait stops polling only; it
+does not cancel the underlying job.
+
 ```json
 // package.json
 { "bin": { "myapp": "./dist/cli.js" } }
@@ -3117,6 +3350,81 @@ await createCli({
 `stitchkit/cli` pulls in neither the MCP SDK nor `ai`, so a CLI binary needs no
 MCP/agent peer dependencies.
 
+## Pathless managed commands
+
+Use `runtimeTools` when an application operation has no HTTP path but must keep
+the canonical operation identity, context, lifecycle/RBAC, hooks and
+introspection. It can share one definition with MCP and Agent while opting into
+CLI explicitly:
+
+```ts
+import { createCli } from 'stitchkit/cli'
+import { defineUploadTool } from 'stitchkit/tools'
+import { z } from 'zod'
+
+const uploadInput = defineUploadTool({
+  name: 'upload_input',
+  description: 'Upload one local input file',
+  identity: { serviceName: 'jobs', action: 'uploadInput', scope: 'user' },
+  output: z.object({ url: z.url() }),
+  transports: ['MCP', 'AGENT', 'CLI'],
+  upload: (path, context) => uploadFile(path, context.signal),
+})
+
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  runtimeTools: [uploadInput],
+})
+```
+
+`services` and `runtimeTools` may each be static arrays or factories receiving
+the resolved identity. A runtime-only CLI is valid; `stitchkit/cli` still pulls
+in neither MCP nor AI peers. Contract/runtime name collisions and reserved
+option fields fail through the same checks before managed dispatch.
+
+## Native binary commands
+
+Login, self-update, diagnostics, integration setup and shell completion belong
+to the executable, not to HTTP/MCP/Agent. Define them with `defineCliCommand`:
+
+```ts
+import { createCli, defineCliCommand } from 'stitchkit/cli'
+import { z } from 'zod'
+
+const login = defineCliCommand({
+  name: 'login',
+  description: 'Store credentials for later managed commands',
+  input: z.object({ token: z.string() }),
+  output: z.object({ configured: z.boolean() }),
+  handler: async ({ input }) => {
+    await saveToken(input.token)
+    return { configured: true }
+  },
+})
+
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  commands: [login],
+  resolveAuth: loadStoredIdentity,
+  services: (identity) => createRemoteServices(identity),
+})
+```
+
+Native commands receive only typed `input`, parsed global `options` and the
+configured stdout/stderr writers. They reuse help, argv/stdin parsing,
+validation, dry-run, error envelopes and exit mapping, but deliberately have no
+fake service/action/scope/method identity, lifecycle or tool hooks and never
+appear in MCP/Agent manifests.
+
+`--version`, a selected native command and its command help run before
+`resolveAuth`, services, context or runtime-tool factories. Top-level help is
+also credential-free when managed surfaces are static. A dynamic factory must
+resolve identity to discover its command names; its collisions are checked at
+that resolution boundary. If eager global collision proof matters, keep the
+surface static.
+
 ## Calling commands
 
 ```
@@ -3147,7 +3455,7 @@ same Zod schema an HTTP or MCP call does.
 
 | Flag                  | Effect                                                     |
 | --------------------- | ---------------------------------------------------------- |
-| `--json`              | Raw JSON on stdout for piping / scripts                    |
+| `--json`              | Compact success/error JSON records for 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                     |
@@ -3155,10 +3463,18 @@ same Zod schema an HTTP or MCP call does.
 | `--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`.
+stdout carries the result; structured errors and progress go to stderr. With
+`--json`, a success or structured failure is exactly one compact,
+newline-terminated JSON record on its respective stream; progress and CLI usage
+diagnostics remain ordinary stderr text. This keeps stdout pipeable and
+`2>/dev/null` 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`.
+
+Per-command help derives the positional form from the same schema order as the
+argv parser. For example, a required `action` and optional `profile` render as
+`Usage: myapp skill <action> [profile] [--flags]`; the argument table also shows
+`<action> | --action` and `[profile] | --profile`. Boolean fields remain flags.
 
 ## `--wait` — background-friendly generation
 
@@ -3175,12 +3491,19 @@ await createCli({
     generate: {
       tool: 'get_generation',
       poll: (r) => (isRecord(r) && typeof r.id === 'string' ? { id: r.id } : null),
-      done: (r) => isRecord(r) && r.status === 'COMPLETED',
+      done: (r) => isRecord(r) && ['COMPLETED', 'FAILED'].includes(String(r.status)),
+      failed: (r) => isRecord(r) && r.status === 'FAILED',
     },
   },
 })
 ```
 
+`failed` is optional. When it matches either the initial result or a later poll,
+polling stops and the CLI emits `WAIT_FAILED` on stderr with a non-zero exit;
+the terminal payload is retained under `details.result`. `failed` is checked
+before `done`, so overlapping predicates fail closed. A failed poll tool call
+keeps its own error code, and an elapsed deadline remains `TIMEOUT`.
+
 ```bash
 # foreground
 myapp generate "a fox" --wait --output-dir ./out
@@ -3201,7 +3524,7 @@ const authHook = createAuthHook({ /* resolve, resolveFromContext, rules */ })
 await createCli({
   name: 'myapp',
   version: '1.0.0',
-  auth: await resolveIdentityFromToken(process.env.MYAPP_TOKEN),
+  resolveAuth: () => resolveIdentityFromToken(process.env.MYAPP_TOKEN),
   context: (identity) => ({ user: identity }),   // resolveFromContext reads this
   lifecycle: { beforeHandle: authHook },          // same policy; HTTP wires it as authorize
   services,
@@ -3233,11 +3556,12 @@ await tools.createCli({
 })
 ```
 
-## Not in v1
+## Remaining boundary
 
-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.
+File-upload (`multipart`) contract endpoints remain CLI-invisible, the same as
+on MCP/Agent: their wire body is not a JSON tool form. Model file-oriented
+application behavior as a managed pathless command, or binary-only behavior as
+a native command. Streaming (SSE) output is not yet piped to stdout.
 
 
 ==============================================================================
@@ -3285,6 +3609,57 @@ runtime. A malformed inbound tuple never reaches the application handler;
 invalid outbound data throws before Socket.IO publishes it. Rejections call the
 optional `onRejected` hook with event, direction, phase and the Zod error.
 
+### Protocol generations
+
+For a distributed producer/consumer pair, put a literal generation first in the
+first payload object. Zod validates object fields in declaration order, so an
+incompatible peer is identified before the rest of its payload is interpreted:
+
+```ts
+const ReplicationMessage = z.object({
+  v: z.literal(2),
+  item: ReplicatedItem,
+})
+
+const realtimeContract = defineRealtimeContract({
+  serverToClient: {
+    replicated: { args: z.tuple([ReplicationMessage]) },
+  },
+  clientToServer: {},
+})
+```
+
+The original `z.ZodError` is retained as `RealtimeRejectedEvent.error.cause`.
+Because event arguments are a tuple, the first payload's `v` path is
+`[0, 'v']` (not `['v']`):
+
+```ts
+import type { RealtimeRejectedEvent } from 'stitchkit'
+import { z } from 'zod'
+
+function isProtocolGenerationMismatch(rejected: RealtimeRejectedEvent): boolean {
+  const cause = rejected.error.cause
+  if (!(cause instanceof z.ZodError)) return false
+  const first = cause.issues[0]
+  return first?.code === 'invalid_value'
+    && first.path.length === 2
+    && first.path[0] === 0
+    && first.path[1] === 'v'
+}
+
+const socket = createRealtimeClient(realtimeContract, {
+  url,
+  onRejected: (rejected) => {
+    if (isProtocolGenerationMismatch(rejected)) schedulePeerUpgrade()
+    else reportMalformedRealtimePayload(rejected)
+  },
+})
+```
+
+A generation mismatch means “upgrade the peer”; another schema rejection means
+“fix the producer or payload”. This stays an application convention, not a core
+API: only the application knows which field denotes protocol compatibility.
+
 ## Server — `createSocketIOServer`
 
 ```ts
@@ -3383,6 +3758,35 @@ socket.on('note:created', (note) => { /* typed note */ })
 socket.emit('room:join', 'general', ({ joined }) => { /* typed + validated */ })
 ```
 
+### Request-response over realtime
+
+For an event with an `ack` schema, `request()` is the Promise form of the same
+native Socket.IO acknowledgement. Arguments and the resolved value are inferred
+from the contract and validated on both sides:
+
+```ts
+const result = await socket.request(
+  'room:join',
+  'general',
+  { timeoutMs: 5_000 },
+)
+// result: { joined: boolean }
+```
+
+An event without `ack` cannot be passed to `request()` by type. A disconnected
+client rejects immediately with `RealtimeRequestDisconnectedError`; an in-flight
+disconnect uses the same error; an elapsed native acknowledgement timeout uses
+`RealtimeRequestTimeoutError`. These are distinct stable classes and codes, so
+never parse Socket.IO error text. An invalid acknowledgement still fires the
+existing `onRejected` hook with phase `acknowledgement`, then rejects with
+`RealtimeRequestInvalidAcknowledgementError`.
+
+`timeoutMs` must be finite and greater than zero. Use acknowledgements only for
+bounded request-response work. A job that runs for minutes, progress streaming,
+or resumable delivery should use separate correlated events or the async
+operation protocol; keeping one acknowledgement open is not a durable RPC/job
+transport.
+
 ## Low-level transport
 
 `createSocketIOClient` remains the low-level Socket.IO transport wrapper for
@@ -3867,10 +4271,11 @@ 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
+- **a function** `(identity, ctx) => boolean | contribution`, sync or async — a custom
   check. It receives request metadata and validated path params, so a
   resource-scoped rule can do a DB lookup. It cannot read `input` or files: the
-  body has deliberately not been consumed yet. May be async.
+  body has deliberately not been consumed yet. `false` denies, `true` passes,
+  and a returned plain object passes and contributes inferred handler fields.
 
 #### Resource-scoped rule — reading a path/prefix param
 
@@ -3900,6 +4305,30 @@ 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'`.
 
+When the async authorization lookup already produced handler data, return it
+instead of repeating the lookup in `inject` and a handwritten scope map:
+
+```ts
+const auth = createAuthHook({
+  resolve: sessionResolver,
+  rules: {
+    project: async (user, ctx) => {
+      const membership = await findMembership(user.id, String(ctx.projectId))
+      return membership
+        ? { userId: user.id, projectId: membership.projectId, role: membership.role }
+        : false
+    },
+  },
+})
+
+const implementFor = createScopedImplement<AuthScopes<typeof auth>>()
+```
+
+Contributions are merged only after full validation. Runtime-owned context keys,
+arrays, class instances, accessors, symbols, unsafe prototypes and partial proxy
+reads fail without mutating context. `false | object` contributes required
+fields; `true | object` correctly makes them optional.
+
 ### `AuthHookConfig`
 
 | Field | Purpose |
@@ -4767,6 +5196,25 @@ observe. (This is also why it lives on `ToolCallHooks` rather than being an
 `Response`, which a tool call has no use for, and a whole `createServer` hooks
 object must stay assignable to `ToolLifecycle`.)
 
+### Compose lifecycle policy explicitly
+
+When auth, a feature policy and audit identity are independent modules, compose
+their existing hooks instead of forwarding each phase by hand:
+
+```ts
+import { composeLifecycleHooks } from 'stitchkit/server'
+import { composeToolLifecycle } from 'stitchkit/tools'
+
+const httpLifecycle = composeLifecycleHooks(authLifecycle, featurePolicy, auditIdentity)
+const toolLifecycle = composeToolLifecycle(authHook, featureToolPolicy, auditToolIdentity)
+```
+
+Phases run left to right. `onRequest` stops on the first `Response`; `onError`
+falls through until a hook handles it; after transforms feed the current value
+forward and preserve it when a hook returns `undefined`. Throws remain owned by
+the existing outer error boundary, and the original context/signal identity is
+never replaced.
+
 **Do not reach for `setRequestError` here.** It writes to the *request* context,
 which the built-in **tool** row does not read: a tool event takes
 `errorCode` / `errorMessage` / `errorDetail` from the `ToolResult`, and only
@@ -4882,6 +5330,38 @@ contract registry. Both helpers are Fetch-only: they construct ordinary
 absolute `Request` objects and call `createHandler` directly, so Bun and Node
 exercise the same framework pipeline.
 
+### Transport conformance
+
+`buildSurfaceManifest` snapshots actual HTTP topology, MCP/Agent/CLI names,
+CLI-only commands, extensions and canonical schema digests. Compare real runner
+discovery with `assertSurfaceDiscovery`, then use `runSurfaceProbes` only for
+the transports you explicitly provide:
+
+```ts
+import {
+  assertSurfaceDiscovery,
+  buildSurfaceManifest,
+  runSurfaceProbes,
+} from 'stitchkit/testing'
+
+const manifest = buildSurfaceManifest({ services, runtimeTools, cliCommands })
+assertSurfaceDiscovery(manifest, {
+  openApi,
+  MCP: (await mcpClient.listTools()).tools.map((tool) => tool.name),
+  AGENT: Object.keys(agentTools),
+  CLI: cliHelpNames,
+})
+
+await runSurfaceProbes({
+  probes,
+  drivers: { HTTP: httpDriver, MCP: mcpDriver, AGENT: agentDriver, CLI: cliDriver },
+})
+```
+
+The kit never starts a server or invents credentials. Each probe declares its
+expected normalized outcome and has bounded timeout, setup/teardown and an
+AbortSignal. A missing driver is unsupported, not silently marked conformant.
+
 ### Test handlers with raw Requests
 
 `createHandler` is the router as a plain `(req) => Promise<Response>` function —
@@ -5079,6 +5559,38 @@ domain run-state remain application resources and close explicitly after server
 drain. Do not call `runtime.stop()` or `socket.io.close()` in parallel with
 `shutdown()`.
 
+### Stdio process signals
+
+An MCP stdio handle has `close()`, not managed HTTP `shutdown()` with a force
+signal and deadline. Bind its process lifecycle with the truthful close-only
+sibling from `stitchkit/tools`:
+
+```ts
+import {
+  bindStdioProcessSignals,
+  createStdioMcpServer,
+} from 'stitchkit/tools'
+
+const stdio = await createStdioMcpServer(config)
+const binding = bindStdioProcessSignals(stdio, {
+  onClose: () => stopWorkers(),
+  onComplete: () => { process.exitCode = 0 },
+  onError: (phase, error) => {
+    console.error(phase, error) // stderr; stdout stays JSON-RPC-only
+    process.exitCode = 1
+  },
+})
+
+await binding.promise
+```
+
+The first signal starts exactly one close chain. A same-turn duplicate is
+ignored; a later signal restores the default OS disposition because the
+official stdio close is not abortable and Stitchkit will not pretend otherwise.
+`binding.close()` removes idle listeners and resolves the promise with
+`undefined`. No listener is installed until the binder is called, and the
+framework never calls `process.exit()`.
+
 ### Deploy on Node
 
 The contract, `implement`, hooks, auth and the client are runtime-agnostic. Only
@@ -5409,6 +5921,45 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Unreleased migration: peer-free `implementRemote`
+
+`implementRemote` now has one canonical, optional-peer-free owner. This keeps
+MCP SDK and AI SDK modules out of CLI bundles that only proxy HTTP calls:
+
+```ts
+// before
+import { implementRemote } from 'stitchkit/tools'
+// after
+import { implementRemote } from 'stitchkit/remote'
+```
+
+## Unreleased migration: managed file boundary and strict auth returns
+
+Create one boundary during application bootstrap and pass the capability, never
+a per-call directory or host path:
+
+```ts
+import { createManagedFileBoundary } from 'stitchkit/files'
+
+const files = await createManagedFileBoundary({ root: '/srv/app-files' })
+
+// before
+defineDownloadTool({ defaultDir: '/srv/app-files', resolveUrl, ...common })
+defineUploadTool({ upload: (path) => provider.uploadFile(path), ...common })
+defineViewFileTool({ baseDir: '/srv/app-files', ...common })
+
+// after
+defineDownloadTool({ files, resolveUrl, ...common })
+defineUploadTool({ files, upload: ({ bytes }) => provider.upload(bytes), ...common })
+defineViewFileTool({ files, ...common })
+```
+
+Downloaded `path` is now relative to the boundary and MIME metadata is named
+`mediaType`. Update raw `mountDownload`/`mountUpload`/`mountViewFile` configs the
+same way. Auth predicates must explicitly return `true`, `false`, or a plain
+object of context fields; replace accidental `undefined` fallthroughs with the
+intended boolean.
+
 ## Released migration: 0.53.0
 
 ### Realtime `emit` returns `boolean` instead of `void`
@@ -6378,11 +6929,18 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
-| `SocketIOClient` | _type_ | the client handle; `emit` returns `false` for an emit dropped while disconnected |
+| `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
 | `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
 | `RealtimeClientOptions` | _type_ | transport options and the rejected-event hook for `createRealtimeClient` |
+| `RealtimeAcknowledgedEvent` | _type_ | event-name union restricted to definitions with an `ack` schema |
+| `RealtimeAcknowledgement` | _type_ | validated acknowledgement output inferred from an event definition |
+| `RealtimeRequestArguments` | _type_ | request arguments inferred from an acknowledged event tuple |
+| `RealtimeRequestOptions` | _type_ | finite positive native acknowledgement `timeoutMs` |
+| `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
+| `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
+| `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |
 | `RealtimeContract` | _type_ | shared server-to-client and client-to-server event registries |
 | `RealtimeEventRegistry` | _type_ | string-keyed registry of event definitions |
 | `RealtimeEventDefinition` | _type_ | one tuple-shaped event and optional acknowledgement schema |
@@ -6443,8 +7001,11 @@ from the root `stitchkit`.
 | `HttpMethod` | _type_ | `GET \| HEAD \| 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 |
+| `RuntimeContext` | _type_ | the loose context seen by transport and hooks, including optional typed `mcp` metadata |
+| `HandlerContext` | _type_ | the typed context seen by a handler, including optional typed `mcp` metadata |
+| `McpCallContext` | _type_ | validated metadata for the active managed MCP call (`era`, method, tool, client and multi-round fields) |
+| `McpClientInfo` | _type_ | self-reported MCP host name/version; attribution only, never application identity |
+| `McpRoundOutcome` | _type_ | managed multi-round attempt outcome |
 | `EndpointHandlerContext` | _type_ | one endpoint handler's fully inferred params, input, files and runtime context |
 | `EndpointFn` | _type_ | the call signature of one client method |
 | `TypedClient` | _type_ | the full typed client for a contract |
@@ -6560,6 +7121,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `OperationIdentity` | _type_ | path-free service/action/scope/method identity shared by contract and native tool operations |
 | `Handlers` | _type_ | the typed handler map `implement` expects |
 | `LifecycleHooks` | _type_ | `onRequest` / pre-body `authorize` / `beforeHandle` / `afterHandle` / `onError` |
+| `composeLifecycleHooks` | function | compose HTTP lifecycle phases in declaration order with short-circuit/fallthrough semantics |
 | `AuthorizationContext` | _type_ | HTTP pre-body context with validated params, `input: undefined` and no files |
 | `RouteGroup` | _type_ | a prefixed group of services with its own hooks |
 | `RawRoute` | _type_ | a non-contract `Request → Response` route with a concrete `BunServer` context |
@@ -6591,6 +7153,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `AuthHook` | _type_ | the hook `createAuthHook` returns |
 | `AuthHookConfig` | _type_ | config for `createAuthHook` |
 | `AuthRule` | _type_ | `'public' \| 'authenticated' \| predicate` |
+| `AuthRuleContribution` | _type_ | plain context fields a sync/async rule may contribute after authorizing |
 | `ScopedAuthRule` | _type_ | a rule plus its typed context contribution — `{ rule, inject? }` |
 | `AuthRules` | _type_ | the `rules` map: bare rules or scoped rules |
 | `RuleScopes` | _type_ | scope→context map derived from a `rules` object; `'public'` fields become optional |
@@ -6759,6 +7322,18 @@ audit event. See the [Observability guide](../guide/observability.md).
 
 ---
 
+## `stitchkit/remote`
+
+Peer-free remote implementation boundary. Importing it does not load the MCP
+SDK, `ai`, or other optional tool peers, so it is safe in a thin CLI bundle.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
+| `ImplementRemoteOptions` | _type_ | optional argument-rewrite hook for `implementRemote` |
+
+---
+
 ## `stitchkit/tools`
 
 Server-only. Turns contracts into MCP and AI-agent tools. MCP server surfaces
@@ -6775,14 +7350,15 @@ payload.
 | `createMcpHandler` | function | a stateless dual-era Streamable-HTTP MCP handler — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
 | `createMcpHttpRoute` | function | framework-owned `RawRoute` adapter for an MCP HTTP handler |
 | `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
+| `bindStdioProcessSignals` | function | explicitly bind OS signals to one close-only stdio handle — [guide](../guide/testing-and-deployment.md#stdio-process-signals) |
 | `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces; no-auth configs omit the second argument |
 | `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) |
+| `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [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`) |
+| `defineCliCommand` | function | define one typed CLI-only command with no fake managed-tool identity — [guide](../guide/cli.md#native-binary-commands) (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 |
@@ -6796,6 +7372,10 @@ payload.
 | `McpLegacyPolicy` | _type_ | `'serve' \| 'reject'` protocol-era compatibility policy |
 | `McpStdioHandle` | _type_ | closeable official stdio transport handle |
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
+| `StdioCloseTarget` | _type_ | minimal close-only target accepted by `bindStdioProcessSignals` |
+| `StdioProcessSignalsOptions` | _type_ | signal source, close callbacks and phased error reporting |
+| `StdioProcessSignalsBinding` | _type_ | close-only signal binding with observed `promise` and listener `close()` |
+| `StdioProcessSignalsErrorPhase` | _type_ | `'prepare' \| 'close' \| 'complete'` reporting phase |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
 | `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
 | `McpServer` | _type_ | official split-SDK server instance accepted by raw extension points |
@@ -6804,7 +7384,6 @@ payload.
 | `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 |
@@ -6833,10 +7412,16 @@ payload.
 | `CimdCacheEvent` | _type_ | observable CIMD cache hit, miss, revalidation and eviction event |
 | `createSecureClientMetadataFetcher` | function | production HTTPS, DNS/IP-pinned CIMD fetcher |
 | `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
-| `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT'` |
+| `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT' \| 'CLI'`; omission still means MCP+Agent only |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
 | `CliConfig` | _type_ | config for `createCli` |
+| `CliSurfaceSource` | _type_ | static managed surface or identity-dependent surface factory for `createCli` |
+| `CliCommandDefinition` | _type_ | Zod-first CLI-only command union |
+| `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
+| `CliCommandDefinitionWithOutput` | _type_ | native command with declared output schema and validated handler result |
+| `CliCommandDefinitionWithoutOutput` | _type_ | void native command with no output schema |
+| `CliCommandContext` | _type_ | parsed native command input, global options and injected writers |
 | `CliWaitConfig` | _type_ | `--wait` polling config |
 | `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
 | `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
@@ -6853,9 +7438,15 @@ payload.
 | `ToolInvokerConfig` | _type_ | compile-time exposure, extension and presentation options |
 | `ToolInvocationOptions` | _type_ | per-call source, context, lifecycle, hooks and output-strip reporter |
 | `ToolInvokerTransport` | _type_ | invoker exposure policy: `MCP \| AGENT \| CLI` |
-| `ToolCallContext` | _type_ | the context every tool hook receives — `{ source }` plus whatever the mount's `context` added |
-| `ViewFileOptions` | _type_ | options for `mountViewFile` |
+| `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
+| `ViewFileOptions` | _type_ | shared URL/managed-file-boundary policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
+| `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
+| `ViewFileInputSchema` | constant | fixed one-or-many media path/URL input schema |
+| `ViewFileOutputSchema` | constant | Zod schema for the neutral managed view-file batch result |
+| `ViewFileErrorSchema` | constant | Zod schema for one structured per-item view failure |
 | `McpAnnotations` | _type_ | MCP annotations on a media result |
+| `McpAnnotationsSchema` | constant | Zod schema for MCP media annotations |
+| `McpMediaContentSchema` | constant | Zod schema for text/image/audio media content |
 | `CollectToolsConfig` | _type_ | options for `collectTools` |
 | `findUntypedProperties` | function | every property in a JSON Schema with no `type`/`enum`/`$ref` — what a model is shown and cannot obey ([guide](../guide/mcp-and-agents.md)) |
 | `UntypedProperty` | _type_ | one such property — `{ path, description? }` |
@@ -6868,13 +7459,44 @@ payload.
 
 ### Native tools
 
-Generic host-supplied tools mounted onto a server — not derived from a contract.
+Generic host-supplied operations — managed definitions for the canonical
+runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `mountDownload` | function | a "download a URL to disk" tool (SSRF-guarded, size-capped) |
-| `mountUpload` | function | an "upload a local file" tool |
-| `mountWait` | function | a generic `--wait`-style polling tool |
+| `defineDownloadTool` | function | define a guarded, size-capped managed download for MCP/Agent `runtimeTools` |
+| `defineUploadTool` | function | define a typed managed local-file upload for MCP/Agent `runtimeTools` |
+| `defineWaitTool` | function | define a typed, cancellable managed polling operation for MCP/Agent `runtimeTools` |
+| `defineViewFileTool` | function | define a guarded, batch-capped managed multimodal operation for MCP/Agent `runtimeTools` |
+| `DefineDownloadToolConfig` | _type_ | Zod input, stable identity, URL resolver, storage policy and presenters for `defineDownloadTool` |
+| `DefineUploadToolConfig` | _type_ | stable identity, typed output, upload callback and presenters for `defineUploadTool` |
+| `DefineWaitToolConfig` | _type_ | Zod input/state, identity, poll/done/timeout policy and presenters for `defineWaitTool` |
+| `DefineViewFileToolConfig` | _type_ | identity, media security policy and optional presenters for `defineViewFileTool` |
+| `ManagedNativeToolConfig` | _type_ | shared name, description, identity, exposure and annotations for managed native factories |
+| `NativeToolIdentity` | _type_ | pathless service/action/scope/meta identity; semantic method is factory-owned |
+| `ManagedWaitRender` | _type_ | optional managed wait terminal text and failure classification |
+| `UploadToolInputSchema` | constant | fixed `{ path: string }` input schema for `defineUploadTool` |
+| `defineAsyncOperation` | function | runtime-only start/status/wait plus configured cancel/result/artifacts definitions |
+| `bindContractAsyncOperation` | function | bind literal methods from an existing contract without creating another HTTP surface |
+| `createAsyncOperationSnapshotSchema` | function | canonical pending/running/succeeded/failed/cancelled Zod snapshot |
+| `AsyncOperationCancelResultSchema` | constant | validated accepted/already_terminal/rejected cancellation result |
+| `AsyncOperationCancelResult` | _type_ | validated cancel capability result |
+| `AsyncOperationCancelCapability` | _type_ | optional typed domain cancellation callback |
+| `AsyncOperationCapability` | _type_ | generated capability-name union |
+| `AsyncOperationStartDefinition` / `AsyncOperationFollowDefinition` | _type_ | generated runtime definition types |
+| `AsyncOperationIdentity` | _type_ | shared service/action/scope/meta identity for an operation |
+| `AsyncOperationOutputCapability` | _type_ | optional result/artifact schema plus handler |
+| `RuntimeAsyncOperationConfig` | _type_ | runtime-only descriptor configuration |
+| `RuntimeAsyncOperation` | _type_ | inferred generated definitions and schemas |
+| `ContractAsyncOperationConfig` | _type_ | literal contract method binding and handlers |
+| `ContractAsyncOperationKeys` | _type_ | literal method-key union of a bound contract |
+| `ContractAsyncOperationStartKey` | _type_ | contract keys with a declared output schema, valid for `start` |
+| `ContractAsyncOperationFollowKey` | _type_ | contract keys whose input schema type matches the selected start output |
+| `ContractAsyncOperationWaitKey` | _type_ | follow-up keys whose output schema type also matches the selected status output |
+| `composeToolLifecycle` | function | ordered composition of tool before/after phases |
+| `mountDownload` | function | raw MCP "download a URL to disk" adapter (SSRF-guarded, size-capped) |
+| `mountUpload` | function | raw MCP "upload a local file" adapter |
+| `mountWait` | function | raw MCP generic `--wait`-style polling adapter |
 | `DownloadToolConfig` | _type_ | config for `mountDownload` |
 | `UploadToolConfig` | _type_ | config for `mountUpload` |
 | `WaitToolConfig` | _type_ | config for `mountWait` |
@@ -6951,6 +7573,43 @@ handler pipeline without opening a TCP port.
 | `HandlerTestClientConfig` | _type_ | handler, contract, path prefix, scoped config and client request defaults |
 | `HandlerTestClientsConfig` | _type_ | batch helper configuration |
 | `HandlerTestTransportConfig` | _type_ | shared in-process handler, origin, prefix, client defaults and optional server handle |
+| `buildSurfaceManifest` | function | deterministic actual HTTP/tool/CLI/extension topology with versioned schema digests |
+| `assertSurfaceManifestSnapshot` | function | bounded deterministic manifest drift assertion |
+| `assertSurfaceDiscovery` | function | compare real OpenAPI/MCP/Agent/CLI discovery to a manifest |
+| `runSurfaceProbes` | function | execute explicit transport drivers with per-probe setup, teardown, timeout and cancellation |
+| `TransportObservationSchema` | constant | normalized success/validation/domain-error/aborted probe outcome |
+| `ConformanceTransport` | _type_ | explicit probe transport union |
+| `RunSurfaceProbesConfig` | _type_ | probes, drivers and diagnostic byte cap |
+| `SurfaceDiscoveryObservation` | _type_ | real OpenAPI/tool/CLI/extension discovery values |
+| `SurfaceProbe` / `SurfaceProbeDriver` | _type_ | one bounded scenario and its consumer-supplied runner |
+| `TransportObservation` | _type_ | validated normalized driver result |
+| `SurfaceManifest` / `SurfaceManifestConfig` | _type_ | deterministic surface snapshot and its inputs |
+| `SurfaceManifestOperation` / `SurfaceManifestOperationSchema` | _type_ / schema | one contract or runtime operation row |
+| `SurfaceManifestExtension` / `SurfaceManifestExtensionSchema` | _type_ / schema | declared transport extension row |
+| `SurfaceManifestSchema` | schema | complete deterministic manifest schema |
+| `SurfaceRuntimeToolDefinition` | _type_ | peer-free structural runtime-operation subset accepted by manifests |
+| `SurfaceSchemaDigestsSchema` | schema | params/input/output/multipart digest object |
+| `serializeSurfaceValue` | function | canonical versioned serialization used for deterministic digests |
+
+---
+
+## `stitchkit/files`
+
+Peer-free Bun/Node filesystem capability. Browser/contract-safe refs are also
+available from `stitchkit/contract`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createManagedFileBoundary` | function | bind one existing application-owned root for capped reads and atomic writes |
+| `ManagedFileBoundary` | _type_ | non-reopenable `read`/`write` capability over canonical relative paths |
+| `ManagedFileBoundaryConfig` | _type_ | bound root, finite limits, inspector and cleanup observer |
+| `ManagedFileRefSchema` / `ManagedFileRef` | schema / _type_ | transport-safe relative path, measured size and optional media metadata |
+| `ManagedFilePathSchema` / `ManagedFilePath` | schema / _type_ | canonical POSIX relative managed-file path |
+| `ManagedFileSource` | _type_ | bounded immutable bytes plus validated ref passed to upload callbacks |
+| `ManagedFileReadOptions` / `ManagedFileWriteOptions` | _type_ | per-operation byte cap, signal and atomic write policy |
+| `ManagedFileError` / `ManagedFileErrorCode` | class / _type_ | stable caller-safe boundary failures |
+| `ManagedFileInspector` | _type_ | bounded-prefix content inspection callback that cannot own path or size |
+| `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector input and normalized metadata-only result |
 
 ---
 
@@ -6979,20 +7638,28 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 
 ## `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.
+Server-only. Composes contract/runtime managed operations and CLI-only native
+commands into one command-line program. 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) |
+| `defineCliCommand` | function | define one Zod-typed CLI-only executable command |
 | `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) |
+| `emitResult` | function | write a pretty or compact `ToolResult` record 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`, …) |
+| `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
+| `CliCommandDefinition` | _type_ | native command definition union |
+| `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
+| `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output |
+| `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
+| `CliCommandContext` | _type_ | parsed input, global options and stdout/stderr writers |
+| `CliRunOptions` | _type_ | parsed global flags (`--json` compacts success/error records, `--wait`, …) |
 | `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
-| `CliWaitConfig` | _type_ | per-command `--wait` polling config |
+| `CliWaitConfig` | _type_ | per-command `--wait` polling config; optional `failed(result)` maps a terminal domain failure to `WAIT_FAILED` and a non-zero exit |
 | `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
 | `PollParams` | _type_ | params for `pollUntilDone` |
 | `CliWriters` | _type_ | stdout/stderr sinks for `emitResult` |