stitchkit 0.118.1 → 0.120.0

package/llms/tools-mcp.txt

@@ -14,15 +14,80 @@ Also read:
 
 ## `stitchkit/tools/mcp`
 
-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, 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` / `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 |
+| `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
+from, so a long-lived consumer can see that its own copy is stale **without making a
+request for it**. `createMcpHandler` is stateless by construction and therefore has no
+retained session to push `notifications/tools/list_changed` down; the stamp needs none.
+
+Store the stamp beside the tools when you list them, compare it against the one on every
+result, and re-list when they differ — including on a refusal, which is exactly when a
+stale catalog is the likeliest explanation and the least visible one. The server side
+needs no wiring: every mount stamps what it advertises.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `readMcpCatalogStamp` | function | read a peer's stamp out of `_meta`, or `null` when there is none |
+| `mcpCatalogMeta` | function | the `_meta` fragment a stamped tool or result carries |
+| `MCP_CATALOG_META_KEY` | const | the namespaced `_meta` key (`stitchkit/catalog`) |
+| `McpCatalogStamp` | _type_ | `{ digest, tools }` — the catalog fingerprint and its tool count |
+
+### MCP Apps (widgets)
+
+Interactive MCP resources — [ADR 0019](../decisions/0019-generic-native-tools.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `mountMcpResource` | function | mount an MCP Apps widget resource |
+| `inlineMcpAppBundle` | function | inline a built widget bundle into a resource |
+| `EXT_APPS_BUNDLE_PLACEHOLDER` | const | the placeholder token `inlineMcpAppBundle` replaces |
+| `RESOURCE_MIME_TYPE` | const | the MCP Apps resource MIME type |
+| `McpResourceDef` | _type_ | an MCP Apps resource definition |
+| `McpAppResourceMeta` | _type_ | resource `_meta` for an MCP App |
+| `McpAppCsp` | _type_ | the widget content-security policy |

package/llms/tools-toolkit.txt

@@ -0,0 +1,23 @@
+# stitchkit/tools/toolkit — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/tools/toolkit`  (docs/api/reference.md)
+
+Also read:
+- see `llms/tools.txt` for the MCP & agents guide
+
+==============================================================================
+# API reference: `stitchkit/tools/toolkit`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/tools/toolkit`
+
+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 | Summary |
+|--------|------|---------|
+| `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
+| `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |

package/llms/tools.2.txt

@@ -154,8 +154,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,
@@ -178,7 +178,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' } })
@@ -262,7 +262,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({
@@ -628,7 +630,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' },

package/llms/tools.3.txt

@@ -14,57 +14,25 @@ Parts of this slice:
 
 ## `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) |
@@ -90,11 +58,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 |
@@ -126,7 +91,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
@@ -163,7 +127,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 |
@@ -230,39 +194,6 @@ 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 |
 
-### Catalog stamp
-
-Every advertised tool and every tool result carries the fingerprint of the catalog it came
-from, so a long-lived consumer can see that its own copy is stale **without making a
-request for it**. `createMcpHandler` is stateless by construction and therefore has no
-retained session to push `notifications/tools/list_changed` down; the stamp needs none.
-
-Store the stamp beside the tools when you list them, compare it against the one on every
-result, and re-list when they differ — including on a refusal, which is exactly when a
-stale catalog is the likeliest explanation and the least visible one. The server side
-needs no wiring: every mount stamps what it advertises.
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `readMcpCatalogStamp` | function | read a peer's stamp out of `_meta`, or `null` when there is none |
-| `mcpCatalogMeta` | function | the `_meta` fragment a stamped tool or result carries |
-| `MCP_CATALOG_META_KEY` | const | the namespaced `_meta` key (`stitchkit/catalog`) |
-| `McpCatalogStamp` | _type_ | `{ digest, tools }` — the catalog fingerprint and its tool count |
-
-### MCP Apps (widgets)
-
-Interactive MCP resources — [ADR 0019](../decisions/0019-generic-native-tools.md).
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `mountMcpResource` | function | mount an MCP Apps widget resource |
-| `inlineMcpAppBundle` | function | inline a built widget bundle into a resource |
-| `EXT_APPS_BUNDLE_PLACEHOLDER` | const | the placeholder token `inlineMcpAppBundle` replaces |
-| `RESOURCE_MIME_TYPE` | const | the MCP Apps resource MIME type |
-| `McpResourceDef` | _type_ | an MCP Apps resource definition |
-| `McpAppResourceMeta` | _type_ | resource `_meta` for an MCP App |
-| `McpAppCsp` | _type_ | the widget content-security policy |
-
 ### Introspection & internals
 
 Advanced building blocks — the shared machinery the mounts are built on.

package/llms/tools.txt

@@ -125,10 +125,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
@@ -150,9 +150,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,
@@ -876,7 +875,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'

package/llms/tracking-contract.txt

@@ -22,7 +22,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` |

package/llms/tracking.txt

@@ -27,7 +27,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
@@ -74,7 +74,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),
 })
@@ -87,6 +87,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
@@ -323,7 +345,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 |
@@ -336,8 +358,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 |