buddy-agent-harness 1.0.1 → 1.2.0

package/src/cli.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from 'node:fs'
 import { cli } from 'clibuilder'
-import { exitCodes } from 'clibuilder/axi'
+import { exitCodes, homeHeader, result } from 'clibuilder/axi'
 import { depPluginsCommand } from './dep-plugins/dep-plugins.command.ts'
-import { doctorCommand } from './diagnose-bridges/doctor.command.ts'
+import { diagnoseReport, doctorCommand } from './diagnose-bridges/doctor.command.ts'
 import { governanceCommand } from './governance-overrides/governance.command.ts'
 import { initCommand } from './initialize-harnesses/init.command.ts'
 import { mcpCommand } from './project-mcp/mcp.command.ts'
@@ -31,9 +31,19 @@ export const rootCommand: { name: string; description: string; commands: readonl
 // would be shared by every later call in the process.
 function app(format: 'toon' | 'text') {
 	const [first, ...rest] = rootCommand.commands
+	// AXI §8: a bare invocation shows live data, not a manual — the doctor report, under the home header.
 	return rest.reduce(
 		(builder, command) => builder.command(command),
-		cli({ name: rootCommand.name, version, description: rootCommand.description, format }).command(first),
+		cli({ name: rootCommand.name, version, description: rootCommand.description, format })
+			.default({
+				description: "Report whether this repository's harness bridges resolve (the same as `doctor`).",
+				options: doctorCommand.options as NonNullable<typeof 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),
 	)
 }
 

package/src/command-output/command-output.ts

@@ -1,14 +1,20 @@
 import { sep } from 'node:path'
 import { type Answer, CliError, exitCodes, type Format, isCliError, printAnswer } from 'clibuilder/axi'
+import { type HarnessName, parseHarnesses } from '../harness-registry/harness-registry.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.
  */
-export function fail(error: unknown, fallback: string): never {
+export function fail(error: unknown, fallback: string, help?: string): never {
 	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,
+	})
 }
 
 /**
@@ -32,3 +38,20 @@ export function collapseHome(home: string, path: string): string {
 export function displayBinPath(home: string, executable: string | undefined): string {
 	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.
+ */
+export function parseHarnessOption(value: string | undefined): HarnessName[] {
+	try {
+		return parseHarnesses(value)
+	} catch (error) {
+		throw new CliError((error as Error).message, {
+			code: 'unsupported-harness',
+			exitCode: exitCodes.usage,
+			help: 'Pass --harness as a comma-separated list of the supported names.',
+			cause: error,
+		})
+	}
+}

package/src/dep-plugins/dep-plugins.command.ts

@@ -74,6 +74,10 @@ export const depPluginsCommand: cli.Command = command({
 			type: t.boolean().optional(),
 		},
 	},
+	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()

package/src/diagnose-bridges/doctor-guidance.ts

@@ -72,6 +72,12 @@ export type GlobalInstructionProblem =
 	| 'global-instructions-overridden'
 	| 'global-instructions-emptied'
 
+/**
+ * What a repository lacks for the git worktrees Claude Code creates under `.claude/worktrees/`;
+ * each is an offer `init` and `enhance` make, never a fault in a file the owner wrote.
+ */
+export type WorktreeProblem = 'worktrees-untracked' | 'worktrees-scanned' | 'worktree-base-unset'
+
 /** Everything `doctor` can report against, across every section. */
 export type DoctorProblem =
 	| BridgeProblem
@@ -80,6 +86,7 @@ export type DoctorProblem =
 	| ConfigurationFault
 	| McpProblem
 	| NonstandardProblem
+	| WorktreeProblem
 
 /** Alias kept for callers that name the whole set rather than one section. */
 export type ConfigurationProblem = DoctorProblem
@@ -192,6 +199,7 @@ export const pnpmSkillRef = (invocation: string): string =>
 	`\`${invocation}\` (pnpm install: \`pnpm-${commandInvocation}-${invocation.slice(invocation.indexOf(':') + 1)}\`)`
 
 export const initSkillRef: string = pnpmSkillRef(initSkillInvocation)
+export const enhanceSkillRef: string = pnpmSkillRef('/buddy-agent-harness:enhance')
 export const repairSkillRef: string = pnpmSkillRef(repairSkillInvocation)
 
 /** Where the user authors the golden MCP server set, named in every MCP repair that points at it. */
@@ -589,6 +597,38 @@ const nonstandardTable: Record<NonstandardProblem, RepairRow> = {
 
 export const nonstandardRepairs: readonly Repair[] = 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: Record<WorktreeProblem, RepairRow> = {
+	'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`,
+	},
+}
+
+export const worktreeRepairs: readonly Repair[] = repairsOf(worktreeTable)
+
 /**
  * Annotated over the whole union rather than inferred, so an added problem fails to compile until
  * its section carries it.
@@ -600,6 +640,7 @@ const doctorTable: Record<DoctorProblem, RepairRow> = {
 	...configurationTable,
 	...mcpTable,
 	...nonstandardTable,
+	...worktreeTable,
 }
 
 export const doctorRepairs: readonly Repair[] = repairsOf(doctorTable)
@@ -612,7 +653,7 @@ export function repairFor(problem: DoctorProblem): Repair {
 export 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.',
+		"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.",
 } as const
 
 /** Written into the generated skill so a reader knows not to edit it in place. */
@@ -699,6 +740,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
@@ -709,6 +751,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.
 `
 }
 
@@ -988,6 +1036,23 @@ ${repairTable(nonstandardRepairs)}
 A harness directory that is a **symlink** is a projection someone already made, not configuration authored here. An artifact is reported whether or not its harness is enabled: a \`.cursorrules\` in a repository nobody opens in Cursor is still instruction content \`AGENTS.md\` does not carry, and filtering by the enabled set would hide exactly the drift worth converting.
 
 Hooks, LSP settings, and output styles are not covered yet. Their event names and shapes differ by harness with no safe projection, and half-reporting them would be worse than the silence.
+`,
+		},
+		{
+			path: 'references/worktrees.md',
+			content: `${generatedSkillWarning}
+
+# Agent worktree findings
+
+Claude Code runs a session started with \`--worktree\`, and a subagent isolated in a worktree, in a git worktree under \`.claude/worktrees/<name>/\` inside the repository. That place is by design, and no setting moves it. These findings are what a repository needs so the worktrees there do no harm. \`doctor\` checks them only where a \`.claude\` directory exists.
+
+${repairTable(worktreeRepairs)}
+
+None of these is a fault in a file the owner wrote, and none is a \`repair\` correction. Each is an offer the \`init-buddy-agent-harness\` and \`enhance\` skills make, one at a time, and write only on approval.
+
+\`worktree-base-unset\` is a choice, not an error. The default branch suits agents given unrelated tasks; \`"head"\` suits agents asked to build on the branch in front of them. Put the trade-off to the owner, and report an explicit \`"fresh"\` as their answer rather than as a finding — \`doctor\` already does.
+
+\`worktrees-scanned\` is checked for Biome only, the one tool with a confirmed failure. A repository whose ESLint, Prettier, knip, or TypeScript configuration walks the tree can hit the same thing; the skills look for those when they make the offer.
 `,
 		},
 		...harnessRegistry.map((harness) => harnessPage(harness, initReferences.has(harness.name))),

