@ontrails/trails 1.0.0-beta.12 → 1.0.0-beta.13

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # trails
 
+## 1.0.0-beta.13
+
+### Patch Changes
+
+- Updated dependencies [6944147]
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.13
+  - @ontrails/cli@1.0.0-beta.13
+  - @ontrails/schema@1.0.0-beta.13
+  - @ontrails/warden@1.0.0-beta.13
+  - @ontrails/logging@1.0.0-beta.13
+
 ## 1.0.0-beta.12
 
 ### Patch Changes
@@ -17,17 +29,17 @@
 
 - Add services as a first-class primitive.
 
-  Services make infrastructure dependencies declarative, injectable, and governable. Define a service with `service()`, declare it on a trail with `services: [db]`, and access it with `db.from(ctx)` or `ctx.service()`.
+  Services make infrastructure dependencies declarative, injectable, and governable. Define a service with `provision()`, declare it on a trail with `provisions: [db]`, and access it with `db.from(ctx)` or `ctx.provision()`.
 
-  **Core:** `service()` factory, `ServiceSpec<T>`, `ServiceContext`, singleton resolution in `executeTrail`, in-flight creation dedup, `isService` guard, `findDuplicateServiceId`, topo service discovery and validation, `services` field on trail specs.
+  **Core:** `provision()` factory, `ServiceSpec<T>`, `ServiceContext`, singleton resolution in `executeTrail`, in-flight creation dedup, `isService` guard, `findDuplicateServiceId`, topo service discovery and validation, `services` field on trail specs.
 
-  **Testing:** Auto-resolution of `mock` factories in `testAll`, `testExamples`, `testContracts`, and `testFollows`. Explicit `services` overrides with correct precedence (`explicit > ctx.extensions > auto-mock`). Service mock propagation through follow graphs.
+  **Testing:** Auto-resolution of `mock` factories in `testAll`, `testExamples`, `testContracts`, and `testCrosses`. Explicit `services` overrides with correct precedence (`explicit > ctx.extensions > auto-mock`). Service mock propagation through crossing graphs.
 
-  **Warden:** `service-declarations` rule validates `db.from(ctx)` and `ctx.service()` usage matches declared `services: [...]`. `service-exists` rule validates declared service IDs resolve in project context. Scope-aware AST walking skips nested function boundaries.
+  **Warden:** `service-declarations` rule validates `db.from(ctx)` and `ctx.provision()` usage matches declared `provisions: [...]`. `service-exists` rule validates declared service IDs resolve in project context. Scope-aware AST walking skips nested function boundaries.
 
-  **Surfaces:** Service overrides thread through `dispatch` and `blaze` on CLI, MCP, and HTTP.
+  **Trailheads:** Service overrides thread through `run` and `trailhead` on CLI, MCP, and HTTP.
 
-  **Introspection:** Survey and surface map outputs include service graph. Topo exposes `.services`, `.getService()`, `.hasService()`, `.listServices()`, `.serviceIds()`, `.serviceCount`.
+  **Introspection:** Survey and trailhead map outputs include service graph. Topo exposes `.services`, `.getService()`, `.hasService()`, `.listServices()`, `.serviceIds()`, `.serviceCount`.
 
   **Docs:** ADR-009 accepted. Unified services guide, updated vocabulary, getting-started, architecture, and package READMEs.
 
@@ -75,9 +87,9 @@
 
 ### Minor Changes
 
-- HTTP surface and OpenAPI generation.
+- HTTP trailhead and OpenAPI generation.
 
-  **http**: New `@ontrails/http` package — Hono-based HTTP adapter. `blaze()` derives routes from trail IDs, maps intent to HTTP verbs (read→GET, write→POST, destroy→DELETE), and maps error taxonomy to status codes. Returns the Hono instance.
+  **http**: New `@ontrails/http` package — Hono-based HTTP connector. `trailhead()` derives routes from trail IDs, maps intent to HTTP verbs (read→GET, write→POST, destroy→DELETE), and maps error taxonomy to status codes. Returns the Hono instance.
 
   **schema**: Add `generateOpenApiSpec(topo)` — generates a complete OpenAPI 3.1 spec from the topo. Each trail becomes an operation with path, method, schemas, and error responses derived from the contract.
 
@@ -122,15 +134,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "bin": {
     "trails": "./bin/trails.ts"
   },

