trails

Imported from outfitter-dev/trails (plugin/skills/trails/SKILL.md). Install upstream with npx skills add outfitter-dev/trails --skill trails. Copyright stays with the author.

Trails

Contract-first TypeScript framework. Define a trail once with typed input, Result output, examples, meta, and an implementation that establishes how it runs — then surface it on CLI, MCP, or HTTP today, with WebSocket planned on the same contract-first model.

Quick Start

// 1. Define a trail
const greet = trail('greet', {
  input: z.object({ name: z.string().describe('Who to greet') }),
  output: z.object({ message: z.string() }),
  intent: 'read',
  examples: [{ name: 'Basic', input: { name: 'World' }, expected: { message: 'Hello, World!' } }],
  implementation: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
});

// 2. Collect into topo
const graph = topo('myapp', greetModule);

// 3. Open surfaces
await surface(graph);        // CLI — from @ontrails/commander
// await surface(graph);     // MCP — from @ontrails/mcp
// await surface(graph, { port: 3000 }); // HTTP — from @ontrails/hono or @ontrails/http/bun

// 4. Headless execution (no surface needed)
const result = await run(graph, 'greet', { name: 'Alice' });

// 5. Test
testAll(graph);            // Examples + contract suite in one line

Lexicon

Use these terms — they are non-negotiable in Trails codebases.

Package Orientation

Current public packages are lockstep at the same Trails framework version.

• Core model: @ontrails/core owns Result, errors, trail/signal/entity/topo contracts, resources, layers, execution, validation, and adapter ports.
• Surfaces: @ontrails/commander, @ontrails/mcp, @ontrails/hono, and @ontrails/http/bun open the same topo on CLI, MCP, Hono HTTP, or Bun-native HTTP. @ontrails/http owns shared route derivation, OpenAPI, and the Web Fetch kernel; @ontrails/cli owns the framework-agnostic CLI command model; @ontrails/vite adapts Trails surfaces for Vite projects.
• Infrastructure: @ontrails/config, @ontrails/permits, @ontrails/store, and @ontrails/drizzle cover config, authorization, schema-derived stores, and Drizzle SQLite bindings.
• Observability: @ontrails/observability defines sink contracts; its /dev and /otel subpaths provide developer-state and OTel support, while /logtape and /pino are temporary sink adapters.
• Ecosystem: @ontrails/testing provides contract tests and surface harnesses; @ontrails/topography owns TopoGraphs, semantic diffing, lock manifests, topo-store persistence, and Wayfind graph-read query APIs; @ontrails/warden owns governance rules.
• Stable install policy: Normal 0.x releases use the npm latest tag. Use the exact package pins in Getting Started. The 0.x line permits documented API changes in minor releases; patches preserve compatibility. Existing 1.0 beta ranges require an explicit manifest migration.

Agent Wayfinding

When saved Topography artifacts can answer a graph question, use Wayfinder before raw text search:

trails wayfind --overview --root-dir . --json
trails wayfind --trails --intent read --root-dir . --json
trails wayfind <trail-id> --contract --root-dir . --json
trails wayfind <trail-id> --deps --root-dir . --json
trails wayfind <trail-id> --impact --map --root-dir . --json
trails schema wayfind

• Start with trails wayfind --overview to learn artifact source, freshness, and graph counts.
• Use the selected operator CLI shape for filtered discovery: trails wayfind --trails, --resources, --signals, --surfaces, --trailheads, --entities, --errors, or --adapter <package>. Attach bounded related facts with --include adapters, errors, examples, surfaces, or versions. Topography may expose graph-query APIs beyond the operator CLI/MCP selection; check trails schema wayfind before constructing shell calls.
• Use trails schema <command...> when you need accepted CLI routes, aliases, flags, and schemas before constructing shell calls.
• Use wayfind.describe for a full saved entity record and wayfind.contract for a trail or version input/output/intent summary.
• Use wayfind.nearby, wayfind.impact, and wayfind.diff for relation context, blast-radius reads, and explicit saved-baseline comparison.
• Use trails wayfind query "<phrase>" for indexed text queries. Treat Wayfinder as graph-read only; do not assume semantic search, signposts, or implications exist in v0.

