@orkestrel/scaffold 0.0.2 → 0.0.3

package/dist/bin/scaffold.js

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
 import * as tls from "node:tls";
-import { parseArgs } from "node:util";
-import { DEPENDENCY_NAME_PATTERN, GROUPS, NAME_PATTERN, SURFACES, ScaffoldError, blueprint, blueprintToPlan, catalogNames, catalogToBlock, createCompiler, dependency, diffPlan, isScaffoldError, manifestToDependencies, planToSummary } from "../src/core/index.js";
-import { catalogPackages, createMaterializer, createSync, deriveBlueprint, discoverPackages, hostRoot, hydratePlan, locateHostSource, pruneTargets, readHostManifest, readManifest, readTarget } from "../src/server/index.js";
+import { DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, GROUPS, MAX_ARTIFACT_BYTES, NAME_PATTERN, ScaffoldError, blueprint, blueprintToPlan, catalogNames, catalogToBlock, createCompiler, dependency, diffPlan, isScaffoldError, manifestToDependencies, planToSummary } from "../src/core/index.js";
+import { WriteTransaction, catalogPackages, commitWriteTransaction, createMaterializer, createSync, deriveBlueprint, digestFile, digestText, discardWriteTransaction, discoverPackages, hostRoot, hydratePlan, isFilesystemPath, isRealDirectory, isTerminalText, isVacant, locateHostSource, pruneTargets, readFileText, readHostManifest, readManifest, readTarget, resolvePhysicalPath, validateWriteDirectories } from "../src/server/index.js";
 import { createReporter, createSpinner, createStyler } from "@orkestrel/console";
 import { createServerSink } from "@orkestrel/console/server";
+import { attempt } from "@orkestrel/contract";
 import { isTerminalError } from "@orkestrel/terminal";
 import { createTerminal } from "@orkestrel/terminal/server";
