@orkestrel/scaffold 0.0.21 → 0.0.22

package/dist/host/guides/src/scaffold.md

@@ -226,7 +226,8 @@ application-browser projection. The root machinery selection never attaches a
 compilers section sets out.
 
 `ViteFacts` is the optional structural-fact slice shared by every root Vite compiler:
-`bin`, `integration`, and `service` each select their matching standalone project when `true`;
+`bin` and `integration` each select their matching standalone project when `true`, while `services`
+selects one standalone project for every listed vendor;
 `global` records the exact-case consumer-owned global-setup module and wires it into each eligible
 project; `showcase` records the exact-case consumer-owned showcase wrapper and selects only its
 generated browser machinery.
@@ -252,7 +253,7 @@ interface Blueprint {
 	readonly overrides: readonly Override[]
 	readonly bin: boolean
 	readonly integration: boolean
-	readonly service: boolean
+	readonly services: readonly string[]
 	readonly global: boolean
 	readonly showcase: boolean
 }
@@ -265,9 +266,10 @@ packages — a peer flagged `optional` also gets a `peerDependenciesMeta` entry.
 package-specific development dependencies merged over the generated baseline, and may carry any
 valid npm package name.
 
-`bin`, `integration`, `service`, `global`, and `showcase` are structural project facts. All five obey one law:
-each is `true` only when the workspace physically ships the directory or exact-case file that
-defines it — never because of the workspace's name, and never because a sibling fact is set.
+`bin`, `integration`, `services`, `global`, and `showcase` are structural project facts. They obey
+one law: each boolean is `true`, and each service name is present, only when the workspace physically
+ships the directory or exact-case file that defines it — never because of the workspace's name, and
+never because a sibling fact is set.
 `deriveBlueprint` probes those paths, so a fresh compile and an audit of a mature repository agree
 on what the workspace is.
 
@@ -279,10 +281,11 @@ on what the workspace is.
   workspace's own built output, outside the default run: the generated root configuration registers
   a standalone `integration` project including `tests/integration/**/*.test.ts`, and the manifest
   emits `test:integration`.
-- **`service`** — `tests/service/` exists. It records a slow, opt-in proof project against a foreign
-  running process, outside the default run: a standalone `service` project including
-  `tests/service/**/*.test.ts`, with `tests/setupService.ts` after the shared setup, and the
-  isolated `test:service` script.
+- **`services`** — each direct `tests/service/<vendor>/` directory that contains a `*.test.ts` at
+  any depth contributes its directory name to the sorted list. Each vendor gets a slow, opt-in
+  `service:<vendor>` proof project against its foreign process, including
+  `tests/service/<vendor>/**/*.test.ts`, and an isolated `test:service:<vendor>` script. The
+  aggregate `test:service` runs all vendor projects in one invocation.
 - **`global`** — the physical, exact-case `tests/setupGlobal.ts` file exists. It is the single
   governing setup-presence fact. A declared `src/browser` project runs that consumer-owned module
   as `globalSetup`; integration runs it only when `bin` and `integration` are also true.
@@ -293,12 +296,20 @@ on what the workspace is.
   consumer-only `vite-plugin-singlefile` development dependency. A directory, link, wrong-case
   name, absent wrapper, demo HTML, script, or installed dependency never implies this fact.
 
-A service workspace owes two companion files beside that directory, and derivation requires both
-physically present: `tests/setupService.ts` and `scripts/service.sh`. Either missing companion is a
-coded `TARGET` failure naming the missing path rather than a silent `service: false`. This package
-emits neither: both are consumer-owned seams, and the generated-workspace section sets out what
-each owes its workspace and which proof runs in which gate. Nothing here is inferred — the
-executable axis turns on neither proof project, and neither proof project turns on the other.
+Each service vendor owes `tests/service/<vendor>/setup.ts`, whose module-load readiness check probes
+and warms only that vendor. A service workspace also owes the shared `scripts/service.sh`
+provisioner. Derivation fails with a coded `INVALID` question when a vendor's readiness module is
+missing, when a vendor directory contains no test, or when a test uses the former flat
+`tests/service/*.test.ts` layout. An absent shared provisioner is instead a repairable missing
+artifact, so declaring the vendor directory does not deadlock the tool that supplies the skeleton.
+The migration is to move each flat test into `tests/service/<vendor>/`, add that vendor's `setup.ts`,
+and customize the repaired provisioner skeleton. Nothing here is inferred from a source or
+application axis: a vendor serves both.
+
+This is a published breaking change: `Blueprint.service` and `ViteFacts.service` were replaced by
+their sorted `services` collections, the single `service` project became one project per vendor,
+and the global `tests/setupService.ts` readiness seam was removed. There is no compatibility
+boolean or declaration file.
 
 `Override` replaces a rendered artifact's content at a path, never partially merges it. `Member` is
 one declared public export of the scaffolded workspace, derived rather than authored.
@@ -316,7 +327,8 @@ by artifact-relative path.
 self-describing. `PlanSummary` is the dry-run tally by origin and carries both selections. `Finding` is one
 drift verdict with an optional bounded `observed` byte hex for a stale destination, and `Audit` is
 the whole diff plus its `clean` and `complete` flags, `questions`, and `drifted` / `missing` /
-`foreign` counts. `Question` is one validation issue; `blocking: true` fails the gate closed while
+`foreign` counts.
+`Question` is one validation issue; `blocking: true` fails the gate closed while
 `false` rides a complete result as an advisory. `Validation` is the semantic pass result and never
 throws.
 
@@ -374,8 +386,11 @@ instead of through the manifest.
 
 `ManifestEntry` is one vendored-host file record — its un-dotted `storage` name, its `destination`
 relative to a target, and an `executable` bit. `HostManifest` pairs the sorted file `entries` with