Wayfinder trails are internal by default. Host apps expose selected queries deliberately, usually as read-only operator tools or MCP resources protected by the host's authorization boundary. Fall back to rg, qmd, source reads, or a fresh compile when Wayfinder reports missing or stale artifacts, when the task needs source code that Topography does not derive, or when writing artifacts is outside your current authority.

Creating Trails

Atomic vs Composite Trails

• Atomic trail: does one thing. (input, ctx) => Result. Default choice.
• Composite trail: composes other trails. Declares composes: [...], uses ctx.compose().
• Runnable trail: an authored contract with an implementation. The runtime runs trails, not implementations.

Trail ID Conventions

Dotted, lowercase, verb-last: entity.show, math.add, search. Dots become CLI subcommands and MCP tool name segments.

Input Schema

Every field gets .describe() — this becomes --help text, MCP descriptions, and form labels.

input: z.object({
  name: z.string().describe('Entity name to look up'),
  limit: z.number().default(20).describe('Maximum results'),
})

Output Schema

Required for MCP and HTTP surfaces. Define what Result.ok returns.

Intent and Flags

Examples

Each example is both documentation AND a test case:

• Full match: expected: { ... } — deep equals
• Schema-only: no expected — validates against output schema
• Error match: error: 'NotFoundError' — asserts error type

See contract-patterns.md for detailed patterns. Copy from trail.md or composition.md.

Surfaces

Adding a surface is a surface() call, not an architecture change. The framework derives everything from the trail contract.

CLI: Flags from Zod, subcommands from dotted IDs, exit codes from error taxonomy.

import { surface } from '@ontrails/commander';
await surface(graph);

Use cli on a trail only for canonical command overrides or trail-owned aliases that still normalize into the same trail contract. String aliases are sibling leaf aliases (find beside search); string-array aliases are absolute command paths (['wf', 'search']). Author app-owned compatibility routes in an exported trailsOverlays = [surfaceOverlay({ cli: { 'wf.search': 'wayfind.search' } })] in the app module, then pass trailsOverlays to the CLI surface's overlays option. Compile, validate, Wayfinder, and trails schema then inspect the same routes the runtime CLI accepts. See CLI surface.

Treat aliases, future input mappings, and trailheads as surface accommodations: render-level fit adjustments, not alternate behavior. The trail stays the capability. A surface entry is the invocable affordance on a surface; an approach is the way a caller reaches it. Aliases add alternate approaches to the same trail, input mappings normalize surface-shaped input into the same trail input, and trailheads group several trails into one entry while preserving the selected trail ID. Use the ADR-0050 test: if the fit would change intent, permits, errors, outputs, lifecycle, side effects, or hide which trail is running, call it a trail fork and author a distinct or composing trail instead.

Classify surface-fit work before editing:

MCP: Tool names from trail IDs, JSON Schema from Zod, annotations from intent, idempotency, and description.

import { surface } from '@ontrails/mcp';
await surface(graph);

Dense MCP surfaces may use trailheads to group related trails into fewer agent-facing tools. A trailhead is surface rendering configuration, not a core Facet primitive and not a new domain operation. It groups and selects without merging. Author it in MCP surface options, call it with { trail, input }, and expect successful results as { trail, output } so the underlying trail stays visible.

await surface(graph, {
  trailheads: {
    governance: {
      description: 'Run project diagnostics and Warden guidance.',
      mcp: { loading: 'deferred' },
      trails: ['doctor', 'warden', 'warden.guide'],
    },
  },
  mcpResources: { examples: true, surfaceMap: true },
});

Use trails://surface-map and per-trail MCP resources for cold context before guessing at grouped affordances. Adapter-kit may validate resolved derived evidence for future surface adapters, but it does not define or author trailheads. Do not invent facet(), overlapsWith, or adapter-kit facet config.

