buddy-agent-harness 1.0.1 → 1.2.0

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { declaredDependencies, listReferences, listReferences as listReferences$1, packageDir, parseReferenceName, referenceLayers as referenceLayers$1, referenceNames, repoReferencesDir, resolveReference, searchReferences, skillsDirectories } from "cyber-agentkit";
 import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { cli, command, t } from "clibuilder";
-import { CliError, document, exitCodes, isCliError, printAnswer, result } from "clibuilder/axi";
+import { CliError, document, empty, exitCodes, homeHeader, isCliError, printAnswer, ref, result } from "clibuilder/axi";
 import { homedir, platform } from "node:os";
 import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
 import { parse, stringify } from "smol-toml";
@@ -10,15 +10,276 @@ import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 import { parseTOML } from "toml-eslint-parser";
 import { findNodeAtLocation, parseTree } from "jsonc-parser";
+//#region src/harness-registry/harness-registry.ts
+/**
+* Throws on a harness `skillsDirectories` does not confirm: treating it as native would silently
+* drop a projection it may need.
+*/
+function skillsProjection(harness, scope, directories = skillsDirectories(harness)?.[scope]) {
+	const listed = directories ?? [];
+	const [first] = listed;
+	if (first === void 0) throw new Error(`cyber-agentkit records no ${scope} skills directories for ${harness}.`);
+	return listed.includes(".agents/skills") ? {} : { skillsDirectory: first };
+}
+/**
+* The user-scope counterpart of the root `AGENTS.md`, relative to the home directory. No harness
+* reads it natively; each loads it only through a user-scope `instructionBridge` (E-CC-18, E-CODEX-05,
+* E-GEM-03, E-COPILOT-04, E-CUR-08).
+*/
+const globalInstructions = ".agents/AGENTS.md";
+/**
+* Skills directories come from `cyber-agentkit`, except for the harnesses it does not know
+* (`devin-desktop`, `windsurf`); see `.research/agentic-configuration-standards/` for the rest.
+*/
+const harnessRegistry = [
+	{
+		name: "claude-code",
+		project: {
+			detect: ".claude",
+			...skillsProjection("claude-code", "project"),
+			shadowedBy: [
+				"CLAUDE.md",
+				".claude/CLAUDE.md",
+				"CLAUDE.local.md"
+			],
+			mcpConfig: {
+				path: ".mcp.json",
+				key: "mcpServers",
+				format: "json",
+				dialect: "claude-code"
+			},
+			nonstandard: [
+				{
+					path: ".claude/commands",
+					shape: "directory",
+					kind: "command"
+				},
+				{
+					path: ".claude/rules",
+					shape: "directory",
+					kind: "rule"
+				},
+				{
+					path: ".claude/agents",
+					shape: "directory",
+					kind: "subagent"
+				}
+			]
+		},
+		user: {
+			detect: ".claude",
+			...skillsProjection("claude-code", "user"),
+			relocatedBy: "CLAUDE_CONFIG_DIR",
+			emptyRelocatesToStart: true,
+			instructionBridge: {
+				kind: "import",
+				path: ".claude/CLAUDE.md",
+				line: `@~/${globalInstructions}`
+			}
+		}
+	},
+	{
+		name: "cursor",
+		project: {
+			detect: ".cursor",
+			...skillsProjection("cursor", "project"),
+			mcpConfig: {
+				path: ".cursor/mcp.json",
+				key: "mcpServers",
+				format: "json",
+				dialect: "cursor"
+			},
+			nonstandard: [
+				{
+					path: ".cursorrules",
+					shape: "file",
+					kind: "instructions"
+				},
+				{
+					path: ".cursor/rules",
+					shape: "directory",
+					kind: "rule"
+				},
+				{
+					path: ".cursor/commands",
+					shape: "directory",
+					kind: "command"
+				},
+				{
+					path: ".cursor/skills",
+					shape: "directory",
+					kind: "skill"
+				}
+			]
+		},
+		user: {
+			detect: ".cursor",
+			...skillsProjection("cursor", "user")
+		}
+	},
+	{
+		name: "codex",
+		project: {
+			detect: ".codex",
+			...skillsProjection("codex", "project"),
+			mcpConfig: {
+				path: ".codex/config.toml",
+				key: "mcp_servers",
+				format: "toml",
+				dialect: "codex",
+				shared: true
+			},
+			nonstandard: [{
+				path: ".codex/skills",
+				shape: "directory",
+				kind: "skill"
+			}]
+		},
+		user: {
+			detect: ".codex",
+			...skillsProjection("codex", "user"),
+			instructionBridge: {
+				kind: "symlink",
+				path: ".codex/AGENTS.md"
+			},
+			shadowedBy: [".codex/AGENTS.override.md"],
+			relocatedBy: "CODEX_HOME"
+		}
+	},
+	{
+		name: "copilot-cli",
+		project: {
+			detect: ".github/skills",
+			...skillsProjection("copilot-cli", "project"),
+			nonstandard: [
+				{
+					path: ".github/copilot-instructions.md",
+					shape: "file",
+					kind: "instructions"
+				},
+				{
+					path: ".github/instructions",
+					shape: "directory",
+					kind: "instructions"
+				},
+				{
+					path: ".github/skills",
+					shape: "directory",
+					kind: "skill"
+				}
+			]
+		},
+		user: {
+			detect: ".copilot",
+			...skillsProjection("copilot-cli", "user"),
+			relocatedBy: "COPILOT_HOME",
+			instructionBridge: {
+				kind: "symlink",
+				path: ".copilot/copilot-instructions.md"
+			}
+		}
+	},
+	{
+		name: "gemini-cli",
+		project: {
+			detect: ".gemini",
+			...skillsProjection("gemini-cli", "project"),
+			instructionBridge: {
+				kind: "settings-entry",
+				path: ".gemini/settings.json",
+				key: "context.fileName"
+			},
+			mcpConfig: {
+				path: ".gemini/settings.json",
+				key: "mcpServers",
+				format: "json",
+				dialect: "gemini-cli",
+				shared: true
+			},
+			nonstandard: [{
+				path: "GEMINI.md",
+				shape: "file",
+				kind: "instructions"
+			}, {
+				path: ".gemini/skills",
+				shape: "directory",
+				kind: "skill"
+			}]
+		},
+		user: {
+			detect: ".gemini",
+			...skillsProjection("gemini-cli", "user"),
+			instructionBridge: {
+				kind: "symlink",
+				path: ".gemini/GEMINI.md"
+			}
+		}
+	},
+	{
+		name: "devin-desktop",
+		project: { detect: ".devin" }
+	},
+	{
+		name: "windsurf",
+		project: {
+			detect: ".windsurf",
+			skillsDirectory: ".windsurf/skills",
+			nonstandard: [{
+				path: ".windsurfrules",
+				shape: "file",
+				kind: "instructions"
+			}, {
+				path: ".windsurf/rules",
+				shape: "directory",
+				kind: "rule"
+			}]
+		},
+		deprecated: "devin-desktop"
+	}
+];
+const harnessNames = new Set(harnessRegistry.map((harness) => harness.name));
+function isHarnessName(value) {
+	return harnessNames.has(value);
+}
+/**
+* An unknown name throws rather than being dropped — silently falling back to the defaults would
+* misreport what was diagnosed.
+*/
+function parseHarnesses(value) {
+	const requested = (value ?? "").split(",").map((name) => name.trim()).filter(Boolean);
+	const unsupported = requested.filter((name) => !isHarnessName(name));
+	if (unsupported.length) throw new Error(`Unsupported harness: ${unsupported.join(", ")}. Supported: ${harnessRegistry.map((harness) => harness.name).join(", ")}.`);
+	return requested.filter(isHarnessName);
+}
+/** Enabled whether or not the repository already contains their directories. */
+const defaultHarnesses = ["claude-code", "cursor"];
+function directoryExists(path) {
+	try {
+		return lstatSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */
+function selectHarnesses(root, preferred) {
+	const enabled = /* @__PURE__ */ new Set([...defaultHarnesses, ...preferred]);
+	return harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.project.detect)));
+}
+//#endregion
 //#region src/command-output/command-output.ts
 /**
-* Reports a failure on stderr, not stdout — stdout carries what an agent parses — and fails the cli
-* with the exit code. A `CliError` the cli already reports is rethrown untouched.
+* AXI §6: a failure is a coded error on stdout, in the caller's format, with a `help` line saying
+* what to do next. A `CliError` the command already built is rethrown untouched; anything else
+* becomes `command-failed`, exit code 1.
 */
