stitchkit 0.118.1 → 0.120.0

package/llms-full.txt

@@ -55,8 +55,10 @@ own, recorded as an ADR.
 | `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports, exact money and rounding tables |
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
-| `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/tools` | server | stable | the transport-neutral tool layer — registry, tool names and manifest, runtime tools, native tools, the OAuth provider, the durability engine; loads no optional peer at runtime |
 | `stitchkit/tools/mcp` | server (Bun or Node) | evolving | the canonical MCP HTTP/stdio server, schemas and typed MCP presenters; only Zod and the MCP server SDK peers |
+| `stitchkit/tools/agent` | server (Bun or Node) | evolving | `mountAgent` — a contract's operations as AI SDK tools; only Zod and the `ai` peer |
+| `stitchkit/tools/toolkit` | server (Bun or Node) | evolving | `createToolkit` — one tool set served over MCP and to an AI SDK agent; the MCP server SDK and `ai` peers |
 | `stitchkit/tools/contract` | browser + server | evolving | the shapes a tool surface speaks — async-operation contract, snapshot and cancel schemas, view-file input/output — without the runtime that serves them |
 | `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
 | `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
@@ -78,16 +80,17 @@ own, recorded as an ADR.
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/voice` | browser **and** server | evolving | the mechanics of a live voice reply — `SentenceCutter`, `speakableText`, a `SpeechQueue` that synthesises ahead and stops on interruption, the conversation phases |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
+| `stitchkit/geo/contract` | browser **and** server | evolving | the place snapshot schema, for a shared contract that stores or sends `GeoAttribution`; brings `zod` |
 | `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 63 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 65 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 63 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 65 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -99,7 +102,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 63 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 65 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -202,7 +205,10 @@ map — feature → packages:
 | `createServer` (Bun) | — (uses `Bun.serve`) |
 | `serveNode` (Node ≥ 22) | `srvx` (+ `@types/bun` dev) |
 | In-process contract tools (`stitchkit/tools/invoker`) | — |
-| MCP / agent adapters (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
+| Tool layer — registry, tool names, runtime tools (`stitchkit/tools`) | — |
+| MCP server (`stitchkit/tools/mcp`) | `@modelcontextprotocol/server` |
+| AI SDK agent tools (`stitchkit/tools/agent`) | `ai` |
+| MCP and agent toolkit (`stitchkit/tools/toolkit`) | `@modelcontextprotocol/server` `ai` |
 | Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
 | Headless Agent harness (`stitchkit/agent-runtime/harness`) | `ai` |
 | Agent coding tools (`stitchkit/agent-runtime/coding-tools`) | — |
@@ -231,15 +237,16 @@ bun add socket.io @socket.io/bun-engine    # e.g. the Socket.IO server on Bun
 ```
 
 Dynamic optional-peer adapters fail with an actionable error naming the package
-and install command. Static entrypoints such as `stitchkit/tools` fail during
+and install command. Static entrypoints such as `stitchkit/tools/mcp` fail during
 ESM resolution by naming the exact missing package; the feature-to-peer matrix
 below is the canonical install command.
 
-The combined tools entry owns MCP and AI-agent adapters, so install both runtime
-peers before importing `stitchkit/tools`:
+`stitchkit/tools` itself loads no optional peer. Install the peer of the adapter
+you import — both for `stitchkit/tools/toolkit`:
 
 ```bash
-bun add @modelcontextprotocol/server@^2 ai@^7
+bun add @modelcontextprotocol/server@^2   # stitchkit/tools/mcp
+bun add ai@^7                             # stitchkit/tools/agent
 ```
 
 Browser, HTTP-client and React entrypoints remain usable without either MCP
@@ -445,7 +452,7 @@ Both entrypoints are **evolving**.
 | the event envelope, the batch, the dispositions, the visit entry and lease schemas | the event **types**, their metadata, their labels |
 | the tab-shared outbox with reserved sequences and a short flush lease | which storage adapter (IndexedDB in a tab) |
 | the page-leave beacon that arrives, and its queued insurance copy | the session, the router, the React provider |
-| visible time, scroll milestones, `data-track` clicks, UTM first/current touch | the referrer → source map, the attribute names |
+| visible time, scroll milestones, `data-track` clicks, raw first/current touch | channel classification, click-marker names, the attribute names |
 | `dispositionTrackingBatch`, `issueVisitLease`, `activeIntervalOf`, presence | the tables, the transaction, adoption, geo, reports |
 
 ## Contract
@@ -492,7 +499,7 @@ const client = createTrackingClient<BrowserEvents>({
   deliver: (batch) => api.tracking.track(batch),   // or a socket first, HTTP as the fallback
   unloadUrl: urls.tracking.track(),
   outbox: createTrackingOutbox(indexedDbOutboxStorage('my-app-tracking')),
-  referrerMap: [{ pattern: /t\.me|telegram\.org/, source: 'telegram', medium: 'social' }],
+  clickIdParams: ['gclid', 'gbraid', 'wbraid', 'msclkid', 'yclid', 'ttclid', 'fbclid'],
   isAction: isInteractionAction,
   onVisit: (visitId) => rum.setVisit(visitId),
 })
@@ -505,6 +512,28 @@ client.track('ITEM_VIEW', { itemId, itemTitle })
 client.track('SIGN_OUT')
 ```
 
+Attribution carries observations, not a channel verdict. `utm` contains only the current URL's
+`utm_*` parameters, retaining case and whitespace up to 200 characters per field; tags without
+`utm_source` are valid. Parameter names are case-sensitive (`UTM_SOURCE` is not a tag), a repeated
+tag keeps its first value, and a whitespace-only value is kept as the fact it is. `referrer` carries
+the referring URL with credentials masked. Neither an external referrer nor a click marker creates
+campaign tags. Classify the channel on your server.
+
+Attribution belongs to the visit: the bootstrap entry carries it, and an event batch carries events
+only. Join events to their visit on the server to attribute them.
+
+`clickIdParams` is the application's ordered list of query-parameter names to recognise. There is no
+built-in list: the first configured name with a nonempty value becomes `clickId` in the touch and
+bootstrap entry. Only the name is retained, never the click ID's value: a referrer from your own site
+repeats the landing query, so the value of every configured marker in a referrer is masked too. An empty
+list collects none; names must contain 1–200 characters, and `createTrackingClient` refuses a list that
+does not. Bootstrap collects these facts even if browser storage is unavailable.
+
+`client.attribution()` returns `firstTouch` and `currentTouch`. The first is persisted for 90 days
+by default; the current is this capture's raw context, so an untagged page does not inherit an earlier
+campaign. The server owns any policy for retaining the last non-direct channel. Stored first-touch
+records carry a format version; unversioned attribution is discarded because its tags may be inferred.
+
 Two knobs match the client to your schema: `batchSize` is the contract's
 `maxEventsPerBatch` (a larger batch is a `400` the outbox can never retire),
 and `decorate` adds your `eventExtras` — a locale, an area, or the identity a
@@ -895,33 +924,55 @@ tools. Narrow it with `expose`:
 
 - `expose: ['HTTP']` — HTTP only. The endpoint never becomes a tool.
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
-- omit `expose` — all transports.
+- `expose: []` — no transport; the endpoint stays hidden.
+- omit `expose` — HTTP, MCP and AGENT; CLI is opt-in.
 
-For a curated or security-sensitive tool surface, opt into explicit tool
-exposure at the scoped factory:
+Choose an application's default surface at its scoped factory. Scope and policy
+are inferred in separate calls, so the returned endpoint types retain exact transports:
 
 ```ts