package/src/__tests__/create.test.ts

@@ -11,19 +11,19 @@ import { basename, dirname, join } from 'node:path';
 
 import { Result } from '@ontrails/core';
 
-import { addSurface } from '../trails/add-surface.js';
+import { addTrailhead } from '../trails/add-trailhead.js';
 import { addVerify } from '../trails/add-verify.js';
 import { createRoute } from '../trails/create.js';
 import { createScaffold } from '../trails/create-scaffold.js';
 import { isInsideProject } from '../trails/project.js';
 
 type Starter = 'empty' | 'entity' | 'hello';
-type Surface = 'cli' | 'mcp';
+type Trailhead = 'cli' | 'mcp';
 
 const makeTempProject = (): string =>
   join(
     tmpdir(),
-    `trails-blaze-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    `trails-create-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
   );
 
 const readJson = (dir: string, relativePath: string): Record<string, unknown> =>
@@ -68,43 +68,43 @@ const expectErr = <T>(result: Result<T, Error>): Error => {
   return result.error;
 };
 
-const runFollow = async (
+const runCross = async (
   id: string,
   input: unknown
 ): Promise<Result<unknown, Error>> => {
   switch (id) {
     case 'create.scaffold': {
-      return await createScaffold.run(input as never, {} as never);
+      return await createScaffold.blaze(input as never, {} as never);
     }
-    case 'add.surface': {
-      return await addSurface.run(input as never, {} as never);
+    case 'add.trailhead': {
+      return await addTrailhead.blaze(input as never, {} as never);
     }
     case 'add.verify': {
-      return await addVerify.run(input as never, {} as never);
+      return await addVerify.blaze(input as never, {} as never);
     }
     default: {
-      return Result.err(new Error(`Unknown follow target: ${id}`));
+      return Result.err(new Error(`Unknown cross target: ${id}`));
     }
   }
 };
 
-const runBlaze = (
+const runCreate = (
   projectDir: string,
   overrides?: Partial<{
     starter: Starter;
-    surfaces: readonly Surface[];
+    trailheads: readonly Trailhead[];
     verify: boolean;
   }>
 ) =>
-  createRoute.run(
+  createRoute.blaze(
     {
       dir: dirname(projectDir),
       name: basename(projectDir),
       starter: overrides?.starter ?? 'hello',
-      surfaces: [...(overrides?.surfaces ?? ['cli'])],
+      trailheads: [...(overrides?.trailheads ?? ['cli'])],
       verify: overrides?.verify ?? true,
     },
-    { follow: runFollow } as never
+    { cross: runCross } as never
   );
 
 const setupMinimalProject = (dir: string): void => {
@@ -177,7 +177,7 @@ const assertEntityStarter = (dir: string): void => {
       'src/trails/entity.ts',
       'src/trails/search.ts',
       'src/trails/onboard.ts',
-      'src/events/entity-events.ts',
+      'src/signals/entity-signals.ts',
       'src/store.ts',
     ],
     true
@@ -187,7 +187,7 @@ const assertEntityStarter = (dir: string): void => {
     "import * as entity from './trails/entity.js'",
     "import * as search from './trails/search.js'",
     "import * as onboard from './trails/onboard.js'",
-    "import * as entityEvents from './events/entity-events.js'",
+    "import * as entitySignals from './signals/entity-signals.js'",
   ]);
   expectContainsAll(readText(dir, 'src/trails/entity.ts'), [
     "import { Result, trail } from '@ontrails/core'",
@@ -204,12 +204,12 @@ const assertEntityStarter = (dir: string): void => {
   ]);
 };
 
-const assertMcpSurface = (dir: string): void => {
+const assertMcpTrailhead = (dir: string): void => {
   expectPaths(dir, ['src/mcp.ts'], true);
   expectPaths(dir, ['src/cli.ts'], false);
   expectContainsAll(readText(dir, 'src/mcp.ts'), [
-    "import { blaze } from '@ontrails/mcp'",
-    'await blaze(app)',
+    "import { trailhead } from '@ontrails/mcp'",
+    'await trailhead(app)',
   ]);
 
   const deps = readJson(dir, 'package.json')['dependencies'] as Record<
@@ -244,11 +244,11 @@ const withTempProject = async (
   }
 };
 
-describe('trails blaze', () => {
+describe('trails create', () => {
   describe('create mode', () => {
     test('generates project structure with defaults', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir));
+        expectOk(await runCreate(dir));
         assertDefaultProjectFiles(dir);
         assertCliPackage(dir);
         assertHelloApp(dir);
@@ -257,46 +257,46 @@ describe('trails blaze', () => {
 
     test('generates with entity starter', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { starter: 'entity' }));
+        expectOk(await runCreate(dir, { starter: 'entity' }));
         assertEntityStarter(dir);
       });
     });
 
-    test('generates with MCP surface', async () => {
+    test('generates with MCP trailhead', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { surfaces: ['mcp'] }));
-        assertMcpSurface(dir);
+        expectOk(await runCreate(dir, { trailheads: ['mcp'] }));
+        assertMcpTrailhead(dir);
       });
     });
 
     test('skips verification when verify is false', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { verify: false }));
+        expectOk(await runCreate(dir, { verify: false }));
         assertVerifySkipped(dir);
       });
     });
 
     test('generates with empty starter', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { starter: 'empty' }));