-//#region src/bin/render.ts
-/** The bin's closed verb vocabulary. */
+import { parseArgs } from "node:util";
+//#region src/bin/constants.ts
+/** The command-line interface's closed command vocabulary. */
 var KNOWN_VERBS = Object.freeze([
 	"new",
 	"pull",
@@ -19,51 +20,185 @@ var KNOWN_VERBS = Object.freeze([
 	"fleet",
 	"catalog"
 ]);
-/** The jargon translation table — internal `Origin`/`Drift`/scope vocabulary → one user-facing register. */
+/** Internal artifact origins translated into user-facing labels. */
 var ORIGIN_LABEL = Object.freeze({
-	host: "template-owned",
-	template: "template-owned",
+	host: "host-owned",
+	template: "starter",
 	computed: "generated"
 });
-/** A `Finding`'s `Drift`, translated — `'aligned'` never reaches a rendered table (callers filter it first). */
+/** Internal drift states translated into user-facing labels. */
 var DRIFT_LABEL = Object.freeze({
 	aligned: "unchanged",
 	stale: "drifted",
 	missing: "missing",
 	foreign: "unexpected file"
 });
-/** A `Freshness` outcome, translated for `pull`'s per-entry cause notes. */
+/** Dependency freshness states translated into user-facing labels. */
 var FRESHNESS_LABEL = Object.freeze({
 	current: "unchanged",
 	behind: "behind",
 	missing: "missing upstream",
 	failed: "fetch failed"
 });
-/** The materializer's per-entry action words, translated (`copied` → `wrote`, `skipped` → `unchanged`). */
+/** Materializer actions translated into user-facing labels. */
 var ACTION_LABEL = Object.freeze({
 	written: "wrote",
 	copied: "wrote",
 	skipped: "unchanged",
 	removed: "removed"
 });
-/** One `{count} {label}` part, pluralized; used by every bucket/tally line. */
-function countPart(count, label) {
-	return `${count} ${label}${count === 1 ? "" : "s"}`;
-}
-/** Nonzero `{count} {label}` parts joined by `, `; `'clean'` when every count is zero — the shared bucket-text primitive every verdict line reuses. */
-function bucketText(counts) {
-	const parts = [];
-	if (counts.drifted > 0) parts.push(countPart(counts.drifted, "drifted"));
-	if (counts.missing > 0) parts.push(countPart(counts.missing, "missing"));
-	if (counts.foreign > 0) parts.push(countPart(counts.foreign, "unexpected"));
-	return parts.length > 0 ? parts.join(", ") : "clean";
-}
-/**
-* Split `findings` by their `plan` artifact's `origin` — `host`/`template` lumped as
-* `template-owned` vs `computed` as `generated` (a `foreign` finding names no plan artifact,
-* so it counts as `generated`: it is never template-owned).
-*/
-function partitionOrigin(findings, plan) {
+/** Repair's deliberately limited ownership boundary. */
+var REPAIR_SCOPE = "repair scope: shared host-owned artifacts only — starter and generated files are never touched";
+/** The dry-run note for `new`. */
+var NEW_DRY_RUN_NOTE = "dry run — pass --apply to write";
+/** The fallback message for a malformed command line without an error message. */
+var INVALID_ARGUMENTS_MESSAGE = "invalid arguments";
+/** Shared prompt-cancellation message. */
+var CANCELLED_MESSAGE = "cancelled — nothing written";
+/** Terminal choices for a new workspace's src and app environments. */
+var ENVIRONMENT_CHOICES = Object.freeze([
+	{
+		name: "core",
+		value: "core",
+		description: "the pure engine"
+	},
+	{
+		name: "browser",
+		value: "browser",
+		description: "DOM-facing environment"
+	},
+	{
+		name: "server",
+		value: "server",
+		description: "node-facing environment"
+	}
+]);
+/** The safety model included in full help. */
+var SAFETY_BANNER = [
+	"safety: every verb is a dry run by default.",
+	"on a terminal, a write prompts for confirmation; in a script, pass --apply (and --yes to skip the confirm).",
+	"every write is confined to the current working directory — cd there first.",
+	"when Node exposes system-CA controls, TLS adds the OS certificate store; earlier supported Node 22 releases use default roots. NODE_EXTRA_CA_CERTS adds custom PEMs."
+].join("\n");
+/** Stable command exit-code meanings. */
+var EXIT_CODES = Object.freeze([
+	["0", "clean / success"],
+	["1", "drift or failure"],
+	["2", "usage error"]
+]);
+/** One-line command summaries. */
+var VERB_SUMMARY = Object.freeze({
+	new: "scaffold a workspace into ./<name>",
+	pull: "refresh vendored guides/versions, report drift",
+	audit: "whole-plan conformance report",
+	repair: "restore the shared host-owned set",
+	fleet: "audit/repair every workspace under the cwd's immediate children",
+	catalog: "regenerate the fleet package-catalog table"
+});
+/** Compact command flag references. */
+var VERB_FLAGS = Object.freeze({
+	new: "--src a,b --app a,b --deps x,y --apply --yes --target <path> --from <path>",
+	pull: "--target . --deps x,y --apply --yes --strict",
+	audit: "--target . --live --from <path> --groups a,b",
+	repair: "--target . --apply --yes --prune --from <path>",
+	fleet: "--apply --yes --prune --from <path>",
+	catalog: "--from <path> ... --target <repo> --offline --apply --yes"
+});
+/** Plain-language command flag descriptions. */
+var VERB_FLAG_HELP = Object.freeze({
+	new: [
+		["--src a,b", "which src environments to include (core, browser, server)"],
+		["--app a,b", "which app environments to include (core, browser, server)"],
+		["--deps x,y", "@orkestrel/* dependencies to add (installed as dependencies)"],
+		["--apply", "write the files (default is a dry run)"],
+		["--yes", "skip the confirmation question"],
+		["--target <path>", "destination directory (default: ./<name>)"],
+		["--from <path>", "read the template from a local path instead of the bundled one"]
+	],
+	pull: [
+		["--target .", "directory to refresh (default: current directory)"],
+		["--deps x,y", "limit the refresh to these dependencies"],
+		["--apply", "write the refreshed files (default is a dry run)"],
+		["--yes", "skip the confirmation question"],
+		["--strict", "fail (exit 1) on any drift, even non-fatal"]
+	],
+	audit: [
+		["--target .", "directory to audit (default: current directory)"],
+		["--live", "also check upstream freshness over the network"],
+		["--from <path>", "read the template from a local path instead of the bundled one"],
+		["--groups a,b", "limit the audit to these artifact groups"]
+	],
+	repair: [
+		["--target .", "directory to repair (default: current directory)"],
+		["--apply", "write the fixes (default is a dry run)"],
+		["--yes", "skip the confirmation question"],
+		["--prune", "also DELETE unexpected files under .claude/agents, .codex/agents, and scripts"],
+		["--from <path>", "read the template from a local path instead of the bundled one"]
+	],
+	fleet: [
+		["--apply", "write fixes across every package (default is a dry run)"],
+		["--yes", "skip the confirmation question"],
+		["--prune", "also DELETE unexpected files under .claude/agents, .codex/agents, and scripts, per package"],
+		["--from <path>", "read the template from a local path instead of the bundled one"]
+	],
+	catalog: [
+		["--from <path> ...", "one or more local package paths to include"],
+		["--target <repo>", "the repository whose Orkestrel agent catalog table gets updated"],
+		["--offline", "skip network lookups (npm registry) for package descriptions"],
+		["--apply", "write the updated table (default is a dry run)"],
+		["--yes", "skip the confirmation question"]
+	]
+});
+/** Dry-run and confirmation notes per command. */
+var VERB_DRY_RUN_NOTE = Object.freeze({
+	new: "dry run by default — add --apply to write the files, --yes to skip the question",
+	pull: "dry run by default — add --apply to write the refreshed files, --yes to skip the question",
+	audit: "read-only — audit never writes; pass --live to also check upstream freshness",
+	repair: "dry run by default — add --apply to write, --yes to skip the question",
+	fleet: "dry run by default — add --apply to write across every package, --yes to skip the question",
+	catalog: "dry run by default — add --apply to write, --yes to skip the question"
+});
+/** One concrete invocation per command. */
+var VERB_EXAMPLE = Object.freeze({
+	new: "example: scaffold new widget --src core,server --app core,browser --apply",
+	pull: "example: scaffold pull --apply",
+	audit: "example: scaffold audit --live",
+	repair: "example: scaffold repair --apply",
+	fleet: "example: scaffold fleet --apply --yes",
+	catalog: "example: scaffold catalog --apply"
+});
+/** Message used when a prune scan has no candidates. */
+var PRUNE_EMPTY = "no unexpected files to delete";
+/** Guidance for unexpected files outside a non-pruning repair handoff. */
+var FOREIGN_HINT = "unexpected files found — run 'scaffold repair --prune' to delete them";
+/** Interactive dependency prompt. */
+var ORKESTREL_DEPS_PROMPT = "@orkestrel dependencies (comma-separated short names, e.g. contract, emitter — installed as dependencies)";
+/** Catalog-degraded validation note. */
+var CATALOG_UNRESOLVED_NOTE = "couldn't resolve the vendored @orkestrel catalog — validating names by shape only";
+/** Catalog block destination in a scaffolded repository. */
+var CATALOG_AGENT_PATH = ".claude/agents/orkestrel.md";
+/** Opening marker for the generated package catalog block. */
+var CATALOG_START_MARKER = "<!-- catalog:start -->";
+/** Closing marker for the generated package catalog block. */
+var CATALOG_END_MARKER = "<!-- catalog:end -->";
+/** Non-terminal prune safety note. */
+var PRUNE_SKIPPED = "prune skipped — not a terminal; add --apply (or --yes) to delete non-interactively";
+/** Degraded unexpected-file scan note. */
+var SCAN_SKIPPED = "unexpected-file scanning skipped — couldn't establish the template source";
+//#endregion
+//#region src/bin/errors.ts
+/** Internal sentinel that unwinds command dispatch without bypassing cleanup. */
+var CLIExitError = class extends Error {
+	code;
+	constructor(code) {
+		super(`cli-exit:${String(code)}`);
+		this.code = code;
+	}
+};
+//#endregion
+//#region src/bin/shapers.ts
+/** Partition findings by whether repair owns their artifact origin. */
+function partitionFindings(findings, plan) {
 	const origins = new Map(plan.artifacts.map((artifact) => [artifact.path, artifact.origin]));
 	let ownedDrifted = 0;
 	let ownedMissing = 0;
@@ -73,13 +208,13 @@ function partitionOrigin(findings, plan) {
 	let generatedForeign = 0;
 	for (const finding of findings) {
 		const origin = origins.get(finding.path);
-		const isOwned = origin === "host" || origin === "template";
+		const owned = origin === "host" || origin === "template";
 		if (finding.drift === "aligned") continue;
-		else if (finding.drift === "stale") if (isOwned) ownedDrifted += 1;
+		if (finding.drift === "stale") if (owned) ownedDrifted += 1;
 		else generatedDrifted += 1;
-		else if (finding.drift === "missing") if (isOwned) ownedMissing += 1;
+		else if (finding.drift === "missing") if (owned) ownedMissing += 1;
 		else generatedMissing += 1;
-		else if (isOwned) ownedForeign += 1;
+		else if (owned) ownedForeign += 1;
 		else generatedForeign += 1;
 	}
 	return {
@@ -95,27 +230,88 @@ function partitionOrigin(findings, plan) {
 		}
 	};
 }
-/** `audit`'s verdict line — lowercase, verb-led, origin-split so template-owned health is immediately visible. */
+/** Create one deterministic fleet result entry. */
+function fleetEntryOf(name, counts, failed) {
+	return {
+		name,
+		drifted: counts?.drifted ?? 0,
+		missing: counts?.missing ?? 0,
+		foreign: counts?.foreign ?? 0,
+		failed
+	};
+}
+/** Create the command-line interface's machine-readable failure envelope. */
+function errorEnvelopeOf(code, message) {
+	return { error: {
+		code,
+		message
+	} };
+}
+/** Project a plan summary to the stable machine-readable `new` result. */
+function summaryToNewResult(summary, applied) {
+	return {
+		name: summary.name,
+		src: summary.src,
+		app: summary.app,
+		host: summary.host,
+		template: summary.template,
+		computed: summary.computed,
+		applied
+	};
+}
+/** Add a materialization result to an audit. */
+function auditToRepairResult(audit, result) {
+	return {
+		...audit,
+		result
+	};
+}
+/** Create the stable machine-readable catalog result. */
+function catalogResultOf(entries, drift, shrink) {
+	return shrink === void 0 ? {
+		entries,
+		drift
+	} : {
+		entries,
+		drift,
+		shrink
+	};
+}
+//#endregion
+//#region src/bin/helpers.ts
+/** Render one pluralized count. */
+function countPart(count, label) {
+	return `${count} ${label}${count === 1 ? "" : "s"}`;
+}
+/** Render nonzero audit buckets or `clean`. */
+function bucketText(counts) {
+	const parts = [];
+	if (counts.drifted > 0) parts.push(countPart(counts.drifted, "drifted"));
+	if (counts.missing > 0) parts.push(countPart(counts.missing, "missing"));
+	if (counts.foreign > 0) parts.push(countPart(counts.foreign, "unexpected"));
+	return parts.length > 0 ? parts.join(", ") : "clean";
+}
+/** Render audit's origin-aware verdict. */
 function auditVerdict(audit, plan) {
-	const total = audit.findings.length;
-	if (audit.clean) return `audit: ${countPart(total, "artifact")} — clean`;
-	const split = partitionOrigin(audit.findings, plan);
-	return split.owned.drifted === 0 && split.owned.missing === 0 && split.owned.foreign === 0 ? `audit: ${countPart(total, "artifact")} — template-owned clean; ${bucketText(split.generated)} (generated)` : `audit: ${countPart(total, "artifact")} — template-owned: ${bucketText(split.owned)}; generated: ${bucketText(split.generated)}`;
+	const count = audit.findings.length;
+	if (audit.clean) return `audit: ${countPart(count, "artifact")} — clean`;
+	const split = partitionFindings(audit.findings, plan);
+	return split.owned.drifted === 0 && split.owned.missing === 0 && split.owned.foreign === 0 ? `audit: ${countPart(count, "artifact")} — host-owned clean; ${bucketText(split.generated)} (generated)` : `audit: ${countPart(count, "artifact")} — host-owned: ${bucketText(split.owned)}; generated: ${bucketText(split.generated)}`;
 }
-/** One aligned-column row per non-`aligned` `Finding` — `[status, kind, path]`, translated labels, ready for `reporter.table`. */
+/** Render non-aligned audit findings as terminal table rows. */
 function findingRows(findings, plan) {
 	const origins = new Map(plan.artifacts.map((artifact) => [artifact.path, artifact.origin]));
 	return findings.filter((finding) => finding.drift !== "aligned").map((finding) => {
 		const origin = origins.get(finding.path);
-		const kind = origin === void 0 ? "unexpected file" : ORIGIN_LABEL[origin];
+		const category = origin === void 0 ? "unexpected file" : ORIGIN_LABEL[origin];
 		return [
 			DRIFT_LABEL[finding.drift],
-			kind,
+			category,
 			finding.path
 		];
 	});
 }
-/** The audit findings table — columns Status/Kind/Path, translated labels, via `reporter.table`. */
+/** Create audit's terminal table. */
 function auditTable(audit, plan) {
 	return {
 		columns: [
@@ -126,42 +322,36 @@ function auditTable(audit, plan) {
 		rows: findingRows(audit.findings, plan)
 	};
 }
-/** The banner `repair` opens with (dry-run AND `--apply`) — its scope is the template-owned set only. */
-var REPAIR_SCOPE = "repair scope: shared template-owned artifacts only — generated source/tests/configs are never touched";
-/** The `repair` note pointing at drift outside its scope — `undefined` when there is none. */
-function scopeNote(outsideCount) {
-	if (outsideCount === 0) return void 0;
-	return `note: ${countPart(outsideCount, "finding")} outside repair's scope — run 'audit' for the list; generated files are yours to edit`;
+/** Render drift outside repair's ownership boundary. */
+function scopeNote(count) {
+	if (count === 0) return void 0;
+	return `note: ${countPart(count, "finding")} outside repair's scope — run 'audit' for the list; generated files are yours to edit`;
 }
-/** `repair`'s dry-run verdict line. */
+/** Render repair's dry-run verdict. */
 function repairVerdict(audit) {
-	if (audit.clean) return `repair: ${countPart(audit.findings.length, "template-owned artifact")} aligned — nothing to write`;
-	return `repair: ${bucketText({
-		drifted: audit.drifted,
-		missing: audit.missing,
-		foreign: audit.foreign
-	})} — pass --apply to write`;
+	if (audit.clean) return `repair: ${countPart(audit.findings.length, "host-owned artifact")} aligned — nothing to write`;
+	return `repair: ${bucketText(audit)} — pass --apply to write`;
 }
-/** `repair --apply`'s success line — the materializer tally, translated action words. */
+/** Render repair's materialization tally. */
 function repairSuccess(result, removed) {
 	const written = result.written.length + result.copied.length;
 	return `${ACTION_LABEL.written} ${written}, ${ACTION_LABEL.skipped} ${result.skipped.length}, ${ACTION_LABEL.removed} ${removed.length}`;
 }
-/** `pull`'s freshness table rows — `[name, kind, freshness]`, translated. */
+/** Render pull freshness as table rows. */
 function pullRows(report) {
-	const guideRows = report.guides.map((guide) => [
+	const guides = report.guides.map((guide) => [
 		guide.name,
 		"guide",
 		FRESHNESS_LABEL[guide.freshness] ?? guide.freshness
 	]);
-	const versionRows = report.versions.map((version) => [
+	const versions = report.versions.map((version) => [
 		version.name,
 		"version",
 		FRESHNESS_LABEL[version.freshness] ?? version.freshness
 	]);
-	return [...guideRows, ...versionRows];
+	return [...guides, ...versions];
 }
-/** `pull`'s freshness table — columns Name/Kind/Freshness. */
+/** Create pull's terminal table. */
 function pullTable(report) {
 	return {
 		columns: [
@@ -172,162 +362,93 @@ function pullTable(report) {
 		rows: pullRows(report)
 	};
 }
-/** Per-entry cause notes for a non-`current` `pull` entry that carries a `note`. */
+/** Render cause notes from non-current pull entries. */
 function pullCauseNotes(report) {
 	return [...report.guides, ...report.versions].filter((entry) => entry.note !== void 0).map((entry) => `  ${entry.name}: ${FRESHNESS_LABEL[entry.freshness] ?? entry.freshness} — ${entry.note}`);
 }
-/** `pull`'s tally line. */
+/** Render pull's tally. */
 function pullVerdict(report) {
 	return `pull: ${countPart(report.guides.length + report.versions.length, "entry")} — ${countPart(report.failed, "failed")}`;
 }
-/** `pull --apply`'s success line. */
+/** Render pull's success tally. */
 function pullSuccess(count) {
 	return `wrote ${countPart(count, "guide")}`;
 }
-/** One `fleet` per-repo line — clean, drifted (dry-run), or repaired (`--apply`). */
+/** Render one fleet repository outcome. */
 function fleetRepoLine(name, outcome) {
-	if (outcome.kind === "clean") return `${name}: clean`;
-	if (outcome.kind === "drifted") return `${name}: ${bucketText({
-		drifted: outcome.drifted,
-		missing: outcome.missing,
-		foreign: outcome.foreign
-	})}`;
-	if (outcome.kind === "repaired") return `${name}: repaired (${countPart(outcome.remaining, "finding")} remaining)`;
+	if (outcome.state === "clean") return `${name}: clean`;
+	if (outcome.state === "drifted") return `${name}: ${bucketText(outcome)}`;
+	if (outcome.state === "repaired") return `${name}: repaired (${countPart(outcome.remaining, "finding")} remaining)`;
 	return `${name}: ${outcome.message}`;
 }
-/** `fleet`'s blast-radius totals line. */
+/** Render fleet's repository totals. */
 function fleetTotals(drifted, failed) {
 	return `total: ${countPart(drifted, "drifted repo")}, ${countPart(failed, "failed")}`;
 }
-/** The `catalog` terminal preview table — columns Package/Version (descriptions live only in the written table and `--json`). */
+/** Create catalog's terminal table. */
 function catalogTable(entries) {
 	return {
 		columns: [{ label: "Package" }, { label: "Version" }],
 		rows: entries.map((entry) => [entry.name, entry.version])
 	};
 }
-/** The `catalog` shrink warning — `undefined` when the table did not shrink. */
+/** Render catalog shrink risk when present. */
 function catalogShrinkWarning(oldRows, newRows) {
 	if (newRows >= oldRows) return void 0;
 	return `warning: catalog shrinks from ${countPart(oldRows, "row")} to ${newRows}`;
 }
-/** `catalog`'s counts line. */
-function catalogCounts(published, localOnly) {
-	return `catalog: ${countPart(published, "published package")}, ${countPart(localOnly, "local-only")}`;
+/** Render catalog source tallies. */
+function catalogCounts(published, local) {
+	return `catalog: ${countPart(published, "published package")}, ${countPart(local, "local-only")}`;
 }
-/** `new`'s dry-run plan preview — origin counts table description + the destination line. */
-function newPlanTable(scaffolding) {
+/** Create `new`'s plan summary table. */
+function newPlanTable(summary) {
 	return {
 		columns: [{ label: "Origin" }, {
 			label: "Count",
 			align: "right"
 		}],
-		rows: [["template-owned", String(scaffolding.host + scaffolding.template)], ["generated", String(scaffolding.computed)]]
+		rows: [
+			["host-owned", String(summary.host)],
+			["starter", String(summary.template)],
+			["generated", String(summary.computed)]
+		]
 	};
 }
-/** `new`'s dry-run destination line. */
+/** Render `new`'s dry-run destination. */
 function newPlanPreview(name) {
 	return `will write into ./${name}`;
 }
-/** `new --apply`'s success line. */
+/** Render `new`'s write result. */
 function newApplySuccess(count, name) {
 	return `wrote ${countPart(count, "file")} into ./${name}`;
 }
-/** `new`'s dry-run declined-apply note. */
-var NEW_DRY_RUN_NOTE = "dry run — pass --apply to write";
-/** `catalog --apply`'s success line. */
+/** Render catalog's write result. */
 function catalogApplySuccess(path) {
 	return `wrote ${path}`;
 }
-/** The fallback line for a `parseArgs` failure that carries no `Error` message of its own. */
-var INVALID_ARGUMENTS_MESSAGE = "invalid arguments";
-/** The apply-confirm prompt message — singular repo, or fleet-wide across `repos` when given. */
-function applyConfirmMessage(fileCount, repoCount) {
-	const scope = repoCount === void 0 ? "" : ` across ${countPart(repoCount, "repo")}`;
-	return `Apply — write ${countPart(fileCount, "file")}${scope}? `;
+/** Render the shared write confirmation. */
+function applyConfirmMessage(files, repos) {
+	const scope = repos === void 0 ? "" : ` across ${countPart(repos, "repo")}`;
+	return `Apply — write ${countPart(files, "file")}${scope}? `;
 }
-/** The prune double-confirm prompt message. */
+/** Render the separate prune confirmation. */
 function pruneConfirmMessage(count) {
-	return `Also delete ${countPart(count, "unexpected file")} under .claude/agents and scripts? `;
+	return `Also delete ${countPart(count, "unexpected file")} under .claude/agents, .codex/agents, and scripts? `;
 }
-/**
-* The audit→repair handoff prompt message — names what will actually be
-* acted on: `owned` template-owned files with drift, and (only when `prune`
-* is active) `foreign` unexpected files that will be deleted. Never promises
-* a deletion the handoff will not perform — `prune` gates the foreign clause.
-*/
+/** Render the interactive audit-to-repair handoff. */
 function repairHandoff(owned, foreign, prune) {
 	const parts = [];
-	if (owned > 0) parts.push(`${countPart(owned, "template-owned file")} ${owned === 1 ? "has" : "have"} drift`);
+	if (owned > 0) parts.push(`${countPart(owned, "host-owned file")} ${owned === 1 ? "has" : "have"} drift`);
 	if (prune && foreign > 0) parts.push(`${countPart(foreign, "unexpected file")} will be deleted`);
 	return `${parts.join(" and ")} — run repair now? `;
 }
-/** Printed when unexpected files exist but the handoff cannot help them (no `--prune`, or no handoff offered at all) — points at the one command that can. */
-function foreignHint() {
-	return "unexpected files found — run 'scaffold repair --prune' to delete them";
-}
-/** `new`'s interactive Q1 prompt (TTY only) — `@orkestrel` short-name deps, landing in `dependencies`. */
-function orkestrelDepsPrompt() {
-	return "@orkestrel dependencies (comma-separated short names, e.g. contract, emitter — installed as dependencies)";
-}
-/**
-* Re-ask wording for a Q1 token that does not resolve against the vendored
-* `@orkestrel` catalog — names the offending token and, when one was found,
-* the nearest catalog name (`render.ts`'s own `nearest`).
-*/
+/** Render one unresolved Orkestrel dependency token. */
 function unknownOrkestrelToken(token, suggestion) {
-	const base = `"${token}" is not a published @orkestrel package`;
-	return suggestion === void 0 ? `${base} — try again` : `${base} — did you mean "${suggestion}"? try again`;
-}
-/** Printed once when the vendored `@orkestrel` catalog cannot be resolved — Q1 degrades to shape-only (`DEPENDENCY_NAME_PATTERN`) validation instead of blocking on it. */
-function catalogUnresolvedNote() {
-	return "couldn't resolve the vendored @orkestrel catalog — validating names by shape only";
-}
-/** The line printed when a confirm prompt is declined. */
-var CANCELLED_MESSAGE = "cancelled — nothing written";
-/** `new`'s surface checkbox choices — per-choice descriptions grounded on the terminal guide's surface semantics. */
-function surfaceChoices() {
-	return [
-		{
-			name: "core",
-			value: "core",
-			description: "the pure engine"
-		},
-		{
-			name: "browser",
-			value: "browser",
-			description: "DOM-facing surface"
-		},
-		{
-			name: "server",
-			value: "server",
-			description: "node-facing surface"
-		}
-	];
+	const message = `"${token}" is not a published @orkestrel package`;
+	return suggestion === void 0 ? `${message} — try again` : `${message} — did you mean "${suggestion}"? try again`;
 }
-/** The safety-model banner every full-help tier includes. */
-var SAFETY_BANNER = [
-	"safety: every verb is a dry run by default.",
-	"on a terminal, a write prompts for confirmation; in a script, pass --apply (and --yes to skip the confirm).",
-	"every write is confined to the current working directory — cd there first.",
-	"TLS trusts the system certificate store automatically (corporate proxies); NODE_EXTRA_CA_CERTS adds custom PEMs."
-].join("\n");
-/** The exit-code reference table every full-help tier includes. */
-var EXIT_CODES = [
-	["0", "clean / success"],
-	["1", "drift or failure"],
-	["2", "usage error"]
-];
-/** One-line-per-verb summaries — the short and full help tiers share this table. */
-var VERB_SUMMARY = Object.freeze({
-	new: "scaffold a package into ./<name>",
-	pull: "refresh vendored guides/versions, report drift",
-	audit: "whole-plan conformance report",
-	repair: "restore the shared template-owned set",
-	fleet: "audit/repair every package under the cwd's immediate children",
-	catalog: "regenerate the fleet package-catalog table"
-});
-/** ≤10 lines: one-liner per verb plus the escape hatch to `verbHelp`. */
+/** Render compact command usage. */
 function shortUsage() {
 	return [
 		"scaffold <verb> [options]",
@@ -337,383 +458,129 @@ function shortUsage() {
 		"run 'scaffold <verb> --help' for a verb's full reference"
 	].join("\n");
 }
-/** Each verb's flag reference — the fullHelp reference and verbHelp share this table. */
-var VERB_FLAGS = Object.freeze({
-	new: "--surfaces a,b --deps x,y --apply --yes --target <path> --from <path>",
-	pull: "--target . --deps x,y --apply --yes --strict",
-	audit: "--target . --live --from <path> --groups a,b",
-	repair: "--target . --apply --yes --prune --from <path>",
-	fleet: "--apply --yes --prune --from <path>",
-	catalog: "--from <path> ... --target <repo> --offline --apply --yes"
-});
-/** Per-verb, per-flag plain-language descriptions — `verbHelp`'s one-line-per-flag body. `--prune` is marked destructive. */
-var VERB_FLAG_HELP = Object.freeze({
-	new: [
-		["--surfaces a,b", "which surfaces to include (core, browser, server)"],
-		["--deps x,y", "@orkestrel/* dependencies to add (installed as dependencies)"],
-		["--apply", "write the files (default is a dry run)"],
-		["--yes", "skip the confirmation question"],
-		["--target <path>", "destination directory (default: ./<name>)"],
-		["--from <path>", "read the template from a local path instead of the bundled one"]
-	],
-	pull: [
-		["--target .", "directory to refresh (default: current directory)"],
-		["--deps x,y", "limit the refresh to these dependencies"],
-		["--apply", "write the refreshed files (default is a dry run)"],
-		["--yes", "skip the confirmation question"],
-		["--strict", "fail (exit 1) on any drift, even non-fatal"]
-	],
-	audit: [
-		["--target .", "directory to audit (default: current directory)"],
-		["--live", "also check upstream freshness over the network"],
-		["--from <path>", "read the template from a local path instead of the bundled one"],
-		["--groups a,b", "limit the audit to these artifact groups"]
-	],
-	repair: [
-		["--target .", "directory to repair (default: current directory)"],
-		["--apply", "write the fixes (default is a dry run)"],
-		["--yes", "skip the confirmation question"],
-		["--prune", "also DELETE unexpected files under .claude/agents and scripts"],
-		["--from <path>", "read the template from a local path instead of the bundled one"]
-	],
-	fleet: [
-		["--apply", "write fixes across every package (default is a dry run)"],
-		["--yes", "skip the confirmation question"],
-		["--prune", "also DELETE unexpected files under .claude/agents and scripts, per package"],
-		["--from <path>", "read the template from a local path instead of the bundled one"]
-	],
-	catalog: [
-		["--from <path> ...", "one or more local package paths to include"],
-		["--target <repo>", "the repo whose README catalog table gets updated"],
-		["--offline", "skip network lookups (npm registry) for package descriptions"],
-		["--apply", "write the updated table (default is a dry run)"],
-		["--yes", "skip the confirmation question"]
-	]
-});
-/** The dry-run/confirm note per verb — `audit` never writes, so its note says so instead. */
-var VERB_DRY_RUN_NOTE = Object.freeze({
-	new: "dry run by default — add --apply to write the files, --yes to skip the question",
-	pull: "dry run by default — add --apply to write the refreshed files, --yes to skip the question",
-	audit: "read-only — audit never writes; pass --live to also check upstream freshness",
-	repair: "dry run by default — add --apply to write, --yes to skip the question",
-	fleet: "dry run by default — add --apply to write across every package, --yes to skip the question",
-	catalog: "dry run by default — add --apply to write, --yes to skip the question"
-});
-/** One concrete example invocation per verb — `verbHelp`'s closing line. */
-var VERB_EXAMPLE = Object.freeze({
-	new: "example: scaffold new widget --surfaces core,server --apply",
-	pull: "example: scaffold pull --apply",
-	audit: "example: scaffold audit --live",
-	repair: "example: scaffold repair --apply",
-	fleet: "example: scaffold fleet --apply --yes",
-	catalog: "example: scaffold catalog --apply"
-});
-/** The full reference help tier — every verb's summary + flags, the safety banner, and the exit-code table. */
+/** Render the full command reference. */
 function fullHelp() {
-	const verbLines = KNOWN_VERBS.map((verb) => `  ${verb} ${VERB_FLAGS[verb]}\n    ${VERB_SUMMARY[verb]}`);
-	const exitLines = EXIT_CODES.map(([code, meaning]) => `  ${code}  ${meaning}`);
+	const verbs = KNOWN_VERBS.map((verb) => `  ${verb} ${VERB_FLAGS[verb]}\n    ${VERB_SUMMARY[verb]}`);
+	const exits = EXIT_CODES.map(([code, meaning]) => `  ${code}  ${meaning}`);
 	return [
 		"scaffold <verb> [options]",
 		"",
-		...verbLines,
+		...verbs,
 		"",
 		SAFETY_BANNER,
 		"",
 		"exit codes:",
-		...exitLines
+		...exits
 	].join("\n");
 }
-/** One verb's help section — summary, dry-run note, one line per flag, and a concrete example. */
+/** Render one command's help reference. */
 function verbHelp(verb) {
-	const flagLines = VERB_FLAG_HELP[verb].map(([flag, meaning]) => `  ${flag.padEnd(20)}${meaning}`);
+	const flags = VERB_FLAG_HELP[verb].map(([flag, meaning]) => `  ${flag.padEnd(20)}${meaning}`);
 	return [
 		`scaffold ${verb} ${VERB_FLAGS[verb]}`,
 		"",
 		VERB_SUMMARY[verb],
 		VERB_DRY_RUN_NOTE[verb],
 		"",
-		...flagLines,
+		...flags,
 		"",
 		VERB_EXAMPLE[verb]
 	].join("\n");
 }
-/** Levenshtein edit distance between two strings — the did-you-mean primitive. */
-function editDistance(a, b) {
-	const rows = a.length + 1;
-	const cols = b.length + 1;
-	const table = Array.from({ length: rows }, () => new Array(cols).fill(0));
-	for (let i = 0; i < rows; i += 1) table[i][0] = i;
-	for (let j = 0; j < cols; j += 1) table[0][j] = j;
-	for (let i = 1; i < rows; i += 1) for (let j = 1; j < cols; j += 1) {
-		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-		table[i][j] = Math.min(table[i - 1][j] + 1, table[i][j - 1] + 1, table[i - 1][j - 1] + cost);
+/** Compute Levenshtein edit distance. */
+function editDistance(left, right) {
+	const rows = left.length + 1;
+	const columns = right.length + 1;
+	const table = new Uint32Array(rows * columns);
+	for (let row = 0; row < rows; row += 1) table[row * columns] = row;
+	for (let column = 0; column < columns; column += 1) table[column] = column;
+	for (let row = 1; row < rows; row += 1) for (let column = 1; column < columns; column += 1) {
+		const cost = left[row - 1] === right[column - 1] ? 0 : 1;
+		const index = row * columns + column;
+		table[index] = Math.min((table[index - columns] ?? 0) + 1, (table[index - 1] ?? 0) + 1, (table[index - columns - 1] ?? 0) + cost);
 	}
-	return table[rows - 1][cols - 1];
+	return table[rows * columns - 1] ?? 0;
 }
-/** The nearest candidate to `input` by `editDistance` — `undefined` when `set` is empty. */
+/** Find the nearest string by edit distance. */
 function nearest(input, set) {
 	let best;
-	let bestDistance = Number.POSITIVE_INFINITY;
+	let distance = Number.POSITIVE_INFINITY;
 	for (const candidate of set) {
-		const distance = editDistance(input, candidate);
-		if (distance < bestDistance) {
-			bestDistance = distance;
+		const candidateDistance = editDistance(input, candidate);
+		if (candidateDistance < distance) {
+			distance = candidateDistance;
 			best = candidate;
 		}
 	}
 	return best;
 }
-/** Retired verb names redirected to their replacement — checked before fuzzy matching in `didYouMean`. */
-var RETIRED_VERBS = Object.freeze({
-	sync: "pull",
-	mirror: "fleet"
-});
-/** The unknown-command message — a retired-verb redirect when recognized, otherwise the nearest `KNOWN_VERBS` guess. */
+/** Render an unknown command with a nearest-command hint. */
 function didYouMean(command) {
-	const retired = RETIRED_VERBS[command];
-	if (retired !== void 0) return `'${command}' has been renamed — use 'scaffold ${retired}'`;
-	const guess = nearest(command, [...KNOWN_VERBS]);
-	return guess === void 0 ? `unknown command "${command}"` : `unknown command "${command}" — did you mean "${guess}"?`;
+	const suggestion = nearest(command, KNOWN_VERBS);
+	return suggestion === void 0 ? `unknown command "${command}"` : `unknown command "${command}" — did you mean "${suggestion}"?`;
 }
-/** One JSON error envelope — the single shape every `--json` failure returns. */
-function errorEnvelope(code, message) {
-	return { error: {
-		code,
-		message
-	} };
+/** Render one prune preview line per exact path. */
+function prunePreview(paths) {
+	return paths.map((path) => `  delete ${path}`);
 }
-/** `new --json`'s value — the plan summary, deterministic key order. */
-function newJson(summary, applied) {
-	return {
-		name: summary.name,
-		surfaces: summary.surfaces,
-		host: summary.host,
-		template: summary.template,
-		computed: summary.computed,
-		applied
-	};
+/** Render non-terminal guidance for missing input. */
+function missingInput(input, verb) {
+	return `missing ${input} — pass it as a flag/argument, or run 'scaffold ${verb}' on a terminal to be guided`;
 }
-/** `pull --json`'s value — the `SyncReport` verbatim (already deterministic + JSON-safe). */
-function pullJson(report) {
-	return report;
+/** Render an invalid package name. */
+function invalidName(name, pattern) {
+	return `Package name "${name}" must match ${pattern}`;
 }
-/** `audit --json`'s value — the `Audit` verbatim. */
-function auditJson(audit) {
-	return audit;
+/** Render dependencies whose latest versions could not be resolved. */
+function unresolvedVersion(names) {
+	return `could not resolve the latest version for ${names.map((name) => `"${name}"`).join(", ")} — check the name or pass name@range`;
 }
-/** `repair --json`'s value — the `Audit` plus the `MaterializeResult` when `--apply` ran. */
-function repairJson(audit, result) {
-	return result === void 0 ? audit : {
-		...audit,
-		result
-	};
-}
-/** `fleet --json`'s value — a top-level ARRAY of per-repo objects, one entry per package. */
-function fleetJson(entries) {
-	return entries;
-}
-/** `catalog --json`'s value — the entries, drift flag, and optional shrink count. */
-function catalogJson(entries, drifted, shrink) {
-	return shrink === void 0 ? {
-		entries,
-		drift: drifted
-	} : {
-		entries,
-		drift: drifted,
-		shrink
-	};
-}
-/** `enabled` for `createStyler` — off under `NO_COLOR` or when the sink is not a TTY (both read by the caller). */
-function chooseStyler(sinkIsTTY, noColor) {
-	return createStyler({ enabled: !noColor && sinkIsTTY });
-}
-/** Whether a long-running step should animate a spinner (TTY) or fall back to a one-line `status` (piped/non-TTY). */
-function shouldSpin(sinkIsTTY) {
-	return sinkIsTTY;
-}
-/** One line per exact relative path that WOULD be deleted — printed before the prune confirm. */
-function prunePreview(paths) {
-	return paths.map((path) => `  delete ${path}`);
-}
-/** Printed when the prune scan finds nothing to delete. */
-var PRUNE_EMPTY = "no unexpected files to delete";
-/** Printed on a non-TTY session when the prune question cannot be asked. */
-function pruneSkipped() {
-	return "prune skipped — not a terminal; add --apply (or --yes) to delete non-interactively";
-}
-/** Non-TTY usage-error guidance for a missing required input. */
-function missingInput(what, verb) {
-	return `missing ${what} — pass it as a flag/argument, or run 'scaffold ${verb}' on a terminal to be guided`;
-}
-/** Printed when `audit` cannot establish the template source for the unexpected-file scan — the audit degrades to the un-scanned findings instead of crashing. */
-function scanSkipped() {
-	return "unexpected-file scanning skipped — couldn't establish the template source";
-}
-/** Usage-error message for a `new` package name that fails `PACKAGE_NAME_PATTERN` — same shape the interactive prompt enforces. */
-function invalidName(name, pattern) {
-	return `Package name "${name}" must match ${pattern}`;
-}
-/** `new`'s hard failure when `sync.versions` cannot resolve a latest version for one or more `--deps` names — names every unresolved package plainly so a `^` (unresolved-latest) range can never be silently written. */
-function unresolvedVersion(names) {
-	return `could not resolve the latest version for ${names.map((name) => `"${name}"`).join(", ")} — check the name or pass name@range`;
-}
-/** Printed when every finding is `generated` drift — repair does not touch generated files. */
+/** Render drift that belongs to generated artifacts. */
 function generatedNote(count) {
 	return `${countPart(count, "finding")} in generated files — these are regenerated, not hand-edited; repair does not touch them`;
 }
-/** `audit --live`'s freshness summary line. */
+/** Render live dependency freshness tallies. */
 function auditLiveNote(current, behind, failed) {
 	return `live: ${countPart(current, "current")}, ${countPart(behind, "behind")}, ${countPart(failed, "failed")}`;
 }
-/** Translated vocabulary for whether the audit compared file contents or only file names, for template-owned files. */
+/** Render whether an audit compared content or presence. */
 function comparisonLine(aware) {
-	return aware ? "comparing: file contents for template-owned files" : "comparing: file names only for template-owned files (no vendored source found)";
+	return aware ? "comparing: file contents for host-owned files" : "comparing: file names only for host-owned files (no vendored source found)";
 }
-/** `fleet`'s ci.yml note — each package customizes its own CI, so `fleet` leaves it unchanged. */
-function fleetCiSkipped() {
-	return "ci.yml: left unchanged — each package customizes its own CI; run 'scaffold repair --apply' inside that package to update it";
-}
-/** `catalog`'s verdict line — clean or drifted. */
+/** Render catalog's final verdict. */
 function catalogVerdict(clean) {
 	return clean ? "catalog: clean" : "catalog: drifted — pass --apply to write";
 }
-//#endregion
-//#region src/bin/scaffold.ts
-var sink = createServerSink();
-var sinkIsTTY = process.stdout.isTTY === true;
-var styler = chooseStyler(sinkIsTTY, process.env.NO_COLOR !== void 0);
-var reporter = createReporter({
-	sink,
-	width: sink.columns,
-	styler
-});
-/**
-* Widen Node's default trusted-issuer set to include the OS certificate
-* store, so `fetch` behind a corporate TLS-inspecting proxy behaves like npm
-* (`cafile`) and browsers (OS trust store) instead of failing with
-* `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` against Node's bundled CA list alone.
-* Feature-detected (`tls.getCACertificates` / `tls.setDefaultCACertificates`
-* ship on Node ≈22.16+/24.5+; this package's floor is `>=22`) and wrapped in
-* try/catch — any failure is a silent no-op, never a crash. This only ADDS
-* trusted issuers; it never touches `rejectUnauthorized` or
-* `NODE_TLS_REJECT_UNAUTHORIZED`, so certificate verification stays on.
-*/
-function trustSystemCertificates() {
-	if (typeof tls.getCACertificates !== "function" || typeof tls.setDefaultCACertificates !== "function") return;
-	try {
-		const merged = /* @__PURE__ */ new Set([...tls.getCACertificates("default"), ...tls.getCACertificates("system")]);
-		tls.setDefaultCACertificates([...merged]);
-	} catch {}
-}
-/**
-* The one sentinel that unwinds the whole command dispatch to a chosen exit
-* code (H4/Windows) — thrown instead of calling `process.exit`, so every
-* `finally` between the throw site and the top-level driver still runs
-* (entity teardown drains naturally instead of racing process teardown).
-* Caught exactly once, at the bottom of this file.
-*/
-var CliExit = class extends Error {
-	code;
-	constructor(code) {
-		super(`cli-exit:${String(code)}`);
-		this.code = code;
-	}
-};
-/** Halt command dispatch with `code` (H4) — never `process.exit`; unwinds through every `finally` first. */
-function halt(code) {
-	throw new CliExit(code);
-}
-/** Render a caught error as a clean one-line message — a `ScaffoldError`'s code, or a bare message otherwise. */
-function describe(error) {
+/** Render a caught error without leaking implementation detail. */
+function describeError(error) {
 	if (isScaffoldError(error)) return `[${error.code}] ${error.message}`;
 	return error instanceof Error ? error.message : "unknown error";
 }
-/** Write ONE machine-readable JSON value to stdout — the entire `--json` output contract. */
-function writeJson(value) {
-	process.stdout.write(`${JSON.stringify(value)}\n`);
-}
-/**
-* Whether the current invocation carries `--json` — set once `parseArguments`
-* has run (`main`'s first act), so the OUTERMOST catch (bottom of this file)
-* can still honor `--json` for an error that escapes every verb runner's own
-* handling, emitting exactly one JSON error envelope instead of prose.
-*/
-var sessionJson = false;
-/** A general operation failure (H1: exit 1) — a prose status line, or the one JSON error envelope under `--json`. */
-function fail(message, json) {
-	if (json) writeJson(errorEnvelope("ERROR", message));
-	else reporter.status("error", message);
-	halt(1);
-}
-/**
-* A general operation failure FROM A CAUGHT ERROR (H1: exit 1) — the real
-* `ScaffoldError` code when available ('ERROR' last resort), prose (via
-* `describe`, which still carries the bracketed code for a human reader) or
-* the one JSON error envelope under `--json` (code and message kept
-* SEPARATE — never double-encoding the code into the message text).
-*/
-function failError(error, json) {
-	if (json) writeJson(errorEnvelope(isScaffoldError(error) ? error.code : "ERROR", isScaffoldError(error) ? error.message : describe(error)));
-	else reporter.status("error", describe(error));
-	halt(1);
-}
-/** A usage error (bad flag value, unknown verb — exit 2) — stderr prose, or the one JSON error envelope under `--json`. */
-function usageFail(message, json) {
-	if (json) writeJson(errorEnvelope("USAGE", message));
-	else process.stderr.write(`${message}\n`);
-	halt(2);
-}
-function resolveReal(path) {
-	if (existsSync(path)) return realpathSync(path);
-	const parent = dirname(path);
-	if (parent === path) return path;
-	return join(resolveReal(parent), relative(parent, path));
-}
-/**
-* Confine a WRITE destination to the current working directory (global-CLI
-* safety): `new`'s resolved target, `--target` on pull/audit/repair/catalog,
-* and `fleet`'s always-cwd root all pass through here before use. A
-* READ-ONLY source (`--from`) is exempt — sibling-repo sourcing from outside
-* the cwd is legitimate. Equal to the cwd or nested beneath it passes;
-* anything else is a coded `INVALID` failure (AGENTS §12), never a silent clamp.
-*
-* @returns The resolved (non-realpath'd) absolute path, for use as the
-* verb's destination.
-*/
-function containDestination(candidate) {
-	const resolvedCwd = resolveReal(resolve(process.cwd()));
-	const resolvedCandidate = resolveReal(resolve(candidate));
-	if (resolvedCandidate !== resolvedCwd && !resolvedCandidate.startsWith(resolvedCwd + sep)) throw new ScaffoldError("INVALID", `Target "${candidate}" escapes the working directory — run scaffold from the directory you want to write beneath.`, { path: candidate });
-	return resolve(candidate);
-}
-/** `containDestination`, halting (H1/`fail`) on a coded escape instead of throwing — the shared entry every runner's target resolution goes through. */
-function containOrFail(candidate, json) {
-	try {
-		return containDestination(candidate);
-	} catch (error) {
-		failError(error, json);
-	}
+/** Resolve and confine one write destination to its invocation root. */
+function containDestination(root, candidate) {
+	if (!isFilesystemPath(root) || !isFilesystemPath(candidate)) throw new ScaffoldError("INVALID", "Target paths must not contain control characters");
+	const contained = attempt(() => resolvePhysicalPath(root, candidate, "INVALID", "working directory"));
+	if (contained.success) return contained.value;
+	if (isScaffoldError(contained.error) && contained.error.code === "INVALID") throw new ScaffoldError("INVALID", `Target "${candidate}" is outside or traverses a linked parent of the working directory — run scaffold from the physical directory you want to write beneath.`, { path: candidate });
+	throw contained.error;
 }
-/** Compile `spec` and unwrap its `plan`, halting (H1/`fail`) with the joined open-question text when compilation could not resolve one — the shared entry every runner's compile step goes through. */
-function compileOrFail(spec, json) {
-	const compiler = createCompiler();
-	try {
-		const scaffolding = compiler.compile(spec);
-		if (!scaffolding.plan) fail(scaffolding.questions.map((question) => question.text).join("; "), json);
-		return scaffolding.plan;
-	} finally {
-		compiler.destroy();
-	}
+/** Return one dependency-token issue, or absence when it is valid. */
+function orkestrelTokenIssue(normalized, catalog) {
+	if (catalog === void 0) return DEPENDENCY_NAME_PATTERN.test(normalized) ? void 0 : unknownOrkestrelToken(normalized, void 0);
+	if (catalog.includes(normalized)) return void 0;
+	return unknownOrkestrelToken(normalized, nearest(normalized, catalog));
 }
-/** `node:util`'s strict `parseArgs`, isolated so its throw on an unknown/malformed flag is catchable (H3). */
-function parseArguments() {
-	const args = process.argv.slice(2);
-	if (args[0] === "--") args.shift();
+//#endregion
+//#region src/bin/parsers.ts
+/** Parse a strict command-line argument vector. */
+function parseArguments(argv) {
+	if (argv.some((argument) => !isTerminalText(argument))) throw new ScaffoldError("INVALID", "Command arguments must not contain control characters");
 	return parseArgs({
-		args,
+		args: argv[0] === "--" ? argv.slice(1) : [...argv],
 		allowPositionals: true,
 		options: {
-			surfaces: { type: "string" },
+			src: { type: "string" },
+			app: { type: "string" },
 			deps: { type: "string" },
 			groups: { type: "string" },
 			target: { type: "string" },
@@ -757,783 +624,878 @@ function parseArguments() {
 		}
 	});
 }
-/** Narrow a positional command to the closed `Verb` vocabulary (render.ts's `KNOWN_VERBS`). */
-function isVerb(value) {
-	return KNOWN_VERBS.some((verb) => verb === value);
-}
-/**
-* Best-effort `hydratePlan` — used by `audit` / `repair` / `fleet` so a
-* missing DEFAULT vendored-source root degrades to presence-only auditing
-* instead of failing the verb. An EXPLICITLY-passed `--from` that does not
-* resolve to a usable directory is NOT downgraded silently — that is a coded
-* `TARGET` failure (M1), since the caller named that source on purpose.
-*/
-function hydrateBestEffort(plan, host, explicit) {
-	if (!existsSync(host)) {
-		if (explicit) throw new ScaffoldError("TARGET", `--from does not resolve to a directory: ${host}`, { host });
-		return {
-			plan,
-			aware: false
-		};
-	}
-	try {
-		return {
-			plan: hydratePlan(plan, host),
-			aware: true
-		};
-	} catch (error) {
-		if (isScaffoldError(error) && error.code === "TARGET") return {
-			plan,
-			aware: false
-		};
-		throw error;
-	}
-}
-/**
-* Merge a `pruneTargets` scan into `audit` as `foreign` findings — pure
-* object-spread composition in the BIN only (`src/core`'s `diffPlan` is never
-* modified/reimplemented). Every unexpected path becomes one
-* `'orchestration'`-group `foreign` finding (the `Group` every `PRUNE_DIRECTORIES`
-* entry — `.claude/agents`, `scripts` — belongs to); any scan hit makes the
-* merged audit unclean, so an "unexpected file" is honestly counted as drift
-* (exit 1) instead of the structurally-always-zero `diffPlan.foreign`.
-*/
-function withForeignScan(audit, target, host) {
-	const paths = pruneTargets(target, host);
-	if (paths.length === 0) return audit;
-	const findings = paths.map((path) => ({
-		path,
-		group: "orchestration",
-		drift: "foreign"
-	}));
-	return {
-		...audit,
-		clean: false,
-		foreign: audit.foreign + paths.length,
-		findings: [...audit.findings, ...findings]
-	};
-}
-/**
-* `withForeignScan`, degrading instead of crashing (F3): `pruneTargets` throws
-* a coded `TARGET` failure when a prune directory exists under `target` but
-* `host` cannot positively establish its allowlist (`vendoredPruneSet`'s
-* fail-closed contract) — an audit should report the un-scanned findings and
-* say scanning was skipped, never crash on this alone (`runFleet` already
-* shields its own per-repo audit the same way).
-*/
-function withForeignScanSafe(audit, target, host) {
-	try {
-		return {
-			audit: withForeignScan(audit, target, host),
-			skipped: false
-		};
-	} catch (error) {
-		if (isScaffoldError(error) && error.code === "TARGET") return {
-			audit,
-			skipped: true
-		};
-		throw error;
-	}
-}
-/**
-* `repair`'s own scope is host-only, but the caller compiles the FULL plan anyway — diff it too
-* (cheap, local, no network) so a clean host verdict can point at drift OUTSIDE repair's reach.
-* The count feeds render.ts's `scopeNote`.
-*/
-function repairOutsideCount(compiled, target) {
-	const full = diffPlan(compiled, readTarget(target, compiled.artifacts.map((artifact) => artifact.path)));
-	return full.drifted + full.missing + full.foreign;
-}
-/** One `fleet --json` entry — `undefined` counts (a failed repo never got an audit) fall back to zero. */
-function fleetEntry(name, counts, failed) {
-	return {
-		name,
-		drifted: counts?.drifted ?? 0,
-		missing: counts?.missing ?? 0,
-		foreign: counts?.foreign ?? 0,
-		failed
-	};
-}
-/** Reject a cancelled prompt (ctrl-c) with the shared `CANCELLED_MESSAGE` — exit 1, nothing written. */
-async function guarded(promise) {
-	try {
-		return await promise;
-	} catch (error) {
-		if (isTerminalError(error) && error.code === "CANCEL") {
-			reporter.line(CANCELLED_MESSAGE);
-			halt(1);
-		}
-		throw error;
-	}
-}
-/**
-* The shared write-confirmation gate every verb calls before it touches disk.
-* `--apply` writes without asking; `--json` (without `--apply`) is a pure
-* dry-run and NEVER prompts; `--yes` auto-answers yes; otherwise a real
-* confirm with `default: false` (EOF on stdin resolves to the default).
-*/
-async function resolveApply(terminal, message, values, json) {
-	if (values.apply) return true;
-	if (json) return false;
-	if (values.yes) return true;
-	return guarded(terminal.confirm({
-		message,
-		default: false
-	}));
-}
-/**
-* The SECOND, separate confirm for `--prune`-eligible deletions — never
-* bundled into `resolveApply`'s question. `--yes` only auto-answers this
-* when `--prune` was also passed (it never enables pruning by itself).
-*/
-async function resolvePrune(terminal, message, values, json) {
-	if (!values.prune) return false;
-	if (values.apply) return true;
-	if (json) return false;
-	if (values.yes) return true;
-	if (!sinkIsTTY) {
-		reporter.line(pruneSkipped());
-		return false;
-	}
-	return guarded(terminal.confirm({
-		message,
-		default: false
-	}));
-}
-/** A spinner for a long-running write step — `undefined` under `--json` or off a TTY sink (render.ts's `shouldSpin`). */
-function createSpinnerMaybe(message, json) {
-	return json || !shouldSpin(sinkIsTTY) ? void 0 : createSpinner({
-		message,
-		sink,
-		styler
-	});
-}
-/** Announce a successful write — the spinner's own success line, or a plain `reporter.status` without one (never under `--json`). */
-function announceApply(spinner, json, message) {
-	if (spinner) spinner.success(message);
-	else if (!json) reporter.status("success", message);
-}
-/** Announce a failed write and halt(1) — the spinner's own failure line (if any), then the shared `fail`. */
-function announceFailure(spinner, json, error) {
-	const message = describe(error);
-	if (spinner) spinner.failure(message);
-	fail(message, json);
-}
-/** Split a comma-separated token list, trimming and dropping empties — the parse `new`'s dependency prompt goes through. */
+/** Split a comma-separated token list, trimming and dropping empty entries. */
 function splitTokens(raw) {
 	return raw.split(",").map((token) => token.trim()).filter((token) => token.length > 0);
 }
-/** Normalize a Q1 token to a full `@orkestrel/<name>` — an already-prefixed token passes through unchanged. */
+/** Normalize an Orkestrel dependency token to its full package name. */
 function normalizeOrkestrelToken(token) {
 	return token.startsWith("@orkestrel/") ? token : `@orkestrel/${token}`;
 }
 /**
-* Best-effort vendored `@orkestrel` catalog names, resolved via `host`
-* (`hostRoot()`, or the active `--from` override) through the host manifest
-* — `undefined` when the catalog cannot be established (a missing/unreadable
-* manifest, no `.claude/agents/orkestrel.md` entry, or any other failure),
-* degrading Q1 to shape-only validation instead of blocking on it.
+* Parse and resolve a pull dependency selection against the target manifest.
+*
+* @param raw - The comma-separated full package names, or `undefined` for all.
+* @param declared - The target's declared Orkestrel dependencies.
+* @returns `undefined` for all dependencies, otherwise the exact selected records.
+* @throws `ScaffoldError('INVALID')` for empty, malformed, repeated, or undeclared names.
 */
-function resolveCatalogNames(host) {
-	try {
-		const full = locateHostSource(readHostManifest(host), ".claude/agents/orkestrel.md", host);
-		if (full === void 0 || !existsSync(full)) return void 0;
-		return catalogNames(readFileSync(full, "utf8"));
-	} catch {
-		return;
-	}
+function parsePullDependencies(raw, declared) {
+	if (raw === void 0) return void 0;
+	const names = raw.split(",").map((name) => name.trim());
+	if (names.length === 0 || names.some((name) => !DEPENDENCY_NAME_PATTERN.test(name)) || new Set(names).size !== names.length) throw new ScaffoldError("INVALID", "Pull dependencies must be unique, comma-separated @orkestrel/* package names");
+	const selected = declared.filter((dependency) => names.includes(dependency.name));
+	const found = new Set(selected.map((dependency) => dependency.name));
+	const missing = names.filter((name) => !found.has(name));
+	if (missing.length > 0) throw new ScaffoldError("INVALID", `Pull dependencies are not declared by the target: ${missing.join(", ")}`, { dependencies: missing });
+	return selected;
 }
-/** One Q1 token's issue against `catalog` (`undefined` = valid) — shape-only (`DEPENDENCY_NAME_PATTERN`) when `catalog` itself could not be resolved. */
-function orkestrelTokenIssue(normalized, catalog) {
-	if (catalog === void 0) return DEPENDENCY_NAME_PATTERN.test(normalized) ? void 0 : unknownOrkestrelToken(normalized, void 0);
-	if (catalog.includes(normalized)) return void 0;
-	return unknownOrkestrelToken(normalized, nearest(normalized, catalog));
+//#endregion
+//#region src/bin/validators.ts
+/** Narrow a positional command to the command-line interface's vocabulary. */
+function isVerb(value) {
+	return KNOWN_VERBS.some((verb) => verb === value);
 }
-/** Q1 (TTY only) — `@orkestrel` short-name deps, re-asking on any unresolved token until the input is clean or empty. */
-async function promptOrkestrelDeps(terminal, catalog) {
-	for (;;) {
-		const tokens = splitTokens(await guarded(terminal.input({
-			message: orkestrelDepsPrompt(),
-			default: ""
-		})));
-		if (tokens.length === 0) return [];
-		const normalized = tokens.map(normalizeOrkestrelToken);
-		const issue = normalized.map((token) => orkestrelTokenIssue(token, catalog)).find((message) => message !== void 0);
-		if (issue === void 0) return normalized;
-		reporter.line(issue);
+//#endregion
+//#region src/bin/CLI.ts
+/** Stateful command-line orchestration and its process boundary. */
+var CLI = class {
+	#sink = createServerSink();
+	#tty = process.stdout.isTTY === true;
+	#styler = createStyler({ enabled: process.env.NO_COLOR === void 0 && this.#tty });
+	#reporter = createReporter({
+		sink: this.#sink,
+		width: this.#sink.columns,
+		styler: this.#styler
+	});
+	#json = false;
+	/** Execute one command-line argument vector. */
+	async run(argv) {
+		this.#trust();
+		try {
+			await this.#dispatch(argv);
+		} catch (error) {
+			if (error instanceof CLIExitError) process.exitCode = error.code;
+			else if (this.#json) {
+				const code = isScaffoldError(error) ? error.code : "ERROR";
+				const message = isScaffoldError(error) ? error.message : describeError(error);
+				this.#write(errorEnvelopeOf(code, message));
+				process.exitCode = 1;
+			} else {
+				this.#reporter.status("error", describeError(error));
+				process.exitCode = 1;
+			}
+		}
 	}
-}
-/** `scaffold new` — scaffold a package into `./<name>` (or `--target`). */
-async function runNew(values, argument, json) {
-	const terminal = createTerminal();
-	let name;
-	if (argument !== void 0) name = argument;
-	else if (json) usageFail("a package name is required with --json", json);
-	else if (!sinkIsTTY) usageFail(missingInput("a package name", "new"), json);
-	else name = await guarded(terminal.input({
-		message: "Package name",
-		validate: { pattern: NAME_PATTERN.source }
-	}));
-	if (!NAME_PATTERN.test(name)) usageFail(invalidName(name, NAME_PATTERN.source), json);
-	let surfaceInput;
-	if (values.surfaces !== void 0) surfaceInput = values.surfaces.split(",");
-	else if (json) usageFail("--surfaces is required with --json", json);
-	else if (!sinkIsTTY) usageFail(missingInput("--surfaces", "new"), json);
-	else surfaceInput = await guarded(terminal.checkbox({
-		message: "Surfaces",
-		choices: surfaceChoices(),
-		min: 1
-	}));
-	const unrecognizedSurface = surfaceInput.filter((candidate) => !SURFACES.some((surface) => surface === candidate));
-	if (unrecognizedSurface.length > 0) usageFail(`Surface "${unrecognizedSurface.join("\", \"")}" is not recognized`, json);
-	const surfaces = SURFACES.filter((surface) => surfaceInput.includes(surface));
-	const destination = containOrFail(values.target ?? `./${name}`, json);
-	let depNames;
-	if (values.deps !== void 0) {
-		depNames = values.deps.split(",").filter((depName) => depName.length > 0);
-		const badDep = depNames.find((depName) => !DEPENDENCY_NAME_PATTERN.test(depName));
-		if (badDep !== void 0) usageFail(`Dependency name "${badDep}" must match ${DEPENDENCY_NAME_PATTERN.source}`, json);
-	} else if (json || !sinkIsTTY) depNames = [];
-	else {
-		const catalog = resolveCatalogNames(values.from?.[0] ?? hostRoot());
-		if (catalog === void 0) reporter.line(catalogUnresolvedNote());
-		depNames = await promptOrkestrelDeps(terminal, catalog);
+	/**
+	* Widen Node's default trusted-issuer set to include the OS certificate
+	* store, so `fetch` behind a corporate TLS-inspecting proxy behaves like npm
+	* (`cafile`) and browsers (OS trust store) instead of failing with
+	* `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` against Node's bundled CA list alone.
+	* Feature-detected (`tls.getCACertificates` / `tls.setDefaultCACertificates`
+	* ship on Node ≈22.16+/24.5+; this package's floor is `>=22.12.0`) and captured
+	* through `attempt` — any failure is a silent no-op, never a crash. This only ADDS
+	* trusted issuers; it never touches `rejectUnauthorized` or
+	* `NODE_TLS_REJECT_UNAUTHORIZED`, so certificate verification stays on.
+	*/
+	#trust() {
+		if (typeof tls.getCACertificates !== "function" || typeof tls.setDefaultCACertificates !== "function") return;
+		attempt(() => {
+			const merged = /* @__PURE__ */ new Set([...tls.getCACertificates("default"), ...tls.getCACertificates("system")]);
+			tls.setDefaultCACertificates([...merged]);
+		});
 	}
-	const sync = createSync();
-	let versions;
-	try {
-		versions = await sync.versions(depNames.map((depName) => dependency(depName, "*")));
-	} finally {
-		sync.destroy();
+	/** Write ONE machine-readable JSON value to stdout — the entire `--json` output contract. */
+	#write(value) {
+		process.stdout.write(`${JSON.stringify(value)}\n`);
 	}
-	const unresolved = versions.filter((version) => version.freshness !== "current" && version.freshness !== "behind" || version.latest === "").map((version) => version.name);
-	if (unresolved.length > 0) fail(unresolvedVersion(unresolved), json);
-	const deps = versions.map((version) => dependency(version.name, `^${version.latest}`));
-	const plan = compileOrFail(blueprint(name, {
-		surfaces,
-		dependencies: deps
-	}), json);
-	const summary = planToSummary(plan);
-	if (!json) {
-		reporter.section("Plan");
-		reporter.table(newPlanTable(summary));
-		reporter.line(newPlanPreview(name));
+	/** Report a general operation failure with exit 1 as prose or one JSON error envelope. */
+	#fail(message, json) {
+		if (json) this.#write(errorEnvelopeOf("ERROR", message));
+		else this.#reporter.status("error", message);
+		throw new CLIExitError(1);
 	}
-	if (!await resolveApply(terminal, applyConfirmMessage(summary.host + summary.template + summary.computed), values, json)) {
-		if (json) writeJson(newJson(summary, false));
-		else reporter.line(NEW_DRY_RUN_NOTE);
-		process.exitCode = 0;
-		return;
+	/**
+	* A general operation failure from a caught error — the real
+	* `ScaffoldError` code when available ('ERROR' last resort), prose (via
+	* `describe`, which still carries the bracketed code for a human reader) or
+	* the one JSON error envelope under `--json` (code and message kept
+	* SEPARATE — never double-encoding the code into the message text).
+	*/
+	#error(error, json) {
+		if (json) {
+			const code = isScaffoldError(error) ? error.code : "ERROR";
+			const message = isScaffoldError(error) ? error.message : describeError(error);
+			this.#write(errorEnvelopeOf(code, message));
+		} else this.#reporter.status("error", describeError(error));
+		throw new CLIExitError(1);
 	}
-	const spinner = createSpinnerMaybe("materializing", json);
-	spinner?.start();
-	const materializer = createMaterializer({ host: values.from?.[0] });
-	try {
-		const result = materializer.materialize(plan, destination);
-		const count = result.written.length + result.copied.length;
-		if (json) writeJson(newJson(summary, true));
-		else announceApply(spinner, json, newApplySuccess(count, name));
-	} catch (error) {
-		announceFailure(spinner, json, error);
-	} finally {
-		materializer.destroy();
+	/** A usage error (bad flag value, unknown verb — exit 2) — stderr prose, or the one JSON error envelope under `--json`. */
+	#usage(message, json) {
+		if (json) this.#write(errorEnvelopeOf("USAGE", message));
+		else process.stderr.write(`${message}\n`);
+		throw new CLIExitError(2);
 	}
-	process.exitCode = 0;
-}
-/** `scaffold pull` — refresh vendored dependency mirrors and report range drift. */
-async function runPull(values, json) {
-	const target = containOrFail(values.target ?? ".", json);
-	const sync = createSync({ strict: values.strict });
-	try {
-		const wanted = values.deps?.split(",");
-		let report;
+	/** Contain a destination and report any coded escape through the shared CLI error path. */
+	#contain(candidate, json) {
+		const contained = attempt(() => containDestination(process.cwd(), candidate));
+		if (contained.success) return contained.value;
+		this.#error(contained.error, json);
+	}
+	/** Compile a spec and report unresolved blocking questions through the shared CLI error path. */
+	#compile(spec, json) {
+		const compiler = createCompiler();
 		try {
-			const declared = manifestToDependencies(readManifest(target));
-			const deps = wanted ? declared.filter((dep) => wanted.includes(dep.name)) : declared;
-			if (wanted) {
-				const guides = await sync.guides(deps);
-				const versions = await sync.versions(deps);
-				const failed = [...guides, ...versions].filter((entry) => entry.freshness === "missing" || entry.freshness === "failed").length;
-				report = {
-					target,
-					guides,
-					versions,
-					clean: failed === 0 && guides.every((guide) => guide.freshness === "current") && versions.every((version) => version.freshness === "current"),
-					failed
-				};
-			} else report = await sync.pull(target);
-		} catch (error) {
-			failError(error, json);
-		}
-		if (!json) {
-			reporter.table(pullTable(report));
-			for (const line of pullCauseNotes(report)) reporter.line(line);
-			reporter.line(pullVerdict(report));
-		}
-		const toWrite = [...report.guides, ...report.versions].filter((entry) => entry.freshness !== "current").length;
-		const terminal = createTerminal();
-		const proceed = toWrite > 0 ? await resolveApply(terminal, applyConfirmMessage(toWrite), values, json) : false;
-		if (proceed) {
-			const spinner = createSpinnerMaybe("writing mirrors", json);
-			spinner?.start();
-			try {
-				const written = await sync.write(report, target);
-				if (json) writeJson(pullJson(report));
-				else announceApply(spinner, json, pullSuccess(written.length));
-			} catch (error) {
-				announceFailure(spinner, json, error);
+			const scaffolding = compiler.compile(spec);
+			if (!scaffolding.plan) {
+				const message = scaffolding.questions.map((question) => question.text).join("; ");
+				this.#fail(message, json);
 			}
-		} else if (json) writeJson(pullJson(report));
-		process.exitCode = report.clean ? 0 : proceed ? 0 : 1;
-	} finally {
-		sync.destroy();
+			return scaffolding.plan;
+		} finally {
+			compiler.destroy();
+		}
 	}
-}
-/** `scaffold audit` — whole-plan conformance report; offers a repair handoff on drift. */
-async function runAudit(values, json) {
-	const target = containOrFail(values.target ?? ".", json);
-	let spec;
-	try {
-		spec = deriveBlueprint(target);
-	} catch (error) {
-		failError(error, json);
+	/**
+	* Merge a `pruneTargets` scan into `audit` as `foreign` findings — pure
+	* object-spread composition in the BIN only (`src/core`'s `diffPlan` is never
+	* modified/reimplemented). Every unexpected path becomes one
+	* `'orchestration'`-group `foreign` finding (the `Group` every `PRUNE_DIRECTORIES`
+	* entry—`.claude/agents`, `.codex/agents`, `scripts`—belongs to); any scan hit makes the
+	* merged audit unclean, so an "unexpected file" is honestly counted as drift
+	* (exit 1) instead of the structurally-always-zero `diffPlan.foreign`.
+	*/
+	#scan(audit, target, host) {
+		const paths = pruneTargets(target, host);
+		if (paths.length === 0) return audit;
+		const findings = paths.map((path) => ({
+			path,
+			group: "orchestration",
+			drift: "foreign"
+		}));
+		return {
+			...audit,
+			clean: false,
+			foreign: audit.foreign + paths.length,
+			findings: [...audit.findings, ...findings]
+		};
 	}
-	const deps = [
-		...spec.dependencies,
-		...spec.peers,
-		...spec.extras
-	];
-	const groupsInput = values.groups?.split(",");
-	let groups;
-	if (groupsInput !== void 0) {
-		const unrecognized = groupsInput.filter((name) => !GROUPS.some((group) => group === name));
-		if (unrecognized.length > 0) usageFail(`Group "${unrecognized.join("\", \"")}" is not recognized`, json);
-		groups = GROUPS.filter((group) => groupsInput.includes(group));
+	/**
+	* Add unexpected-file findings when the vendored allowlist can be established.
+	* When fail-closed allowlist discovery raises a coded `TARGET` failure, retain
+	* the existing findings and mark the audit incomplete instead of crashing.
+	*/
+	#scanSafe(audit, target, host) {
+		const scanned = attempt(() => this.#scan(audit, target, host));
+		if (scanned.success) return {
+			audit: scanned.value,
+			skipped: false
+		};
+		if (isScaffoldError(scanned.error) && scanned.error.code === "TARGET") return {
+			audit: {
+				...audit,
+				clean: false,
+				complete: false,
+				questions: [...audit.questions, {
+					field: "host",
+					text: scanned.error.message,
+					blocking: true
+				}]
+			},
+			skipped: true
+		};
+		throw scanned.error;
 	}
-	const compiled = blueprintToPlan(spec, groups);
-	const from = values.from?.[0];
-	const host = from ?? hostRoot();
-	let hydrated;
-	try {
-		hydrated = hydrateBestEffort(compiled, host, from !== void 0);
-	} catch (error) {
-		failError(error, json);
+	/**
+	* `repair`'s own scope is host-only, but the caller compiles the FULL plan anyway — diff it too
+	* (cheap, local, no network) so a clean host verdict can point at drift OUTSIDE repair's reach.
+	* The count feeds the shared `scopeNote` renderer.
+	*/
+	#outside(compiled, target) {
+		const full = diffPlan(compiled, readTarget(target, compiled.artifacts.map((artifact) => artifact.path)));
+		return full.drifted + full.missing + full.foreign;
 	}
-	const plan = hydrated.plan;
-	const artifactPaths = plan.artifacts.map((artifact) => artifact.path);
-	const rawAudit = diffPlan(plan, readTarget(target, artifactPaths));
-	const scanned = hydrated.aware ? withForeignScanSafe(rawAudit, target, host) : {
-		audit: rawAudit,
-		skipped: false
-	};
-	const audit = scanned.audit;
-	let drifted = !audit.clean;
-	let live;
-	if (values.live) {
-		const sync = createSync();
+	/** Reject a cancelled prompt (ctrl-c) with the shared `CANCELLED_MESSAGE` — exit 1, nothing written. */
+	async #guard(promise) {
 		try {
-			const guides = await sync.guides(deps);
-			const versions = await sync.versions(deps);
-			const entries = [...guides, ...versions];
-			drifted ||= entries.some((entry) => entry.freshness !== "current");
-			const current = entries.filter((entry) => entry.freshness === "current").length;
-			const behind = entries.filter((entry) => entry.freshness === "behind").length;
-			live = {
-				current,
-				behind,
-				failed: entries.length - current - behind
-			};
-		} finally {
-			sync.destroy();
+			return await promise;
+		} catch (error) {
+			if (isTerminalError(error) && error.code === "CANCEL") {
+				this.#reporter.line(CANCELLED_MESSAGE);
+				throw new CLIExitError(1);
+			}
+			throw error;
 		}
 	}
-	if (json) {
-		writeJson(live === void 0 ? auditJson(audit) : {
-			...auditJson(audit),
-			live
-		});
-		process.exitCode = drifted ? 1 : 0;
-		return;
+	/**
+	* The shared write-confirmation gate every verb calls before it touches disk.
+	* `--apply` writes without asking; `--json` (without `--apply`) is a pure
+	* dry-run and NEVER prompts; `--yes` auto-answers yes; otherwise a real
+	* confirm with `default: false` (EOF on stdin resolves to the default).
+	*/
+	async #apply(terminal, message, values, json) {
+		if (values.apply) return true;
+		if (json) return false;
+		if (values.yes) return true;
+		return this.#guard(terminal.confirm({
+			message,
+			default: false
+		}));
 	}
-	if (scanned.skipped) reporter.line(scanSkipped());
-	reporter.line(comparisonLine(hydrated.aware));
-	reporter.table(auditTable(audit, plan));
-	reporter.line(auditVerdict(audit, plan));
-	if (live !== void 0) reporter.line(auditLiveNote(live.current, live.behind, live.failed));
-	if (!audit.clean) {
-		const origins = new Map(plan.artifacts.map((artifact) => [artifact.path, artifact.origin]));
-		const isOwned = (path) => origins.get(path) === "host" || origins.get(path) === "template";
-		const ownedCount = audit.findings.filter((finding) => finding.drift !== "aligned" && finding.drift !== "foreign" && isOwned(finding.path)).length;
-		const computedCount = audit.findings.filter((finding) => finding.drift !== "aligned" && finding.drift !== "foreign" && !isOwned(finding.path)).length;
-		const pruneRequested = values.prune;
-		const offerHandoff = sinkIsTTY && (ownedCount > 0 || audit.foreign > 0 && pruneRequested);
-		let handoffAccepted = false;
-		if (offerHandoff) {
-			const terminal = createTerminal();
-			const message = repairHandoff(ownedCount, audit.foreign, pruneRequested);
-			handoffAccepted = await guarded(terminal.confirm({
-				message,
-				default: false
-			}));
-			if (handoffAccepted) {
-				await runRepair(values, false);
-				const rawFinal = diffPlan(plan, readTarget(target, artifactPaths));
-				const finalScanned = hydrated.aware ? withForeignScanSafe(rawFinal, target, host) : {
-					audit: rawFinal,
-					skipped: false
-				};
-				process.exitCode = finalScanned.audit.clean ? 0 : 1;
-				return;
-			}
-		}
-		if (!handoffAccepted) {
-			if (audit.foreign > 0 && !pruneRequested) reporter.line(foreignHint());
-			if (computedCount > 0) reporter.line(generatedNote(computedCount));
+	/**
+	* The SECOND, separate confirm for `--prune`-eligible deletions — never
+	* bundled into `resolveApply`'s question. `--yes` only auto-answers this
+	* when `--prune` was also passed (it never enables pruning by itself).
+	*/
+	async #prune(terminal, message, values, json) {
+		if (!values.prune) return false;
+		if (values.apply) return true;
+		if (json) return false;
+		if (values.yes) return true;
+		if (!this.#tty) {
+			this.#reporter.line(PRUNE_SKIPPED);
+			return false;
 		}
+		return this.#guard(terminal.confirm({
+			message,
+			default: false
+		}));
 	}
-	process.exitCode = drifted ? 1 : 0;
-}
-/** `scaffold repair` — restore the shared template-owned set for ONE target. */
-async function runRepair(values, json) {
-	const target = containOrFail(values.target ?? ".", json);
-	let spec;
-	try {
-		spec = deriveBlueprint(target);
-	} catch (error) {
-		failError(error, json);
+	/** A spinner for a long-running write step, absent under `--json` or off a TTY sink. */
+	#spinner(message, json) {
+		return json || !this.#tty ? void 0 : createSpinner({
+			message,
+			sink: this.#sink,
+			styler: this.#styler
+		});
 	}
-	const compiled = compileOrFail(spec, json);
-	const scoped = {
-		...compiled,
-		artifacts: compiled.artifacts.filter((artifact) => artifact.origin === "host")
-	};
-	const from = values.from?.[0];
-	const host = from ?? hostRoot();
-	let plan;
-	try {
-		plan = hydrateBestEffort(scoped, host, from !== void 0).plan;
-	} catch (error) {
-		failError(error, json);
+	/** Announce a successful write — the spinner's own success line, or a plain `reporter.status` without one (never under `--json`). */
+	#succeed(spinner, json, message) {
+		if (spinner) spinner.success(message);
+		else if (!json) this.#reporter.status("success", message);
 	}
-	let audit;
-	try {
-		audit = diffPlan(plan, readTarget(target, plan.artifacts.map((artifact) => artifact.path)));
-	} catch (error) {
-		failError(error, json);
+	/** Announce a failed write and halt(1) — the spinner's own failure line (if any), then the shared `fail`. */
+	#reject(spinner, json, error) {
+		const message = describeError(error);
+		if (spinner) spinner.failure(message);
+		this.#fail(message, json);
 	}
-	if (!json) {
-		reporter.line(REPAIR_SCOPE);
-		reporter.section("Audit");
-		reporter.table(auditTable(audit, plan));
+	/**
+	* Best-effort vendored `@orkestrel` catalog names, resolved via `host`
+	* (`hostRoot()`, or the active `--from` override) through the host manifest
+	* — `undefined` when the catalog cannot be established (a missing/unreadable
+	* manifest, no `.claude/agents/orkestrel.md` entry, or any other failure),
+	* degrading the dependency prompt to shape-only validation instead of blocking on it.
+	*/
+	#names(host) {
+		const names = attempt(() => {
+			const full = locateHostSource(readHostManifest(host), ".claude/agents/orkestrel.md", host);
+			if (full === void 0 || !existsSync(full)) return void 0;
+			return catalogNames(readFileText(host, relative(host, full).replaceAll("\\", "/"), "TARGET", "host"));
+		});
+		return names.success ? names.value : void 0;
+	}
+	/** Prompt for `@orkestrel` short-name dependencies until every token resolves or input is empty. */
+	async #prompt(terminal, catalog) {
+		for (;;) {
+			const tokens = splitTokens(await this.#guard(terminal.input({
+				message: ORKESTREL_DEPS_PROMPT,
+				default: ""
+			})));
+			if (tokens.length === 0) return [];
+			const normalized = tokens.map(normalizeOrkestrelToken);
+			const issue = normalized.map((token) => orkestrelTokenIssue(token, catalog)).find((message) => message !== void 0);
+			if (issue === void 0) return normalized;
+			this.#reporter.line(issue);
+		}
 	}
-	const prunePaths = values.prune && existsSync(host) ? pruneTargets(target, host) : [];
-	if (audit.clean && prunePaths.length === 0) {
-		if (json) writeJson(repairJson(audit));
+	/** `scaffold new` — scaffold a package into `./<name>` (or `--target`). */
+	async #new(values, argument, json) {
+		const terminal = createTerminal();
+		let name;
+		if (argument !== void 0) name = argument;
+		else if (json) this.#usage("a package name is required with --json", json);
+		else if (!this.#tty) this.#usage(missingInput("a package name", "new"), json);
+		else name = await this.#guard(terminal.input({
+			message: "Package name",
+			validate: { pattern: NAME_PATTERN.source }
+		}));
+		if (!NAME_PATTERN.test(name)) this.#usage(invalidName(name, NAME_PATTERN.source), json);
+		let srcInput;
+		let appInput;
+		if (values.src !== void 0) srcInput = values.src.split(",").map((candidate) => candidate.trim());
+		else if (values.app !== void 0) srcInput = [];
+		else if (json || !this.#tty) this.#usage("at least one of --src or --app is required", json);
+		else srcInput = await this.#guard(terminal.checkbox({
+			message: "Published src environments",
+			choices: ENVIRONMENT_CHOICES,
+			min: 0
+		}));
+		if (values.app !== void 0) appInput = values.app.split(",").map((candidate) => candidate.trim());
+		else if (values.src !== void 0 || json || !this.#tty) appInput = [];
+		else appInput = await this.#guard(terminal.checkbox({
+			message: "Application environments",
+			choices: ENVIRONMENT_CHOICES,
+			min: 0
+		}));
+		const unrecognizedSrcEnvironment = srcInput.filter((candidate) => !ENVIRONMENTS.some((environment) => environment === candidate));
+		if (unrecognizedSrcEnvironment.length > 0) this.#usage(`Environment "${unrecognizedSrcEnvironment.join("\", \"")}" is not recognized`, json);
+		if (new Set(srcInput).size !== srcInput.length) this.#usage("Published src environments must not repeat", json);
+		const src = ENVIRONMENTS.filter((environment) => srcInput.includes(environment));
+		const unrecognizedAppEnvironment = appInput.filter((candidate) => !ENVIRONMENTS.some((environment) => environment === candidate));
+		if (unrecognizedAppEnvironment.length > 0) this.#usage(`Application environment "${unrecognizedAppEnvironment.join("\", \"")}" is not recognized`, json);
+		if (new Set(appInput).size !== appInput.length) this.#usage("Application environments must not repeat", json);
+		const app = ENVIRONMENTS.filter((environment) => appInput.includes(environment));
+		if (src.length === 0 && app.length === 0) this.#usage("at least one source or application environment is required", json);
+		const destination = this.#contain(values.target ?? `./${name}`, json);
+		if (!isVacant(destination)) this.#error(new ScaffoldError("TARGET", "new requires a vacant target", { target: destination }), json);
+		const explicitHost = values.from?.[0];
+		if (explicitHost !== void 0) {
+			if (!isRealDirectory(explicitHost)) this.#error(new ScaffoldError("TARGET", `Host root is not a physical directory at ${explicitHost}`, { host: explicitHost }), json);
+			readHostManifest(explicitHost);
+		}
+		let depNames;
+		if (values.deps !== void 0) {
+			depNames = values.deps.split(",").filter((depName) => depName.length > 0);
+			const badDep = depNames.find((depName) => !DEPENDENCY_NAME_PATTERN.test(depName));
+			if (badDep !== void 0) this.#usage(`Dependency name "${badDep}" must match ${DEPENDENCY_NAME_PATTERN.source}`, json);
+		} else if (json || !this.#tty) depNames = [];
 		else {
-			reporter.line(repairVerdict(audit));
-			const note = scopeNote(repairOutsideCount(compiled, target));
-			if (note !== void 0) reporter.line(note);
+			const catalogHost = values.from?.[0] ?? hostRoot();
+			const catalog = this.#names(catalogHost);
+			if (catalog === void 0) this.#reporter.line(CATALOG_UNRESOLVED_NOTE);
+			depNames = await this.#prompt(terminal, catalog);
+		}
+		const sync = createSync();
+		let versions;
+		try {
+			versions = await sync.versions(depNames.map((depName) => dependency(depName, "*")));
+		} finally {
+			sync.destroy();
+		}
+		const unresolved = versions.filter((version) => version.freshness !== "current" && version.freshness !== "behind" || version.latest === "").map((version) => version.name);
+		if (unresolved.length > 0) this.#fail(unresolvedVersion(unresolved), json);
+		const deps = versions.map((version) => dependency(version.name, `^${version.latest}`));
+		const plan = this.#compile(blueprint(name, {
+			src,
+			app,
+			dependencies: deps
+		}), json);
+		const summary = planToSummary(plan);
+		if (!json) {
+			this.#reporter.section("Plan");
+			this.#reporter.table(newPlanTable(summary));
+			this.#reporter.line(newPlanPreview(name));
+		}
+		if (!await this.#apply(terminal, applyConfirmMessage(summary.host + summary.template + summary.computed), values, json)) {
+			if (json) this.#write(summaryToNewResult(summary, false));
+			else this.#reporter.line(NEW_DRY_RUN_NOTE);
+			process.exitCode = 0;
+			return;
+		}
+		const spinner = this.#spinner("materializing", json);
+		spinner?.start();
+		const host = values.from?.[0];
+		const materializer = createMaterializer(host === void 0 ? void 0 : { host });
+		try {
+			const result = materializer.materialize(plan, destination);
+			const count = result.written.length + result.copied.length;
+			if (json) this.#write(summaryToNewResult(summary, true));
+			else this.#succeed(spinner, json, newApplySuccess(count, name));
+		} catch (error) {
+			this.#reject(spinner, json, error);
+		} finally {
+			materializer.destroy();
 		}
 		process.exitCode = 0;
-		return;
 	}
-	if (!json) reporter.line(repairVerdict(audit));
-	const terminal = createTerminal();
-	let proceed = true;
-	if (!audit.clean) proceed = await resolveApply(terminal, applyConfirmMessage(audit.drifted + audit.missing + audit.foreign), values, json);
-	if (!proceed) {
-		if (json) writeJson(repairJson(audit));
-		process.exitCode = 1;
-		return;
-	}
-	if (values.prune && !json) if (prunePaths.length === 0) reporter.line(PRUNE_EMPTY);
-	else for (const line of prunePreview(prunePaths)) reporter.line(line);
-	const doPrune = prunePaths.length > 0 && await resolvePrune(terminal, pruneConfirmMessage(prunePaths.length), values, json);
-	const spinner = createSpinnerMaybe("repairing", json);
-	spinner?.start();
-	const materializer = createMaterializer({ host: values.from?.[0] });
-	try {
-		const result = materializer.repair(plan, audit, target);
-		const removed = doPrune ? materializer.prune(target).removed : [];
-		if (json) writeJson(repairJson(audit, {
-			...result,
-			removed
-		}));
-		else announceApply(spinner, json, repairSuccess(result, removed));
-	} catch (error) {
-		announceFailure(spinner, json, error);
-	} finally {
-		materializer.destroy();
+	/** `scaffold pull` — refresh vendored dependency mirrors and report range drift. */
+	async #pull(values, json) {
+		const target = this.#contain(values.target ?? ".", json);
+		const sync = createSync(values.strict === void 0 ? void 0 : { strict: values.strict });
+		try {
+			let report;
+			try {
+				const declared = manifestToDependencies(readManifest(target));
+				const selected = parsePullDependencies(values.deps, declared);
+				report = await sync.pull(target, selected);
+			} catch (error) {
+				this.#error(error, json);
+			}
+			if (!json) {
+				this.#reporter.table(pullTable(report));
+				for (const line of pullCauseNotes(report)) this.#reporter.line(line);
+				this.#reporter.line(pullVerdict(report));
+			}
+			const toWrite = [...report.guides, ...report.versions].filter((entry) => entry.freshness !== "current").length;
+			const terminal = createTerminal();
+			const proceed = toWrite > 0 ? await this.#apply(terminal, applyConfirmMessage(toWrite), values, json) : false;
+			if (proceed) {
+				const spinner = this.#spinner("writing mirrors", json);
+				spinner?.start();
+				try {
+					const written = await sync.write(report, target);
+					if (json) this.#write(report);
+					else this.#succeed(spinner, json, pullSuccess(written.length));
+				} catch (error) {
+					this.#reject(spinner, json, error);
+				}
+			} else if (json) this.#write(report);
+			process.exitCode = report.clean ? 0 : proceed ? 0 : 1;
+		} finally {
+			sync.destroy();
+		}
 	}
-	process.exitCode = 0;
-}
-/** `scaffold fleet` — audit/repair every `@orkestrel` package beneath the current directory's immediate children. */
-async function runFleet(values, json) {
-	const root = containOrFail(".", json);
-	const packages = discoverPackages(root);
-	if (packages.length === 0) fail(`no @orkestrel packages under "${root}" — fleet scans the immediate children of the current directory; stand in the folder that contains your checkouts (cd ..), or use 'repair' to true up just this repo.`, json);
-	const from = values.from?.[0];
-	const host = from ?? hostRoot();
-	const explicit = from !== void 0;
-	const repos = [];
-	const failures = [];
-	let ciExcluded = false;
-	for (const directory of packages) {
-		const name = basename(directory);
+	/** `scaffold audit` — whole-plan conformance report; offers a repair handoff on drift. */
+	async #audit(values, json) {
+		const target = this.#contain(values.target ?? ".", json);
+		let spec;
+		try {
+			spec = deriveBlueprint(target);
+		} catch (error) {
+			this.#error(error, json);
+		}
+		const deps = [
+			...spec.dependencies,
+			...spec.peers,
+			...spec.extras
+		];
+		const groupsInput = values.groups?.split(",");
+		let groups;
+		if (groupsInput !== void 0) {
+			const unrecognized = groupsInput.filter((name) => !GROUPS.some((group) => group === name));
+			if (unrecognized.length > 0) this.#usage(`Group "${unrecognized.join("\", \"")}" is not recognized`, json);
+			groups = GROUPS.filter((group) => groupsInput.includes(group));
+		}
+		const compiled = blueprintToPlan(spec, groups);
+		const host = values.from?.[0] ?? hostRoot();
+		let plan;
 		try {
-			const compiler = createCompiler();
-			let scoped;
+			plan = hydratePlan(compiled, host);
+		} catch (error) {
+			this.#error(error, json);
+		}
+		const artifactPaths = plan.artifacts.map((artifact) => artifact.path);
+		const rawAudit = diffPlan(plan, readTarget(target, artifactPaths));
+		const scanned = this.#scanSafe(rawAudit, target, host);
+		const audit = scanned.audit;
+		let drifted = !audit.clean;
+		let live;
+		if (values.live) {
+			const sync = createSync();
 			try {
-				const spec = deriveBlueprint(directory);
-				const scaffolding = compiler.compile(spec);
-				if (!scaffolding.plan) throw new ScaffoldError("INVALID", scaffolding.questions.map((question) => question.text).join("; "));
-				scoped = {
-					...scaffolding.plan,
-					artifacts: scaffolding.plan.artifacts.filter((artifact) => artifact.origin === "host" && artifact.path !== ".github/workflows/ci.yml")
+				const guides = await sync.guides(deps);
+				const versions = await sync.versions(deps);
+				const entries = [...guides, ...versions];
+				drifted ||= entries.some((entry) => entry.freshness !== "current");
+				const current = entries.filter((entry) => entry.freshness === "current").length;
+				const behind = entries.filter((entry) => entry.freshness === "behind").length;
+				live = {
+					current,
+					behind,
+					failed: entries.length - current - behind
 				};
-				if (!ciExcluded && scaffolding.plan.artifacts.some((artifact) => artifact.path === ".github/workflows/ci.yml")) {
-					if (!json) reporter.line(fleetCiSkipped());
-					ciExcluded = true;
-				}
 			} finally {
-				compiler.destroy();
+				sync.destroy();
 			}
-			const hydrated = hydrateBestEffort(scoped, host, explicit);
-			const plan = hydrated.plan;
-			const rawAudit = diffPlan(plan, readTarget(directory, plan.artifacts.map((artifact) => artifact.path)));
-			const audit = hydrated.aware ? withForeignScan(rawAudit, directory, host) : rawAudit;
-			repos.push({
-				name,
-				directory,
-				plan,
-				audit,
-				aware: hydrated.aware
-			});
-		} catch (error) {
-			failures.push({
-				name,
-				message: describe(error)
+		}
+		if (json) {
+			this.#write(live === void 0 ? audit : {
+				...audit,
+				live
 			});
+			process.exitCode = drifted ? 1 : 0;
+			return;
 		}
-	}
-	if (!json) {
-		for (const repo of repos) reporter.line(fleetRepoLine(repo.name, repo.audit.clean ? { kind: "clean" } : {
-			kind: "drifted",
-			drifted: repo.audit.drifted,
-			missing: repo.audit.missing,
-			foreign: repo.audit.foreign
-		}));
-		for (const failure of failures) reporter.line(fleetRepoLine(failure.name, {
-			kind: "failed",
-			message: failure.message
-		}));
-	}
-	const dirty = repos.filter((repo) => !repo.audit.clean);
-	if (dirty.length === 0) {
-		if (json) writeJson(fleetJson([...repos.map((repo) => fleetEntry(repo.name, repo.audit, false)), ...failures.map((failure) => fleetEntry(failure.name, void 0, true))]));
-		else reporter.line(fleetTotals(0, failures.length));
-		process.exitCode = failures.length > 0 ? 1 : 0;
-		return;
-	}
-	const fileCount = dirty.reduce((total, repo) => total + repo.audit.drifted + repo.audit.missing + repo.audit.foreign, 0);
-	const terminal = createTerminal();
-	const proceed = await resolveApply(terminal, applyConfirmMessage(fileCount, dirty.length), values, json);
-	const prunePaths = proceed && values.prune && existsSync(host) ? dirty.flatMap((repo) => pruneTargets(repo.directory, host).map((path) => `${repo.name}/${path}`)) : [];
-	if (proceed && values.prune && !json) if (prunePaths.length === 0) reporter.line(PRUNE_EMPTY);
-	else for (const line of prunePreview(prunePaths)) reporter.line(line);
-	const doPrune = proceed && prunePaths.length > 0 && await resolvePrune(terminal, pruneConfirmMessage(prunePaths.length), values, json);
-	if (!proceed) {
-		if (json) writeJson(fleetJson([...repos.map((repo) => fleetEntry(repo.name, repo.audit, false)), ...failures.map((failure) => fleetEntry(failure.name, void 0, true))]));
-		else reporter.line(fleetTotals(dirty.length, failures.length));
-		process.exitCode = 1;
-		return;
-	}
-	const materializer = createMaterializer({ host });
-	let drifted = 0;
-	let failedCount = failures.length;
-	const entries = repos.filter((repo) => repo.audit.clean).map((repo) => fleetEntry(repo.name, repo.audit, false));
-	try {
-		for (const repo of dirty) try {
-			materializer.repair(repo.plan, repo.audit, repo.directory);
-			if (doPrune) materializer.prune(repo.directory);
-			const paths = repo.plan.artifacts.map((artifact) => artifact.path);
-			const rawFinal = diffPlan(repo.plan, readTarget(repo.directory, paths));
-			const finalAudit = repo.aware ? withForeignScan(rawFinal, repo.directory, host) : rawFinal;
-			if (!finalAudit.clean) drifted += 1;
-			entries.push(fleetEntry(repo.name, finalAudit, false));
-			if (!json) reporter.line(fleetRepoLine(repo.name, {
-				kind: "repaired",
-				remaining: finalAudit.drifted + finalAudit.missing + finalAudit.foreign
-			}));
-		} catch (error) {
-			failedCount += 1;
-			entries.push(fleetEntry(repo.name, void 0, true));
-			if (!json) reporter.line(fleetRepoLine(repo.name, {
-				kind: "failed",
-				message: describe(error)
-			}));
+		if (scanned.skipped) this.#reporter.line(SCAN_SKIPPED);
+		this.#reporter.line(comparisonLine(true));
+		this.#reporter.table(auditTable(audit, plan));
+		this.#reporter.line(auditVerdict(audit, plan));
+		if (live !== void 0) this.#reporter.line(auditLiveNote(live.current, live.behind, live.failed));
+		if (!audit.clean) {
+			const split = partitionFindings(audit.findings, plan);
+			const ownedCount = split.owned.drifted + split.owned.missing;
+			const computedCount = split.generated.drifted + split.generated.missing;
+			const pruneRequested = values.prune === true;
+			const offerHandoff = this.#tty && (ownedCount > 0 || audit.foreign > 0 && pruneRequested);
+			let handoffAccepted = false;
+			if (offerHandoff) {
+				const terminal = createTerminal();
+				const message = repairHandoff(ownedCount, audit.foreign, pruneRequested);
+				handoffAccepted = await this.#guard(terminal.confirm({
+					message,
+					default: false
+				}));
+				if (handoffAccepted) {
+					await this.#repair(values, false);
+					const rawFinal = diffPlan(plan, readTarget(target, artifactPaths));
+					const finalScanned = this.#scanSafe(rawFinal, target, host);
+					process.exitCode = finalScanned.audit.clean ? 0 : 1;
+					return;
+				}
+			}
+			if (!handoffAccepted) {
+				if (audit.foreign > 0 && !pruneRequested) this.#reporter.line(FOREIGN_HINT);
+				if (computedCount > 0) this.#reporter.line(generatedNote(computedCount));
+			}
 		}
-	} finally {
-		materializer.destroy();
+		process.exitCode = drifted ? 1 : 0;
 	}
-	if (json) writeJson(fleetJson([...entries, ...failures.map((failure) => fleetEntry(failure.name, void 0, true))]));
-	else reporter.line(fleetTotals(drifted, failedCount));
-	process.exitCode = drifted > 0 || failedCount > 0 ? 1 : 0;
-}
-/** `scaffold catalog` — regenerate the fleet package catalog table embedded in `.claude/agents/orkestrel.md`. */
-async function runCatalog(values, json) {
-	const target = containOrFail(values.target ?? ".", json);
-	const explicitRoots = values.from;
-	let entries;
-	let published = 0;
-	let localOnly = 0;
-	const notes = /* @__PURE__ */ new Map();
-	if (values.offline) {
-		const roots = explicitRoots ?? [process.cwd()];
+	/** `scaffold repair` — restore the shared host-owned set for one target. */
+	async #repair(values, json) {
+		const target = this.#contain(values.target ?? ".", json);
+		let spec;
 		try {
-			entries = catalogPackages(roots);
+			spec = deriveBlueprint(target);
 		} catch (error) {
-			failError(error, json);
+			this.#error(error, json);
 		}
-	} else {
-		const sync = createSync({ on: { package: (name, note) => {
-			if (note !== "") notes.set(name, note);
-		} } });
-		let registryEntries;
+		const compiled = this.#compile(spec, json);
+		const scoped = {
+			...compiled,
+			artifacts: compiled.artifacts.filter((artifact) => artifact.origin === "host")
+		};
+		const host = values.from?.[0] ?? hostRoot();
+		let plan;
 		try {
-			registryEntries = await sync.catalog();
+			plan = hydratePlan(scoped, host);
 		} catch (error) {
-			failError(error, json);
-		} finally {
-			sync.destroy();
+			this.#error(error, json);
 		}
-		published = registryEntries.length;
-		let localEntries = [];
-		if (explicitRoots !== void 0) try {
-			localEntries = catalogPackages(explicitRoots);
+		let audit;
+		try {
+			audit = diffPlan(plan, readTarget(target, plan.artifacts.map((artifact) => artifact.path)));
 		} catch (error) {
-			failError(error, json);
+			this.#error(error, json);
 		}
-		const merged = /* @__PURE__ */ new Map();
-		for (const entry of registryEntries) merged.set(entry.name, entry);
-		for (const local of localEntries) {
-			const existing = merged.get(local.name);
-			if (existing === void 0) {
-				merged.set(local.name, local);
-				localOnly += 1;
-			} else if (local.description.length > 0) merged.set(local.name, {
-				...existing,
-				description: local.description
-			});
+		if (!json) {
+			this.#reporter.line(REPAIR_SCOPE);
+			this.#reporter.section("Audit");
+			this.#reporter.table(auditTable(audit, plan));
+		}
+		const prunePaths = values.prune ? pruneTargets(target, host) : [];
+		const pruneSnapshot = readTarget(target, prunePaths);
+		if (audit.clean && prunePaths.length === 0) {
+			if (json) this.#write(audit);
+			else {
+				this.#reporter.line(repairVerdict(audit));
+				const note = scopeNote(this.#outside(compiled, target));
+				if (note !== void 0) this.#reporter.line(note);
+			}
+			process.exitCode = 0;
+			return;
+		}
+		if (!json) this.#reporter.line(repairVerdict(audit));
+		const terminal = createTerminal();
+		let proceed = true;
+		if (!audit.clean) proceed = await this.#apply(terminal, applyConfirmMessage(audit.drifted + audit.missing + audit.foreign), values, json);
+		if (!proceed) {
+			if (json) this.#write(audit);
+			process.exitCode = 1;
+			return;
+		}
+		if (values.prune && !json) if (prunePaths.length === 0) this.#reporter.line(PRUNE_EMPTY);
+		else for (const line of prunePreview(prunePaths)) this.#reporter.line(line);
+		const doPrune = prunePaths.length > 0 && await this.#prune(terminal, pruneConfirmMessage(prunePaths.length), values, json);
+		const spinner = this.#spinner("repairing", json);
+		spinner?.start();
+		const materializer = createMaterializer({ host });
+		try {
+			const result = materializer.repair(plan, audit, target);
+			const removed = doPrune ? materializer.prune(target, pruneSnapshot).removed : [];
+			if (json) this.#write(auditToRepairResult(audit, {
+				...result,
+				removed
+			}));
+			else this.#succeed(spinner, json, repairSuccess(result, removed));
+		} catch (error) {
+			this.#reject(spinner, json, error);
+		} finally {
+			materializer.destroy();
 		}
-		entries = [...merged.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
-	}
-	const block = catalogToBlock(entries);
-	const agentPath = containOrFail(join(target, ".claude", "agents", "orkestrel.md"), json);
-	let current;
-	try {
-		current = readFileSync(agentPath, "utf8");
-	} catch (error) {
-		failError(new ScaffoldError("TARGET", `Failed to read ${agentPath}`, {
-			path: agentPath,
-			error
-		}), json);
-	}
-	const startMarker = "<!-- catalog:start -->";
-	const endMarker = "<!-- catalog:end -->";
-	const startIndex = current.indexOf(startMarker);
-	const endIndex = current.indexOf(endMarker);
-	if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) failError(new ScaffoldError("TARGET", `Markers "${startMarker}" / "${endMarker}" not found in ${agentPath}`, { path: agentPath }), json);
-	const updated = `${current.slice(0, startIndex + 22)}\n\n${block}\n${current.slice(endIndex)}`;
-	const oldRows = catalogNames(current.slice(startIndex + 22, endIndex)).length;
-	const shrink = entries.length < oldRows ? oldRows - entries.length : void 0;
-	if (updated === current) {
-		if (json) writeJson(catalogJson(entries, false));
-		else reporter.line(catalogVerdict(true));
 		process.exitCode = 0;
-		return;
 	}
-	if (!json) {
-		reporter.table(catalogTable(entries));
-		const warning = catalogShrinkWarning(oldRows, entries.length);
-		if (warning !== void 0) reporter.line(warning);
+	/** `scaffold fleet` — audit/repair every `@orkestrel` package beneath the current directory's immediate children. */
+	async #fleet(values, json) {
+		const root = this.#contain(".", json);
+		const packages = discoverPackages(root);
+		if (packages.length === 0) this.#fail(`no @orkestrel packages under "${root}" — fleet scans the immediate children of the current directory; stand in the folder that contains your checkouts (cd ..), or use 'repair' to true up just this repo.`, json);
+		const host = values.from?.[0] ?? hostRoot();
+		const repos = [];
+		const failures = [];
+		for (const directory of packages) {
+			const name = basename(directory);
+			try {
+				const compiler = createCompiler();
+				let scoped;
+				try {
+					const spec = deriveBlueprint(directory);
+					const scaffolding = compiler.compile(spec);
+					if (!scaffolding.plan) throw new ScaffoldError("INVALID", scaffolding.questions.map((question) => question.text).join("; "));
+					scoped = {
+						...scaffolding.plan,
+						artifacts: scaffolding.plan.artifacts.filter((artifact) => artifact.origin === "host")
+					};
+				} finally {
+					compiler.destroy();
+				}
+				const plan = hydratePlan(scoped, host);
+				const rawAudit = diffPlan(plan, readTarget(directory, plan.artifacts.map((artifact) => artifact.path)));
+				const audit = this.#scan(rawAudit, directory, host);
+				repos.push({
+					name,
+					directory,
+					plan,
+					audit
+				});
+			} catch (error) {
+				failures.push({
+					name,
+					message: describeError(error)
+				});
+			}
+		}
+		if (!json) {
+			for (const repo of repos) this.#reporter.line(fleetRepoLine(repo.name, repo.audit.clean ? { state: "clean" } : {
+				state: "drifted",
+				drifted: repo.audit.drifted,
+				missing: repo.audit.missing,
+				foreign: repo.audit.foreign
+			}));
+			for (const failure of failures) this.#reporter.line(fleetRepoLine(failure.name, {
+				state: "failed",
+				message: failure.message
+			}));
+		}
+		const dirty = repos.filter((repo) => !repo.audit.clean);
+		if (dirty.length === 0) {
+			if (json) this.#write([...repos.map((repo) => fleetEntryOf(repo.name, repo.audit, false)), ...failures.map((failure) => fleetEntryOf(failure.name, void 0, true))]);
+			else this.#reporter.line(fleetTotals(0, failures.length));
+			process.exitCode = failures.length > 0 ? 1 : 0;
+			return;
+		}
+		const fileCount = dirty.reduce((total, repo) => total + repo.audit.drifted + repo.audit.missing + repo.audit.foreign, 0);
+		const terminal = createTerminal();
+		const proceed = await this.#apply(terminal, applyConfirmMessage(fileCount, dirty.length), values, json);
+		const pruneSets = proceed && values.prune ? new Map(dirty.map((repo) => {
+			const paths = pruneTargets(repo.directory, host);
+			return [repo.name, readTarget(repo.directory, paths)];
+		})) : /* @__PURE__ */ new Map();
+		const prunePaths = dirty.flatMap((repo) => Object.keys(pruneSets.get(repo.name) ?? {}).map((path) => `${repo.name}/${path}`));
+		if (proceed && values.prune && !json) if (prunePaths.length === 0) this.#reporter.line(PRUNE_EMPTY);
+		else for (const line of prunePreview(prunePaths)) this.#reporter.line(line);
+		const doPrune = proceed && prunePaths.length > 0 && await this.#prune(terminal, pruneConfirmMessage(prunePaths.length), values, json);
+		if (!proceed) {
+			if (json) this.#write([...repos.map((repo) => fleetEntryOf(repo.name, repo.audit, false)), ...failures.map((failure) => fleetEntryOf(failure.name, void 0, true))]);
+			else this.#reporter.line(fleetTotals(dirty.length, failures.length));
+			process.exitCode = 1;
+			return;
+		}
+		const materializer = createMaterializer({ host });
+		let drifted = 0;
+		let failedCount = failures.length;
+		const entries = repos.filter((repo) => repo.audit.clean).map((repo) => fleetEntryOf(repo.name, repo.audit, false));
+		try {
+			for (const repo of dirty) try {
+				materializer.repair(repo.plan, repo.audit, repo.directory);
+				if (doPrune) materializer.prune(repo.directory, pruneSets.get(repo.name) ?? {});
+				const paths = repo.plan.artifacts.map((artifact) => artifact.path);
+				const rawFinal = diffPlan(repo.plan, readTarget(repo.directory, paths));
+				const finalAudit = this.#scan(rawFinal, repo.directory, host);
+				if (!finalAudit.clean) drifted += 1;
+				entries.push(fleetEntryOf(repo.name, finalAudit, false));
+				if (!json) this.#reporter.line(fleetRepoLine(repo.name, {
+					state: "repaired",
+					remaining: finalAudit.drifted + finalAudit.missing + finalAudit.foreign
+				}));
+			} catch (error) {
+				failedCount += 1;
+				entries.push(fleetEntryOf(repo.name, void 0, true));
+				if (!json) this.#reporter.line(fleetRepoLine(repo.name, {
+					state: "failed",
+					message: describeError(error)
+				}));
+			}
+		} finally {
+			materializer.destroy();
+		}
+		if (json) this.#write([...entries, ...failures.map((failure) => fleetEntryOf(failure.name, void 0, true))]);
+		else this.#reporter.line(fleetTotals(drifted, failedCount));
+		process.exitCode = drifted > 0 || failedCount > 0 ? 1 : 0;
+	}
+	/** `scaffold catalog` — regenerate the fleet package catalog table embedded in `.claude/agents/orkestrel.md`. */
+	async #catalog(values, json) {
+		const target = this.#contain(values.target ?? ".", json);
+		const explicitRoots = values.from;
+		let entries;
+		let published = 0;
+		let localOnly = 0;
+		const notes = /* @__PURE__ */ new Map();
 		if (values.offline) {
-			const missingDescription = entries.filter((entry) => entry.description.length === 0).map((entry) => entry.name);
-			if (missingDescription.length > 0) reporter.line(`${missingDescription.length} without guide description: ${missingDescription.join(", ")}`);
+			const roots = explicitRoots ?? [process.cwd()];
+			try {
+				entries = catalogPackages(roots);
+			} catch (error) {
+				this.#error(error, json);
+			}
 		} else {
-			reporter.line(catalogCounts(published, localOnly));
-			for (const [name, note] of notes) reporter.line(`  ${name}: ${note}`);
+			const sync = createSync();
+			sync.emitter.on("package", (name, note) => {
+				if (note !== "") notes.set(name, note);
+			});
+			let registryEntries;
+			try {
+				registryEntries = await sync.catalog();
+			} catch (error) {
+				this.#error(error, json);
+			} finally {
+				sync.destroy();
+			}
+			published = registryEntries.length;
+			let localEntries = [];
+			if (explicitRoots !== void 0) try {
+				localEntries = catalogPackages(explicitRoots);
+			} catch (error) {
+				this.#error(error, json);
+			}
+			const merged = /* @__PURE__ */ new Map();
+			for (const entry of registryEntries) merged.set(entry.name, entry);
+			for (const local of localEntries) {
+				const existing = merged.get(local.name);
+				if (existing === void 0) {
+					merged.set(local.name, local);
+					localOnly += 1;
+				} else if (local.description.length > 0) merged.set(local.name, {
+					...existing,
+					description: local.description
+				});
+			}
+			entries = [...merged.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 		}
-	}
-	if (!await resolveApply(createTerminal(), applyConfirmMessage(1), values, json)) {
-		if (json) writeJson(catalogJson(entries, true, shrink));
-		else reporter.line(catalogVerdict(false));
-		process.exitCode = 1;
-		return;
-	}
-	try {
-		writeFileSync(agentPath, updated, "utf8");
-	} catch (error) {
-		failError(new ScaffoldError("TARGET", `Failed to write ${agentPath}`, {
+		const block = catalogToBlock(entries);
+		const agentPath = this.#contain(join(target, CATALOG_AGENT_PATH), json);
+		let current;
+		let baseline;
+		try {
+			current = readFileText(target, CATALOG_AGENT_PATH, "TARGET", "target");
+			baseline = digestText(current);
+		} catch (error) {
+			this.#error(new ScaffoldError("TARGET", `Failed to read ${agentPath}`, {
+				path: agentPath,
+				error
+			}), json);
+		}
+		const startIndex = current.indexOf(CATALOG_START_MARKER);
+		const endIndex = current.indexOf(CATALOG_END_MARKER);
+		const startParts = current.split(CATALOG_START_MARKER);
+		const endParts = current.split(CATALOG_END_MARKER);
+		if (startIndex === -1 || endIndex === -1 || endIndex < startIndex || startParts.length !== 2 || endParts.length !== 2) this.#error(new ScaffoldError("TARGET", `Expected exactly one ordered "${CATALOG_START_MARKER}" / "${CATALOG_END_MARKER}" pair in ${agentPath}`, { path: agentPath }), json);
+		const updated = `${current.slice(0, startIndex + CATALOG_START_MARKER.length)}\n\n${block}\n${current.slice(endIndex)}`;
+		const oldRows = catalogNames(current.slice(startIndex + CATALOG_START_MARKER.length, endIndex)).length;
+		const shrink = entries.length < oldRows ? oldRows - entries.length : void 0;
+		if (updated === current) {
+			if (json) this.#write(catalogResultOf(entries, false));
+			else this.#reporter.line(catalogVerdict(true));
+			process.exitCode = 0;
+			return;
+		}
+		if (!json) {
+			this.#reporter.table(catalogTable(entries));
+			const warning = catalogShrinkWarning(oldRows, entries.length);
+			if (warning !== void 0) this.#reporter.line(warning);
+			if (values.offline) {
+				const missingDescription = entries.filter((entry) => entry.description.length === 0).map((entry) => entry.name);
+				if (missingDescription.length > 0) this.#reporter.line(`${missingDescription.length} without guide description: ${missingDescription.join(", ")}`);
+			} else {
+				this.#reporter.line(catalogCounts(published, localOnly));
+				for (const [name, note] of notes) this.#reporter.line(`  ${name}: ${note}`);
+			}
+		}
+		const terminal = createTerminal();
+		if (!await this.#apply(terminal, applyConfirmMessage(1), values, json)) {
+			if (json) this.#write(catalogResultOf(entries, true, shrink));
+			else this.#reporter.line(catalogVerdict(false));
+			process.exitCode = 1;
+			return;
+		}
+		if (Buffer.byteLength(updated, "utf8") > MAX_ARTIFACT_BYTES) this.#error(new ScaffoldError("WRITE", `Catalog exceeds the artifact limit at ${agentPath}`, {
 			path: agentPath,
-			error
+			limit: MAX_ARTIFACT_BYTES
 		}), json);
