@ontrails/mcp 1.0.0-beta.32 → 1.0.0-beta.39

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @ontrails/mcp
 
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/mcp",
-  "version": "1.0.0-beta.32",
+  "version": "1.0.0-beta.39",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,7 +22,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.32"
+    "@ontrails/core": "^1.0.0-beta.39"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",

package/src/build.ts

@@ -8,12 +8,15 @@
 
 import {
   AuthError,
+  InternalError,
   Result,
   ValidationError,
   collectAttachedTypedLayers,
+  deriveMcpTrailheadDescription,
   deriveSurfaceTrailVersionProjections,
   deriveStructuredTrailExamples,
   executeTrail,
+  expandMcpSurfaceBindings,
   filterSurfaceTrails,
   isBlobRef,
   isTrailsError,
@@ -21,6 +24,7 @@ import {
   matchesTrailPattern,
   projectLayerFieldName,
   projectPublicSurfaceError,
+  resolveSurfaceOverlayBindings,
   toBlobRefDescriptor,
   validateSurfaceTopo,
   withSurfaceLayerNames,
@@ -32,6 +36,8 @@ import type {
   BaseSurfaceOptions,
   BlobRef,
   Layer,
+  McpSurfaceBindingExpansion,
+  OverlayEnvelopeLike,
   ResourceOverrideMap,
   SurfaceErrorProjection,
   SurfaceTrailVersionProjection,
@@ -71,20 +77,20 @@ export const MCP_TOOL_EXAMPLES_META_KEY = 'ontrails/examples';
 export const MCP_TOOL_ERROR_META_KEY = 'ontrails/error';
 
 /**
- * Metadata key used to identify MCP tools derived from surface facets.
+ * Metadata key used to identify MCP tools derived from surface trailheads.
  *
- * Surface facets preserve member trail identity rather than merging member
- * contracts. The metadata names the facet and its member trail IDs so clients
+ * Surface trailheads preserve member trail identity rather than merging member
+ * contracts. The metadata names the trailhead and its member trail IDs so clients
  * can inspect the grouped entry before choosing a selected trail.
  *
  * @example
  * ```ts
- * import { MCP_TOOL_FACET_META_KEY } from '@ontrails/mcp';
+ * import { MCP_TOOL_TRAILHEAD_META_KEY } from '@ontrails/mcp';
  *
- * const facet = tool._meta?.[MCP_TOOL_FACET_META_KEY];
+ * const trailhead = tool._meta?.[MCP_TOOL_TRAILHEAD_META_KEY];
  * ```
  */
-export const MCP_TOOL_FACET_META_KEY = 'ontrails/facet';
+export const MCP_TOOL_TRAILHEAD_META_KEY = 'ontrails/trailhead';
 
 /**
  * Metadata key used as a compatibility hint for clients that support
@@ -107,17 +113,29 @@ export interface DeriveMcpToolsOptions extends BaseSurfaceOptions {
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
-  readonly facets?: McpSurfaceFacetMap | undefined;
+  /**
+   * App-authored overlay envelopes (the same collection compile embeds in
+   * `trails.lock`). The `surfaces` overlay's `mcp` bindings are the authored,
+   * lockable default: list bindings become grouped trailhead tools and scalar
+   * bindings become tool synonyms.
+   */
+  readonly overlays?: readonly OverlayEnvelopeLike[] | undefined;
+  /**
+   * Call-site trailhead map. Override-in-context by design: when both this
+   * map and overlay `mcp` list bindings are present, the call-site map wins
+   * at runtime.
+   */
+  readonly trailheads?: McpSurfaceTrailheadMap | undefined;
   readonly layers?: readonly Layer[] | undefined;
   readonly resources?: ResourceOverrideMap | undefined;
   readonly resolvePermit?: ResolveMcpPermit | undefined;
 }
 
-export type McpSurfaceFacetTrailSelector = string | readonly string[];
+export type McpSurfaceTrailheadTrailSelector = string | readonly string[];
 
 /** Surface-side grouped entry over existing trails. */
-export interface McpSurfaceFacetDefinition {
-  readonly trails: McpSurfaceFacetTrailSelector;
+export interface McpSurfaceTrailheadDefinition {
+  readonly trails: McpSurfaceTrailheadTrailSelector;
   readonly description: string;
   readonly visibility?: 'public' | 'internal' | undefined;
   readonly descriptionStableThrough?: string | undefined;
@@ -129,8 +147,8 @@ export interface McpSurfaceFacetDefinition {
     | undefined;
 }
 
-export type McpSurfaceFacetMap = Readonly<
-  Record<string, McpSurfaceFacetDefinition>
+export type McpSurfaceTrailheadMap = Readonly<
+  Record<string, McpSurfaceTrailheadDefinition>
 >;
 
 export interface ResolveMcpPermitInput {
@@ -149,7 +167,7 @@ export interface McpToolDefinition {
   readonly _meta?: Record<string, unknown> | undefined;
   readonly annotations: McpAnnotations | undefined;
   readonly description: string | undefined;
-  readonly facetId?: string | undefined;
+  readonly trailheadId?: string | undefined;
   readonly handler: (
     args: Record<string, unknown>,
     extra: McpExtra
@@ -1025,19 +1043,19 @@ const buildToolDefinition = (
   };
 };
 
-const facetSelectors = (
-  selector: McpSurfaceFacetTrailSelector
+const trailheadSelectors = (
+  selector: McpSurfaceTrailheadTrailSelector
 ): readonly string[] => (typeof selector === 'string' ? [selector] : selector);
 
-const matchesFacetSelector = (
+const matchesTrailheadSelector = (
   trailId: string,
-  selector: McpSurfaceFacetTrailSelector
+  selector: McpSurfaceTrailheadTrailSelector
 ): boolean =>
-  facetSelectors(selector).some((pattern) =>
+  trailheadSelectors(selector).some((pattern) =>
     matchesTrailPattern(trailId, pattern)
   );
 
-interface FacetMemberTool {
+interface TrailheadMemberTool {
   readonly tool: McpToolDefinition;
   readonly trail: Trail<unknown, unknown, unknown>;
 }
@@ -1045,8 +1063,8 @@ interface FacetMemberTool {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value);
 
-const buildFacetInputSchema = (
-  members: readonly FacetMemberTool[]
+const buildTrailheadInputSchema = (
+  members: readonly TrailheadMemberTool[]
 ): Record<string, unknown> => ({
   anyOf: members.map(({ tool, trail }) => ({
     properties: {
@@ -1067,8 +1085,8 @@ const buildFacetInputSchema = (
   type: 'object',
 });
 
-const buildFacetOutputSchema = (
-  members: readonly FacetMemberTool[]
+const buildTrailheadOutputSchema = (
+  members: readonly TrailheadMemberTool[]
 ): Record<string, unknown> => {
   const outputSchemas = members.map(({ tool }) => tool.outputSchema ?? {});
   return {
@@ -1101,7 +1119,7 @@ const parseJsonTextContent = (
   }
 };
 
-const wrapFacetResult = (
+const wrapTrailheadResult = (
   trailId: string,
   result: McpToolResult
 ): McpToolResult => {
@@ -1121,9 +1139,9 @@ const wrapFacetResult = (
   };
 };
 
-const createFacetHandler = (
-  facetId: string,
-  members: readonly FacetMemberTool[]
+const createTrailheadHandler = (
+  trailheadId: string,
+  members: readonly TrailheadMemberTool[]
 ): McpToolDefinition['handler'] => {
   const byTrailId = new Map(
     members.map((member) => [member.trail.id, member.tool])
@@ -1135,7 +1153,7 @@ const createFacetHandler = (
     if (tool === undefined) {
       return mcpError(
         new ValidationError(
-          `MCP facet "${facetId}" received unknown trail selector "${trailId || '(missing)'}"`
+          `MCP trailhead "${trailheadId}" received unknown trail selector "${trailId || '(missing)'}"`
         )
       );
     }
@@ -1144,17 +1162,17 @@ const createFacetHandler = (
     if (!isRecord(input)) {
       return mcpError(
         new ValidationError(
-          `MCP facet "${facetId}" expects an object input for trail "${trailId}"`
+          `MCP trailhead "${trailheadId}" expects an object input for trail "${trailId}"`
         )
       );
     }
 
-    return wrapFacetResult(trailId, await tool.handler(input, extra));
+    return wrapTrailheadResult(trailId, await tool.handler(input, extra));
   };
 };
 
-const deriveFacetIntent = (
-  members: readonly FacetMemberTool[]
+const deriveTrailheadIntent = (
+  members: readonly TrailheadMemberTool[]
 ): Pick<Trail<unknown, unknown, unknown>, 'intent'>['intent'] => {
   if (members.every(({ trail }) => trail.intent === 'read')) {
     return 'read';
@@ -1165,14 +1183,14 @@ const deriveFacetIntent = (
   return 'write';
 };
 
-const deriveFacetAnnotations = (
-  definition: McpSurfaceFacetDefinition,
-  members: readonly FacetMemberTool[]
+const deriveTrailheadAnnotations = (
+  definition: McpSurfaceTrailheadDefinition,
+  members: readonly TrailheadMemberTool[]
 ): McpAnnotations | undefined => {
   const annotations = deriveAnnotations({
     description: definition.description,
     idempotent: false,
-    intent: deriveFacetIntent(members),
+    intent: deriveTrailheadIntent(members),
   } as Pick<
     Trail<unknown, unknown, unknown>,
     'description' | 'idempotent' | 'intent'
@@ -1180,15 +1198,15 @@ const deriveFacetAnnotations = (
   return Object.keys(annotations).length > 0 ? annotations : undefined;
 };
 
-const buildFacetMeta = (
-  facetId: string,
-  definition: McpSurfaceFacetDefinition,
+const buildTrailheadMeta = (
+  trailheadId: string,
+  definition: McpSurfaceTrailheadDefinition,
   memberTrailIds: readonly string[]
 ): Record<string, unknown> | undefined =>
   mergeMeta(
     {
-      [MCP_TOOL_FACET_META_KEY]: {
-        id: facetId,
+      [MCP_TOOL_TRAILHEAD_META_KEY]: {
+        id: trailheadId,
         memberTrailIds,
       },
     },
@@ -1197,23 +1215,23 @@ const buildFacetMeta = (
       : undefined
   );
 
-const buildFacetToolDefinition = (
+const buildTrailheadToolDefinition = (
   graph: Topo,
-  facetId: string,
-  definition: McpSurfaceFacetDefinition,
-  members: readonly FacetMemberTool[]
+  trailheadId: string,
+  definition: McpSurfaceTrailheadDefinition,
+  members: readonly TrailheadMemberTool[]
 ): McpToolDefinition => {
   const memberTrailIds = members.map(({ trail }) => trail.id);
   return {
-    _meta: buildFacetMeta(facetId, definition, memberTrailIds),
-    annotations: deriveFacetAnnotations(definition, members),
+    _meta: buildTrailheadMeta(trailheadId, definition, memberTrailIds),
+    annotations: deriveTrailheadAnnotations(definition, members),
     description: definition.description,
-    facetId,
-    handler: createFacetHandler(facetId, members),
-    inputSchema: buildFacetInputSchema(members),
+    handler: createTrailheadHandler(trailheadId, members),
+    inputSchema: buildTrailheadInputSchema(members),
     memberTrailIds,
-    name: deriveToolName(graph.name, facetId),
-    outputSchema: buildFacetOutputSchema(members),
+    name: deriveToolName(graph.name, trailheadId),
+    outputSchema: buildTrailheadOutputSchema(members),
+    trailheadId,
   };
 };
 
@@ -1256,71 +1274,135 @@ const validateToolBuild = (
   options: DeriveMcpToolsOptions
 ): Result<void, Error> => validateSurfaceTopo(graph, options);
 
-const collectFacetMembers = (
+const collectTrailheadMembers = (
   graph: Topo,
-  definition: McpSurfaceFacetDefinition,
+  definition: McpSurfaceTrailheadDefinition,
   availableTrails: readonly Trail<unknown, unknown, unknown>[],
   layers: readonly Layer[],
   options: DeriveMcpToolsOptions
-): readonly FacetMemberTool[] =>
+): readonly TrailheadMemberTool[] =>
   availableTrails
     .filter((trailItem) =>
-      matchesFacetSelector(trailItem.id, definition.trails)
+      matchesTrailheadSelector(trailItem.id, definition.trails)
     )
     .map((trailItem) => ({
       tool: buildToolDefinition(graph, trailItem, layers, options),
       trail: trailItem,
     }));
 
-const registerFacet = (
+const registerTrailhead = (
   graph: Topo,
-  facetId: string,
-  definition: McpSurfaceFacetDefinition,
-  members: readonly FacetMemberTool[],
+  trailheadId: string,
+  definition: McpSurfaceTrailheadDefinition,
+  members: readonly TrailheadMemberTool[],
   nameToSourceId: Map<string, string>,
   tools: McpToolDefinition[]
 ): Result<void, Error> => {
   if (members.length === 0) {
     return Result.err(
       new ValidationError(
-        `MCP facet "${facetId}" did not match any surface-eligible trails`
+        `MCP trailhead "${trailheadId}" did not match any surface-eligible trails`
       )
     );
   }
 
-  const toolName = deriveToolName(graph.name, facetId);
+  const toolName = deriveToolName(graph.name, trailheadId);
   const existingId = nameToSourceId.get(toolName);
   if (existingId !== undefined) {
     return Result.err(
       new ValidationError(
-        `MCP tool-name collision: "${existingId}" and "facet:${facetId}" both derive the tool name "${toolName}"`
+        `MCP tool-name collision: "${existingId}" and "trailhead:${trailheadId}" both derive the tool name "${toolName}"`
       )
     );
   }
 
-  nameToSourceId.set(toolName, `facet:${facetId}`);
-  tools.push(buildFacetToolDefinition(graph, facetId, definition, members));
+  nameToSourceId.set(toolName, `trailhead:${trailheadId}`);
+  tools.push(
+    buildTrailheadToolDefinition(graph, trailheadId, definition, members)
+  );
   return Result.ok();
 };
 
-const registerFacets = (
+/**
+ * Resolve the `surfaces` overlay's `mcp` bindings against the
+ * surface-eligible trails.
+ *
+ * Framework overlay/binding validation failures are represented as
+ * `Result.err` so `deriveMcpTools` keeps its no-throw contract.
+ */
+const resolveOverlayBindingExpansion = (
+  options: DeriveMcpToolsOptions,
+  availableTrails: readonly Trail<unknown, unknown, unknown>[]
+): Result<McpSurfaceBindingExpansion | undefined, Error> => {
+  try {
+    const bindings = resolveSurfaceOverlayBindings(options.overlays);
+    return Result.ok(
+      expandMcpSurfaceBindings(
+        bindings?.mcp,
+        availableTrails.map((trailItem) => trailItem.id)
+      )
+    );
+  } catch (error) {
+    return Result.err(
+      error instanceof Error
+        ? error
+        : new InternalError(
+            `MCP surface overlay resolution failed: ${String(error)}`
+          )
+    );
+  }
+};
+
+/**
+ * Construct call-site-equivalent trailhead definitions from the overlay's
+ * `mcp` list bindings.
+ *
+ * Each grouped binding becomes one definition with the expanded member trail
+ * ids as exact selectors and the shared derived default description, so the
+ * existing trailhead machinery builds the tool exactly as a call-site map
+ * would.
+ */
+const trailheadDefinitionsFromOverlay = (
+  expansion: McpSurfaceBindingExpansion | undefined
+): McpSurfaceTrailheadMap | undefined => {
+  if (expansion === undefined) {
+    return undefined;
+  }
+  const groups = Object.entries(expansion.groups);
+  if (groups.length === 0) {
+    return undefined;
+  }
+  return Object.fromEntries(
+    groups.map(([name, memberIds]) => [
+      name,
+      {
+        description: deriveMcpTrailheadDescription(memberIds),
+        trails: memberIds,
+      },
+    ])
+  );
+};
+
+const registerTrailheads = (
   graph: Topo,
+  trailheads: McpSurfaceTrailheadMap | undefined,
   options: DeriveMcpToolsOptions,
   layers: readonly Layer[],
   availableTrails: readonly Trail<unknown, unknown, unknown>[],
   nameToSourceId: Map<string, string>,
   tools: McpToolDefinition[]
 ): Result<ReadonlySet<string>, Error> => {
-  const { facets } = options;
   const consumedTrailIds = new Set<string>();
   const ownerByTrailId = new Map<string, string>();
 
-  if (facets === undefined || Object.keys(facets).length === 0) {
+  if (trailheads === undefined || Object.keys(trailheads).length === 0) {
     return Result.ok(consumedTrailIds);
   }
 
-  for (const [facetId, definition] of Object.entries(facets).toSorted()) {
-    const members = collectFacetMembers(
+  for (const [trailheadId, definition] of Object.entries(
+    trailheads
+  ).toSorted()) {
+    const members = collectTrailheadMembers(
       graph,
       definition,
       availableTrails,
@@ -1332,17 +1414,17 @@ const registerFacets = (
       if (previous !== undefined) {
         return Result.err(
           new ValidationError(
-            `MCP facet overlap: trail "${memberTrail.id}" is selected by facets "${previous}" and "${facetId}"`
+            `MCP trailhead overlap: trail "${memberTrail.id}" is selected by trailheads "${previous}" and "${trailheadId}"`
           )
         );
       }
-      ownerByTrailId.set(memberTrail.id, facetId);
+      ownerByTrailId.set(memberTrail.id, trailheadId);
       consumedTrailIds.add(memberTrail.id);
     }
 
-    const registered = registerFacet(
+    const registered = registerTrailhead(
       graph,
-      facetId,
+      trailheadId,
       definition,
       members,
       nameToSourceId,
@@ -1356,6 +1438,49 @@ const registerFacets = (
   return Result.ok(consumedTrailIds);
 };
 
+/**
+ * Register overlay tool synonyms: additional MCP tools whose names are the
+ * scalar binding names, sharing the target trail's schema, annotations, and
+ * handler.
+ */
+const registerSynonymTools = (
+  graph: Topo,
+  options: DeriveMcpToolsOptions,
+  layers: readonly Layer[],
+  availableTrails: readonly Trail<unknown, unknown, unknown>[],
+  synonyms: Readonly<Record<string, string>>,
+  nameToSourceId: Map<string, string>,
+  tools: McpToolDefinition[]
+): Result<void, Error> => {
+  const trailById = new Map(
+    availableTrails.map((trailItem) => [trailItem.id, trailItem])
+  );
+  for (const [name, trailId] of Object.entries(synonyms)) {
+    const trailItem = trailById.get(trailId);
+    if (trailItem === undefined) {
+      return Result.err(
+        new ValidationError(
+          `MCP overlay binding "${name}" targets trail "${trailId}", which is not surface-eligible`
+        )
+      );
+    }
+    const existingId = nameToSourceId.get(name);
+    if (existingId !== undefined) {
+      return Result.err(
+        new ValidationError(
+          `MCP tool-name collision: "${existingId}" and "binding:${name}" both use the tool name "${name}"`
+        )
+      );
+    }
+    nameToSourceId.set(name, `binding:${name}`);
+    tools.push({
+      ...buildToolDefinition(graph, trailItem, layers, options),
+      name,
+    });
+  }
+  return Result.ok();
+};
+
 const registerTools = (
   graph: Topo,
   options: DeriveMcpToolsOptions,
@@ -1364,18 +1489,27 @@ const registerTools = (
   const tools: McpToolDefinition[] = [];
   const nameToSourceId = new Map<string, string>();
   const availableTrails = eligibleTrails(graph, options);
-  const registeredFacets = registerFacets(
+  const expansion = resolveOverlayBindingExpansion(options, availableTrails);
+  if (expansion.isErr()) {
+    return expansion;
+  }
+  // Override-in-context: the call-site trailhead map wins over the authored
+  // overlay default whenever the caller supplies one.
+  const trailheads =
+    options.trailheads ?? trailheadDefinitionsFromOverlay(expansion.value);
+  const registeredTrailheads = registerTrailheads(
     graph,
+    trailheads,
     options,
     layers,
     availableTrails,
     nameToSourceId,
     tools
   );
-  if (registeredFacets.isErr()) {
-    return registeredFacets;
+  if (registeredTrailheads.isErr()) {
+    return registeredTrailheads;
   }
-  const consumedTrailIds = registeredFacets.value;
+  const consumedTrailIds = registeredTrailheads.value;
 
   for (const trailItem of availableTrails) {
     if (consumedTrailIds.has(trailItem.id)) {
@@ -1394,6 +1528,19 @@ const registerTools = (
     }
   }
 
+  const registeredSynonyms = registerSynonymTools(
+    graph,
+    options,
+    layers,
+    availableTrails,
+    expansion.value?.synonyms ?? {},
+    nameToSourceId,
+    tools
+  );
+  if (registeredSynonyms.isErr()) {
+    return registeredSynonyms;
+  }
+
   return Result.ok(tools);
 };
 

package/src/index.ts

@@ -3,12 +3,12 @@ export {
   MCP_TOOL_ERROR_META_KEY,
   MCP_TOOL_EXAMPLES_META_KEY,
   MCP_TOOL_DEFERRED_META_KEY,
-  MCP_TOOL_FACET_META_KEY,
+  MCP_TOOL_TRAILHEAD_META_KEY,
   deriveMcpTools,
   type DeriveMcpToolsOptions,
-  type McpSurfaceFacetDefinition,
-  type McpSurfaceFacetMap,
-  type McpSurfaceFacetTrailSelector,
+  type McpSurfaceTrailheadDefinition,
+  type McpSurfaceTrailheadMap,
+  type McpSurfaceTrailheadTrailSelector,
   type McpToolDefinition,
   type McpToolResult,
   type McpToolErrorMeta,
@@ -24,7 +24,7 @@ export {
   MCP_SURFACE_MAP_RESOURCE_URI,
   MCP_TRAIL_RESOURCE_PREFIX,
   buildMcpResources,
-  isMcpFacetTool,
+  isMcpTrailheadTool,
   type BuiltMcpResources,
   type McpResourceContent,
   type McpResourceDefinition,

package/src/resources.ts

@@ -7,7 +7,7 @@ import type { Topo, Trail } from '@ontrails/core';
 
 import {
   MCP_TOOL_DEFERRED_META_KEY,
-  MCP_TOOL_FACET_META_KEY,
+  MCP_TOOL_TRAILHEAD_META_KEY,
 } from './build.js';
 import type { McpToolDefinition } from './build.js';
 
@@ -74,7 +74,7 @@ export interface BuiltMcpResources {
 interface McpSurfaceMapTool {
   readonly annotations: McpToolDefinition['annotations'];
   readonly description: string | undefined;
-  readonly facetId?: string | undefined;
+  readonly trailheadId?: string | undefined;
   readonly inputSchema: Record<string, unknown>;
   readonly memberTrailIds?: readonly string[] | undefined;
   readonly name: string;
@@ -112,7 +112,7 @@ const projectSurfaceMapTool = (tool: McpToolDefinition): McpSurfaceMapTool => ({
   description: tool.description,
   inputSchema: tool.inputSchema,
   name: tool.name,
-  ...(tool.facetId === undefined ? {} : { facetId: tool.facetId }),
+  ...(tool.trailheadId === undefined ? {} : { trailheadId: tool.trailheadId }),
   ...(tool.memberTrailIds === undefined
     ? {}
     : { memberTrailIds: tool.memberTrailIds }),
@@ -323,14 +323,14 @@ export const buildMcpResources = (
 };
 
 /**
- * Return whether an MCP tool was projected from a surface facet.
+ * Return whether an MCP tool was projected from a surface trailhead.
  *
  * @example
  * ```ts
- * import { isMcpFacetTool } from '@ontrails/mcp';
+ * import { isMcpTrailheadTool } from '@ontrails/mcp';
  *
- * const facetTools = tools.filter(isMcpFacetTool);
+ * const trailheadTools = tools.filter(isMcpTrailheadTool);
  * ```
  */
-export const isMcpFacetTool = (tool: McpToolDefinition): boolean =>
-  tool._meta?.[MCP_TOOL_FACET_META_KEY] !== undefined;
+export const isMcpTrailheadTool = (tool: McpToolDefinition): boolean =>
+  tool._meta?.[MCP_TOOL_TRAILHEAD_META_KEY] !== undefined;

package/src/surface.ts

@@ -14,13 +14,14 @@ import {
 import type {
   BaseSurfaceOptions,
   Layer,
+  OverlayEnvelopeLike,
   ResourceOverrideMap,
   Topo,
   TrailContextInit,
 } from '@ontrails/core';
 
 import type {
-  McpSurfaceFacetMap,
+  McpSurfaceTrailheadMap,
   McpToolDefinition,
   ResolveMcpPermit,
 } from './build.js';
@@ -38,7 +39,19 @@ export interface CreateServerOptions extends BaseSurfaceOptions {
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
   readonly description?: string | undefined;
-  readonly facets?: McpSurfaceFacetMap | undefined;
+  /**
+   * App-authored overlay envelopes (the same collection compile embeds in
+   * `trails.lock`). The `surfaces` overlay's `mcp` bindings are the authored,
+   * lockable default: list bindings become grouped trailhead tools and scalar
+   * bindings become tool synonyms.
+   */
+  readonly overlays?: readonly OverlayEnvelopeLike[] | undefined;
+  /**
+   * Call-site trailhead map. Override-in-context by design: when both this
+   * map and overlay `mcp` list bindings are present, the call-site map wins
+   * at runtime.
+   */
+  readonly trailheads?: McpSurfaceTrailheadMap | undefined;
   readonly layers?: readonly Layer[] | undefined;
   readonly mcpResources?: McpResourcesConfig | false | undefined;
   readonly name?: string | undefined;
@@ -220,12 +233,13 @@ export const createServer = (
     configValues: options.configValues,
     createContext: options.createContext,
     exclude: options.exclude,
-    facets: options.facets,
     include: options.include,
     intent: options.intent,
     layers: options.layers,
+    overlays: options.overlays,
     resolvePermit: options.resolvePermit,
     resources: options.resources,
+    trailheads: options.trailheads,
     validate: options.validate,
   });
 

package/src/tool-name.ts

@@ -1,10 +1,13 @@
 /**
  * Derive MCP-safe tool names from app name + trail ID.
  *
- * MCP tool names must be [a-z0-9_]+. We prefix with the app name,
- * replace dots and hyphens with underscores, and lowercase everything.
+ * The derivation itself lives in `@ontrails/core` (`deriveMcpToolName`) so
+ * governance readers such as Warden's `surface-overlay-coherence` rule check
+ * collisions against the exact projection the MCP surface renders.
  */
 
+import { deriveMcpToolName } from '@ontrails/core';
+
 /**
  * Convert app name + trail ID to an MCP-safe tool name.
  *
@@ -12,8 +15,4 @@
  * deriveToolName("myapp", "entity.show") // "myapp_entity_show"
  * deriveToolName("dispatch", "patch.search") // "dispatch_patch_search"
  */
-export const deriveToolName = (appName: string, trailId: string): string => {
-  const prefix = appName.toLowerCase().replaceAll(/[.-]/g, '_');
-  const suffix = trailId.toLowerCase().replaceAll(/[.-]/g, '_');
-  return `${prefix}_${suffix}`;
-};
+export const deriveToolName = deriveMcpToolName;