-the complete sorted directory `roots` inventory, so a destructive consumer can tell a
-declared-empty root from a truncated manifest.
+the complete sorted directory `roots` inventory and a SHA-256 `digest` of that exact membership.
+The independently persisted digest detects an entry/root membership edit that did not update the
+digest, while roots distinguish a declared-empty directory. A self-consistent replacement manifest
+remains structurally valid and defines its own smaller membership; authenticity of that complete
+membership is outside the digest's checksum-only contract.
 
 The write-transaction shapes are the fail-closed mutation vocabulary. `WriteExpectation` is one
 destination snapshot captured before mutation (`absent`, `file`, or `directory`, with device,
@@ -410,9 +425,12 @@ From [`constants.ts`](../../src/core/constants.ts).
 | `BIN_CONFIGS`                     | const |
 | `APP_MATRIX`                      | const |
 | `HOST_PATHS`                      | const |
+| `ORCHESTRATION_PATH_PREFIXES`     | const |
+| `ORCHESTRATION_PATH_NAMES`        | const |
 | `SERVICE_SCRIPT_PATH`             | const |
 | `GLOBAL_SETUP_PATH`               | const |
 | `SHOWCASE_CONFIG_PATH`            | const |
+| `CATALOG_AGENT_PATH`              | const |
 | `NAME_PATTERN`                    | const |
 | `MAX_NAME_LENGTH`                 | const |
 | `MAX_DEPENDENCY_NAME_LENGTH`      | const |
@@ -464,10 +482,38 @@ produces one (`app/browser/index.html`, `app/server/main.ts`). `BIN_CONFIGS` is
 axis's computed `tsconfig` and Vite wrapper pair. `HOST_PATHS` is the ordered list of byte-copied
 host artifacts, and it is the staging manifest rather than the per-plan carried set:
 `stageHost` vendors every path on it, while each plan carries the subset `selectHostPaths` selects
-for that one workspace. `SERVICE_SCRIPT_PATH` names the consumer-owned provisioner a service
-workspace's audit expects, and `GLOBAL_SETUP_PATH` names the consumer-owned Vitest global-setup
+for that one workspace. `ORCHESTRATION_PATH_PREFIXES` and `ORCHESTRATION_PATH_NAMES` are the one
+membership rule behind both group classifiers: `inferGroup` reads them for a foreign target path and
+`hostGroup` for a `HOST_PATHS` entry, so a new harness directory is admitted once rather than twice.
+`SERVICE_SCRIPT_PATH` names the generated provisioner skeleton a service
+workspace must replace with its idempotent vendor provisioning. It is birth-only while present and
+repairable while absent. `GLOBAL_SETUP_PATH` names the consumer-owned Vitest global-setup
 module that independently selected projects can load. `SHOWCASE_CONFIG_PATH` names the sole
 consumer-owned regular file whose exact physical presence enables the optional app showcase.
+`CATALOG_AGENT_PATH` names the one artifact `diffPlan` compares by presence even after hydration,
+so a consumer can name the file the catalog operation owns rather than rediscovering it from a
+finding:
+
+```ts
+import type { Plan } from '@orkestrel/scaffold'
+import { blueprint, CATALOG_AGENT_PATH, contentToHex, diffPlan } from '@orkestrel/scaffold'
+
+const plan: Plan = {
+	blueprint: blueprint('router', { src: ['core'] }),
+	groups: ['orchestration'],
+	artifacts: [
+		{
+			path: CATALOG_AGENT_PATH,
+			group: 'orchestration',
+			origin: 'host',
+			hex: contentToHex('vendored catalog\n'),
+		},
+	],
+}
+
+diffPlan(plan, { [CATALOG_AGENT_PATH]: contentToHex('a newer fleet table\n') }).clean // true
+diffPlan(plan, {}).missing // 1 — restorable while absent, never replaced while present
+```
 
 The bounds are public because they are part of the contract, not implementation trivia.
 `MAX_ARTIFACT_BYTES` caps one artifact at 5 MiB and `MAX_TOTAL_ARTIFACT_BYTES` caps one blueprint,
@@ -548,6 +594,14 @@ From [`constants.ts`](../../src/server/constants.ts).
 `PRUNE_DIRECTORIES` is the closed set of prune-owned directories — `.claude/agents`,
 `.codex/agents`, and `scripts`. Nothing outside those roots is ever a deletion candidate, which is
 why project-owned skills under `.agents/skills` and `.claude/skills` are structurally safe.
+`.cursor/rules` is vendored but deliberately not pruned, for the same reason: a workspace owns
+project-specific Cursor rules beside the vendored bridge, and pruning would delete them. That
+choice has a cost, and it is accepted rather than avoided: a rule file dropped from `HOST_PATHS`
+stays in every consumer that already received it, no `audit` run reports it — the executable audit
+reads only planned paths, and nothing outside `PRUNE_DIRECTORIES` is ever a `foreign` finding — and
+a Cursor rule carrying `alwaysApply: true` keeps instructing agents there indefinitely. Retiring a
+vendored rule therefore needs a deliberate consumer-side removal, not a scaffold run.
+`.claude/rules` and `.claude/skills` carry the identical exposure for the identical reason.
 `HOST_MANIFEST_PATH` is the reserved `manifest.json` written at the root of every staged host.
 `SENSITIVE_HOST_PATH_PATTERN` rejects credential-like, key-store, certificate-key, and
 local-configuration paths at the staging boundary. `RESERVED_TARGET_PATH_PATTERN` protects `.git`
@@ -838,6 +892,7 @@ From [`helpers.ts`](../../src/core/helpers.ts).
 | `syncToReview`              | function |
 | `catalogToBlock`            | function |
 | `inferGroup`                | function |
+| `matchesOrchestrationPath`  | function |
 | `diffPlan`                  | function |
 | `bytesToHex`                | function |
 | `contentCodePoint`          | function |
@@ -899,6 +954,14 @@ that block enters agent instruction context. `isBehind` is the shared freshness
 report projections count with.
 
 `diffPlan` is the audit engine, and `inferGroup` classifies a target file the plan does not own.
+`matchesOrchestrationPath` is the shared membership test both classifiers use to decide whether a
+path instructs or wires an agent rather than configuring the toolchain.
+A host artifact without canonical `hex` is presence-owned: present is `aligned`, absent is
+`missing`. The server face attaches `hex` to every readable vendored source before executable
+audits, except the dependency-guide pointers hydration deliberately marks presence-owned. The
+hydrated `CATALOG_AGENT_PATH` artifact remains presence-owned even with vendored bytes because
+`catalog` owns its bounded marker region. The same engine governs `Materializer.repair`'s preview
+recheck and direct library consumers without a call-site plan rewrite.
 `snapshotOf`, `contentToHex`, `contentToBytes`, `contentByteLength`, `contentCodePoint`, and
 `bytesToHex` are the host-independent byte leaves that make exact comparison possible without a
 host encoder or buffer; an unpaired surrogate encodes as `U+FFFD` rather than throwing.
@@ -946,6 +1009,7 @@ From [`helpers.ts`](../../src/server/helpers.ts).
 | `digestFile`               | function |
 | `digestHex`                | function |
 | `digestText`               | function |
+| `digestHostManifest`       | function |
 | `guideStub`                | function |
 | `packageShortName`         | function |
 | `readGuideReferences`      | function |
@@ -998,7 +1062,9 @@ directory. All three reject malformed paths before filesystem access. Containmen
 realpath-aware rather than merely lexical, so a symlinked subdirectory planted inside an otherwise
 legitimate root cannot smuggle a write or a read outside it.
 
-`digestFile`, `digestHex`, and `digestText` are the three SHA-256 leaves. The file digest is
+`digestFile`, `digestHex`, and `digestText` are the byte and text SHA-256 leaves;
+`digestHostManifest` hashes the canonical entry/root membership independently of the stored digest
+field. The file digest is
 bounded-memory and revalidates device, inode, size, and modification time before and after reading,
 so a file swapped mid-read is a failure rather than a silent wrong digest. `readFileHex` and
 `readFileText` read one contained file under the same revalidation, and the text reader decodes
@@ -1030,8 +1096,9 @@ existing workspace so a mature package is diffed against its own would-be scaffo
 dependency-less stand-in. Environments come from `src/<environment>/` and `app/<environment>/`, the
 three directory-shaped structural project facts from their directory probes, `global` from the
 physical exact-case `tests/setupGlobal.ts` file, and `showcase` from the physical exact-case regular
-file `configs/app/vite.showcase.config.ts`; the service companion law remains the one the blueprint
-section states — every fact is a reading of the filesystem, never of the name. Dependencies and peers come
+file `configs/app/vite.showcase.config.ts`; service names come from the direct vendor directories
+under `tests/service/`, subject to the companion law in the blueprint section. Every fact is a
+reading of the filesystem, never of the package name. Dependencies and peers come
 from the manifest's scoped entries, with an optional peer recovered from
 `peerDependenciesMeta`; and `extras` is every development dependency minus the complete set
 `devDependenciesFor` emits for those environments and structural axes, and minus anything already
@@ -1045,7 +1112,8 @@ repository forking the file.
 `hydratePlan` are the vendored-host path. `storagePath` maps a repo-relative path to its un-dotted
 storage name, `stageHost` copies the vendored set into an output directory behind a full preflight
 and an atomic swap, and `readHostManifest` reads and validates the resulting `manifest.json`,
-returning `undefined` when a host has none — the raw-repository-root fallback that maps sources 1:1.
+including its independently stored membership digest, returning `undefined` when a host has none —
+the raw-repository-root fallback that maps sources 1:1.
 `locateHostSource` resolves one source to its storage file, `remapArtifactPath` maps a manifest
 destination back onto an artifact's target prefix, and `hydratePlan` rehydrates a plan's host
 artifacts with their exact bytes, expanding a directory-shaped host artifact into one artifact per
@@ -1182,10 +1250,11 @@ formatter's 100-column fixed point: a complete registration-array line, includin
 its trailing comma, stays collapsed when it fits and expands one entry per line otherwise.
 `viteProjectRegistrations` is the one registration derivation every root shape consumes: it derives
 the selected source and application projects from the canonical environment order, then appends
-`policy`, `config`, `guides`, and the optional `srcBin`, `integration`, and `service` projects.
+`policy`, `config`, `guides`, the optional `srcBin` and `integration` projects, and one
+`service<Vendor>` project for every selected service.
 `viteProjectDefinitions` renders the standalone proof and structural-fact definitions in that same
 order with one blank line between declarations. Both consume `ViteFacts`, so each optional project
-is controlled only by its matching `bin`, `integration`, or `service` blueprint fact; the same
+is controlled only by its matching `bin`, `integration`, or `services` blueprint fact; the same
 slice carries `global` to integration and the source-browser compiler, and `showcase` to the
 application-browser compiler, without adding another test project.
 
@@ -1200,11 +1269,12 @@ single non-core `src` environment, and application-bearing workspace respectivel
 executable-project emitter. A
 proof project is structurally derived from the directory holding its tests and never wraps a source
 or application environment project. The guides project therefore uses only `tests/setup.ts`, never
-`setupServer.ts`, `setupBrowser.ts`, or `setupService.ts`; and its `tests/src/**/*.test.ts` and
+`setupServer.ts`, `setupBrowser.ts`, or a vendor readiness module; and its `tests/src/**/*.test.ts` and
 `tests/app/**/*.test.ts` exclude rows are uniform across all root shapes by design, including
 core-only workspaces where one row cannot currently match. Integration and service use 120-second
-test and hook timeouts with file parallelism disabled, and service alone layers
-`tests/setupService.ts` onto the shared setup. The integration project wires
+test and hook timeouts with file parallelism disabled. Each service project layers
+`tests/setupServer.ts` and `tests/service/<vendor>/setup.ts` onto the shared setup, carries the
+server environment boundary, and may exercise either the `src` or `app` axis. The integration project wires
 `tests/setupGlobal.ts` for the shared template-registry harness exactly when `bin`, `integration`,
 and `global` are all true. Independently, a `global` source-browser project places
 `globalSetup: ['./tests/setupGlobal.ts']` immediately before its ordinary `setupFiles` row (and
@@ -1221,7 +1291,9 @@ generated parity suite resolves fence imports through. `guideMemberTable`, `guid
 `guideMethods`, and `guideTests` render the generated guide's member tables, usage examples, method
 contract, and test inventory. `fillArtifact` fills one template entry into a `template`-origin
 artifact with missing placeholders treated as an error, and `hostGroup` resolves which group a
-byte-copied host path belongs to. `applyOverrides` replaces a matching artifact's content in place
+byte-copied host path belongs to — splitting by what a path governs rather than where it sits, so
+that both MCP registrations (`.mcp.json` and `.cursor/mcp.json`) group with the harness bridges as
+`orchestration` rather than with the root dotfiles they sit beside. `applyOverrides` replaces a matching artifact's content in place
 and deliberately leaves an unmatched, host-owned, or `package.json` override unapplied, because the
 gate reports it as a blocking question. `ciWorkflow` renders the generated workflow.
 
@@ -1317,7 +1389,10 @@ The public methods of each behavioral interface, one table per type.
 `audit(blueprint, current, groups?)` compiles and then diffs the resulting plan against the
 caller-supplied current content; a gated blueprint returns `complete: false` with the gate's
 blocking questions and zero findings, and a complete one carries the gate's advisories on that same
-`questions` field. `destroy()` is idempotent teardown. The interface also exposes the readonly
+`questions` field. Because this core-only method performs no host I/O, its compiled host artifacts
+have no `hex` and are audited by presence. Callers that need host-byte verdicts hydrate the compiled
+plan through the server face and call `diffPlan`, which is the path every executable audit uses.
+`destroy()` is idempotent teardown. The interface also exposes the readonly
 `emitter`.
 
 #### `PlanManagerInterface`
@@ -1347,13 +1422,14 @@ interface also exposes the readonly `emitter` and `size` properties.
 | `destroy`     | `void`              |
 
 `materialize(plan, target)` is green-field: it refuses any target `isVacant` rejects, then copies
-each host artifact and writes each template and computed artifact. `repair(plan, audit, target)` is
-into-existing: it skips the vacancy check, re-verifies that the target still matches the audit
-preview, and writes only the missing and stale artifacts that audit names, leaving aligned ones
-untouched and reporting them as `skipped`. `prune(target, expected)` deletes exactly the unexpected
-files the vendored host no longer declares under the prune directories, and only after the observed
-bytes still match the `expected` snapshot it was previewed with. `destroy()` is idempotent teardown.
-The interface also exposes the readonly `emitter`.
+each host artifact and writes each template and computed artifact. `repair(plan, audit, target,
+replace?)` is into-existing: it skips the vacancy check, re-verifies that the target still matches
+the audit preview, and writes missing artifacts. Stale artifacts are report-only and returned as
+`skipped` by default; passing `true` for `replace` explicitly replaces their bytes and discards their
+local changes. Aligned artifacts are always `skipped`. `prune(target, expected)` deletes exactly the
+unexpected files the vendored host no longer declares under the prune directories, and only after
+the observed bytes still match the `expected` snapshot it was previewed with. `destroy()` is
+idempotent teardown. The interface also exposes the readonly `emitter`.
 
 #### `SyncInterface`
 
@@ -1424,10 +1500,11 @@ produce the same digest — and a `PlanManager` id is that digest.
 how it is audited, and whether it may ever be overwritten.
 
 - **`host`** — byte-copied from the vendored data root. These are the shared files a whole fleet
-  keeps identical: the root instruction documents and licence, the agent, rule, and skill
-  directories, the session scripts, the repository coding-law policy module, the byte-identical root
-  dotfiles, and the two line guide mirrors a workspace carries for contracts other than its own.
-  `HOST_PATHS` is the exact vendored list; what a given plan carries is `selectHostPaths` of it.
+  keeps identical: the root instruction documents and licence, the canonical orchestration contract
+  and the three harness bridges that point at it, the agent, rule, and skill directories, the
+  session scripts, the repository coding-law policy module, the byte-identical root dotfiles, and
+  the two line guide mirrors a workspace carries for contracts other than its own. `HOST_PATHS` is
+  the exact vendored list; what a given plan carries is `selectHostPaths` of it.
 - **`template`** — filled from a frozen template definition by a pure fill engine. These are
   starter files: source stubs, test stubs, the starter guide, the README.
 - **`computed`** — derived by this package's own combination logic. These are the structural files:
@@ -1443,19 +1520,32 @@ Audit semantics follow directly from that.
   missing, or clean tallies.
 - A **computed** artifact is content-aware canon: `missing`, `aligned`, or `stale`, and it gates the
   audit like any other drift.
-- A **host** artifact is audited by presence alone — `missing` or `aligned`, never `stale` — unless
-  it has been hydrated with its real host bytes, in which case it is content-compared exactly like a
-  computed artifact and can be `stale`. Hydration also expands a directory-shaped host artifact into
-  one artifact per file, so agent configuration and skills are audited file by file.
-- A target file the plan does not own is `foreign`, and `inferGroup` classifies it by its leading
-  path segment.
+- A **host** artifact with canonical `hex` is content-compared exactly like a computed artifact and
+  can be `stale`. Without `hex`, it is presence-owned: present is `aligned`, absent is `missing`.
+  The catalog agent is explicitly presence-owned because `catalog` is its sole content writer.
+  Hydration expands a directory-shaped host artifact into one artifact per declared file and verifies
+  that the manifest digest matches the manifest's current membership before expansion. That detects
+  stale-digest truncation; a self-consistently rewritten manifest defines a smaller valid inventory,
+  so the digest alone cannot authenticate omitted membership.
+- In a caller-supplied snapshot, a path the plan does not own is `foreign`, and `inferGroup`
+  classifies it by its leading path segment. The executable supplies unexpected paths only from
+  `.claude/agents`, `.codex/agents`, and `scripts`, because those prune-owned directories are the
+  only regions scaffold has authority to delete from; unplanned files elsewhere are not reported
+  as foreign.
 
 The same ownership boundary is what makes mutation safe. **`fleet` and default `repair` both scope
-the compiled plan to host origin before hydrating, diffing, or applying.** `--generated` widens that
-scoped plan to generated canon except `package.json`; template artifacts remain birth-only in
-either mode. A mature workspace's hand-written source, tests, guides, and manifest are therefore
-never overwritten with a stub. The generated `.github/workflows/ci.yml` is a **computed** artifact,
-so user-owned CI stands by default but is intentionally restored when `--generated` is passed.
+the compiled plan to host origin before hydrating, diffing, or applying.** Missing files in that
+scope are restored, but stale files are report-only unless `--replace` explicitly authorizes byte
+replacement. `--generated` widens the selected ownership scope to generated canon. It keeps the
+`package.json` publication boundary protected except for the generated service-script keys needed
+when the derived service set changes; it composes with `--replace` and does not itself authorize
+replacement. Template
+artifacts remain birth-only in either scope, except that an absent service provisioner and absent
+service conformance test are promoted to missing-file repair artifacts. A present customized copy
+is never compared or replaced. A mature workspace's hand-written source, tests, and guides are
+therefore never overwritten with a stub. The generated
+`.github/workflows/ci.yml` is a **computed** artifact, so user-owned CI stands by default and is
+restored only when both `--generated` and `--replace` are passed.
 Audit always compares it because computed artifacts are content-aware canon. A legitimate
 difference that the blueprint cannot express is a canon gap: add the missing blueprint axis rather
 than forking the computed file in one repository.
@@ -1477,8 +1567,11 @@ owner: a dependency this package vendors a byte-identical mirror for gets a real
 dependency, so a package depending on `@orkestrel/guide` plans one `guides/src/guide.md` rather than
 two. Any other dependency gets a host-origin _pointer_ artifact plus a non-blocking question, never
 a fabricated mirror; on materialization that pointer degrades to a short stub, and `scaffold pull`
-fetches the real thing. That degrade is scoped exactly to guide pointers: any other missing manifest
-entry means a corrupt or truncated vendored manifest, and fails closed. Selection is the law and
+fetches the real thing. Hydration marks that permanent pointer state presence-owned, so both the
+birth stub and a later pulled guide audit clean while present; `pull` refreshes content but is not a
+remedy for an audit state. That degrade is scoped exactly to guide pointers. A manifest whose
+membership changes without a matching digest is rejected, while any other undeclared or unreadable
+source is rejected with a coded `TARGET` failure. Selection is the law and
 `findFileConflict` is its backstop: two artifacts at one path refuse the plan rather than racing to
 be the last writer.
 
@@ -1489,23 +1582,63 @@ checks one. `readTarget` supplies the snapshot as exact bytes; `diffPlan` return
 `auditToReview` renders them for a human. Nothing in that path writes.
 
 The executable's physical unexpected-file scan treats exactly `scripts/service.sh` as an expected
-consumer-owned seam when the derived blueprint has `service: true`. That exclusion is warranted
-because a service blueprint cannot derive without the physical file: the companion-file law raises
-a `TARGET` failure first, so the scan removes a false positive and can never mask an absent
-provisioner. A non-service workspace still reports the same path as foreign.
+workspace-owned seam when the derived blueprint has at least one service. That exclusion is
+warranted because the promoted plan reports an absent file as missing while a present file is
+consumer-owned. A workspace with no services still reports the same path as foreign.
 
 `repair` turns those findings back into the narrowest possible write. It re-reads the target,
 re-diffs it, and refuses to proceed if the findings changed since the preview it was given — a
 target that moved under the caller is a `TARGET` failure, not a race to win. It then derives a write
 precondition per artifact from the audit itself: a `missing` finding requires the destination to
-still be absent, a `stale` finding requires it to still carry exactly the bytes that were observed.
-Those preconditions are checked again inside the write transaction before any promotion.
-An interactive audit repair hand-off forwards `--generated` into the repair invocation when the
-flag was present on `audit`.
+still be absent. A `stale` finding remains untouched and is reported as skipped unless the caller
+passes `replace`; an authorized stale replacement requires the destination to still carry exactly
+the bytes that were observed. Those preconditions are checked again inside the write transaction
+before any promotion. A skipped stale path keeps the executable at exit `1`, because the selected
+workspace remains drifted; a clean run and a run that fully applies its findings exit `0`. An
+interactive audit repair hand-off forwards both `--generated` and `--replace` when those flags were
+present on `audit`.
+
+That boundary governs the executable's words too. Every drift line states what a command will do
+rather than how a file came to differ: the executable cannot know whether a generated file was
+hand-edited, and a consumer whose blueprint cannot yet express what it needs legitimately edits one.
+Every cost is stated where it can still be declined, and nowhere else: a run with nothing to write
+states no boundary it is not about to act on, because a warning attached to a no-op only trains
+operators to ignore warnings. `repair` states its scope when the audit found something to repair;
+`fleet` states its scope, its repository count, and the same replacement cost once `--apply` has
+authorized a write; neither states it over a dry run. Each run closes on the tally of what it did,
+including a run that writes nothing — and a drifted file left alone is counted apart from an
+aligned one, because `unchanged` is already the audit table's word for a file that matches canon.
+
+**Four paths discard content a consumer may own, and each names its cost before it acts.**
+
+| Path                              | What it discards                                                     | Ownership boundary                                                                                               |
+| --------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--replace` on repair or fleet    | The local bytes of a drifted file the report named                   | Host-owned artifacts, widened to generated canon by `--generated`; never a present starter, never `package.json` |
+| `--prune --apply`                 | Whole unexpected files, quarantined first and reported by exact path | Only `.claude/agents`, `.codex/agents`, and `scripts`, and only paths the vendored host does not declare         |
+| `catalog --apply`                 | Everything between the two catalog markers, local additions included | Exactly the one bounded marker region of `CATALOG_AGENT_PATH`; the rest of that file is never touched            |
+| `pull --apply` / `mirror --apply` | A locally edited vendored guide mirror, which reads as `behind`      | Only `guides/src/<name>.md` mirrors of other packages; never the guide this workspace owns                       |
+
+`--replace` is the only one of the four that is an opt-in modifier rather than a verb, so it is the
+one whose cost is repeated in every line that offers it: the scope line, the repair verdict, the
+audit's drift guidance, and the hand-off question itself. `--apply` authorizes all four and nothing
+else does — `--yes` only skips a confirmation it can no longer stand in for, and an unexpected-file
+hint that recommended `repair --prune` without it would name a command that deletes nothing. `new`
+is absent from the table on purpose: it refuses any target `isVacant` rejects, so it has no local
+content to discard.
+
+The catalog agent has a narrower ownership exception in `diffPlan` itself.
+`CATALOG_AGENT_PATH` remains presence-owned after host hydration: repair can restore the
+absent file, but audit, repair, fleet, and direct library consumers never compare or replace its
+existing bytes, even under `--replace`. `catalog` is the sole content writer and continues to
+replace only the uniquely bounded marker region. Thus
+`repair` → `catalog` → `repair` converges without restoring a stale embedded catalog snapshot over
+the current fleet table.
 
 `prune` is the deletion arm, and it is deliberately narrow. Its candidate set comes from
-`pruneTargets`, which is also what the executable's audit and preview read, so what is reported and
-what is deleted cannot diverge. Only the three prune directories are in scope; the allowlist must be
+`pruneTargets`, which is also what the executable's merged report and preview read. Repair's
+optimistic-concurrency recheck receives the raw plan audit, while the separate foreign findings
+remain attached to reporting and exit status; after that recheck succeeds, the same preview snapshot
+drives deletion. Only the three prune directories are in scope; the allowlist must be
 positively established from the vendored host, or the call fails closed rather than treating an
 unresolved host as "vendors nothing" and proposing to delete everything. Each candidate is verified
 as a plain physical file whose bytes still match the preview, moved into a private quarantine rather
@@ -1574,11 +1707,14 @@ fleet refresh is never partial. Files outside the discovered guide set remain un
 
 A generated workspace is not a folder of suggestions; it is a working, gated project.
 
-**Manifest and scripts.** A published workspace is scoped and carries an `exports` map, publish
-configuration, and ships `dist/src` plus its README. An application-only workspace is unscoped and
-`private: true`, with no export map and no publish configuration, and ships `dist/app`. A workspace
-that builds its own executable additionally ships `dist/bin` and `dist/host`. Scripts are emitted in
-a fixed, interleaved order so aggregates sit immediately before their per-environment members:
+**Manifest and scripts.** A published workspace is scoped, carries the Orkestrel GitHub homepage,
+issues, and repository identity, carries an `exports` map and publish configuration, and ships
+`dist/src` plus its README. An application-only workspace is unscoped and `private: true`, with no
+export map, publish configuration, or invented GitHub identity, and ships `dist/app`. Both carry
+`license: "MIT"` because every generated workspace receives the same host-owned MIT `LICENSE`.
+A workspace that builds its own executable additionally ships `dist/bin` and `dist/host`. Scripts
+are emitted in a fixed, interleaved order so aggregates sit immediately before their per-environment
+members:
 
 - `clean`, `copy`, `scaffold`, `lint`
 - `check`, then `check:src` with one `check:src:<environment>` per published environment, then
@@ -1586,7 +1722,8 @@ a fixed, interleaved order so aggregates sit immediately before their per-enviro
   Vue typechecker, every other scope uses plain `tsc`
 - `format`, `format:check`, `lint:check`
 - `test`, then `test:src` and its per-environment scopes, the optional `test:integration`,
-  `test:equivalence`, and `test:service` proofs, `test:app` and its per-environment scopes, then
+  `test:equivalence`, and `test:service` aggregate followed by its sorted per-vendor proofs,
+  `test:app` and its per-environment scopes, then
   `test:policy`, `test:config`, and `test:guides`
 - `build`, then `build:src` and its per-environment targets, `build:app` and its runtime targets, and
   `build:host` for a bin workspace
@@ -1595,24 +1732,24 @@ a fixed, interleaved order so aggregates sit immediately before their per-enviro
 - `showcase`, `build:showcase`, and `show` only when the physical showcase wrapper is present;
   `show` formats, then builds, then copies `dist/showcase/index.html` to `demo/showcase.html`
 - `prepublishOnly` chaining `format:check → lint:check → check → build → test`, followed by
-  `test:integration` when the integration axis is selected
+  `test:integration` when selected and finally `test:service` when any service is selected
 
 **Proof gating.** The opt-in proofs are predictable from the axes alone. `test:integration` rides
-the `integration` axis and `test:service` the `service` axis, while `test:equivalence` is emitted
+the `integration` axis and `test:service` a nonempty `services` axis, while `test:equivalence` is emitted
 only where `bin` and `integration` are both set:
 
-| Proof              | `npm test` | `prepublishOnly` | CI                         |
-| ------------------ | ---------- | ---------------- | -------------------------- |
-| `test:integration` | no         | yes, last        | after the standard gates   |
-| `test:equivalence` | no         | no               | no                         |
-| `test:service`     | no         | never            | after `scripts/service.sh` |
+| Proof              | `npm test` | `prepublishOnly`    | CI                         |
+| ------------------ | ---------- | ------------------- | -------------------------- |
+| `test:integration` | no         | yes, before service | after the standard gates   |
+| `test:equivalence` | no         | no                  | no                         |
+| `test:service`     | no         | yes, last           | after `scripts/service.sh` |
 
 No opt-in proof joins the default chain: `npm test` runs the source, application, policy,
 configuration, and guide projects, and nothing there needs a build artifact or a foreign process.
-Publication is the one
-asymmetry — `prepublishOnly` appends `test:integration`, because a package about to be published
-should prove itself against its own built output, while `test:service` is never in that chain.
-Neither default testing nor publication starts or requires a foreign process.
+Publication is the one asymmetry: `prepublishOnly` appends integration and then service proofs.
+A package that claims to drive a vendor has not proved that claim unless publishing runs against
+it, despite the provisioning cost. Neither default testing nor publication starts a foreign
+process; publication requires the caller to provision one first.
 The showcase is likewise outside `build`, `test`, and `prepublishOnly`; it is an explicit projection
 of `app/browser`, not an environment, test-project row, or source/demo artifact.
 Its copied `demo/showcase.html` is generated and minified, so the mirrored `.prettierignore` keeps it
@@ -1630,22 +1767,29 @@ The equivalence proof is a dual-path re-run rather than a separate suite. Run
 integration project in dual-path mode and proves each programmatic driver verdict against the
 spawned npm-script reference. Ordinary integration runs keep the faster driver-only path.
 
-**Consumer-owned service seams.** The service axis is the one place canon stops at the boundary:
-there is no template for a proof project and neither companion path is on `HOST_PATHS`, so a
-service workspace owns both of its seams outright. They come as a pair.
-
-- `tests/setupService.ts` is the readiness seam. It probes the foreign process and warms it before
-  any test runs, and throws at module load — naming the `service` project — when that process is
-  unreachable, so an unprovisioned run fails loudly instead of passing an empty suite. Only the
-  `service` project loads it.
-- `scripts/service.sh` is the provisioning seam, named once by `SERVICE_SCRIPT_PATH`. It brings that
-  process up idempotently — a second run against an already-provisioned service is a no-op rather
-  than a second instance — and exits nonzero when it cannot, which is what makes CI's
-  `bash scripts/service.sh` step a gate rather than a hint.
+**Consumer-owned service seams.** Each vendor owns its readiness module at
+`tests/service/<vendor>/setup.ts`. It probes and warms that vendor at module load, throwing a clear
+error when unavailable so only that vendor project fails readiness. The scaffold never generates
+these modules because an inert readiness check would be a false proof.
+
+`scripts/service.sh`, named once by `SERVICE_SCRIPT_PATH`, is shared provisioning for every vendor.
+The scaffold emits a template skeleton that exits nonzero until the workspace replaces it with
+idempotent provisioning; an already-provisioned vendor must be a no-op, and any vendor that cannot
+be prepared must make the script fail. The skeleton is written at birth when services are already
+declared, or by repair when a post-birth vendor declaration makes it newly absent. Once present it
+is consumer-owned and never replaced. CI invokes it once before the aggregate project run.
+
+The configuration conformance test lives in the ordinary `config` project, so `npm test` checks the
+directory names, readiness files, project declarations, scripts, default-test omission, and
+publication suffix without contacting a vendor. Like the provisioner it is repaired only when
+absent, then remains workspace-owned and audit-exempt. Service adoption under `--generated`
+regenerates the Vite and CI canon and merges only `test:service`, the per-vendor service scripts,
+and the `prepublishOnly` service suffix into `package.json`; publication metadata and unrelated
+scripts retain their existing values.
 
 The audit expects the script rather than reporting it foreign, on the derive-time warrant the audit
 section gives. Repair pruning applies the same exclusion, so it never proposes or removes that
-required consumer-owned provisioner.
+required workspace-owned provisioner.
 
 **Environment isolation.** Scoped TypeScript projects remove the wrong host's globals from each
 environment: core scopes carry the WHATWG web-interop surface and no host at all — no DOM, no Node,
@@ -1881,8 +2025,13 @@ the proof-gating table gives them.
 dependency, model, and external-tool readiness scripts at session start. The **`Stop` hook runs only
 `git diff --check`** — a whitespace and conflict-marker check over the working tree, nothing more.
 Bash invocation and sensitive reads are controlled by the **settings permission list, not by a guard
-script**: every Bash command requires explicit approval, including commands Claude Code otherwise
-classifies as read-only. Read-only reviewer, checker, and ecosystem roles carry no Bash tool; the
+script**. The allow list is closed and holds exactly two entries — `Bash(codex --version)` and
+`Bash(codex login *)` — because the orchestration contract requires a bench-liveness probe and a
+device-login recovery at session start, and prompting for those would stall every session before
+planning. Every other Bash command requires explicit approval, including commands Claude Code
+otherwise classifies as read-only. That list is inherited by every workspace in the line, so a
+machine-local grant belongs in `settings.local.json`, which `SENSITIVE_HOST_PATH_PATTERN` keeps out
+of every vendored host. Read-only reviewer, checker, and ecosystem roles carry no Bash tool; the
 orchestrator supplies their diff and status evidence. Bridge, writer, and verifier roles request
 approval when their bounded shell work is needed. Read patterns covering environment files,
 package-manager credentials, credential stores, private keys, key stores, SSH, cloud credentials,
@@ -1905,7 +2054,7 @@ no module API of its own. Seven verbs:
 | `pull`    | refresh vendored guides and versions, report drift       |
 | `mirror`  | refresh every published Orkestrel package guide          |
 | `audit`   | whole-plan conformance report                            |
-| `repair`  | restore host-owned files and optional generated canon    |
+| `repair`  | restore missing canon; optionally replace drifted bytes  |
 | `fleet`   | audit or repair every workspace under the cwd's children |
 | `catalog` | regenerate the fleet package-catalog table               |
 
@@ -1919,8 +2068,10 @@ Orkestrel short name. Other npm packages are not a creation-time flag — add th
 manifest's development dependencies afterwards, and they round-trip through `deriveBlueprint`'s
 extras so the workspace stays audit-clean.
 
-**Other flags.** `--target <path>` selects the directory a verb operates on. `--from <path>` is
-repeatable and points at a local template or catalog source instead of the bundled one.
+**Other flags.** `--target <path>` selects the directory a single-workspace verb operates on;
+`fleet --target` is a usage error because fleet's root is always the current directory.
+`--from <path>` points at a local template source instead of the bundled one and may be passed once
+to those verbs. It is repeatable only for `catalog`, where each occurrence adds one catalog source.
 On `pull`, `--deps x,y` limits refresh to those declared Orkestrel dependencies; without it, every
 declared dependency mirror is considered.
 `mirror` accepts no dependency selection: its exact npm organization discovery is the operation's
@@ -1928,25 +2079,34 @@ scope, and it fetches guides without registry version or packument requests.
 `--groups a,b` scopes an audit to artifact groups. `--live` adds an upstream freshness check to an
 audit. `--strict` makes a pull or mirror throw on a network fault. `--offline` restricts a catalog to local
 sources. `--prune` opts a repair or fleet run into deleting unexpected files under the three prune
-directories. `--generated` opts a repair or fleet run into restoring generated canon except
-`package.json`; on `audit`, it is inherited if the interactive repair hand-off is accepted.
+directories. `--generated` opts a repair or fleet run into including generated canon while
+protecting `package.json` outside its generated service-script keys; on `audit`, it is inherited if
+the interactive repair hand-off is accepted.
+`--replace` authorizes repair to discard local changes in the drifted files named by its report; it
+composes with `--generated`, and is likewise inherited by an accepted audit hand-off.
 `--json` emits one machine-readable value. `--apply` writes, `--yes` skips the confirmation, and
 `-h` or `--help` prints usage.
 
-**Safety model.** Every verb is a dry run by default. On a terminal a write asks for confirmation
-first, defaulting to no; in a script, `--apply` writes and `--yes` skips the question. Every write is
+**Safety model.** Every verb is a dry run by default. `--apply` is the sole write authorization;
+`--yes` only skips a confirmation and never authorizes a write or deletion by itself. On a terminal
+an authorized write asks for confirmation first, defaulting to no; scripts do not prompt. Every write is
 confined to the working directory, so the instruction is to change into it first rather than to pass
 a root. `repair` asks a second, separately defaulted question before deleting anything, and a
-non-interactive session without `--apply` or `--yes` skips pruning rather than guessing. `fleet`
-operates on the immediate children of the working directory and never on the directory itself, and
-it has no root flag at all — `repair` is the single-workspace tool.
-
-`fleet` and default `repair` are scoped to host-origin artifacts. `repair` states its selected scope
-in the output; `--generated` widens both verbs to generated files while still excluding starter
-files and `package.json`.
+session without `--apply` skips pruning regardless of `--yes`. `fleet` operates on the immediate
+children of the working directory and never on the directory itself. It has no root flag at all:
+passing `--target` is rejected with exit `2` instead of being silently ignored. `repair` is the
+single-workspace tool.
+
+`fleet` and default `repair` are scoped to host-origin artifacts plus absent service-owned starter
+seams. Both state that selected scope in the output before they act — `repair` once its audit found
+something to repair, `fleet` once `--apply` authorized a write, naming the number of repositories
+that write covers. `--generated` widens both verbs to generated
+files and the manifest's generated service-script keys while still excluding present starter files
+and package publication metadata. Within either scope, missing files are safe to restore, stale
+files are report-only by default, and `--replace` is the explicit destructive opt-in.
 
 **Catalog markers.** `catalog` rewrites the block between `<!-- catalog:start -->` and
-`<!-- catalog:end -->` in `.claude/agents/orkestrel.md`. **Ambiguous markers fail before any
+`<!-- catalog:end -->` in `CATALOG_AGENT_PATH`. **Ambiguous markers fail before any
 mutation**: the file must contain exactly one ordered pair. A missing marker, a reversed pair, or a
 repeated marker of either kind is a coded `TARGET` failure raised before the file is touched, and
 the run reports the drift and any row-count shrink rather than rewriting a file it cannot bound.
@@ -1958,10 +2118,16 @@ The check is a feature detection: **earlier supported Node 22 releases simply us
 roots**. It only ever adds trusted issuers — nothing disables verification — and a failure is a
 silent no-op rather than a crash. Custom PEMs are added through the standard environment variable.
 
-**Exit codes.** `0` is clean or successful, `1` is drift or failure, `2` is a usage error. An audit
-exits non-zero on any drift, foreign files included, which makes it usable directly as a CI gate. A
-pull exits non-zero on any drift or failure whether or not `--strict` was passed; `--strict`
-additionally throws on a network fault. Every unknown verb is a usage error and gets a nearest-match
+**Exit codes.** `0` is clean or successful, `1` is drift or failure, `2` is a usage error. Repair
+and fleet use the same dirty-repository predicate: selected-scope drift or any full-plan finding
+outside that scope keeps exit `1`. A repair that skips stale files therefore exits `1`; a repair
+exits `0` only when its selected audit and its reported outside scope are both clean. An audit exits
+non-zero on any drift, foreign files included, which makes it usable directly as a CI gate.
+`repair --json` carries that same terminal audit after any authorized write, while its `result`
+records the files the write copied, wrote, skipped, and removed. A pull exits non-zero on any drift
+or failure whether or not `--strict` was passed, including when
+other entries were applied successfully; `--strict` additionally throws on a network fault. Every
+unknown verb is a usage error and gets a nearest-match
 suggestion when one is sufficiently close.
 
 ## Package contents
@@ -1972,7 +2138,8 @@ files, plus `./package.json`. The `scaffold` binary maps to the built executable
 
 The published file set is exactly `dist/src`, `dist/bin`, `dist/host`, and `README.md`. `dist/host`
 is the vendored data root: the byte-preserved host files plus the `manifest.json` recording their
-storage names, destinations, and executable bits. Storage names are un-dotted, because a leading dot
+storage names, destinations, executable bits, directory roots, and membership digest. Storage names
+are un-dotted, because a leading dot
 does not survive packaging intact; the manifest is what maps a storage name back to its real
 destination. That is also why the default host is resolved from the installed module's own
 location — the package carries its host data with itself, and a caller-supplied raw repository root
@@ -2368,10 +2535,14 @@ configViteProject()
 guidesViteProject()
 binViteProject()
 integrationViteProject({ bin: true, integration: true, global: true })
-serviceViteProject()
-viteProjectDefinitions({ integration: true }).includes('export const integration =') // true
-viteProjectRegistrations(['core'], [], { integration: true }).map(({ project }) => project)
-// ['srcCore', 'policy', 'config', 'guides', 'integration']
+serviceViteProject('claude')
+viteProjectDefinitions({ integration: true, services: ['claude'] }).includes(
+	'export const serviceClaude =',
+) // true
+viteProjectRegistrations(['core'], [], { integration: true, services: ['claude'] }).map(
+	({ project }) => project,
+)
+// ['srcCore', 'policy', 'config', 'guides', 'integration', 'serviceClaude']
 
 rootViteConfig(['core', 'server'], { bin: true })
 singleSrcViteConfig('server').includes('srcServer') // true
@@ -2411,6 +2582,7 @@ syncReportOf('./packages/router', [], []) // { clean: true, failed: 0, … }
 import { blueprint, blueprintToPlan, diffPlan } from '@orkestrel/scaffold'
 import {
 	createMaterializer,
+	digestHostManifest,
 	hostRoot,
 	hydratePlan,
 	isVacant,
@@ -2424,6 +2596,7 @@ import {
 } from '@orkestrel/scaffold/server'
 
 const host = hostRoot()
+digestHostManifest([], []) // exact empty manifest membership digest
 readHostManifest(host) // the vendored manifest, or undefined for a raw root
 storagePath('.claude/agents/reviewer.md') // 'claude/agents/reviewer.md'
 locateHostSource(undefined, 'package.json', host)
@@ -2443,7 +2616,8 @@ const current = readTarget(
 	'./packages/router',
 	plan.artifacts.map((artifact) => artifact.path),
 )
-materializer.repair(plan, diffPlan(plan, current), './packages/router')
+materializer.repair(plan, diffPlan(plan, current), './packages/router') // missing only; stale is skipped
+materializer.repair(plan, diffPlan(plan, current), './packages/router', true) // replace stale bytes
 materializer.prune('./packages/router', {})
 materializer.destroy()
 
@@ -2638,7 +2812,11 @@ hasOnlyDataProperties({ a: 1 }) // true
 isDenseDataArray(['a'], 10, isPortablePath) // true
 isWritePrecondition({ path: 'package.json', shape: 'absent' }) // true
 isManifestEntry({ storage: 'AGENTS.md', destination: 'AGENTS.md', executable: false }) // true
-isHostManifest({ entries: [], roots: [] }) // true
+isHostManifest({
+	entries: [],
+	roots: [],
+	digest: 'f98e1531d9fd8fab7e301d1cc944249913d93f48c918a11a753048b877211679',
+}) // true
 isSyncEventHooks({ done: () => undefined }) // true
 isMaterializerEventHooks({ done: () => undefined }) // true
 isEmitterErrorHandler(() => undefined) // true