@ontrails/trails 1.0.0-beta.30 → 1.0.0-beta.39

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # trails
 
+## 1.0.0-beta.39
+
+### Minor Changes
+
+- [`9518f5c`](https://github.com/outfitter-dev/trails/commit/9518f5cc892a87273a3bfdaa0d7319f98004ecb8): `trails regrade adjust <transition>` pulls a graduated transition back from consolidated history into an active plan minus the run ledger, preserving the stable transition id so subsequent applies append to the same history spine. Plan re-derivation (`regrade plan`) now carries `transitionId` forward from an existing active plan.
+- [`714939d`](https://github.com/outfitter-dev/trails/commit/714939d6ec143c55a1aba55b65bd11a8a2bfbf1e): Stacked/phased regrades ride the primary tooling: class-mode Regrade plans accept `include` path globs so one transition can be applied in scoped parts that all append to the same consolidated history, and an authored `--name` keys multi-class transitions to a clean transition-name filename instead of concatenated class ids.
+- [`65b362f`](https://github.com/outfitter-dev/trails/commit/65b362f65fa2a75e2121d1a8b31882d52fa0376b): Regrade history consolidates per transition, append-only: `regrade apply` appends a run entry stamped `{ planContentHash, lockHashAtRun }` to `.trails/regrade/history/<transition>.json` instead of overwriting lockhash-named files, identical re-runs are recognized as replays, the artifact carries a stable internal transition `id`, and `regrade check <transition>` verifies each recorded run at its own stamped lock. The report `history.status` union widens to `applied | checked | replay`.
+- [`7c05376`](https://github.com/outfitter-dev/trails/commit/7c05376a4ee2a66ef477d8f165205bf2fbbdc37f): `trails compile` and `trails validate` now collect adapter overlay overlays from the app module's `trailsOverlays` export and embed the validated facts as `overlays.<namespace>` in `trails.lock`, threading the registrations through every derivation site so compiled and freshly derived graphs stay hash-identical.
+- [`adf6419`](https://github.com/outfitter-dev/trails/commit/adf64191ea9e458d7405465ab6fa96ca72ab574c): Add `trails wayfind --overlay <namespace>`: a generic read of namespaced lock overlays (adapter-contributed facts) from saved artifacts, listing available namespaces on a miss — new fact families become inspectable with zero wayfinder edits.
+
+### Patch Changes
+
+- [`f42ca6e`](https://github.com/outfitter-dev/trails/commit/f42ca6e40b29155acec446e5bf44e52e014466bd): Hard cutover: the CLI consumes `cli` bindings from the app-authored surfaces overlay. Scalar bindings behave identically to the removed cliAliases (parity-tested) — the binding name splits on `.` into a transparent synonym command path for exactly one trail. List bindings arrive as command groups: each expanded member trail gets a group-prefixed route that dispatches the member trail with its identity preserved, and a singleton list stays a group. Expansion is fail-fast boundary validation: a scalar binding resolving to zero or multiple trails, or a group with an empty member union, is a `ValidationError` naming the binding. `DeriveTopoGraphOptions.cliAliases`, the `cliAliases`/`trailsCliAliases` app-module export convention, and the per-kind compile lift are deleted; `deriveCliCommands`/`createProgram` take `overlays` instead of `aliases`, and both topo-graph derivation pipelines expand the same bindings through one shared helper so runtime CLI routes and lock routes come from one semantic. A leftover legacy export is now a Warden error (`no-legacy-cli-alias-export`) naming the `surfaceOverlay({ cli: { ... } })` rewrite.
+
+  This is a breaking API removal shipped under the lockstep beta patch convention (pre-1.0 hard-cutover posture, zero external adoption); the removed options have no deprecation window by design.
+
+- [`bafde1f`](https://github.com/outfitter-dev/trails/commit/bafde1fc8172abb8d8617f69a3c7a70667626d10): Fresh derivations now collect app-module overlays through the shared channel compile uses. `@ontrails/adapter-kit` exports `resolveTrailsOverlays()`, the one reader of an app module's `trailsOverlays` export; the compile-path fresh app lease and Warden's fresh topo loading both go through it, making per-namespace drift asymmetry structurally impossible. Warden drift checks (`checkDrift` now accepts derive options carrying overlays) and the topo-aware rule context graph derive with the same overlays the committed lock embeds, so rules like `surface-overlay-coherence` fire on standard runs. Stale drift results name the drifted overlay namespaces (`DriftResult.driftedOverlayNamespaces`) and point at `trails compile` as the remediation.
+- [`b077fb7`](https://github.com/outfitter-dev/trails/commit/b077fb7ba6d9724cac6f0e59bc3fec9aec28984c): Add the export-restructure Regrade class family (TRL-1210). `export-restructure:cli-aliases` inverts legacy `cliAliases`/`trailsCliAliases` exports into `surfaceOverlay({ cli })` bindings inside the module's `trailsOverlays` export — adding the `@ontrails/core` import, deleting the legacy export, and routing anything it cannot prove safe (computed keys, spreads, in-module `aliases:` references) to `needs-review` with the exact target shape named. `export-restructure:mcp-trailheads` projects call-site MCP trailhead maps into `surfaceOverlay({ mcp })` group bindings: it rewrites in place when the same module exports `trailsOverlays`, and otherwise emits a classified `needs-review` handoff naming the module-overlay target while the call-site map stays as the richer-metadata override-in-context. Warden's fix-class union grows to `'export-restructure' | 'term-rewrite'`, `no-legacy-cli-alias-export` now advertises the `export-restructure` class, and `loadWardenRegradeClasses` supersedes `loadWardenTermRewriteClasses` (still exported) as the full Warden-routed class loader. Class-mode Regrade also gains the full plan lifecycle: `trails regrade plan --type class --class-ids ...` writes a `.trails/regrade/<slug>.json` plan carrying class ids, scope, and intent, `regrade check` re-runs the dry run and gates on outstanding rewrites or review, and `regrade apply` applies and graduates the plan to `.trails/regrade/history/<slug>-<hash>.json` — the same plan → check → apply → history evidence trail vocabulary regrades already had, now available to structural transforms. The class family ships for downstream apps bridging the pre-1.0 gap, so pre-cutover alias exports and trailhead maps migrate mechanically instead of by hand.
+- [`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.
+
+- [`a0517ef`](https://github.com/outfitter-dev/trails/commit/a0517efa01014754b1dc307169b21ae71a6e3620): Fresh app loading now resolves extensionless relative imports the way Bun does at runtime, so runtime-valid apps stay operator-loadable (`trails compile`, `trails warden`, and every other fresh-load path). When a relative import cannot be resolved at all, the failure is an actionable `ValidationError` naming the importer file and specifier instead of an opaque redacted "Internal server error".
+- [`a89d469`](https://github.com/outfitter-dev/trails/commit/a89d4696aa78f3dda9394c14665ab3ea8c0f313c): Make `trails compile` → `trails validate` round-trip deterministically (TRL-1191). The per-user topo store no longer reuses previously stored JSON Schema bytes by zod definition hash — that hash cannot see `.describe()` metadata or object field order, so a warm store could serve pre-edit schema values into a freshly compiled lock and make `validate` report it stale immediately. Every snapshot now regenerates schema JSON from the live Zod schema, the store's graph hash goes through the same shared `deriveStableHash` path as `deriveTopoGraphHash`, and the committed `trails.lock` omits the wallclock `generatedAt` field so recompiling unchanged sources yields a byte-identical lock. `TopoGraph.generatedAt` is now optional; locks written by earlier versions still parse.
+- [`a89d469`](https://github.com/outfitter-dev/trails/commit/a89d4696aa78f3dda9394c14665ab3ea8c0f313c): Make the per-user topo store an honest cache (TRL-1196). Every snapshot now records a content fingerprint of the app source set (`topo_snapshots.source_fingerprint`, store schema v14), `trails compile` reports it in its output, and Wayfinder artifact loading compares it against a freshly derived fingerprint — a mismatch surfaces as a `topo-store-source-fingerprint-mismatch` stale reason instead of silently serving pre-edit facts. Compile derives everything from live source on every run, so a poisoned or stale store can never reach `trails.lock`, with or without `--force`.
+- [`a89d469`](https://github.com/outfitter-dev/trails/commit/a89d4696aa78f3dda9394c14665ab3ea8c0f313c): Add the lock round-trip invariant gate (TRL-1200): `trails release smoke --check lock-roundtrip` discovers every committed `trails.lock`, recompiles each against a cold per-user store in a temporary state home, and asserts `validate` is green and the recompiled lock is byte-identical to the committed one. Failure output names the diverging section and the `trails compile` command that fixes it — hand-editing a lock is never the remediation. Wired into `bun run check` and the CI Governance job via `bun run lock:roundtrip`.
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+### Patch Changes
+
+- [`09f15de`](https://github.com/outfitter-dev/trails/commit/09f15def8fcc8c28b0d604f436e6eeed46da8f37): Stage wide-net Regrade expansion candidates as structured plan review inventory with evidence, status, and pending counts.
+
+## 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.
+- [`26786a1`](https://github.com/outfitter-dev/trails/commit/26786a14acbe9ed03f69adbdac22968891e33df1): Persist vocabulary Regrade plan artifacts, expose plan/check/preview/apply flows across CLI and MCP, and write applied plan history for reviewed vocabulary migrations.
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+### Patch Changes
+
+- [`d67558b`](https://github.com/outfitter-dev/trails/commit/d67558bea3bfa363ed57e0f4091b6eccbf2a7710): Run governed AST symbol renames from the registry-backed `trails regrade` command path, including MCP parity, while preserving derived live API forms.
+
+## 1.0.0-beta.33
+
+### Patch Changes
+
+- [`04a6057`](https://github.com/outfitter-dev/trails/commit/04a6057502281fb81d1eb77df140d07181bfdd07): Clean generated release output by suppressing internal dependency cascade noise in package changelogs and rendering generated release PR and GitHub Release notes from the same Highlights, Changes, and Package Versions summary.
+- [`0c40138`](https://github.com/outfitter-dev/trails/commit/0c40138efb962e779710daa172bdfd756d9d992f): Harden vocabulary regrades by deferring Markdown code contexts for review and
+  exposing structured preserve rules through the Trails `regrade` command.
+- [`7d65189`](https://github.com/outfitter-dev/trails/commit/7d65189cc33408755fe07a0b5679f1ed01123455): Expose derived live-API preserve inventory in vocabulary Regrade runs and have the Trails operator regrade surface derive current facet API preserves from live topo and MCP surface facts.
+- [`04bb8a4`](https://github.com/outfitter-dev/trails/commit/04bb8a42af4ada51a74b1d8c83697db92035b5e9): Expose vocabulary Regrade occurrence dispositions and disposition summary counts alongside mechanical verdicts.
+
+  Accept explicit preserve-rule dispositions through the `trails regrade` CLI/MCP contract.
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- f3c4fef: Export a shared `escapeRegExp` helper from core and migrate first-party callers off local copies.
+- cb0a9d8: Export shared workspace package discovery helpers from core and migrate first-party discovery callers.
+- 8db145e: Move activation report derivation into Topographer and keep the Trails app
+  consuming the owner-held activation facts through a compatibility re-export.
+- 8e2603c: Rename read-only topo helper exports from `build*` to `derive*`.
+- 7a3a25f: Rename version lifecycle result paths from `file` to `filePath`.
+- fe72b84: Fold remaining Regrade and Warden scan-target surfaces onto the shared path-scope vocabulary.
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [8db145e]
+- Updated dependencies [2b819f4]
+- Updated dependencies [21c6dda]
+- Updated dependencies [860ef32]
+- Updated dependencies [fe72b84]
+  - @ontrails/adapter-kit@1.0.0-beta.32
+  - @ontrails/core@1.0.0-beta.32
+  - @ontrails/permits@1.0.0-beta.32
+  - @ontrails/warden@1.0.0-beta.32
+  - @ontrails/regrade@1.0.0-beta.32
+  - @ontrails/topographer@1.0.0-beta.32
+  - @ontrails/config@1.0.0-beta.32
+  - @ontrails/cli@1.0.0-beta.32
+  - @ontrails/commander@1.0.0-beta.32
+  - @ontrails/http@1.0.0-beta.32
+  - @ontrails/mcp@1.0.0-beta.32
+  - @ontrails/observe@1.0.0-beta.32
+  - @ontrails/tracing@1.0.0-beta.32
+  - @ontrails/wayfinder@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- e2f3d23: Default Regrade reports to actionable entries, add skip counts grouped by
+  reason, and expose an `includeEntries` option for full report inventories.
+- 9be2b7e: Load project-local Warden term-rewrite rules from the Regrade root so repo-owned
+  migration classes can run through `trails regrade`.
+- 47f782c: Add occurrence-level vocabulary regrade reports with plan, ledger,
+  and completion-gate facts. The Trails `regrade` operator command now supports
+  positional `<from> <to>` regrade runs and exposes the same capability through
+  the curated MCP surface.
+- 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.
+
+- 982a4d7: Add Regrade path-scope exclusion globs for vocabulary runs and expose them
+  through the `trails regrade` CLI/MCP contract.
+- 1540233: Add Regrade scan inventory summaries that group matched files by extension and
+  top-level path, with occurrence counts for vocabulary regrade reports.
+- de878bd: Let Trails project config provide default Regrade vocabulary scope settings,
+  with explicit CLI or MCP plan inputs overriding those defaults.
+- a0126d9: Add Warden `scope.exclude` globs through project config and the Trails CLI
+  wrapper so governance runs can exclude local notes, scratch space, and generated
+  state without dropping durable skills or plugin assets from scope.
+- a079073: Rename Regrade path-scope scan controls from `ignore` to `exclude` across CLI, MCP, and project config.
+- 6a26a08: Rename Warden governance scope controls from jurisdiction ignore settings to `scope.exclude` across config, CLI, and Trails surfaces.
+- Updated dependencies [e2f3d23]
+- Updated dependencies [9be2b7e]
+- Updated dependencies [47f782c]
+- Updated dependencies [ee9f3ae]
+- Updated dependencies [982a4d7]
+- Updated dependencies [1540233]
+- Updated dependencies [a0126d9]
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [a079073]
+- Updated dependencies [6a26a08]
+- Updated dependencies [38907cc]
+  - @ontrails/regrade@1.0.0-beta.31
+  - @ontrails/warden@1.0.0-beta.31
+  - @ontrails/mcp@1.0.0-beta.31
+  - @ontrails/wayfinder@1.0.0-beta.31
+  - @ontrails/core@1.0.0-beta.31
+  - @ontrails/commander@1.0.0-beta.31
+  - @ontrails/adapter-kit@1.0.0-beta.31
+  - @ontrails/cli@1.0.0-beta.31
+  - @ontrails/config@1.0.0-beta.31
+  - @ontrails/http@1.0.0-beta.31
+  - @ontrails/observe@1.0.0-beta.31
+  - @ontrails/permits@1.0.0-beta.31
+  - @ontrails/topographer@1.0.0-beta.31
+  - @ontrails/tracing@1.0.0-beta.31
+
 ## 1.0.0-beta.30
 
 ### Patch Changes

package/README.md

@@ -16,9 +16,9 @@ Common workflows:
 - `trails compile` writes root `trails.lock`.
 - `trails validate` checks root `trails.lock` for drift.
 - `trails wayfind`, `trails wayfind --trails --intent read`, `trails wayfind <id> --contract`, `trails wayfind <id> --deps`, `trails wayfind <id> --impact`, `trails wayfind pattern "wayfind.*"`, `trails wayfind query "release drift"`, `trails wayfind file <file> --outline`, and `trails wayfind diff ...` read graph artifacts and source outlines through Wayfinder for local navigation.
-- `trails schema <command...>` shows accepted CLI routes, aliases, flags, and schemas for an operator command.
-- `trails warden` runs Trails governance checks for contract and architecture drift.
-- `trails regrade --root-dir <path> --json` dry-runs downstream migration checks; add `--apply` only to write safe rewrites.
+- `trails schema <command...>` shows accepted CLI routes, aliases, flags, and schemas for an operator command or command namespace.
+- `trails warden` runs Trails governance checks for contract and architecture drift. Use `--scope-exclude <glob>` or project `warden.scope.exclude` config when local notes, scratch space, or generated state should not be governed by Warden.
+- `trails regrade plan <from> <to> --root-dir <path> --json` writes an active Regrade plan, `trails regrade plan --expand` stages wide-net review candidates in that plan, `trails regrade preview` reruns it without writing, and `trails regrade apply` consumes the plan and writes history. Use `plan --expand --dry-run` to inspect staged candidates without writing the active plan, and add `--dry-run` to `apply` to prove the apply path without mutating source. Use `trails regrade plans` and `trails regrade check` when a workspace has active plans that need inspection before apply. MCP exposes the same lifecycle as `trails_plan_regrade`, `trails_list_regrades`, `trails_check_regrade`, `trails_preview_regrade`, and `trails_apply_regrade`.
 - `trails guide` remains available for compatibility; prefer `trails wayfind --source live --module <app-module>` or saved-artifact Wayfinder reads for agent navigation.
 
 Trails is contract-first: define trails once with typed input, Result output, examples, and meta; the framework derives CLI, MCP, HTTP, and future surfaces from the same contracts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.30",
+  "version": "1.0.0-beta.39",
   "bin": {
     "trails": "./bin/trails.ts"
   },
@@ -27,25 +27,26 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/adapter-kit": "^1.0.0-beta.30",
-    "@ontrails/cli": "^1.0.0-beta.30",
-    "@ontrails/commander": "^1.0.0-beta.30",
-    "@ontrails/config": "^1.0.0-beta.30",
-    "@ontrails/core": "^1.0.0-beta.30",
-    "@ontrails/http": "^1.0.0-beta.30",
-    "@ontrails/mcp": "^1.0.0-beta.30",
-    "@ontrails/observe": "^1.0.0-beta.30",
-    "@ontrails/permits": "^1.0.0-beta.30",
-    "@ontrails/regrade": "^1.0.0-beta.30",
-    "@ontrails/topographer": "^1.0.0-beta.30",
-    "@ontrails/tracing": "^1.0.0-beta.30",
-    "@ontrails/warden": "^1.0.0-beta.30",
-    "@ontrails/wayfinder": "^1.0.0-beta.30",
+    "@ontrails/adapter-kit": "^1.0.0-beta.39",
+    "@ontrails/cli": "^1.0.0-beta.39",
+    "@ontrails/commander": "^1.0.0-beta.39",
+    "@ontrails/config": "^1.0.0-beta.39",
+    "@ontrails/core": "^1.0.0-beta.39",
+    "@ontrails/http": "^1.0.0-beta.39",
+    "@ontrails/mcp": "^1.0.0-beta.39",
+    "@ontrails/observe": "^1.0.0-beta.39",
+    "@ontrails/permits": "^1.0.0-beta.39",
+    "@ontrails/regrade": "^1.0.0-beta.39",
+    "@ontrails/topographer": "^1.0.0-beta.39",
+    "@ontrails/tracing": "^1.0.0-beta.39",
+    "@ontrails/warden": "^1.0.0-beta.39",
+    "@ontrails/wayfinder": "^1.0.0-beta.39",
     "commander": "^14.0.3",
     "typescript": "^5.9.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.30"
+    "@ontrails/cloudflare": "^1.0.0-beta.39",
+    "@ontrails/testing": "^1.0.0-beta.39"
   }
 }

package/src/app.ts

@@ -1,4 +1,4 @@
-import { topo } from '@ontrails/core';
+import { surfaceOverlay, topo } from '@ontrails/core';
 import {
   wayfindAdaptersTrail,
   wayfindContoursTrail,
@@ -7,7 +7,8 @@ import {
   wayfindDiffTrail,
   wayfindErrorsTrail,
   wayfindExamplesTrail,
-  wayfindFacetsTrail,
+  wayfindOverlayTrail,
+  wayfindTrailheadsTrail,
   wayfindImpactTrail,
   wayfindNearbyTrail,
   wayfindOverviewTrail,
@@ -111,15 +112,16 @@ const cliWayfinderSupportTrails = {
   wayfindDescribeTrail,
   wayfindErrorsTrail,
   wayfindExamplesTrail,
-  wayfindFacetsTrail,
   wayfindImpactTrail,
   wayfindNearbyTrail,
   wayfindOutlineTrail,
+  wayfindOverlayTrail,
   wayfindOverviewTrail,
   wayfindResourcesTrail,
   wayfindSearchTrail,
   wayfindSignalsTrail,
   wayfindSurfacesTrail,
+  wayfindTrailheadsTrail,
   wayfindTrailsTrail,
   wayfindVersionsTrail,
 };
@@ -138,8 +140,27 @@ export const trailsCliIncludedTrails = [
   ]),
 ];
 
-export const trailsCliAliases = {
-  'survey.diff': [['diff']],
-} as const;
+export const trailsOverlays = [
+  surfaceOverlay({
+    cli: { diff: 'survey.diff' },
+    // Authored, lockable default for the operator MCP `inspect` trailhead.
+    // The call-site map in `mcp-options.ts` overrides it at runtime with
+    // richer metadata (description, deferred loading) over the same members.
+    mcp: {
+      inspect: [
+        'survey',
+        'topo',
+        'guide',
+        'survey.brief',
+        'survey.diff',
+        'survey.resource',
+        'survey.signal',
+        'survey.surfaces',
+        'survey.trail',
+        'topo.history',
+      ],
+    },
+  }),
+];
 
 export const app = topo('trails', operatorTrails, cliWayfinderTrails);

package/src/cli.ts

@@ -21,7 +21,7 @@ import type { CreateProgramOptions } from '@ontrails/commander';
 import { resolvePermitFromBearerToken } from '@ontrails/permits';
 import { deriveTopoGraph } from '@ontrails/topographer';
 
-import { app, trailsCliAliases, trailsCliIncludedTrails } from './app.js';
+import { app, trailsCliIncludedTrails, trailsOverlays } from './app.js';
 import { resolveInputWithClack } from './clack.js';
 import { getRetiredTopoCommandDiagnostic } from './retired-topo-command.js';
 import { attachCompletionsInstallCommand } from './run-completions-install.js';
@@ -247,6 +247,7 @@ const wardenValueFlags = new Set([
   '--drafts',
   '--fail-on',
   '--format',
+  '--scope-exclude',
   '--lock',
   '--root-dir',
 ]);
@@ -301,11 +302,11 @@ const runSurfaceOnce = async (): Promise<void> => {
   const session = maybeInstallTraceSession();
   try {
     const surfaceOptions = {
-      aliases: trailsCliAliases,
       description: 'Agent-native, contract-first TypeScript framework',
       include: trailsCliIncludedTrails,
       name: 'trails',
       onResult: buildOnResult(session),
+      overlays: trailsOverlays,
       presets: [
         outputModePreset(),
         tracePreset(),

package/src/mcp-app.ts

@@ -6,6 +6,7 @@ import {
   wayfindDiffTrail,
   wayfindErrorsTrail,
   wayfindExamplesTrail,
+  wayfindOverlayTrail,
   wayfindImpactTrail,
   wayfindNearbyTrail,
   wayfindOverviewTrail,
@@ -32,6 +33,7 @@ export const trailsMcpApp = topo('trails', operatorTrails, {
   wayfindImpactTrail,
   wayfindNearbyTrail,
   wayfindOutlineTrail,
+  wayfindOverlayTrail,
   wayfindOverviewTrail,
   wayfindResourcesTrail,
   wayfindSearchTrail,

package/src/mcp-options.ts

@@ -1,4 +1,9 @@
-import type { CreateServerOptions, McpSurfaceFacetMap } from '@ontrails/mcp';
+import type {
+  CreateServerOptions,
+  McpSurfaceTrailheadMap,
+} from '@ontrails/mcp';
+
+import { trailsOverlays } from './app.js';
 
 export const trailsMcpIncludedTrails = [
   'adapter.check',
@@ -14,6 +19,12 @@ export const trailsMcpIncludedTrails = [
   'doctor',
   'draft.promote',
   'guide',
+  'adjust.regrade',
+  'apply.regrade',
+  'check.regrade',
+  'list.regrades',
+  'plan.regrade',
+  'preview.regrade',
   'release.check',
   'release.smoke',
   'revise',
@@ -46,7 +57,7 @@ export const trailsMcpIncludedTrails = [
   'wayfind.trails',
 ] as const;
 
-export const trailsMcpFacets = {
+export const trailsMcpTrailheads = {
   inspect: {
     description:
       'Inspect saved topo structure, resources, signals, surfaces, and diffs.',
@@ -64,13 +75,17 @@ export const trailsMcpFacets = {
       'topo.history',
     ],
   },
-} satisfies McpSurfaceFacetMap;
+} satisfies McpSurfaceTrailheadMap;
 
 export const trailsMcpSurfaceOptions = {
   description:
-    'Trails framework operator surface. Use MCP resources for cold context, direct tools for high-signal work, and the inspect facet for saved topo reads.',
-  facets: trailsMcpFacets,
+    'Trails framework operator surface. Use MCP resources for cold context, direct tools for high-signal work, and the inspect trailhead for saved topo reads.',
   include: trailsMcpIncludedTrails,
   mcpResources: { examples: true, graph: true, surfaceMap: true },
   name: 'trails',
+  // The overlay authors the lockable `inspect` default; the call-site map
+  // below is the runtime override-in-context with richer metadata
+  // (description, deferred loading) over the same member selectors.
+  overlays: trailsOverlays,
+  trailheads: trailsMcpTrailheads,
 } satisfies CreateServerOptions;

package/src/regrade/config.ts

@@ -0,0 +1,152 @@
+import { loadTrailsConfigValue } from '@ontrails/config';
+import {
+  InternalError,
+  Result,
+  ValidationError,
+  pathScopeSchema,
+} from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import { z } from 'zod';
+
+export const regradeConfigSchema = z
+  .object({
+    scope: pathScopeSchema.optional(),
+  })
+  .default({});
+
+export type RegradeConfig = z.output<typeof regradeConfigSchema>;
+
+interface RegradeConfigLoadResult {
+  readonly config?: RegradeConfig;
+  readonly configPath?: string;
+}
+
+interface ResolvableConfig {
+  readonly resolve: (options?: {
+    readonly cwd?: string;
+    readonly env?: Record<string, string | undefined>;
+  }) => unknown;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isResultLike = (
+  value: unknown
+): value is {
+  readonly error?: unknown;
+  readonly isErr: () => boolean;
+  readonly isOk: () => boolean;
+  readonly value?: unknown;
+} =>
+  isRecord(value) &&
+  typeof value['isOk'] === 'function' &&
+  typeof value['isErr'] === 'function';
+
+const isResolvableConfig = (value: unknown): value is ResolvableConfig =>
+  isRecord(value) && typeof value['resolve'] === 'function';
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const extractRegradeConfig = (
+  value: unknown
+): TrailsResult<RegradeConfig | undefined, ValidationError> => {
+  if (!(isRecord(value) && 'regrade' in value)) {
+    return Result.ok();
+  }
+
+  const parsed = regradeConfigSchema.safeParse(value['regrade']);
+  if (parsed.success) {
+    return Result.ok(parsed.data);
+  }
+
+  return Result.err(
+    new ValidationError('Invalid regrade config in Trails config file.', {
+      context: { issues: parsed.error.issues },
+    })
+  );
+};
+
+export const loadRegradeConfig = async ({
+  configPath,
+  env = {},
+  rootDir,
+}: {
+  readonly configPath?: string | undefined;
+  readonly env?: Record<string, string | undefined> | undefined;
+  readonly rootDir: string;
+}): Promise<
+  TrailsResult<RegradeConfigLoadResult, InternalError | ValidationError>
+> => {
+  try {
+    const loaded = await loadTrailsConfigValue({
+      configPath,
+      rootDir,
+    });
+    const exported = loaded.value;
+    if (exported === undefined) {
+      return Result.ok({});
+    }
+
+    if (isResolvableConfig(exported)) {
+      const resolved = await exported.resolve({ cwd: rootDir, env });
+      if (isResultLike(resolved)) {
+        if (resolved.isErr()) {
+          return Result.err(
+            new InternalError(
+              `Failed to resolve regrade config: ${errorMessage(resolved.error)}`
+            )
+          );
+        }
+        const configResult = extractRegradeConfig(resolved.value);
+        if (configResult.isErr()) {
+          return configResult;
+        }
+        return Result.ok({
+          ...(configResult.value === undefined
+            ? {}
+            : { config: configResult.value }),
+          ...(loaded.configPath === undefined
+            ? {}
+            : { configPath: loaded.configPath }),
+        });
+      }
+
+      const configResult = extractRegradeConfig(resolved);
+      if (configResult.isErr()) {
+        return configResult;
+      }
+      return Result.ok({
+        ...(configResult.value === undefined
+          ? {}
+          : { config: configResult.value }),
+        ...(loaded.configPath === undefined
+          ? {}
+          : { configPath: loaded.configPath }),
+      });
+    }
+
+    const configResult = extractRegradeConfig(exported);
+    if (configResult.isErr()) {
+      return configResult;
+    }
+    return Result.ok({
+      ...(configResult.value === undefined
+        ? {}
+        : { config: configResult.value }),
+      ...(loaded.configPath === undefined
+        ? {}
+        : { configPath: loaded.configPath }),
+    });
+  } catch (error) {
+    return Result.err(
+      new InternalError(
+        `Failed to load regrade config: ${errorMessage(error)}`,
+        {
+          cause: error instanceof Error ? error : new Error(String(error)),
+        }
+      )
+    );
+  }
+};