buddy-agent-harness 1.0.1 → 1.2.0

package/dist/cli.mjs

@@ -1,18 +1,46 @@
 import { createRequire } from "node:module";
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { inspect, styleText } from "node:util";
 import { homedir, platform } from "node:os";
 import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, sep, win32 } from "node:path";
 import { readFile, readdir } from "node:fs/promises";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/render/ref.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/render/ref.js
 /**
 * Next-step references: `ref()` names another command, and the runner renders it as a command line.
 * Imports nothing from the framework (axi-native RFC section 4.1; next-step-refs RFC).
 */
 const refKey = Symbol.for("clibuilder.ref");
 const placeholderKey = Symbol.for("clibuilder.placeholder");
+/**
+* A reference to another command, for a `help` list.
+*
+* The runner renders it as a complete command line for the channel it runs in:
+* `<cli name> task get --gid 123` under `cli()`, or the sibling script, `pnpm exec` or pinned `npx` line under `runScript()`.
+*
+* Options render as `--name value` in the order given. `true` renders as `--name`, `false` and `undefined` are left out,
+* an array repeats the flag, and a value is single-quoted when the shell would read it otherwise.
+*
+* @param path the command path as a user types it, without the cli name.
+* @param options the options to pass, keyed by option name. Use {@link placeholder} for a value not known yet.
+* @param why what running it does, as a verb phrase: `Run \`…\` to <why>`.
+*
+* @example
+* ```ts
+* return result(task, { help: ref('task get', { gid: task.parent.gid }, 'show the parent task') })
+* ```
+*/
+function ref(path, options = {}, why) {
+	const words = path.trim().split(/\s+/).filter(Boolean);
+	if (words.length === 0) throw new TypeError("ref() needs a command path, such as \"task get\"");
+	return {
+		[refKey]: true,
+		path: words.join(" "),
+		options: { ...options },
+		why
+	};
+}
 function isRef(value) {
 	return typeof value === "object" && value !== null && value[refKey] === true;
 }