-function fail(error, fallback) {
+function fail(error, fallback, help) {
 	if (isCliError(error)) throw error;
-	process.stderr.write(`error: ${error instanceof Error ? error.message : fallback}\n`);
-	throw CliError.reported(exitCodes.error);
+	throw new CliError(error instanceof Error ? error.message : fallback, {
+		code: "command-failed",
+		exitCode: exitCodes.error,
+		...help ? { help } : {},
+		cause: error
+	});
 }
 /**
 * An answer that comes with a failing exit code. The cli prints only an answer a command returns, and
@@ -39,6 +300,22 @@ function collapseHome(home, path) {
 function displayBinPath(home, executable) {
 	return executable ? collapseHome(home, executable) : "buddy-agent-harness";
 }
+/**
+* `parseHarnesses` for a command's `--harness`: an unsupported name is a usage error, exit code 2.
+* The registry stays free of clibuilder, which the library entry treats as an optional peer.
+*/
+function parseHarnessOption(value) {
+	try {
+		return parseHarnesses(value);
+	} catch (error) {
+		throw new CliError(error.message, {
+			code: "unsupported-harness",
+			exitCode: exitCodes.usage,
+			help: "Pass --harness as a comma-separated list of the supported names.",
+			cause: error
+		});
+	}
+}
 //#endregion
 //#region src/dep-plugins/dep-plugins.ts
 /** Generic marketplace names: a second registration under one of these replaces the first, silently. */
@@ -94,7 +371,7 @@ function serializeCatalog(catalog) {
 }
 //#endregion
 //#region src/dep-plugins/resolve.ts
-function readJson$1(path) {
+function readJson$2(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -109,7 +386,7 @@ function readDepPlugin(pkg, fromManifest) {
 		package: pkg,
 		reason: "unresolved"
 	};
-	const manifest = readJson$1(join(dir, "plugin.json"));
+	const manifest = readJson$2(join(dir, "plugin.json"));
 	if (!manifest || typeof manifest !== "object") return {
 		ok: false,
 		package: pkg,
@@ -122,7 +399,7 @@ function readDepPlugin(pkg, fromManifest) {
 		package: pkg,
 		reason: "unnamed"
 	};
-	const installed = readJson$1(join(dir, "package.json"));
+	const installed = readJson$2(join(dir, "package.json"));
 	const version = typeof installed?.version === "string" ? installed.version : void 0;
 	if (!version) return {
 		ok: false,
@@ -215,7 +492,7 @@ function writeCatalog(root, catalog) {
 //#endregion
 //#region src/dep-plugins/harness-plugins.ts
 const COPILOT_LIMITATION = "Copilot CLI rejects an npm marketplace source, so it cannot install from this catalog. It needs a path-sourced catalog, which cannot reach node_modules from a subdirectory.";
-function readJson(path) {
+function readJson$1(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -233,7 +510,7 @@ function claudeConfigDir(home, env = process.env) {
 	return env["CLAUDE_CONFIG_DIR"] || join(home, ".claude");
 }
 function readClaudeState(configDir) {
-	const installedFile = readJson(join(configDir, "plugins", "installed_plugins.json"));
+	const installedFile = readJson$1(join(configDir, "plugins", "installed_plugins.json"));
 	const installed = [];
 	for (const [id, entries] of Object.entries(installedFile?.plugins ?? {})) {
 		if (!Array.isArray(entries)) continue;
@@ -256,7 +533,7 @@ function readClaudeState(configDir) {
 			});
 		}
 	}
-	const knownFile = readJson(join(configDir, "plugins", "known_marketplaces.json"));
+	const knownFile = readJson$1(join(configDir, "plugins", "known_marketplaces.json"));
 	const marketplaces = [];
 	for (const [name, value] of Object.entries(knownFile ?? {})) marketplaces.push({
 		name,
@@ -394,350 +671,101 @@ function commandFor(runtime, action, marketplace) {
 			return refresh ? `${refresh} && ${update}` : update;
 		}
 		case "uninstall": return runtime.uninstall(action.subject);
-	}
-}
-function notesFor(derived) {
-	const notes = [];
-	if (derived.pnp) notes.push("Yarn Plug’n’Play is active: dependencies live inside zip archives, so no harness can install from them. Set nodeLinker: node-modules, or unplug the plugin dependencies.");
-	if (derived.genericName) notes.push(`Marketplace name "${derived.catalog.name}" is generic. Registering a second marketplace under a name already in use replaces the first silently, and the install that follows reports "already installed" — the repository then runs the other one's versions.`);
-	for (const { package: pkg } of derived.unresolved) notes.push(`Declared dependency "${pkg}" is not installed; install dependencies before generating.`);
-	return notes;
-}
-const depPluginsCommand = command({
-	name: "dep-plugins",
-	description: "Derive the marketplace catalog for plugins shipped by this repository’s dependencies, so a harness can install them. Writes the catalog; installing is the harness’s own job.",
-	options: {
-		root: {
-			description: "Repository directory. Defaults to the current directory.",
-			type: t.string().optional()
-		},
-		check: {
-			description: "Report whether the catalog is current without writing it. For CI and postinstall.",
-			type: t.boolean().optional()
-		}
-	},
-	run(args) {
-		try {
-			const root = args.root ?? process.cwd();
-			const derived = deriveCatalog(root);
-			const outcome = args.check ? catalogStatus(root, derived.catalog) === "unchanged" ? "current" : "would-change" : writeCatalog(root, derived.catalog);
-			const home = homedir();
-			const notes = notesFor(derived);
-			const detected = runtimes.filter((candidate) => candidate.installedOnMachine(home));
-			const harness = [];
-			const actions = [];
-			for (const runtime of detected) {
-				const state = runtime.state(home);
-				const delta = reconcile({
-					catalog: derived.catalog,
-					catalogDir: CATALOG_DIR,
-					root: resolve(root),
-					installed: state.installed,
-					marketplaces: state.marketplaces,
-					scoped: runtime.scoped
-				});
-				if (delta.collision) notes.push(`${runtime.name}: marketplace "${derived.catalog.name}" is already registered against ${delta.collision}. Registering over it replaces the other repository's silently, and the install that follows reports "already installed" — rename this repository's marketplace instead.`);
-				harness.push({
-					runtime: runtime.name,
-					status: delta.actions.length ? `${delta.actions.length} to apply` : "in sync"
-				});
-				for (const action of delta.actions) actions.push({
-					runtime: runtime.name,
-					do: commandFor(runtime, action, derived.catalog.name),
-					subject: action.subject,
-					why: action.detail
-				});
-			}
-			if (derived.plugins.length) notes.push(COPILOT_LIMITATION);
-			const report = {
-				catalog: CATALOG_PATH,
-				marketplace: derived.catalog.name,
-				outcome,
-				plugins: derived.plugins.length ? derived.plugins.map(({ plugin, package: pkg, version }) => ({
-					name: plugin,
-					package: pkg,
-					version
-				})) : "0 dependencies ship a plugin — nothing to install",
-				harness: harness.length ? harness : "no supported harness detected on this machine",
-				actions: actions.length ? actions : "0 actions — every detected harness matches the catalog",
-				...notes.length ? { notes } : {}
-			};
-			const answer = result(report);
-			return outcome === "would-change" ? answerThenFail(answer, this.format) : answer;
-		} catch (error) {
-			return fail(error, "Catalog generation failed.");
-		}
-	}
-});
-//#endregion
-//#region src/diagnose-bridges/directory-files.ts
-/** A directory that does not exist reads as empty: `doctor` never creates one to look at it. */
-function filesUnder(directory) {
-	try {
-		return readdirSync(directory, {
-			recursive: true,
-			withFileTypes: true
-		}).filter((entry) => entry.isFile()).map((entry) => relative(directory, join(entry.parentPath, entry.name)).split(sep).join(posix.sep)).sort();
-	} catch {
-		return [];
-	}
-}
-//#endregion
-//#region src/harness-registry/harness-registry.ts
-/**
-* Throws on a harness `skillsDirectories` does not confirm: treating it as native would silently
-* drop a projection it may need.
-*/
-function skillsProjection(harness, scope, directories = skillsDirectories(harness)?.[scope]) {
-	const listed = directories ?? [];
-	const [first] = listed;
-	if (first === void 0) throw new Error(`cyber-agentkit records no ${scope} skills directories for ${harness}.`);
-	return listed.includes(".agents/skills") ? {} : { skillsDirectory: first };
-}
-/**
-* The user-scope counterpart of the root `AGENTS.md`, relative to the home directory. No harness
-* reads it natively; each loads it only through a user-scope `instructionBridge` (E-CC-18, E-CODEX-05,
-* E-GEM-03, E-COPILOT-04, E-CUR-08).
-*/
-const globalInstructions = ".agents/AGENTS.md";
-/**
-* Skills directories come from `cyber-agentkit`, except for the harnesses it does not know
-* (`devin-desktop`, `windsurf`); see `.research/agentic-configuration-standards/` for the rest.
-*/
-const harnessRegistry = [
-	{
-		name: "claude-code",
-		project: {
-			detect: ".claude",
-			...skillsProjection("claude-code", "project"),
-			shadowedBy: [
-				"CLAUDE.md",
-				".claude/CLAUDE.md",
-				"CLAUDE.local.md"
-			],
-			mcpConfig: {
-				path: ".mcp.json",
-				key: "mcpServers",
-				format: "json",
-				dialect: "claude-code"
-			},
-			nonstandard: [
-				{
-					path: ".claude/commands",
-					shape: "directory",
-					kind: "command"
-				},
-				{
-					path: ".claude/rules",
-					shape: "directory",
-					kind: "rule"
-				},
-				{
-					path: ".claude/agents",
-					shape: "directory",
-					kind: "subagent"
-				}
-			]
-		},
-		user: {
-			detect: ".claude",
-			...skillsProjection("claude-code", "user"),
-			relocatedBy: "CLAUDE_CONFIG_DIR",
-			emptyRelocatesToStart: true,
-			instructionBridge: {
-				kind: "import",
-				path: ".claude/CLAUDE.md",
-				line: `@~/${globalInstructions}`
-			}
-		}
-	},
-	{
-		name: "cursor",
-		project: {
-			detect: ".cursor",
-			...skillsProjection("cursor", "project"),
-			mcpConfig: {
-				path: ".cursor/mcp.json",
-				key: "mcpServers",
-				format: "json",
-				dialect: "cursor"
-			},
-			nonstandard: [
-				{
-					path: ".cursorrules",
-					shape: "file",
-					kind: "instructions"
-				},
-				{
-					path: ".cursor/rules",
-					shape: "directory",
-					kind: "rule"
-				},
-				{
-					path: ".cursor/commands",
-					shape: "directory",
-					kind: "command"
-				},
-				{
-					path: ".cursor/skills",
-					shape: "directory",
-					kind: "skill"
-				}
-			]
-		},
-		user: {
-			detect: ".cursor",
-			...skillsProjection("cursor", "user")
-		}
-	},
-	{
-		name: "codex",
-		project: {
-			detect: ".codex",
-			...skillsProjection("codex", "project"),
-			mcpConfig: {
-				path: ".codex/config.toml",
-				key: "mcp_servers",
-				format: "toml",
-				dialect: "codex",
-				shared: true
-			},
-			nonstandard: [{
-				path: ".codex/skills",
-				shape: "directory",
-				kind: "skill"
-			}]
-		},
-		user: {
-			detect: ".codex",
-			...skillsProjection("codex", "user"),
-			instructionBridge: {
-				kind: "symlink",
-				path: ".codex/AGENTS.md"
-			},
-			shadowedBy: [".codex/AGENTS.override.md"],
-			relocatedBy: "CODEX_HOME"
-		}
-	},
-	{
-		name: "copilot-cli",
-		project: {
-			detect: ".github/skills",
-			...skillsProjection("copilot-cli", "project"),
-			nonstandard: [
-				{
-					path: ".github/copilot-instructions.md",
-					shape: "file",
-					kind: "instructions"
-				},
-				{
-					path: ".github/instructions",
-					shape: "directory",
-					kind: "instructions"
-				},
-				{
-					path: ".github/skills",
-					shape: "directory",
-					kind: "skill"
-				}
-			]
+	}
+}
+function notesFor(derived) {
+	const notes = [];
+	if (derived.pnp) notes.push("Yarn Plug’n’Play is active: dependencies live inside zip archives, so no harness can install from them. Set nodeLinker: node-modules, or unplug the plugin dependencies.");
+	if (derived.genericName) notes.push(`Marketplace name "${derived.catalog.name}" is generic. Registering a second marketplace under a name already in use replaces the first silently, and the install that follows reports "already installed" — the repository then runs the other one's versions.`);
+	for (const { package: pkg } of derived.unresolved) notes.push(`Declared dependency "${pkg}" is not installed; install dependencies before generating.`);
+	return notes;
+}
+const depPluginsCommand = command({
+	name: "dep-plugins",
+	description: "Derive the marketplace catalog for plugins shipped by this repository’s dependencies, so a harness can install them. Writes the catalog; installing is the harness’s own job.",
+	options: {
+		root: {
+			description: "Repository directory. Defaults to the current directory.",
+			type: t.string().optional()
 		},
-		user: {
-			detect: ".copilot",
-			...skillsProjection("copilot-cli", "user"),
-			relocatedBy: "COPILOT_HOME",
-			instructionBridge: {
-				kind: "symlink",
-				path: ".copilot/copilot-instructions.md"
-			}
+		check: {
+			description: "Report whether the catalog is current without writing it. For CI and postinstall.",
+			type: t.boolean().optional()
 		}
 	},
-	{
-		name: "gemini-cli",
-		project: {
-			detect: ".gemini",
-			...skillsProjection("gemini-cli", "project"),
-			instructionBridge: {
-				kind: "settings-entry",
-				path: ".gemini/settings.json",
-				key: "context.fileName"
-			},
-			mcpConfig: {
-				path: ".gemini/settings.json",
-				key: "mcpServers",
-				format: "json",
-				dialect: "gemini-cli",
-				shared: true
-			},
-			nonstandard: [{
-				path: "GEMINI.md",
-				shape: "file",
-				kind: "instructions"
-			}, {
-				path: ".gemini/skills",
-				shape: "directory",
-				kind: "skill"
-			}]
-		},
-		user: {
-			detect: ".gemini",
-			...skillsProjection("gemini-cli", "user"),
-			instructionBridge: {
-				kind: "symlink",
-				path: ".gemini/GEMINI.md"
+	examples: [{
+		command: "buddy-agent-harness dep-plugins",
+		description: "Write the marketplace catalog for dependency plugins"
+	}, {
+		command: "buddy-agent-harness dep-plugins --check",
+		description: "Fail when the catalog is stale (CI)"
+	}],
+	run(args) {
+		try {
+			const root = args.root ?? process.cwd();
+			const derived = deriveCatalog(root);
+			const outcome = args.check ? catalogStatus(root, derived.catalog) === "unchanged" ? "current" : "would-change" : writeCatalog(root, derived.catalog);
+			const home = homedir();
+			const notes = notesFor(derived);
+			const detected = runtimes.filter((candidate) => candidate.installedOnMachine(home));
+			const harness = [];
+			const actions = [];
+			for (const runtime of detected) {
+				const state = runtime.state(home);
+				const delta = reconcile({
+					catalog: derived.catalog,
+					catalogDir: CATALOG_DIR,
+					root: resolve(root),
+					installed: state.installed,
+					marketplaces: state.marketplaces,
+					scoped: runtime.scoped
+				});
+				if (delta.collision) notes.push(`${runtime.name}: marketplace "${derived.catalog.name}" is already registered against ${delta.collision}. Registering over it replaces the other repository's silently, and the install that follows reports "already installed" — rename this repository's marketplace instead.`);
+				harness.push({
+					runtime: runtime.name,
+					status: delta.actions.length ? `${delta.actions.length} to apply` : "in sync"
+				});
+				for (const action of delta.actions) actions.push({
+					runtime: runtime.name,
+					do: commandFor(runtime, action, derived.catalog.name),
+					subject: action.subject,
+					why: action.detail
+				});
 			}
+			if (derived.plugins.length) notes.push(COPILOT_LIMITATION);
+			const report = {
+				catalog: CATALOG_PATH,
+				marketplace: derived.catalog.name,
+				outcome,
+				plugins: derived.plugins.length ? derived.plugins.map(({ plugin, package: pkg, version }) => ({
+					name: plugin,
+					package: pkg,
+					version
+				})) : "0 dependencies ship a plugin — nothing to install",
+				harness: harness.length ? harness : "no supported harness detected on this machine",
+				actions: actions.length ? actions : "0 actions — every detected harness matches the catalog",
+				...notes.length ? { notes } : {}
+			};
+			const answer = result(report);
+			return outcome === "would-change" ? answerThenFail(answer, this.format) : answer;
+		} catch (error) {
+			return fail(error, "Catalog generation failed.");
 		}
-	},
-	{
-		name: "devin-desktop",
-		project: { detect: ".devin" }
-	},
-	{
-		name: "windsurf",
-		project: {
-			detect: ".windsurf",
-			skillsDirectory: ".windsurf/skills",
-			nonstandard: [{
-				path: ".windsurfrules",
-				shape: "file",
-				kind: "instructions"
-			}, {
-				path: ".windsurf/rules",
-				shape: "directory",
-				kind: "rule"
-			}]
-		},
-		deprecated: "devin-desktop"
 	}
-];
-const harnessNames = new Set(harnessRegistry.map((harness) => harness.name));
-function isHarnessName(value) {
-	return harnessNames.has(value);
-}
-/**
-* An unknown name throws rather than being dropped — silently falling back to the defaults would
-* misreport what was diagnosed.
-*/
-function parseHarnesses(value) {
-	const requested = (value ?? "").split(",").map((name) => name.trim()).filter(Boolean);
-	const unsupported = requested.filter((name) => !isHarnessName(name));
-	if (unsupported.length) throw new Error(`Unsupported harness: ${unsupported.join(", ")}. Supported: ${harnessRegistry.map((harness) => harness.name).join(", ")}.`);
-	return requested.filter(isHarnessName);
-}
-/** Enabled whether or not the repository already contains their directories. */
-const defaultHarnesses = ["claude-code", "cursor"];
-function directoryExists(path) {
+});
+//#endregion
+//#region src/diagnose-bridges/directory-files.ts
+/** A directory that does not exist reads as empty: `doctor` never creates one to look at it. */
+function filesUnder(directory) {
 	try {
-		return lstatSync(path).isDirectory();
+		return readdirSync(directory, {
+			recursive: true,
+			withFileTypes: true
+		}).filter((entry) => entry.isFile()).map((entry) => relative(directory, join(entry.parentPath, entry.name)).split(sep).join(posix.sep)).sort();
 	} catch {
-		return false;
+		return [];
 	}
 }
-/** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */
-function selectHarnesses(root, preferred) {
-	const enabled = /* @__PURE__ */ new Set([...defaultHarnesses, ...preferred]);
-	return harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.project.detect)));
-}
 //#endregion
 //#region src/diagnose-bridges/locator.ts
 /** The locator as one string: the finding's `path`, and what a repair names. */
@@ -776,6 +804,7 @@ const initSkillInvocation = `/buddy-agent-harness:init-buddy-agent-harness`;
 */
 const pnpmSkillRef = (invocation) => `\`${invocation}\` (pnpm install: \`pnpm-${commandInvocation}-${invocation.slice(invocation.indexOf(":") + 1)}\`)`;
 const initSkillRef = pnpmSkillRef(initSkillInvocation);
+const enhanceSkillRef = pnpmSkillRef("/buddy-agent-harness:enhance");
 const repairSkillRef = pnpmSkillRef(repairSkillInvocation);
 /** Where the user authors the golden MCP server set, named in every MCP repair that points at it. */
 const goldenSet = ".agents/buddy-agent-harness/mcp.toml";
@@ -1141,6 +1170,35 @@ const nonstandardTable = {
 	}
 };
 repairsOf(nonstandardTable);
+/** Who offers every worktree repair, named the same way in each row. */
+const worktreeOffer = `${initSkillRef} offers it, or ${enhanceSkillRef} where the repository already has an AGENTS.md`;
+const worktreeTable = {
+	"worktrees-untracked": {
+		detail: ".claude/worktrees/ is not git-ignored, so every agent worktree Claude Code creates there shows up as untracked in git status",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `add \`.claude/worktrees/\` to ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the .gitignore line`
+	},
+	"worktrees-scanned": {
+		detail: "this config does not exclude .claude/worktrees, so the tool walks into each agent worktree, a whole checkout with its own config, and Biome stops on the nested root configuration",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `add \`"!**/.claude/worktrees"\` to \`files.includes\` in ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the exclusion`
+	},
+	"worktree-base-unset": {
+		detail: "worktree.baseRef is unset, so agent worktrees branch from the default branch rather than the current HEAD — work on a feature branch starts without its commits",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `decide whether agent worktrees should branch from HEAD, and if so set \`"worktree": { "baseRef": "head" }\` in ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which explains the trade-off and offers the setting`
+	}
+};
+repairsOf(worktreeTable);
 /**
 * Annotated over the whole union rather than inferred, so an added problem fails to compile until
 * its section carries it.
@@ -1151,7 +1209,8 @@ const doctorTable = {
 	...globalInstructionTable,
 	...configurationTable,
 	...mcpTable,
-	...nonstandardTable
+	...nonstandardTable,
+	...worktreeTable
 };
 const doctorRepairs = repairsOf(doctorTable);
 /** The repair for one problem. Total by construction: the table is keyed by the union. */
@@ -1163,7 +1222,7 @@ function repairFor(problem) {
 }
 const doctorSkill = {
 	name: "doctor-buddy-agent-harness",
-	description: "Use this skill when a repository loads no project skills, when skills are missing after a clone, when a harness appears to be ignoring AGENTS.md, or when checking whether the agent configuration bridges into .claude/skills and the other harness files still resolve."
+	description: "Checks whether a repository's agent configuration bridges into .claude/skills and the other harness files still resolve — when a repository loads no project skills, when skills are missing after a clone, or when a harness appears to be ignoring AGENTS.md."
 };
 /** Written into the generated skill so a reader knows not to edit it in place. */
 const generatedSkillWarning = "<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->";
@@ -1230,6 +1289,7 @@ Every \`problem\` name routes to exactly one page. Load the page for the finding
 | \`references/configuration.md\` | a finding about the configuration around the bridges rather than a bridge |
 | \`references/mcp.md\` | any finding whose path is an MCP locator — **always** before acting on a credential finding |
 | \`references/nonstandard.md\` | a finding about configuration only one harness can read |
+| \`references/worktrees.md\` | a finding about the agent worktrees Claude Code creates under \`.claude/worktrees/\` |
 | \`references/harnesses/<name>.md\` | the paths and files one named harness uses |
 
 ## Rules
@@ -1240,6 +1300,12 @@ Every \`problem\` name routes to exactly one page. Load the page for the finding
 - Never repeat a value from a file an \`mcp-literal-secret\` or \`mcp-committed-secret\` finding points at. The report withheld it on purpose, and quoting it back puts it in the transcript anyway.
 - Never write outside the repository. A \`globalInstructions\` repair is a step for the user to take in their own home directory; hand it over exactly as reported.
 - Write instructions in \`AGENTS.md\`, never in \`CLAUDE.md\`. Content written there reaches one harness, drifts from the canonical file, and — because Claude Code prefers it — takes \`AGENTS.md\` out of that harness's context entirely.
+
+## Done when
+
+- **C1.** The reply names each problem the report found and its cause, or, when the report found none, says the configuration is healthy and calls for no change.
+- **C2.** No bridge, skill, or instruction file changed: no \`init\` ran, and nothing was written to \`CLAUDE.md\`.
+- **C3.** The reply repeats no value that a secret finding withheld.
 `;
 }
 //#endregion
@@ -2052,6 +2118,43 @@ function diagnoseNonstandard({ root, cli }) {
 	}
 	return findings.sort((left, right) => left.path.localeCompare(right.path));
 }
+const biomeConfigs = ["biome.json", "biome.jsonc"];
+const claudeSettings = ".claude/settings.json";
+/** `undefined` when the file is missing or does not parse; either way Claude Code reads no base from it. */
+function readJson(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Checked only where `.claude/` exists, the sign the repository is worked in with Claude Code.
+* Biome is the one tool checked: it is the confirmed failure, and the others are offered by the
+* skills without a finding.
+*/
+function diagnoseWorktrees({ root, git, cli }) {
+	if (!existsSync(join(root, ".claude"))) return [];
+	const findings = [];
+	const add = (path, problem) => {
+		const { detail, repair } = repairFor(problem);
+		findings.push({
+			path,
+			problem,
+			detail,
+			repair: repair({ file: path }, cli)
+		});
+	};
+	if (git.isRepository() && !git.isIgnored(".claude/worktrees/")) add(".gitignore", "worktrees-untracked");
+	for (const config of biomeConfigs) {
+		const path = join(root, config);
+		if (existsSync(path) && !readFileSync(path, "utf8").includes(".claude/worktrees")) add(config, "worktrees-scanned");
+	}
+	const settings = readJson(join(root, claudeSettings));
+	const worktree = isRecord(settings) ? settings["worktree"] : void 0;
+	if (!isRecord(worktree) || worktree["baseRef"] === void 0) add(claudeSettings, "worktree-base-unset");
+	return findings;
+}
 //#endregion
 //#region src/governance-overrides/governance-overrides.ts
 function machineWideDir(platform, programData, names) {
@@ -2204,10 +2307,13 @@ function referenceLayers({ packageRoot = dirname(packageGovernancesDir()), ...op
 		}
 	});
 }
-const referenceCommand = createReferenceCommand({ plugin: {
-	name: PACKAGE_PLUGIN,
-	root: dirname(packageGovernancesDir())
-} });
+const referenceCommand = createReferenceCommand({
+	plugin: {
+		name: PACKAGE_PLUGIN,
+		root: dirname(packageGovernancesDir())
+	},
+	path: "buddy-agent-harness reference"
+});
 //#endregion
 //#region src/skill-projection/skill-projection.ts
 function skillNames(skillsDirectory) {
@@ -2660,6 +2766,10 @@ var GitBridgeState = class {
 		this.root = root;
 		this.repoRootPrefix = git(root, ["rev-parse", "--show-prefix"])?.trim();
 	}
+	/** Whether `root` is inside a git work tree at all; a check that needs git's answer skips when not. */
+	isRepository() {
+		return this.repoRootPrefix !== void 0;
+	}
 	/** The skip-worktree bit is a hint some checkouts clear, so it is verified rather than assumed. */
 	trackingOf(path) {
 		if (this.repoRootPrefix === void 0) return "untracked";
@@ -2922,64 +3032,82 @@ function buildDoctorReport(bin, result, configuration = [], held = []) {
 		help: [...new Map(findings.map((finding) => [`${finding.repair.command}\u0000${finding.repair.instruction}`, finding.repair])).values()]
 	};
 }
-const doctorCommand = command({
-	name: "doctor",
-	description: "Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md — and whether each harness's user-scope file loads ~/.agents/AGENTS.md. Read-only.",
-	options: {
-		root: {
-			description: "Repository or package directory. Defaults to the current directory.",
-			type: t.string().optional()
-		},
-		harness: {
-			description: "Comma-separated harnesses to check in addition to Claude Code and Cursor, e.g. codex,gemini-cli.",
-			type: t.string().optional()
-		}
+const doctorOptions = {
+	root: {
+		description: "Repository or package directory. Defaults to the current directory.",
+		type: t.string().optional()
 	},
-	async run(args) {
-		try {
-			const harnesses = parseHarnesses(args.harness);
-			const root = args.root ?? process.cwd();
-			const home = homedir();
-			const diagnosis = diagnoseBridges({
+	harness: {
+		description: "Comma-separated harnesses to check in addition to Claude Code and Cursor, e.g. codex,gemini-cli.",
+		type: t.string().optional()
+	}
+};
+const doctorDescription = "Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md — and whether each harness's user-scope file loads ~/.agents/AGENTS.md. Read-only.";
+/** The live report `doctor` answers with, shared with the bare invocation of the CLI. */
+async function diagnoseReport(args) {
+	try {
+		const harnesses = parseHarnessOption(args.harness);
+		const root = args.root ?? process.cwd();
+		const home = homedir();
+		const diagnosis = diagnoseBridges({
+			root,
+			...harnesses.length ? { harnesses } : {},
+			cli: commandInvocation,
+			home,
+			env: process.env
+		});
+		const git = new GitBridgeState(root);
+		const configuration = [
+			...diagnoseConfiguration({
 				root,
-				...harnesses.length ? { harnesses } : {},
-				cli: commandInvocation,
-				home,
-				env: process.env
-			});
-			const git = new GitBridgeState(root);
-			const configuration = [
-				...diagnoseConfiguration({
-					root,
-					git,
-					cli: commandInvocation
-				}),
-				...diagnoseMcp({
-					root,
-					git,
-					cli: commandInvocation
-				}),
-				...diagnoseNonstandard({
-					root,
-					cli: commandInvocation
-				})
-			];
-			const { layers: rows } = listReferences$1(await referenceLayers({
+				git,
+				cli: commandInvocation
+			}),
+			...diagnoseMcp({
 				root,
-				home,
-				platform: process.platform,
-				env: process.env
-			}));
-			const held = rows.filter(({ tier }) => tier !== "plugin").map(({ name, tier, path, outcome }) => ({
-				name,
-				tier,
-				path: collapseHome(home, path),
-				status: outcome
-			}));
-			return result(buildDoctorReport(displayBinPath(home, process.argv[1]), diagnosis, configuration, held));
-		} catch (error) {
-			return fail(error, "Harness diagnosis failed.");
-		}
+				git,
+				cli: commandInvocation
+			}),
+			...diagnoseNonstandard({
+				root,
+				cli: commandInvocation
+			}),
+			...diagnoseWorktrees({
+				root,
+				git,
+				cli: commandInvocation
+			})
+		];
+		const { layers: rows } = listReferences$1(await referenceLayers({
+			root,
+			home,
+			platform: process.platform,
+			env: process.env
+		}));
+		const held = rows.filter(({ tier }) => tier !== "plugin").map(({ name, tier, path, outcome }) => ({
+			name,
+			tier,
+			path: collapseHome(home, path),
+			status: outcome
+		}));
+		return buildDoctorReport(displayBinPath(home, process.argv[1]), diagnosis, configuration, held);
+	} catch (error) {
+		return fail(error, "Harness diagnosis failed.");
+	}
+}
+const doctorCommand = command({
+	name: "doctor",
+	description: doctorDescription,
+	options: doctorOptions,
+	examples: [{
+		command: "buddy-agent-harness doctor",
+		description: "Check the current repository"
+	}, {
+		command: "buddy-agent-harness doctor --harness codex,gemini-cli",
+		description: "Also check Codex and Gemini CLI"
+	}],
+	async run(args) {
+		return result(await diagnoseReport(args));
 	}
 });
 //#endregion
@@ -3010,6 +3138,10 @@ const governanceListCommand = command({
 		root: rootOption,
 		"overrides-only": overridesOnlyOption
 	},
+	examples: [{
+		command: "buddy-agent-harness governance list",
+		description: "List the governances the layers hold"
+	}],
 	run(args) {
 		process.stderr.write(GOVERNANCE_DEPRECATED);
 		try {
@@ -3046,16 +3178,21 @@ const governanceShowCommand = command({
 		root: rootOption,
 		"overrides-only": overridesOnlyOption
 	},
+	examples: [{
+		command: "buddy-agent-harness governance show skill-design",
+		description: "Print one governance document"
+	}],
 	run(args) {
 		const format = this.format;
 		process.stderr.write(GOVERNANCE_DEPRECATED);
 		try {
 			const name = parseGovernanceName(args.name);
 			const found = resolveGovernance(name, layersFor(args));
-			if (!found) {
-				process.stderr.write(args["overrides-only"] ? `error: no override for governance "${name}" in the project, user, or machine-wide layer.\n` : `error: no governance named "${name}" in any layer.\n`);
-				throw CliError.reported(exitCodes.error);
-			}
+			if (!found) throw new CliError(args["overrides-only"] ? `no override for governance "${name}" in the project, user, or machine-wide layer.` : `no governance named "${name}" in any layer.`, {
+				code: "governance-not-found",
+				details: { name },
+				help: ref("reference list", {}, "see what is available")
+			});
 			const report = {
 				name: found.name,
 				scope: found.scope,
@@ -3136,9 +3273,16 @@ const initCommand = command({
 			type: t.string().optional()
 		}
 	},
+	examples: [{
+		command: "buddy-agent-harness init",
+		description: "Set up skills for Claude Code and Cursor"
+	}, {
+		command: "buddy-agent-harness init --harness codex --copy",
+		description: "Also enable Codex, copying skills instead of linking"
+	}],
 	run(args) {
 		try {
-			const harnesses = parseHarnesses(args.harness);
+			const harnesses = parseHarnessOption(args.harness);
 			return result(initializeHarnesses({
 				root: args.root ?? process.cwd(),
 				...harnesses.length ? { harnesses } : {},
@@ -3594,6 +3738,13 @@ const mcpReconcileCommand = command({
 			type: t.array(t.string()).optional()
 		}
 	},
+	examples: [{
+		command: "buddy-agent-harness mcp reconcile",
+		description: "List harness-side changes the golden set lacks"
+	}, {
+		command: "buddy-agent-harness mcp reconcile --accept <path>",
+		description: "Import one approved field"
+	}],
 	run(args) {
 		try {
 			const root = args.root ?? process.cwd();
@@ -3605,19 +3756,17 @@ const mcpReconcileCommand = command({
 			});
 			if (plan.kind === "unreadable") {
 				const at = plan.position ? ` at line ${plan.position.line}, column ${plan.position.column}` : "";
-				process.stderr.write(`error: ${goldenSetPath} does not parse${at}.\n`);
-				throw CliError.reported(exitCodes.error);
-			}
-			if (plan.kind === "rejected") {
-				process.stderr.write(`error: nothing written.\n${plan.reasons.map((reason) => `- ${reason}\n`).join("")}`);
-				throw CliError.reported(exitCodes.error);
+				throw new CliError(`${goldenSetPath} does not parse${at}.`, {
+					code: "golden-set-unreadable",
+					help: `Fix the TOML syntax in ${goldenSetPath}, then re-run.`
+				});
 			}
-			if (plan.kind === "absent") return result({
-				golden: `0 servers — no golden set at ${goldenSetPath}`,
-				mode: "nothing to reconcile into",
-				fields: "0 fields",
-				record: "not written"
+			if (plan.kind === "rejected") throw new CliError("nothing written.", {
+				code: "accept-rejected",
+				details: { reasons: plan.reasons },
+				help: ref("mcp reconcile", {}, "list the fields that can be approved")
 			});
+			if (plan.kind === "absent") return empty(`0 servers — no golden set at ${goldenSetPath}`, { help: `Create ${goldenSetPath} first; there is nothing to reconcile into.` });
 			const report = {
 				golden: goldenSetPath,
 				mode: plan.written ? "written — only the fields named by --accept" : "dry run — nothing written; re-run with --accept <path> for each approved field",
@@ -3882,6 +4031,13 @@ const mcpProjectCommand = command({
 			type: t.boolean().optional()
 		}
 	},
+	examples: [{
+		command: "buddy-agent-harness mcp project",
+		description: "Preview what would be projected"
+	}, {
+		command: "buddy-agent-harness mcp project --write",
+		description: "Project the golden set into each harness"
+	}],
 	run(args) {
 		try {
 			const root = args.root ?? process.cwd();
@@ -3893,15 +4049,12 @@ const mcpProjectCommand = command({
 			});
 			if (plan.kind === "unreadable") {
 				const at = plan.position ? ` at line ${plan.position.line}, column ${plan.position.column}` : "";
-				process.stderr.write(`error: ${goldenSetPath} does not parse${at}.\n`);
-				throw CliError.reported(exitCodes.error);
+				throw new CliError(`${goldenSetPath} does not parse${at}.`, {
+					code: "golden-set-unreadable",
+					help: `Fix the TOML syntax in ${goldenSetPath}, then re-run.`
+				});
 			}
-			if (plan.kind === "absent") return result({
-				golden: `0 servers — no golden set at ${goldenSetPath}`,
-				mode: "nothing to project",
-				actions: "0 changes",
-				record: "not written"
-			});
+			if (plan.kind === "absent") return empty(`0 servers — no golden set at ${goldenSetPath}`, { help: [`Create ${goldenSetPath} with the MCP servers to project.`, ref("mcp project", {}, "preview the projection")] });
 			const report = {
 				golden: goldenSetPath,
 				mode: write ? "written" : "dry run — nothing written; re-run with --write to apply",
@@ -3943,6 +4096,19 @@ function app(format) {
 		version,
 		description: rootCommand.description,
 		format
+	}).default({
+		description: "Report whether this repository's harness bridges resolve (the same as `doctor`).",
+		options: doctorCommand.options,
+		async run(args) {
+			const { bin: _bin, ...report } = await diagnoseReport({
+				root: args["root"],
+				harness: args["harness"]
+			});
+			return result({
+				...homeHeader({ description: rootCommand.description }),
+				...report
+			});
+		}
 	}).command(first));
 }
 const textByDefault = {