+        expectOk(await runCreate(dir, { starter: 'empty' }));
         assertEmptyStarter(dir);
       });
     });
   });
 
-  describe('add-surface mode', () => {
+  describe('add-trailhead mode', () => {
     test('adds MCP to existing project', async () => {
       await withTempProject(async (dir) => {
         setupMinimalProject(dir);
         const result = expectOk(
-          await addSurface.run({ dir, surface: 'mcp' }, {} as never)
+          await addTrailhead.blaze({ dir, trailhead: 'mcp' }, {} as never)
         );
 
         expect(result.created).toBe('src/mcp.ts');
         expect(result.dependency).toBe('@ontrails/mcp');
         expectPaths(dir, ['src/mcp.ts'], true);
         expectContainsAll(readText(dir, 'src/mcp.ts'), [
-          "import { blaze } from '@ontrails/mcp'",
+          "import { trailhead } from '@ontrails/mcp'",
         ]);
         const deps = readJson(dir, 'package.json')['dependencies'] as Record<
           string,
@@ -306,16 +306,18 @@ describe('trails blaze', () => {
       });
     });
 
-    test('detects already-blazed surface', async () => {
+    test('detects existing trailhead entrypoint', async () => {
       await withTempProject(async (dir) => {
         mkdirSync(join(dir, 'src'), { recursive: true });
         mkdirSync(join(dir, '.trails'), { recursive: true });
         writeFileSync(join(dir, 'src', 'mcp.ts'), 'existing content');
 
         const error = expectErr(
-          await addSurface.run({ dir, surface: 'mcp' }, {} as never)
+          await addTrailhead.blaze({ dir, trailhead: 'mcp' }, {} as never)
+        );
+        expect(error.message).toBe(
+          'MCP trailhead already exists. Nothing to do.'
         );
-        expect(error.message).toBe('MCP is already blazed. Nothing to do.');
       });
     });
   });

package/src/__tests__/guide.test.ts

@@ -9,6 +9,10 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 
 const helloTrail = trail('hello', {
+  blaze: (input) => {
+    const name = input.name ?? 'world';
+    return Result.ok({ message: `Hello, ${name}!` });
+  },
   description: 'Say hello',
   detours: {
     NotFoundError: ['search'],
@@ -28,10 +32,6 @@ const helloTrail = trail('hello', {
   input: z.object({ name: z.string().optional() }),
   intent: 'read',
   output: z.object({ message: z.string() }),
-  run: (input) => {
-    const name = input.name ?? 'world';
-    return Result.ok({ message: `Hello, ${name}!` });
-  },
 });
 
 const app = topo('test-app', { hello: helloTrail });

package/src/__tests__/survey.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from 'bun:test';
 
-import { Result, service, topo, trail } from '@ontrails/core';
+import { Result, provision, topo, trail } from '@ontrails/core';
 import {
-  generateSurfaceMap,
-  hashSurfaceMap,
-  diffSurfaceMaps,
+  generateTrailheadMap,
+  hashTrailheadMap,
+  diffTrailheadMaps,
 } from '@ontrails/schema';
-import type { SurfaceMap } from '@ontrails/schema';
+import type { TrailheadMap } from '@ontrails/schema';
 import { z } from 'zod';
 
 import {
@@ -25,6 +25,10 @@ import type {
 // ---------------------------------------------------------------------------
 
 const helloTrail = trail('hello', {
+  blaze: (input) => {
+    const name = input.name ?? 'world';
+    return Result.ok({ message: `Hello, ${name}!` });
+  },
   description: 'Say hello',
   detours: {
     NotFoundError: ['search'],
@@ -39,32 +43,28 @@ const helloTrail = trail('hello', {
   input: z.object({ name: z.string().optional() }),
   intent: 'read',
   output: z.object({ message: z.string() }),
-  run: (input) => {
-    const name = input.name ?? 'world';
-    return Result.ok({ message: `Hello, ${name}!` });
-  },
-  services: [
-    service('db.main', {
+  provisions: [
+    provision('db.main', {
       create: () => Result.ok({ source: 'factory' }),
     }),
   ],
 });
 
 const byeTrail = trail('bye', {
+  blaze: (input) => Result.ok({ message: `Goodbye, ${input.name}!` }),
   description: 'Say goodbye',
   input: z.object({ name: z.string() }),
   output: z.object({ message: z.string() }),
-  run: (input) => Result.ok({ message: `Goodbye, ${input.name}!` }),
 });
 
-const [dbService] = helloTrail.services;
-if (!dbService) {
+const [dbProvision] = helloTrail.provisions;
+if (!dbProvision) {
   throw new Error('Expected helloTrail to declare db.main');
 }
 
 const app = topo('test-app', {
   bye: byeTrail,
-  dbService,
+  dbProvision,
   hello: helloTrail,
 });
 
@@ -73,46 +73,46 @@ const app = topo('test-app', {
 // ---------------------------------------------------------------------------
 
 describe('trails survey', () => {
-  test('generateSurfaceMap includes all trails', () => {
-    const surfaceMap = generateSurfaceMap(app);
-    expect(surfaceMap.entries.length).toBe(3);
-    const ids = surfaceMap.entries.map((e) => e.id);
+  test('generateTrailheadMap includes all trails', () => {
+    const trailheadMap = generateTrailheadMap(app);
+    expect(trailheadMap.entries.length).toBe(3);
+    const ids = trailheadMap.entries.map((e) => e.id);
     expect(ids).toContain('hello');
     expect(ids).toContain('bye');
     expect(ids).toContain('db.main');
   });
 
-  test('surface map entries have expected fields', () => {
-    const surfaceMap = generateSurfaceMap(app);
-    const hello = surfaceMap.entries.find((e) => e.id === 'hello');
+  test('trailhead map entries have expected fields', () => {
+    const trailheadMap = generateTrailheadMap(app);
+    const hello = trailheadMap.entries.find((e) => e.id === 'hello');
     expect(hello).toBeDefined();
     expect(hello?.kind).toBe('trail');
     expect(hello?.intent).toBe('read');
     expect(hello?.exampleCount).toBe(1);
-    expect(hello?.services).toEqual(['db.main']);
+    expect(hello?.provisions).toEqual(['db.main']);
   });
 
   test('JSON output is valid JSON', () => {
-    const surfaceMap = generateSurfaceMap(app);
-    const json = JSON.stringify(surfaceMap, null, 2);
-    const parsed = JSON.parse(json) as SurfaceMap;
+    const trailheadMap = generateTrailheadMap(app);
+    const json = JSON.stringify(trailheadMap, null, 2);
+    const parsed = JSON.parse(json) as TrailheadMap;
     expect(parsed.version).toBe('1.0');
     expect(parsed.entries.length).toBe(3);
   });
 
-  test('hashSurfaceMap produces stable hash', () => {
-    const surfaceMap = generateSurfaceMap(app);
-    const hash1 = hashSurfaceMap(surfaceMap);
-    const hash2 = hashSurfaceMap(surfaceMap);
+  test('hashTrailheadMap produces stable hash', () => {
+    const trailheadMap = generateTrailheadMap(app);
+    const hash1 = hashTrailheadMap(trailheadMap);
+    const hash2 = hashTrailheadMap(trailheadMap);
     expect(hash1).toBe(hash2);
     // SHA-256 hex
     expect(hash1.length).toBe(64);
   });
 
-  test('diffSurfaceMaps detects added trails', () => {
-    const prev = generateSurfaceMap(topo('test', { hello: helloTrail }));
-    const curr = generateSurfaceMap(app);
-    const diff = diffSurfaceMaps(prev, curr);
+  test('diffTrailheadMaps detects added trails', () => {
+    const prev = generateTrailheadMap(topo('test', { hello: helloTrail }));
+    const curr = generateTrailheadMap(app);
+    const diff = diffTrailheadMaps(prev, curr);
 
     expect(diff.info.length).toBeGreaterThan(0);
     const addedBye = diff.info.find((e) => e.id === 'bye');
@@ -120,10 +120,10 @@ describe('trails survey', () => {
     expect(addedBye?.change).toBe('added');
   });
 
-  test('diffSurfaceMaps detects removed trails', () => {
-    const prev = generateSurfaceMap(app);
-    const curr = generateSurfaceMap(topo('test', { hello: helloTrail }));
-    const diff = diffSurfaceMaps(prev, curr);
+  test('diffTrailheadMaps detects removed trails', () => {
+    const prev = generateTrailheadMap(app);
+    const curr = generateTrailheadMap(topo('test', { hello: helloTrail }));
+    const diff = diffTrailheadMaps(prev, curr);
 
     expect(diff.hasBreaking).toBe(true);
     const removedBye = diff.breaking.find((e) => e.id === 'bye');
@@ -131,9 +131,9 @@ describe('trails survey', () => {
     expect(removedBye?.change).toBe('removed');
   });
 
-  test('diffSurfaceMaps returns empty for identical maps', () => {
-    const map = generateSurfaceMap(app);
-    const diff = diffSurfaceMaps(map, map);
+  test('diffTrailheadMaps returns empty for identical maps', () => {
+    const trailheadMap = generateTrailheadMap(app);
+    const diff = diffTrailheadMaps(trailheadMap, trailheadMap);
     expect(diff.entries.length).toBe(0);
     expect(diff.hasBreaking).toBe(false);
   });
@@ -153,8 +153,8 @@ describe('trails survey --brief', () => {
   test('report includes correct trail count', () => {
     const report = generateBriefReport(app);
     expect(report.trails).toBe(2);
-    expect(report.events).toBe(0);
-    expect(report.services).toBe(1);
+    expect(report.signals).toBe(0);
+    expect(report.provisions).toBe(1);
   });
 
   test('detects features in use', () => {
@@ -162,8 +162,8 @@ describe('trails survey --brief', () => {
     expect(report.features.outputSchemas).toBe(true);
     expect(report.features.examples).toBe(true);
     expect(report.features.detours).toBe(true);
-    expect(report.features.events).toBe(false);
-    expect(report.features.services).toBe(true);
+    expect(report.features.signals).toBe(false);
+    expect(report.features.provisions).toBe(true);
   });
 
   test('JSON output is valid', () => {
@@ -172,7 +172,7 @@ describe('trails survey --brief', () => {
     const parsed = JSON.parse(json) as BriefReport;
     expect(parsed.name).toBe('test-app');
     expect(parsed.trails).toBe(2);
-    expect(parsed.services).toBe(1);
+    expect(parsed.provisions).toBe(1);
   });
 
   test('empty app reports zero features', () => {
@@ -182,33 +182,33 @@ describe('trails survey --brief', () => {
     expect(report.features.outputSchemas).toBe(false);
     expect(report.features.examples).toBe(false);
     expect(report.features.detours).toBe(false);
-    expect(report.features.services).toBe(false);
+    expect(report.features.provisions).toBe(false);
   });
 });
 
 describe('trails survey detail', () => {
-  test('trail detail includes declared services, follow, and intent', () => {
+  test('trail detail includes declared provisions, crossings, and intent', () => {
     const detail = generateTrailDetail(helloTrail);
     const parsed = structuredClone(detail) as TrailDetailReport;
 
-    expect(parsed.follow).toEqual([]);
+    expect(parsed.crosses).toEqual([]);
     expect(parsed.intent).toBe('read');
-    expect(parsed.services).toEqual(['db.main']);
+    expect(parsed.provisions).toEqual(['db.main']);
   });
 });
 
-describe('trails survey services section', () => {
-  test('list output includes service lifetime and health status', () => {
+describe('trails survey provisions section', () => {
+  test('list output includes provision lifetime and health status', () => {
     const report = generateSurveyList(app);
     const parsed = structuredClone(report) as SurveyListReport;
-    const db = parsed.services.find((entry) => entry.id === 'db.main');
+    const db = parsed.provisions.find((entry) => entry.id === 'db.main');
 
-    expect(parsed.serviceCount).toBe(1);
+    expect(parsed.provisionCount).toBe(1);
     expect(db).toEqual({
       description: null,
       health: 'none',
       id: 'db.main',
-      kind: 'service',
+      kind: 'provision',
       lifetime: 'singleton',
       usedBy: ['hello'],
     });

package/src/__tests__/warden.test.ts

@@ -21,7 +21,7 @@ describe('trails warden', () => {
       writeFileSync(
         join(dir, 'good.ts'),
         `trail("hello", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     return Result.ok({ message: "hi" });
   }
 })`
@@ -54,7 +54,7 @@ describe('trails warden', () => {
       writeFileSync(
         join(dir, 'bad.ts'),
         `trail("x", {
-  run: async () => { throw new Error("boom"); }
+  blaze: async () => { throw new Error("boom"); }
 })`
       );
       const report = await runWarden({ driftOnly: true, rootDir: dir });

package/src/app.ts

@@ -1,6 +1,6 @@
 import { topo } from '@ontrails/core';
 
-import * as addSurface from './trails/add-surface.js';
+import * as addTrailhead from './trails/add-trailhead.js';
 import * as addTrail from './trails/add-trail.js';
 import * as addVerify from './trails/add-verify.js';
 import * as create from './trails/create.js';
@@ -16,7 +16,7 @@ export const app = topo(
   warden,
   create,
   createScaffold,
-  addSurface,
+  addTrailhead,
   addVerify,
   addTrail
 );

package/src/clack.ts

@@ -1,7 +1,7 @@
 /**
  * Clack-backed input resolver for the Trails CLI.
  *
- * This stays at the app layer so @ontrails/cli remains prompt-library agnostic.
+ * This stays at the app gate so @ontrails/cli remains prompt-library agnostic.
  */
 
 import type { Field, InputResolver, ResolveInputOptions } from '@ontrails/cli';

package/src/cli.ts

@@ -1,11 +1,11 @@
 import { outputModePreset } from '@ontrails/cli';
-import { blaze } from '@ontrails/cli/commander';
+import { trailhead } from '@ontrails/cli/commander';
 
 import { app } from './app.js';
 import { resolveInputWithClack } from './clack.js';
 
 // oxlint-disable-next-line require-hook -- CLI entry point
-blaze(app, {
+trailhead(app, {
   description: 'Agent-native, contract-first TypeScript framework',
   name: 'trails',
   presets: [outputModePreset()],

package/src/trails/add-trail.ts

@@ -29,7 +29,7 @@ export const ${id.replaceAll('.', '_')} = trail('${id}', {
       name: 'TODO: add example',
     },
   ],
-  run: async (input) => {
+  blaze: async (input) => {
     return Result.ok({ message: 'TODO' });
   },
   input: z.object({}),${intentLine}
@@ -64,18 +64,7 @@ const writeWithDirs = async (
 };
 
 export const addTrail = trail('add.trail', {
-  description: 'Scaffold a new trail with tests and examples',
-  input: z.object({
-    id: z.string().describe('Trail ID (e.g., entity.update)'),
-    intent: z
-      .enum(['read', 'write', 'destroy'])
-      .default('write')
-      .describe('Trail intent'),
-  }),
-  output: z.object({
-    created: z.array(z.string()),
-  }),
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     const { id } = input;
     const moduleName = id.replaceAll('.', '-');
     const cwd = resolve(ctx.cwd ?? '.');
@@ -91,4 +80,15 @@ export const addTrail = trail('add.trail', {
 
     return Result.ok({ created: [...files.keys()] });
   },
+  description: 'Scaffold a new trail with tests and examples',
+  input: z.object({
+    id: z.string().describe('Trail ID (e.g., entity.update)'),
+    intent: z
+      .enum(['read', 'write', 'destroy'])
+      .default('write')
+      .describe('Trail intent'),
+  }),
+  output: z.object({
+    created: z.array(z.string()),
+  }),
 });