@ontrails/mcp 1.0.0-beta.4 → 1.0.0-beta.41

package/CHANGELOG.md

@@ -1,5 +1,384 @@
 # @ontrails/mcp
 
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+
+## 1.0.0-beta.39
+
+### Patch Changes
+
+- [`81373bc`](https://github.com/outfitter-dev/trails/commit/81373bc5e980bb06d56fb06af4f0986f72e318c7): Wave-2 MCP cutover to the app-authored `surfaces` overlay. The overlay's `mcp` bindings are now the authored, lockable default for the MCP surface: a list binding derives one grouped trailhead tool (member selection in `{ trail, input }`, member identity preserved in `{ trail, output }`, deterministic derived description), and a scalar binding derives an additional tool synonym whose MCP-safe name is published verbatim and must expand to exactly one trail. `deriveMcpTools`/`createServer` accept the new `overlays` option; `@ontrails/core` gains `expandMcpSurfaceBindings` and `deriveMcpTrailheadDescription`.
+
+  The call-site `CreateServerOptions.trailheads` map survives as permanent override-in-context design, not a compatibility bridge: when both channels are present, the call-site map wins at runtime. Warden's new `trailhead-override-divergence` rule (warn) names both sides when a call-site map's binding names or member selectors diverge from the authored overlay default.
+
+  Topographer now derives `graph.trailheads` from the overlay's `mcp` list bindings in both `deriveTopoGraph` and the store-side graph build, so trailhead facts flow from compiled locks into Wayfinder reads for the first time. The never-wired `DeriveTopoGraphOptions.trailheads` option and the `TopoGraphTrailheadDeclaration`/`TopoGraphTrailheadTrailSelector` types are removed — a beta-window hard cutover of an option no caller could reach; author the equivalent `mcp` list binding in `surfaceOverlay({ mcp })` instead.
+
+- [`820b4ad`](https://github.com/outfitter-dev/trails/commit/820b4ad9c40ea383b3c489a05fe7e4b2328e324f): Add `surfaceOverlay` — the shared surface-naming schema (scalar binding = synonym, list binding = grouped entry, singleton list stays a group) with app-authored/adapter-derived overlay provenance enforced at collection and consumption, and the `surface-overlay-coherence` Warden rule. MCP tool-name derivation moves to `@ontrails/core` (`deriveMcpToolName`) so the surface and governance read one projection; `@ontrails/mcp`'s `deriveToolName` now delegates to it. The coherence rule activates on standard warden runs once fresh derivations collect app-module overlays through the shared compile channel (TRL-1209, next in this stack).
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+### Patch Changes
+
+- [`6e63e48`](https://github.com/outfitter-dev/trails/commit/6e63e483617b84cb6868d0c4d58d5b5a8d3b9ed2): Complete the v1 grouped surface-entry vocabulary cutover from facet to trailhead, including Regrade dogfood support for governed string literal renames and composed AST rewrite application.
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [21c6dda]
+- Updated dependencies [fe72b84]
+  - @ontrails/core@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- ee9f3ae: Let Warden fix capabilities declare downstream scan targets and have Regrade
+  honor those targets for Warden-backed term-rewrite classes.
+
+  Dogfood the first safe facet-to-trailhead prose rewrite through project-local
+  Warden rules and Regrade.
+
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [38907cc]
+  - @ontrails/core@1.0.0-beta.31
+
+## 1.0.0-beta.30
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.30
+
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- a9fdbc7: Clarify surface accommodation doctrine in MCP surface facet metadata and Warden trail-fork coaching guidance.
+- 2c08afe: Expose MCP trail graph fact resources and enable them for the Trails operator MCP surface.
+- f1e6efa: Document the Wayfinder MCP resource surface and polish Wayfinder filter dogfood coverage for unified navigation.
+- df13faf: Tighten Wayfinder navigation review findings: carry adapter filters into included adapter facts, keep live-source outline off the operator MCP surface until host-root binding exists, make unknown MCP resources protocol errors, route secondary Wayfinder graph populations through unified flags, and keep undeclared string `ctx.compose()` calls as Warden errors.
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+  - @ontrails/core@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.24
+
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.23
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.22
+
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- Updated dependencies [99523f2]
+  - @ontrails/core@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Minor Changes
+
+- accb9ec: Add MCP surface facets, MCP resource projection for cold context, and deferred-loading metadata hints.
+
+### Patch Changes
+
+- 9bec01c: Document MCP resource projection and deferred-loading options for cold surface context.
+- Updated dependencies [851a2a3]
+  - @ontrails/core@1.0.0-beta.20
+
+## 1.0.0-beta.19
+
+### Patch Changes
+
+- e41c382: Document beta-channel install guidance in package and adapter README install snippets so consumers use explicit `@beta` (or pinned `1.0.0-beta.N`) tags instead of accidental `latest` resolution during the prerelease line. Adds the policy doc at `docs/releases/beta-channel-policy.md`, prints both `latest` and `beta` dist-tags in `bun run publish:registry-check`, and aligns plugin/skill install snippets.
+- 1eb5bdc: Rename first-class trail composition from the `cross` API family to the `compose` family across core contracts, testing helpers, topo projections, Warden rules, CLI scaffolds, and docs. `composes`, `ctx.compose`, `composeInput`, and `Compose*` type names are now the public authoring vocabulary; topo persistence migrates legacy composition rows and graph keys forward.
+- 8638dae: Add a public API example for MCP `deriveAnnotations` annotation derivation.
+- 8638dae: Add public API examples for the MCP tool metadata keys.
+- 8638dae: Add a public API example for the MCP progress callback bridge.
+- 84f56a5: Project live trail-version metadata on CLI, HTTP, and MCP surfaces and thread explicit surface version selection into shared trail execution.
+- 5d88104: Polish Trails blaze terminology across package docs and Warden guidance.
+- Updated dependencies [e41c382]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [846a597]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [d76be13]
+- Updated dependencies [84f56a5]
+- Updated dependencies [431b04c]
+- Updated dependencies [5d88104]
+- Updated dependencies [f04a9ef]
+  - @ontrails/core@1.0.0-beta.19
+
+## 1.0.0-beta.18
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.18
+
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- 61497c5: Add v1-minimum public API examples for shipped surface entrypoints.
+- Updated dependencies [3dc8254]
+  - @ontrails/core@1.0.0-beta.17
+
+## 1.0.0-beta.16
+
+### Minor Changes
+
+- 26f9ffd: Project typed-layer `input` schemas onto MCP and HTTP surfaces. Closes Phase 7. Lifts `collectAttachedTypedLayers` and `projectLayerFieldName` (collision-rename rule) into `@ontrails/core/internal/layer-projection` so all three surfaces share one source of truth. The CLI surface refactors to consume the lifted helpers (no behavior change). MCP merges layer fields into each tool's `inputSchema` and partitions inbound args at invocation time. HTTP merges layer fields into the route's request schema (query for reads, body for writes) and exposes new optional `HttpRouteDefinition.inputSchema` + `layerInputProjections` for surface adapters / OpenAPI generators. Collision rule matches TRL-473's: deterministic rename to a layer-prefixed camelCase name with the original captured in the routing table. Side fix: MCP and HTTP handlers now forward `topoLayers: graph.layers` + `surfaceLayers: layers` so topo-scope layers actually compose at runtime (previously the handlers used the deprecated `layers` alias and never read `graph.layers`).
+
+### Patch Changes
+
+- 6300f70: Refresh source comments and test labels for retired connector terminology as adapter guardrails become strict.
+- 20d7a5c: Enforce the shared safe error projection policy for public error bodies, diagnostics, serialized payloads, and CLI stderr.
+- 49c2e7d: Refresh published package README taxonomy to use adapter language instead of retired connector vocabulary.
+- Updated dependencies [73622ae]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [e898cc4]
+- Updated dependencies [3395234]
+- Updated dependencies [bcdc484]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+  - @ontrails/core@1.0.0-beta.16
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+
+## 1.0.0-beta.14
+
+### Minor Changes
+
+- 69057e9: Add hierarchical CLI command trees and structured input, enforce established-only topo exports across trailheads, move developer topo and tracker state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+
+### Patch Changes
+
+- Updated dependencies [69057e9]
+  - @ontrails/core@1.0.0-beta.14
+
+## 1.0.0-beta.13
+
+### Minor Changes
+
+- Trail-native vocabulary cutover. Breaking API field renames across all packages:
+
+  - Trail spec: `run:` → `blaze:`, `follow:` → `crosses:`, `services:` → `provisions:`, `metadata:` → `meta:`, `emits:` → `signals:`
+  - Runtime: `ctx.follow()` → `ctx.cross()`, `ctx.emit()` → `ctx.signal()`, `ctx.signal` (abort) → `ctx.abortSignal`
+  - Entry points: `blaze(app)` → `trailhead(app)`
+  - Package rename: `@ontrails/crumbs` → `@ontrails/tracker`
+  - Wrapper types: `Layer` → `Gate`, `layers`/`middleware` → `gates`
+  - Transport: `surface` → `trailhead`, `adapter` → `connector`
+
+### Patch Changes
+
+- 6944147: Complete trifecta for config, permits, and tracker (formerly tracks)
+
+  - **config**: Add `configProvision`, `configGate`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **permits**: Add `authService` and `auth.verify` trail for runtime authorization checks
+  - **tracker**: Rename tracks to tracker; add `trackerProvision` and `tracker.status` trail for structured signal tracking
+  - **cli**: Fix build flag handling and improve bootstrap scaffolding
+  - **testing**: Expand test context helpers and example-based testing utilities
+  - **core/mcp/http**: Internal alignment for provision and composition updates
+
+- Updated dependencies [6944147]
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.13
+
+## 1.0.0-beta.12
+
+### Patch Changes
+
+- Complete trifecta for config, permits, and tracker (formerly tracks)
+
+  - **config**: Add `configProvision`, `config.gate`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **permits**: Add `authProvision` and `auth.verify` trail for runtime authorization checks
+  - **tracker**: Rename tracks to tracker; add `trackerProvision` and `tracker.status` trail for structured event tracking
+  - **cli**: Fix build flag handling and improve bootstrap scaffolding
+  - **testing**: Expand test context helpers and example-based testing utilities
+  - **core/mcp/http**: Internal alignment for provision and composition updates
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.12
+
+## 1.0.0-beta.11
+
+### Patch Changes
+
+- Add provisions as a first-class primitive.
+
+  Provisions make infrastructure dependencies declarative, injectable, and governable. Define a provision with `provision()`, declare it on a trail with `provisions: [db]`, and access it with `db.from(ctx)` or `ctx.provision()`.
+
+  **Core:** `provision()` factory, `ProvisionSpec<T>`, `ProvisionContext`, singleton resolution in `executeTrail`, in-flight creation dedup, `isProvision` guard, `findDuplicateProvisionId`, topo provision discovery and validation, `provisions` field on trail specs.
+
+  **Testing:** Auto-resolution of `mock` factories in `testAll`, `testExamples`, `testContracts`, and `testCrosses`. Explicit `provisions` overrides with correct precedence (`explicit > ctx.extensions > auto-mock`). Provision mock propagation through crossing graphs.
+
+  **Warden:** `provision-declarations` rule validates `db.from(ctx)` and `ctx.provision()` usage matches declared `provisions: [...]`. `provision-exists` rule validates declared provision IDs resolve in project context. Scope-aware AST walking skips nested function boundaries.
+
+  **Trailheads:** Provision overrides thread through `run` and `trailhead` on CLI, MCP, and HTTP.
+
+  **Introspection:** Survey and trailhead map outputs include provision graph. Topo exposes `.provisions`, `.getProvision()`, `.hasProvision()`, `.listProvisions()`, `.provisionIds()`, `.provisionCount`.
+
+  **Docs:** ADR-009 accepted. Unified provisions guide, updated vocabulary, getting-started, architecture, and package READMEs.
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.11
+
+## 1.0.0-beta.10
+
+### Patch Changes
+
+- Cleanup and hardening pass across all packages.
+
+  **core**: Deduplicate `DispatchOptions` as type alias of `ExecuteTrailOptions`. Replace `TrailContext` index signature with typed `extensions` field for type safety. Deep-merge `extensions` in `executeTrail` context resolution. Remove unused `Trailhead` type, `connectors.ts`, `health.ts`, and `job.ts` proof-of-concept from published package.
+
+  **cli**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `trailhead()` with opt-out via `validate: false`.
+
+  **http**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `trailhead()` with opt-out.
+
+  **mcp**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `trailhead()` with opt-out.
+
+  **warden**: Project-aware rule context preserved in trail wrappers.
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.10
+
+## 1.0.0-beta.9
+
+### Minor Changes
+
+- Consolidated improvements across all trailhead packages.
+
+  **core**: Add `TrailResult<T>` utility type, `topo.ids()` and `topo.count` accessors, `run()` for headless trail execution, and extract shared `executeTrail` pipeline used by CLI/MCP/HTTP.
+
+  **http**: Detect route path collisions and return `Result` from `buildHttpRoutes()`, wire request `AbortSignal` through to trail context, and make write → POST mapping explicit in intent-to-method lookup.
+
+  **mcp**: Return `Result` from `buildMcpTools()` on collision instead of throwing.
+
+  **cli**: Verify exception catching via centralized `executeTrail`.
+
+  **testing**: Cross-context awareness improvements.
+
+  **warden**: Refactor rules as composable trails with examples.
+
+  **schema**: Error code and empty body fixes.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.9
+
+## 1.0.0-beta.8
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.8
+
+## 1.0.0-beta.7
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.7
+
+## 1.0.0-beta.6
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.6
+
+## 1.0.0-beta.5
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.5
+
 ## 1.0.0-beta.4
 
 ### Major Changes
@@ -8,15 +387,15 @@
 
   **BREAKING CHANGES:**
 
-  - `hike()` removed — use `trail()` with optional `follow: [...]` field
-  - `follows` renamed to `follow` (singular, matching `ctx.follow()`)
+  - `hike()` removed — use `trail()` with optional `crosses: [...]` field
+  - `follows` renamed to `crosses` (matching `ctx.cross()`)
   - `topo.hikes` removed — single `topo.trails` map
   - `kind: 'hike'` removed — everything is `kind: 'trail'`
   - `readOnly`/`destructive` booleans replaced by `intent: 'read' | 'write' | 'destroy'`
   - `implementation` field renamed to `run`
   - `markers` field renamed to `metadata`
-  - `testHike` renamed to `testFollows`, `HikeScenario` to `FollowScenario`
-  - `blaze()` now returns the surface handle (`Command` for CLI, `Server` for MCP)
+  - `testHike` renamed to `testCrosses`, `HikeScenario` to `CrossScenario`
+  - `trailhead()` now returns the trailhead handle (`Command` for CLI, `Server` for MCP)
 
 ### Patch Changes
 
@@ -27,15 +406,15 @@
 
 ### Minor Changes
 
-- Bug fixes across all surface packages found via parallel Codex review.
+- Bug fixes across all trailhead packages found via parallel Codex review.
 
   **core**: Fix Result.toJson false circular detection on DAGs, deserializeError subclass round-trip, topo cross-kind ID collisions, validateTopo multi-node cycle detection, error example input validation bypass, and deriveFields array type collapse.
 
-  **cli**: Switch blaze to parseAsync for proper async error handling, add boolean flag negation (--no-flag), and strict number parsing that rejects partial input.
+  **cli**: Switch trailhead to parseAsync for proper async error handling, add boolean flag negation (--no-flag), and strict number parsing that rejects partial input.
 
   **mcp**: Align BlobRef with core (including ReadableStream support) and detect tool-name collisions after normalization.
 
-  **testing**: Include hikes in testContracts validation, with follow-context awareness.
+  **testing**: Include hikes in testContracts validation, with cross-context awareness.
 
   **warden**: Collect hike detour targets, validate detour refs in hike specs, and stop implementation-returns-result from walking into nested function bodies.
 
@@ -70,12 +449,12 @@
 - Initial v1 beta release of the Trails framework.
 
   - **@ontrails/core** — Result type, error taxonomy, trail/hike/event/topo, validateTopo, validateInput/Output, deriveFields, patterns, redaction, branded types, resilience
-  - **@ontrails/cli** — CLI surface adapter, Commander integration, flag derivation, layers
-  - **@ontrails/mcp** — MCP surface adapter, tool generation, annotations, progress bridge
-  - **@ontrails/logging** — Structured logging, sinks, formatters, LogTape adapter
-  - **@ontrails/testing** — testAll, testExamples, testTrail, testHike, testContracts, testDetours, surface harnesses
+  - **@ontrails/cli** — CLI trailhead connector, Commander integration, flag derivation, gates
+  - **@ontrails/mcp** — MCP trailhead connector, tool generation, annotations, progress bridge
+  - **@ontrails/logging** — Structured logging, sinks, formatters, LogTape connector
+  - **@ontrails/testing** — testAll, testExamples, testTrail, testHike, testContracts, testDetours, trailhead harnesses
   - **@ontrails/warden** — AST-based code convention rules via oxc-parser, drift detection, CI formatters
-  - **@ontrails/schema** — Surface map generation, hashing, semantic diffing
+  - **@ontrails/schema** — Trailhead map generation, hashing, semantic diffing
 
 ### Patch Changes
 

package/README.md

@@ -1,55 +1,69 @@
 # @ontrails/mcp
 
-MCP surface adapter. One `blaze()` call turns a topo into an MCP server with tool definitions, annotations, and progress bridging -- all derived from the trail contracts.
+MCP surface adapter. One `surface()` call turns a topo into an MCP server with tool definitions, annotations, and progress bridging -- all derived from the trail contracts.
 
 ## Usage
 
 ```typescript
 import { trail, topo, Result } from '@ontrails/core';
-import { blaze } from '@ontrails/mcp';
+import { surface } from '@ontrails/mcp';
 import { z } from 'zod';
 
 const greet = trail('greet', {
   input: z.object({ name: z.string().describe('Who to greet') }),
+  output: z.object({ greeting: z.string() }),
   intent: 'read',
-  run: (input) => Result.ok(`Hello, ${input.name}!`),
+  examples: [
+    {
+      expected: { greeting: 'Hello, Ada!' },
+      input: { name: 'Ada' },
+      name: 'Ada',
+    },
+  ],
+  implementation: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
 });
 
-const app = topo('myapp', { greet });
-await blaze(app);
+const graph = topo('myapp', { greet });
+await surface(graph);
 ```
 
-This starts an MCP server over stdio with a `myapp_greet` tool. The tool gets `readOnlyHint: true` and a JSON Schema input -- both derived from the trail definition.
+This starts an MCP server over stdio with a `myapp_greet` tool. The tool gets `readOnlyHint: true`, JSON Schema input, JSON Schema output, and structured examples -- all derived from the trail definition.
 
 For more control, build the tools yourself:
 
 ```typescript
-import { buildMcpTools } from '@ontrails/mcp';
+import { deriveMcpTools } from '@ontrails/mcp';
 
-const tools = buildMcpTools(app);
-for (const tool of tools) {
+const result = deriveMcpTools(graph);
+if (result.isErr()) throw result.error; // ValidationError on tool-name collision
+for (const tool of result.value) {
   server.registerTool(tool.name, tool.handler, {
     inputSchema: tool.inputSchema,
+    outputSchema: tool.outputSchema,
     annotations: tool.annotations,
+    _meta: tool._meta,
   });
 }
 ```
 
+`deriveMcpTools` returns `Result<McpToolDefinition[], Error>` rather than a bare array. It returns `Result.err(ValidationError)` if two trails derive the same MCP tool name. Each `McpToolDefinition` includes a `trailId` field that records which trail the tool was derived from.
+
 ## API
 
 | Export | What it does |
 | --- | --- |
-| `blaze(app, options?)` | Start an MCP server with all trails as tools |
-| `buildMcpTools(app, options?)` | Build tool definitions without starting a server |
+| `surface(graph, options?)` | Start an MCP server with all trails as tools |
+| `deriveMcpTools(graph, options?)` | Build tool definitions without starting a server |
+| `buildMcpResources(graph, tools, config?)` | Build MCP resource listings and read handlers for cold context |
 | `deriveToolName(appName, trailId)` | Compute the MCP tool name from app and trail IDs |
-| `deriveAnnotations(trail)` | Extract MCP annotations from trail intent and metadata |
+| `deriveAnnotations(trail)` | Extract MCP annotations from trail intent, idempotency, and description |
 | `createMcpProgressCallback(server)` | Bridge `ctx.progress` to MCP `notifications/progress` |
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
 ## Annotations
 
-Trail intent and metadata map directly to MCP annotations:
+Trail intent, idempotency, and description map directly to MCP annotations:
 
 | Trail field | MCP annotation |
 | --- | --- |
@@ -60,17 +74,53 @@ Trail intent and metadata map directly to MCP annotations:
 
 No manual annotation definitions. The contract is the source of truth.
 
+## Schemas and Examples
+
+MCP tool definitions include the trail's input schema, and trails with an `output` schema also project that schema into MCP `outputSchema`. Non-object trail outputs are wrapped in a `{ data: ... }` object because MCP structured tool results are object-shaped.
+
+Trail examples are projected as structured metadata under `_meta["ontrails/examples"]`. Each projected example preserves its input, expected output or error, a success/error kind, and provenance pointing back to the authored `trail.examples` field.
+
+## MCP resources and deferred loading
+
+Cold context is projected through MCP resources, not extra Trails resources. `surface(graph)` and `createServer(graph)` expose MCP resources by default:
+
+- `trails://surface-map` lists the resolved MCP tool projection, including ordinary tools, trailhead tools, schemas, versions, deferred hints, and member trail IDs.
+- `trails://examples/<trailId>` exposes structured examples for exposed trails that define examples.
+- `trails://trail/<trailId>` exposes MCP-visible graph facts for an exposed trail when graph resources are enabled.
+
+Disable resource projection only when the host needs a minimal MCP capability surface:
+
+```typescript
+await surface(graph, { mcpResources: false });
+```
+
+Or choose a narrower resource set:
+
+```typescript
+await surface(graph, {
+  mcpResources: { examples: false, graph: true, surfaceMap: true },
+});
+```
+
+Graph resources are opt-in for general MCP hosts because they widen cold context for every exposed trail. The Trails operator enables them so agents can inspect high-signal graph facts without invoking another tool.
+
+Trailhead definitions may set `mcp: { loading: 'deferred' }`. In this release, deferred loading is a compatibility hint under `_meta["ontrails/deferred"]`; the MCP tool schema remains present so clients that do not understand deferred loading continue to work.
+
 ## Tool naming
 
 Trail IDs become MCP tool names with the app prefix: `entity.show` in app `myapp` becomes `myapp_entity_show`. Dots and hyphens become underscores, everything lowercase.
 
+## Resource resolution
+
+Declared resources on each trail are resolved into the context before the implementation receives input.
+
 ## Progress bridge
 
 Implementations report progress through `ctx.progress`. On MCP, these bridge to `notifications/progress` when the client sends a `progressToken`:
 
 ```typescript
 const importTrail = trail('data.import', {
-  run: async (input, ctx) => {
+  implementation: async (input, ctx) => {
     for (let i = 0; i < items.length; i++) {
       await processItem(items[i]);
       ctx.progress?.({ type: 'progress', current: i + 1, total: items.length });
@@ -83,12 +133,14 @@ const importTrail = trail('data.import', {
 ## Filtering
 
 ```typescript
-await blaze(app, { includeTrails: ['entity.show', 'search'] });
-await blaze(app, { excludeTrails: ['internal.debug'] });
+await surface(graph, { include: ['entity.**', 'search'] });
+await surface(graph, { exclude: ['internal.debug'] });
 ```
 
+`*` matches one dotted segment and `**` matches any depth. Trails declared with `visibility: 'internal'` stay hidden unless you include their exact trail ID.
+
 ## Installation
 
 ```bash
-bun add @ontrails/mcp
+bun add @ontrails/mcp@beta
 ```

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@ontrails/mcp",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.41",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,10 +22,10 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.0"
+    "@ontrails/core": "^1.0.0-beta.41"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "zod": "^4.3.5"
   }
 }

package/src/annotations.ts

@@ -25,9 +25,32 @@ export interface McpAnnotations {
  *
  * Only sets hints that are explicitly declared on the trail.
  * Omitted hints let the MCP SDK use its defaults.
+ *
+ * @example
+ * ```ts
+ * import { deriveAnnotations } from '@ontrails/mcp';
+ *
+ * const annotations = deriveAnnotations({
+ *   intent: 'read',
+ *   idempotent: true,
+ *   description: 'Show account',
+ * });
+ *
+ * // read intent -> readOnlyHint, idempotent -> idempotentHint, description -> title.
+ * annotations.readOnlyHint === true;
+ * annotations.idempotentHint === true;
+ * annotations.title === 'Show account';
+ *
+ * // destroy intent -> destructiveHint.
+ * const destroyAnnotations = deriveAnnotations({ intent: 'destroy' });
+ * destroyAnnotations.destructiveHint === true;
+ * ```
  */
 export const deriveAnnotations = (
-  trail: Pick<Trail<unknown, unknown>, 'intent' | 'idempotent' | 'description'>
+  trail: Pick<
+    Trail<unknown, unknown, unknown>,
+    'intent' | 'idempotent' | 'description'
+  >
 ): McpAnnotations => {
   const annotations: Record<string, unknown> = {};