HTTP: Routes from trail IDs (dots become path segments), verbs from intent, error responses from taxonomy. Use Hono for framework portability or Bun-native HTTP when you want Bun serving without a third-party runtime; both share the @ontrails/http route/fetch kernel.

import { surface } from '@ontrails/hono';
await surface(graph, { port: 3000 });

import { surface } from '@ontrails/http/bun';
await surface(graph, { port: 3000 });

WebSocket is planned, not shipped. See the CLI surface docs, the MCP surface docs, and the HTTP package docs for derivation details.

Resources

Resources declare infrastructure dependencies — databases, API clients, caches — as first-class primitives alongside trails and signals.

Define a resource with resource():

const db = resource('db.main', {
  create: (resourceCtx) => Result.ok(openDatabase(resourceCtx.env?.DATABASE_URL)),
  dispose: (conn) => conn.close(),
  health: (conn) => conn.ping(),
  mock: () => createInMemoryDb(),
});

The create factory receives ResourceContext (env, cwd, workspaceRoot, and validated config when the resource declares a config schema — not the full TrailContext). Resources are singletons, resolved once per process and cached.

Declare on trails with resources: [...]:

const search = trail('search', {
  resources: [db],
  input: z.object({ query: z.string() }),
  output: z.array(z.object({ id: z.string(), title: z.string() })),
  implementation: async (input, ctx) => {
    const conn = db.from(ctx);
    return Result.ok(await conn.search(input.query));
  },
});

Access via db.from(ctx) (typed, preferred) or ctx.resource<Database>('db.main') (dynamic escape hatch).

Test with zero config — resources with mock factories auto-resolve in testAll(graph). Mark live-only dependencies with unmockable: { reason } and provide explicit overrides for examples or contracts that need them.

testAll(graph, () => ({ resources: { 'db.main': createSpecialTestDb() } }));

Governance: The warden enforces resource-declarations (usage matches declarations) and resource-exists (resource IDs resolve in the topo).

See contract-patterns.md for declaration patterns and testing-patterns.md for mock strategies.

Testing

testAll(graph) runs the full contract suite in one line:

1. Topo validation (composes, schemas, signals, resources)
2. Example execution (every example as an assertion)
3. Contract checks (output matches schema)
4. Detour verification (targets exist)

TDD workflow: Define trail with examples → run tests (red) → implement (green) → refactor.

Edge cases go in testTrail(trail, scenarios). Use createComposeContext() to mock ctx.compose for composite trail unit tests. Surface integration uses @ontrails/testing/cli, @ontrails/testing/mcp, @ontrails/testing/http, and @ontrails/testing/surface-parity.

See testing-patterns.md for the full testing API.

Error Taxonomy

17 fixed-category error classes across 10 categories, plus the dynamic RetryExhaustedError wrapper, with deterministic mapping to exit codes, HTTP status, and JSON-RPC codes:

RetryExhaustedError is dynamic: it wraps another TrailsError, inherits the wrapped error's category for surface mappings, and always reports retryable: false.

Use the most specific class. Return Result.err(new XError(...)), never throw.

See error-taxonomy.md for constructor signatures and patterns. See common-pitfalls.md for anti-patterns.

Migration

Converting existing code to Trails:

1. Inventory handlers (routes, CLI commands, MCP tools)
2. Extract Zod input/output schemas
3. Convert implementations to return Result (replace throw/console.log/process.exit)
4. Compose into topo, open surfaces
5. Add examples, run testAll()
6. Run warden for governance

See migration-checklist.md for the detailed checklist.

Governance

The warden enforces conventions and detects drift:

trails warden          # Convention checks
trails warden --lock cached --no-lock-mutation # Governance against cached lock data
trails compile         # Regenerate a standalone or current-app trails.lock
trails compile --app my-app # Regenerate one configured app lock from a workspace root
trails validate        # Verify the current app, or every app from a workspace root
trails validate --app my-app # Verify one configured app from a workspace root

Each lock-owning app has its own root trails.lock. A configured workspace derives its app set from workspace.apps; it never owns an aggregate workspace-root lock.

For the current generated rule index, read warden-guide.md instead of relying on copied rule prose.

References