-	}
-	if (json) writeJson(catalogJson(entries, true, shrink));
-	else reporter.status("success", catalogApplySuccess(agentPath));
-	process.exitCode = 0;
-}
-/**
-* The whole command dispatch — a single top-level driver (no nested function
-* declarations, AGENTS §4). Every verb sets `process.exitCode` (never
-* `process.exit`, H4) and returns, or `halt()`s through a `finally` that
-* tears its entities down first; the caller at the bottom of this file
-* catches exactly one sentinel (`CliExit`) and stops.
-*/
-async function main() {
-	let parsed;
-	try {
-		parsed = parseArguments();
-	} catch (error) {
-		process.stderr.write(`${error instanceof Error ? error.message : INVALID_ARGUMENTS_MESSAGE}\n`);
-		process.exitCode = 2;
-		return;
-	}
-	const { values, positionals } = parsed;
-	const [command, argument] = positionals;
-	const json = values.json === true;
-	sessionJson = json;
-	if (command === void 0) {
-		process.stdout.write(`${values.help ? fullHelp() : shortUsage()}\n`);
-		process.exitCode = 0;
-		return;
-	}
-	if (!isVerb(command)) usageFail(didYouMean(command), json);
-	if (values.help) {
-		process.stdout.write(`${verbHelp(command)}\n`);
+		const transaction = WriteTransaction.create(target, [CATALOG_AGENT_PATH], [{
+			path: CATALOG_AGENT_PATH,
+			shape: "file",
+			digest: baseline
+		}]);
+		const staged = attempt(() => {
+			validateWriteDirectories(transaction);
+			mkdirSync(dirname(resolvePhysicalPath(transaction.stage, CATALOG_AGENT_PATH, "WRITE", "staging")), { recursive: true });
+			validateWriteDirectories(transaction);
+			const contained = resolvePhysicalPath(transaction.stage, CATALOG_AGENT_PATH, "WRITE", "staging");
+			writeFileSync(contained, updated, {
+				encoding: "utf8",
+				flag: "wx"
+			});
+			if (digestFile(contained) !== digestText(updated)) throw new ScaffoldError("WRITE", `Staged catalog changed at ${agentPath}`, { path: agentPath });
+			validateWriteDirectories(transaction);
+		});
+		if (!staged.success) {
+			const cleanup = attempt(() => discardWriteTransaction(transaction));
+			this.#error(new ScaffoldError("WRITE", `Failed to stage ${agentPath}`, {
+				path: agentPath,
+				error: staged.error,
+				cleanup: cleanup.success ? void 0 : cleanup.error
+			}), json);
+		}
+		const committed = attempt(() => commitWriteTransaction(transaction, [CATALOG_AGENT_PATH]));
+		if (!committed.success) this.#error(committed.error, json);
+		if (json) this.#write(catalogResultOf(entries, true, shrink));
+		else this.#reporter.status("success", catalogApplySuccess(agentPath));
 		process.exitCode = 0;