-const { defineContract } = createContractFactory<AppScope>({
-  toolExposure: 'explicit',
+const { defineContract } = createContractFactory<AppScope>().configure({
+  toolExposure: { default: ['HTTP', 'CLI'] },
 })
 ```
 
-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.
+An omitted `expose` (including `undefined`) materializes this array on the returned
+endpoint before validation. An explicit endpoint array **replaces** it, never merges
+with it: `['HTTP']` stays HTTP-only, `['MCP']` enables only MCP, and `[]` hides the
+operation everywhere. Types, HTTP routes, typed clients, tools, CLI, OpenAPI and
+transport summaries read that same materialized exposure.
+
+HTTP client methods and URL builders require a **guaranteed** HTTP transport:
+pass a literal policy array directly to `configure` so its const generic infers
+the tuple. A stored array, even with `satisfies ContractFactoryConfig`, can widen
+to `Transport[]` and contain no HTTP at runtime,
+so it does not promise an HTTP method. Optional capabilities preserve both
+possible effective exposures rather than claiming an unfiltered default tuple.
 
-Consequently, `expose: ['HTTP']` is redundant inside a factory configured with
-`toolExposure: 'explicit'`: omit it unless the explicit spelling is useful to a
-local reader. Add `MCP`, `AGENT` or `CLI` only on endpoints that intentionally
-join those surfaces.
+The same holds for an endpoint whose own type is broad, with or without a factory:
+a value annotated as `EndpointDef` or `FactoryScopedEndpoint<Scope>` carries
+`expose?: readonly Transport[]`, which may hold no HTTP, so it has no client method
+or URL. A helper that builds endpoints keeps their literal type with a const generic:
 
-Tool transports (`MCP`, `AGENT`) skip four kinds of endpoint automatically:
-`multipart` (a file upload is not a tool call),
-[`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
-a tool result cannot carry — it would serialize to `{}`),
-[`responseMeta`](./server.md#typed-json-response-metadata) (outbound HTTP
-headers have no meaning on a tool call) and `rawBody` (HTTP-only by
-construction).
+```ts
+const endpoint = <const Endpoint extends FactoryScopedEndpoint<AppScope>>(value: Endpoint) => value
+```
+
+For a curated tool surface use `toolExposure: { default: ['HTTP'] }`, then name
+tool transports only on endpoints that intentionally join them. An empty default
+is legal. Each `configure` snapshots its array independently; it does not change
+the base factory, sibling configurations or authored endpoints. The no-config
+factory and plain `defineContract` keep the default-on behaviour above.
+
+Six intrinsic HTTP-only forms intersect an **implicit factory default** with HTTP:
+`multipart`, [`rawResponse`](./server.md#raw-response-endpoints),
+[`responseMeta`](./server.md#typed-json-response-metadata), `rawBody`, streaming
+responses and `HEAD`. Under `['HTTP', 'CLI']` they receive `['HTTP']`; under
+`['CLI']` or `[]` they receive `[]`, not an implicitly reopened HTTP route.
+An **explicit** non-HTTP exposure on any of them is a definition error, not a
+silent downgrade. `safelistedBody` only changes HTTP parsing and remains
+multi-transport. A factory policy applies only to contracts authored through
+that factory, not to contracts another helper builds internally.
 
 ## Tool options (`tool`)
 
@@ -939,7 +990,7 @@ endpoint that can never be a tool (a raw response, a stream, `responseMeta`,
 
 `expose` stays outside the group: it chooses transports, HTTP included.
 Setting `tool` on an endpoint with no tool transport — `expose: ['HTTP']`, or an
-omitted `expose` under a factory with `toolExposure: 'explicit'` — throws at
+omitted `expose` under a factory with a default containing no tool transport — throws at
 definition time. The pre-0.94 top-level keys (`toolName`, `toolView`, `ui`,
 `annotations`, `mcp`) are refused by name, with where each one went.
 
@@ -3891,10 +3942,10 @@ recursive calls without retaining request state. Every invocation gets a fresh
 tool-call context and runs the same extension resolution, input/output
 validation, lifecycle, hooks and output-strip reporter as mounted tools.
 
-The dedicated entrypoint needs only the normal `stitchkit`/`zod` install. Use
-the broader `stitchkit/tools` barrel when the same program also mounts MCP or AI
-adapters and has installed their optional peers. Both imports reach the same
-runner; this is dependency isolation, not a second execution implementation.
+The dedicated entrypoint needs only the normal `stitchkit`/`zod` install, and so does
+`stitchkit/tools`, which exports the same invoker beside the rest of the tool layer. Both
+imports reach the same runner; this is dependency isolation, not a second execution
+implementation.
 
 `invoke` returns the canonical discriminated `ToolResult`, not an AI SDK or MCP
 presentation envelope. `invokeOrThrow` returns validated data and throws the
@@ -3916,9 +3967,8 @@ get the view's defaults and projected answer, which is what `collectTools` and
 An MCP-only server imports `stitchkit/tools/mcp` and installs
 `stitchkit`, `zod` and `@modelcontextprotocol/server`. The leaf's runtime and strict
 NodeNext declarations require no `ai`. It exports the existing HTTP/stdio server,
-schema policy, catalog and resource helpers; their implementation and security are shared
-with the full `stitchkit/tools` barrel. Use that full barrel when the application also
-needs its AI SDK features.
+schema policy, catalog and resource helpers, and it is the only entrypoint that does:
+`stitchkit/tools` loads no optional peer. AI SDK tools come from `stitchkit/tools/agent`.
 
 `createMcpHandler` builds a complete stateless Streamable-HTTP MCP endpoint on
 the official TypeScript SDK v2 server package. It owns server creation,
@@ -4642,7 +4692,8 @@ stitchkit ships the OAuth **protocol mechanics**; the app supplies only
 **identity and storage**. Three pieces wire it together:
 
 ```ts
-import { createMcpHandler, createMcpHttpRoute, mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
+import { mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
+import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools/mcp'
 import { createServer } from 'stitchkit/server'
 
 const resource = 'https://api.example.com/mcp'
@@ -4879,8 +4930,8 @@ export const users = defineContract({ prefix: 'users' }, {
   reshapes values inside the full schema. With `output` alone it is a slice, and
   the full result must fit that schema — `withToolView` refuses the endpoint at
   compile time when it does not.
-- **Exposure.** A view needs a tool transport. With `createContractFactory({
-  toolExposure: 'explicit' })` an endpoint without `expose` is HTTP-only, so an
+- **Exposure.** A view needs a tool transport. With `createContractFactory<Scope>().configure({
+  toolExposure: { default: ['HTTP'] } })` an endpoint without `expose` is HTTP-only, so an
   endpoint with a view names its tool transports in `expose`.
 - **What it refuses.** `defineContract` rejects a view on an endpoint with no
   tool transport or no full `output`, on a raw, `rawBody`, multipart,
@@ -4903,7 +4954,7 @@ see [Agent application runtime](./agent-runtime.md).
 `generateText` / `streamText`:
 
 ```ts
-import { mountAgent } from 'stitchkit/tools'
+import { mountAgent } from 'stitchkit/tools/agent'
 import { generateText } from 'ai'
 
 const tools = mountAgent(usersService, { context: { userId: 'agent-1' } })
@@ -4987,7 +5038,9 @@ result. Optional presentation callbacks map that result to MCP content and AI
 SDK model output without coupling the handler to either SDK:
 
 ```ts
-import { createMcpHandler, defineRuntimeTool, mountAgent } from 'stitchkit/tools'
+import { defineRuntimeTool } from 'stitchkit/tools'
+import { createMcpHandler } from 'stitchkit/tools/mcp'
+import { mountAgent } from 'stitchkit/tools/agent'
 import { z } from 'zod'
 
 const renderPreview = defineRuntimeTool({
@@ -5353,7 +5406,8 @@ hooks. The built-in `mountViewFile`, `mountWait`, `mountDownload` and
 media helper fetches with SSRF and path-traversal defenses:
 
 ```ts
-import { createMcpHandler, mountViewFile } from 'stitchkit/tools'
+import { mountViewFile } from 'stitchkit/tools'
+import { createMcpHandler } from 'stitchkit/tools/mcp'
 
 const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
@@ -5461,16 +5515,16 @@ identical. Write the handler once; it serves every surface.
 > **Maturity: evolving.** This surface is still finding its shape and may be
 > redefined in any minor release — always with a `### ⚠️ Breaking changes` entry
 > and a migration section, never silently. If your application already owns the
-> conversation loop, `mountAgent` from `stitchkit/tools` is the stable path.
+> conversation loop, `mountAgent` from `stitchkit/tools/agent` is the direct path.
 
 `stitchkit/agent-runtime` is the server-only, opinionated layer above
 `mountAgent`. Use it when the application wants Stitchkit to own conversation
 mechanics: durable acceptance, history projection, the AI SDK stream loop,
 checkpoints, keyed interruption, terminal commit and stable application events.
 
-If the application already owns that loop, continue importing `mountAgent` from
-`stitchkit/tools`. `stitchkit/tools` does not depend on this entrypoint at all;
-this entrypoint uses the tool executor from it, but pulls no MCP peer, so
+If the application already owns that loop, import `mountAgent` from
+`stitchkit/tools/agent`. Neither `stitchkit/tools` nor `stitchkit/tools/agent` depends on
+this entrypoint; this entrypoint uses the tool executor, but pulls no MCP peer, so
 choosing `mountAgent` alone costs you nothing from here.
 
 UI and shared DTO code must import canonical records and delivery validation from
@@ -5494,12 +5548,8 @@ persistence, event sinks and every Node context dependency.
 bun add stitchkit ai zod
 ```
 
-`mountAgent` from `stitchkit/tools` — used in the composition below — additionally
-needs the MCP peer, which that entrypoint imports statically:
-
-```sh
-bun add @modelcontextprotocol/server
-```
+`mountAgent` from `stitchkit/tools/agent` — used in the composition below — needs no
+peer beyond `ai`.
 
 OpenRouter is isolated so other runtime users do not resolve its package:
 
@@ -5520,7 +5570,8 @@ import {
   defineModelRegistry,
 } from 'stitchkit/agent-runtime'
 import { openRouterProvider } from 'stitchkit/agent-runtime/openrouter'
-import { composeToolLifecycle, mountAgent } from 'stitchkit/tools'
+import { composeToolLifecycle } from 'stitchkit/tools'
+import { mountAgent } from 'stitchkit/tools/agent'
 
 const protocol = defineAgentProtocol({
   context: z.object({ userId: z.string() }),
@@ -7234,7 +7285,8 @@ import {
   createAgentHarnessFileResources,
   createHeadlessAgentHarness,
 } from 'stitchkit/agent-runtime/harness';
-import { composeToolLifecycle, mountAgent } from 'stitchkit/tools';
+import { composeToolLifecycle } from 'stitchkit/tools';
+import { mountAgent } from 'stitchkit/tools/agent';
 
 const resources = createAgentHarnessFileResources({
   roots: [{ id: 'guide', kind: 'instruction', path: instructionRoot }],
@@ -7258,8 +7310,8 @@ compose your authorization with the run's `toolFenceLifecycle` by `composeToolLi
 fence rejects a call from a run that no longer owns the conversation, and it must run exactly
 once. Every mount option remains available, including registry, runtime tools, extension,
 coercion, output stripping, hooks and durability, and the callback may be async. The same callback
-still accepts arbitrary typed AI SDK tools and prepareStep. `stitchkit/tools` needs the same `ai` and
-`@modelcontextprotocol/server` peers as any `mountAgent` use; the base harness stays AI-only.
+still accepts arbitrary typed AI SDK tools and prepareStep. `mountAgent` comes from `stitchkit/tools/agent`, which needs only the `ai` peer the
+harness already has; the base harness stays AI-only.
 The resource reader is explicitly selected: filtered allowlists do not gain tools merely
 because a loader exists. Root IDs, kinds, provenance and limits are unchanged.
 
@@ -8612,7 +8664,7 @@ Storage is process-durable, without a power-loss/fsync guarantee.
 
 ```ts
 import { createSandboxCodingTools } from 'stitchkit/agent-runtime/sandbox';
-import { mountAgent } from 'stitchkit/tools';
+import { mountAgent } from 'stitchkit/tools/agent';
 
 const tools = mountAgent([], {
   runtimeTools: createSandboxCodingTools(handle, {
@@ -9995,7 +10047,7 @@ types; the package keeps its required dependencies separate from optional SDKs.
 CLI runtime tools use the one runtime-tool declaration: identity, input and output
 schemas, handler, and explicit CLI exposure. SDK presenters are the adapter's extension
 of that declaration (the fourth type argument of `RuntimeToolDefinitionWithOutput`, or
-`defineRuntimeTool` in `stitchkit/tools`), which requires the corresponding peers. A typed
+`defineRuntimeTool` in `stitchkit/tools`), whose presenter types name the corresponding SDKs. A typed
 definition returned by `defineRuntimeTool` or `createRuntimeToolFactory` can be
 passed directly to both CLI and SDK mounts.
 
@@ -14872,8 +14924,9 @@ fixture's transitive dependency.
 
 That includes `stitchkit/tools/invoker`: a minimal packed consumer imports it
 without MCP/AI peers and executes validation, output projection and normalized
-errors on Bun and Node. The broader `stitchkit/tools` barrel deliberately keeps
-the adapter peer budget.
+errors on Bun and Node, and so does `stitchkit/tools`, which loads no optional peer at
+runtime. The adapters keep their peer budgets on their own subpaths:
+`stitchkit/tools/mcp`, `stitchkit/tools/agent` and `stitchkit/tools/toolkit`.
 
 Beside the matrix, one case is about the ARTIFACT rather than the inventory: a
 program that injects the Socket.IO peer loaders is bundled and started in a
@@ -15102,10 +15155,7 @@ signal and deadline. Bind its process lifecycle with the truthful close-only
 sibling from `stitchkit/tools`:
 
 ```ts
-import {
-  bindStdioProcessSignals,
-  createStdioMcpServer,
-} from 'stitchkit/tools'
+import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools/mcp'
 
 const stdio = await createStdioMcpServer(config)
 const binding = bindStdioProcessSignals(stdio, {
@@ -16950,7 +17000,45 @@ const attribution = await geo.resolve(requestIp);
 `resolve` returns `null` for invalid, loopback, private, link-local and otherwise
 non-public addresses without querying the reader. A database miss or lookup
 failure also returns `null`; `onError` receives operational failures. A result
-may include country, region, city, postal, coordinates, timezone and ASN fields.
+is a sparse `GeoAttribution`: absent facts have no own property, not `null` or
+an own `undefined` value. City and ASN can be present independently. The default
+mapper preserves the complete City + ASN place snapshot:
+
+| Fields | Meaning |
+|--------|---------|
+| `continentCode`, `continentName`, `continentGeonameId` | continent code, English name and GeoNames identifier |
+| `countryCode`, `countryName`, `countryGeonameId` | the country the database locates the address in; absent when the record locates none |
+| `registeredCountryCode`, `registeredCountryName`, `registeredCountryGeonameId` | the country the address block is registered to, a separate fact |
+| `regionCode`, `regionName`, `regionGeonameId` | first subdivision |
+| `city`, `cityGeonameId`, `postalCode` | city and postal facts; no city is required |
+| `latitude`, `longitude`, `timezone`, `accuracyRadiusKm` | coordinates, timezone and accuracy radius in kilometres; zero is a value |
+| `autonomousSystemNumber`, `autonomousSystemOrganization` | finite autonomous system number and organisation |
+| `localizedNames` | every available language under optional `continent`, `country`, `registeredCountry`, `region` and `city` dictionaries |
+
+No locale is synthesised: without English names, localized dictionaries make a
+meaningful result, but `countryName`, `regionName` or `city` stays absent. The
+located country is never inferred from the registered one — an application that
+wants a country for every address chooses `countryCode ?? registeredCountryCode`
+itself, knowing which fact it used. Empty localized groups are omitted. Each field
+is validated on its own by the schema: text is nonempty, GeoNames identifiers and
+`accuracyRadiusKm` are nonnegative safe integers, latitude and longitude are in
+range. A malformed field is omitted without erasing the other valid facts. Unknown
+vendor fields are not projected.
+
+A snapshot carries every language the database has: with the eight GeoLite2
+languages in all five groups it is 1–1.5 KB of JSON. An application that stores
+one per visit and needs fewer languages maps the result to its own shape.
+
+`GeoAttributionSchema` is the strict, readonly Zod owner of the DTO. It lives in
+the browser-safe `stitchkit/geo/contract`, so a shared contract validates a stored
+or transported snapshot without the server-only resolver. Every field is optional
+and readonly; use `.unwrap()` before composing the underlying object schema. The
+mapper copies localized dictionaries, so later reader mutations do not change a
+snapshot. An empty or unrecognised record returns `null`.
+
+An explicit `map` callback receives the raw reader result and owns its
+answer. The resolver does not apply `GeoAttributionSchema` after a custom mapper,
+strip its application fields or replace its returned object.
 
 When a reload succeeds, new lookups move to the new generation immediately.
 The previous reader closes only after its in-flight lookups finish.
@@ -17061,6 +17149,155 @@ charts, no merged cells and no streaming: an application that needs them takes a
 
 # Upgrading stitchkit
 
+## Released migration: 0.120.0
+
+### tools-barrel-subpaths
+
+**Who must act:** code importing the MCP server, `mountAgent` or `createToolkit` from
+`stitchkit/tools`. Imports of the registry, tool names, manifest, runtime and native tools, the
+invoker, the OAuth provider and the durability engine stay where they are.
+
+`stitchkit/tools` now loads no optional peer, so an application without
+`@modelcontextprotocol/server` and `ai` can import it. Move each adapter import to its subpath:
+
+```ts
+// before
+import { createMcpHandler, listToolNames, mountAgent } from 'stitchkit/tools'
+import { createToolkit } from 'stitchkit/tools'
+// after
+import { listToolNames } from 'stitchkit/tools'
+import { createMcpHandler } from 'stitchkit/tools/mcp'
+import { mountAgent } from 'stitchkit/tools/agent'
+import { createToolkit } from 'stitchkit/tools/toolkit'
+```
+
+| Names | New subpath | Peers it needs |
+|-------|-------------|----------------|
+| `createMcpHandler`, `createMcpHttpRoute`, `buildMcpServer`, `mountMcp`, `mountMcpResource`, `validateMcpSchemas`, `createStdioMcpServer`, `bindStdioProcessSignals`, `inlineMcpAppBundle`, `mcpCatalogMeta`, `readMcpCatalogStamp`, `EXT_APPS_BUNDLE_PLACEHOLDER`, `MCP_CATALOG_META_KEY`, `RESOURCE_MIME_TYPE` and their config types, `McpServer`, `IncompatibleSchemaPolicy`, `McpSchemaValidationConfig` | `stitchkit/tools/mcp` | `@modelcontextprotocol/server` |
+| `mountAgent`, `AgentMountConfig`, `AgentContext` | `stitchkit/tools/agent` | `ai` |
+| `createToolkit`, `Toolkit` | `stitchkit/tools/toolkit` | `@modelcontextprotocol/server`, `ai` |
+
+The move is mechanical: `bunx stitchkit upgrade --from 0.119.0` lists every import it touches, and
+`tsc` names any name still imported from `stitchkit/tools`. Behaviour is unchanged.
+
+## Released migration: 0.119.0
+
+### factory-default-exposure
+
+**Who must act:** code passing arguments to `createContractFactory`, depending on its fixed-string
+policy types or the renamed exposure types, calling HTTP clients of endpoints typed as the broad
+`EndpointDef` / `FactoryScopedEndpoint`, or declaring multipart endpoints with non-HTTP exposure or
+tool options.
+
+Scope and default transports are inferred separately. Replace the constructor configuration:
+
+```ts
+// before
+const { defineContract } = createContractFactory<AppScope>({ toolExposure: 'explicit' })
+// after: preserve the same curated HTTP-only default
+const { defineContract } = createContractFactory<AppScope>().configure({
+  toolExposure: { default: ['HTTP'] },
+})
+```
+
+To deliberately expose ordinary operations through HTTP and CLI, choose `default: ['HTTP', 'CLI']`
+and remove redundant matching endpoint arrays. Explicit arrays replace, rather than extend, the
+default. Raw responses, multipart, raw bodies, response metadata, response streams and HEAD get only
+HTTP from implicit defaults; a CLI-only or empty default leaves them hidden on every transport.
+Explicit contradictions fail at definition; remove non-HTTP transports and tool options from multipart
+endpoints rather than relying on their silent omission from tool catalogs.
+
+`ExplicitToolExposureEndpoints` and `ExplicitScopedDefineContract` are renamed
+`ConfiguredToolExposureEndpoints<Endpoints, Defaults>` and `ConfiguredScopedDefineContract<Scope, Defaults>`:
+they describe materialization from any default tuple, their second generic, and HTTP-only when it is
+omitted.
+An optional or conditional endpoint override remains an alternative in the returned type. It does not
+guarantee an HTTP client method unless every alternative includes HTTP.
+
+HTTP clients and URL builders no longer assume a widened `Transport[]` contains
+HTTP. Pass the literal array directly to `configure` when the HTTP surface is static;
+its const generic infers the tuple. An annotation or `satisfies ContractFactoryConfig`
+on a separately stored configuration does not preserve the tuple by itself.
+Optional capabilities likewise retain the filtered alternative in endpoint types.
+
+The rule reads the endpoint's type, with or without a factory. An endpoint returned by a helper
+annotated `(): EndpointDef` or `(): FactoryScopedEndpoint<Scope>`, or holding a stored
+`readonly Transport[]`, has no HTTP client method or URL, because that type allows an exposure
+without HTTP. Keep the literal type with a const generic helper:
+
+```ts
+// before
+const read = (): FactoryScopedEndpoint<AppScope> => ({ method: 'GET', path: '/', desc: 'Read', output })
+// after
+const endpoint = <const Endpoint extends FactoryScopedEndpoint<AppScope>>(value: Endpoint) => value
+const read = () => endpoint({ method: 'GET', path: '/', desc: 'Read', output })
+```
+
+If every endpoint already has an explicit array, removing the constructor configuration alone also
+preserves exposure. [ADR 0283](../decisions/0283-factory-default-exposure-is-materialized-by-capability.md).
+
+Search patterns: `createContractFactory`, `toolExposure`, `ExplicitToolExposureEndpoints`,
+`ExplicitScopedDefineContract`, `: EndpointDef`, `: FactoryScopedEndpoint`, and multipart endpoints
+with `expose` or `tool`.
+
+### geo-full-snapshot
+
+**Who must act:** code comparing `stitchkit/geo` results by equality, parsing them with a strict
+schema of its own, mutating a returned `GeoAttribution`, or relying on empty labels.
+
+The default mapper returns everything the City + ASN record states: continent, the registered
+country as its own fields, GeoNames identifiers, `accuracyRadiusKm` and `localizedNames` with every
+language. A record that used to give `{ city: 'Bangkok' }` now also gives
+`localizedNames: { city: { en: 'Bangkok' } }`.
+
+```ts
+// before: an application's copy of the shape
+const StoredGeo = z.strictObject({ city: z.string().optional(), countryCode: z.string().optional() })
+// after: the framework's schema, importable from shared code
+import { GeoAttributionSchema } from 'stitchkit/geo/contract'
+```
+
+`GeoAttribution` is readonly to its nested dictionaries; copy before changing a field. Empty labels
+and coordinates outside ±90° / ±180° are omitted. The located country never borrows the registered
+one; write `countryCode ?? registeredCountryCode` where a country for every address is wanted.
+
+Search pattern: `stitchkit/geo`, `mapGeoIpRecord`, `GeoAttribution`, `resolve(`.
+
+### raw-tracking-attribution
+
+**Who must act:** code passing `referrerMap` or `hostname` to `resolveAttribution`, importing
+`ReferrerRule` or `parseReferrer`, relying on inferred, lowercased or retained UTM, or reading `utm`
+from an event batch on the server.
+
+Tracking sends raw attribution facts. Remove `referrerMap`, `ReferrerRule`, `parseReferrer` and the
+resolver's `hostname`; `TrackingPageContext` and `browserTrackingHost()` no longer require or return
+`hostname` either. Classify `referrer` and campaign tags on your server instead. Configure the
+click-marker names your application recognises:
+
+```ts
+// before
+createTrackingClient({ ...config, referrerMap: [{ pattern: /search\.example/, source: 'search', medium: 'organic' }] })
+// after
+createTrackingClient({ ...config, clickIdParams: ['gclid', 'msclkid'] })
+```
+
+Bootstrap and both touches carry `clickId`, the configured parameter's name without its value. Extend
+your bootstrap DTO or stored attribution shape if you previously copied the framework's fields. No
+marker is recognised unless configured. Real UTM retains its case and whitespace, and a tag without
+`utm_source` is no longer discarded. Keep any channel normalisation in the server classifier.
+
+`currentTouch` is the current capture's context; an untagged entry has no campaign even when a prior
+one did. Implement last-non-direct retention on the server if required. First-touch storage uses a
+versioned format and resets unversioned records once, because inferred and real tags in those records
+cannot be distinguished. Without browser storage, current landing facts still reach bootstrap.
+
+An event batch (`TrackEventsRequest`, the `request` schema of `createTrackingSchemas`) carries
+`buildId` and `events` only. A server that read `request.utm` attributes events through their visit:
+store the bootstrap entry's `utm`, `referrer` and `clickId` with the visit and join on `visitId`.
+
+Search pattern: `referrerMap`, `ReferrerRule`, `parseReferrer`, `resolveAttribution`, `currentTouch`,
+`request.utm`, `input.utm`.
+
 ## Released migration: 0.118.0
 
 ### telegram-due-cursor
@@ -22347,11 +22584,11 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
+| `ConfiguredScopedDefineContract` | _type_ | scoped authoring parameterized by the exact default transport tuple; explicit endpoint exposure replaces it |
+| `ConfiguredToolExposureEndpoints` | _type_ | endpoint map with materialized exposure; a second generic selects defaults (HTTP when omitted), preserving explicit, optional and conditional overrides |
 | `createContractFactory` | function | a `defineContract` whose scope — on the contract **and** on any endpoint override — is required and held to your union, retaining 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']` |
+| `ContractFactoryConfig` | _type_ | configuration passed to `createContractFactory<Scope>().configure({ toolExposure: { default: [...] } })`; the constructor itself takes no arguments |
+| `ContractFactoryToolExposure` | _type_ | `default: readonly Transport[]`; omitted endpoint exposure uses the immutable policy snapshot, intersected with intrinsic HTTP-only capabilities |
 | `FactoryScopedEndpoint` | _type_ | an endpoint authored through the factory — its own `scope` override is held to the same union |
 | `ScopedContractDef` | _type_ | a factory-defined contract whose `meta.scope` is the required concrete literal |
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns — endpoint `scope` overrides join the union |
@@ -23612,8 +23849,8 @@ Separate optional evolving Bun/OpenTUI package over a caller-composed headless h
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `defineAgentTui` | function | typed config for title/theme/status rows, model catalog, context, commands, runtime bundle and optional host-evidenced recovery policy; the default never requeues acquired effects |
-| `runAgentTui` | function | start one fresh durable conversation and terminal controller, recover durable work and publish its authenticated local session; `initialConversationId` is an explicit resume override |
+| `defineAgentTui` | function | typed config for title, `theme` (a `TerminalPalette` override) and `themeMode`, status rows, model catalog, context, commands, runtime bundle and optional host-evidenced recovery policy; the default never requeues acquired effects |
+| `runAgentTui` | function | start one fresh durable conversation and terminal controller, recover durable work and publish its authenticated local session; `initialConversationId` is an explicit resume override; it closes the session and exits the process on Ctrl-C and every signal OpenTUI catches unless `exitSignals: []` |
 | `defineTuiCommand` / `resolveTuiCommand` | function | typed composable slash-command registry; unknown slash input remains an ordinary model prompt |
 | `createAgentTuiController` | function | single admission, selection, approval, interruption and conversation-switch owner over the harness |
 | `startAgentTuiSessionHost` / `createAgentTuiClient` | function | authenticated mode-`0600` Unix-socket host/client for status, submit and interrupt through that controller |
@@ -23622,7 +23859,7 @@ Separate optional evolving Bun/OpenTUI package over a caller-composed headless h
 | `defaultAgentTuiStatusLine` / `AgentTuiStatusLineFormatter` | function / _type_ | terminal-native default rows and a host formatter over model capacity, durable snapshot, activity, workspace and local identities; `statusLine: false` hides the rows |
 | `createAgentTuiDiagnosticRecorder` / `AgentTuiDiagnosticEventSchema` | function / schema | bounded per-session metadata journal that rejects prompt, reasoning, tool-input and provider-cause payloads before disk admission |
 
-The `stitchkit-agent` binary loads `stitchkit.agent.ts` by default and also exposes `sessions`,
+The `stitchkit-agent` binary runs React's production build unless `NODE_ENV` says otherwise and loads `stitchkit.agent.ts` by default and also exposes `sessions`,
 `status`, `send` and `interrupt`. `--workspace` addresses a host outside the caller's cwd,
 `send --idempotency-key` accepts caller-owned retry identity, and `interrupt` defaults to the
 active run returned by `status`. Session descriptors and sockets are local control credentials,
@@ -23645,6 +23882,65 @@ Renderer-neutral state only. This entrypoint imports neither React/OpenTUI nor t
 | `createTerminalCommandPalette` / `terminalCommandMatches` | function | bounded command filtering and keyboard selection over a collision-validated registry |
 | `resolveExactTerminalCommand` / `validateTerminalCommands` | function | exact dispatch and fail-closed name/alias validation |
 | `createTerminalOperationState` / `reduceTerminalOperationState` | function | confirmation and single-pending-operation lifecycle |
+| `createTerminalTable` / `reduceTerminalTable` / `projectTerminalTable` | function | live table: typed columns, rows validated on entry, sort with key tie-break and missing values last, tree expansion pruned to present rows, filter on displayed text, selection kept across data; a row's `tone` and a column's `tone(value, row)` colour state |
+| `layoutTerminalTableColumns` / `formatTerminalTableCell` / `visibleTerminalTableRows` / `terminalTableTreePrefix` | function | fixed and flexible column widths, `—` for missing values, the virtualized window, tree indentation |
+| `createTerminalList` / `reduceTerminalList` / `visibleTerminalListLines` | function | picker with sections, fuzzy query with title highlight ranges, multi-select, disabled items and "more above/below" counts |
+| `createTerminalForm` / `reduceTerminalForm` / `readTerminalForm` / `terminalFormFieldsFromJsonSchema` | function | typed fields (text, secret, number, integer, boolean, choice, JSON) from a JSON Schema, relative text edits, validation on leave and submit |
+| `createTerminalTabs` / `reduceTerminalTabs` | function | tabs with badges, wrap-around movement, digit selection and reconcile that keeps the selected tab |
+| `createTerminalNavigation` / `reduceTerminalNavigation` / `terminalBreadcrumbs` | function | screen stack keeping each level's state, root never popped |
+| `createTerminalFocus` / `reduceTerminalFocus` | function | focus ring plus layers that take the keyboard and give it back |
+| `createTerminalNotices` / `reduceTerminalNotices` / `nextTerminalNoticeExpiry` | function | bounded toasts on a caller clock, replaced by id |
+| `createTerminalTimeSeries` / `appendTerminalSample` / `sampleTerminalTimeSeries` | function | time window bounded by duration and sample count, value-in-force sampling with explicit gaps |
+| `terminalBrailleChart` / `terminalSparkline` / `terminalTimeAxis` / `terminalChartScale` | function | multi-series braille line or area chart as toned runs, sparkline, time axis |
+| `terminalMeter` / `layoutTerminalMeterGrid` | function | eighth-block bar toned by thresholds, unmeasured as muted; column-major core grid |
+| `terminalProgress` / `terminalSpinnerFrame` / `terminalIndeterminateBlock` / `formatTerminalDuration` | function | ratio, rate and ETA only when knowable; spinner frames; indeterminate bar; elapsed time |
+| `defineTerminalKeymap` / `matchTerminalKey` / `fitTerminalKeyHints` | function | conflict-checked bindings that both answer keys and draw a footer fitted to the width |
+| `terminalTableKeymap` / `terminalTableKey` / `terminalTabsKeymap` / `terminalTabsKey` | function | htop-style table bindings and tab bindings as keymaps |
+| `matchTerminalSearch` / `searchTerminalItems` / `terminalHighlightRuns` | function | multi-word fuzzy match with ranges, stable ranking, highlight runs |
+| `sanitizeTerminalText` / `terminalTextWidth` / `truncateTerminalText` / `fitTerminalText` / `wrapTerminalText` | function | strip escape and control sequences; measure, cut, pad and wrap by terminal cells |
+| `terminalTextEdit` / `applyTerminalTextEdit` | function | one-line edits as relative actions, so fast input is never lost |
+| `terminalJsonLines` / `layoutTerminalDetails` | function | toned, sanitized JSON lines; aligned key/value pairs |
+| `terminalPalettes` / `resolveTerminalPalette` / `TerminalPalette` / `TerminalTone` | value / function / _type_ | one semantic palette (surfaces plus `primary`, `muted`, `accent`, `success`, `warning`, `danger`) for dark and light terminals |
+| `terminalLabelsEn` / `terminalLabelsRu` / `TerminalLabels` | value / _type_ | every word the widgets draw |
+
+### `stitchkit-tui/widgets`
+
+OpenTUI React widgets over the core state. React, `@opentui/core` and `@opentui/react` are peers;
+this entrypoint never loads `stitchkit`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `TerminalAppShell` / `TerminalPanel` / `TerminalStatusBar` / `TerminalKeyHints` | component | breadcrumbs, status lines, body, fitted key hints and toast overlay; titled rounded panels with a focus frame |
+| `TerminalTable` | component | virtualized live table with header sort marks, tree, filter line and htop keys; row and cell tones in the palette, bold or dim where colour is missing |
+| `terminalToneAttributes` | function | the text attribute that carries a tone without colour: `danger` and `warning` bold, `muted` dim |
+| `TerminalList` | component | sections, fuzzy search line with highlights, `›` cursor, meta, badges, multi-select, description |
+| `runTerminalApp` / `RunTerminalAppOptions` / `RunningTerminalApp` | function / _type_ | start an application: renderer, theme and labels providers, the error boundary, and an exit with 128 + signal after `onClose` on Ctrl-C and every signal OpenTUI catches — a closed window leaves no orphan |
+| `TerminalErrorBoundary` / `TERMINAL_EXIT_SIGNALS` / `TerminalExitSignal` | component / value / _type_ | draws a render error and its stack in place of the screen, where OpenTUI's own boundary renders nothing under production React |
+| `TerminalForm` | component | fields edited in place, cycling choices, masked secrets, inline errors; a form without fields says so and submits `{}` on Enter |
+| `TerminalTextView` / `TerminalJsonView` | component | pager over sanitized wrapped text or toned JSON |
+| `TerminalMeter` / `TerminalMeterGrid` / `TerminalChart` / `TerminalSparkline` | component | htop meters and core grid; btop braille charts with axis |
+| `TerminalTabs` / `TerminalDialog` / `TerminalSpinner` / `TerminalProgressBar` / `TerminalAsyncView` / `TerminalDetails` / `TerminalNotices` / `TerminalHelp` | component | views, confirmation, loading, progress, async states, details, toasts, key help |
+| `TerminalThemeProvider` / `useTerminalPalette` / `useTerminalThemeMode` | component / hook | palette from the terminal's reported background (`auto`) or a fixed mode |
+| `TerminalLabelsProvider` / `TerminalFocusProvider` / `useTerminalFocused` | component / hook | product language and shared focus |
+
+The `stitchkit-tui-gallery` binary shows every widget live.
+
+### `stitchkit-tui/build`
+
+Build-time only; imports Bun and no React.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `compileTerminalApp` / `CompileTerminalAppOptions` | function / _type_ | one standalone executable for any Bun compile target, from any machine, with React's production build defined |
+| `terminalNativePlugin` / `TerminalNativePluginOptions` | function / _type_ | the `Bun.build` plugin behind it: the target's `@opentui/core-<os>-<arch>` at the pinned version from the registry, verified against `bun.lock`; other platforms' packages throw; musl refused |
+| `terminalNativeTarget` / `TerminalNativeTarget` | function / _type_ | the native package a compile target needs |
+
+### `stitchkit-tui/testing`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `renderTerminalTest` / `TerminalTestScreen` / `TerminalTestOptions` | function / _type_ | a screen inside the kit's providers on a test terminal; `press`, `type`, `burst`, `advance`, `waitForText`, `resize` run inside React's `act` and wait out a lone Esc |
+| `TerminalTestKey` / `TerminalTestModifiers` | _type_ | the mock input's key names and modifiers |
 
 ## `stitchkit/agent-runtime/sqlite/node`
 
@@ -23754,57 +24050,25 @@ SDK, `ai`, or other optional tool peers, so it is safe in a thin CLI bundle.
 
 ## `stitchkit/tools`
 
-Server-only. Turns contracts into MCP and AI-agent tools. MCP server surfaces
-need the `@modelcontextprotocol/server` v2 peer; MCP hosts/tests use the separate
-`@modelcontextprotocol/client` package. Agent surfaces need the `ai` peer.
-
-Framework-owned MCP tools advertise the exact declared output schema and return
-the validated value unchanged as `structuredContent`, including arrays, scalars
-and `null`. Tools without an output contract advertise and return no structured
-payload.
+Server-only, and imported without any optional peer: the transport-neutral tool layer —
+the registry, tool names and manifest, runtime tools, native tools, the invoker, the OAuth
+provider and the durability engine. An application that serves its operations over HTTP and
+CLI lists its tool names here with neither MCP nor the AI SDK installed. The adapters that
+need a peer have their own subpaths: [`stitchkit/tools/mcp`](#stitchkittoolsmcp) (the MCP
+server SDK), [`stitchkit/tools/agent`](#stitchkittoolsagent) (the `ai` peer) and
+[`stitchkit/tools/toolkit`](#stitchkittoolstoolkit) (both). → ADR 0284.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `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) |
-| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service; failed executions reject through the SDK tool-error channel with a safe typed envelope, while successful output is never classified by field name — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
 | `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; use peer-free `stitchkit/tools/invoker`, or the full `stitchkit/tools` adapter barrel — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
-| `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
+| `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner; use `stitchkit/tools/invoker` or `stitchkit/tools`, both peer-free — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
 | `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 contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
 | `listContractToolNames` | function | the same listing straight from contracts — no handlers or stub services needed |
 | `describeToolCatalog` | function | inspect the exact model-facing names, source identities, schema byte sizes and deferred state; an explicit total byte budget fails closed |
 | `ToolCatalogConfig` / `ToolCatalogEntry` | _type_ | catalog source, transport, optional explicit schema budget and one inspectable result row |
-| `McpHandlerConfig` | _type_ | server surface plus stateless HTTP transport config |
-| `McpHttpConfig` | _type_ | HTTP auth, protected-resource, legacy-era and security options |
-| `McpHttpHandler` | _type_ | framework-owned `{ fetch(request), close() }` lifecycle |
-| `McpHttpSecurityConfig` | _type_ | Fetch-boundary Host and Origin allowlists |
-| `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 |
-| `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` |
-| `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 |
 | `RuntimeToolDefinition` | _type_ | heterogeneous registration of pathless operations in `runtimeTools: [...]`; an inline handler is contextually typed by the parsed object, a definition constructed with its own schema registers unchanged, and the runner validates input before the handler |
 | `RuntimeToolDefinitionBase` | _type_ | common name, identity, input, exposure and MCP metadata fields |
 | `RuntimeToolDefinitionWithOutput` | _type_ | the one neutral construction: identity, schemas and a handler typed from them; the fourth type argument names the adapter's `present` extension (`RuntimeToolPresenters<…>` here, `RuntimeMcpToolPresenters<…>` on `stitchkit/tools/mcp`, none by default) |
@@ -23830,11 +24094,8 @@ 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` |
-| `AgentMountConfig` | _type_ | config for `mountAgent` |
 | `AgentToolRegistry` / `AgentToolRegistryBuilder` / `AgentToolRegistryInput` | _type_ | the composed runtime surface and its builder: declared defaults, `replace`/`disable` by name, and the exact `{ tools, names }` a mount receives |
 | `defineToolRegistry` | function | compose runtime tools over one declared default set; an unknown `replace`/`disable` name is refused instead of silently leaving the default in place |
-| `AgentContext` | _type_ | the context merged into agent tool handlers |
-| `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
 | `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
 | `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
 | `ToolExecutionControlReason` | _type_ | internal managed-execution stop reason: stale run or requested interruption |
@@ -23866,7 +24127,6 @@ payload.
 | `NonPortableFormat` | _type_ | one `{ path, format }` portability finding |
 | `PORTABLE_JSON_SCHEMA_FORMATS` | constant | portable-format baseline used by MCP validation |
 | `ToolNameEntry` | _type_ | one `listToolNames` row — `{ kind, name, service, method, transports }` |
-| `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
 | `McpMediaContent` | _type_ | a multimodal MCP content item |
 
 ### Native tools
@@ -23903,7 +24163,7 @@ runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 | `AsyncOperationOutputCapability` | _type_ | optional result/artifact schema plus handler |
 | `RuntimeAsyncOperationConfig` | _type_ | runtime-only descriptor configuration |
 | `RuntimeAsyncOperation` | _type_ | inferred generated definitions and schemas |
-| `AsyncOperationContractConfig` | _type_ | canonical contract config where start returns the operation id; optional `expose` names the transports per capability, because this contract is built inside the framework and never passes through a consumer's `toolExposure: 'explicit'` factory |
+| `AsyncOperationContractConfig` | _type_ | canonical contract config where start returns the operation id; optional `expose` names the transports per capability, because this contract is built inside the framework and never passes through a consumer's configured factory |
 | `AsyncOperationContractWithStartOutputConfig` | _type_ | canonical contract config with an application start envelope and typed id extractor |
 | `DefinedAsyncOperationContract` | _type_ | generated contract, capability keys, schemas and parsed adapters |
 | `ContractAsyncOperationConfig` | _type_ | literal contract method binding and handlers |
@@ -23970,6 +24230,77 @@ mountAgent(services, { durability: (toolCallId) => myLedgerFor(toolCallId) });
 | `AgentToolError` | class | the model-safe envelope a failed agent tool throws |
 | `isAgentToolError` | function | brand check for it — a consumer running its own loop no longer parses the message |
 
+### Introspection & internals
+
+Advanced building blocks — the shared machinery the mounts are built on.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `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 | 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_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
+| `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
+| `ToolSurfaceProjection` | _type_ | the one readonly `{ services?, runtimeTools? }` container shared by full, MCP-only and introspection surfaces (`buildToolManifest`, `listToolNames`, `summarizeTransports` take `ToolSurfaceProjection<RuntimeToolDefinition>`) |
+| `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
+| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments, including object guards restored from JSON Schema; arbitrary transform pipes stay untouched; throws a `ZodError` naming the field when a union that keeps a string member receives a string that parses to an array its array member accepts |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; 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 |
+
+---
+
+## `stitchkit/tools/mcp`
+
+Server-only, and the one place the MCP server is exported. Its runtime and strict NodeNext
+declarations require Zod and the `@modelcontextprotocol/server` v2 peer, with no AI SDK peer;
+MCP hosts and tests use the separate `@modelcontextprotocol/client` package.
+
+Framework-owned MCP tools advertise the exact declared output schema and return
+the validated value unchanged as `structuredContent`, including arrays, scalars
+and `null`. Tools without an output contract advertise and return no structured
+payload. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphandler).
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `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) |
+| `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)) |
+| `McpHandlerConfig` | _type_ | server surface plus stateless HTTP transport config |
+| `McpHttpConfig` | _type_ | HTTP auth, protected-resource, legacy-era and security options |
+| `McpHttpHandler` | _type_ | framework-owned `{ fetch(request), close() }` lifecycle |
+| `McpHttpSecurityConfig` | _type_ | Fetch-boundary Host and Origin allowlists |
+| `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 |
+| `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` |
+| `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 |
+| `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
+| `RuntimeToolDefinitionWithOutput` / `RuntimeToolDefinitionWithoutOutput` | _type_ | the one neutral construction, shared with `stitchkit/cli` and `stitchkit/tools`; MCP-only presenters are its fourth type argument, `RuntimeMcpToolPresenters<z.output<typeof output>>` |
+| `RuntimeToolDefinition` | _type_ | heterogeneous registration; the canonical runner validates input/output before invocation |
+| `RuntimeMcpToolPresenters` / `RuntimeMcpPresentation` | _type_ | official SDK content without framework-owned `structuredContent` or `isError`; one presenter owner shared with the full SDK surface |
+
 ### Catalog stamp
 
 Every advertised tool and every tool result carries the fingerprint of the catalog it came
@@ -24003,44 +24334,26 @@ Interactive MCP resources — [ADR 0019](../decisions/0019-generic-native-tools.
 | `McpAppResourceMeta` | _type_ | resource `_meta` for an MCP App |
 | `McpAppCsp` | _type_ | the widget content-security policy |
 
-### Introspection & internals
+## `stitchkit/tools/agent`
 
-Advanced building blocks — the shared machinery the mounts are built on.
+Server-only. A contract's operations as Vercel AI SDK tools; needs Zod and the `ai`
+peer, not the MCP server SDK. → ADR 0284.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `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 | 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_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
-| `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
-| `ToolSurfaceProjection` | _type_ | the one readonly `{ services?, runtimeTools? }` container shared by full, MCP-only and introspection surfaces (`buildToolManifest`, `listToolNames`, `summarizeTransports` take `ToolSurfaceProjection<RuntimeToolDefinition>`) |
-| `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
-| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments, including object guards restored from JSON Schema; arbitrary transform pipes stay untouched; throws a `ZodError` naming the field when a union that keeps a string member receives a string that parses to an array its array member accepts |
-| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; 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 |
-
----
+| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service; failed executions reject through the SDK tool-error channel with a safe typed envelope, while successful output is never classified by field name — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
+| `AgentMountConfig` | _type_ | config for `mountAgent` |
+| `AgentContext` | _type_ | the context merged into agent tool handlers |
 
-## `stitchkit/tools/mcp`
+## `stitchkit/tools/toolkit`
 
-A server-only leaf over the same MCP owner as `stitchkit/tools`. Its runtime and strict
-NodeNext declarations require Zod and `@modelcontextprotocol/server`, with no AI SDK peer.
-HTTP/stdio factories, mounts, schema policy, catalog and resource helpers keep their canonical
-behavior and names. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphandler).
+Server-only. One context-typed tool set served over MCP and to an AI SDK agent, so it
+needs both the `@modelcontextprotocol/server` and `ai` peers. → ADR 0284.
 
-| Export | Kind | Purpose |
+| Export | Kind | Summary |
 |--------|------|---------|
-| `createMcpHandler` / `createMcpHttpRoute` / `buildMcpServer` / `mountMcp` | function | the shared authenticated HTTP handler, raw-route adapter, SDK server and contract mount |
-| `createStdioMcpServer` / `bindStdioProcessSignals` | function | the shared stdio server and bounded process cleanup |
-| `RuntimeToolDefinitionWithOutput` / `RuntimeToolDefinitionWithoutOutput` | _type_ | the one neutral construction, shared with `stitchkit/cli` and `stitchkit/tools`; MCP-only presenters are its fourth type argument, `RuntimeMcpToolPresenters<z.output<typeof output>>` |
-| `RuntimeToolDefinition` | _type_ | heterogeneous registration; the canonical runner validates input/output before invocation |
-| `RuntimeMcpToolPresenters` / `RuntimeMcpPresentation` | _type_ | official SDK content without framework-owned `structuredContent` or `isError`; one presenter owner shared with the full SDK surface |
+| `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
+| `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
 
 ## `stitchkit/tools/connections`
 
@@ -24316,7 +24629,7 @@ shapes are `stitchkit/tracking/contract`, the server half is
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createTrackingClient` | function | the client: visit lease and renewal, pending queue, synchronous identity from reserved sequences, outbox and flush lease, delivery, the string-body page-leave beacon plus a queued copy, visible time, scroll milestones, declarative clicks, heartbeats |
-| `TrackingClient` / `TrackingClientConfig` | _type_ | `track` / `onNavigate` / `start` / `visitId` / `browserStreamId` / `attribution`, and the host, `buildId`, `builtin` names, `bootstrap`, `deliver`, optional `decorate` (your `eventExtras` on every minted event), `unload` / `unloadUrl`, `outbox`, `onUnauthorized`, `onVisit`, `onFailure`, `isAction`, `referrerMap`, `clickAttributes`, `hrefPolicy` (`path-only` by default; `full` retains click query/fragment before `decorate`), `scrollMilestones`, `batchSize`, periods and limits |
+| `TrackingClient` / `TrackingClientConfig` | _type_ | `track` / `onNavigate` / `start` / `visitId` / `browserStreamId` / `attribution`, and the host, `buildId`, `builtin` names, `bootstrap`, `deliver`, optional `decorate` (your `eventExtras` on every minted event), `unload` / `unloadUrl`, `outbox`, `onUnauthorized`, `onVisit`, `onFailure`, `isAction`, `clickIdParams` (ordered application-defined marker names; no values retained), `clickAttributes`, `hrefPolicy` (`path-only` by default; `full` retains click query/fragment before `decorate`), `scrollMilestones`, `batchSize`, periods and limits |
 | `TrackFn` / `EventsWithMetadata` / `EventsWithoutMetadata` | _type_ | `track(type)` / `track(type, metadata)` typed by the application's metadata map, and the two halves of that map |
 | `BuiltinTrackingEventTypes` / `CONVENTIONAL_TRACKING_EVENT_TYPES` | _type_ / const | the application's names for the events the client emits itself; the conventional `PAGE_VIEW` … `INTERACTION` set |
 | `browserTrackingHost` / `TrackingHost` / `TrackingPageContext` | function / _type_ | everything the client takes from a browser tab behind one interface — page context, visibility, scroll depth, events, intervals, clocks, storage — so a test or a non-tab host can supply its own |
@@ -24329,8 +24642,8 @@ shapes are `stitchkit/tracking/contract`, the server half is
 | `createVisibleTimeMeter` / `VisibleTimeMeter` / `VisibleInterval` / `VisibleHeartbeat` / `VisibleTimeMeterOptions` | function / _type_ | additive visible time — `checkpoint` / `cut` / `heartbeat`, each interval with its own id; a hidden heartbeat carries no interval |
 | `scrollDepthPercent` / `createScrollMilestones` / `ScrollMilestones` | function / _type_ | depth as a percentage of the scrollable range; milestones fired once each per page |
 | `createOncePerPage` / `OncePerPage` | function / _type_ | one fact per key per page within a window — the guard a twice-mounted component cannot keep itself |
-| `resolveAttribution` / `ResolveAttributionInput` / `ResolvedAttribution` / `AttributionStorage` / `ReferrerRule` | function / _type_ | first-touch once, current-touch on every new UTM; the referrer → source/medium map is the application's, there is no built-in list |
-| `parseUtmFromSearch` / `parseReferrer` | function | the two parsers `resolveAttribution` is built from |
+| `resolveAttribution` / `ResolveAttributionInput` / `ResolvedAttribution` / `AttributionStorage` | function / _type_ | persisted first-touch with TTL, raw current-touch on each capture; actual UTM, referrer and optional `clickId` name from `clickIdParams`; `storage: null` collects without persistence; no channel inference |
+| `parseUtmFromSearch` | function | reads only `utm_*`, preserving case and whitespace up to 200 characters per field; any tag is sufficient, no source required |
 | `redactTrackingText` / `redactTrackingValue` | functions | mask passwords, sign-in credentials and signed launch data in text or a value of any shape; the key stays, and navigation and campaign parameters are untouched |
 | `resolveTrackedClick` / `ResolveTrackedClickOptions` / `TrackedClick` / `TrackedClickAttributes` / `ClickTarget` | function / _type_ | `data-track` → click, `data-track-action` → interaction, a link to another origin → outbound; attribute names configurable; `hrefPolicy: 'full'` retains query/fragment (default `path-only` omits them), URL credentials excluded; `leavesPage` says which path to send on |
 
@@ -24346,7 +24659,7 @@ browser code that only sends events does not import it. → ADR 0280
 | `createTrackingContract` / `TrackingContractConfig` / `TrackingContractEndpoints` | function / _type_ | `bootstrap` (`POST /visit`) and `track` (`POST /events`, `safelistedBody`) from the application's event types, scope and optional extras |
 | `createTrackingSchemas` / `TrackingSchemas` / `TrackingSchemasConfig` | function / _type_ | every schema of one surface — `event`, `request`, `response`, `disposition`, `entry`, `bootstrap` — from `eventTypes`, optional `eventExtras`, `buildIdPattern`, `maxEventsPerBatch` |
 | `TrackingEventEnvelope` / `TrackingEventShape` | _type_ | `eventId`, `visitId`, `browserStreamId`, `browserSequence`, `type`, `page`, `metadata`, `clientTimestamp` |
-| `TrackEventsRequest` / `TrackEventsResponse` / `TrackEventsResponseSchema` | _type_ / schema | a batch (`buildId`, `events`, `utm`) and its answer (`accepted`, `dispositions`) |
+| `TrackEventsRequest` / `TrackEventsResponse` / `TrackEventsResponseSchema` | _type_ / schema | a batch (`buildId`, `events`; attribution travels with the visit bootstrap) and its answer (`accepted`, `dispositions`) |
 | `TrackingDisposition` / `TrackingDispositionSchema` / `TrackingDispositionStatus` / `TrackingDispositionStatusSchema` | _type_ / schema | `accepted` / `duplicate` / `identity-invalid` / `excluded-bot` — every one terminal |
 | `VisitEntryContext` / `VisitEntryContextShape` / `VisitBootstrapResponse` / `VisitBootstrapResponseSchema` | _type_ / schema | what a browser reports to open a visit (lineage, landing, referrer, UTM, display, screen, `buildId`, outbox health) and the lease it gets back |
 | `TrackingOutboxState` / `TrackingOutboxStateSchema` | _type_ / schema | `available` / `unavailable` |
@@ -24437,7 +24750,15 @@ adapter is used.
 | `createGeoIpResolver` / `GeoIpResolver` / `GeoIpResolverOptions` / `GeoIpSnapshot` | function / _type_ | public-IP lookup over one stable reader generation; unavailable start, last-known-good degraded reload and cleanup are explicit states |
 | `createMaxMindGeoIpLoader` / `MaxMindGeoIpLoaderOptions` / `MaxMindGeoIpPaths` | function / _type_ | lazy optional-peer City+ASN loader with stable before/after file revision checks |
 | `GeoIpReader` / `GeoIpReaderLoader` | _type_ | peer-neutral reader/generation seam for adapters and tests |
-| `GeoAttribution` / `mapGeoIpRecord` | _type_ / function | generic optional place and autonomous-system projection; application-specific fields remain outside |
+| `GeoAttribution` / `mapGeoIpRecord` | _type_ / function | strict readonly sparse City + ASN snapshot: continent, located and registered country as separate facts, GeoNames IDs, first region/city/postal, coordinates/timezone, `accuracyRadiusKm`, autonomous system and all source languages in five `localizedNames` groups; each malformed field is omitted on its own; custom resolver mappers remain app-owned — [guide](../guide/geo.md#lookups) |
+
+## `stitchkit/geo/contract`
+
+The place snapshot's schema, browser-safe, for a shared contract. Brings `zod`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `GeoAttributionSchema` / `GeoAttribution` | schema / _type_ | the strict readonly Zod owner of the snapshot `stitchkit/geo` resolves — [guide](../guide/geo.md#lookups) |
 
 ---