buddy-agent-harness 0.10.0 → 0.12.0

package/dist/cli.mjs

@@ -2,7 +2,7 @@ import { a as __toESM, i as __require, n as unpartial, r as __commonJSMin, t as
 import { createRequire } from "node:module";
 import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, parse, posix, relative, resolve, sep } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir, platform } from "node:os";
 import { execFileSync } from "node:child_process";
 //#region ../../node_modules/.pnpm/clibuilder@10.1.0/node_modules/clibuilder/esm/argv.js
@@ -15651,15 +15651,6 @@ function resolveOptions(options) {
 }
 //#endregion
 //#region src/is-record/is-record.ts
-/**
-* Whether a value is a record: an object with named keys, and not an array.
-*
-* Everything this package reads is a file someone else wrote — a golden MCP set, a harness config,
-* a projection record — so every parse lands on `unknown` and every reader narrows it here before
-* asking for a key. Four modules had their own copy of the same three clauses; a predicate that
-* decides what counts as a parsed object is one fact, and a copy of it that drifts changes what a
-* file is read to say.
-*/
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -15679,6 +15670,13 @@ function parseFormat(value) {
 function writeResult(value, format) {
 	process.stdout.write(`${encodeResult(value, format)}\n`);
 }
+/**
+* Writes a document exactly as read, bypassing the encoders — a Markdown body run through TOON or
+* the text renderer comes back as one escaped line. A command writes one or the other, never both.
+*/
+function writeDocument(content) {
+	process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+}
 function encodeResult(value, format) {
 	if (format === "json") return JSON.stringify(value);
 	return format === "text" ? renderText(value) : encode(value);
@@ -15686,18 +15684,13 @@ function encodeResult(value, format) {
 function cell(value) {
 	return value === void 0 ? "" : String(value);
 }
-/** A header row plus one row per record, every column padded to its widest cell. */
 function table(rows) {
 	const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))];
 	const widths = columns.map((column) => Math.max(column.length, ...rows.map((row) => cell(row[column]).length)));
 	const line = (values) => `  ${values.map((value, index) => value.padEnd(widths[index])).join("  ")}`.trimEnd();
 	return [line(columns), ...rows.map((row) => line(columns.map((column) => cell(row[column]))))];
 }