-		return;
 	}
-	if (command === "new") return runNew(values, argument, json);
-	if (command === "pull") return runPull(values, json);
-	if (command === "audit") return runAudit(values, json);
-	if (command === "repair") return runRepair(values, json);
-	if (command === "fleet") return runFleet(values, json);
-	return runCatalog(values, json);
-}
-trustSystemCertificates();
-try {
-	await main();
-} catch (error) {
-	if (error instanceof CliExit) process.exitCode = error.code;
-	else if (sessionJson) {
-		writeJson(errorEnvelope(isScaffoldError(error) ? error.code : "ERROR", isScaffoldError(error) ? error.message : describe(error)));
-		process.exitCode = 1;
-	} else {
-		reporter.status("error", describe(error));
-		process.exitCode = 1;
+	/**
+	* The whole command dispatch — a single top-level driver (no nested function
+	* declarations, AGENTS §4). Every verb sets `process.exitCode` (never
+	* `process.exit`) and returns, or `halt()`s through a `finally` that
+	* tears its entities down first; the caller at the bottom of this file
+	* catches exactly one sentinel (`CliExit`) and stops.
+	*/
+	async #dispatch(argv) {
+		let parsed;
+		try {
+			parsed = parseArguments(argv);
+		} catch (error) {
+			process.stderr.write(`${error instanceof Error ? error.message : INVALID_ARGUMENTS_MESSAGE}\n`);
+			process.exitCode = 2;
+			return;
+		}
+		const { values, positionals } = parsed;
+		const [command, argument] = positionals;
+		const json = values.json === true;
+		this.#json = json;
+		if (command === void 0) {
+			process.stdout.write(`${values.help ? fullHelp() : shortUsage()}\n`);
+			process.exitCode = 0;
+			return;
+		}
+		if (!isVerb(command)) this.#usage(didYouMean(command), json);
+		if (command !== "catalog" && values.from !== void 0 && values.from.length > 1) this.#usage(`--from may be provided only once for '${command}'`, json);
+		if (values.help) {
+			process.stdout.write(`${verbHelp(command)}\n`);
+			process.exitCode = 0;
+			return;
+		}
+		if (command === "new") return this.#new(values, argument, json);
+		if (command === "pull") return this.#pull(values, json);
+		if (command === "audit") return this.#audit(values, json);
+		if (command === "repair") return this.#repair(values, json);
+		if (command === "fleet") return this.#fleet(values, json);
+		return this.#catalog(values, json);
 	}
-}
+};
+//#endregion
+//#region src/bin/scaffold.ts
+await new CLI().run(process.argv.slice(2));
 //#endregion
 
 //# sourceMappingURL=scaffold.js.map