@@ -66,7 +94,7 @@ function shellQuote(value) {
 	return /^[\w./:@%+=,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/app/errors.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/app/errors.js
 var _a;
 /**
 * The exit codes a clibuilder cli uses, following the AXI convention so an agent
@@ -142,7 +170,7 @@ var CliError = class CliError extends Error {
 		super(report.message);
 		this.name = "CliError";
 		this[_a] = true;
-		this.exitCode = validateExitCode(report.exitCode ?? exitCodes.error);
+		this.exitCode = validateExitCode$1(report.exitCode ?? exitCodes.error);
 		this.code = validateCode(report.code ?? "error");
 		this.details = validateDetails(report.details ?? {});
 		const lines = report.help === void 0 ? [] : Array.isArray(report.help) ? [...report.help] : [report.help];
@@ -163,7 +191,7 @@ function helpLinesOf(err) {
 function isReportedCliError(err) {
 	return err[reportedBrand] === true;
 }
-function validateExitCode(exitCode) {
+function validateExitCode$1(exitCode) {
 	if (Number.isInteger(exitCode) && exitCode >= 1 && exitCode <= 255) return exitCode;
 	throw new RangeError(`CliError exitCode must be an integer from 1 to 255, received ${exitCode}`);
 }
@@ -176,7 +204,7 @@ function validateDetails(details) {
 	return { ...details };
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/command/define.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/command/define.js
 /**
 * Defines a command with its argument and option types inferred.
 *
@@ -198,7 +226,7 @@ function command(cmd) {
 	return cmd;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/descriptor.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/descriptor.js
 /** Whether a descriptor option takes a value, as `args-minus` decides: a boolean or boolean literal is a flag. */
 function takesValue$1(data) {
 	const d = data.kind === "array" ? data.element : data;
@@ -228,7 +256,22 @@ function describeRange(min, max) {
 	return "";
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-minus@0.2.2/node_modules/args-minus/esm/t.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/props.js
+/** The property `key` of `object` itself, or `undefined` when only its prototype has one. */
+function getProp$1(object, key) {
+	return Object.prototype.hasOwnProperty.call(object, key) ? object[key] : void 0;
+}
+/** Sets `key` on `object` itself, even when the key is `__proto__`. */
+function setProp(object, key, value) {
+	Object.defineProperty(object, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+}
+//#endregion
+//#region ../../node_modules/.pnpm/args-minus@0.2.3/node_modules/args-minus/esm/t.js
 const descriptorBrand = Symbol.for("args-minus.descriptor");
 const descriptorVersion = 1;
 const methods = {
@@ -400,7 +443,7 @@ Array.prototype.reduce;
 const ArraySlice = Array.prototype.slice;
 const ArrayPush = Array.prototype.push;
 //#endregion
-//#region ../../node_modules/.pnpm/args-minus@0.2.2/node_modules/args-minus/esm/tokenize_args.js
+//#region ../../node_modules/.pnpm/args-minus@0.2.3/node_modules/args-minus/esm/tokenize_args.js
 const DEFAULT_GRAMMAR = {
 	modifiers: "-",
 	terminator: "--"
@@ -472,7 +515,7 @@ function tokenizeArgs(args, grammar) {
 	return tokens;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-minus@0.2.2/node_modules/args-minus/esm/parse_args.js
+//#region ../../node_modules/.pnpm/args-minus@0.2.3/node_modules/args-minus/esm/parse_args.js
 /**
 * Thrown when the input does not fit the declarations: a usage error the caller can fix.
 */
@@ -602,7 +645,7 @@ function* parse$1(config) {
 					const raw = names[i];
 					const isLast = i === names.length - 1;
 					const name = canonical.get(raw) ?? raw;
-					const declaration = declarations?.[name];
+					const declaration = declarations && getProp(declarations, name);
 					if (config.strict && !declaration) throw new ParseArgsError(`Unknown option '${raw}' (from '${token.raw}')`, raw, token.raw, { kind: "unknown-option" });
 					if (!isLast && declaration && takesValue(declaration)) throw new ParseArgsError(`Invalid option group '${token.raw}': '${raw}' takes a value, so it can only be the last option in a group`, name, token.raw, {
 						kind: "invalid-group",
@@ -666,6 +709,10 @@ function* parse$1(config) {
 	if (config.tokens) result.tokens = tokens;
 	return result;
 }
+/** The property `key` of `object` itself, or `undefined` when only its prototype has one. */
+function getProp(object, key) {
+	return Object.prototype.hasOwnProperty.call(object, key) ? object[key] : void 0;
+}
 function checkDeclarations(declarations) {
 	for (const [name, declaration] of Object.entries(declarations ?? {})) {
 		const type = declaration.type;
@@ -901,10 +948,10 @@ function* checkDefault(declaration, name) {
 	checkedDefaults.set(declaration, true);
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/invocation/argv_occurrences.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/invocation/argv_occurrences.js
 const optionOccurrences = /* @__PURE__ */ new WeakMap();
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/invocation/lookup.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/invocation/lookup.js
 /**
 * @param fallback a command whose options apply to every command (the global options).
 * It decides how many following tokens such an option takes,
@@ -986,13 +1033,13 @@ function assignOptionValues(rawArgs, command, fallback) {
 		});
 		positionals.push(...o.following.slice(count));
 		const own = o.inline.length + taken.length > 0 ? [...o.inline, ...taken] : ["true"];
-		values[o.key] = [...values[o.key] ?? [], ...own];
+		setProp(values, o.key, [...getProp$1(values, o.key) ?? [], ...own]);
 	}
 	const result = {
 		...rawArgs,
 		_: [...rawArgs._, ...positionals]
 	};
-	for (const key of Object.keys(values)) if (rawArgs[key]) result[key] = values[key];
+	for (const key of Object.keys(values)) if (getProp$1(rawArgs, key)) setProp(result, key, values[key]);
 	return [result, descriptorOccurrences];
 }
 function countFollowing(entry, o) {
@@ -1116,7 +1163,7 @@ function collectDescriptorOptions(state, occurrences) {
 function lookupOptions(command, key) {
 	const opts = command.options;
 	if (!opts) return [];
-	const options = opts[key];
+	const options = getProp$1(opts, key);
 	if (options) return [key, options];
 	const optKey = Object.keys(opts).find((k) => {
 		const opt = opts[k];
@@ -1180,6 +1227,25 @@ var RawString = class {
 		this.value = value;
 	}
 };
+/**
+* Wraps a pre-formatted string for verbatim emission, typically returned from
+* an encode `replacer`. Compose with `escapeString` to control quoting yourself.
+*
+* @param value The exact text to emit at the value position
+* @returns A `RawString` marker honored at primitive value positions
+*
+* @example
+* ```ts
+* encode({ name: 'Ada', age: 30 }, {
+*   replacer: (key, value) => rawString(`"${escapeString(String(value))}"`)
+* })
+* // name: "Ada"
+* // age: "30"
+* ```
+*/
+function rawString(value) {
+	return new RawString(value);
+}
 function isRawString(value) {
 	return value instanceof RawString;
 }
@@ -1674,7 +1740,7 @@ function resolveOptions(options) {
 	};
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/render/text.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/render/text.js
 /**
 * The `text` encoder, the same rendering as `@clibuilder/axi`'s `renderText`.
 * Imports nothing from the framework (axi-native RFC section 4.1).
@@ -1682,14 +1748,14 @@ function resolveOptions(options) {
 function isRecord$3(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function cell(value) {
+function cell$1(value) {
 	return value === void 0 ? "" : String(value);
 }
 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 widths = columns.map((column) => Math.max(column.length, ...rows.map((row) => cell$1(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]))))];
+	return [line(columns), ...rows.map((row) => line(columns.map((column) => cell$1(row[column]))))];
 }
 /**
 * Renders a value for a person: a key per line, a list of records as an aligned table, a list of values as bullets,
@@ -1708,7 +1774,7 @@ function renderText(value) {
 	}).join("\n");
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/render/encode.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/render/encode.js
 /**
 * The single place an answer is turned into text.
 * Imports nothing from the framework (axi-native RFC section 4.1).
@@ -1718,11 +1784,40 @@ const formats = [
 	"json",
 	"text"
 ];
-/** Encodes `value` in `format`, without a trailing newline. `toon` uses the official `@toon-format/toon` encoder. */
+/**
+* Encodes `value` in `format`, without a trailing newline.
+*
+* `toon` uses TOON only for collections (change 1 of the AXI conventions): an array, at any depth, is encoded
+* by the official `@toon-format/toon` encoder, and a string field outside any array is a plain `key: value` line.
+* The output is still TOON: a TOON decoder reads it back to the same value.
+*/
 function encode(value, format) {
 	if (format === "json") return JSON.stringify(value);
 	if (format === "text") return renderText(value);
-	return encode$1(value);
+	return encode$1(value, { replacer: plainLine });
+}
+function plainLine(_key, value, path) {
+	if (typeof value !== "string" || path.length === 0 || path.some((p) => typeof p === "number")) return value;
+	return readsBackAsIs(value) ? rawString(value) : value;
+}
+/**
+* Whether a TOON decoder reads `value`, written unquoted after `key: `, back as the same string.
+* Quoted are: the empty string, edge whitespace, control characters such as a newline, a leading `"`,
+* a leading `#` (the encoder keeps it for comments), and what reads as another type:
+* `true`, `false`, `null`, a number and `[]`.
+*/
+function readsBackAsIs(value) {
+	if (value === "" || value === "[]" || value.startsWith("\"") || value.startsWith("#")) return false;
+	if (/^\s|\s$/.test(value) || hasControlCharacter(value)) return false;
+	if (value === "true" || value === "false" || value === "null") return false;
+	return !/^[+-]?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i.test(value);
+}
+function hasControlCharacter(value) {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code < 32 || code === 127) return true;
+	}
+	return false;
 }
 /** The error as a flat value: `error`, `code`, the `details` fields, then `help` (left out when empty). Keys match `@clibuilder/axi`'s `errorOutput` and axi-sdk-js. */
 function errorOutput({ message, code, details, help }) {
@@ -1735,7 +1830,7 @@ function errorOutput({ message, code, details, help }) {
 	return output;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/builtin/base_command.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/builtin/base_command.js
 const globalFormat = Symbol.for("clibuilder.global-format");
 /**
 * Marks a command's own `format` option that gives way to the global `--format`:
@@ -1807,7 +1902,7 @@ function yieldToGlobalFormat(command) {
 	};
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/plugins/registry.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/plugins/registry.js
 /** Creates a key for a single value. `id` must be unique across extensions. */
 function defineKey(id) {
 	return {
@@ -1857,7 +1952,7 @@ function createRegistry() {
 	};
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/config/key.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/config/key.js
 /**
 * The shared-state key the `clibuilder/config` extension stores the resolved config under.
 *
@@ -1866,7 +1961,7 @@ function createRegistry() {
 */
 const configKey = defineKey("clibuilder.config");
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/invocation/argv.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/invocation/argv.js
 function parseArgv(argv) {
 	const occurrences = [];
 	const result = argv.slice(2).reduce((result, v) => {
@@ -1941,9 +2036,10 @@ function startMultiCharacterOptions(result, value) {
 function endOption(state) {
 	const { key, values } = state;
 	const args = { ...state.args };
-	if (!args[key]) args[key] = [];
-	if (values.length === 0) args[key].push("true");
-	else args[key].push(...values);
+	const list = getProp$1(args, key) ?? [];
+	if (values.length === 0) list.push("true");
+	else list.push(...values);
+	setProp(args, key, list);
 	return {
 		args,
 		key: "",
@@ -1951,7 +2047,7 @@ function endOption(state) {
 	};
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/invocation/descriptors.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/invocation/descriptors.js
 const declarations = /* @__PURE__ */ new WeakMap();
 /**
 * Converts and checks every declaration of the matched command through `args-minus`,
@@ -2003,7 +2099,7 @@ function configOf(input) {
 	};
 }
 function assign(result, input, { options }) {
-	if (options[input.name] !== void 0) result.args[input.name] = options[input.name];
+	if (options[input.name] !== void 0) setProp(result.args, input.name, options[input.name]);
 }
 function report$1(result, input, e) {
 	if (!(e instanceof ParseArgsError)) throw e;
@@ -2050,7 +2146,7 @@ function rawValues(input) {
 	return input.occurrences.map((o) => o.tokens.join(" "));
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/render/answer.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/render/answer.js
 /**
 * The result channel: what `run()` returns, and how it is printed under `output: 'axi'`.
 * Imports nothing from the framework (axi-native RFC section 4.1).
@@ -2063,19 +2159,31 @@ const answerKey = Symbol.for("clibuilder.answer");
 * inside it. A renderer for the format replaces the encoder: its string is written verbatim, and the
 * `help` follows it, encoded. `parse()` resolves to `value`.
 *
+* The cli exits with `exitCode`, 0 by default, in either output mode.
+* A non-zero one returns an answer that is also a failure, printed as a result rather than as an error.
+*
 * @example
 * ```ts
 * run() {
 * 	return result({ items }, { help: 'Run `my-cli show <id>` for one', render: { text: (v) => table(v.items) } })
 * }
 * ```
+*
+* @example
+* ```ts
+* run({ name }) {
+* 	const exists = panes.has(name)
+* 	return result({ exists }, { exitCode: exists ? exitCodes.success : exitCodes.error })
+* }
+* ```
 */
 function result(value, options = {}) {
 	return {
 		[answerKey]: "result",
 		value,
 		help: helpLines(options.help),
-		render: options.render
+		render: options.render,
+		exitCode: validateExitCode(options.exitCode)
 	};
 }
 /**
@@ -2083,11 +2191,13 @@ function result(value, options = {}) {
 * whatever the format, ending on a newline. `parse()` resolves to `content`.
 *
 * For output that is already the answer, such as Markdown, a diff or a file.
+* The cli exits with `exitCode`, 0 by default, in either output mode.
 */
-function document(content) {
+function document(content, options = {}) {
 	return {
 		[answerKey]: "document",
-		value: String(content)
+		value: String(content),
+		exitCode: validateExitCode(options.exitCode)
 	};
 }
 /**
@@ -2115,6 +2225,15 @@ function answerValue(returned) {
 	return isAnswer(returned) ? returned.value : returned;
 }
 /**
+* The code the cli exits with for what `run()` returned: the `exitCode` of a `result()` or `document()`, otherwise 0.
+* Read field by field: an answer from an older copy of clibuilder has no `exitCode`.
+*/
+function answerExitCode(returned) {
+	if (!isAnswer(returned)) return 0;
+	const code = returned.exitCode;
+	return typeof code === "number" ? code : 0;
+}
+/**
 * The text written on stdout for what `run()` returned, ending on one newline, or `undefined` when nothing is printed.
 * A string is written verbatim, an object is encoded, and an array or scalar is encoded under the `result` key
 * so `help` has a place beside it.
@@ -2122,18 +2241,22 @@ function answerValue(returned) {
 function printAnswer(returned, format, options = {}) {
 	if (returned === void 0) return void 0;
 	const tail = (lines) => renderHelp(lines, options.resolve, options.refs);
+	const withVerbs = (value, lines) => options.verbs && !hasOwnCommands(value) ? [...lines, options.verbs] : lines;
 	if (!isAnswer(returned)) return print(returned, tail([]), format);
 	switch (returned[answerKey]) {
 		case "written": return;
 		case "document": return line(returned.value);
-		case "empty": return line(encode(withHelp({ empty: returned.value }, tail(returned.help)), format));
+		case "empty": return line(encode(withHelp({ empty: returned.value }, tail(withVerbs(returned.value, returned.help))), format));
 		case "result": {
 			const render = returned.render?.[format];
-			if (render) return withRenderedHelp(render(returned.value), tail(returned.help), format);
-			return print(returned.value, tail(returned.help), format);
+			if (render) return withRenderedHelp(render(returned.value), tail(withVerbs(returned.value, returned.help)), format);
+			return print(returned.value, tail(withVerbs(returned.value, returned.help)), format);
 		}
 	}
 }
+function hasOwnCommands(value) {
+	return typeof value === "object" && value !== null && "commands" in value;
+}
 function print(value, tail, format) {
 	if (typeof value === "string") return withRenderedHelp(value, tail, format);
 	return line(encode(withHelp(toRecord(value), tail), format));
@@ -2164,11 +2287,16 @@ function helpLines(help) {
 	if (help === void 0) return [];
 	return Array.isArray(help) ? [...help] : [help];
 }
+function validateExitCode(exitCode) {
+	if (exitCode === void 0) return 0;
+	if (Number.isInteger(exitCode) && exitCode >= 0 && exitCode <= 255) return exitCode;
+	throw new RangeError(`an answer's exitCode must be an integer from 0 to 255, received ${exitCode}`);
+}
 function line(text) {
 	return text.endsWith("\n") ? text : `${text}\n`;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/render/error.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/render/error.js
 /** Describes one `lookupCommand` error in the terms the caller used. `command` tells an argument name from an option name. */
 function formatLookupError(error, command) {
 	switch (error.type) {
@@ -2196,7 +2324,7 @@ function toArray$1(value) {
 	return Array.isArray(value) ? value : [value];
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/render/wrap.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/render/wrap.js
 /**
 * Wraps `text` at `width` columns, breaking only between words; a longer word stays whole.
 * A tab counts as four spaces.
@@ -2219,15 +2347,19 @@ function wrap(text, width) {
 	return lines.join("\n");
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/render/help.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/render/help.js
 const RIGHT_PADDING = 2;
 const MIN_LHS_WIDTH = 25;
-function generateHelpMessage(cliName, command) {
+/**
+* `signatures` lists a group's sub-commands with their full signatures (AXI change 2).
+* Left off, the list is names only, as `output: 'console'` has always printed it.
+*/
+function generateHelpMessage(cliName, command, options) {
 	return `
 ${[
 		generateUsageSection(cliName, command),
 		generateDescriptionSection(command),
-		generateCommandsSection(command),
+		generateCommandsSection(command, options?.signatures ?? false),
 		generateArgumentsSection(command),
 		generateOptionsSection(command),
 		generateAliasSection(command),
@@ -2241,12 +2373,23 @@ function generateUsageSection(cliName, command) {
 	const hasCommand = command.commands && command.commands.length > 0;
 	let message = `Usage: ${nameChain.join(" ")}${hasCommand ? " <command>" : ""}`;
 	if (command.arguments) message += command.arguments.some((a) => isRequired(a, true)) ? " <arguments>" : " [arguments]";
-	if (command.options) {
+	if (hasOptions(command)) {
 		const options = command.options;
 		message += Object.keys(options).some((k) => isRequired(options[k], false)) ? " <options>" : " [options]";
 	}
 	return message;
 }
+function hasOptions(command) {
+	return !!command.options && Object.keys(command.options).length > 0;
+}
+/**
+* A sub-command as a bare group lists it: its name and its required arguments, such as `get <id>`
+* (AXI change 2: names and required arguments only).
+*/
+function commandSignature(command) {
+	const required = (command.arguments ?? []).filter((a) => isRequired(a, true)).map((a) => `<${a.name}>`);
+	return [command.name, ...required].join(" ");
+}
 function isRequired({ type, default: d }, defaultValue) {
 	if (!type) return defaultValue;
 	return !type.isOptional && d === void 0;
@@ -2262,22 +2405,37 @@ function getCommandNameChain(cliName, command) {
 	}
 	return [cliName, ...commands.map((c) => c.name).filter((x) => x)];
 }
-function generateCommandsSection(command) {
-	const commandNames = getCommandsNamesAndAlias(command.commands);
-	if (commandNames.length === 0) return "";
+/**
+* A sub-command as its group's `--help` lists it: name, alias, and the full signature of its
+* arguments and options, such as `add <name: string> [--force]` (AXI change 2: a node's --help is its schema).
+*/
+function commandFullSignature(command) {
+	const parts = [command.alias?.length ? `${command.name} (${command.alias.join("|")})` : command.name];
+	if (command.commands && command.commands.length > 0) parts.push("<command>");
+	for (const a of command.arguments ?? []) parts.push(a.type ? formatArgumentDescriptor(a.name, a.type) : `<${a.name}>`);
+	if (hasOptions(command)) {
+		const options = command.options;
+		for (const key in options) parts.push(formatKeyValue(key, options[key]));
+	}
+	return parts.join(" ");
+}
+function generateCommandsSection(command, signatures) {
+	const commands = command.commands ?? [];
+	if (commands.length === 0) return "";
+	if (!signatures) return `Commands:
+  ${wrap(commands.map((c) => c.alias ? `${c.name} (${c.alias.join("|")})` : c.name).join(", "), 80)}
+
+${(command.name ? `${command.name} <command> -h` : "  <command> -h").padEnd(MIN_LHS_WIDTH)}Get help for <command>`;
+	const sigs = commands.map(commandFullSignature);
+	const width = Math.max(23, ...sigs.map((x) => x.length + RIGHT_PADDING));
 	return `Commands:
-  ${wrap(commandNames.join(", "), 80)}
+${commands.map((c, i) => {
+		const line = c.description?.split("\n")[0] ?? "";
+		return `  ${sigs[i].padEnd(width)}${line}`.trimEnd();
+	}).join("\n")}
 
 ${(command.name ? `${command.name} <command> -h` : "  <command> -h").padEnd(MIN_LHS_WIDTH)}Get help for <command>`;
 }
-function getCommandsNamesAndAlias(commands) {
-	const result = [];
-	if (commands) commands.forEach((c) => {
-		if (c.alias) result.push(`${c.name} (${c.alias.join("|")})`);
-		else result.push(c.name);
-	});
-	return result;
-}
 function generateArgumentsSection(command) {
 	if (!command.arguments) return "";
 	let message = "Arguments:\n";
@@ -2293,14 +2451,15 @@ function generateArgumentsSection(command) {
 	return message;
 }
 function generateOptionsSection(command) {
-	if (!command.options) return "";
+	if (!hasOptions(command)) return "";
 	let message = "Options:\n";
 	const entries = [];
 	let maxOptionStrWidth = 0;
-	for (const key in command.options) {
-		const value = command.options[key];
+	const options = command.options;
+	for (const key in options) {
+		const value = options[key];
 		const optionStr = formatKeyValue(key, value);
-		const description = formatDescription(value, conflictsOf(key, command.options));
+		const description = formatDescription(value, conflictsOf(key, options));
 		entries.push([optionStr, description]);
 		maxOptionStrWidth = Math.max(maxOptionStrWidth, optionStr.length);
 	}
@@ -2396,7 +2555,13 @@ function generateHelpModel(cliName, command, globalOptions) {
 	if (command.description) model.description = command.description;
 	if (command.alias && command.alias.length > 0) model.aliases = [...command.alias];
 	if (command.commands && command.commands.length > 0) model.commands = command.commands.map((c) => {
-		const summary = { name: c.name };
+		const summary = {
+			name: c.name,
+			usage: commandFullSignature({
+				...c,
+				alias: void 0
+			})
+		};
 		if (c.alias && c.alias.length > 0) summary.aliases = [...c.alias];
 		const line = c.description?.split("\n")[0];
 		if (line) summary.description = line;
@@ -2420,7 +2585,12 @@ function generateHelpModel(cliName, command, globalOptions) {
 		command,
 		description
 	}));
-	model.globalOptions = optionModels(globalOptions, []);
+	if (isRoot) model.globalOptions = optionModels(globalOptions, []);
+	else {
+		const others = Object.keys(globalOptions).filter((k) => k !== "help" && k !== "format");
+		model.globalOptions = optionModels(globalOptions, others);
+		if (others.length > 0) model.otherGlobalOptions = others;
+	}
 	return model;
 }
 function optionModels(options, exclude) {
@@ -2470,8 +2640,42 @@ function describeData(data) {
 		default: return { type: data.kind };
 	}
 }
+/**
+* The structured help shaped for `toon`: each collection of rows becomes a uniform table.
+*
+* TOON writes an array as a table only when every row has the same keys and every cell is a scalar.
+* A row of the help model leaves out a key with nothing to say, and some keys hold an array,
+* so the collections fell back to list form. Here every row of a collection carries the union of its keys,
+* a missing one as `null`, and an array of scalars as one comma-joined string.
+* The `json` shape is unchanged: this is applied for `toon` only.
+*/
+function tabularHelpModel(model) {
+	const shaped = { ...model };
+	for (const key of [
+		"commands",
+		"arguments",
+		"options",
+		"examples",
+		"globalOptions"
+	]) {
+		const rows = model[key];
+		if (rows) shaped[key] = uniformRows(rows);
+	}
+	return shaped;
+}
+function uniformRows(rows) {
+	const keys = [];
+	for (const row of rows) for (const key of Object.keys(row)) if (!keys.includes(key)) keys.push(key);
+	return rows.map((row) => Object.fromEntries(keys.map((key) => [key, cell(row[key])])));
+}
+function cell(value) {
+	if (value === void 0) return null;
+	if (Array.isArray(value)) return value.map(String).join(",");
+	if (typeof value === "object" && value !== null) return JSON.stringify(value);
+	return value;
+}
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/render/usage_error.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/render/usage_error.js
 const rank = {
 	"invalid-key": 0,
 	"conflicting-options": 1,
@@ -2564,7 +2768,7 @@ function describeUsageError(error, command, cliName, hasHelp = true) {
 /** A command group invoked without its sub-command (#609): `missing-command`, with the valid sub-commands in `help`. */
 function describeMissingCommand(command, cliName) {
 	const name = commandName(command, cliName);
-	const commands = (command.commands ?? []).map((c) => c.name);
+	const commands = (command.commands ?? []).map(commandSignature);
 	return {
 		message: `missing command for \`${name}\``,
 		code: "missing-command",
@@ -2594,7 +2798,7 @@ function isOptional(type) {
 }
 function argumentsHelp(command, cliName) {
 	const name = command.name || cliName;
-	const commands = (command.commands ?? []).map((c) => c.name);
+	const commands = (command.commands ?? []).map(commandSignature);
 	if (!command.arguments?.length && commands.length > 0) return `valid commands for \`${name}\`: ${commands.join(", ")}`;
 	const args = (command.arguments ?? []).map((a) => isOptional(a.type) ? `[${a.name}]` : `<${a.name}>`);
 	return args.length > 0 ? `\`${name}\` takes: ${args.join(" ")}` : `\`${name}\` takes no arguments`;
@@ -2622,7 +2826,7 @@ function toArray(value) {
 	return Array.isArray(value) ? value : [value];
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/app/state.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/app/state.js
 function state(options) {
 	const { name, description = "", version } = options;
 	return {
@@ -2634,7 +2838,7 @@ function state(options) {
 	};
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/app/usage_errors.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/app/usage_errors.js
 /**
 * Looks the invocation up on the base command, the single source of truth for the global options.
 * A bad `--format` value falls back to `format`, so its usage error is reported in a valid format and cannot loop.
@@ -2693,7 +2897,7 @@ function withAllowedFormats(baseCommand) {
 	} : e;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/app/builder.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/app/builder.js
 function builder(context, options) {
 	const s = state(options);
 	const format = options.format ?? "toon";
@@ -2881,7 +3085,7 @@ function builder(context, options) {
 				for (const hook of beforeRunHooks) await hook(run);
 			} catch (e) {
 				if (!isCliError(e)) throw e;
-				reportCliError(e, globals.format, ui);
+				reportCliError(e, globals.format, ui, command);
 				return exit(e.exitCode);
 			}
 			s.config = run.config;
@@ -2897,16 +3101,16 @@ function builder(context, options) {
 			commandInstance.ui.showVersion = () => writeVersion();
 		}
 		try {
-			return answer(await commandInstance.run(args), globals.format);
+			return answer(await commandInstance.run(args), globals.format, command);
 		} catch (e) {
 			if (!isCliError(e)) throw e;
-			reportCliError(e, globals.format, commandInstance.ui);
+			reportCliError(e, globals.format, commandInstance.ui, command);
 			return exit(e.exitCode);
 		}
 	}
-	function reportCliError(e, format, ui) {
+	function reportCliError(e, format, ui, command) {
 		if (isReportedCliError(e)) return;
-		const { help } = renderHelp(helpLinesOf(e), resolveRef);
+		const { help } = renderHelp(helpLinesOf(e), (r) => resolveRef(r, command));
 		if (output === "axi") {
 			const report = errorOutput({
 				message: e.message,
@@ -2924,36 +3128,72 @@ function builder(context, options) {
 	function writeReport(report, format) {
 		context.writeStdout(`${encode(errorOutput(report), format)}\n`);
 	}
-	function answer(returned, format) {
+	function answer(returned, format, command) {
 		if (output === "axi") {
+			const verbs = command?.commands?.length ? `valid commands for \`${commandName(command, s.name)}\`: ${command.commands.map(commandSignature).join(", ")}` : void 0;
 			const text = printAnswer(returned, format, {
-				resolve: resolveRef,
-				refs
+				resolve: (r) => resolveRef(r, command),
+				refs,
+				verbs
 			});
 			if (text !== void 0) context.writeStdout(text);
 		}
+		const code = answerExitCode(returned);
+		if (code !== exitCodes.success) context.exit(code);
 		return answerValue(returned);
 	}
-	function writeHelp(command, baseCommand, format) {
-		context.writeStdout(format === "text" ? `${generateHelpMessage(s.name, command)}\n` : `${encode(generateHelpModel(s.name, command, baseCommand.options), format)}\n`);
+	function helpModel(command, baseCommand, format) {
+		const model = generateHelpModel(s.name, command, baseCommand.options);
+		return format === "toon" ? tabularHelpModel(model) : model;
 	}
-	function resolveRef(ref) {
-		let command = s.command;
-		for (const word of ref.path.split(" ")) {
-			const next = command.commands?.find((c) => c.name === word || c.alias?.includes(word));
-			if (!next) throw new TypeError(`ref('${ref.path}'): ${s.name} has no command "${ref.path}"`);
-			command = next;
+	function writeHelp(command, baseCommand, format) {
+		context.writeStdout(format === "text" ? `${generateHelpMessage(s.name, command, { signatures: true })}\n` : `${encode(helpModel(command, baseCommand, format), format)}\n`);
+	}
+	function resolveRef(ref, from) {
+		const words = ref.path.split(" ");
+		let found;
+		for (const scope of scopesOf(from)) {
+			const command = walk(scope, words);
+			if (command) {
+				found = {
+					command,
+					scope
+				};
+				break;
+			}
 		}
+		if (!found) throw new TypeError(`ref('${ref.path}'): ${s.name} has no command "${ref.path}"`);
+		const { command, scope } = found;
 		for (const name of Object.keys(ref.options)) {
 			if (command.options?.[name] || s.command.options?.[name]) continue;
 			throw new TypeError(`ref('${ref.path}'): the command has no option "${name}"`);
 		}
 		return [
 			s.name,
+			...pathOf(scope),
 			ref.path,
 			...refArgs(ref)
 		].join(" ");
 	}
+	function scopesOf(from) {
+		const scopes = [];
+		for (let c = from?.parent; c?.parent; c = c.parent) scopes.push(c);
+		scopes.push(s.command);
+		return scopes;
+	}
+	function walk(scope, words) {
+		let command = scope;
+		for (const word of words) {
+			command = command.commands?.find((c) => c.name === word || c.alias?.includes(word));
+			if (!command) return void 0;
+		}
+		return command;
+	}
+	function pathOf(command) {
+		const words = [];
+		for (let c = command; c?.parent; c = c.parent) words.unshift(c.name);
+		return words;
+	}
 	function writeVersion() {
 		context.writeStdout(`${s.version || "not versioned"}\n`);
 	}
@@ -3018,7 +3258,7 @@ function adjustCommand(base, command) {
 	return command;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/drivers/logger.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/drivers/logger.js
 function createBuilderUI(ui) {
 	let pending = true;
 	const entries = [];
@@ -3042,7 +3282,7 @@ function createBuilderUI(ui) {
 	};
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/drivers/stream_ui.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/drivers/stream_ui.js
 /**
 * Which stream each `ui` method writes to, per output mode. Internal: a cli picks a preset
 * with `cli({ output })`, never a table (axi-native RFC section 3.10).
@@ -3119,7 +3359,7 @@ function formatLine(args, colors) {
 	return args.map((v) => typeof v === "object" && v !== null ? inspect(v, { colors }) : v).join(" ");
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/drivers/streams.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/drivers/streams.js
 /**
 * The stdout and stderr driver: where every byte the cli writes goes through.
 *
@@ -3173,7 +3413,7 @@ function handleEpipe(stream) {
 	});
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/drivers/context.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/drivers/context.js
 /** Creates the app context: the built-in ui writing to `streams` as `output` routes it. */
 function context(options = {}) {
 	const cwd = process.cwd();
@@ -3197,7 +3437,7 @@ function context(options = {}) {
 	};
 }
 //#endregion
-//#region ../../node_modules/.pnpm/clibuilder@12.1.1_js-yaml@4.3.2/node_modules/clibuilder/esm/cli.js
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/cli.js
 function cli(options) {
 	return builder(context({
 		streams: options.streams,
@@ -3205,37 +3445,76 @@ function cli(options) {
 	}), options);
 }
 //#endregion
-//#region src/command-output/command-output.ts
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/axi/home.js
+/** Shortens a path under the home directory to `~/...`: fewer tokens, and no user name in the output. */
+function collapseHome$2(path, home = homedir()) {
+	const rest = path.slice(home.length);
+	if (!home || !path.startsWith(home) || rest !== "" && rest[0] !== "/" && rest[0] !== "\\") return path;
+	return `~${rest}`;
+}
 /**
-* 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.
+* The first lines of a CLI's home view — what it prints when run with no arguments — so an agent
+* knows which tool answered: `bin: ~/.local/bin/my-cli` and `description: ...`.
+*
+* Spread it in front of the live content the home view shows:
+*
+* @example
+* ```ts
+* return result({ ...homeHeader({ description: 'Manage plugins' }), plugins })
+* ```
 */
-function fail(error, fallback) {
-	if (isCliError(error)) throw error;
-	process.stderr.write(`error: ${error instanceof Error ? error.message : fallback}\n`);
-	throw CliError.reported(exitCodes.error);
+function homeHeader(options) {
+	return {
+		bin: collapseHome$2(options.bin ?? process.argv[1] ?? "", options.home ?? homedir()),
+		description: options.description
+	};
 }
+//#endregion
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/axi/truncate.js
 /**
-* An answer that comes with a failing exit code. The cli prints only an answer a command returns, and
-* a thrown error replaces the return, so the answer is printed first.
+* Keeps the first `limit` items and counts the rest, so the reader knows whether it saw everything
+* without another call.
+*
+* `count` reads `30 of 847 total`. The kept list's own length (`items[30]` in TOON) stays the
+* number of rows shown, so a header never claims rows that are not there.
 */
-function answerThenFail(answer, format) {
-	const text = printAnswer(answer, format);
-	if (text !== void 0) process.stdout.write(text);
-	throw CliError.reported(exitCodes.error);
+function truncateList(items, options) {
+	const total = items.length;
+	const kept = options.full ? [...items] : items.slice(0, options.limit);
+	return {
+		items: kept,
+		count: `${kept.length} of ${total} total`,
+		total,
+		truncated: kept.length < total
+	};
 }
+//#endregion
+//#region ../../node_modules/.pnpm/clibuilder@12.3.0_js-yaml@4.3.2/node_modules/clibuilder/esm/axi.js
 /**
-* AXI §10: collapses the home directory to `~` so a path in a report is portable to another
-* machine.
+* `clibuilder/axi`: helpers that shape the value a command returns for an agent.
+*
+* Core already renders errors, usage errors and results the AXI way.
+* This subpath adds truncation, counts, the empty state and the home header,
+* plus the result channel and exit codes so one import covers a command.
+*
+* It also works without `cli()`: `encode`, `errorOutput` and `printAnswer` are the output contract,
+* and `runScript` runs a command headless, for a script that is not a cli.
 */
-function collapseHome$1(home, path) {
-	return home && path.startsWith(home + sep) ? `~${path.slice(home.length)}` : path;
-}
-function displayBinPath(home, executable) {
-	return executable ? collapseHome$1(home, executable) : "buddy-agent-harness";
-}
+/**
+* The `--full` option: the escape hatch from truncation. Add it to a command's options, and pass
+* `args.full` to {@link truncateText} and {@link truncateList}.
+*
+* @example
+* ```ts
+* options: { full: fullOption }
+* ```
+*/
+const fullOption = {
+	type: t.boolean().optional(),
+	description: "Show the complete output instead of truncating it"
+};
 //#endregion
-//#region ../../node_modules/.pnpm/cyber-agentkit@2.0.0_clibuilder@12.1.1_js-yaml@4.3.2_/node_modules/cyber-agentkit/dist/reference-where-CVmGFOwR.js
+//#region ../../node_modules/.pnpm/cyber-agentkit@2.2.0_clibuilder@12.3.0_js-yaml@4.3.2_/node_modules/cyber-agentkit/dist/reference-where-C93SAYP9.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /** Read a file, or `undefined` when it does not exist. Other read errors are thrown. */
@@ -11611,7 +11890,15 @@ const referenceCodes = {
 	},
 	"reference-renamed": {
 		kind: "warning",
-		when: "a name or file under an older name, or an interface's older id (R96, R97)"
+		when: "a name or file under an older name, an interface's older id, or a name a plugin's rename table renames (R96, R97, R120)"
+	},
+	"rename-invalid": {
+		kind: "warning",
+		when: "a plugin's rename table, or an entry of it, that is not a pair of bare reference names (R120)"
+	},
+	"reference-legacy-format": {
+		kind: "warning",
+		when: "a contribution in a form version 1 wrote and 2.0 retired, which `reference migrate` rewrites (R119)"
 	},
 	"alias-not-used": {
 		kind: "warning",
@@ -11659,7 +11946,7 @@ const referenceCodes = {
 	},
 	"interface-unknown": {
 		kind: "refused",
-		when: "`implementations` of an unknown interface (R35)"
+		when: "`implementations` of an unknown interface (R35), or of a family matching none; `customize` of a family matching none (R135)"
 	},
 	"template-title": {
 		kind: "refused",
@@ -11719,7 +12006,7 @@ const referenceCodes = {
 	},
 	"name-invalid": {
 		kind: "usage",
-		when: "a write given a string that is not a name, such as `../x` (J1, R1)"
+		when: "a write given a string that is not a name, such as `../x` (J1, R1); `*` anywhere but the last segment of a family (R136)"
 	},
 	"reference-qualified": {
 		kind: "usage",
@@ -12042,6 +12329,19 @@ const namePattern$1 = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/i;
 const defaultSuffix = ".default";
 /** The suffix a metadata file's name carries before `.md` (K31); a name ending in it is reserved for that file. */
 const metadataSuffix = ".meta";
+/** Whether a value is written as a family: it ends in `.*`. Its prefix may still be invalid (R136). */
+function isFamilyName(value) {
+	return value.endsWith(".*");
+}
+/**
+* The prefix of a family (K39), or why the value is not one. `*` anywhere but the last segment, a
+* qualified or file-like prefix, or an empty prefix makes the name invalid (R136).
+*/
+function parseFamily(value) {
+	const prefix = value.slice(0, -2);
+	if (!isFamilyName(value) || !prefix || prefix.includes("*") || !namePattern$1.test(prefix)) return { invalid: `"${value}" is not a family. A family is \`<prefix>.*\`, with \`*\` only as the last segment and a prefix of letters, digits, hyphens, and dots.` };
+	return { prefix };
+}
 /** No name at all is a usage error (`name-missing`), unlike a string that is not a name, which is `invalid`. */
 function requireName(value) {
 	if (!value.trim()) throw new ReferenceFailure("name-missing", "name a reference.", { help: "Run `reference list` for every name." });
@@ -12060,6 +12360,7 @@ function parseReferenceName(value) {
 	if (value.endsWith(".md")) return invalid(`"${value}" names a file. Ask for the reference by name, without the .md extension.`);
 	const extension = dataExtensions.find((item) => value.endsWith(item.extension));
 	if (extension) return invalid(`"${value}" names a file. Ask for the reference by name, without the ${extension.extension} extension.`);
+	if (value.includes("*")) return invalid(`"${value}" is not a reference name: \`*\` makes a family, \`<prefix>.*\`, which only customize and implementations take.`);
 	const parts = value.split("/");
 	if (parts.length > 2 || value.includes("\\")) return invalid(`"${value}" is a path. A name is letters, digits, hyphens, and dots, optionally after "<plugin>/".`);
 	const [first, second] = parts;
@@ -12112,11 +12413,12 @@ function parseDocument(raw, warn) {
 		body
 	};
 }
-/** The contribution's own `merge`; `undefined` when it writes none. An unknown value reads as `patch`. */
+/** The contribution's own `merge`; `undefined` when it writes none. An unknown or version 1 value reads as `patch`. */
 function readMergeOperation(metadata, warn) {
 	const value = metadata["merge"];
 	if (value === void 0) return void 0;
 	if (isMergeOperation(value)) return value;
+	if (value === "merge-sections" || value === "first-wins") return "patch";
 	warn("merge-unknown", `unknown merge "${String(value)}"; read as patch`);
 	return "patch";
 }
@@ -12473,6 +12775,184 @@ function pickSections(body, picks) {
 		missing
 	};
 }
+const legacyMerges = {
+	"merge-sections": void 0,
+	"first-wins": "replace"
+};
+function isLegacyMerge(value) {
+	return value === "merge-sections" || value === "first-wins";
+}
+/** The plugins `overrides` names, each qualified entry reduced to its plugin; `undefined` when it is not a list of them. */
+function overriddenPlugins(value) {
+	const list = typeof value === "string" ? [value] : Array.isArray(value) ? value : void 0;
+	if (!list?.length || !list.every((item) => typeof item === "string" && item.trim())) return void 0;
+	return [...new Set(list.map((item) => item.split("/")[0].trim()))];
+}
+/** The plugin or `default` each `extends` step names, as written; `undefined` when it is not a list of steps. */
+function stepTargets(value) {
+	const list = typeof value === "string" ? [value] : Array.isArray(value) ? value : void 0;
+	if (!list) return void 0;
+	const targets = [];
+	for (const item of list) if (typeof item === "string") targets.push(item);
+	else if (isRecord$1(item) && Object.keys(item).length === 1) targets.push(Object.keys(item)[0]);
+	else return void 0;
+	return targets;
+}
+const flow = (items) => `[${items.join(", ")}]`;
+/**
+* The legacy forms a Markdown contribution's frontmatter holds (K37), and the frontmatter that says
+* the same in 2.0 (R122). The body and every other key are left as written.
+*/
+function legacyRewrite(metadata, body, place, name) {
+	const findings = [];
+	const keys = {};
+	const merge = metadata["merge"];
+	if (isLegacyMerge(merge)) {
+		const into = legacyMerges[merge];
+		keys["merge"] = place === "project" ? void 0 : into;
+		findings.push({
+			form: merge,
+			from: `merge: ${merge}`,
+			to: place === "project" ? "no merge: a project section carries none" : into === void 0 ? "no merge: patch is the default" : `merge: ${into}`,
+			reads: "it reads as patch"
+		});
+	}
+	if ("overrides" in metadata) findings.push(overridesFinding(metadata, place, keys));
+	if (place === "project" && metadata["extends"] !== void 0 && !hasBody(body)) {
+		const steps = stepTargets(metadata["extends"]);
+		findings.push({
+			form: "project-selection",
+			from: `extends: ${steps ? flow(steps) : JSON.stringify(metadata["extends"])}`,
+			manual: `a pick now applies to the whole repository: run \`reference customize ${name} --extends ${steps?.join(" ") ?? "<step>..."}\` at the root, then delete this file`,
+			reads: "its extends is ignored"
+		});
+	}
+	return {
+		findings,
+		keys
+	};
+}
+function overridesFinding(metadata, place, keys) {
+	const value = metadata["overrides"];
+	const plugins = overriddenPlugins(value);
+	const from = `overrides: ${plugins ? flow(Array.isArray(value) ? value : [String(value)]) : JSON.stringify(value)}`;
+	const reads = "it is ignored";
+	if (place === "project") {
+		keys["overrides"] = void 0;
+		return {
+			form: "overrides",
+			from,
+			to: "removed: a project section carries no extends",
+			reads
+		};
+	}
+	if (!plugins) return {
+		form: "overrides",
+		from,
+		manual: "`overrides` is not a list of plugin names",
+		reads
+	};
+	const written = metadata["extends"];
+	if (written === void 0) {
+		keys["overrides"] = void 0;
+		keys["extends"] = plugins;
+		return {
+			form: "overrides",
+			from,
+			to: `extends: ${flow(plugins)}`,
+			reads
+		};
+	}
+	const targets = stepTargets(written);
+	const missing = plugins.filter((plugin) => !targets?.includes(plugin));
+	if (targets && !missing.length) {
+		keys["overrides"] = void 0;
+		return {
+			form: "overrides",
+			from,
+			to: "removed: extends already names each plugin",
+			reads
+		};
+	}
+	return {
+		form: "overrides",
+		from,
+		manual: `\`extends\` is also written and does not name ${missing.join(", ")}; add ${missing.length > 1 ? "them" : "it"} to \`extends\` where it belongs, then remove \`overrides\``,
+		reads
+	};
+}
+/** The 2.0 form of a skill's default in the old layout (K37). */
+function defaultLayoutFinding(name) {
+	return {
+		form: "default-layout",
+		from: `references/${name}.md`,
+		to: `references/${name}.default.md`,
+		reads: "it is not read as the default"
+	};
+}
+/** The warning a legacy form raises at load (R119): the form, how it reads, its 2.0 form, and the fix. */
+function warnLegacy(finding, fix, warn) {
+	const note = finding.note === void 0 ? "" : `, and ${finding.note}`;
+	const into = finding.to === void 0 ? "" : `; its 2.0 form is ${finding.to}${note}`;
+	const how = finding.manual === void 0 ? fix : `To fix it, ${finding.manual}${finding.note === void 0 ? "" : `; ${finding.note}`}.`;
+	warn("reference-legacy-format", `\`${finding.from}\` is a version 1 form, and ${finding.reads}${into}. ${how}`);
+}
+function directoryEntries(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+	} catch {
+		return [];
+	}
+}
+/**
+* The qualified-name overrides a tier or project folder holds, of `name` when given. A subfolder
+* holding `README.md` is a reference in folder form, not a plugin's, so its files are left alone.
+*/
+function qualifiedOverrides(dir, name) {
+	const found = [];
+	for (const folder of directoryEntries(dir)) {
+		const plugin = folder.name;
+		if (!folder.isDirectory() || !namePattern$1.test(plugin)) continue;
+		const files = directoryEntries(join(dir, plugin));
+		if (files.some((file) => file.name === "README.md")) continue;
+		for (const file of files) {
+			if (!file.isFile() || !file.name.endsWith(".md")) continue;
+			const held = file.name.slice(0, -3);
+			if (!namePattern$1.test(held) || held.endsWith(".default") || held.endsWith(".meta")) continue;
+			if (name !== void 0 && held !== name) continue;
+			found.push({
+				plugin,
+				name: held,
+				path: join(dir, plugin, file.name),
+				file: `${plugin}/${file.name}`
+			});
+		}
+	}
+	return found;
+}
+const neverApplied = "no released version read it, so the override never applied";
+const turnsOn = "applying the plan turns it on";
+/**
+* The 2.0 form of a qualified-name override (K37): `<name>.md` beside the subfolder, with
+* `extends: [<plugin>]`. A project section carries no `extends` (K24), so there it is manual.
+*/
+function qualifiedOverrideFinding(found, place) {
+	const { plugin, name, file } = found;
+	const said = {
+		form: "qualified-override",
+		from: file,
+		reads: neverApplied,
+		note: turnsOn
+	};
+	if (place === "project") return {
+		...said,
+		manual: `pick plugin ${plugin} for the whole repository with \`reference customize ${name} --extends ${plugin}\` at the root, since a project section carries no extends; then move this file's body into ${name}.md in this folder and delete this file`
+	};
+	return {
+		...said,
+		to: `${name}.md with extends: [${plugin}]`
+	};
+}
 /** Keys a metadata file cannot carry: a non-Markdown contribution always replaces below (R68), and an interface's sections are Markdown. */
 const ignoredKeys$1 = ["merge", "implements"];
 /** The metadata file beside a contribution of `name` in a layer: `<name>.meta.md`, or a default's `<name>.default.meta.md`. */
@@ -12822,6 +13302,11 @@ function readContribution(layer, name, entry, { display, without, warnAt, older
 		const stray = join(layer.dir, `${name}${defaultSuffix}.md`);
 		if (stray !== without && tryRead$2(stray) !== void 0) warnAt(display(stray))("default-in-tier", "it is ignored: a default goes in a skill's references/ folder");
 	}
+	if (layer.tier === "repo" || layer.tier === "user") warnQualifiedOverrides$1(layer, name, {
+		display,
+		without,
+		warnAt
+	});
 	const owner = layer.tier === "plugin" || layer.tier === "default";
 	const [hit, ...ignored] = [name, ...owner ? [] : older].flatMap((as) => candidateFiles(layer, as).flatMap((file) => {
 		const path = join(layer.dir, file);
@@ -12849,6 +13334,11 @@ function readContribution(layer, name, entry, { display, without, warnAt, older
 		break;
 	}
 	if (hit && hit.as !== name) renamed(entry, hit.as, name, hit.path, display, warnAt);
+	if (!hit && !sidecar && layer.tier === "default") warnDefaultLayout(layer, name, {
+		display,
+		without,
+		warnAt
+	});
 	if (!hit) return sidecar ? sidecarSelection(layer, entry, sidecar, display, warnAt) : void 0;
 	const label = contributionLabel(layer, hit.path, display);
 	const warn = warnAt(label);
@@ -12878,6 +13368,8 @@ function readContribution(layer, name, entry, { display, without, warnAt, older
 		};
 	}
 	const { metadata, body } = parseDocument(hit.raw, warn);
+	const fix = legacyFix(layer, name, display);
+	for (const finding of legacyRewrite(metadata, body, "contribution", name).findings) warnLegacy(finding, fix, warn);
 	const merge = readMergeOperation(metadata, warn);
 	const steps = readExtends(metadata["extends"], warn);
 	Object.assign(entry, {
@@ -12904,6 +13396,26 @@ function readContribution(layer, name, entry, { display, without, warnAt, older
 		steps
 	};
 }
+/** Who rewrites a legacy form, and how (R119): only a file `migrate` may change gets the command itself. */
+function legacyFix(layer, name, display) {
+	if (layer.tier === "plugin") return `Plugin ${layer.plugin}'s author rewrites it with \`reference migrate --plugin <its source folder>\`; until then, customize the name.`;
+	if (layer.tier === "default") return `Its skill's author rewrites it with \`reference migrate ${name} --default ${display(dirname(layer.dir))}\`.`;
+	if (layer.tier === "managed") return "An admin rewrites it; `reference migrate` never changes a managed file.";
+	return "Run `reference migrate` to rewrite it.";
+}
+/** A qualified-name override of the name in a tier folder is not read; each warns (R119). */
+function warnQualifiedOverrides$1(layer, name, { display, without, warnAt }) {
+	for (const found of qualifiedOverrides(layer.dir, name)) {
+		if (found.path === without) continue;
+		warnLegacy(qualifiedOverrideFinding(found, "contribution"), legacyFix(layer, name, display), warnAt(contributionLabel(layer, found.path, display)));
+	}
+}
+/** A skill's default in the old layout, `references/<name>.md`, is not read; it warns when the skill's folder has no default of the name (R119). */
+function warnDefaultLayout(layer, name, { display, without, warnAt }) {
+	const path = join(layer.dir, `${name}.md`);
+	if (path === without || tryRead$2(path) === void 0) return;
+	warnLegacy(defaultLayoutFinding(name), legacyFix(layer, name, display), warnAt(display(path)));
+}
 /** A file filed under an older name applies as the new one, with a warning naming the file to rename (R97). */
 function renamed(entry, as, name, path, display, warnAt) {
 	entry.alias = as;
@@ -13147,7 +13659,7 @@ function checkImplementation(iface, { name, version, content, accept = iface.ver
 		unsupported
 	};
 }
-const cache = /* @__PURE__ */ new WeakMap();
+const cache$1 = /* @__PURE__ */ new WeakMap();
 const quiet = () => () => {};
 function ownerLabel(owner) {
 	return owner.tier === "plugin" ? `plugin ${owner.plugin}` : `default of ${owner.skill}`;
@@ -13169,7 +13681,7 @@ function listed(value) {
 */
 function aliasIndex(source) {
 	const keyed = Array.isArray(source) ? void 0 : source;
-	const hit = keyed && cache.get(keyed);
+	const hit = keyed && cache$1.get(keyed);
 	if (hit) return hit;
 	const layers = Array.isArray(source) ? source : source.layers;
 	const byAlias = /* @__PURE__ */ new Map();
@@ -13209,16 +13721,15 @@ function aliasIndex(source) {
 					});
 					continue;
 				}
-				if (id !== void 0) {
-					push(interfaces, id, {
-						alias,
-						owner
-					});
-					continue;
+				if (id !== void 0) push(interfaces, id, {
+					alias,
+					owner
+				});
+				for (const older of id === void 0 ? [alias] : documentNames$1(alias, read.metadata)) {
+					push(byAlias, older, owner);
+					const known = byName.get(name) ?? [];
+					if (!known.includes(older)) byName.set(name, [...known, older]);
 				}
-				push(byAlias, alias, owner);
-				const older = byName.get(name) ?? [];
-				if (!older.includes(alias)) byName.set(name, [...older, alias]);
 			}
 		}
 	}
@@ -13229,9 +13740,18 @@ function aliasIndex(source) {
 		warnings,
 		interfaces
 	};
-	if (keyed) cache.set(keyed, index);
+	if (keyed) cache$1.set(keyed, index);
 	return index;
 }
+/**
+* The older names of an interface document that lists `alias` (R128): `<old id>.interface` always,
+* and `<old id>` itself when the interface is `many`, as no implementation of one is named `<old id>`.
+* For a `one` interface, `<old id>` is the implementation's older name (R96).
+*/
+function documentNames$1(alias, metadata) {
+	const block = metadata["interface"];
+	return isRecord$1(block) && block["cardinality"] === "many" ? [alias, `${alias}${interfaceSuffix}`] : [`${alias}${interfaceSuffix}`];
+}
 function aliasFile(read) {
 	return read.entry.frontmatter && read.whole ? read.path.replace(/\.[^./]+$/, ".meta.md") : read.path;
 }
@@ -13476,7 +13996,7 @@ function ignoredFolderOf(root, entry) {
 	const folder = segments.join("/");
 	return folder && isDirectory$3(join(root, ...segments, ...referencesPath)) ? folder : void 0;
 }
-function entries(dir) {
+function entries$1(dir) {
 	try {
 		return readdirSync(dir, { withFileTypes: true });
 	} catch {
@@ -13493,7 +14013,7 @@ function walk(root) {
 	const found = [];
 	const packages = [];
 	const visit = (relative) => {
-		const listing = entries(join(root, relative));
+		const listing = entries$1(join(root, relative));
 		if (relative && !relative.split("/").includes("node_modules")) {
 			if (listing.some((entry) => entry.isFile() && entry.name === "package.json")) packages.push(relative);
 		}
@@ -13504,8 +14024,8 @@ function walk(root) {
 				visit(child);
 				continue;
 			}
-			if (relative && entries(join(root, child, referencesPath[1])).length) found.push(relative);
-			for (const inner of entries(join(root, child))) if (inner.isDirectory() && inner.name !== referencesPath[1]) visit(`${child}/${inner.name}`);
+			if (relative && entries$1(join(root, child, referencesPath[1])).length) found.push(relative);
+			for (const inner of entries$1(join(root, child))) if (inner.isDirectory() && inner.name !== referencesPath[1]) visit(`${child}/${inner.name}`);
 		}
 	};
 	visit("");
@@ -13590,7 +14110,7 @@ function gitIgnores(root, path) {
 }
 /** One answer per discovery, so a run resolving many names reads each `package.json` once. */
 const found = /* @__PURE__ */ new WeakMap();
-function readJson$2(path) {
+function readJson$3(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -13601,7 +14121,7 @@ function declared(top, folders) {
 	const plugins = [];
 	for (const folder of folders) {
 		const manifestPath = join(top, ...folder.split("/"), "package.json");
-		const manifest = readJson$2(manifestPath);
+		const manifest = readJson$3(manifestPath);
 		for (const pkg of declaredDependencies(manifest)) {
 			const dir = packageDir(pkg, manifestPath);
 			const plugin = dir && pluginManifestName(dir);
@@ -13978,10 +14498,26 @@ function readPluginSection(name, found, read, result) {
 		plugin: plugin.plugin
 	});
 }
+/** A qualified-name override of the name in a project folder is not read; each warns (R119). */
+function warnQualifiedOverrides(name, folder, read) {
+	const { display, without, warnAt, listed } = read;
+	for (const found of qualifiedOverrides(folder.dir, name)) {
+		const hit = {
+			folder,
+			file: found.file,
+			as: name,
+			path: found.path,
+			relative: `${folder.folder}/.agents/references/${found.file}`
+		};
+		if (found.path === without || !listed(hit)) continue;
+		warnLegacy(qualifiedOverrideFinding(found, "project"), "", warnAt(`project ${display(found.path)}`));
+	}
+}
 /** The folder's own `.agents/references/<name>.md` or `<name>/README.md`, when git does not ignore it. */
 function readOwnSection(name, folder, ignored, read, result) {
 	const { trace, sections } = result;
 	const { format, display, without, warnAt, catalog, older, listed, dropping, managed } = read;
+	if (!ignored) warnQualifiedOverrides(name, folder, read);
 	const filed = [name, ...older].map((as) => filesFor(folder, as, without));
 	const markdown = filed.flatMap((files) => files.markdown);
 	const data = filed.flatMap((files) => files.data);
@@ -14017,9 +14553,14 @@ function readOwnSection(name, folder, ignored, read, result) {
 	const { metadata, body } = parseDocument(tryRead$2(hit.path) ?? "", warnAt(label));
 	row.frontmatter = metadata;
 	const kept = { ...metadata };
+	const legacy = legacyRewrite(metadata, body, "project", name).findings;
+	for (const finding of legacy) warnLegacy(finding, "Run `reference migrate` to rewrite it.", warnAt(label));
+	const warnedAsLegacy = new Set(legacy.flatMap(({ form }) => form === "project-selection" ? ["extends"] : form === "overrides" ? ["overrides"] : ["merge"]));
+	delete kept["overrides"];
 	for (const key of ignoredKeys) {
 		if (!(key in kept)) continue;
 		delete kept[key];
+		if (warnedAsLegacy.has(key)) continue;
 		warnAt(label)("project-section-key-ignored", `\`${key}\` is ignored in the project section for ${folder.folder}: a project section states only what differs in its folder`);
 	}
 	if (dropping) {
@@ -14102,6 +14643,88 @@ function projectSectionNames(root, cache, plugins = /* @__PURE__ */ new Set()) {
 	}
 	return [...held];
 }
+/** Every name a qualified-name override (K37) in a project folder below the root names, in a file git does not ignore. */
+function projectQualifiedNames(root, cache) {
+	const found = projectFolders(root, cache);
+	return found.folders.flatMap((folder) => qualifiedOverrides(folder.dir).filter(({ file }) => !found.listed || found.listed.has(`${folder.folder}/.agents/references/${file}`)).map(({ name }) => name));
+}
+/**
+* A plugin's rename table, in its `references/` folder (K38). A leading `_` is not a reference name,
+* so the file never answers one.
+*/
+const renameTableFile = "_renames.yaml";
+const cache = /* @__PURE__ */ new WeakMap();
+function bare(value) {
+	if (typeof value !== "string") return void 0;
+	const parsed = parseReferenceName(value.trim());
+	return parsed.invalid || parsed.plugin !== void 0 ? void 0 : parsed.name;
+}
+/**
+* Every rename table the plugin tier's plugins ship (R120, R124), read once per set of layers. Only
+* a plugin renames its names, so no other tier is read.
+*/
+function renameTable(source) {
+	const keyed = Array.isArray(source) ? void 0 : source;
+	const hit = keyed && cache.get(keyed);
+	if (hit) return hit;
+	const layers = Array.isArray(source) ? source : source.layers;
+	const byOld = /* @__PURE__ */ new Map();
+	const warnings = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const layer of layers) {
+		if (layer.tier !== "plugin" || layer.skipped || layer.plugin === void 0) continue;
+		const path = join(layer.dir, renameTableFile);
+		if (seen.has(path)) continue;
+		seen.add(path);
+		const raw = tryRead$2(path);
+		if (raw === void 0) continue;
+		const plugin = layer.plugin;
+		let value;
+		try {
+			value = (0, import_dist.parse)(raw);
+		} catch {
+			value = void 0;
+		}
+		if (value === null || value === void 0) {
+			if (raw.trim()) warnings.push({
+				code: "rename-invalid",
+				message: `plugin ${plugin}: ${path} is not YAML; it is ignored`
+			});
+			continue;
+		}
+		if (!isRecord$1(value)) {
+			warnings.push({
+				code: "rename-invalid",
+				message: `plugin ${plugin}: ${path} is not a mapping of older names to new names; it is ignored`
+			});
+			continue;
+		}
+		for (const [key, target] of Object.entries(value)) {
+			const from = bare(key);
+			const to = bare(target);
+			if (from === void 0 || to === void 0 || from === to) {
+				warnings.push({
+					code: "rename-invalid",
+					message: `plugin ${plugin}: the rename ${JSON.stringify(key)}: ${JSON.stringify(target)} in ${renameTableFile} is not a pair of bare reference names; it is ignored`
+				});
+				continue;
+			}
+			const list = byOld.get(from) ?? [];
+			if (!list.some((entry) => entry.to === to && entry.plugin === plugin)) list.push({
+				from,
+				to,
+				plugin
+			});
+			byOld.set(from, list);
+		}
+	}
+	const table = {
+		byOld,
+		warnings
+	};
+	if (keyed) cache.set(keyed, table);
+	return table;
+}
 function layersOf(source) {
 	return Array.isArray(source) ? {
 		layers: [...source],
@@ -14188,6 +14811,7 @@ function resolveAdjusted(input, source, { display = (path) => path, without, bel
 		resolvedAs: ref.name
 	};
 	const older = olderNames(ref.name, aliases, warn);
+	if (followed.kind === "own") warnTableRename(ref, source, aliases, warn);
 	const cut = below === void 0 ? -1 : all.findIndex((layer) => layer.dir === below);
 	const layers = cut === -1 ? all : all.slice(cut + 1);
 	const contributions = [];
@@ -14475,7 +15099,19 @@ function resolveInterface(ref, contributions, holders, defaultContribution, resu
 function referenceNames(source) {
 	return [...new Set(layersOf(source).layers.flatMap(layerNames))].sort((a, b) => a.localeCompare(b));
 }
-/** Every name each installed skill holds a default of, by name then skill. */
+/**
+* A load of a name a plugin's rename table lists as older (R120) answers as itself, with a warning
+* naming the new name. A name a plugin or a default still holds as its own is not renamed.
+*/
+function warnTableRename(ref, source, aliases, warn) {
+	if (aliases.owned.has(ref.name)) return;
+	const entries = (renameTable(source).byOld.get(ref.name) ?? []).filter((entry) => ref.plugin === void 0 || entry.plugin === ref.plugin);
+	if (!entries.length) return;
+	const by = [...new Set(entries.map(({ plugin }) => `plugin ${plugin}`))].join(" and ");
+	const targets = [...new Set(entries.map(({ to }) => `"${to}"`))].join(" or ");
+	warn("reference-renamed", `${by} renamed "${ref.name}" to ${targets}: load ${targets} instead, and run \`reference migrate\` to rename the files filed under "${ref.name}"`);
+}
+/** Every name each installed skill holds a default of, by name then skill. */
 function skillHoldings(source) {
 	return (Array.isArray(source) ? [] : source.skills?.skills ?? []).flatMap((skill) => layerNames(defaultLayer(skill.folder)).map((name) => ({
 		name,
@@ -14790,6 +15426,8 @@ const checkWarningClass = {
 	"reference-stale": "environment",
 	"reference-renamed": "environment",
 	"alias-not-used": "environment",
+	"rename-invalid": "environment",
+	"reference-legacy-format": "defect",
 	"alias-invalid": "defect",
 	"project-section-not-markdown": "project-section",
 	"reference-hidden": "environment",
@@ -14874,6 +15512,14 @@ function interfaceLookup(source, options = {}) {
 }
 function lookUp(id, source, options) {
 	const resolved = resolveReference(`${id}${interfaceSuffix}`, source, options);
+	const owner = interfaceIdOf(resolved.trace.alias?.resolvedAs ?? "");
+	if (owner !== void 0) {
+		const found = readFound(owner, resolved);
+		return found.value ? {
+			...found,
+			renamed: owner
+		} : found;
+	}
 	if (resolved.status === "missing") {
 		const owners = [...aliasIndex(source).interfaces].filter(([, aliases]) => aliases.some(({ alias }) => alias === id)).map(([owner]) => owner);
 		if (owners.length > 1) return lookupFailure(id, `${id} is an older id of ${owners.join(" and ")}; implement one of them by its own id`);
@@ -14903,13 +15549,15 @@ function readFound(id, resolved) {
 	const { value, problems } = readInterface(id, resolved.metadata ?? {});
 	return value ? { value } : lookupFailure(id, `${name} is malformed: ${problems.join("; ")}`);
 }
-function bareName$1(name) {
+/** The bare name a document answers as: the name an older one asked for resolves as (R96, R128), or the name itself. */
+function bareName$1(resolved) {
+	const name = resolved.trace.alias?.resolvedAs ?? resolved.name;
 	return name.slice(name.lastIndexOf("/") + 1);
 }
 /** What a composed document declares: an interface, an implementation, or neither. */
 function kindOf(resolved) {
 	const metadata = resolved.metadata ?? {};
-	if (interfaceIdOf(bareName$1(resolved.name)) !== void 0 || metadata["interface"] !== void 0) return "interface";
+	if (interfaceIdOf(bareName$1(resolved)) !== void 0 || metadata["interface"] !== void 0) return "interface";
 	return metadata["implements"] === void 0 ? "none" : "implementation";
 }
 /** The `compose` failure for the defects composing a document raised (UC6.8), if any. */
@@ -14935,7 +15583,7 @@ function checkResolved(resolved, lookup, accept) {
 	};
 	if (resolved.status !== "found") return result;
 	const { failures, warnings } = result;
-	const name = bareName$1(resolved.name);
+	const name = bareName$1(resolved);
 	const metadata = resolved.metadata ?? {};
 	if (kindOf(resolved) === "interface") {
 		const id = interfaceIdOf(name);
@@ -15052,7 +15700,7 @@ function checkReferences(source, options = {}) {
 	};
 	const lookup = interfaceLookup(source, rest);
 	const layers = Array.isArray(source) ? void 0 : source;
-	const sectionNames = new Set(layers?.root === void 0 ? [] : projectSectionNames(layers.root, layers.projects, heldPlugins(layers)));
+	const sectionNames = new Set(layers?.root === void 0 ? [] : [...projectSectionNames(layers.root, layers.projects, heldPlugins(layers)), ...projectQualifiedNames(layers.root, layers.projects)]);
 	const resolve = (name) => {
 		const ref = parseReferenceName(name);
 		const main = resolveReference(ref, source, resolveOptions);
@@ -15260,6 +15908,198 @@ function generatorBase(resolved, iface) {
 	if (stub !== void 0) base.stub = `${stub}\n`;
 	return base;
 }
+function firstLine(value) {
+	return typeof value === "string" ? value.split("\n")[0]?.trim() || "" : "";
+}
+/** Whether a name is in the interface's namespace but declares another interface that its name fits. */
+function belongsElsewhere(name, declared, id) {
+	return declared !== void 0 && declared !== id && (name === declared || name.startsWith(`${declared}.`));
+}
+/** The highest `repo` or `user` file with a body the document holds: what makes the bare name its own. */
+function ownTier(resolved) {
+	return resolved.trace.layers.find((layer) => (layer.tier === "repo" || layer.tier === "user") && layer.file && (layer.outcome === "used" || layer.outcome === "stale") && !layer.selection && !layer.empty)?.tier;
+}
+/** The plugins holding a file for the name, as read. */
+function holders(resolved) {
+	return [...new Set(resolved.trace.layers.flatMap(({ tier, plugin, file }) => tier === "plugin" && plugin !== void 0 && file ? [plugin] : []))];
+}
+function referenceImplementations(id, source, options = {}) {
+	return isFamilyName(id) || id.includes("*") ? familyImplementations(id, source, options) : interfaceImplementations(id, source, options);
+}
+/**
+* The interfaces a family names (K39): each interface document whose id starts with the prefix and a
+* dot, at any depth, never a plain document or an implementation (R130). Sorted by id. Throws
+* `name-invalid` for a malformed family (R136), and `interface-unknown` when none match (R135).
+*/
+function familyInterfaces(family, source, options = {}) {
+	const parsed = parseFamily(family);
+	if (parsed.invalid !== void 0) throw new ReferenceFailure("name-invalid", parsed.invalid);
+	const lookup = interfaceLookup(source, options);
+	const aliases = aliasIndex(source);
+	const ids = /* @__PURE__ */ new Set();
+	for (const name of referenceNames(source)) {
+		const id = interfaceIdOf(shownName(name, aliases));
+		if (id === void 0 || !id.startsWith(`${parsed.prefix}.`)) continue;
+		const value = lookup(id).value;
+		if (value) ids.add(value.id);
+	}
+	if (!ids.size) throw new ReferenceFailure("interface-unknown", `no interface document matches ${family}.`, { help: "Run `reference list` for the names found." });
+	return [...ids].sort((a, b) => a.localeCompare(b));
+}
+/** `implementations <prefix>.*`: each matched interface, in name order, as `implementations <id>` lists it (R134). */
+function familyImplementations(family, source, options = {}) {
+	return {
+		family,
+		interfaces: familyInterfaces(family, source, options).map((id) => interfaceImplementations(id, source, options))
+	};
+}
+function interfaceImplementations(id, source, options) {
+	const { accept: acceptOption, ...rest } = options;
+	const resolveOptions = {
+		...rest,
+		projectSections: false
+	};
+	const ifaceName = parseReferenceName(`${id}${interfaceSuffix}`);
+	if (ifaceName.invalid || ifaceName.plugin !== void 0) throw new ReferenceFailure("interface-unknown", `"${id}" is not an interface id.`);
+	const lookup = interfaceLookup(source, rest);
+	const iface = lookup(id);
+	const value = iface.value;
+	if (!value) throw new ReferenceFailure("interface-unknown", iface.failure?.message ?? `no interface ${id}`);
+	const aliases = aliasIndex(source);
+	const ids = [value.id, ...(aliases.interfaces.get(value.id) ?? []).map(({ alias }) => alias)];
+	const accept = [...acceptOption?.length ? acceptOption : value.versions];
+	const report = {
+		interface: value.id,
+		cardinality: value.cardinality,
+		accept,
+		implementations: [],
+		excluded: [],
+		warnings: []
+	};
+	const seen = /* @__PURE__ */ new Set();
+	const warn = (warnings) => {
+		for (const warning of warnings) {
+			const key = `${warning.code} ${warning.message}`;
+			if (!seen.has(key)) report.warnings.push(warning);
+			seen.add(key);
+		}
+	};
+	if (iface.renamed !== void 0) warn([{
+		code: "reference-renamed",
+		message: `${id} is an older id of ${value.id}; ask for ${value.id} instead`
+	}]);
+	const inNamespace = (name) => ids.some((each) => name === each || name.startsWith(`${each}.`));
+	/** Whether a resolved document is a candidate at all: it declares the interface, or its name is in the namespace. */
+	const relevant = (name, resolved) => {
+		const declared = readImplements(resolved.metadata ?? {}).entry?.id;
+		if (declared !== void 0 && ids.includes(declared)) return true;
+		return inNamespace(name) && !ids.some((each) => belongsElsewhere(name, declared, each));
+	};
+	const consider = ({ pin, name, resolved, tier }) => {
+		warn(resolved.warnings);
+		const declared = readImplements(resolved.metadata ?? {}).entry;
+		if (!declared || !ids.includes(declared.id)) {
+			const shape = fitsNamespace(value.cardinality, ids, name) ? "" : ` and is not named ${value.cardinality === "one" ? value.id : `${value.id}.<key>`}`;
+			report.excluded.push({
+				name: pin,
+				reasons: [`declares no implements ${value.id}@<version>${shape}`]
+			});
+			return;
+		}
+		const checked = checkResolved(resolved, lookup, {
+			id: value.id,
+			versions: accept
+		});
+		warn(checked.warnings);
+		if (checked.failures.length) {
+			report.excluded.push({
+				name: pin,
+				reasons: checked.failures.map(({ check, message }) => `${check}: ${message}`)
+			});
+			return;
+		}
+		report.implementations.push({
+			pin,
+			description: firstLine(resolved.metadata?.["description"]),
+			unsupported: checked.unsupported,
+			name,
+			tier,
+			version: declared.version
+		});
+	};
+	const qualified = (plugin, name) => resolveReference(parseReferenceName(`${plugin}/${name}`), source, resolveOptions);
+	const names = [...new Set(referenceNames(source).map((name) => shownName(name, aliases)))];
+	for (const name of names) {
+		if (interfaceIdOf(name) !== void 0) continue;
+		const resolved = resolveReference(name, source, resolveOptions);
+		if (resolved.status === "ambiguous") {
+			for (const option of resolved.options ?? []) {
+				if (option === "default") continue;
+				const copy = resolveReference(parseReferenceName(option), source, resolveOptions);
+				if (copy.status !== "found" || !relevant(name, copy)) continue;
+				warn(copy.warnings);
+				report.excluded.push({
+					name: option,
+					reasons: [`ambiguous: ${resolved.message}; each is left out until a customizer picks one`]
+				});
+			}
+			continue;
+		}
+		if (resolved.status !== "found" || !relevant(name, resolved)) continue;
+		const plugins = holders(resolved);
+		const tier = value.cardinality === "many" ? ownTier(resolved) : void 0;
+		if (tier !== void 0) {
+			consider({
+				pin: name,
+				name,
+				resolved,
+				tier
+			});
+			for (const plugin of plugins) report.excluded.push({
+				name: `${plugin}/${name}`,
+				reasons: [`the ${tier} implementation answers ${name}; a consumer loads it by that name`]
+			});
+			continue;
+		}
+		const pick = resolved.trace.stack.filter((target) => target !== "default").at(-1);
+		if (pick === void 0) continue;
+		consider({
+			pin: `${pick}/${name}`,
+			name,
+			resolved: qualified(pick, name),
+			tier: "plugin"
+		});
+		for (const plugin of plugins) {
+			if (plugin === pick) continue;
+			report.excluded.push({
+				name: `${plugin}/${name}`,
+				reasons: [`${name} loads the stack of ${pick}, the pick; load ${pick}/${name}`]
+			});
+		}
+	}
+	if (value.cardinality === "one") {
+		const inUse = implementationInUse(value.id, source, resolveOptions, report.implementations);
+		if (inUse !== void 0) report.inUse = inUse;
+	}
+	return report;
+}
+/**
+* The implementation a load of a `one` interface's name builds on (R129), read from the stack the
+* load composes: the pin of the listed candidate for the plugin it builds on, or `default` when only
+* the skill's default is in the stack. None when the name is not `found`, or the plugin it builds on
+* is not listed.
+*/
+function implementationInUse(id, source, options, listed) {
+	const resolved = resolveReference(parseReferenceName(id), source, options);
+	if (resolved.status !== "found") return void 0;
+	const pick = resolved.trace.stack.filter((target) => target !== "default").at(-1);
+	if (pick === void 0) return resolved.trace.stack.includes("default") ? "default" : void 0;
+	return listed.find(({ pin }) => pin === `${pick}/${id}`)?.pin;
+}
+/** Whether a name fits the interface's cardinality under its id or one of its older ids. */
+function fitsNamespace(cardinality, ids, name) {
+	return ids.some((id) => cardinality === "one" ? name === id : name.startsWith(`${id}.`) && name.length > id.length + 1);
+}
 /** A bare, valid name, or a refusal naming the bare name to use. */
 function bareName(value) {
 	requireName(value);
@@ -16071,13 +16911,91 @@ function after(result, plan, layers, options) {
 		}, options)
 	};
 }
+/** Whether a step, at any depth, gives `sections`: they differ per interface, so a family takes none (UC24.4). */
+function givesSections(value) {
+	if (Array.isArray(value)) return value.some(givesSections);
+	if (typeof value !== "object" || value === null) return false;
+	return Object.values(value).some((keys) => {
+		if (typeof keys !== "object" || keys === null || Array.isArray(keys)) return false;
+		const record = keys;
+		return record["sections"] !== void 0 || givesSections(record["extends"]);
+	});
+}
 /**
-* Customizes a name for the `repo` or `user` tier or a folder's project section, running no model:
-* writes the picks (a selection), or a body the generator wrote with its record, or, with `base`,
-* returns what the generator reads and writes nothing. Every check runs first, in the order
-* `validateWrite` gives; a file a contribution above hides is written all the same, with a warning.
+* Customizes every `one` interface of a family (K39) with the same steps (R131): for each, the file
+* `customize <id>` with those steps writes, in the tier asked. An interface no step can answer keeps
+* what it had (R132); a `many` interface is skipped (R133). Every interface is planned first, so a
+* refusal for any of them, a family matching none (R135), or a step giving `sections` leaves every
+* file as it was.
 */
+function customizeFamily(layers, args, options = {}) {
+	const parsed = parseFamily(args.name);
+	if (parsed.invalid !== void 0) throw new ReferenceFailure("name-invalid", parsed.invalid);
+	const usage = validateWrite({
+		command: "customize",
+		...args,
+		name: parsed.prefix
+	});
+	if ([
+		args.base,
+		args.request,
+		args.body,
+		args.implements,
+		args.merge
+	].some((value) => value !== void 0)) throw new ReferenceFailure("options-conflict", "a family takes only picks: --extends or --extends-file, with --scope and --dry-run; a body, a merge, or a base is per name.");
+	const picks = args.extendsFile === void 0 ? usage.picks : readExtendsFile(args.extendsFile);
+	if (picks !== void 0 && picks !== "none" && givesSections(picks.values)) throw new ReferenceFailure("step-invalid", `a step of ${args.name} gives sections, which differ per interface; pick for one interface at a time to change sections.`);
+	const lookup = interfaceLookup(layers, options);
+	const interfaces = familyInterfaces(args.name, layers, options).map((id) => {
+		if (lookup(id).value?.cardinality === "many") return {
+			interface: id,
+			outcome: "skipped",
+			reason: `${id} is a many interface, which has no single pick.`
+		};
+		const each = {
+			...args,
+			name: id
+		};
+		try {
+			const plan = validateWrite({
+				command: "customize",
+				...each
+			}, layers, options);
+			if (picks !== "none" && plan.base.status !== "found") return {
+				interface: id,
+				outcome: "kept",
+				reason: `no step holds ${id}; it keeps what it had.`
+			};
+		} catch (error) {
+			if (error instanceof ReferenceFailure && error.code === "step-invalid") return {
+				interface: id,
+				outcome: "kept",
+				reason: `${error.message} It keeps what it had.`
+			};
+			throw error;
+		}
+		return {
+			interface: id,
+			outcome: "written",
+			answer: each
+		};
+	}).map(({ answer, ...entry }) => answer === void 0 ? entry : {
+		...entry,
+		result: customizeSingle(layers, answer, options)
+	});
+	return {
+		family: args.name,
+		scope: args.scope ?? "repo",
+		dryRun: Boolean(args.dryRun),
+		interfaces
+	};
+}
 function customizeContribution(layers, args, options = {}) {
+	if (isFamilyName(args.name) || args.name.includes("*")) return customizeFamily(layers, args, options);
+	return customizeSingle(layers, args, options);
+}
+/** Customizes one name that is not a family. */
+function customizeSingle(layers, args, options) {
 	const plan = validateWrite({
 		command: "customize",
 		...args
@@ -16099,160 +17017,324 @@ function customizeContribution(layers, args, options = {}) {
 	if (plan.request !== void 0) return writeGenerated(plan, layers, result, options);
 	return writePicks(plan, layers, result, options);
 }
-function firstLine(value) {
-	return typeof value === "string" ? value.split("\n")[0]?.trim() || "" : "";
-}
-/** Whether a name is in the interface's namespace but declares another interface that its name fits. */
-function belongsElsewhere(name, declared, id) {
-	return declared !== void 0 && declared !== id && (name === declared || name.startsWith(`${declared}.`));
+const dataSuffixes = dataExtensions.map(({ extension }) => extension);
+function entries(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+	} catch {
+		return [];
+	}
 }
-/** The highest `repo` or `user` file with a body the document holds: what makes the bare name its own. */
-function ownTier(resolved) {
-	return resolved.trace.layers.find((layer) => (layer.tier === "repo" || layer.tier === "user") && layer.file && (layer.outcome === "used" || layer.outcome === "stale") && !layer.selection && !layer.empty)?.tier;
+function valid(name) {
+	return !parseReferenceName(name).invalid;
+}
+/** The files a place holds for each name, in the forms its tier answers. */
+function heldFiles(place) {
+	const held = [];
+	const isDefault = place.tier === "default";
+	const own = isDefault ? defaultSuffix : "";
+	for (const entry of entries(place.dir)) {
+		const file = entry.name;
+		const path = join(place.dir, file);
+		if (entry.isDirectory()) {
+			if (!isDefault && valid(file) && tryRead$2(join(path, "README.md")) !== void 0) held.push({
+				name: file,
+				path: join(path, "README.md"),
+				suffix: "/README.md",
+				kind: "markdown",
+				folderForm: true
+			});
+			continue;
+		}
+		if (file === "_renames.yaml") continue;
+		const metadata = `${own}${metadataSuffix}.md`;
+		if (file.endsWith(metadata)) {
+			const name = file.slice(0, -metadata.length);
+			if (valid(name)) held.push({
+				name,
+				path,
+				suffix: metadata,
+				kind: "metadata",
+				folderForm: false
+			});
+			continue;
+		}
+		const markdown = `${own}.md`;
+		if (file.endsWith(markdown)) {
+			const name = file.slice(0, -markdown.length);
+			if (valid(name)) held.push({
+				name,
+				path,
+				suffix: markdown,
+				kind: "markdown",
+				folderForm: false
+			});
+			continue;
+		}
+		const data = dataSuffixes.find((extension) => file.endsWith(`${own}${extension}`));
+		if (data) {
+			const name = file.slice(0, -`${own}${data}`.length);
+			if (valid(name)) held.push({
+				name,
+				path,
+				suffix: `${own}${data}`,
+				kind: "data",
+				folderForm: false
+			});
+		}
+	}
+	return held;
 }
-/** The plugins holding a file for the name, as read. */
-function holders(resolved) {
-	return [...new Set(resolved.trace.layers.flatMap(({ tier, plugin, file }) => tier === "plugin" && plugin !== void 0 && file ? [plugin] : []))];
+/** The places a run reads (R123): a source folder alone, or the `repo` and `user` tiers and every project section. */
+function placesOf(layers, root, options) {
+	if (options.plugin !== void 0 && options.default !== void 0) throw new ReferenceFailure("options-conflict", "pass one of --plugin and --default.");
+	if (options.plugin !== void 0) return [{
+		tier: "plugin",
+		dir: join(sourceFolder(options.plugin, root, "plugin"), "references")
+	}];
+	if (options.default !== void 0) return [{
+		tier: "default",
+		dir: join(sourceFolder(options.default, root, "skill"), "references")
+	}];
+	const places = [
+		{
+			tier: "repo",
+			dir: repoReferencesDir(root)
+		},
+		{
+			tier: "user",
+			dir: userReferencesDir(options.home)
+		},
+		...projectFolders(root, layers.projects).folders.map(({ folder, dir }) => ({
+			tier: "project",
+			dir,
+			folder
+		}))
+	];
+	const seen = /* @__PURE__ */ new Set();
+	return places.filter(({ dir }) => {
+		const key = resolve(dir);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
 }
-/**
-* The implementations of interface `id` a consumer may load, each checked as `check` would on its
-* composed document, and every candidate left out with why (R35). A candidate is a name in the
-* interface's namespace (`<id>` or `<id>.<key>`) or a reference that declares `implements: <id>@<n>`:
-* a plugin's, pinned by its qualified name, or, for a `many` interface, a `repo` or `user` one,
-* pinned by its bare name. When a `repo` or `user` implementation answers the bare name, a plugin's
-* of that name is left out (C1, J3), since loading the bare name returns the other. Plugins holding
-* a name no `extends` orders are all left out until a customizer picks one (R87). A skill's default
-* is never listed: it has no qualified name to pin. An unknown interface throws.
-*/
-function referenceImplementations(id, source, options = {}) {
-	const { accept: acceptOption, ...rest } = options;
-	const resolveOptions = {
-		...rest,
-		projectSections: false
+/** The new names an older name takes: from each plugin's rename table, and from each owner's `aliases` (R124). */
+function renameSources(layers) {
+	const table = renameTable(layers);
+	const aliases = aliasIndex(layers);
+	return (name) => {
+		if (aliases.owned.has(name)) return [];
+		const found = /* @__PURE__ */ new Map();
+		const add = (to, by) => found.set(to, (found.get(to) ?? /* @__PURE__ */ new Set()).add(by));
+		for (const entry of table.byOld.get(name) ?? []) add(entry.to, `plugin ${entry.plugin}'s ${renameTableFile}`);
+		for (const owner of aliases.byAlias.get(name) ?? []) add(owner.name, `the aliases of ${owner.tier === "plugin" ? `plugin ${owner.plugin}` : `the default of ${owner.skill}`}`);
+		return [...found].map(([to, by]) => ({
+			to,
+			by: [...by].join(" and ")
+		}));
 	};
-	const ifaceName = parseReferenceName(`${id}${interfaceSuffix}`);
-	if (ifaceName.invalid || ifaceName.plugin !== void 0) throw new ReferenceFailure("interface-unknown", `"${id}" is not an interface id.`);
-	const lookup = interfaceLookup(source, rest);
-	const iface = lookup(id);
-	const value = iface.value;
-	if (!value) throw new ReferenceFailure("interface-unknown", iface.failure?.message ?? `no interface ${id}`);
-	const aliases = aliasIndex(source);
-	const ids = [value.id, ...(aliases.interfaces.get(value.id) ?? []).map(({ alias }) => alias)];
-	const accept = [...acceptOption?.length ? acceptOption : value.versions];
-	const report = {
-		interface: value.id,
-		cardinality: value.cardinality,
-		accept,
-		implementations: [],
-		excluded: [],
-		warnings: []
-	};
-	const seen = /* @__PURE__ */ new Set();
-	const warn = (warnings) => {
-		for (const warning of warnings) {
-			const key = `${warning.code} ${warning.message}`;
-			if (!seen.has(key)) report.warnings.push(warning);
-			seen.add(key);
+}
+/** Whether a folder holds any file answering `name` in its tier (R60's forms). */
+function holdsName(place, name) {
+	const own = place.tier === "default" ? defaultSuffix : "";
+	return [
+		`${name}${own}.md`,
+		...place.tier === "default" ? [] : [join(name, "README.md")],
+		...dataSuffixes.map((extension) => `${name}${own}${extension}`),
+		`${name}${own}${metadataSuffix}.md`
+	].some((file) => existsSync(join(place.dir, file)));
+}
+/**
+* Finds every file in a legacy form (K37), or under a name a plugin renamed, and returns the plan
+* (R121). With `write`, it applies each change that is not manual. It reads the `repo` tier, the
+* `user` tier, and every project section below the root, or only a plugin's or a skill's source
+* folder in the repository (R123), and never changes a managed folder or an installed copy.
+*/
+function migrateReferences(layers, options) {
+	const root = resolve(options.root ?? layers.root ?? process.cwd());
+	const names = options.names?.length ? new Set(options.names.map((name) => bareName(name).name)) : void 0;
+	const places = placesOf(layers, root, options);
+	const targetsOf = renameSources(layers);
+	const installed = new Set(layers.layers.flatMap(({ tier, plugin, skipped }) => tier === "plugin" && plugin && !skipped ? [plugin] : []));
+	const rows = [];
+	const operations = [];
+	for (const place of places) {
+		const where = place.folder === void 0 ? {} : { folder: place.folder };
+		const renames = place.tier === "repo" || place.tier === "user" || place.tier === "project";
+		/** New names this run gives files in the folder, so a second file renamed to one is manual. */
+		const claimed = /* @__PURE__ */ new Set();
+		const held = heldFiles(place);
+		if (place.tier === "default") held.push(...oldDefaults(place, names, held));
+		for (const file of held) {
+			const targets = renames ? targetsOf(file.name) : [];
+			if (names && !names.has(file.name) && !targets.some(({ to }) => names.has(to))) continue;
+			const base = {
+				path: file.path,
+				tier: place.tier,
+				...where,
+				name: file.name
+			};
+			const operation = { path: file.path };
+			if (file.kind === "markdown") {
+				const raw = tryRead$2(file.path) ?? "";
+				const { metadata, body } = parseDocument(raw, () => {});
+				const { findings, keys } = legacyRewrite(metadata, body, place.tier === "project" ? "project" : "contribution", file.name);
+				for (const finding of findings) rows.push(rowOf(base, finding));
+				if (Object.keys(keys).length) operation.content = editFrontmatter(raw, keys);
+			}
+			if (file.suffix === ".md" && place.tier === "default") {
+				const to = join(place.dir, `${file.name}${defaultSuffix}.md`);
+				const finding = defaultLayoutFinding(file.name);
+				if (existsSync(to)) {
+					const { to: _, ...kept } = finding;
+					rows.push(rowOf(base, {
+						...kept,
+						manual: `${file.name}${defaultSuffix}.md is there too and answers the name; the old file is not read, so delete it by hand once nothing in it is needed`
+					}));
+				} else {
+					rows.push(rowOf(base, finding));
+					Object.assign(operation, {
+						moveFrom: file.path,
+						moveTo: to
+					});
+				}
+			}
+			if (targets.length) renameRow(place, file, targets, claimed, base, rows, operation);
+			if (operation.content !== void 0 || operation.moveTo !== void 0) operations.push(operation);
 		}
+		if (renames) for (const found of qualifiedOverrides(place.dir)) {
+			if (names && !names.has(found.name)) continue;
+			const operation = qualifiedRow(place, found, installed, claimed, {
+				path: found.path,
+				tier: place.tier,
+				...where,
+				name: found.name
+			}, rows);
+			if (operation) operations.push(operation);
+		}
+	}
+	let written = false;
+	if (options.write) for (const operation of operations) {
+		if (operation.content !== void 0) writeFileSync(operation.path, operation.content);
+		if (operation.moveFrom !== void 0 && operation.moveTo !== void 0) renameSync(operation.moveFrom, operation.moveTo);
+		if (operation.prune !== void 0) pruneEmpty(operation.prune);
+		written = true;
+	}
+	return {
+		rows,
+		written,
+		warnings: [...renameTable(layers).warnings]
 	};
-	if (iface.renamed !== void 0) warn([{
-		code: "reference-renamed",
-		message: `${id} is an older id of ${value.id}; ask for ${value.id} instead`
-	}]);
-	const inNamespace = (name) => ids.some((each) => name === each || name.startsWith(`${each}.`));
-	/** Whether a resolved document is a candidate at all: it declares the interface, or its name is in the namespace. */
-	const relevant = (name, resolved) => {
-		const declared = readImplements(resolved.metadata ?? {}).entry?.id;
-		if (declared !== void 0 && ids.includes(declared)) return true;
-		return inNamespace(name) && !ids.some((each) => belongsElsewhere(name, declared, each));
+}
+function rowOf(base, finding) {
+	const row = {
+		...base,
+		form: finding.form,
+		from: finding.from
 	};
-	const consider = ({ pin, name, resolved, tier }) => {
-		warn(resolved.warnings);
-		const declared = readImplements(resolved.metadata ?? {}).entry;
-		if (!declared || !ids.includes(declared.id)) {
-			const shape = fitsNamespace(value.cardinality, ids, name) ? "" : ` and is not named ${value.cardinality === "one" ? value.id : `${value.id}.<key>`}`;
-			report.excluded.push({
-				name: pin,
-				reasons: [`declares no implements ${value.id}@<version>${shape}`]
-			});
-			return;
-		}
-		const checked = checkResolved(resolved, lookup, {
-			id: value.id,
-			versions: accept
-		});
-		warn(checked.warnings);
-		if (checked.failures.length) {
-			report.excluded.push({
-				name: pin,
-				reasons: checked.failures.map(({ check, message }) => `${check}: ${message}`)
-			});
-			return;
-		}
-		report.implementations.push({
-			pin,
-			description: firstLine(resolved.metadata?.["description"]),
-			unsupported: checked.unsupported,
+	const note = finding.note === void 0 ? "" : `; ${finding.reads}, and ${finding.note}`;
+	if (finding.to !== void 0) row.to = `${finding.to}${note}`;
+	if (finding.manual !== void 0) row.manual = `${finding.manual}${note}`;
+	return row;
+}
+/**
+* A skill's defaults in the old layout, `references/<name>.md`, for the names given (UC22.7): the
+* folder's other files may be the skill's own documents, so no name given recognizes none.
+*/
+function oldDefaults(place, names, held) {
+	if (!names) return [];
+	return [...names].flatMap((name) => {
+		const path = join(place.dir, `${name}.md`);
+		if (tryRead$2(path) === void 0 || held.some((file) => file.path === path)) return [];
+		return [{
 			name,
-			tier,
-			version: declared.version
-		});
+			path,
+			suffix: ".md",
+			kind: "markdown",
+			folderForm: false
+		}];
+	});
+}
+/** The rename row of a file under an older name (R124), and the move that applies it. */
+function renameRow(place, file, targets, claimed, base, rows, operation) {
+	const from = file.folderForm ? `${file.name}/` : `${file.name}${file.suffix}`;
+	const row = {
+		...base,
+		form: "renamed",
+		from,
+		by: targets.map(({ by }) => by).join("; ")
 	};
-	const qualified = (plugin, name) => resolveReference(parseReferenceName(`${plugin}/${name}`), source, resolveOptions);
-	const names = [...new Set(referenceNames(source).map((name) => shownName(name, aliases)))];
-	for (const name of names) {
-		if (interfaceIdOf(name) !== void 0) continue;
-		const resolved = resolveReference(name, source, resolveOptions);
-		if (resolved.status === "ambiguous") {
-			for (const option of resolved.options ?? []) {
-				if (option === "default") continue;
-				const copy = resolveReference(parseReferenceName(option), source, resolveOptions);
-				if (copy.status !== "found" || !relevant(name, copy)) continue;
-				warn(copy.warnings);
-				report.excluded.push({
-					name: option,
-					reasons: [`ambiguous: ${resolved.message}; each is left out until a customizer picks one`]
-				});
-			}
-			continue;
-		}
-		if (resolved.status !== "found" || !relevant(name, resolved)) continue;
-		const plugins = holders(resolved);
-		const tier = value.cardinality === "many" ? ownTier(resolved) : void 0;
-		if (tier !== void 0) {
-			consider({
-				pin: name,
-				name,
-				resolved,
-				tier
-			});
-			for (const plugin of plugins) report.excluded.push({
-				name: `${plugin}/${name}`,
-				reasons: [`the ${tier} implementation answers ${name}; a consumer loads it by that name`]
-			});
-			continue;
-		}
-		const pick = resolved.trace.stack.filter((target) => target !== "default").at(-1);
-		if (pick === void 0) continue;
-		consider({
-			pin: `${pick}/${name}`,
-			name,
-			resolved: qualified(pick, name),
-			tier: "plugin"
+	if (targets.length > 1) {
+		rows.push({
+			...row,
+			manual: `it is renamed differently: ${targets.map(({ to, by }) => `"${to}" by ${by}`).join(", ")}; rename it by hand to the one that applies`
 		});
-		for (const plugin of plugins) {
-			if (plugin === pick) continue;
-			report.excluded.push({
-				name: `${plugin}/${name}`,
-				reasons: [`${name} loads the stack of ${pick}, the pick; load ${pick}/${name}`]
-			});
-		}
+		return;
 	}
-	return report;
+	const { to } = targets[0];
+	const companion = file.kind === "metadata" || file.kind === "data";
+	if (holdsName(place, to) && !claimed.has(to) || claimed.has(to) && !companion) {
+		rows.push({
+			...row,
+			manual: `"${to}" already has a file in that folder; merge the two by hand, then delete this one`
+		});
+		return;
+	}
+	claimed.add(to);
+	const into = file.folderForm ? `${to}/` : `${to}${file.suffix}`;
+	rows.push({
+		...row,
+		to: into
+	});
+	const moveFrom = file.folderForm ? dirname(file.path) : file.path;
+	Object.assign(operation, {
+		moveFrom,
+		moveTo: join(place.dir, file.folderForm ? to : `${to}${file.suffix}`)
+	});
 }
-/** Whether a name fits the interface's cardinality under its id or one of its older ids. */
-function fitsNamespace(cardinality, ids, name) {
-	return ids.some((id) => cardinality === "one" ? name === id : name.startsWith(`${id}.`) && name.length > id.length + 1);
+function pruneEmpty(dir) {
+	try {
+		if (!readdirSync(dir).length) rmdirSync(dir);
+	} catch {}
+}
+/**
+* The row of a qualified-name override (K37), and the move that applies it: `<plugin>/<name>.md`
+* becomes `<name>.md` beside the subfolder, extending the plugin. It is manual in a project folder,
+* for a plugin the plugin tier does not hold, beside a file that already answers the name, and for a
+* file that writes its own `extends` or `overrides`.
+*/
+function qualifiedRow(place, found, installed, claimed, base, rows) {
+	const { plugin, name } = found;
+	const finding = qualifiedOverrideFinding(found, place.tier === "project" ? "project" : "contribution");
+	const { to, ...kept } = finding;
+	const manual = (why) => {
+		rows.push(rowOf(base, {
+			...kept,
+			manual: why
+		}));
+	};
+	if (to === void 0) return manual(finding.manual);
+	if (!installed.has(plugin)) return manual(`plugin ${plugin} is not installed; it would become ${to}, extending a plugin that is not there: install ${plugin} and run migrate again, or delete this file`);
+	if (holdsName(place, name) || claimed.has(name)) return manual(`"${name}" already has a file in that folder; move this file's sections into it and add ${plugin} to its extends, then delete this one`);
+	const raw = tryRead$2(found.path) ?? "";
+	const { metadata, body } = parseDocument(raw, () => {});
+	const own = ["extends", "overrides"].find((key) => key in metadata);
+	if (own !== void 0) return manual(`it also writes \`${own}\`; move it to ${name}.md by hand, with an extends that names ${plugin}`);
+	claimed.add(name);
+	rows.push(rowOf(base, finding));
+	const { findings, keys } = legacyRewrite(metadata, body, "contribution", name);
+	for (const other of findings) rows.push(rowOf(base, other));
+	return {
+		path: found.path,
+		content: editFrontmatter(raw, {
+			...keys,
+			extends: [plugin]
+		}),
+		moveFrom: found.path,
+		moveTo: join(place.dir, `${name}.md`),
+		prune: dirname(found.path)
+	};
 }
 /**
 * The files a customization of `name` is written to, `repo` and `user` and, with `in`, that folder's
@@ -16306,7 +17388,314 @@ function whereReference(input, source, { root, display = (path) => path, in: fol
 		if (hider) file.hiddenBy = hiderLabel(hider, display);
 		report.files.push(file);
 	}
-	return report;
+	return report;
+}
+//#endregion
+//#region src/harness-registry/harness-registry.ts
+/**
+* Throws on a harness `skillsDirectories` does not confirm: treating it as native would silently
+* drop a projection it may need.
+*/
+function skillsProjection(harness, scope, directories = skillsDirectories(harness)?.[scope]) {
+	const listed = directories ?? [];
+	const [first] = listed;
+	if (first === void 0) throw new Error(`cyber-agentkit records no ${scope} skills directories for ${harness}.`);
+	return listed.includes(".agents/skills") ? {} : { skillsDirectory: first };
+}
+/**
+* The user-scope counterpart of the root `AGENTS.md`, relative to the home directory. No harness
+* reads it natively; each loads it only through a user-scope `instructionBridge` (E-CC-18, E-CODEX-05,
+* E-GEM-03, E-COPILOT-04, E-CUR-08).
+*/
+const globalInstructions = ".agents/AGENTS.md";
+/**
+* Skills directories come from `cyber-agentkit`, except for the harnesses it does not know
+* (`devin-desktop`, `windsurf`); see `.research/agentic-configuration-standards/` for the rest.
+*/
+const harnessRegistry = [
+	{
+		name: "claude-code",
+		project: {
+			detect: ".claude",
+			...skillsProjection("claude-code", "project"),
+			shadowedBy: [
+				"CLAUDE.md",
+				".claude/CLAUDE.md",
+				"CLAUDE.local.md"
+			],
+			mcpConfig: {
+				path: ".mcp.json",
+				key: "mcpServers",
+				format: "json",
+				dialect: "claude-code"
+			},
+			nonstandard: [
+				{
+					path: ".claude/commands",
+					shape: "directory",
+					kind: "command"
+				},
+				{
+					path: ".claude/rules",
+					shape: "directory",
+					kind: "rule"
+				},
+				{
+					path: ".claude/agents",
+					shape: "directory",
+					kind: "subagent"
+				}
+			]
+		},
+		user: {
+			detect: ".claude",
+			...skillsProjection("claude-code", "user"),
+			relocatedBy: "CLAUDE_CONFIG_DIR",
+			emptyRelocatesToStart: true,
+			instructionBridge: {
+				kind: "import",
+				path: ".claude/CLAUDE.md",
+				line: `@~/${globalInstructions}`
+			}
+		}
+	},
+	{
+		name: "cursor",
+		project: {
+			detect: ".cursor",
+			...skillsProjection("cursor", "project"),
+			mcpConfig: {
+				path: ".cursor/mcp.json",
+				key: "mcpServers",
+				format: "json",
+				dialect: "cursor"
+			},
+			nonstandard: [
+				{
+					path: ".cursorrules",
+					shape: "file",
+					kind: "instructions"
+				},
+				{
+					path: ".cursor/rules",
+					shape: "directory",
+					kind: "rule"
+				},
+				{
+					path: ".cursor/commands",
+					shape: "directory",
+					kind: "command"
+				},
+				{
+					path: ".cursor/skills",
+					shape: "directory",
+					kind: "skill"
+				}
+			]
+		},
+		user: {
+			detect: ".cursor",
+			...skillsProjection("cursor", "user")
+		}
+	},
+	{
+		name: "codex",
+		project: {
+			detect: ".codex",
+			...skillsProjection("codex", "project"),
+			mcpConfig: {
+				path: ".codex/config.toml",
+				key: "mcp_servers",
+				format: "toml",
+				dialect: "codex",
+				shared: true
+			},
+			nonstandard: [{
+				path: ".codex/skills",
+				shape: "directory",
+				kind: "skill"
+			}]
+		},
+		user: {
+			detect: ".codex",
+			...skillsProjection("codex", "user"),
+			instructionBridge: {
+				kind: "symlink",
+				path: ".codex/AGENTS.md"
+			},
+			shadowedBy: [".codex/AGENTS.override.md"],
+			relocatedBy: "CODEX_HOME"
+		}
+	},
+	{
+		name: "copilot-cli",
+		project: {
+			detect: ".github/skills",
+			...skillsProjection("copilot-cli", "project"),
+			nonstandard: [
+				{
+					path: ".github/copilot-instructions.md",
+					shape: "file",
+					kind: "instructions"
+				},
+				{
+					path: ".github/instructions",
+					shape: "directory",
+					kind: "instructions"
+				},
+				{
+					path: ".github/skills",
+					shape: "directory",
+					kind: "skill"
+				}
+			]
+		},
+		user: {
+			detect: ".copilot",
+			...skillsProjection("copilot-cli", "user"),
+			relocatedBy: "COPILOT_HOME",
+			instructionBridge: {
+				kind: "symlink",
+				path: ".copilot/copilot-instructions.md"
+			}
+		}
+	},
+	{
+		name: "gemini-cli",
+		project: {
+			detect: ".gemini",
+			...skillsProjection("gemini-cli", "project"),
+			instructionBridge: {
+				kind: "settings-entry",
+				path: ".gemini/settings.json",
+				key: "context.fileName"
+			},
+			mcpConfig: {
+				path: ".gemini/settings.json",
+				key: "mcpServers",
+				format: "json",
+				dialect: "gemini-cli",
+				shared: true
+			},
+			nonstandard: [{
+				path: "GEMINI.md",
+				shape: "file",
+				kind: "instructions"
+			}, {
+				path: ".gemini/skills",
+				shape: "directory",
+				kind: "skill"
+			}]
+		},
+		user: {
+			detect: ".gemini",
+			...skillsProjection("gemini-cli", "user"),
+			instructionBridge: {
+				kind: "symlink",
+				path: ".gemini/GEMINI.md"
+			}
+		}
+	},
+	{
+		name: "devin-desktop",
+		project: { detect: ".devin" }
+	},
+	{
+		name: "windsurf",
+		project: {
+			detect: ".windsurf",
+			skillsDirectory: ".windsurf/skills",
+			nonstandard: [{
+				path: ".windsurfrules",
+				shape: "file",
+				kind: "instructions"
+			}, {
+				path: ".windsurf/rules",
+				shape: "directory",
+				kind: "rule"
+			}]
+		},
+		deprecated: "devin-desktop"
+	}
+];
+const harnessNames = new Set(harnessRegistry.map((harness) => harness.name));
+function isHarnessName(value) {
+	return harnessNames.has(value);
+}
+/**
+* An unknown name throws rather than being dropped — silently falling back to the defaults would
+* misreport what was diagnosed.
+*/
+function parseHarnesses(value) {
+	const requested = (value ?? "").split(",").map((name) => name.trim()).filter(Boolean);
+	const unsupported = requested.filter((name) => !isHarnessName(name));
+	if (unsupported.length) throw new Error(`Unsupported harness: ${unsupported.join(", ")}. Supported: ${harnessRegistry.map((harness) => harness.name).join(", ")}.`);
+	return requested.filter(isHarnessName);
+}
+/** Enabled whether or not the repository already contains their directories. */
+const defaultHarnesses = ["claude-code", "cursor"];
+function directoryExists(path) {
+	try {
+		return lstatSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */
+function selectHarnesses(root, preferred) {
+	const enabled = /* @__PURE__ */ new Set([...defaultHarnesses, ...preferred]);
+	return harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.project.detect)));
+}
+//#endregion
+//#region src/command-output/command-output.ts
+/**
+* AXI §6: a failure is a coded error on stdout, in the caller's format, with a `help` line saying
+* what to do next. A `CliError` the command already built is rethrown untouched; anything else
+* becomes `command-failed`, exit code 1.
+*/
+function fail(error, fallback, help) {
+	if (isCliError(error)) throw error;
+	throw new CliError(error instanceof Error ? error.message : fallback, {
+		code: "command-failed",
+		exitCode: exitCodes.error,
+		...help ? { help } : {},
+		cause: error
+	});
+}
+/**
+* An answer that comes with a failing exit code. The cli prints only an answer a command returns, and
+* a thrown error replaces the return, so the answer is printed first.
+*/
+function answerThenFail(answer, format) {
+	const text = printAnswer(answer, format);
+	if (text !== void 0) process.stdout.write(text);
+	throw CliError.reported(exitCodes.error);
+}
+/**
+* AXI §10: collapses the home directory to `~` so a path in a report is portable to another
+* machine.
+*/
+function collapseHome$1(home, path) {
+	return home && path.startsWith(home + sep) ? `~${path.slice(home.length)}` : path;
+}
+function displayBinPath(home, executable) {
+	return executable ? collapseHome$1(home, executable) : "buddy-agent-harness";
+}
+/**
+* `parseHarnesses` for a command's `--harness`: an unsupported name is a usage error, exit code 2.
+* The registry stays free of clibuilder, which the library entry treats as an optional peer.
+*/
+function parseHarnessOption(value) {
+	try {
+		return parseHarnesses(value);
+	} catch (error) {
+		throw new CliError(error.message, {
+			code: "unsupported-harness",
+			exitCode: exitCodes.usage,
+			help: "Pass --harness as a comma-separated list of the supported names.",
+			cause: error
+		});
+	}
 }
 //#endregion
 //#region src/dep-plugins/dep-plugins.ts
@@ -16363,7 +17752,7 @@ function serializeCatalog(catalog) {
 }
 //#endregion
 //#region src/dep-plugins/resolve.ts
-function readJson$1(path) {
+function readJson$2(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -16378,7 +17767,7 @@ function readDepPlugin(pkg, fromManifest) {
 		package: pkg,
 		reason: "unresolved"
 	};
-	const manifest = readJson$1(join(dir, "plugin.json"));
+	const manifest = readJson$2(join(dir, "plugin.json"));
 	if (!manifest || typeof manifest !== "object") return {
 		ok: false,
 		package: pkg,
@@ -16391,7 +17780,7 @@ function readDepPlugin(pkg, fromManifest) {
 		package: pkg,
 		reason: "unnamed"
 	};
-	const installed = readJson$1(join(dir, "package.json"));
+	const installed = readJson$2(join(dir, "package.json"));
 	const version = typeof installed?.version === "string" ? installed.version : void 0;
 	if (!version) return {
 		ok: false,
@@ -16484,7 +17873,7 @@ function writeCatalog(root, catalog) {
 //#endregion
 //#region src/dep-plugins/harness-plugins.ts
 const COPILOT_LIMITATION = "Copilot CLI rejects an npm marketplace source, so it cannot install from this catalog. It needs a path-sourced catalog, which cannot reach node_modules from a subdirectory.";
-function readJson(path) {
+function readJson$1(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -16502,7 +17891,7 @@ function claudeConfigDir(home, env = process.env) {
 	return env["CLAUDE_CONFIG_DIR"] || join(home, ".claude");
 }
 function readClaudeState(configDir) {
-	const installedFile = readJson(join(configDir, "plugins", "installed_plugins.json"));
+	const installedFile = readJson$1(join(configDir, "plugins", "installed_plugins.json"));
 	const installed = [];
 	for (const [id, entries] of Object.entries(installedFile?.plugins ?? {})) {
 		if (!Array.isArray(entries)) continue;
@@ -16525,7 +17914,7 @@ function readClaudeState(configDir) {
 			});
 		}
 	}
-	const knownFile = readJson(join(configDir, "plugins", "known_marketplaces.json"));
+	const knownFile = readJson$1(join(configDir, "plugins", "known_marketplaces.json"));
 	const marketplaces = [];
 	for (const [name, value] of Object.entries(knownFile ?? {})) marketplaces.push({
 		name,
@@ -16685,6 +18074,13 @@ const depPluginsCommand = 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();
@@ -16727,285 +18123,29 @@ const depPluginsCommand = command({
 					package: pkg,
 					version
 				})) : "0 dependencies ship a plugin — nothing to install",
-				harness: harness.length ? harness : "no supported harness detected on this machine",
-				actions: actions.length ? actions : "0 actions — every detected harness matches the catalog",
-				...notes.length ? { notes } : {}
-			});
-			return outcome === "would-change" ? answerThenFail(answer, this.format) : answer;
-		} catch (error) {
-			return fail(error, "Catalog generation failed.");
-		}
-	}
-});
-//#endregion
-//#region src/diagnose-bridges/directory-files.ts
-/** A directory that does not exist reads as empty: `doctor` never creates one to look at it. */
-function filesUnder(directory) {
-	try {
-		return readdirSync(directory, {
-			recursive: true,
-			withFileTypes: true
-		}).filter((entry) => entry.isFile()).map((entry) => relative(directory, join(entry.parentPath, entry.name)).split(sep).join(posix.sep)).sort();
-	} catch {
-		return [];
-	}
-}
-//#endregion
-//#region src/harness-registry/harness-registry.ts
-/**
-* Throws on a harness `skillsDirectories` does not confirm: treating it as native would silently
-* drop a projection it may need.
-*/
-function skillsProjection(harness, scope, directories = skillsDirectories(harness)?.[scope]) {
-	const listed = directories ?? [];
-	const [first] = listed;
-	if (first === void 0) throw new Error(`cyber-agentkit records no ${scope} skills directories for ${harness}.`);
-	return listed.includes(".agents/skills") ? {} : { skillsDirectory: first };
-}
-/**
-* The user-scope counterpart of the root `AGENTS.md`, relative to the home directory. No harness
-* reads it natively; each loads it only through a user-scope `instructionBridge` (E-CC-18, E-CODEX-05,
-* E-GEM-03, E-COPILOT-04, E-CUR-08).
-*/
-const globalInstructions = ".agents/AGENTS.md";
-/**
-* Skills directories come from `cyber-agentkit`, except for the harnesses it does not know
-* (`devin-desktop`, `windsurf`); see `.research/agentic-configuration-standards/` for the rest.
-*/
-const harnessRegistry = [
-	{
-		name: "claude-code",
-		project: {
-			detect: ".claude",
-			...skillsProjection("claude-code", "project"),
-			shadowedBy: [
-				"CLAUDE.md",
-				".claude/CLAUDE.md",
-				"CLAUDE.local.md"
-			],
-			mcpConfig: {
-				path: ".mcp.json",
-				key: "mcpServers",
-				format: "json",
-				dialect: "claude-code"
-			},
-			nonstandard: [
-				{
-					path: ".claude/commands",
-					shape: "directory",
-					kind: "command"
-				},
-				{
-					path: ".claude/rules",
-					shape: "directory",
-					kind: "rule"
-				},
-				{
-					path: ".claude/agents",
-					shape: "directory",
-					kind: "subagent"
-				}
-			]
-		},
-		user: {
-			detect: ".claude",
-			...skillsProjection("claude-code", "user"),
-			relocatedBy: "CLAUDE_CONFIG_DIR",
-			emptyRelocatesToStart: true,
-			instructionBridge: {
-				kind: "import",
-				path: ".claude/CLAUDE.md",
-				line: `@~/${globalInstructions}`
-			}
-		}
-	},
-	{
-		name: "cursor",
-		project: {
-			detect: ".cursor",
-			...skillsProjection("cursor", "project"),
-			mcpConfig: {
-				path: ".cursor/mcp.json",
-				key: "mcpServers",
-				format: "json",
-				dialect: "cursor"
-			},
-			nonstandard: [
-				{
-					path: ".cursorrules",
-					shape: "file",
-					kind: "instructions"
-				},
-				{
-					path: ".cursor/rules",
-					shape: "directory",
-					kind: "rule"
-				},
-				{
-					path: ".cursor/commands",
-					shape: "directory",
-					kind: "command"
-				},
-				{
-					path: ".cursor/skills",
-					shape: "directory",
-					kind: "skill"
-				}
-			]
-		},
-		user: {
-			detect: ".cursor",
-			...skillsProjection("cursor", "user")
-		}
-	},
-	{
-		name: "codex",
-		project: {
-			detect: ".codex",
-			...skillsProjection("codex", "project"),
-			mcpConfig: {
-				path: ".codex/config.toml",
-				key: "mcp_servers",
-				format: "toml",
-				dialect: "codex",
-				shared: true
-			},
-			nonstandard: [{
-				path: ".codex/skills",
-				shape: "directory",
-				kind: "skill"
-			}]
-		},
-		user: {
-			detect: ".codex",
-			...skillsProjection("codex", "user"),
-			instructionBridge: {
-				kind: "symlink",
-				path: ".codex/AGENTS.md"
-			},
-			shadowedBy: [".codex/AGENTS.override.md"],
-			relocatedBy: "CODEX_HOME"
-		}
-	},
-	{
-		name: "copilot-cli",
-		project: {
-			detect: ".github/skills",
-			...skillsProjection("copilot-cli", "project"),
-			nonstandard: [
-				{
-					path: ".github/copilot-instructions.md",
-					shape: "file",
-					kind: "instructions"
-				},
-				{
-					path: ".github/instructions",
-					shape: "directory",
-					kind: "instructions"
-				},
-				{
-					path: ".github/skills",
-					shape: "directory",
-					kind: "skill"
-				}
-			]
-		},
-		user: {
-			detect: ".copilot",
-			...skillsProjection("copilot-cli", "user"),
-			relocatedBy: "COPILOT_HOME",
-			instructionBridge: {
-				kind: "symlink",
-				path: ".copilot/copilot-instructions.md"
-			}
-		}
-	},
-	{
-		name: "gemini-cli",
-		project: {
-			detect: ".gemini",
-			...skillsProjection("gemini-cli", "project"),
-			instructionBridge: {
-				kind: "settings-entry",
-				path: ".gemini/settings.json",
-				key: "context.fileName"
-			},
-			mcpConfig: {
-				path: ".gemini/settings.json",
-				key: "mcpServers",
-				format: "json",
-				dialect: "gemini-cli",
-				shared: true
-			},
-			nonstandard: [{
-				path: "GEMINI.md",
-				shape: "file",
-				kind: "instructions"
-			}, {
-				path: ".gemini/skills",
-				shape: "directory",
-				kind: "skill"
-			}]
-		},
-		user: {
-			detect: ".gemini",
-			...skillsProjection("gemini-cli", "user"),
-			instructionBridge: {
-				kind: "symlink",
-				path: ".gemini/GEMINI.md"
-			}
+				harness: harness.length ? harness : "no supported harness detected on this machine",
+				actions: actions.length ? actions : "0 actions — every detected harness matches the catalog",
+				...notes.length ? { notes } : {}
+			});
+			return outcome === "would-change" ? answerThenFail(answer, this.format) : answer;
+		} catch (error) {
+			return fail(error, "Catalog generation failed.");
 		}
-	},
-	{
-		name: "devin-desktop",
-		project: { detect: ".devin" }
-	},
-	{
-		name: "windsurf",
-		project: {
-			detect: ".windsurf",
-			skillsDirectory: ".windsurf/skills",
-			nonstandard: [{
-				path: ".windsurfrules",
-				shape: "file",
-				kind: "instructions"
-			}, {
-				path: ".windsurf/rules",
-				shape: "directory",
-				kind: "rule"
-			}]
-		},
-		deprecated: "devin-desktop"
 	}
-];
-const harnessNames = new Set(harnessRegistry.map((harness) => harness.name));
-function isHarnessName(value) {
-	return harnessNames.has(value);
-}
-/**
-* An unknown name throws rather than being dropped — silently falling back to the defaults would
-* misreport what was diagnosed.
-*/
-function parseHarnesses(value) {
-	const requested = (value ?? "").split(",").map((name) => name.trim()).filter(Boolean);
-	const unsupported = requested.filter((name) => !isHarnessName(name));
-	if (unsupported.length) throw new Error(`Unsupported harness: ${unsupported.join(", ")}. Supported: ${harnessRegistry.map((harness) => harness.name).join(", ")}.`);
-	return requested.filter(isHarnessName);
-}
-/** Enabled whether or not the repository already contains their directories. */
-const defaultHarnesses = ["claude-code", "cursor"];
-function directoryExists(path) {
+});
+//#endregion
+//#region src/diagnose-bridges/directory-files.ts
+/** A directory that does not exist reads as empty: `doctor` never creates one to look at it. */
+function filesUnder(directory) {
 	try {
-		return lstatSync(path).isDirectory();
+		return readdirSync(directory, {
+			recursive: true,
+			withFileTypes: true
+		}).filter((entry) => entry.isFile()).map((entry) => relative(directory, join(entry.parentPath, entry.name)).split(sep).join(posix.sep)).sort();
 	} catch {
-		return false;
+		return [];
 	}
 }
-/** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */
-function selectHarnesses(root, preferred) {
-	const enabled = /* @__PURE__ */ new Set([...defaultHarnesses, ...preferred]);
-	return harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.project.detect)));
-}
 //#endregion
 //#region src/diagnose-bridges/locator.ts
 /** The locator as one string: the finding's `path`, and what a repair names. */
@@ -17036,6 +18176,7 @@ const initSkillInvocation = `/buddy-agent-harness:init-buddy-agent-harness`;
 */
 const pnpmSkillRef = (invocation) => `\`${invocation}\` (pnpm install: \`pnpm-${commandInvocation}-${invocation.slice(invocation.indexOf(":") + 1)}\`)`;
 const initSkillRef = pnpmSkillRef(initSkillInvocation);
+const enhanceSkillRef = pnpmSkillRef("/buddy-agent-harness:enhance");
 const repairSkillRef = pnpmSkillRef(repairSkillInvocation);
 /** Where the user authors the golden MCP server set, named in every MCP repair that points at it. */
 const goldenSet = ".agents/buddy-agent-harness/mcp.toml";
@@ -17401,6 +18542,35 @@ const nonstandardTable = {
 	}
 };
 repairsOf(nonstandardTable);
+/** Who offers every worktree repair, named the same way in each row. */
+const worktreeOffer = `${initSkillRef} offers it, or ${enhanceSkillRef} where the repository already has an AGENTS.md`;
+const worktreeTable = {
+	"worktrees-untracked": {
+		detail: ".claude/worktrees/ is not git-ignored, so every agent worktree Claude Code creates there shows up as untracked in git status",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `add \`.claude/worktrees/\` to ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the .gitignore line`
+	},
+	"worktrees-scanned": {
+		detail: "this config does not exclude .claude/worktrees, so the tool walks into each agent worktree, a whole checkout with its own config, and Biome stops on the nested root configuration",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `add \`"!**/.claude/worktrees"\` to \`files.includes\` in ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the exclusion`
+	},
+	"worktree-base-unset": {
+		detail: "worktree.baseRef is unset, so agent worktrees branch from the default branch rather than the current HEAD — work on a feature branch starts without its commits",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `decide whether agent worktrees should branch from HEAD, and if so set \`"worktree": { "baseRef": "head" }\` in ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which explains the trade-off and offers the setting`
+	}
+};
+repairsOf(worktreeTable);
 /**
 * Annotated over the whole union rather than inferred, so an added problem fails to compile until
 * its section carries it.
@@ -17411,7 +18581,8 @@ const doctorTable = {
 	...globalInstructionTable,
 	...configurationTable,
 	...mcpTable,
-	...nonstandardTable
+	...nonstandardTable,
+	...worktreeTable
 };
 repairsOf(doctorTable);
 /** The repair for one problem. Total by construction: the table is keyed by the union. */
@@ -19200,8 +20371,45 @@ function diagnoseNonstandard({ root, cli }) {
 	}
 	return findings.sort((left, right) => left.path.localeCompare(right.path));
 }
+const biomeConfigs = ["biome.json", "biome.jsonc"];
+const claudeSettings = ".claude/settings.json";
+/** `undefined` when the file is missing or does not parse; either way Claude Code reads no base from it. */
+function readJson(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Checked only where `.claude/` exists, the sign the repository is worked in with Claude Code.
+* Biome is the one tool checked: it is the confirmed failure, and the others are offered by the
+* skills without a finding.
+*/
+function diagnoseWorktrees({ root, git, cli }) {
+	if (!existsSync(join(root, ".claude"))) return [];
+	const findings = [];
+	const add = (path, problem) => {
+		const { detail, repair } = repairFor(problem);
+		findings.push({
+			path,
+			problem,
+			detail,
+			repair: repair({ file: path }, cli)
+		});
+	};
+	if (git.isRepository() && !git.isIgnored(".claude/worktrees/")) add(".gitignore", "worktrees-untracked");
+	for (const config of biomeConfigs) {
+		const path = join(root, config);
+		if (existsSync(path) && !readFileSync(path, "utf8").includes(".claude/worktrees")) add(config, "worktrees-scanned");
+	}
+	const settings = readJson(join(root, claudeSettings));
+	const worktree = isRecord(settings) ? settings["worktree"] : void 0;
+	if (!isRecord(worktree) || worktree["baseRef"] === void 0) add(claudeSettings, "worktree-base-unset");
+	return findings;
+}
 //#endregion
-//#region ../../node_modules/.pnpm/cyber-agentkit@2.0.0_clibuilder@12.1.1_js-yaml@4.3.2_/node_modules/cyber-agentkit/dist/commands.js
+//#region ../../node_modules/.pnpm/cyber-agentkit@2.2.0_clibuilder@12.3.0_js-yaml@4.3.2_/node_modules/cyber-agentkit/dist/commands.js
 /**
 * AXI §10: collapses the home directory to `~` so a path in a report is portable to another
 * machine.
@@ -19214,6 +20422,8 @@ t.boolean().optional();
 t.string().optional();
 t.string();
 t.string().optional();
+/** The command line that reaches the reference commands in `cyber-agentkit`'s own CLI. */
+const defaultReferencePath = "cyber-agentkit reference";
 const rootOption$3 = {
 	description: "The repository root: its `.agents/references/` is the repo tier, and its `package.json` names the dependency plugins. Defaults to the nearest folder at or above the current directory holding `.git`, else the current directory.",
 	type: t.string().optional()
@@ -19366,7 +20576,7 @@ const skillOption = {
 	description: "A skill's source folder in this repository: acts on its `references/<name>.default.md`.",
 	type: t.string().optional()
 };
-function checkCommand(layersFor) {
+function checkCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "check",
 		description: "Check references, each composed as `load` composes it: an interface document against its shape, an implementation against its interface, and every document for the defects composing it raises. With no names, checks every name found. Every warning `load` raises is reported. A failure is an entry in `failed`, not an error; a warning never fails a check.",
@@ -19382,6 +20592,10 @@ function checkCommand(layersFor) {
 				description: "Add every entry checked, with its kind and unsupported sections."
 			}
 		},
+		examples: [{
+			command: `${path} check`,
+			description: "Check every reference against its interface"
+		}],
 		async run(args) {
 			try {
 				const home = homedir();
@@ -19423,7 +20637,7 @@ function checkCommand(layersFor) {
 		}
 	});
 }
-function createCommand(layersFor) {
+function createCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "create",
 		description: "Start a contribution in the repo or user tier, a folder's project section, or a plugin's or a skill's source folder, from a template or an interface. Never overwrites a file with a body; writes a file a contribution above hides, with a warning.",
@@ -19459,6 +20673,10 @@ function createCommand(layersFor) {
 				description: "After the write, add the trace, in which the new file applies."
 			}
 		},
+		examples: [{
+			command: `${path} create my-topic`,
+			description: "Start a new reference named my-topic"
+		}],
 		async run(args) {
 			const format = this.format;
 			try {
@@ -19569,13 +20787,32 @@ function text(customized, shown) {
 	const meta = shown.metadataFile ? ` Its record is in ${shown.metadataFile}.` : "";
 	return `${shown.path}\n\n${shown.hint}${meta}\n`;
 }
-function customizeCommand(layersFor) {
+function familyReport(customized, args, home) {
+	return compact({
+		family: customized.family,
+		interfaces: customized.interfaces.map(({ interface: id, outcome, reason, result: each }) => compact({
+			interface: id,
+			outcome,
+			reason,
+			...each ? report(each, args, home) : {}
+		})),
+		hint: customized.dryRun ? "Nothing was written. Run again without --dry-run to write it." : "Run `load <interface>` for each composed document."
+	});
+}
+function familyText(customized, shown) {
+	return `${customized.interfaces.map(({ interface: id, outcome, reason, result: each }, at) => {
+		if (!each) return `${id}: ${outcome}. ${reason}\n`;
+		const own = shown.interfaces[at];
+		return `${id}: ${outcome}.\n${text(each, own)}`;
+	}).join("\n")}`;
+}
+function customizeCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "customize",
 		description: "Customize a name for the repo or user tier, or a folder's project section, running no model: pick what it builds on (`extends`), write a body generated from a request with its record, or print what the generator reads (--base). Writes a file a contribution above hides, with a warning.",
 		arguments: [{
 			name: "name",
-			description: "Reference name, without the `.md` extension.",
+			description: "Reference name, without the `.md` extension; or a family, `<prefix>.*`, to pick for every interface under the prefix at once (takes --extends or --extends-file, no `sections`).",
 			type: t.string()
 		}, {
 			name: "steps",
@@ -19634,6 +20871,13 @@ function customizeCommand(layersFor) {
 				description: "After the write, add the trace, in which the written file applies."
 			}
 		},
+		examples: [{
+			command: `${path} customize my-topic`,
+			description: "Customize a reference for this project"
+		}, {
+			command: `${path} customize my-skill.aspects.* --extends house-style`,
+			description: "Pick one plugin for every interface under a prefix"
+		}],
 		async run(args) {
 			const format = this.format;
 			try {
@@ -19657,19 +20901,33 @@ function customizeCommand(layersFor) {
 					base: args.base,
 					dryRun: args["dry-run"]
 				};
+				const family = isFamilyName(args.name) || args.name.includes("*") ? parseFamily(args.name) : void 0;
 				validateWrite({
 					command: "customize",
-					...request
+					...request,
+					name: family === void 0 || family.invalid !== void 0 ? args.name : family.prefix
 				});
 				if (args.steps?.length && args.extends === void 0) throw new ReferenceFailure("options-missing", `${args.steps.join(" ")} follow no --extends; pass --extends before the steps.`);
 				const layers = await layersFor({
 					root: args.root,
 					default: args.default
 				}, home);
+				if (family !== void 0) {
+					const customized = customizeContribution(layers, {
+						...request,
+						root: layers.root ?? request.root
+					}, { display });
+					if (!("family" in customized)) throw new Error(`${args.name} was customized as a single name, not a family.`);
+					const shown = familyReport(customized, args, home);
+					if (format !== "text") return result(shown);
+					for (const { result: each } of customized.interfaces) writeWarnings(each?.warnings ?? []);
+					return document(familyText(customized, shown));
+				}
 				const customized = customizeContribution(layers, {
 					...request,
 					root: layers.root ?? request.root
 				}, { display });
+				if ("family" in customized) throw new Error(`${args.name} was customized as a family, not a single name.`);
 				if (customized.action === "base") {
 					if (format !== "text") return result(baseReport(customized));
 					return document(baseText(customized));
@@ -19702,7 +20960,7 @@ function deleteReport(deleted, home) {
 		options: deleted.after.options
 	});
 }
-function deleteCommand(layersFor) {
+function deleteCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "delete",
 		description: "Delete a repo or user contribution, a folder's project section, or one in a plugin's or a skill's source folder, with a non-Markdown file's metadata file, and report what answers the name afterwards. Never deletes an installed or managed one.",
@@ -19725,6 +20983,10 @@ function deleteCommand(layersFor) {
 				type: t.boolean().optional()
 			}
 		},
+		examples: [{
+			command: `${path} delete my-topic`,
+			description: "Delete your contribution to my-topic"
+		}],
 		async run(args) {
 			const format = this.format;
 			try {
@@ -19772,13 +21034,40 @@ function parseAccept(value) {
 	} });
 	return versions.map(Number);
 }
-function implementationsCommand(layersFor) {
+function rowsOf(found, trace) {
+	return found.implementations.map(({ pin, description, unsupported, name, tier, version }) => compact(trace ? {
+		pin,
+		description,
+		unsupported,
+		name,
+		tier,
+		version
+	} : {
+		pin,
+		...tier === "plugin" ? {} : { tier },
+		description,
+		unsupported
+	}));
+}
+function reportOf(found, trace) {
+	const report = { implementations: rowsOf(found, trace) };
+	if (found.inUse !== void 0) report.inUse = found.inUse;
+	if (trace) Object.assign(report, compact({
+		interface: found.interface,
+		cardinality: found.cardinality,
+		accept: found.accept,
+		excluded: found.excluded,
+		warnings: found.warnings
+	}));
+	return report;
+}
+function implementationsCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "implementations",
 		description: "List the implementations of an interface a consumer can load, each with its pin, description, and unsupported sections.",
 		arguments: [{
 			name: "id",
-			description: "Interface id, the name of its `<id>.interface` document without the suffix.",
+			description: "Interface id, the name of its `<id>.interface` document without the suffix; or a family, `<prefix>.*`, for every interface under the prefix.",
 			type: t.string()
 		}],
 		options: {
@@ -19792,36 +21081,34 @@ function implementationsCommand(layersFor) {
 				description: "Add each one's name, tier, and version, the interface's cardinality and accepted versions, and the ones left out with why."
 			}
 		},
+		examples: [{
+			command: `${path} implementations my-interface`,
+			description: "List what implements an interface"
+		}, {
+			command: `${path} implementations my-skill.aspects.*`,
+			description: "List, for every interface under a prefix, what implements it and which one is in use"
+		}],
 		async run(args) {
 			try {
 				const accept = parseAccept(args.accept);
 				const home = homedir();
-				const found = referenceImplementations(args.id, await layersFor(args, home), {
+				const options = {
 					accept,
 					display: (path) => collapseHome(home, path)
-				});
-				const rows = found.implementations.map(({ pin, description, unsupported, name, tier, version }) => compact(args.trace ? {
-					pin,
-					description,
-					unsupported,
-					name,
-					tier,
-					version
-				} : {
-					pin,
-					...tier === "plugin" ? {} : { tier },
-					description,
-					unsupported
-				}));
-				if (!rows.length && !args.trace) return empty(`0 implementations of ${args.id}`, { help: `Run \`reference implementations ${args.id} --trace\` for the ones left out, with why.` });
-				const report = { implementations: rows };
-				if (args.trace) Object.assign(report, compact({
-					interface: found.interface,
-					cardinality: found.cardinality,
-					accept: found.accept,
-					excluded: found.excluded,
-					warnings: found.warnings
-				}));
+				};
+				const found = referenceImplementations(args.id, await layersFor(args, home), options);
+				if ("family" in found) {
+					const family = found;
+					return result({
+						family: family.family,
+						interfaces: family.interfaces.map((each) => ({
+							...reportOf(each, args.trace),
+							interface: each.interface
+						}))
+					});
+				}
+				const report = reportOf(found, args.trace);
+				if (!report.implementations.length && report.inUse === void 0 && !args.trace) return empty(`0 implementations of ${args.id}`, { help: `Run \`reference implementations ${args.id} --trace\` for the ones left out, with why.` });
 				return result(report);
 			} catch (error) {
 				return asCliError(error, "Implementation lookup failed.");
@@ -19829,7 +21116,7 @@ function implementationsCommand(layersFor) {
 		}
 	});
 }
-function listCommand(layersFor) {
+function listCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "list",
 		description: "List every reference name, one row each, with its description, and its status when not found. A pattern keeps only the names it matches exactly.",
@@ -19845,6 +21132,13 @@ function listCommand(layersFor) {
 				description: "Add one row per name per layer holding it, with its outcome."
 			}
 		},
+		examples: [{
+			command: `${path} list`,
+			description: "List every reference name"
+		}, {
+			command: `${path} list 'project-tracker.*'`,
+			description: "List the names matching a pattern"
+		}],
 		async run(args) {
 			try {
 				const home = homedir();
@@ -19912,7 +21206,7 @@ function loadText(resolved) {
 	}
 	return document(resolved.map(tag).join("\n\n"));
 }
-function loadCommand(layersFor) {
+function loadCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "load",
 		description: "Print one or more references, each composed from its contributions as their extends and merge declare.",
@@ -19930,6 +21224,13 @@ function loadCommand(layersFor) {
 			},
 			trace: traceOption
 		},
+		examples: [{
+			command: `${path} load my-topic`,
+			description: "Print one reference"
+		}, {
+			command: `${path} load my-topic other-topic --format json`,
+			description: "Print several as JSON"
+		}],
 		async run(args) {
 			const format = this.format;
 			try {
@@ -19970,7 +21271,87 @@ function loadCommand(layersFor) {
 		}
 	});
 }
-function searchCommand(layersFor) {
+function rowLine(row) {
+	const where = row.folder === void 0 ? row.tier : `${row.tier} ${row.folder}`;
+	const change = row.manual === void 0 ? `${row.from} → ${row.to}` : `${row.from}: manual: ${row.manual}`;
+	const by = row.by === void 0 ? "" : ` (by ${row.by})`;
+	const user = row.tier === "user" ? "; a user file, which no git history restores" : "";
+	return `${row.path} (${where}): ${row.form}: ${change}${by}${user}`;
+}
+function summary(rows, written) {
+	const manual = rows.filter((row) => row.manual !== void 0).length;
+	const applied = rows.length - manual;
+	const left = manual ? ` ${manual} ${manual === 1 ? "needs" : "need"} a person, as each says.` : "";
+	if (written) return `migrated ${applied} ${applied === 1 ? "change" : "changes"}.${left}`;
+	if (!applied) return `nothing to apply.${left}`;
+	return `${applied} ${applied === 1 ? "change" : "changes"} to make; run \`reference migrate --write\` with the same arguments to apply ${applied === 1 ? "it" : "them"}.${left}`;
+}
+function migrateCommand(layersFor, path = defaultReferencePath) {
+	return command({
+		name: "migrate",
+		description: "Rewrite reference files still in a form version 1 wrote, and rename files under a name a plugin renamed, in the repo and user tiers and every project section, or in one plugin or skill source folder. Prints the plan; `--write` applies it. Never changes a managed or installed file.",
+		arguments: [{
+			name: "names",
+			description: "Reference names to limit the run to, without the `.md` extension; a file under an older name of one is included.",
+			type: t.array(t.string()).optional()
+		}],
+		options: {
+			root: rootOption$3,
+			plugin: {
+				description: "A plugin's source folder in this repository: migrate only its `references/`, in place of the tiers.",
+				type: t.string().optional()
+			},
+			default: {
+				description: "A skill's source folder in this repository: migrate only its `references/`, in place of the tiers. A default at `references/<name>.md` is renamed only for a name given.",
+				type: t.string().optional()
+			},
+			write: {
+				description: "Apply the changes. It edits `user` files too, which no git history restores.",
+				type: t.boolean().optional()
+			}
+		},
+		examples: [{
+			command: `${path} migrate`,
+			description: "Migrate version 1 reference files"
+		}],
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				if (args.plugin !== void 0 && args.default !== void 0) throw new ReferenceFailure("options-conflict", "pass one of --plugin and --default.");
+				const layers = await layersFor({ root: args.root }, home);
+				const migrated = migrateReferences(layers, {
+					root: layers.root ?? givenRoot(args.root),
+					home,
+					names: args.names,
+					plugin: args.plugin,
+					default: args.default,
+					write: args.write
+				});
+				const changes = migrated.rows.map((row) => ({
+					...row,
+					path: collapseHome(home, row.path)
+				}));
+				if (!changes.length && !migrated.warnings.length) return empty("0 changes — no reference file is in a version 1 form or under a renamed name", { help: ["Run `reference check` for every warning `load` raises."] });
+				const report = compact({
+					changes,
+					written: migrated.written ? true : void 0,
+					warnings: migrated.warnings
+				});
+				if (format !== "text") return result(report);
+				writeWarnings(migrated.warnings);
+				return document(`${[
+					...changes.map(rowLine),
+					"",
+					summary(changes, migrated.written)
+				].join("\n").trimStart()}\n`);
+			} catch (error) {
+				return asCliError(error, "Reference migration failed.");
+			}
+		}
+	});
+}
+function searchCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "search",
 		description: "Find references by name, description, tags, headings, or body, best match first.",
@@ -19984,16 +21365,29 @@ function searchCommand(layersFor) {
 			trace: {
 				...traceOption,
 				description: "Add the tier and plugin or skill of each match."
+			},
+			full: {
+				...fullOption,
+				description: `Show every match, not only the best 10.`
 			}
 		},
+		examples: [{
+			command: `${path} search "worktree leases"`,
+			description: "Find references by topic"
+		}],
 		async run(args) {
 			const query = args.query.trim();
 			try {
 				const home = homedir();
 				const { matches, defaults } = searchReferences(query, await layersFor(args, home), { display: (path) => collapseHome(home, path) });
 				if (!matches.length) return empty(`0 references match "${query}"`, { help: [...defaults ? [defaults] : [], "Try other words, or run `reference list` for every name."] });
-				return result(compact({
-					references: matches.map(({ name, description, match, folder, tier, plugin, skill, loadedBy }) => compact(args.trace ? {
+				const shown = truncateList(matches, {
+					limit: 10,
+					full: args.full
+				});
+				const report = compact({
+					count: shown.truncated ? shown.count : void 0,
+					references: shown.items.map(({ name, description, match, folder, tier, plugin, skill, loadedBy }) => compact(args.trace ? {
 						name,
 						description,
 						match,
@@ -20010,14 +21404,15 @@ function searchCommand(layersFor) {
 						loadedBy
 					})),
 					defaults
-				}));
+				});
+				return shown.truncated ? result(report, { help: [`Run \`reference search ${JSON.stringify(query)} --full\` for every match.`] }) : result(report);
 			} catch (error) {
 				return asCliError(error, "Reference search failed.");
 			}
 		}
 	});
 }
-function whereCommand(layersFor) {
+function whereCommand(layersFor, path = defaultReferencePath) {
 	return command({
 		name: "where",
 		description: "Give the repo and user files, and with --in a folder's project section, a customization or a selection of a reference is written to, who each reaches and what hides it, the main document's heading paths, and the read-only plugins and default the stack uses.",
@@ -20038,6 +21433,10 @@ function whereCommand(layersFor) {
 				description: "Add every layer checked, with its outcome."
 			}
 		},
+		examples: [{
+			command: `${path} where my-topic`,
+			description: "Show which layers hold my-topic"
+		}],
 		async run(args) {
 			const format = this.format;
 			try {
@@ -20072,25 +21471,26 @@ function whereCommand(layersFor) {
 	});
 }
 /** A factory, so each host CLI names itself as the plugin whose own references come first. */
-function createReferenceCommands({ plugin } = {}) {
+function createReferenceCommands({ plugin, path = defaultReferencePath } = {}) {
 	const layersFor = layerSource(plugin);
 	return {
-		load: loadCommand(layersFor),
-		list: listCommand(layersFor),
-		search: searchCommand(layersFor),
-		where: whereCommand(layersFor),
-		create: createCommand(layersFor),
-		customize: customizeCommand(layersFor),
-		delete: deleteCommand(layersFor),
-		check: checkCommand(layersFor),
-		implementations: implementationsCommand(layersFor)
+		load: loadCommand(layersFor, path),
+		list: listCommand(layersFor, path),
+		search: searchCommand(layersFor, path),
+		where: whereCommand(layersFor, path),
+		create: createCommand(layersFor, path),
+		customize: customizeCommand(layersFor, path),
+		delete: deleteCommand(layersFor, path),
+		migrate: migrateCommand(layersFor, path),
+		check: checkCommand(layersFor, path),
+		implementations: implementationsCommand(layersFor, path)
 	};
 }
 function createReferenceCommand(options = {}) {
-	const { load, list, search, where, create, customize, delete: remove, check, implementations } = createReferenceCommands(options);
+	const { load, list, search, where, create, customize, delete: remove, migrate, check, implementations } = createReferenceCommands(options);
 	return command({
 		name: "reference",
-		description: "Read reference documents by name, composed from the managed, repo, user, plugin, and default tiers, and create, customize, or delete a contribution.",
+		description: "Read reference documents by name, composed from the managed, repo, user, plugin, and default tiers, create, customize, or delete a contribution, and migrate version 1 files.",
 		commands: [
 			load,
 			list,
@@ -20099,6 +21499,7 @@ function createReferenceCommand(options = {}) {
 			create,
 			customize,
 			remove,
+			migrate,
 			implementations,
 			check
 		]
@@ -20256,10 +21657,13 @@ function referenceLayers({ packageRoot = dirname(packageGovernancesDir()), ...op
 		}
 	});
 }
-const referenceCommand = createReferenceCommand({ plugin: {
-	name: PACKAGE_PLUGIN,
-	root: dirname(packageGovernancesDir())
-} });
+const referenceCommand = createReferenceCommand({
+	plugin: {
+		name: PACKAGE_PLUGIN,
+		root: dirname(packageGovernancesDir())
+	},
+	path: "buddy-agent-harness reference"
+});
 //#endregion
 //#region src/skill-projection/skill-projection.ts
 function skillNames(skillsDirectory) {
@@ -20712,6 +22116,10 @@ var GitBridgeState = class {
 		this.root = root;
 		this.repoRootPrefix = git(root, ["rev-parse", "--show-prefix"])?.trim();
 	}
+	/** Whether `root` is inside a git work tree at all; a check that needs git's answer skips when not. */
+	isRepository() {
+		return this.repoRootPrefix !== void 0;
+	}
 	/** The skip-worktree bit is a hint some checkouts clear, so it is verified rather than assumed. */
 	trackingOf(path) {
 		if (this.repoRootPrefix === void 0) return "untracked";
@@ -20974,64 +22382,82 @@ function buildDoctorReport(bin, result, configuration = [], held = []) {
 		help: [...new Map(findings.map((finding) => [`${finding.repair.command}\u0000${finding.repair.instruction}`, finding.repair])).values()]
 	};
 }
-const doctorCommand = command({
-	name: "doctor",
-	description: "Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md — and whether each harness's user-scope file loads ~/.agents/AGENTS.md. Read-only.",
-	options: {
-		root: {
-			description: "Repository or package directory. Defaults to the current directory.",
-			type: t.string().optional()
-		},
-		harness: {
-			description: "Comma-separated harnesses to check in addition to Claude Code and Cursor, e.g. codex,gemini-cli.",
-			type: t.string().optional()
-		}
+const doctorOptions = {
+	root: {
+		description: "Repository or package directory. Defaults to the current directory.",
+		type: t.string().optional()
 	},
-	async run(args) {
-		try {
-			const harnesses = parseHarnesses(args.harness);
-			const root = args.root ?? process.cwd();
-			const home = homedir();
-			const diagnosis = diagnoseBridges({
+	harness: {
+		description: "Comma-separated harnesses to check in addition to Claude Code and Cursor, e.g. codex,gemini-cli.",
+		type: t.string().optional()
+	}
+};
+const doctorDescription = "Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md — and whether each harness's user-scope file loads ~/.agents/AGENTS.md. Read-only.";
+/** The live report `doctor` answers with, shared with the bare invocation of the CLI. */
+async function diagnoseReport(args) {
+	try {
+		const harnesses = parseHarnessOption(args.harness);
+		const root = args.root ?? process.cwd();
+		const home = homedir();
+		const diagnosis = diagnoseBridges({
+			root,
+			...harnesses.length ? { harnesses } : {},
+			cli: commandInvocation,
+			home,
+			env: process.env
+		});
+		const git = new GitBridgeState(root);
+		const configuration = [
+			...diagnoseConfiguration({
 				root,
-				...harnesses.length ? { harnesses } : {},
-				cli: commandInvocation,
-				home,
-				env: process.env
-			});
-			const git = new GitBridgeState(root);
-			const configuration = [
-				...diagnoseConfiguration({
-					root,
-					git,
-					cli: commandInvocation
-				}),
-				...diagnoseMcp({
-					root,
-					git,
-					cli: commandInvocation
-				}),
-				...diagnoseNonstandard({
-					root,
-					cli: commandInvocation
-				})
-			];
-			const { layers: rows } = listReferences(await referenceLayers({
+				git,
+				cli: commandInvocation
+			}),
+			...diagnoseMcp({
 				root,
-				home,
-				platform: process.platform,
-				env: process.env
-			}));
-			const held = rows.filter(({ tier }) => tier !== "plugin").map(({ name, tier, path, outcome }) => ({
-				name,
-				tier,
-				path: collapseHome$1(home, path),
-				status: outcome
-			}));
-			return result(buildDoctorReport(displayBinPath(home, process.argv[1]), diagnosis, configuration, held));
-		} catch (error) {
-			return fail(error, "Harness diagnosis failed.");
-		}
+				git,
+				cli: commandInvocation
+			}),
+			...diagnoseNonstandard({
+				root,
+				cli: commandInvocation
+			}),
+			...diagnoseWorktrees({
+				root,
+				git,
+				cli: commandInvocation
+			})
+		];
+		const { layers: rows } = listReferences(await referenceLayers({
+			root,
+			home,
+			platform: process.platform,
+			env: process.env
+		}));
+		const held = rows.filter(({ tier }) => tier !== "plugin").map(({ name, tier, path, outcome }) => ({
+			name,
+			tier,
+			path: collapseHome$1(home, path),
+			status: outcome
+		}));
+		return buildDoctorReport(displayBinPath(home, process.argv[1]), diagnosis, configuration, held);
+	} catch (error) {
+		return fail(error, "Harness diagnosis failed.");
+	}
+}
+const doctorCommand = command({
+	name: "doctor",
+	description: doctorDescription,
+	options: doctorOptions,
+	examples: [{
+		command: "buddy-agent-harness doctor",
+		description: "Check the current repository"
+	}, {
+		command: "buddy-agent-harness doctor --harness codex,gemini-cli",
+		description: "Also check Codex and Gemini CLI"
+	}],
+	async run(args) {
+		return result(await diagnoseReport(args));
 	}
 });
 //#endregion
@@ -21066,6 +22492,10 @@ const governanceCommand = command({
 			root: rootOption,
 			"overrides-only": overridesOnlyOption
 		},
+		examples: [{
+			command: "buddy-agent-harness governance list",
+			description: "List the governances the layers hold"
+		}],
 		run(args) {
 			process.stderr.write(GOVERNANCE_DEPRECATED);
 			try {
@@ -21100,16 +22530,21 @@ const governanceCommand = command({
 			root: rootOption,
 			"overrides-only": overridesOnlyOption
 		},
+		examples: [{
+			command: "buddy-agent-harness governance show skill-design",
+			description: "Print one governance document"
+		}],
 		run(args) {
 			const format = this.format;
 			process.stderr.write(GOVERNANCE_DEPRECATED);
 			try {
 				const name = parseGovernanceName(args.name);
 				const found = resolveGovernance(name, layersFor(args));
-				if (!found) {
-					process.stderr.write(args["overrides-only"] ? `error: no override for governance "${name}" in the project, user, or machine-wide layer.\n` : `error: no governance named "${name}" in any layer.\n`);
-					throw CliError.reported(exitCodes.error);
-				}
+				if (!found) throw new CliError(args["overrides-only"] ? `no override for governance "${name}" in the project, user, or machine-wide layer.` : `no governance named "${name}" in any layer.`, {
+					code: "governance-not-found",
+					details: { name },
+					help: ref("reference list", {}, "see what is available")
+				});
 				const report = {
 					name: found.name,
 					scope: found.scope,
@@ -21185,9 +22620,16 @@ const initCommand = command({
 			type: t.string().optional()
 		}
 	},
+	examples: [{
+		command: "buddy-agent-harness init",
+		description: "Set up skills for Claude Code and Cursor"
+	}, {
+		command: "buddy-agent-harness init --harness codex --copy",
+		description: "Also enable Codex, copying skills instead of linking"
+	}],
 	run(args) {
 		try {
-			const harnesses = parseHarnesses(args.harness);
+			const harnesses = parseHarnessOption(args.harness);
 			return result(initializeHarnesses({
 				root: args.root ?? process.cwd(),
 				...harnesses.length ? { harnesses } : {},
@@ -23763,6 +25205,13 @@ const mcpReconcileCommand = command({
 			type: t.array(t.string()).optional()
 		}
 	},
+	examples: [{
+		command: "buddy-agent-harness mcp reconcile",
+		description: "List harness-side changes the golden set lacks"
+	}, {
+		command: "buddy-agent-harness mcp reconcile --accept <path>",
+		description: "Import one approved field"
+	}],
 	run(args) {
 		try {
 			const root = args.root ?? process.cwd();
@@ -23774,19 +25223,17 @@ const mcpReconcileCommand = command({
 			});
 			if (plan.kind === "unreadable") {
 				const at = plan.position ? ` at line ${plan.position.line}, column ${plan.position.column}` : "";
-				process.stderr.write(`error: ${goldenSetPath} does not parse${at}.\n`);
-				throw CliError.reported(exitCodes.error);
-			}
-			if (plan.kind === "rejected") {
-				process.stderr.write(`error: nothing written.\n${plan.reasons.map((reason) => `- ${reason}\n`).join("")}`);
-				throw CliError.reported(exitCodes.error);
-			}
-			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"
+				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") throw new CliError("nothing written.", {
+				code: "accept-rejected",
+				details: { reasons: plan.reasons },
+				help: ref("mcp reconcile", {}, "list the fields that can be approved")
 			});
+			if (plan.kind === "absent") return empty(`0 servers — no golden set at ${goldenSetPath}`, { help: `Create ${goldenSetPath} first; there is nothing to reconcile into.` });
 			return result({
 				golden: goldenSetPath,
 				mode: plan.written ? "written — only the fields named by --accept" : "dry run — nothing written; re-run with --accept <path> for each approved field",
@@ -24836,6 +26283,13 @@ const mcpCommand = 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();
@@ -24847,15 +26301,12 @@ const mcpCommand = command({
 				});
 				if (plan.kind === "unreadable") {
 					const at = plan.position ? ` at line ${plan.position.line}, column ${plan.position.column}` : "";
-					process.stderr.write(`error: ${goldenSetPath} does not parse${at}.\n`);
-					throw CliError.reported(exitCodes.error);
+					throw new CliError(`${goldenSetPath} does not parse${at}.`, {
+						code: "golden-set-unreadable",
+						help: `Fix the TOML syntax in ${goldenSetPath}, then re-run.`
+					});
 				}
-				if (plan.kind === "absent") return result({
-					golden: `0 servers — no golden set at ${goldenSetPath}`,
-					mode: "nothing to project",
-					actions: "0 changes",
-					record: "not written"
-				});
+				if (plan.kind === "absent") return empty(`0 servers — no golden set at ${goldenSetPath}`, { help: [`Create ${goldenSetPath} with the MCP servers to project.`, ref("mcp project", {}, "preview the projection")] });
 				return result({
 					golden: goldenSetPath,
 					mode: write ? "written" : "dry run — nothing written; re-run with --write to apply",
@@ -24892,6 +26343,19 @@ function app(format) {
 		version,
 		description: rootCommand.description,
 		format
+	}).default({
+		description: "Report whether this repository's harness bridges resolve (the same as `doctor`).",
+		options: doctorCommand.options,
+		async run(args) {
+			const { bin: _bin, ...report } = await diagnoseReport({
+				root: args["root"],
+				harness: args["harness"]
+			});
+			return result({
+				...homeHeader({ description: rootCommand.description }),
+				...report
+			});
+		}
 	}).command(first));
 }
 const textByDefault = {