-/**
-* The same result rendered for a person rather than for an agent: scalars as `key: value`, records
-* as an aligned table, and everything else as a bulleted list. TOON stays the default because it is
-* what an agent parses; this is for reading over someone's shoulder.
-*/
+/** Renders for a person, not an agent — TOON stays the default since that's what an agent parses. */
 function renderText(value) {
 	const blocks = Object.entries(value).map(([key, item]) => {
 		if (!Array.isArray(item)) return [`${key}: ${isRecord(item) ? JSON.stringify(item) : String(item)}`];
@@ -15710,19 +15703,19 @@ function renderText(value) {
 		return previous && (previous.length > 1 || block.length > 1) ? ["", ...block] : block;
 	}).join("\n");
 }
-/** AXI §10: the executable's absolute path, with the user's home directory collapsed to `~`. */
-function binPath(home, executable) {
-	if (!executable) return "buddy-agent-harness";
-	return home && executable.startsWith(home + sep) ? `~${executable.slice(home.length)}` : executable;
+/**
+* AXI §10: collapses the home directory to `~` so a path in a report is portable to another
+* machine.
+*/
+function collapseHome(home, path) {
+	return home && path.startsWith(home + sep) ? `~${path.slice(home.length)}` : path;
+}
+function displayBinPath(home, executable) {
+	return executable ? collapseHome(home, executable) : "buddy-agent-harness";
 }
 //#endregion
 //#region src/dep-plugins/dep-plugins.ts
-/**
-* Marketplace names generic enough that two repositories are likely to pick the same one. The
-* collision is silent and costly: registering a second marketplace under a name already in use
-* replaces the first, and the install that follows reports "already installed" and does nothing —
-* so the repository silently runs the other one's plugin versions.
-*/
+/** Generic marketplace names: a second registration under one of these replaces the first, silently. */
 const GENERIC_NAMES = /* @__PURE__ */ new Set([
 	"deps",
 	"dependencies",
@@ -15736,19 +15729,15 @@ function isGenericName(name) {
 	return GENERIC_NAMES.has(name.toLowerCase());
 }
 /**
-* A marketplace name derived from the consuming package's own name, so two repositories do not
-* collide by default. A scope is folded into the name rather than dropped (`@acme/web` → `acme-web`)
-* because the unscoped half is the part most likely to repeat across organizations.
+* Folds a scope into the name (`@acme/web` → `acme-web`) rather than dropping it — the unscoped
+* part collides more often.
 */
 function marketplaceName(packageName) {
 	return packageName.replace(/^@/, "").replace(/\//g, "-").replace(/[^a-zA-Z0-9-_.]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "agent-plugins";
 }
 /**
-* Dependency names a repository declares, both runtime and development.
-*
-* Development dependencies are included on purpose: a plugin that supplies a project's testing or
-* release workflow is a development dependency, and excluding them would drop most of the cases this
-* exists for. Transitive dependencies are never included — see `resolve.ts`.
+* Includes `devDependencies` — a plugin can supply a project's testing or release workflow.
+* Transitive dependencies are excluded; see `resolve.ts`.
 */
 function declaredDependencies(manifest) {
 	if (!manifest || typeof manifest !== "object") return [];
@@ -15762,12 +15751,8 @@ function declaredDependencies(manifest) {
 	return [...names].sort();
 }
 /**
-* The catalog is derived in full on every run and never merged into what is already on disk. That is
-* what makes the three cases a consumer cares about — a plugin added, a plugin removed, a version
-* moved — fall out of regeneration instead of needing reconciliation logic of their own.
-*
-* Entries are sorted by name so that a regeneration whose inputs did not change produces a
-* byte-identical file, which is what lets a check mode compare rather than interpret.
+* Derived in full every run, never merged with what's on disk. Entries are sorted so unchanged
+* inputs serialize identically, which `--check` relies on.
 */
 function buildCatalog({ name, owner, plugins }) {
 	const entries = [...plugins].sort((a, b) => a.plugin.localeCompare(b.plugin)).map(({ plugin, package: pkg, version, description }) => {
@@ -15792,22 +15777,12 @@ function buildCatalog({ name, owner, plugins }) {
 		plugins: entries
 	};
 }
-/** Serialized the way the repository formats JSON, with the trailing newline a text file needs. */
+/** Includes the trailing newline. */
 function serializeCatalog(catalog) {
 	return `${JSON.stringify(catalog, null, "	")}\n`;
 }
 //#endregion
 //#region src/dep-plugins/resolve.ts
-/**
-* Locating a declared dependency on disk, and reading the plugin manifest it may ship.
-*
-* Resolution rather than scanning. Walking `node_modules` finds transitive dependencies nobody
-* vetted, and a skill or plugin is instruction text that steers an agent — an unvetted transitive
-* dependency is a supply-chain surface, not a convenience. Asking the module resolver where a
-* *declared* dependency lives answers the question that was actually asked, and it is correct under
-* npm, pnpm, yarn with the node-modules linker, and bun alike, because all four put a real directory
-* on disk. Only Yarn PnP does not, and it is reported rather than guessed at.
-*/
 function readJson$1(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
@@ -15815,10 +15790,6 @@ function readJson$1(path) {
 		return;
 	}
 }
-/**
-* Every ancestor `node_modules/<pkg>` from `startDir` upward. The fallback path only — see
-* {@link packageDir}.
-*/
 function ancestorCandidates(startDir, pkg) {
 	const segments = pkg.split("/");
 	const candidates = [];
@@ -15832,17 +15803,8 @@ function ancestorCandidates(startDir, pkg) {
 	return candidates;
 }
 /**
-* The directory a declared dependency was installed into, or `undefined`.
-*
-* Two mechanisms, in order, because neither alone is sufficient:
-*
-* 1. **`require.resolve('<pkg>/package.json')`, anchored at the declaring manifest.** The anchor
-*    matters: under pnpm's isolated store only the package that declares a dependency can resolve it,
-*    so resolving from a workspace root would miss what a workspace member declared.
-* 2. **A walk up `node_modules`.** Roughly one package in seven declares an `exports` map without a
-*    `./package.json` entry, and those refuse the first mechanism with `ERR_PACKAGE_PATH_NOT_EXPORTED`
-*    however plainly they are installed. Resolving a deeper file instead is not an escape — the same
-*    map blocks that too.
+* Anchored at the declaring manifest (required for pnpm's isolation), then falls back to a
+* `node_modules` walk — an `exports` map without a `./package.json` entry blocks the first.
 */
 function packageDir(pkg, fromManifest) {
 	try {
@@ -15851,16 +15813,7 @@ function packageDir(pkg, fromManifest) {
 	} catch {}
 	for (const candidate of ancestorCandidates(dirname(fromManifest), pkg)) if (existsSync(join(candidate, "package.json"))) return candidate;
 }
-/**
-* Reads the plugin a dependency ships, if it ships one.
-*
-* The version comes from the dependency's own `package.json` rather than from a lockfile. It is the
-* same number — the version actually installed — and reading it needs no knowledge of which of the
-* four lockfile formats this repository uses.
-*
-* A manifest at the package root is what the Agent Plugins Specification pins, and it is the form a
-* harness accepts as a marketplace source without any vendor-specific manifest alongside it.
-*/
+/** A manifest lives at the package root — the Agent Plugins Specification's pinned location. */
 function readDepPlugin(pkg, fromManifest) {
 	const dir = packageDir(pkg, fromManifest);
 	if (!dir) return {
@@ -15904,10 +15857,8 @@ function readDepPlugin(pkg, fromManifest) {
 	};
 }
 /**
-* True when the process is running under Yarn's Plug'n'Play resolver, where packages live inside zip
-* archives rather than as directories. A marketplace source must be a real directory and an npm
-* source must be installable, so a PnP project needs `nodeLinker: node-modules` or the affected
-* dependencies unplugged. Detected rather than worked around, so the report can say so.
+* True under Yarn PnP, where packages live in zip archives rather than directories — nothing here
+* has an installable directory.
 */
 function isPnp() {
 	return Boolean(process.versions["pnp"]);
@@ -15915,35 +15866,14 @@ function isPnp() {
 //#endregion
 //#region src/dep-plugins/generate.ts
 /**
-* Deriving a repository's dependency-plugin catalog, and deciding whether what is on disk matches.
-*/
-/**
-* The catalog's home, relative to the repository root.
-*
-* Under this tool's own directory, beside the other files it owns there — the same place as
-* `mcp.toml` and `mcp.projected.json`, and the same shape as `.agents/repobuddy/` and
-* `.agents/cyberlegion/`. A directory named for what it holds rather than for who writes it would be
-* a second convention in a tree that already has one.
-*
-* Not the repository root's `.claude-plugin/`, which is where a repository publishes its *own*
-* plugins for its *own* consumers. Merging the two would leak every dependency-provided plugin into
-* what a consumer sees on adding the published marketplace, and no harness has a notion of a private
-* catalog entry to prevent that. Being a separate directory also makes this one a marketplace root
-* in its own right, which is what lets its entries be resolved without reaching outside it.
+* Not the repository root's `.claude-plugin/` — that's the repo's own published catalog; merging
+* would leak dependency plugins into it.
 */
 const CATALOG_DIR = join(".agents", "buddy-agent-harness");
 const CATALOG_PATH = join(CATALOG_DIR, ".claude-plugin", "marketplace.json");
 function readManifest(path) {
 	return JSON.parse(readFileSync(path, "utf8"));
 }
-/**
-* Derives the catalog from the repository's declared dependencies.
-*
-* Derived in full every time. A plugin newly added to `package.json` appears, one removed disappears,
-* and a version that moved follows — all three without a line of reconciliation logic, because there
-* is nothing to reconcile against. That is the same rule the vendor manifests already follow: the
-* artifact is derived, never authored.
-*/
 function deriveCatalog(root) {
 	const manifestPath = join(root, "package.json");
 	const manifest = readManifest(manifestPath);
@@ -15972,11 +15902,8 @@ function deriveCatalog(root) {
 	};
 }
 /**
-* What writing the catalog would do, without touching the disk.
-*
-* Comparing the serialized form rather than the parsed one is deliberate: a byte comparison is what
-* lets a check mode be a comparison instead of an interpretation, and `buildCatalog` sorts its
-* entries so that unchanged inputs serialize identically.
+* Compares serialized bytes, not parsed values — that's what makes `--check` a comparison rather
+* than an interpretation.
 */
 function catalogStatus(root, catalog) {
 	let current;
@@ -15988,7 +15915,7 @@ function catalogStatus(root, catalog) {
 	if (current === serializeCatalog(catalog)) return "unchanged";
 	return current === void 0 ? "created" : "updated";
 }
-/** Writes the catalog, reporting whether it moved. A write that would change nothing writes nothing. */
+/** A write that would change nothing writes nothing. */
 function writeCatalog(root, catalog) {
 	const outcome = catalogStatus(root, catalog);
 	if (outcome === "unchanged") return outcome;
@@ -15999,31 +15926,6 @@ function writeCatalog(root, catalog) {
 }
 //#endregion
 //#region src/dep-plugins/harness-plugins.ts
-/**
-* What each harness does with a marketplace catalog, and how to read what it currently has.
-*
-* The runtimes diverge more than they look, and every difference below was established by running
-* the shipped CLI rather than by reading a document:
-*
-* - **Claude Code** refreshes with `plugin update`; re-running `plugin install` is a no-op that
-*   reports "already installed" and leaves the stale copy in place. Every verb defaults to user
-*   scope, so each one has to name `--scope project` explicitly.
-* - **Codex** has no update verb and no scope. Re-running `plugin add` re-reads the catalog and
-*   replaces the cached copy, so the same command installs and refreshes. It records no version in
-*   its config — the installed version is only in the cache directory's name.
-* - **Copilot CLI** accepts a path source but **rejects an `npm` source**, so it cannot consume this
-*   catalog at all. See {@link COPILOT_LIMITATION}.
-* - **Cursor** exposes no plugin subcommand from a terminal.
-*
-* A consumer should not have to know any of that, which is why it is here rather than in a document.
-*/
-/**
-* Why Copilot CLI is absent from the table. Recorded rather than dropped, so the reason travels with
-* the code: `copilot plugin marketplace add` rejects this catalog with
-* `Invalid marketplace.json: plugins.0.source: Invalid input`, while the same catalog with a
-* `./path` source is accepted. Supporting it needs a second, path-sourced catalog — and a path source
-* cannot escape its marketplace root, which is the constraint the `npm` source was chosen to avoid.
-*/
 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) {
 	try {
@@ -16039,19 +15941,9 @@ function directories(path) {
 		return [];
 	}
 }
-/**
-* `CLAUDE_CONFIG_DIR` wins where set, which is also what keeps a test off a developer's real
-* configuration.
-*/
 function claudeConfigDir(home, env = process.env) {
 	return env["CLAUDE_CONFIG_DIR"] || join(home, ".claude");
 }
-/**
-* Reads what Claude Code has installed.
-*
-* The file keys each plugin by `<plugin>@<marketplace>` and holds an *array* per key, because the
-* same plugin can be installed at more than one scope and, at project scope, once per project.
-*/
 function readClaudeState(configDir) {
 	const installedFile = readJson(join(configDir, "plugins", "installed_plugins.json"));
 	const installed = [];
@@ -16090,16 +15982,10 @@ function readClaudeState(configDir) {
 const claudeCode = {
 	name: "claude-code",
 	scoped: true,
-	present: (home, env = process.env) => existsSync(claudeConfigDir(home, env)),
+	installedOnMachine: (home, env = process.env) => existsSync(claudeConfigDir(home, env)),
 	state: (home, env = process.env) => readClaudeState(claudeConfigDir(home, env)),
 	register: (catalogDir) => `claude plugin marketplace add ./${catalogDir} --scope project`,
 	install: (id) => `claude plugin install ${id} --scope project`,
-	/**
-	* Not `install`: re-running that on an already-installed plugin changes nothing and says so, which
-	* reads as success. `--scope project` is required rather than cosmetic — every verb defaults to
-	* user scope, so an update omitting it fails with "not installed at scope user" against a plugin
-	* that is plainly installed.
-	*/
 	update: (id) => `claude plugin update ${id} --scope project`,
 	uninstall: (id) => `claude plugin uninstall ${id} --scope project`,
 	refreshMarketplace: (marketplace) => `claude plugin marketplace update ${marketplace}`
@@ -16107,16 +15993,6 @@ const claudeCode = {
 function codexHome(home, env = process.env) {
 	return env["CODEX_HOME"] || join(home, ".codex");
 }
-/**
-* Reads what Codex has installed.
-*
-* The installed version comes from the cache layout, `plugins/cache/<marketplace>/<plugin>/<version>`,
-* because Codex's `config.toml` records only that a plugin is enabled — never which version.
-*
-* Registered marketplaces are read from `config.toml` by scanning for its `[marketplaces.<name>]`
-* tables. A deliberately narrow read rather than a TOML parser: only two keys are needed, and the
-* cost of being wrong is a report that suggests re-registering, which is harmless to re-run.
-*/
 function readCodexState(home) {
 	const cacheRoot = join(home, "plugins", "cache");
 	const installed = [];
@@ -16157,30 +16033,20 @@ function readCodexState(home) {
 }
 const runtimes = [claudeCode, {
 	name: "codex",
-	/**
-	* Codex installs into `CODEX_HOME` with no notion of scope, so one install is shared by every
-	* repository on the machine. Two repositories whose catalogs share a marketplace name cannot be
-	* told apart here, which is what makes the marketplace name derived from the package name matter.
-	*/
 	scoped: false,
-	present: (home, env = process.env) => existsSync(codexHome(home, env)),
+	installedOnMachine: (home, env = process.env) => existsSync(codexHome(home, env)),
 	state: (home, env = process.env) => readCodexState(codexHome(home, env)),
 	register: (catalogDir) => `codex plugin marketplace add ./${catalogDir}`,
 	install: (id) => `codex plugin add ${id}`,
-	/** No update verb: re-running `add` re-reads the catalog and replaces the cached copy. */
 	update: (id) => `codex plugin add ${id}`,
 	uninstall: (id) => `codex plugin remove ${id}`,
-	/** `marketplace upgrade` refreshes git snapshots only; `add` already re-reads a local catalog. */
 	refreshMarketplace: () => ""
 }];
 //#endregion
 //#region src/dep-plugins/reconcile.ts
 /**
-* Installs belonging to this repository and this catalog.
-*
-* On a scoped runtime a user-scoped install is deliberately excluded rather than counted: it is
-* shared with every other repository on the machine, so treating it as satisfying this repository's
-* catalog would let one project's pin silently stand in for another's.
+* Excludes a user-scoped install on a scoped runtime — it's shared machine-wide, so it can't
+* satisfy this repository's catalog alone.
 */
 function ours(installed, marketplace, root, scoped) {
 	const suffix = `@${marketplace}`;
@@ -16230,7 +16096,6 @@ function reconcile({ catalog, catalogDir, root, installed, marketplaces, scoped
 }
 //#endregion
 //#region src/dep-plugins/dep-plugins.command.ts
-/** The command that performs one action, so a reader is not left to look the verb up per runtime. */
 function commandFor(runtime, action, marketplace) {
 	switch (action.kind) {
 		case "register": return runtime.register(CATALOG_DIR);
@@ -16243,11 +16108,6 @@ function commandFor(runtime, action, marketplace) {
 		case "uninstall": return runtime.uninstall(action.subject);
 	}
 }
-/**
-* Notes name the conditions a caller cannot see from the entry list and would otherwise discover as a
-* failure later — a dependency that is declared but absent, a marketplace name two repositories are
-* likely to share, a resolver under which no dependency has a directory at all.
-*/
 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.");
@@ -16281,7 +16141,7 @@ const depPluginsCommand = command({
 			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.present(home));
+			const detected = runtimes.filter((candidate) => candidate.installedOnMachine(home));
 			const harness = [];
 			const actions = [];
 			for (const runtime of detected) {
@@ -16329,10 +16189,7 @@ const depPluginsCommand = command({
 });
 //#endregion
 //#region src/diagnose-bridges/directory-files.ts
-/**
-* Every file below `directory`, as paths relative to it, POSIX-separated and sorted. A directory
-* that does not exist reads as empty: `doctor` never creates one to look at it.
-*/
+/** A directory that does not exist reads as empty: `doctor` never creates one to look at it. */
 function filesUnder(directory) {
 	try {
 		return readdirSync(directory, {
@@ -16345,36 +16202,18 @@ function filesUnder(directory) {
 }
 //#endregion
 //#region src/harness-registry/harness-registry.ts
-/**
-* The two scopes disagree in general, and a single answer per harness could only record one of them:
-* Copilot CLI is `.github/skills` in a repository and `~/.copilot` for the user. Claude Code is the
-* only harness that needs a skills projection, and it needs one at both scopes. Codex, Cursor,
-* Copilot CLI, Gemini CLI, and Devin Desktop read `.agents/skills` themselves and are never
-* projected into.
-*
-* Gemini CLI carried a `.gemini/skills` projection until E-GEM-02: it reads the `.agents/skills`
-* alias at project scope too, where that alias takes precedence over `.gemini/skills`. It still
-* needs an instruction bridge, which is a separate axis and unaffected.
-*
-* Instruction bridges are recorded at project scope only. The user-scope equivalents exist, but
-* nothing writes or reads them yet: `init` works inside a repository, and so does `doctor`.
-*
-* `windsurf` is the former name of Devin Desktop, rebranded 2026-06-02. It is retained as a
-* deprecated alias: Devin still scans the legacy `.windsurf/skills` path, so its projection keeps
-* working, but new repositories should enable `devin-desktop` and have nothing written for them.
-*
-* See `.research/agentic-configuration-standards/` for the per-harness sources.
-*/
+/** See `.research/agentic-configuration-standards/` for the per-harness sources. */
 const harnessRegistry = [
 	{
 		name: "claude-code",
 		project: {
 			detect: ".claude",
 			skillsDirectory: ".claude/skills",
-			instructionBridge: {
-				kind: "import",
-				path: "CLAUDE.md"
-			},
+			shadowedBy: [
+				"CLAUDE.md",
+				".claude/CLAUDE.md",
+				"CLAUDE.local.md"
+			],
 			mcpConfig: {
 				path: ".mcp.json",
 				key: "mcpServers",
@@ -16532,13 +16371,8 @@ function isHarnessName(value) {
 	return harnessNames.has(value);
 }
 /**
-* The `--harness` option, as names this registry knows. Both commands take the option and neither
-* owns what a name means, so the parse lives beside the list it validates against: a harness added
-* to the registry is accepted by both commands with nothing else to change, and the rejection reads
-* the same either way.
-*
-* An unknown name throws rather than being dropped. A caller that asked for a harness by name and
-* got a report about the two default ones has been told the wrong thing about their repository.
+* 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);
@@ -16571,9 +16405,8 @@ function locatorText({ file, server, field, position }) {
 //#endregion
 //#region src/diagnose-bridges/doctor-guidance.ts
 /**
-* A table as the list `doctor` reports, in the order it was written. The keys of a
-* `Record<P, RepairRow>` are `P` by construction, which is what the assertion says; nothing here
-* claims a row exists.
+* Turns a table into the list `doctor` reports; the cast is safe because a `Record<P, RepairRow>`'s
+* keys are `P` by construction.
 */
 function repairsOf(table) {
 	return Object.entries(table).map(([problem, row]) => ({
@@ -16581,19 +16414,11 @@ function repairsOf(table) {
 		...row
 	}));
 }
-/** How the command names itself. */
 const commandInvocation = "buddy-agent-harness";
-/**
-* How the skill hands a repair to `repair`. Bridge and instruction repairs go to `init`, which
-* writes both kinds of bridge in the first place; configuration that is present and wrong goes
-* here, because no `init` flag corrects a file the user already wrote.
-*/
 const repairSkillInvocation = "/buddy-agent-harness:repair";
-/** How the skill hands a repair back to `init`. */
-const initSkillInvocation = "/buddy-agent-harness:init";
+const initSkillInvocation = `/buddy-agent-harness:init-buddy-agent-harness`;
 /** 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";
-/** The skills bridges, reported in `bridges`. */
 const bridgeTable = {
 	"no-canonical": {
 		detail: "the canonical skill directory does not exist, so no bridge can resolve",
@@ -16670,19 +16495,17 @@ const bridgeTable = {
 };
 repairsOf(bridgeTable);
 /**
-* The instruction bridges, reported in `instructions`. Every repair is the `init` skill: these are
-* files a person wrote, or files carrying content beside the bridge, and deciding what to preserve
-* while restoring the bridge is judgment no flag carries. `repair` therefore names the skill in
-* both places rather than pretending a shell command exists.
+* Everything reported in `instructions`: bridges into `AGENTS.md` and the files that suppress it.
+* Every repair is the `init-buddy-agent-harness` skill's judgment, never a shell command.
 */
 const instructionTable = {
 	"no-instructions": {
-		detail: "no AGENTS.md at the repository root, so every instruction bridge points at nothing",
+		detail: "no AGENTS.md at the repository root, so the instructions this repository has reach one harness at most",
 		repair: () => ({
 			command: "",
-			instruction: `hand this to \`${initSkillInvocation}\`, which derives AGENTS.md and the bridges to it`
+			instruction: `hand this to \`${initSkillInvocation}\`, which consolidates what the repository has into AGENTS.md, or derives it`
 		}),
-		skillRepair: () => `run \`${initSkillInvocation}\`, which derives AGENTS.md and the bridges to it`
+		skillRepair: () => `run \`${initSkillInvocation}\`, which consolidates or derives AGENTS.md`
 	},
 	"instructions-missing": {
 		detail: "no instruction bridge at this path — the harness reads none of AGENTS.md",
@@ -16700,6 +16523,22 @@ const instructionTable = {
 		}),
 		skillRepair: () => `run \`${initSkillInvocation}\`, which adds the bridge without discarding what the file already says`
 	},
+	"instructions-shadowing": {
+		detail: "this file suppresses the AGENTS.md beside it — the harness reads this instead, and none of AGENTS.md",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `hand ${file} to \`${initSkillInvocation}\`, which consolidates what it says into AGENTS.md, or adds an @AGENTS.md import above it where the file has to stay`
+		}),
+		skillRepair: () => `run \`${initSkillInvocation}\`, which consolidates the file into AGENTS.md or imports AGENTS.md from it`
+	},
+	"instructions-superseded": {
+		detail: "a bridge from before the harness read AGENTS.md itself — it still works, and nothing needs it",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `remove ${file}, or keep it for sessions that cannot read AGENTS.md directly — \`${initSkillInvocation}\` offers the choice`
+		}),
+		skillRepair: () => `run \`${initSkillInvocation}\`, which offers to remove it`
+	},
 	"instructions-unreadable": {
 		detail: "the settings file does not parse, so the harness reads none of it",
 		repair: ({ file }) => ({
@@ -16710,10 +16549,6 @@ const instructionTable = {
 	}
 };
 repairsOf(instructionTable);
-/**
-* Configuration that is present and wrong. Detected here like everything else, but repaired by the
-* `repair` skill rather than by `init` — which is why it is a section of its own.
-*/
 const configurationTable = {
 	"deprecated-harness": {
 		detail: "a projection under a harness name that has been superseded — the replacement reads .agents/skills natively and needs no projection at all",
@@ -16750,13 +16585,8 @@ const configurationTable = {
 };
 repairsOf(configurationTable);
 /**
-* The golden MCP server set against the harness copies of it.
-*
-* Every repair names a **locator** rather than a file — `.cursor/mcp.json#servers.linear.command` —
-* because a file holding twenty servers is not an address. The locator never carries a value: not
-* a whole one, and not a prefix. `doctor` is safe to run from a session-start hook, so a value it
-* echoes lands in agent context on every session and from there into transcripts, and `sk-ab…`
-* leaks into exactly the same place the whole string would.
+* Every repair names a locator rather than a file, and the locator never carries a credential
+* value.
 */
 const mcpTable = {
 	"mcp-golden-unreadable": {
@@ -16842,13 +16672,8 @@ const mcpTable = {
 };
 repairsOf(mcpTable);
 /**
-* Configuration only one harness can read. Every repair here is a **conversion**, and every one of
-* them is the `init` skill's: consolidating what a repository already has is exactly its remit, and
-* the content is the user's, so it is offered and never written on sight. `repair` owns none of
-* them — it corrects configuration that is wrong, and none of this is wrong.
-*
-* `nonstandard-subagent` is the exception that names no owner. There is no cross-harness subagent
-* format to convert to, so the honest report is that the gap exists, not a repair that cannot run.
+* Every repair here is a conversion owned by the `init-buddy-agent-harness` skill, except
+* `nonstandard-subagent`, which names no owner since no cross-harness format exists to convert to.
 */
 const nonstandardTable = {
 	"nonstandard-instructions": {
@@ -16894,8 +16719,8 @@ const nonstandardTable = {
 };
 repairsOf(nonstandardTable);
 /**
-* All five sections, in the order `doctor` reports them. Annotated over the whole union rather than
-* inferred, so a problem added to any of the four fails here too if its section was left alone.
+* Annotated over the whole union rather than inferred, so an added problem fails to compile until
+* its section carries it.
 */
 const doctorTable = {
 	...bridgeTable,
@@ -16917,12 +16742,10 @@ function repairFor(problem) {
 const canonicalSkills = ".agents/skills";
 const localOverride = "AGENTS.local.md";
 /**
-* The two frontmatter faults that make a harness skip a skill outright, per
-* `skills/init/references/frontmatter.md`: YAML that does not parse, and a missing `description`.
-* A `name` that mismatches the directory is a warning and still loads, so it is not reported here.
-*
-* The unquoted colon is the documented cause of the first, and is checked directly rather than by
-* parsing YAML: the package ships no parser, and a targeted check names the actual fault.
+* The two frontmatter faults that make a harness skip a skill outright (see
+* `skills/init-buddy-agent-harness/references/frontmatter.md`): unparseable YAML, and a missing
+* `description`. A name/directory mismatch only warns and still loads, so it's not checked here.
+* Checked directly for an unquoted colon rather than by parsing YAML — the package ships no parser.
 */
 function frontmatterFault(body) {
 	const block = /^---\n([\s\S]*?)\n---/.exec(body);
@@ -16932,10 +16755,8 @@ function frontmatterFault(body) {
 	if (!/^(['"]).*\1$/.test(value) && /:\s/.test(value)) return "unparseable";
 }
 /**
-* Unlike `diagnoseBridges`, this takes no harness preference. Every check here requires the
-* projection to exist on disk, and a projection cannot exist without its harness's detection
-* directory — which selects that harness anyway. A preference could therefore never add a finding,
-* so accepting one would be surface that does nothing.
+* Takes no harness preference, unlike `diagnoseBridges`: every check here needs the projection to
+* already exist on disk, which already selects the harness — a preference could never add a finding.
 */
 function diagnoseConfiguration({ root, git, cli }) {
 	const findings = [];
@@ -16963,13 +16784,6 @@ function diagnoseConfiguration({ root, git, cli }) {
 }
 //#endregion
 //#region src/diagnose-bridges/json-with-comments.ts
-/**
-* `.gemini/settings.json` may legally carry comments — the Gemini CLI loader strips them before
-* parsing. A plain `JSON.parse` of a valid settings file therefore throws, and `doctor` would report
-* a working bridge as unreadable. Comments are removed before parsing for that reason.
-*
-* Only comments. A trailing comma stays a parse error, because nothing documents it as accepted.
-*/
 function stripJsonComments(source) {
 	let output = "";
 	let index = 0;
@@ -17031,10 +16845,7 @@ const mcpFields = [
 ];
 /** The two fields holding one value per name rather than a single value. */
 const mapFields = /* @__PURE__ */ new Set(["env", "headers"]);
-/**
-* Whether two values of the same field agree. Arrays are ordered — `args` is a command line, and
-* reordering it changes what runs. Maps are not, so they are compared by their sorted entries.
-*/
+/** Arrays compare ordered (`args` is a command line); maps compare by sorted entries. */
 function sameValue(field, left, right) {
 	if (mapFields.has(field) && isRecord(left) && isRecord(right)) {
 		const keys = Object.keys(left);
@@ -17042,18 +16853,6 @@ function sameValue(field, left, right) {
 	}
 	return JSON.stringify(left) === JSON.stringify(right);
 }
-/**
-* The fields on which a target disagrees with the golden set.
-*
-* Asymmetric by design, and this is the rule that keeps a golden set from accumulating noise. A
-* field the golden set leaves unset is never a difference, however the target fills it: a host
-* restating its own default and a user's deliberate edit are indistinguishable in that position,
-* and pulling both back would grow the golden set on every round-trip. The golden set speaks only
-* about what it says.
-*
-* `env` and `headers` are compared per name for the same reason — a variable only the target sets
-* is that target's business, and one the golden set names must match.
-*/
 function divergingFields(golden, target) {
 	return mcpFields.filter((field) => {
 		const declared = golden[field];
@@ -17843,7 +17642,6 @@ function parse$1(toml, { maxDepth = 1e3, integersAsBigInt } = {}) {
 //#region src/diagnose-mcp/mcp-sources.ts
 /** Where the golden set lives, and why it is namespaced rather than sitting at `.agents/mcp.json`. */
 const goldenSetPath = ".agents/buddy-agent-harness/mcp.toml";
-/** The table the golden set keeps its servers under. */
 const goldenKey = "servers";
 function stringMap(value) {
 	if (!isRecord(value)) return void 0;
@@ -17856,10 +17654,8 @@ const transports = /* @__PURE__ */ new Set([
 	"sse"
 ]);
 /**
-* The transport a host entry describes. Hosts spell it `type` (Claude Code, VS Code) or
-* `transport`, and several state it nowhere and leave it implied by which of `url` and `command`
-* is present. Inferring it is what lets a `url` entry in one file compare equal to a `type: http`
-* entry in another.
+* Infers transport when unstated (`url` → `http`, `command` → `stdio`), so a `url` entry in one
+* file compares equal to a `type: http` entry in another.
 */
 function transportOf(entry) {
 	const declared = entry["type"] ?? entry["transport"];
@@ -17868,13 +17664,10 @@ function transportOf(entry) {
 	if (typeof entry["command"] === "string") return "stdio";
 }
 /**
-* One host entry, or one golden entry, in the canonical model. The two formats carry the same
-* field names — the divergence between hosts is the file, the top-level key, and the serialization,
-* not the entry — so one reader serves both directions of the comparison.
-*
-* A field whose value is the wrong type is dropped rather than carried through. A `timeout` that
-* is a string is not a timeout, and letting it into the model would report a divergence whose real
-* cause is a typo the finding does not name.
+* One host or golden entry, converted into the shared model; a field of the wrong type is dropped
+* rather than carried through, so a `timeout` that is a string does not report as a divergence.
+* Also used by `mcp-inventory.ts`, which normalizes its own raw shapes into these same fields
+* first.
 */
 function serverFrom(entry) {
 	const args = Array.isArray(entry["args"]) && entry["args"].every((item) => typeof item === "string");
@@ -17900,16 +17693,8 @@ function serversUnder(document, key) {
 	return new Map(Object.entries(table).filter(([, entry]) => isRecord(entry)).map(([name, entry]) => [name, serverFrom(entry)]));
 }
 /**
-* The position out of a thrown parse error, and nothing else out of it.
-*
-* `smol-toml` reports `line` and `column` on the error alongside a `codeblock` quoting the source,
-* and its `message` embeds that same code block. Both are unusable: in a file of MCP configuration
-* the line a parser failed on is exactly the line holding the credential. Only the two numbers are
-* read, and anything thrown that does not carry them is reported without a position rather than by
-* reaching for its message.
-*
-* Exported because that restriction is the point of the function rather than an implementation
-* detail of it, and it is verified directly.
+* Only line and column — never `message` or `codeblock`, which quote the source line and could echo
+* a credential.
 */
 function positionOf(error) {
 	if (!isRecord(error)) return void 0;
@@ -17935,12 +17720,8 @@ function parseGoldenSet(source) {
 	}
 }
 /**
-* One harness's MCP configuration, parsed. The file is read for its own key and nothing else:
-* `.gemini/settings.json` also carries the instruction bridge, and a reader that treated the whole
-* file as MCP would report the rest of a user's settings as servers it does not recognize.
-*
-* JSON is parsed with comments stripped, because Gemini CLI's loader strips them too and a
-* settings file may legally carry them.
+* One harness's config, parsed under its own key only — `.gemini/settings.json` also carries the
+* instruction bridge. JSON is parsed with comments stripped, matching Gemini CLI's own loader.
 */
 function parseTarget(config, source) {
 	if (source === void 0) return { kind: "absent" };
@@ -17961,49 +17742,26 @@ function parseTarget(config, source) {
 }
 //#endregion
 //#region src/diagnose-mcp/mcp-baseline.ts
-/** Where the record of what was last written to each target lives, beside the golden set it came from. */
-const projectionRecordPath = ".agents/buddy-agent-harness/mcp.projected.json";
 /**
-* The last-projected record: per target path, per server name, the model that was written there.
-*
-* It exists because git can only answer for a file it can see. Harnesses write their MCP
-* configuration themselves, at user scope, into files that are often untracked or ignored outright,
-* and for those "which side moved since they last agreed" has no answer in history. A record
-* written at projection time has one, exactly, because it *is* what was projected.
-*
-* A malformed record answers nothing rather than throwing. It is a cache of an answer, not the
-* answer, and a diagnosis that dies because its cache is corrupt is worse than one that says
-* `unknown`.
+* Where the record of what was last written to each target lives, beside the golden set it came
+* from.
 */
+const projectionRecordPath = ".agents/buddy-agent-harness/mcp.projected.json";
 function parseProjectionRecord(source) {
 	const document = source === void 0 ? void 0 : parseJsonWithComments(source);
 	const targets = isRecord(document) ? document["targets"] : void 0;
 	if (!isRecord(targets)) return /* @__PURE__ */ new Map();
 	return new Map(Object.entries(targets).filter(([, servers]) => isRecord(servers)).map(([path, servers]) => [path, new Map(Object.entries(servers).filter(([, server]) => isRecord(server)).map(([name, server]) => [name, server]))]));
 }
-/**
-* Which side moved, for one server and one field.
-*
-* The record is asked first, because it records exactly what was written and therefore answers
-* exactly. Where it holds nothing, a **tracked** target falls back to git: the newest commit where
-* the golden set and the target agreed on that field, then which working tree still matches it.
-* Where neither can answer, the direction is `unknown` and the finding says so — naming a side on a
-* guess would send a reconcile at the wrong file.
-*/
 var McpBaseline = class {
 	options;
 	constructor(options) {
 		this.options = options;
 	}
 	/**
-	* One parse per commit per file, and one commit walk per target.
-	*
-	* `lastAgreed` runs per (config, server, field) that diverges without a projection record, and
-	* every one of those walks reads the same two files at the same commits. Unmemoized, three
-	* targets against five servers with two diverged fields each over fifty commits of history is
-	* three thousand `git show` calls and as many parses — on the command the `doctor` skill says is
-	* cheap enough for a session-start hook. One instance serves one diagnosis, so the memo lives and
-	* dies with it and can never answer for a working tree that has moved on.
+	* Memoized per instance: unmemoized, `lastAgreed` would repeat the same `git show` and parse
+	* for every diverged field. The memo dies with the instance, so it never answers for a working
+	* tree that has since moved on.
 	*/
 	parsed = /* @__PURE__ */ new Map();
 	walked = /* @__PURE__ */ new Map();
@@ -18021,9 +17779,8 @@ var McpBaseline = class {
 		return this.lastAgreed(config, name, field);
 	}
 	/**
-	* The newest committed state where both files described this field the same way. Read at model
-	* granularity rather than by comparing blobs: the two files never share bytes, and a commit that
-	* reformatted one of them did not change what it says.
+	* Compared at model granularity, not blob bytes — the two files never share bytes, so a
+	* reformat wouldn't register as agreement lost.
 	*/
 	lastAgreed(config, name, field) {
 		for (const commit of this.commitsTouching(config)) {
@@ -18054,28 +17811,18 @@ var McpBaseline = class {
 //#endregion
 //#region src/diagnose-mcp/mcp-secrets.ts
 /**
-* Finding a literal credential in MCP configuration, without ever handling one.
-*
-* `doctor` is safe to run from a session-start hook, so its output lands in agent context on every
-* session and from there into transcripts. A value it echoes is amplified far past the file it came
-* from. Every function here answers **where**, never **what**: the return is a field path, and the
-* value never leaves this module.
-*
-* That is also why the redaction lives here rather than in a formatter. `doctor` renders three ways
-* — TOON, `--format text`, and `--format json` — and trusting each of them to mask is three chances
-* to drift. A value that never enters the finding cannot be printed by any of them.
+* Finding a literal credential in MCP configuration, without ever handling one: every function
+* here answers where, never what, and the value itself never leaves this module — redaction lives
+* here, once, rather than being trusted to each of `doctor`'s three output formats.
 */
 /**
-* Words that mark a field as credential-bearing wherever they appear in its name. Each is one that
-* effectively never turns up inside an innocent word, so a bare substring test is safe and catches
-* the run-together spellings a segment test would miss — `MYTOKEN`, `githubsecret`.
+* Marks a field as credential-bearing anywhere in its name — safe as a substring, since none of
+* these turn up inside an innocent word.
 */
 const credentialWord = /token|secret|password|passwd|credential/i;
 /**
-* Words that mark a field only when they are a **segment** of its name. `key` and `auth` are the
-* two that matter, and both are common inside words that carry nothing — `MONKEY`, `AUTHOR`,
-* `KEYSTONE_URL`. Matching them as substrings reports those, and a scanner that cries wolf on a
-* hook-run command is one people stop reading.
+* Marks a field only as a whole name segment: `key`/`auth` are common inside innocent words like
+* `MONKEY` or `AUTHOR`.
 */
 const credentialSegment = /* @__PURE__ */ new Set([
 	"key",
@@ -18089,19 +17836,15 @@ function segmentsOf(key) {
 	return key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean).map((segment) => segment.toLowerCase());
 }
 /**
-* A value that **names** a secret instead of holding one, in the forms the supported hosts
-* document: `${VAR}`, `$VAR`, and the `${env:VAR}` / `${input:id}` variants.
-*
-* Classification is by shape, not by content. An entropy test on the value would be a guess about
-* a string this module has already decided not to look at, and it would fail in both directions —
-* a short password is low-entropy and a base64 configuration blob is high.
+* A value that names a secret rather than holding one: `${VAR}`, `$VAR`, `${env:VAR}`,
+* `${input:id}`. Classification is by shape, not entropy — a short password and a base64 blob look
+* identical to an entropy test.
 */
 const reference = /\$\{[^}]+\}|\$[A-Za-z_][A-Za-z0-9_]*/;
 /**
-* A credential-bearing field passes when it carries a reference anywhere in it, because the common
-* legitimate form is a template rather than a bare variable — `Bearer ${LINEAR_TOKEN}` is the
-* documented way to write an authorization header, and requiring the whole value to be a reference
-* would report every correct one.
+* True unless a reference appears anywhere in the value — `Bearer ${LINEAR_TOKEN}` is the
+* documented template form, so requiring the whole value to be a reference would flag it as
+* literal.
 */
 function holdsLiteral(value) {
 	return !reference.test(value);
@@ -18110,11 +17853,8 @@ function credentialKey(key) {
 	return credentialWord.test(key) || segmentsOf(key).some((segment) => credentialSegment.has(segment));
 }
 /**
-* Whether a URL carries a credential in itself. Two shapes: a password in the userinfo component,
-* and a credential-named query parameter holding a literal. Neither value is read past the test.
-*
-* A URL that does not parse is not reported. It is malformed rather than leaky, and guessing at its
-* structure with a regular expression is how a scanner starts matching the thing it must not touch.
+* A password in the URL's userinfo, or a credential-named query parameter holding a literal. An
+* unparseable URL is not reported — malformed, not leaky.
 */
 function urlHoldsCredential(value) {
 	let url;
@@ -18130,12 +17870,7 @@ function urlHoldsCredential(value) {
 function literalsIn(field, values) {
 	return Object.entries(values ?? {}).filter(([key, value]) => credentialKey(key) && holdsLiteral(value)).map(([key]) => `${field}.${key}`);
 }
-/**
-* Every field of one server holding a literal credential, as a path within that server.
-*
-* The path is the whole answer. It is never a truncated value: `sk-ab…` is a leak into the same
-* transcript and buys a reader nothing the field name does not already give them.
-*/
+/** Field paths only — never a truncated value; `sk-ab…` is still a leak into the same transcript. */
 function credentialFields(server) {
 	return [
 		...literalsIn("env", server.env),
@@ -18150,12 +17885,8 @@ function read(root, path) {
 	return existsSync(absolute) ? readFileSync(absolute, "utf8") : void 0;
 }
 /**
-* The distinct MCP files the enabled harnesses read. Two harnesses may name the same file.
-*
-* No harness preference is accepted, for the same reason the configuration half accepts none: every
-* harness documenting an MCP file is already selected without one. Claude Code and Cursor are
-* selected unconditionally; Codex and Gemini CLI keep their file inside their own detection
-* directory, so it cannot exist without that directory selecting them. A preference could never add
+* The distinct MCP files the enabled harnesses read. No `--harness` preference is accepted: every
+* harness documenting an MCP file is already selected without one, so a preference could never add
 * a finding.
 */
 function targetsOf(root) {
@@ -18179,12 +17910,6 @@ function diagnoseMcp({ root, git, cli }) {
 			repair: repair(at, cli)
 		});
 	};
-	/**
-	* Credentials are reported for every file that holds servers, the golden set included — a user
-	* pastes a token into whichever file is open, and the golden set is a file. Severity splits on
-	* tracking, because a literal in a tracked file is already a committed credential and moving it
-	* to an environment variable does not un-commit it.
-	*/
 	const reportSecrets = (path, servers) => {
 		const committed = git.trackingOf(path) !== "untracked";
 		for (const [name, server] of servers) for (const field of credentialFields(server)) add({
@@ -18254,11 +17979,9 @@ const problemOf = {
 	subagent: "nonstandard-subagent"
 };
 /**
-* A `.mdc` rule splits on whether its scoping is load-bearing. `globs:` with a value binds the rule
-* to paths, and `AGENTS.md` has no equivalent — it scopes by directory nesting only — so that one
-* converts to a skill, or stays. Without it the rule is always-on prose, which `AGENTS.md` holds
-* verbatim. Read from frontmatter rather than assumed, because the two need different conversions
-* and guessing wrong sends prose to the wrong destination.
+* `globs:` with a value binds a `.mdc` rule to paths — `AGENTS.md` has no equivalent, so that rule
+* converts to a skill; without it, the rule is always-on prose that `AGENTS.md` holds verbatim.
+* Read from frontmatter rather than assumed, since guessing wrong sends prose to the wrong destination.
 */
 function scopedByGlobs(body) {
 	const block = /^---\n([\s\S]*?)\n---/.exec(body);
@@ -18271,8 +17994,8 @@ function skillFiles(directory) {
 	return filesUnder(directory).filter((file) => file.endsWith("SKILL.md"));
 }
 /**
-* A harness directory that is a symlink is a projection someone already made, not configuration
-* authored here — reporting it would tell a repository to convert what it already converted.
+* A symlinked path is already a projection, not authored config — reporting it would tell a repo to
+* convert what it already converted.
 */
 function authoredHere(path) {
 	try {
@@ -18288,10 +18011,8 @@ function artifactFiles(root, artifact) {
 	return (artifact.kind === "skill" ? skillFiles(absolute) : filesUnder(absolute)).map((file) => posix.join(artifact.path, file));
 }
 /**
-* Unlike the other detectors this takes no harness preference and no enabled set. An artifact is
-* reachable by one harness whether or not that harness is enabled here — a `.cursorrules` in a
-* repository nobody opens in Cursor is still instruction content `AGENTS.md` does not carry — so
-* filtering by the enabled set would hide exactly the drift worth converting.
+* Takes no harness preference or enabled set, unlike the other detectors — an artifact matters
+* whether or not its harness is enabled here, so filtering by the enabled set would hide it.
 */
 function diagnoseNonstandard({ root, cli }) {
 	const findings = [];
@@ -18309,6 +18030,129 @@ function diagnoseNonstandard({ root, cli }) {
 	return findings.sort((left, right) => left.path.localeCompare(right.path));
 }
 //#endregion
+//#region src/governance-overrides/governance-overrides.ts
+function managedGovernancesDir(platform, programData) {
+	if (platform === "darwin") return "/Library/Application Support/BuddyAgentHarness/governances";
+	if (platform === "win32") return join(programData || "C:\\ProgramData", "BuddyAgentHarness", "governances");
+	return "/etc/buddy-agent-harness/governances";
+}
+/**
+* Still read below the layer above, so a machine already using it keeps working; reported as
+* deprecated so an admin knows to move it.
+*/
+function deprecatedManagedGovernancesDir(platform, programData) {
+	if (platform === "darwin") return "/Library/Application Support/UniPlugin/governances";
+	if (platform === "win32") return join(programData || "C:\\ProgramData", "UniPlugin", "governances");
+	return "/etc/universal-plugin/governances";
+}
+function projectGovernancesDir(root) {
+	return join(root, ".agents", "governances");
+}
+function userGovernancesDir(home) {
+	return join(home, ".agents", "governances");
+}
+/**
+* Walks up to the nearest `package.json` rather than a relative literal — this module sits at a
+* different depth in `src/` vs the bundle.
+*/
+function packageGovernancesDir(from = fileURLToPath(import.meta.url)) {
+	let dir = dirname(from);
+	for (;;) {
+		if (existsSync(join(dir, "package.json"))) return join(dir, "governances");
+		const parent = dirname(dir);
+		if (parent === dir) return join(dir, "governances");
+		dir = parent;
+	}
+}
+function governanceLayers({ root, home, platform, programData }) {
+	return [
+		{
+			scope: "project",
+			dir: projectGovernancesDir(root)
+		},
+		{
+			scope: "user",
+			dir: userGovernancesDir(home)
+		},
+		{
+			scope: "managed",
+			dir: managedGovernancesDir(platform, programData)
+		},
+		{
+			scope: "managed-deprecated",
+			dir: deprecatedManagedGovernancesDir(platform, programData)
+		},
+		{
+			scope: "package",
+			dir: packageGovernancesDir()
+		}
+	];
+}
+/**
+* Filters by scope rather than slicing the list, so a layer added later can't quietly become an
+* override by position.
+*/
+function overrideLayers(layers) {
+	return layers.filter((layer) => layer.scope !== "package");
+}
+const namePattern = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/i;
+/**
+* Rejects rather than sanitizes — silently answering a different question is how untrusted input
+* reads a file outside the layer.
+*/
+function parseGovernanceName(value) {
+	if (value.endsWith(".md")) throw new Error(`"${value}" names a file. Ask for the governance by name, without the .md extension.`);
+	if (!namePattern.test(value)) throw new Error(`"${value}" is not a governance name. A name is letters, digits, hyphens, and dots — not a path.`);
+	return value;
+}
+function tryReadDocument(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+}
+/** Empty for a layer that's missing, unreadable, or not a directory — never throws. */
+function documentNames(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => entry.name.slice(0, -3));
+	} catch {
+		return [];
+	}
+}
+/** The first layer that holds the name wins; the rest are not read. */
+function resolveGovernance(name, layers) {
+	for (const { scope, dir } of layers) {
+		const path = join(dir, `${name}.md`);
+		const content = tryReadDocument(path);
+		if (content !== void 0) return {
+			name,
+			scope,
+			path,
+			content
+		};
+	}
+}
+/** Every name any layer holds, each reported at the layer that would win, sorted by name. */
+function listGovernances(layers) {
+	const found = /* @__PURE__ */ new Map();
+	for (const { scope, dir } of layers) for (const name of documentNames(dir)) if (!found.has(name)) found.set(name, {
+		name,
+		scope,
+		path: join(dir, `${name}.md`)
+	});
+	return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+* Creates the directory if absent — a fresh repository gets one obvious place to put an override,
+* and a count of zero.
+*/
+function countProjectGovernances(root) {
+	const dir = projectGovernancesDir(root);
+	mkdirSync(dir, { recursive: true });
+	return documentNames(dir).length;
+}
+//#endregion
 //#region src/skill-projection/skill-projection.ts
 function skillNames(skillsDirectory) {
 	return readdirSync(skillsDirectory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
@@ -18322,10 +18166,8 @@ function pathOccupied(path) {
 	}
 }
 /**
-* Whether `target` is a symbolic link that resolves to `canonical`. Resolved paths are compared
-* rather than link text, so a link a user wrote as an absolute path, one this tool wrote as a
-* Windows junction, and one reached through a symbolic link in a parent directory all read as the
-* correct bridge. A link that no longer resolves is not.
+* Compares resolved paths, not link text, so an absolute link, a Windows junction, or a link
+* reached through a parent symlink all read as correct.
 */
 function linksTo(target, canonical) {
 	try {
@@ -18341,18 +18183,15 @@ function countSkills(canonicalSkills) {
 	return skillNames(canonicalSkills).length;
 }
 /**
-* A junction is the only link Windows grants an unprivileged process, and Node resolves a relative
-* junction target against the process directory rather than the link's own, so Windows is given the
-* absolute path. Every other platform keeps the link relative, so it survives the repository moving.
+* Windows junctions resolve a relative target against the process directory, not the link's own, so
+* Windows gets an absolute path; everywhere else stays relative to survive the repository moving.
 */
 function linkTarget(target, canonicalSkills) {
 	return platform() === "win32" ? resolve(canonicalSkills) : relative(dirname(target), canonicalSkills);
 }
 /**
-* Translates what the option parser hands back into a selection. A valueless `--force` arrives as
-* the literal string `true` — that is how the parser encodes a flag given no value — and means
-* every conflicting target, which is what keeps an existing `init --force` doing what it always did.
-* Anything else is a comma-separated list of targets.
+* A valueless `--force` arrives as the literal string `"true"` — the parser's flag encoding — and
+* means every target; anything else is a comma-separated list.
 */
 function parseForce(value) {
 	if (value === "true") return true;
@@ -18360,17 +18199,13 @@ function parseForce(value) {
 	return value.split(",").map((target) => target.trim()).filter((target) => target.length > 0);
 }
 /**
-* Targets are matched against what the caller typed, resolved against the repository root, so the
-* repo-relative form the conflict message prints is the form that selects it back — and an absolute
-* path naming the same directory selects it too.
+* Resolves both sides so the repo-relative path a conflict message prints also selects it back, and
+* so does an absolute path naming the same directory.
 */
 function namesTarget(root, target, given) {
 	return resolve(root, given) === resolve(target);
 }
-/**
-* Points every harness that cannot read `.agents/skills` at the canonical directory. Symlinking is
-* preferred; a platform that refuses the link falls back to a copy.
-*/
+/** Symlinks by default; falls back to a copy where the platform refuses the link. */
 function projectSkills({ root, canonicalSkills, harnesses, copy, force }) {
 	const projections = harnesses.filter((harness) => harness.project.skillsDirectory).map((harness) => ({
 		harness,
@@ -18412,12 +18247,8 @@ function projectSkills({ root, canonicalSkills, harnesses, copy, force }) {
 /** Directories that never hold instructions this repository is responsible for bridging. */
 const pruned = /* @__PURE__ */ new Set(["node_modules"]);
 /**
-* Every directory below `root` holding an `AGENTS.md`, repository-relative and POSIX-separated,
-* with the root itself as `''`. Sorted, root first.
-*
-* Dot-directories are pruned along with `node_modules`. That is not only a speed measure:
-* `.agents/AGENTS.md` is canonical shared instructions rather than a subtree-scoped file, and
-* bridging it would claim a scope it does not have.
+* Dot-directories are pruned along with `node_modules`: `.agents/AGENTS.md` is canonical shared
+* instructions, not a subtree-scoped file.
 */
 function agentsFileDirectories(root) {
 	const found = [];
@@ -18440,40 +18271,6 @@ function agentsFileDirectories(root) {
 //#endregion
 //#region src/diagnose-bridges/diagnose-instructions.ts
 const canonicalInstructions = "AGENTS.md";
-/**
-* An import bridges the `AGENTS.md` beside it and nothing else, so the check is per directory
-* holding one rather than per harness. A line of its own is enough: the harness reference allows
-* Claude-specific notes below the import, and a file that carries the import plus notes still
-* bridges.
-*/
-function inspectImport(target) {
-	let stats;
-	try {
-		stats = lstatSync(target);
-	} catch {
-		return {
-			kind: "none",
-			status: "missing",
-			problem: "instructions-missing"
-		};
-	}
-	if (stats.isSymbolicLink()) return readlinkSync(target) === "AGENTS.md" ? {
-		kind: "symlink",
-		status: "ok"
-	} : {
-		kind: "symlink",
-		status: "unbridged",
-		problem: "instructions-unbridged"
-	};
-	return readFileSync(target, "utf8").split("\n").some((line) => line.trim() === `@AGENTS.md`) ? {
-		kind: "import",
-		status: "ok"
-	} : {
-		kind: "file",
-		status: "unbridged",
-		problem: "instructions-unbridged"
-	};
-}
 /** Reads a dotted key out of parsed JSON without asserting anything about the rest of the file. */
 function valueAt(settings, key) {
 	return key.split(".").reduce((value, segment) => {
@@ -18481,6 +18278,14 @@ function valueAt(settings, key) {
 		return value[segment];
 	}, settings);
 }
+function exists(target) {
+	try {
+		lstatSync(target);
+		return true;
+	} catch {
+		return false;
+	}
+}
 function inspectSettingsEntry(target, key) {
 	let source;
 	try {
@@ -18508,21 +18313,45 @@ function inspectSettingsEntry(target, key) {
 		problem: "instructions-unbridged"
 	};
 }
-/** Every path an instruction bridge of this kind belongs at, in report order. */
-function pathsFor(root, bridge) {
-	if (bridge.kind !== "import") return [bridge.path];
-	return agentsFileDirectories(root).map((directory) => directory ? posix.join(directory, bridge.path) : bridge.path);
-}
-function inspect$1(target, bridge) {
-	return bridge.kind === "import" ? inspectImport(target) : inspectSettingsEntry(target, bridge.key);
+function inspectShadow(target) {
+	let stats;
+	try {
+		stats = lstatSync(target);
+	} catch {
+		return;
+	}
+	if (stats.isSymbolicLink()) return readlinkSync(target) === "AGENTS.md" ? {
+		kind: "symlink",
+		status: "superseded",
+		problem: "instructions-superseded"
+	} : {
+		kind: "symlink",
+		status: "shadowing",
+		problem: "instructions-shadowing"
+	};
+	let body;
+	try {
+		body = readFileSync(target, "utf8");
+	} catch {
+		return {
+			kind: "file",
+			status: "unreadable",
+			problem: "instructions-unreadable"
+		};
+	}
+	return body.split("\n").some((line) => line.trim() === `@AGENTS.md`) ? {
+		kind: "import",
+		status: "superseded",
+		problem: "instructions-superseded"
+	} : {
+		kind: "file",
+		status: "shadowing",
+		problem: "instructions-shadowing"
+	};
 }
 /**
-* Reports whether every enabled harness can still read `AGENTS.md`.
-*
-* Losing one of these is quieter than losing a skills bridge and costs more: a harness with no
-* instruction bridge reads none of the repository's instructions, and says nothing about it. The
-* checks are read-only, and no repair is a command — rewriting an instruction file is the `init`
-* skill's judgment.
+* Checks two things: whether each instruction bridge resolves, and whether anything suppresses a
+* harness that reads `AGENTS.md` natively.
 */
 function diagnoseInstructions(root, harnesses, cli) {
 	const bridged = harnesses.map((harness) => ({
@@ -18531,11 +18360,9 @@ function diagnoseInstructions(root, harnesses, cli) {
 	})).filter((harness) => Boolean(harness.bridge));
 	const instructions = [];
 	const findings = [];
-	if (!bridged.length) return {
-		instructions,
-		findings
-	};
-	if (!agentsFileDirectories(root).includes("")) {
+	const directories = agentsFileDirectories(root);
+	const shadowsAtRoot = harnesses.some((harness) => (harness.project.shadowedBy ?? []).some((shadow) => exists(join(root, shadow))));
+	if ((bridged.length || shadowsAtRoot) && !directories.includes("")) {
 		const { detail, repair } = repairFor("no-instructions");
 		findings.push({
 			path: canonicalInstructions,
@@ -18544,24 +18371,42 @@ function diagnoseInstructions(root, harnesses, cli) {
 			repair: repair({ file: canonicalInstructions }, cli)
 		});
 	}
-	for (const { name, bridge } of bridged) for (const path of pathsFor(root, bridge)) {
-		const inspection = inspect$1(join(root, path), bridge);
+	for (const { name, bridge } of bridged) {
+		const inspection = inspectSettingsEntry(join(root, bridge.path), bridge.key);
 		instructions.push({
 			harness: name,
-			path,
+			path: bridge.path,
 			kind: inspection.kind,
 			status: inspection.status
 		});
 		if (inspection.problem) {
 			const { detail, repair } = repairFor(inspection.problem);
 			findings.push({
-				path,
+				path: bridge.path,
 				problem: inspection.problem,
 				detail,
-				repair: repair({ file: path }, cli)
+				repair: repair({ file: bridge.path }, cli)
 			});
 		}
 	}
+	for (const harness of harnesses) for (const shadow of harness.project.shadowedBy ?? []) for (const directory of directories) {
+		const path = directory ? posix.join(directory, shadow) : shadow;
+		const inspection = inspectShadow(join(root, path));
+		if (!inspection) continue;
+		instructions.push({
+			harness: harness.name,
+			path,
+			kind: inspection.kind,
+			status: inspection.status
+		});
+		const { detail, repair } = repairFor(inspection.problem);
+		findings.push({
+			path,
+			problem: inspection.problem,
+			detail,
+			repair: repair({ file: path }, cli)
+		});
+	}
 	return {
 		instructions,
 		findings
@@ -18589,25 +18434,20 @@ function lines(output) {
 	return (output ?? "").split("\n").filter(Boolean);
 }
 /**
-* Reads git state for the two sides of a bridge. Every method degrades to "cannot tell" rather than
-* throwing, so `doctor` still reports on a tarball, a worktree without git, or a repository with no
-* commits.
+* Every method degrades to "cannot tell" rather than throwing, so `doctor` still reports on a
+* tarball or a repository with no commits.
 */
 var GitBridgeState = class {
 	root;
-	/** Path of `root` relative to the repository root, `''` at the top, `undefined` outside a repository. */
-	prefix;
+	/** `''` at the top, `undefined` outside a repository. */
+	repoRootPrefix;
 	constructor(root) {
 		this.root = root;
-		this.prefix = git(root, ["rev-parse", "--show-prefix"])?.trim();
+		this.repoRootPrefix = git(root, ["rev-parse", "--show-prefix"])?.trim();
 	}
-	/**
-	* `init --copy` marks a bridge skip-worktree so a machine-local copy over a tracked symlink stops
-	* showing as a pending change. The bit is a hint that some checkouts clear, so it is verified
-	* rather than assumed.
-	*/
+	/** The skip-worktree bit is a hint some checkouts clear, so it is verified rather than assumed. */
 	trackingOf(path) {
-		if (this.prefix === void 0) return "untracked";
+		if (this.repoRootPrefix === void 0) return "untracked";
 		const entries = lines(git(this.root, [
 			"ls-files",
 			"-v",
@@ -18618,13 +18458,11 @@ var GitBridgeState = class {
 		return entries.every((entry) => entry.startsWith("S")) ? "skip-worktree" : "tracked";
 	}
 	/**
-	* Whether a `.gitignore` rule matches this path. Asked of git rather than matched against the
-	* file, so a rule on a parent directory — the common way a bridge gets ignored — is caught.
-	* Outside a repository nothing is ignored, which is the same "cannot tell" degradation the rest
-	* of this class uses.
+	* Asked of git rather than matched against the file, so a rule on a parent directory is caught
+	* too.
 	*/
 	isIgnored(path) {
-		if (this.prefix === void 0) return false;
+		if (this.repoRootPrefix === void 0) return false;
 		return git(this.root, [
 			"check-ignore",
 			"-q",
@@ -18633,15 +18471,11 @@ var GitBridgeState = class {
 		]) !== void 0;
 	}
 	/**
-	* The newest commits that touched any of these paths, newest first. Empty outside a repository,
-	* which is the same "cannot tell" degradation as everything else here.
-	*
-	* Bounded like `lastAgreedTree` is: a baseline that is not in the recent history of the two files
-	* is not a baseline anyone can act on, and walking a whole repository to prove its absence costs
-	* more than the answer is worth.
+	* Bounded to the last 200 commits: a baseline outside that range costs more to find than it's
+	* worth acting on.
 	*/
 	commitsTouching(paths) {
-		if (this.prefix === void 0) return [];
+		if (this.repoRootPrefix === void 0) return [];
 		return lines(git(this.root, [
 			"rev-list",
 			"-n",
@@ -18653,15 +18487,11 @@ var GitBridgeState = class {
 	}
 	/** One file's content at one commit, or `undefined` when it did not exist there. */
 	contentAt(commit, path) {
-		if (this.prefix === void 0) return void 0;
-		return git(this.root, ["show", `${commit}:${this.prefix}${path}`]);
+		if (this.repoRootPrefix === void 0) return void 0;
+		return git(this.root, ["show", `${commit}:${this.repoRootPrefix}${path}`]);
 	}
-	/**
-	* Names the side that moved by finding the newest commit whose two trees agreed, then asking which
-	* of the working directories still matches it.
-	*/
 	directionOf(bridge, canonical) {
-		if (this.prefix === void 0) return "unknown";
+		if (this.repoRootPrefix === void 0) return "unknown";
 		const base = this.lastAgreedTree(bridge, canonical);
 		if (base === void 0) return "unknown";
 		const bridgeMoved = !this.matchesTree(bridge, base);
@@ -18685,20 +18515,20 @@ var GitBridgeState = class {
 				"rev-parse",
 				"-q",
 				"--verify",
-				`${commit}:${this.prefix}${bridge}`
+				`${commit}:${this.repoRootPrefix}${bridge}`
 			])?.trim();
 			if (!bridgeObject) continue;
 			if (bridgeObject === git(this.root, [
 				"rev-parse",
 				"-q",
 				"--verify",
-				`${commit}:${this.prefix}${canonical}`
+				`${commit}:${this.repoRootPrefix}${canonical}`
 			])?.trim()) return bridgeObject;
 		}
 	}
 	/**
-	* Compares a working directory against a git tree by object id. `hash-object` is used rather than
-	* hashing in-process so the comparison follows whatever object format the repository uses.
+	* Compares by object id via `hash-object` rather than hashing in-process, so it follows
+	* whatever object format the repository uses.
 	*/
 	matchesTree(directory, tree) {
 		const expected = new Map(lines(git(this.root, [
@@ -18780,9 +18610,8 @@ function inspect(target, path, canonical, git) {
 	}
 }
 /**
-* Reports whether every bridge this repository needs still resolves: the skills bridges into
-* `.agents/skills`, and the instruction bridges into `AGENTS.md`. Read-only: nothing is created,
-* moved, or repaired, so the caller decides what to run from the repair each finding carries.
+* Read-only: nothing is created, moved, or repaired — the caller decides what to run from the
+* repair each finding carries.
 */
 function diagnoseBridges({ root, harnesses: preferred = [], cli }) {
 	const canonical = join(root, ".agents", "skills");
@@ -18839,11 +18668,12 @@ function diagnoseBridges({ root, harnesses: preferred = [], cli }) {
 //#endregion
 //#region src/diagnose-bridges/doctor.command.ts
 /**
-* AXI §5: the healthy answer states the zero with context, so an agent does not re-run with other
-* flags to confirm that an empty section really meant "nothing wrong".
+* AXI §5: the healthy answer states the zero with context, so an agent doesn't re-run to confirm
+* nothing was wrong.
 */
-function buildDoctorReport(bin, result, configuration = []) {
+function buildDoctorReport(bin, result, configuration = [], overrides = []) {
 	const findings = [...result.findings, ...configuration];
+	const governances = overrides.length ? overrides : "0 governance overrides — no .agents/governances at project, user, or machine scope";
 	if (!findings.length) {
 		const count = result.bridges.length + result.instructions.length;
 		const bridges = count === 1 ? "the 1 bridge resolves" : `all ${count} bridges resolve`;
@@ -18851,6 +18681,7 @@ function buildDoctorReport(bin, result, configuration = []) {
 			bin,
 			bridges: result.bridges,
 			instructions: result.instructions,
+			governances,
 			findings: `0 problems found — ${bridges} and the configuration around them is current`
 		};
 	}
@@ -18858,6 +18689,7 @@ function buildDoctorReport(bin, result, configuration = []) {
 		bin,
 		bridges: result.bridges,
 		instructions: result.instructions,
+		governances,
 		...result.divergence.length ? { divergence: result.divergence } : {},
 		findings: findings.map(({ path, problem, detail }) => ({
 			path,
@@ -18890,6 +18722,7 @@ const doctorCommand = command({
 			const format = parseFormat(args.format);
 			const harnesses = parseHarnesses(args.harness);
 			const root = args.root ?? process.cwd();
+			const home = homedir();
 			const result = diagnoseBridges({
 				root,
 				...harnesses.length ? { harnesses } : {},
@@ -18912,7 +18745,17 @@ const doctorCommand = command({
 					cli: commandInvocation
 				})
 			];
-			writeResult(buildDoctorReport(binPath(homedir(), process.argv[1]), result, configuration), format);
+			const overrides = listGovernances(overrideLayers(governanceLayers({
+				root,
+				home,
+				platform: process.platform,
+				programData: process.env["ProgramData"]
+			}))).map(({ name, scope, path }) => ({
+				name,
+				scope,
+				path: collapseHome(home, path)
+			}));
+			writeResult(buildDoctorReport(displayBinPath(home, process.argv[1]), result, configuration, overrides), format);
 			return exitCodes.success;
 		} catch (error) {
 			process.stderr.write(`error: ${error instanceof Error ? error.message : "Harness diagnosis failed."}\n`);
@@ -18921,10 +18764,111 @@ const doctorCommand = command({
 	}
 });
 //#endregion
+//#region src/governance-overrides/governance.command.ts
+function layersFor(args) {
+	const layers = governanceLayers({
+		root: args.root ?? process.cwd(),
+		home: homedir(),
+		platform: process.platform,
+		programData: process.env["ProgramData"]
+	});
+	return args["overrides-only"] ? overrideLayers(layers) : layers;
+}
+const DEPRECATED_MANAGED = "deprecated — move these documents to the managed layer above";
+const rootOption = {
+	description: "Repository or package directory. Defaults to the current directory.",
+	type: optionalType(stringType())
+};
+const overridesOnlyOption = {
+	description: "Resolve only the project, user, and machine-wide layers. Never returns a governance this package ships, and exits non-zero when no layer has one.",
+	type: optionalType(booleanType())
+};
+const governanceCommand = command({
+	name: "governance",
+	description: "Read the governance documents the project, user, and machine-wide override layers hold. Read-only.",
+	commands: [command({
+		name: "list",
+		description: "List every governance the override layers hold, each at the layer that would win.",
+		options: {
+			root: rootOption,
+			"overrides-only": overridesOnlyOption,
+			format: {
+				description: "Output format: toon (default), json, or text for a human-readable report.",
+				type: optionalType(stringType()),
+				default: "toon"
+			}
+		},
+		run(args) {
+			try {
+				const format = parseFormat(args.format);
+				const home = homedir();
+				const layers = layersFor(args);
+				const entries = listGovernances(layers);
+				writeResult({
+					layers: layers.map(({ scope, dir }) => ({
+						scope,
+						path: collapseHome(home, dir),
+						status: scope === "managed-deprecated" ? DEPRECATED_MANAGED : ""
+					})),
+					governances: entries.length ? entries.map(({ name, scope, path }) => ({
+						name,
+						scope,
+						path: collapseHome(home, path)
+					})) : "0 governances — no layer holds one"
+				}, format);
+				return exitCodes.success;
+			} catch (error) {
+				process.stderr.write(`error: ${error instanceof Error ? error.message : "Governance listing failed."}\n`);
+				return exitCodes.error;
+			}
+		}
+	}), command({
+		name: "show",
+		description: "Print one governance document, resolved through the layers in order.",
+		arguments: [{
+			name: "name",
+			description: "The governance name, without the `.md` extension.",
+			type: stringType()
+		}],
+		options: {
+			root: rootOption,
+			"overrides-only": overridesOnlyOption,
+			format: {
+				description: "Output format: text (default) writes the document itself; toon and json wrap it with the layer it came from.",
+				type: optionalType(stringType()),
+				default: "text"
+			}
+		},
+		run(args) {
+			try {
+				const format = parseFormat(args.format);
+				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`);
+					return exitCodes.error;
+				}
+				if (format === "text") writeDocument(found.content);
+				else writeResult({
+					name: found.name,
+					scope: found.scope,
+					path: collapseHome(homedir(), found.path),
+					content: found.content
+				}, format);
+				return exitCodes.success;
+			} catch (error) {
+				process.stderr.write(`error: ${error instanceof Error ? error.message : "Governance lookup failed."}\n`);
+				return exitCodes.error;
+			}
+		}
+	})]
+});
+//#endregion
 //#region src/initialize-harnesses/initialize-harnesses.ts
 function initializeHarnesses({ root, harnesses: preferred = [], copy = false, force = false }) {
 	const canonicalSkills = join(root, ".agents", "skills");
 	const skills = countSkills(canonicalSkills);
+	const governances = countProjectGovernances(root);
 	const harnesses = selectHarnesses(root, preferred);
 	const { linked, skipped } = projectSkills({
 		root,
@@ -18944,6 +18888,7 @@ function initializeHarnesses({ root, harnesses: preferred = [], copy = false, fo
 			replacedBy: harness.deprecated
 		})),
 		skills,
+		governances,
 		copied: copy
 	};
 }
@@ -18995,27 +18940,16 @@ const initCommand = command({
 //#endregion
 //#region src/cli.ts
 const version = typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-/**
-* A factory rather than a module-level constant: `cli()` builds state, and state built at import
-* time is shared by every later call in the process.
-*/
 function app() {
 	return cli({
 		name: "buddy-agent-harness",
 		version,
 		description: "Initialize agent harness skill compatibility in consumer repositories."
-	}).command(initCommand).command(doctorCommand).command(depPluginsCommand);
+	}).command(initCommand).command(doctorCommand).command(depPluginsCommand).command(governanceCommand);
 }
 /**
-* The application boundary: argv in, exit code out, nothing read from or written to the process.
-*
-* The exit code is returned rather than written so that a caller which is not the process — a skill
-* launcher, a test — can run a command and learn how it went. `bin/buddy-agent-harness.mjs` is the
-* only place that turns the returned code back into a process outcome.
-*
-* One exit path this return cannot carry: `clibuilder` answers an unknown option or an unknown
-* command by printing help and writing `process.exitCode` itself, returning nothing. `run` reports
-* `0` there, which is why `bin` and the launchers apply the returned code only when it is non-zero.
+* The application boundary: argv in, exit code out — returned rather than written, so a caller that
+* is not the process (a skill launcher, a test) can act on it.
 */
 async function run(argv) {
 	try {