package/src/diagnose-bridges/doctor.command.ts

@@ -3,11 +3,11 @@ import type { cli } from 'clibuilder'
 import { command, t } from 'clibuilder'
 import { result } from 'clibuilder/axi'
 import { listReferences, type ReferenceListLayerRow } from 'cyber-agentkit'
-import { collapseHome, displayBinPath, fail } from '../command-output/command-output.ts'
+import { collapseHome, displayBinPath, fail, parseHarnessOption } from '../command-output/command-output.ts'
 import { type ConfigurationFinding, diagnoseConfiguration } from '../diagnose-configuration/diagnose-configuration.ts'
 import { diagnoseMcp } from '../diagnose-mcp/diagnose-mcp.ts'
 import { diagnoseNonstandard } from '../diagnose-nonstandard/diagnose-nonstandard.ts'
-import { parseHarnesses } from '../harness-registry/harness-registry.ts'
+import { diagnoseWorktrees } from '../diagnose-worktrees/diagnose-worktrees.ts'
 import { referenceLayers } from '../references/references.ts'
 import { type DiagnoseResult, diagnoseBridges } from './diagnose-bridges.ts'
 import { commandInvocation, type DoctorProblem, type RepairAction } from './doctor-guidance.ts'
@@ -82,56 +82,76 @@ export function buildDoctorReport(
 	}
 }
 
-export const doctorCommand: cli.Command = 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. */
+export async function diagnoseReport(args: {
+	root?: string | undefined
+	harness?: string | undefined
+}): Promise<DoctorReport> {
+	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, git, cli: commandInvocation }),
+			...diagnoseMcp({ root, git, cli: commandInvocation }),
+			...diagnoseNonstandard({ root, cli: commandInvocation }),
+			...diagnoseWorktrees({ root, git, cli: commandInvocation }),
+		]
+		const { layers: rows } = listReferences(
+			await referenceLayers({
 				root,
-				...(harnesses.length ? { harnesses } : {}),
-				cli: commandInvocation,
 				home,
+				platform: process.platform,
 				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(
-				await referenceLayers({
-					root,
-					home,
-					platform: process.platform,
-					env: process.env,
-				}),
-			)
-			// Resolved across every tier so each status matches `reference list`, but plugin rows are
-			// left out: what a plugin ships is its own business, not a repository setting.
-			const held = rows
-				.filter(({ tier }) => tier !== 'plugin')
-				.map(({ name, tier, path, outcome }) => ({ name, tier, path: collapseHome(home, path), status: outcome }))
-			// Exit stays 0 even with findings: a non-zero code reads to an agent as "this command
-			// is broken".
-			return result(buildDoctorReport(displayBinPath(home, process.argv[1]), diagnosis, configuration, held))
-		} catch (error) {
-			return fail(error, 'Harness diagnosis failed.')
-		}
+			}),
+		)
+		// Resolved across every tier so each status matches `reference list`, but plugin rows are
+		// left out: what a plugin ships is its own business, not a repository setting.
+		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.')
+	}
+}
+
+export const doctorCommand: cli.Command = 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',
+		},
+	],
+	// Exit stays 0 even with findings: a non-zero code reads to an agent as "this command
+	// is broken".
+	async run(args) {
+		return result(await diagnoseReport(args))
 	},
 })

package/src/diagnose-bridges/git-bridge-state.ts

@@ -37,6 +37,11 @@ export class GitBridgeState {
 		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(): boolean {
+		return this.repoRootPrefix !== undefined
+	}
+
 	/** The skip-worktree bit is a hint some checkouts clear, so it is verified rather than assumed. */
 	trackingOf(path: string): TrackingState {
 		if (this.repoRootPrefix === undefined) return 'untracked'

package/src/diagnose-worktrees/diagnose-worktrees.ts

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { type RepairAction, repairFor, type WorktreeProblem } from '../diagnose-bridges/doctor-guidance.ts'
+import type { GitBridgeState } from '../diagnose-bridges/git-bridge-state.ts'
+import { isRecord } from '../is-record/is-record.ts'
+
+/**
+ * The agent-worktree half of `doctor`: what a repository lacks for the git worktrees Claude Code
+ * creates inside it under `.claude/worktrees/`. Read-only.
+ */
+export type WorktreeFinding = {
+	/** Repository-relative path the finding is about. */
+	path: string
+	problem: WorktreeProblem
+	detail: string
+	/** Always an empty `command`: each repair is an offer the owner approves. */
+	repair: RepairAction
+}
+
+export type DiagnoseWorktreesOptions = {
+	root: string
+	git: GitBridgeState
+	/** How to name this tool in the repair commands. */
+	cli: string
+}
+
+/** The trailing slash matters: `git check-ignore` matches a directory rule only against a directory path. */
+export const worktreeDirectory = '.claude/worktrees/'
+
+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: string): unknown {
+	try {
+		return JSON.parse(readFileSync(path, 'utf8'))
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * 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.
+ */
+export function diagnoseWorktrees({ root, git, cli }: DiagnoseWorktreesOptions): WorktreeFinding[] {
+	if (!existsSync(join(root, '.claude'))) return []
+
+	const findings: WorktreeFinding[] = []
+	const add = (path: string, problem: WorktreeProblem) => {
+		const { detail, repair } = repairFor(problem)
+		findings.push({ path, problem, detail, repair: repair({ file: path }, cli) })
+	}
+
+	if (git.isRepository() && !git.isIgnored(worktreeDirectory)) 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'] : undefined
+	// An explicit `"fresh"` is the owner's choice; only an unset key is reported.
+	if (!isRecord(worktree) || worktree['baseRef'] === undefined) add(claudeSettings, 'worktree-base-unset')
+
+	return findings
+}

package/src/governance-overrides/governance.command.ts

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os'
 import type { cli } from 'clibuilder'
 import { command, t } from 'clibuilder'
-import { CliError, document, exitCodes, result } from 'clibuilder/axi'
+import { CliError, document, ref, result } from 'clibuilder/axi'
 import { collapseHome, fail } from '../command-output/command-output.ts'
 import {
 	type GovernanceLayer,
@@ -67,6 +67,7 @@ export const governanceListCommand: cli.Command = command({
 		root: rootOption,
 		'overrides-only': overridesOnlyOption,
 	},
+	examples: [{ command: 'buddy-agent-harness governance list', description: 'List the governances the layers hold' }],
 	run(args: Args) {
 		process.stderr.write(GOVERNANCE_DEPRECATED)
 		try {
@@ -98,6 +99,9 @@ export const governanceShowCommand: cli.Command = command({
 		root: rootOption,
 		'overrides-only': overridesOnlyOption,
 	},
+	examples: [
+		{ command: 'buddy-agent-harness governance show skill-design', description: 'Print one governance document' },
+	],
 	run(args: Args & { name: string }) {
 		const format = this.format
 		process.stderr.write(GOVERNANCE_DEPRECATED)
@@ -105,15 +109,16 @@ export const governanceShowCommand: cli.Command = command({
 			const name = parseGovernanceName(args.name)
 			const found = resolveGovernance(name, layersFor(args))
 			if (!found) {
-				// stderr, not stdout — a caller piping the document off stdout must never see this
-				// prose
-				// mixed in.
-				process.stderr.write(
+				throw new CliError(
 					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`,
+						? `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'),
+					},
 				)
-				throw CliError.reported(exitCodes.error)
 			}
 			const report: GovernanceShowReport = {
 				name: found.name,

package/src/index.ts

@@ -56,6 +56,7 @@ export type {
 	InstructionProblem,
 	McpProblem,
 	Repair,
+	WorktreeProblem,
 } from './diagnose-bridges/doctor-guidance.ts'
 export {
 	bridgeRepairs,

package/src/initialize-harnesses/init.command.ts

@@ -1,10 +1,9 @@
 import type { cli } from 'clibuilder'
 import { command, t } from 'clibuilder'
 import { result } from 'clibuilder/axi'
-import { fail } from '../command-output/command-output.ts'
+import { fail, parseHarnessOption } from '../command-output/command-output.ts'
 import { doctorCommand } from '../diagnose-bridges/doctor.command.ts'
 import { governanceCommand } from '../governance-overrides/governance.command.ts'
-import { parseHarnesses } from '../harness-registry/harness-registry.ts'
 import { referenceCommand } from '../references/references.ts'
 import { parseForce } from '../skill-projection/skill-projection.ts'
 import { initializeHarnesses } from './initialize-harnesses.ts'
@@ -31,9 +30,16 @@ export const initCommand: cli.Command = 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(),

package/src/project-mcp/mcp.command.ts

@@ -1,6 +1,6 @@
 import type { cli } from 'clibuilder'
 import { command, t } from 'clibuilder'
-import { CliError, exitCodes, result } from 'clibuilder/axi'
+import { CliError, empty, ref, result } from 'clibuilder/axi'
 import { fail } from '../command-output/command-output.ts'
 import { GitBridgeState } from '../diagnose-bridges/git-bridge-state.ts'
 import { projectionRecordPath } from '../diagnose-mcp/mcp-baseline.ts'
@@ -32,6 +32,10 @@ export const mcpProjectCommand: cli.Command = 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()
@@ -40,16 +44,18 @@ export const mcpProjectCommand: cli.Command = command({
 			if (plan.kind === 'unreadable') {
 				// Position only: the parser's message quotes the line, and that line may hold a credential.
 				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',
-				} satisfies ProjectionReport)
+				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: ProjectionReport = {
 				golden: goldenSetPath,

package/src/reconcile-mcp/reconcile.command.ts

@@ -1,6 +1,6 @@
 import type { cli } from 'clibuilder'
 import { command, t } from 'clibuilder'
-import { CliError, exitCodes, result } from 'clibuilder/axi'
+import { CliError, empty, ref, result } from 'clibuilder/axi'
 import { fail } from '../command-output/command-output.ts'
 import { GitBridgeState } from '../diagnose-bridges/git-bridge-state.ts'
 import { projectionRecordPath } from '../diagnose-mcp/mcp-baseline.ts'
@@ -30,6 +30,10 @@ export const mcpReconcileCommand: cli.Command = 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()
@@ -38,20 +42,22 @@ export const mcpReconcileCommand: cli.Command = command({
 			if (plan.kind === 'unreadable') {
 				// Position only: the parser's message quotes the line, and that line may hold a credential.
 				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 === 'rejected') {
-				process.stderr.write(`error: nothing written.\n${plan.reasons.map((reason) => `- ${reason}\n`).join('')}`)
-				throw CliError.reported(exitCodes.error)
+				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 result({
-					golden: `0 servers — no golden set at ${goldenSetPath}`,
-					mode: 'nothing to reconcile into',
-					fields: '0 fields',
-					record: 'not written',
-				} satisfies ReconcileReport)
+				return empty(`0 servers — no golden set at ${goldenSetPath}`, {
+					help: `Create ${goldenSetPath} first; there is nothing to reconcile into.`,
+				})
 			}
 			const report: ReconcileReport = {
 				golden: goldenSetPath,

package/src/references/references.ts

@@ -25,4 +25,5 @@ export function referenceLayers({
 
 export const referenceCommand: cli.Command = createReferenceCommand({
 	plugin: { name: PACKAGE_PLUGIN, root: dirname(packageGovernancesDir()) },
+	path: 'buddy-agent-harness reference',
 })