cyber-agentkit 1.2.0 → 2.0.0

package/dist/commands.js

@@ -1,9 +1,9 @@
-import { A as skillName, C as repositoryRoot, M as require_dist, R as pluginManifestName, S as referenceLayers, _ as parseDocument, a as interfaceLookup, c as readExtends, d as parseReferenceName, f as fitsName, g as isMergeOperation, h as hasBody, i as checkResolved, m as frontmatterPattern, n as referenceImplementations, o as listReferences, p as dataExtensions, r as checkReferences, s as searchReferences, t as whereReference, u as resolveReference, v as parseSections, w as userReferencesDir, x as projectReferencesDir, y as canonical } from "./reference-where-C84J6MsR.js";
+import { B as userAssetsDir, C as referenceLayers, E as ReferenceFailure, F as resolveAsset, I as assetDataExtensions, K as skillName, L as parseAssetName, P as assetNames, R as assetLayers, S as findRoot, b as requireName, c as deleteContribution, d as insideRepository, f as checkReferences, g as searchReferences, h as listReferences, l as describeAnswer, m as interfaceLookup, n as referenceImplementations, p as checkResolved, r as customizeContribution, s as createContribution, t as whereReference, u as validateWrite, v as resolveReference, y as parseReferenceName, z as projectAssetsDir } from "./reference-where-CVmGFOwR.js";
 import { homedir } from "node:os";
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join, resolve, sep } from "node:path";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { command, exitCodes, t } from "clibuilder";
-import { CliError, document, encode, isCliError, printAnswer, result } from "clibuilder/axi";
+import { CliError, document, empty, encode, isCliError, printAnswer, result } from "clibuilder/axi";
 //#region src/command-output/collapse-home.ts
 /**
 * AXI §10: collapses the home directory to `~` so a path in a report is portable to another
@@ -13,351 +13,124 @@ function collapseHome(home, path) {
 	return home && path.startsWith(home + sep) ? `~${path.slice(home.length)}` : path;
 }
 //#endregion
-//#region src/references/create-reference.ts
-var import_dist = require_dist();
-/** No `#` title: `patch` matches by heading path, so a title would hold every section under it. */
-const defaultTemplate = `---
-description: What this reference covers, and when an agent should read it.
-tags: [topic]
----
-
-## Overview
-
-Write the guidance here. Give each topic its own top-level \`##\` section.
-`;
-/** The interface's sections as `##` headings, in order, each stubbed `**Unsupported.**`. */
-function implementationTemplate(iface) {
-	const sections = iface.sections.map((name) => `## ${name}\n\n**Unsupported.** Replace this line with the section, or say in one sentence why it is not supported.\n`);
-	return parseTemplate(`---\ndescription: What this ${iface.id} implementation covers, and when an agent should read it.\nimplements: ${iface.id}@${iface.version}\n---\n\n${sections.join("\n")}`, `the ${iface.id} interface`);
-}
-function readTemplate(path) {
-	if (path === void 0) return parseTemplate(defaultTemplate, "the default template");
-	let content;
-	try {
-		content = readFileSync(path, "utf8");
-	} catch (error) {
-		throw new Error(`cannot read the template ${path}: ${error.message}`);
-	}
-	return parseTemplate(content, `the template ${path}`);
-}
-function parseTemplate(content, label) {
-	let mapping = true;
-	const { metadata, body } = parseDocument(content, () => {
-		mapping = false;
-	});
-	if (!mapping) throw new Error(`${label} has frontmatter that is not a YAML mapping.`);
-	return {
-		content,
-		metadata,
-		body
-	};
-}
-/**
-* A title: the top level is a single heading holding every other one. `patch` matches by heading
-* path, so it would add the whole document under the title instead of patching its sections.
-*/
-function titleOf({ body }) {
-	const tree = parseSections(body, () => {});
-	const [only] = tree.children;
-	return tree.children.length === 1 && only?.children.length ? only.heading.trim() : void 0;
-}
-function hasDescription({ metadata }) {
-	return typeof metadata["description"] === "string" && metadata["description"].trim().length > 0;
+//#region src/assets/asset-catalog.ts
+function patternMatcher(pattern) {
+	const source = pattern.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"));
+	return new RegExp(`^${source.join(".*")}$`, "s");
 }
 /**
-* Sets or removes frontmatter keys and keeps the rest of the file as written: other keys, comments,
-* and the body. A file left with no key and no body is empty.
+* One row per asset name any layer holds, and one row per name per layer holding it (the skill's own
+* `default` tier is not listed per layer). A `pattern` keeps only the names it matches exactly.
 */
-function editFrontmatter(raw, keys) {
-	const match = frontmatterPattern.exec(raw);
-	const body = match ? raw.slice(match[0].length) : raw;
-	const doc = (0, import_dist.parseDocument)(match ? match[1] : "");
-	for (const [key, value] of Object.entries(keys)) if (value === void 0) doc.delete(key);
-	else {
-		const node = doc.createNode(value, { flow: Array.isArray(value) });
-		doc.set(key, node);
+function listAssetNames(source, { pattern, ...resolveOptions } = {}) {
+	const matcher = pattern === void 0 ? void 0 : patternMatcher(pattern);
+	const listing = {
+		references: [],
+		layers: [],
+		warnings: []
+	};
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of assetNames(source)) {
+		if (matcher && !matcher.test(name)) continue;
+		const resolved = resolveAsset(name, source, resolveOptions);
+		for (const warning of resolved.warnings) {
+			const key = `${warning.code} ${warning.message}`;
+			if (!seen.has(key)) listing.warnings.push(warning);
+			seen.add(key);
+		}
+		const row = {
+			name,
+			status: resolved.status
+		};
+		if (resolved.format && resolved.format !== "markdown") row.format = resolved.format;
+		if (resolved.options) row.options = resolved.options.filter((option) => option !== "default");
+		listing.references.push(row);
+		for (const entry of resolved.trace.layers) {
+			if (entry.file === void 0 || entry.tier === "default") continue;
+			const layerRow = {
+				name,
+				tier: entry.tier,
+				path: entry.path,
+				outcome: entry.outcome
+			};
+			if (entry.plugin !== void 0) layerRow.plugin = entry.plugin;
+			if (entry.skill !== void 0) layerRow.skill = entry.skill;
+			listing.layers.push(layerRow);
+		}
 	}
-	if (!doc.contents?.items?.length) return body.replace(/^(?:[ \t]*\r?\n)+/, "");
-	const gap = !match && body.trim() ? "\n" : "";
-	return `---\n${doc.toString({
-		lineWidth: 0,
-		flowCollectionPadding: false
-	})}---\n${gap}${body}`;
+	return listing;
 }
 //#endregion
-//#region src/references/reference-write.ts
-/** A write refused. `usage` marks a wrong invocation (exit 2) rather than a refusal (exit 1). */
-var ReferenceWriteError = class extends Error {
-	code;
-	usage;
-	constructor(code, message, usage = false) {
-		super(message);
-		this.code = code;
-		this.usage = usage;
-	}
+//#region src/assets/asset-where.ts
+const reaches = {
+	project: "everyone working in this repository",
+	user: "only you, in every repository"
 };
-/** A bare, valid name, or a refusal naming the bare name to use. */
-function bareName(value) {
-	const name = parseReferenceName(value);
-	if (name.invalid) throw new ReferenceWriteError("reference-invalid", name.invalid);
-	if (name.plugin !== void 0) throw new ReferenceWriteError("reference-qualified", `a contribution is written under the bare name, which every tier resolves; ask for "${name.name}".`);
-	return name;
-}
-/** The repository the root sits in: a write to a source folder must land inside it, and never in an installed copy. */
-function insideRepository(folder, root) {
-	const repository = canonical(repositoryRoot(root) ?? resolve(root));
-	const target = canonical(folder);
-	if (target !== repository && !target.startsWith(repository + sep)) return false;
-	return !target.slice(repository.length).split(sep).includes("node_modules");
-}
-/** Resolves `--scope`, `--plugin`, and `--default` to the file a write acts on; more than one is a usage error. */
-function writeTarget(name, { root, home, scope, plugin, default: skill }) {
-	if ([
-		scope,
-		plugin,
-		skill
-	].filter((value) => value !== void 0).length > 1) throw new ReferenceWriteError("options-conflict", "pass one of --scope, --plugin, and --default.", true);
-	if (plugin !== void 0) {
-		const folder = resolve(plugin);
-		if (!pluginManifestName(folder)) throw new ReferenceWriteError("folder-invalid", `${folder} holds no plugin manifest, so it is not a plugin folder.`);
-		if (!insideRepository(folder, root)) throw new ReferenceWriteError("folder-invalid", `${folder} is outside the repository, such as an installed copy; write to the plugin's source instead.`);
-		const dir = join(folder, "references");
-		return {
-			scope: "plugin",
-			dir,
-			path: join(dir, `${name.name}.md`)
-		};
-	}
-	if (skill !== void 0) {
-		const folder = resolve(skill);
-		if (skillName(folder) === void 0) throw new ReferenceWriteError("folder-invalid", `${folder} holds no SKILL.md, so it is not a skill folder.`);
-		if (!insideRepository(folder, root)) throw new ReferenceWriteError("folder-invalid", `${folder} is outside the repository, such as an installed copy; write to the skill's source instead.`);
-		const dir = join(folder, "references");
-		return {
-			scope: "default",
-			dir,
-			path: join(dir, `${name.name}.default.md`)
-		};
-	}
-	if (scope !== void 0 && scope !== "project" && scope !== "user") throw new ReferenceWriteError("options-invalid", "--scope is project or user.", true);
-	const dir = scope === "user" ? userReferencesDir(home) : projectReferencesDir(resolve(root));
-	return {
-		scope: scope === "user" ? "user" : "project",
-		dir,
-		path: join(dir, `${name.name}.md`)
-	};
-}
-function tryRead(path) {
-	try {
-		return readFileSync(path, "utf8");
-	} catch {
-		return;
-	}
-}
-/** What answers a name, in one sentence a person reads. */
-function describeAnswer(resolved, display = (path) => path) {
-	if (resolved.status === "found") {
-		const top = resolved.trace.contributions.at(-1);
-		const by = top ? top.tier === "plugin" ? `plugin ${top.plugin}` : top.tier === "default" ? `the default of ${top.skill}` : `the ${top.tier} file ${display(top.path)}` : "nothing";
-		const stack = resolved.trace.stack.length ? `, on the stack ${resolved.trace.stack.join(" → ")}` : "";
-		return `"${resolved.name}" is answered by ${by}${stack}.`;
-	}
-	if (resolved.status === "ambiguous") return `"${resolved.name}" is ambiguous: ${resolved.message}; the options are ${(resolved.options ?? []).join(", ")}.`;
-	return `"${resolved.name}" is ${resolved.status}: ${resolved.message}.`;
-}
-/** The interface `create --implements` starts an implementation of, once the new name fits it. */
-function interfaceFor(id, name, layers, options) {
-	const parsed = parseReferenceName(id);
-	if (parsed.invalid || parsed.plugin !== void 0) throw new ReferenceWriteError("interface-invalid", `"${id}" is not an interface id.`);
-	const iface = interfaceLookup(layers, options)(id);
-	if (!iface.value) throw new ReferenceWriteError("interface-invalid", iface.failure?.message ?? `no interface ${id}`);
-	if (!fitsName(iface.value, name)) throw new ReferenceWriteError("interface-invalid", `an implementation of ${id} is named ${iface.value.cardinality === "one" ? id : `${id}.<key>`}, not "${name}".`);
-	return iface.value;
-}
-/**
-* Hides the new file: a `replace` with a body, or a `remove`, that applies above it. A folder that
-* is not a layer the stack reads has nothing above it.
-*/
-function hiddenBy(resolved, dir, path) {
-	const layers = resolved.trace.layers;
-	const at = layers.findIndex((layer) => layer.path === dir || layer.path === path);
-	if (at === -1) return void 0;
-	const target = layers[at];
-	const tiered = (tier) => tier === "managed" || tier === "project" || tier === "user";
-	const stackAt = target && !tiered(target.tier) ? resolved.trace.stack.indexOf(target.tier === "default" ? "default" : target.plugin ?? "") : -1;
-	const hider = layers.filter((layer, index) => {
-		if (!layer.file || layer.outcome !== "used") return false;
-		if (target && tiered(target.tier)) return index < at && tiered(layer.tier);
-		if (tiered(layer.tier)) return true;
-		const position = resolved.trace.stack.indexOf(layer.tier === "default" ? "default" : layer.plugin ?? "");
-		return stackAt !== -1 && position > stackAt;
-	}).find((layer) => layer.operation === "remove" || layer.operation === "replace" && !layer.empty);
-	return hider ? `${hider.tier}${hider.plugin ? ` ${hider.plugin}` : ""} ${hider.path} (${hider.operation})` : void 0;
-}
-/** A selection-only file keeps its own keys, `extends` among them; the template adds the keys it lacks. */
-function selectionKeys(existing, template, merge) {
-	const held = parseDocument(existing, () => {}).metadata;
-	const keys = {};
-	for (const [key, value] of Object.entries(template.metadata)) if (key !== "merge" && !(key in held)) keys[key] = value;
-	keys["merge"] = merge;
-	return keys;
-}
-function withBody(head, body) {
-	const text = body.replace(/^(?:[ \t]*\r?\n)+/, "");
-	return text ? `${head.replace(/\s*$/, "")}\n\n${text}` : head;
-}
-function createContribution(layers, args, options = {}) {
-	const name = bareName(args.name);
-	const target = writeTarget(name, args);
-	if (args.merge !== void 0 && !isMergeOperation(args.merge)) throw new ReferenceWriteError("options-invalid", `--merge is replace, patch, combine, or remove; got "${args.merge}".`, true);
-	const merge = args.merge;
-	if (args.template !== void 0 && args.implements !== void 0) throw new ReferenceWriteError("options-conflict", "pass --template or --implements, not both.");
-	if (merge === "remove" && args.template !== void 0) throw new ReferenceWriteError("options-conflict", "--merge remove writes no body, so it takes no --template.");
-	if (merge !== void 0 && target.scope === "default") throw new ReferenceWriteError("options-conflict", "a default is written with no merge; drop --merge.");
-	const existing = tryRead(target.path);
-	if (existing !== void 0 && hasBody(parseDocument(existing, () => {}).body)) throw new ReferenceWriteError("file-exists", `${(options.display ?? ((path) => path))(target.path)} already holds "${name.name}"; change it with the reference skill's Update mode.`);
-	const template = args.implements !== void 0 ? implementationTemplate(interfaceFor(args.implements, name.name, layers, options)) : merge === "remove" ? {
-		content: "",
-		metadata: {},
-		body: ""
-	} : readTemplate(args.template === void 0 ? void 0 : resolve(args.template));
-	const title = titleOf(template);
-	if (title) throw new ReferenceWriteError("template-title", `the template's top level is the single heading "${title}" holding the others; patch matches by heading path, so make its sections top-level.`);
-	const before = resolveReference(name, layers, options);
-	const hider = hiddenBy(before, target.dir, target.path);
-	if (hider) throw new ReferenceWriteError("hidden", `${hider} applies above it, so nothing would read the new file; change that contribution instead.`);
-	const operation = target.scope === "default" ? void 0 : args.implements !== void 0 ? "replace" : merge ?? (isMergeOperation(template.metadata["merge"]) ? template.metadata["merge"] : void 0) ?? (target.scope === "plugin" ? void 0 : "patch");
-	const content = existing === void 0 ? editFrontmatter(template.content, { merge: operation }) : withBody(editFrontmatter(existing, selectionKeys(existing, template, operation)), template.body);
-	const hints = hasDescription(parseDocument(content, () => {})) ? [] : ["it has no `description` in its frontmatter, so `list` and `search` show it blank"];
-	const result = {
-		name: name.name,
-		scope: target.scope,
-		path: target.path,
-		content,
-		dryRun: Boolean(args.dryRun),
-		hints
+/** The project and user folders an override of the asset `name` is written to. */
+function whereAsset(input, source, { root, display = (path) => path }) {
+	const name = typeof input === "string" ? parseAssetName(input) : input;
+	const resolved = resolveAsset(name, source, { display });
+	const report = {
+		name: name.raw,
+		status: resolved.status,
+		places: [],
+		layers: resolved.trace.layers,
+		warnings: resolved.warnings
 	};
-	if (result.dryRun) return result;
-	mkdirSync(target.dir, { recursive: true });
-	writeFileSync(target.path, content, existing === void 0 ? { flag: "wx" } : {});
-	if (before.trace.layers.some((layer) => layer.path === target.dir || layer.path === target.path)) result.after = resolveReference(name, layers, options);
-	return result;
-}
-function selectContribution(layers, args, options = {}) {
-	const name = bareName(args.name);
-	const target = writeTarget(name, {
-		root: args.root,
-		home: args.home,
-		scope: args.scope
-	});
-	const scope = target.scope;
-	const existing = tryRead(target.path);
-	if (args.clear) {
-		if (args.options.length) throw new ReferenceWriteError("options-conflict", "--clear takes no option.", true);
-		if (!(existing === void 0 ? void 0 : readExtends(parseDocument(existing, () => {}).metadata["extends"], () => {}))) throw new ReferenceWriteError("no-selection", `the ${scope} tier holds no selection of "${name.name}". ${describeAnswer(resolveReference(name, layers, options), options.display)}`);
-		const content = editFrontmatter(existing, { extends: void 0 });
-		const deleted = !content.trim();
-		if (deleted) rmSync(target.path);
-		else writeFileSync(target.path, content);
-		return {
-			name: name.name,
+	if (resolved.options) report.options = resolved.options;
+	if (name.invalid) return report;
+	const userDir = (Array.isArray(source) ? source : source.layers).find(({ tier }) => tier === "user")?.dir;
+	const targets = [{
+		scope: "project",
+		dir: projectAssetsDir(root)
+	}, ...userDir ? [{
+		scope: "user",
+		dir: userDir
+	}] : []];
+	for (const { scope, dir } of targets) {
+		const held = [join(dir, `${name.name}.md`), ...assetDataExtensions.map(({ extension }) => join(dir, `${name.name}${extension}`))];
+		const entry = resolved.trace.layers.find((layer) => held.includes(layer.path));
+		report.places.push({
 			scope,
-			path: target.path,
-			extends: [],
-			deleted,
-			after: resolveReference(name, layers, options)
-		};
-	}
-	if (!args.options.length) throw new ReferenceWriteError("options-missing", "name at least one option: a plugin or default.", true);
-	const before = resolveReference(name, layers, options);
-	const holders = new Set(before.trace.layers.flatMap(({ plugin, file }) => plugin !== void 0 && file ? [plugin] : []));
-	const picked = args.options.map((option) => option.endsWith(`/${name.name}`) ? option.slice(0, -name.name.length - 1) : option);
-	const wrong = picked.filter((option) => option !== "default" && !holders.has(option));
-	if (wrong.length) throw new ReferenceWriteError("option-invalid", `${wrong.join(", ")} ${wrong.length === 1 ? "is" : "are"} neither default nor a plugin holding "${name.name}"${holders.size ? `; the plugins holding it are ${[...holders].join(", ")}` : ""}.`);
-	const content = editFrontmatter(existing ?? "", { extends: picked });
-	mkdirSync(target.dir, { recursive: true });
-	writeFileSync(target.path, content);
-	return {
-		name: name.name,
-		scope,
-		path: target.path,
-		extends: picked,
-		deleted: false,
-		after: resolveReference(name, layers, options)
-	};
-}
-/** The data files that can answer a name in a folder. */
-function dataFiles(dir, name) {
-	return dataExtensions.map(({ extension }) => join(dir, `${name}${extension}`));
-}
-function deleteContribution(layers, args, options = {}) {
-	const name = bareName(args.name);
-	const target = writeTarget(name, args);
-	const shown = options.display ?? ((path) => path);
-	const before = resolveReference(name, layers, options);
-	const path = (target.scope === "project" || target.scope === "user" ? [
-		target.path,
-		join(target.dir, name.name, "README.md"),
-		...dataFiles(target.dir, name.name)
-	] : [target.path]).find((candidate) => candidate !== options.without && existsSync(candidate));
-	if (!path) throw new ReferenceWriteError("no-file", `${shown(target.path)} does not exist, so there is no ${target.scope} contribution of "${name.name}" to delete. ${describeAnswer(before, options.display)} An installed plugin's, a managed, or an installed skill's contribution is never deleted.`);
-	const steps = readExtends(parseDocument(tryRead(path) ?? "", () => {}).metadata["extends"], () => {});
-	const dryRun = Boolean(args.dryRun);
-	if (!dryRun) {
-		rmSync(path);
-		if (dirname(path) !== target.dir) try {
-			rmdirSync(dirname(path));
-		} catch {}
+			path: `${scope === "project" ? relative(root, dir) : display(dir)}/${name.name}.<ext>`,
+			reaches: reaches[scope],
+			status: entry?.file ? entry.outcome : "empty",
+			sections: []
+		});
 	}
-	const result = {
-		name: name.name,
-		scope: target.scope,
-		path,
-		dryRun,
-		after: resolveReference(name, layers, {
-			...options,
-			without: dryRun ? path : void 0
-		})
-	};
-	if (steps) result.selection = steps.map(({ target: step }) => step);
-	return result;
+	return report;
 }
 //#endregion
-//#region src/references/reference.command.ts
-const rootOption$1 = {
+//#region src/assets/asset-resolve.command.ts
+const rootOption$2 = {
 	description: "Directory the project tier is read from, and each folder above it up to the repository root; a project write goes to its `.agents/references/`. Defaults to the current directory.",
 	type: t.string().optional()
 };
-const traceOption = {
+const traceOption$1 = {
 	description: "Add the trace: every layer checked, with its outcome, and how the result was built.",
 	type: t.boolean().optional()
 };
-const defaultOption = {
+const defaultOption$1 = {
 	description: "The calling skill's folder: its `references/<name>.default.md` joins as the `default` tier.",
 	type: t.string().optional()
 };
-function layerSource(plugin, folder = "references") {
-	return (args, home) => referenceLayers({
+function layerSource$1(plugin) {
+	return (args, home) => assetLayers({
 		root: args.root ?? process.cwd(),
 		home,
 		platform: process.platform,
 		env: process.env,
 		plugin,
-		defaultSkill: args.default,
-		folder
+		defaultSkill: args.default
 	});
 }
 /** A field with nothing to say is left out: `undefined`, an empty string, or an empty list. */
-function compact(value) {
+function compact$1(value) {
 	return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0 && field !== "" && !(Array.isArray(field) && !field.length)));
 }
 /** stderr, not stdout: an agent parses stdout. Rethrows what the cli already reports. */
 function fail$1(error, fallback) {
 	if (isCliError(error)) throw error;
-	if (error instanceof ReferenceWriteError) {
-		process.stderr.write(`error: ${error.code}: ${error.message}\n`);
-		throw CliError.reported(error.usage ? exitCodes.usage : exitCodes.error);
-	}
 	process.stderr.write(`error: ${error instanceof Error ? error.message : fallback}\n`);
 	throw CliError.reported(exitCodes.error);
 }
@@ -371,10 +144,10 @@ function answerThenFail(answer, format) {
 	if (text !== void 0) process.stdout.write(text);
 	throw CliError.reported(exitCodes.error);
 }
-function writeWarnings(warnings) {
+function writeWarnings$1(warnings) {
 	for (const { code, message } of warnings) process.stderr.write(`warning: ${code}: ${message}\n`);
 }
-function displayTrace(trace, home) {
+function displayTrace$1(trace, home) {
 	const show = (path) => collapseHome(home, path);
 	return {
 		...trace,
@@ -388,37 +161,27 @@ function displayTrace(trace, home) {
 		}))
 	};
 }
-/** The text trace: a summary line, then each section with its contributions, then each layer. */
-function traceText(resolved, home) {
-	const trace = displayTrace(resolved.trace, home);
+/** The text trace: a summary line, then each layer. */
+function traceText$1(resolved, home) {
+	const trace = displayTrace$1(resolved.trace, home);
 	const lines = [`${resolved.name}: ${resolved.status}; stack: ${trace.stack.join(" → ") || "none"}; built by ${trace.builtBy}; harnesses: ${trace.harnesses.join(", ") || "none detected"}`];
 	if (resolved.message) lines.push(`  ${resolved.message}`);
-	if (trace.sections.length) {
-		lines.push("sections:");
-		for (const section of trace.sections) {
-			const how = section.removedBy ? `removed by ${section.removedBy}` : section.contributions.map(({ contribution, operation }) => `${contribution} (${operation})`).join(", ") || "no text";
-			lines.push(`  ${section.path}: ${how}`);
-		}
-	}
 	lines.push("layers:");
 	for (const layer of trace.layers) {
 		const who = layer.plugin ? ` ${layer.plugin}` : layer.skill ? ` ${layer.skill}` : "";
 		const how = layer.operation ? `; ${layer.operation} from ${layer.operationFrom}` : "";
-		const extendsNote = layer.extendsOutcome ? `; extends ${layer.extendsOutcome}` : "";
-		const selection = layer.selection ? "; selection" : "";
-		const frontmatter = layer.frontmatter && Object.keys(layer.frontmatter).length ? ` ${JSON.stringify(layer.frontmatter)}` : "";
-		lines.push(`  ${layer.tier}${who} ${layer.path}: ${layer.outcome}${how}${extendsNote}${selection}${frontmatter}`);
+		lines.push(`  ${layer.tier}${who} ${layer.path}: ${layer.outcome}${how}`);
 	}
 	return `${lines.join("\n")}\n`;
 }
-/** A name not found, for a person: the name, why, and, when ambiguous, the options `reference select` takes. */
+/** A name not found, for a person: the name, why, and, when ambiguous, the options `asset select` takes. */
 function errorText(entry) {
 	const options = entry.options?.length ? `; options: ${entry.options.join(", ")}` : "";
 	return `${entry.name}: ${entry.message}${options}`;
 }
 function showEntry(resolved, home, { metadata, trace }) {
 	if (resolved.status === "found" && !resolved.warnings.length && !metadata && !trace && resolved.format === "markdown") return resolved.content;
-	return compact({
+	return compact$1({
 		name: resolved.name,
 		status: resolved.status,
 		content: resolved.content,
@@ -427,11 +190,11 @@ function showEntry(resolved, home, { metadata, trace }) {
 		options: resolved.options,
 		metadata: metadata ? resolved.metadata : void 0,
 		warnings: resolved.warnings,
-		trace: trace ? displayTrace(resolved.trace, home) : void 0
+		trace: trace ? displayTrace$1(resolved.trace, home) : void 0
 	});
 }
 /** One entry per name asked, as the array itself rather than under a `result` key. */
-const bareArray = {
+const bareArray$1 = {
 	toon: (entries) => encode(entries, "toon"),
 	json: (entries) => encode(entries, "json")
 };
@@ -443,9 +206,9 @@ function showText(resolved) {
 	const blocks = resolved.map((entry) => entry.content === void 0 ? `<reference name="${entry.name}" status="${entry.status}" />` : `<reference name="${entry.name}">\n${entry.content}</reference>`);
 	return document(blocks.join("\n\n"));
 }
-function showCommand$1(layersFor, name = "show") {
+function loadCommand$1(layersFor) {
 	return command({
-		name,
+		name: "load",
 		description: "Print one or more references, each composed from its contributions as their extends and merge declare.",
 		arguments: [{
 			name: "names",
@@ -453,13 +216,13 @@ function showCommand$1(layersFor, name = "show") {
 			type: t.array(t.string())
 		}],
 		options: {
-			root: rootOption$1,
-			default: defaultOption,
+			root: rootOption$2,
+			default: defaultOption$1,
 			metadata: {
 				description: "Make every entry a record with its status and composed frontmatter.",
 				type: t.boolean().optional()
 			},
-			trace: traceOption
+			trace: traceOption$1
 		},
 		async run(args) {
 			const format = this.format;
@@ -468,24 +231,13 @@ function showCommand$1(layersFor, name = "show") {
 				const home = homedir();
 				const layers = await layersFor(args, home);
 				const display = (path) => collapseHome(home, path);
-				const lookup = interfaceLookup(layers, { display });
-				const resolved = args.names.map((name) => {
-					const entry = resolveReference(parseReferenceName(name), layers, { display });
-					for (const failure of checkResolved(entry, lookup).failures) {
-						if (failure.check === "compose") continue;
-						entry.warnings.push({
-							code: "interface-check",
-							message: `it fails its interface check (${failure.check}): ${failure.message}`
-						});
-					}
-					return entry;
-				});
+				const resolved = args.names.map((name) => resolveAsset(parseAssetName(name), layers, { display }));
 				const ok = resolved.every((entry) => entry.status === "found");
 				if (format === "text") {
 					for (const entry of resolved) {
-						writeWarnings(entry.warnings);
+						writeWarnings$1(entry.warnings);
 						if (entry.status !== "found") process.stderr.write(`error: ${entry.code}: ${errorText(entry)}\n`);
-						if (args.trace) process.stderr.write(traceText(entry, home));
+						if (args.trace) process.stderr.write(traceText$1(entry, home));
 					}
 					const answer = showText(resolved);
 					if (answer === void 0) throw CliError.reported(exitCodes.error);
@@ -495,7 +247,7 @@ function showCommand$1(layersFor, name = "show") {
 					metadata: Boolean(args.metadata),
 					trace: Boolean(args.trace)
 				};
-				const answer = result(resolved.map((entry) => showEntry(entry, home, flags)), { render: bareArray });
+				const answer = result(resolved.map((entry) => showEntry(entry, home, flags)), { render: bareArray$1 });
 				return ok ? answer : answerThenFail(answer, format);
 			} catch (error) {
 				return fail$1(error, "Reference lookup failed.");
@@ -503,9 +255,9 @@ function showCommand$1(layersFor, name = "show") {
 		}
 	});
 }
-function listCommand$1(layersFor, name = "list") {
+function namesCommand(layersFor) {
 	return command({
-		name,
+		name: "names",
 		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.",
 		arguments: [{
 			name: "pattern",
@@ -513,9 +265,9 @@ function listCommand$1(layersFor, name = "list") {
 			type: t.string().optional()
 		}],
 		options: {
-			root: rootOption$1,
+			root: rootOption$2,
 			trace: {
-				...traceOption,
+				...traceOption$1,
 				description: "Add one row per name per layer holding it, with its outcome."
 			}
 		},
@@ -523,25 +275,21 @@ function listCommand$1(layersFor, name = "list") {
 			try {
 				const home = homedir();
 				const display = (path) => collapseHome(home, path);
-				const listing = listReferences(await layersFor(args, home), {
+				const listing = listAssetNames(await layersFor(args, home), {
 					display,
 					pattern: args.pattern
 				});
-				const report = compact({
-					references: listing.references.length ? listing.references.map((row) => compact({
-						name: row.name,
-						description: row.description,
-						format: row.format,
-						status: row.status === "found" ? void 0 : row.status,
-						options: row.options
-					})) : args.pattern ? `0 references match "${args.pattern}"` : "0 references — no layer holds one",
-					defaults: listing.defaults
-				});
-				if (args.trace) report.layers = listing.layers.map((row) => compact({
+				const report = compact$1({ references: listing.references.length ? listing.references.map((row) => compact$1({
+					name: row.name,
+					format: row.format,
+					status: row.status === "found" ? void 0 : row.status,
+					options: row.options
+				})) : args.pattern ? `0 references match "${args.pattern}"` : "0 references — no layer holds one" });
+				if (args.trace) report["layers"] = listing.layers.map((row) => compact$1({
 					...row,
 					path: display(row.path)
 				}));
-				if (listing.warnings.length) report.warnings = listing.warnings;
+				if (listing.warnings.length) report["warnings"] = listing.warnings;
 				return result(report);
 			} catch (error) {
 				return fail$1(error, "Reference listing failed.");
@@ -549,55 +297,9 @@ function listCommand$1(layersFor, name = "list") {
 		}
 	});
 }
-function searchCommand(layersFor) {
-	return command({
-		name: "search",
-		description: "Find references by name, description, tags, headings, or body, best match first.",
-		arguments: [{
-			name: "query",
-			description: "What the reference is about.",
-			type: t.string()
-		}],
-		options: {
-			root: rootOption$1,
-			trace: {
-				...traceOption,
-				description: "Add the tier and plugin or skill of each match."
-			}
-		},
-		async run(args) {
-			const query = args.query.trim();
-			if (!query) usage$1("search needs a query.");
-			try {
-				const home = homedir();
-				const { matches, defaults } = searchReferences(query, await layersFor(args, home), { display: (path) => collapseHome(home, path) });
-				const report = compact({
-					references: matches.length ? matches.map(({ name, description, match, tier, plugin, skill, loadedBy }) => compact(args.trace ? {
-						name,
-						description,
-						match,
-						loadedBy,
-						tier,
-						plugin,
-						skill
-					} : {
-						name,
-						description,
-						match,
-						loadedBy
-					})) : `0 references match "${query}"`,
-					defaults
-				});
-				return result(report);
-			} catch (error) {
-				return fail$1(error, "Reference search failed.");
-			}
-		}
-	});
-}
-function whereCommand(layersFor, assets = false, name = "where") {
+function whereCommand$1(layersFor) {
 	return command({
-		name,
+		name: "where",
 		description: "Give the project and user files a customization or a selection of a reference is written to, who each reaches, and the heading paths of the document below each.",
 		arguments: [{
 			name: "name",
@@ -605,10 +307,10 @@ function whereCommand(layersFor, assets = false, name = "where") {
 			type: t.string()
 		}],
 		options: {
-			root: rootOption$1,
-			default: defaultOption,
+			root: rootOption$2,
+			default: defaultOption$1,
 			trace: {
-				...traceOption,
+				...traceOption$1,
 				description: "Add every layer checked, with its outcome."
 			}
 		},
@@ -617,15 +319,14 @@ function whereCommand(layersFor, assets = false, name = "where") {
 			try {
 				const home = homedir();
 				const display = (path) => collapseHome(home, path);
-				const report = whereReference(args.name, await layersFor(args, home), {
+				const report = whereAsset(args.name, await layersFor(args, home), {
 					root: resolve(args.root ?? process.cwd()),
-					display,
-					assets
+					display
 				});
-				const output = compact({
+				const output = compact$1({
 					name: report.name,
 					status: report.status,
-					places: report.places.map((place) => compact(place)),
+					places: report.places.map((place) => compact$1(place)),
 					options: report.options,
 					layers: args.trace ? report.layers.map((layer) => ({
 						...layer,
@@ -633,10 +334,10 @@ function whereCommand(layersFor, assets = false, name = "where") {
 					})) : void 0,
 					warnings: report.warnings
 				});
-				if (format === "text") writeWarnings(report.warnings);
+				if (format === "text") writeWarnings$1(report.warnings);
 				const answer = result(output);
 				if (report.status !== "invalid") return answer;
-				process.stderr.write(`error: reference-invalid: ${parseReferenceName(args.name).invalid}\n`);
+				process.stderr.write(`error: reference-invalid: ${parseAssetName(args.name).invalid}\n`);
 				return answerThenFail(answer, format);
 			} catch (error) {
 				return fail$1(error, "Reference placement lookup failed.");
@@ -644,384 +345,33 @@ function whereCommand(layersFor, assets = false, name = "where") {
 		}
 	});
 }
-function parseAccept(value) {
-	if (value === void 0) return void 0;
-	const versions = value.split(",").map((part) => part.trim());
-	if (!versions.length || versions.some((part) => !/^[1-9]\d*$/.test(part))) usage$1(`--accept is a comma-separated list of versions, such as 1,2; got "${value}".`);
-	return versions.map(Number);
+/** The tiered, by-name commands over `assets/` folders. `asset`'s own commands act on a path. */
+function createAssetResolveCommands({ plugin } = {}) {
+	const layersFor = layerSource$1(plugin);
+	return {
+		load: loadCommand$1(layersFor),
+		names: namesCommand(layersFor),
+		where: whereCommand$1(layersFor)
+	};
 }
-function implementationsCommand(layersFor) {
-	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.",
-			type: t.string()
-		}],
-		options: {
-			root: rootOption$1,
-			accept: {
-				description: "Versions the consumer knows, comma-separated, such as 1,2. Defaults to the interface's `versions`.",
-				type: t.string().optional()
-			},
-			trace: {
-				...traceOption,
-				description: "Add each one's name, tier, and version, the interface's cardinality and accepted versions, and the ones left out with why."
-			}
-		},
-		async run(args) {
-			const accept = parseAccept(args.accept);
-			try {
-				const home = homedir();
-				const found = referenceImplementations(args.id, await layersFor(args, home), {
-					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,
-					description,
-					unsupported
-				}));
-				const report = { implementations: rows.length ? rows : `0 implementations of ${args.id}` };
-				if (args.trace) Object.assign(report, compact({
-					interface: found.interface,
-					cardinality: found.cardinality,
-					accept: found.accept,
-					excluded: found.excluded,
-					warnings: found.warnings
-				}));
-				return result(report);
-			} catch (error) {
-				return fail$1(error, "Implementation lookup failed.");
-			}
-		}
-	});
-}
-function checkCommand(layersFor) {
-	return command({
-		name: "check",
-		description: "Check interface documents and their implementations, each composed as `show` composes it. With no names, checks every one found. Exits 1 on any failure.",
-		arguments: [{
-			name: "names",
-			description: "Reference names, without the `.md` extension; `<plugin>/<name>` builds that plugin’s own stack.",
-			type: t.array(t.string()).optional()
-		}],
-		options: {
-			root: rootOption$1,
-			trace: {
-				...traceOption,
-				description: "Add every entry checked, with its kind and unsupported sections."
-			}
-		},
-		async run(args) {
-			const format = this.format;
-			try {
-				const home = homedir();
-				const entries = checkReferences(await layersFor(args, home), {
-					names: args.names ?? [],
-					display: (path) => collapseHome(home, path)
-				});
-				const failing = entries.filter((entry) => entry.status !== "passed");
-				const strip = (failures) => failures.map(({ check, message }) => ({
-					check,
-					message
-				}));
-				const report = compact({
-					failed: failing.map(({ name, loadedBy, failures }) => compact({
-						name,
-						loadedBy,
-						failures: strip(failures)
-					})),
-					passed: entries.length - failing.length,
-					references: args.trace ? entries.map(({ name, loadedBy, kind, status, failures, unsupported }) => compact({
-						name,
-						loadedBy,
-						kind,
-						status,
-						failures: strip(failures),
-						unsupported
-					})) : void 0
-				});
-				const answer = result(report);
-				if (!failing.length) return answer;
-				if (format === "text") process.stderr.write(`error: interface-check: ${failing.length} of ${entries.length} references fail their check.\n`);
-				return answerThenFail(answer, format);
-			} catch (error) {
-				return fail$1(error, "Reference check failed.");
-			}
-		}
-	});
-}
-const scopeOption = {
-	description: "Tier to write: project (default), `.agents/references/` at the root, or user, `~/.agents/references/`.",
-	type: t.string().optional()
-};
-const pluginOption = {
-	description: "A plugin's source folder in this repository: acts on its `references/<name>.md`.",
-	type: t.string().optional()
-};
-const skillOption$1 = {
-	description: "A skill's source folder in this repository: acts on its `references/<name>.default.md`.",
-	type: t.string().optional()
-};
-function createCommand(layersFor) {
-	return command({
-		name: "create",
-		description: "Start a contribution in the project or user tier, or in a plugin's or a skill's source folder, from a template or an interface. Never overwrites a file with a body.",
-		arguments: [{
-			name: "name",
-			description: "Reference name, without the `.md` extension.",
-			type: t.string()
-		}],
-		options: {
-			root: rootOption$1,
-			scope: scopeOption,
-			plugin: pluginOption,
-			default: skillOption$1,
-			merge: {
-				description: "How it applies over what is below: replace, patch (default), combine, or remove. remove writes no body.",
-				type: t.string().optional()
-			},
-			template: {
-				description: "File whose text is written as it is, frontmatter included. Defaults to a built-in template of top-level `##` sections.",
-				type: t.string().optional()
-			},
-			implements: {
-				description: "Interface id to implement: the interface's sections become `##` headings, each stubbed `**Unsupported.**`, with `merge: replace`. Not with --template.",
-				type: t.string().optional()
-			},
-			"dry-run": {
-				description: "Print the target path and the exact content, and write nothing.",
-				type: t.boolean().optional()
-			},
-			trace: {
-				...traceOption,
-				description: "After the write, add the trace, in which the new file applies."
-			}
-		},
-		async run(args) {
-			const format = this.format;
-			try {
-				const home = homedir();
-				const root = resolve(args.root ?? process.cwd());
-				const display = (path) => collapseHome(home, path);
-				const created = createContribution(await layersFor({
-					root,
-					default: args.default
-				}, home), {
-					root,
-					home,
-					name: args.name,
-					scope: args.scope,
-					plugin: args.plugin,
-					default: args.default,
-					merge: args.merge,
-					template: args.template,
-					implements: args.implements,
-					dryRun: args["dry-run"]
-				}, { display });
-				const report = compact({
-					path: display(created.path),
-					hint: created.dryRun ? "Nothing was written. Run again without --dry-run to write it." : `Run \`show ${created.name}\` for the composed document.`,
-					content: created.dryRun ? created.content : void 0,
-					hints: created.hints,
-					trace: args.trace && created.after ? displayTrace(created.after.trace, home) : void 0
-				});
-				if (format !== "text") return result(report);
-				for (const hint of created.hints) process.stderr.write(`hint: ${hint}\n`);
-				if (args.trace && created.after) process.stderr.write(traceText(created.after, home));
-				return document(created.dryRun ? `${report.path}\n\n${created.content}` : `${report.path}\n\n${report.hint}\n`);
-			} catch (error) {
-				return fail$1(error, "Reference creation failed.");
-			}
-		}
-	});
-}
-function selectCommand$1(layersFor) {
-	return command({
-		name: "select",
-		description: "Choose what a name builds on: write an `extends` listing the options, bottom first, in the project or user file. Its body and other keys are kept.",
-		arguments: [{
-			name: "name",
-			description: "Reference name, without the `.md` extension.",
-			type: t.string()
-		}, {
-			name: "options",
-			description: "Bottom first: each a plugin holding the name (or `<plugin>/<name>`), or `default`.",
-			type: t.array(t.string()).optional()
-		}],
-		options: {
-			root: rootOption$1,
-			scope: scopeOption,
-			clear: {
-				description: "Remove the selection; a file left with nothing in it is deleted.",
-				type: t.boolean().optional()
-			}
-		},
-		async run(args) {
-			const format = this.format;
-			try {
-				const home = homedir();
-				const root = resolve(args.root ?? process.cwd());
-				const display = (path) => collapseHome(home, path);
-				const selected = selectContribution(await layersFor({ root }, home), {
-					root,
-					home,
-					name: args.name,
-					options: args.options ?? [],
-					scope: args.scope,
-					clear: args.clear
-				}, { display });
-				const report = compact({
-					path: display(selected.path),
-					extends: selected.extends,
-					deleted: selected.deleted || void 0,
-					status: selected.after.status,
-					stack: selected.after.trace.stack,
-					answer: describeAnswer(selected.after, display)
-				});
-				if (format !== "text") return result(report);
-				writeWarnings(selected.after.warnings);
-				const what = args.clear ? selected.deleted ? "selection cleared; the file was left empty and deleted" : "selection cleared" : `extends: [${selected.extends.join(", ")}]`;
-				return document(`${report.path}\n\n${what}. ${report.answer}\n`);
-			} catch (error) {
-				return fail$1(error, "Reference selection failed.");
-			}
-		}
-	});
-}
-function deleteReport(deleted, home) {
-	const selection = deleted.selection ? `the selection extends: [${deleted.selection.join(", ")}] went with it; run \`reference select ${deleted.name} <option>...\` to restore it` : void 0;
-	return compact({
-		path: collapseHome(home, deleted.path),
-		dryRun: deleted.dryRun || void 0,
-		status: deleted.after.status,
-		stack: deleted.after.trace.stack,
-		answer: describeAnswer(deleted.after, (path) => collapseHome(home, path)),
-		selection,
-		options: deleted.after.options
-	});
-}
-function deleteCommand$1(layersFor) {
-	return command({
-		name: "delete",
-		description: "Delete a project or user contribution, or one in a plugin's or a skill's source folder, and report what answers the name afterwards. Never deletes an installed or managed one.",
-		arguments: [{
-			name: "name",
-			description: "Reference name, without the `.md` extension.",
-			type: t.string()
-		}],
-		options: {
-			root: rootOption$1,
-			scope: {
-				...scopeOption,
-				description: "Tier to delete from: project (default) or user."
-			},
-			plugin: pluginOption,
-			default: skillOption$1,
-			"dry-run": {
-				description: "Print the file that would be deleted and what would answer the name then, and delete nothing.",
-				type: t.boolean().optional()
-			}
-		},
-		async run(args) {
-			const format = this.format;
-			try {
-				const home = homedir();
-				const root = resolve(args.root ?? process.cwd());
-				const deleted = deleteContribution(await layersFor({
-					root,
-					default: args.default
-				}, home), {
-					root,
-					home,
-					name: args.name,
-					scope: args.scope,
-					plugin: args.plugin,
-					default: args.default,
-					dryRun: args["dry-run"]
-				}, { display: (path) => collapseHome(home, path) });
-				const report = deleteReport(deleted, home);
-				if (format !== "text") return result(report);
-				const selection = report.selection ? ` Also, ${report.selection}.` : "";
-				return document(`${report.path}\n\n${deleted.dryRun ? "would delete" : "deleted"}. ${report.answer}${selection}\n`);
-			} catch (error) {
-				return fail$1(error, "Reference deletion failed.");
-			}
-		}
-	});
-}
-/** A factory, so each host CLI names itself as the plugin whose own references come first. */
-function createReferenceCommands({ plugin } = {}) {
-	const layersFor = layerSource(plugin);
-	return {
-		show: showCommand$1(layersFor),
-		list: listCommand$1(layersFor),
-		search: searchCommand(layersFor),
-		where: whereCommand(layersFor),
-		create: createCommand(layersFor),
-		select: selectCommand$1(layersFor),
-		delete: deleteCommand$1(layersFor),
-		check: checkCommand(layersFor),
-		implementations: implementationsCommand(layersFor)
-	};
-}
-function createReferenceCommand(options = {}) {
-	const { show, list, search, where, create, select, delete: remove, check, implementations } = createReferenceCommands(options);
-	return command({
-		name: "reference",
-		description: "Read reference documents by name, composed from the managed, project, user, plugin, and default tiers, and write, select, or delete a contribution.",
-		commands: [
-			show,
-			list,
-			search,
-			where,
-			create,
-			select,
-			remove,
-			implementations,
-			check
-		]
-	});
-}
-/**
-* The tiered, by-name commands over `assets/` folders: the reference engine reading `assets/` where it
-* reads `references/`. `load` is `show`, `names` is `list`. `asset`'s own commands act on a path.
-*/
-function createAssetResolveCommands({ plugin } = {}) {
-	const layersFor = layerSource(plugin, "assets");
-	return {
-		load: showCommand$1(layersFor, "load"),
-		names: listCommand$1(layersFor, "names"),
-		where: whereCommand(layersFor, true)
-	};
-}
-//#endregion
-//#region src/assets/skill-assets.ts
-/** A refusal. `usage` marks a wrong invocation (exit 2) rather than a refusal (exit 1). */
-var AssetError = class extends Error {
-	code;
-	usage;
-	constructor(code, message, usage = false) {
-		super(message);
-		this.code = code;
-		this.usage = usage;
-	}
-};
-/** The skill's `assets/` folder, for a skill folder that holds a `SKILL.md`. */
-function assetsDir(skill, root, write) {
-	const folder = resolve(skill);
-	if (skillName(folder) === void 0) throw new AssetError("folder-invalid", `${folder} holds no SKILL.md, so it is not a skill folder.`);
-	if (write && !insideRepository(folder, root)) throw new AssetError("folder-invalid", `${folder} is outside the repository, such as an installed copy; write to the skill's source instead.`);
-	return join(folder, "assets");
+//#endregion
+//#region src/assets/skill-assets.ts
+/** A refusal. `usage` marks a wrong invocation (exit 2) rather than a refusal (exit 1). */
+var AssetError = class extends Error {
+	code;
+	usage;
+	constructor(code, message, usage = false) {
+		super(message);
+		this.code = code;
+		this.usage = usage;
+	}
+};
+/** The skill's `assets/` folder, for a skill folder that holds a `SKILL.md`. */
+function assetsDir(skill, root, write) {
+	const folder = resolve(skill);
+	if (skillName(folder) === void 0) throw new AssetError("folder-invalid", `${folder} holds no SKILL.md, so it is not a skill folder.`);
+	if (write && !insideRepository(folder, root)) throw new AssetError("folder-invalid", `${folder} is outside the repository, such as an installed copy; write to the skill's source instead.`);
+	return join(folder, "assets");
 }
 /** An asset path: relative, `/`-separated, with no `..` or empty part. */
 function assetFile(dir, path) {
@@ -1107,21 +457,20 @@ function deleteAsset(skill, root, path) {
 * were in effect (the managed file would still win).
 */
 function copyAsset(layers, args) {
-	const name = parseReferenceName(args.name);
+	const name = parseAssetName(args.name);
 	if (name.invalid || name.plugin !== void 0) throw new AssetError("name-invalid", name.invalid ?? "create takes a bare name.", true);
 	if (args.scope !== "project" && args.scope !== "user") throw new AssetError("options-invalid", "--scope is project or user.", true);
 	if (args.copy === "managed") throw new AssetError("managed-copy-refused", "the managed tier is policy and is never copied into a project or user folder. Ask the administrator, or read it with \"asset load\".");
-	const found = resolveReference(name.name, layers).trace.layers.filter(({ file }) => file);
+	const found = resolveAsset(name.name, layers).trace.layers.filter(({ file }) => file);
 	const source = found.find((layer) => args.copy === "default" || args.copy === "project" || args.copy === "user" ? layer.tier === args.copy : layer.tier === "plugin" && layer.plugin === args.copy);
 	if (!source) {
 		const held = found.map((layer) => layer.tier === "plugin" ? layer.plugin : layer.tier);
 		throw new AssetError("no-source", `"${args.copy}" holds no asset "${name.name}". Held by: ${held.filter((tier) => tier !== "managed").join(", ") || "nothing"}.`);
 	}
 	const extension = extname(source.path);
-	if (source.file && ![...dataExtensions.map((item) => item.extension), ".md"].includes(extension)) throw new AssetError("no-source", `${basename(source.path)} is not a file an asset name resolves to.`);
-	const base = args.scope === "user" ? userReferencesDir(args.home) : projectReferencesDir(resolve(args.root));
-	const dir = join(dirname(base), "assets");
-	const taken = [".md", ...dataExtensions.map((item) => item.extension)].map((item) => join(dir, `${name.name}${item}`)).find((path) => existsSync(path));
+	if (source.file && ![...assetDataExtensions.map((item) => item.extension), ".md"].includes(extension)) throw new AssetError("no-source", `${basename(source.path)} is not a file an asset name resolves to.`);
+	const dir = args.scope === "user" ? userAssetsDir(args.home) : projectAssetsDir(resolve(args.root));
+	const taken = [".md", ...assetDataExtensions.map((item) => item.extension)].map((item) => join(dir, `${name.name}${item}`)).find((path) => existsSync(path));
 	if (taken) throw new AssetError("exists", `${taken} already exists; edit it, or delete it first.`);
 	const path = join(dir, `${name.name}${extension}`);
 	mkdirSync(dir, { recursive: true });
@@ -1136,7 +485,7 @@ function copyAsset(layers, args) {
 //#region src/assets/select-asset.ts
 /** The options a name can be selected between: each plugin holding it, and `default` when the skill's file exists. */
 function options(layers, name) {
-	const found = resolveReference(name, layers).trace.layers;
+	const found = resolveAsset(name, layers).trace.layers;
 	return [...found.filter(({ tier, file }) => tier === "plugin" && file).map(({ plugin }) => plugin), ...found.some(({ tier, file }) => tier === "default" && file) ? ["default"] : []];
 }
 /**
@@ -1144,11 +493,11 @@ function options(layers, name) {
 * answers the name. Nothing else is in the file, and nothing extends or merges.
 */
 function selectAsset(layers, args) {
-	const name = parseReferenceName(args.name);
+	const name = parseAssetName(args.name);
 	if (name.invalid || name.plugin !== void 0) throw new AssetError("name-invalid", name.invalid ?? "select takes a bare name.", true);
 	if (args.scope !== void 0 && args.scope !== "project" && args.scope !== "user") throw new AssetError("options-invalid", "--scope is project or user.", true);
-	const base = args.scope === "user" ? userReferencesDir(args.home) : projectReferencesDir(resolve(args.root));
-	const path = join(dirname(base), "assets", `${name.name}.select`);
+	const dir = args.scope === "user" ? userAssetsDir(args.home) : projectAssetsDir(resolve(args.root));
+	const path = join(dir, `${name.name}.select`);
 	if (args.clear) {
 		if (!existsSync(path)) throw new AssetError("no-file", `${path} does not exist, so there is no selection to clear.`);
 		rmSync(path);
@@ -1161,7 +510,7 @@ function selectAsset(layers, args) {
 	const result = {
 		path,
 		cleared: Boolean(args.clear),
-		after: resolveReference(name.name, layers, { without: args.clear ? path : void 0 })
+		after: resolveAsset(name.name, layers, { without: args.clear ? path : void 0 })
 	};
 	return args.clear ? result : {
 		...result,
@@ -1170,11 +519,11 @@ function selectAsset(layers, args) {
 }
 //#endregion
 //#region src/assets/asset.command.ts
-const skillOption = {
+const skillOption$1 = {
 	description: "A skill's source folder in this repository: its `assets/` folder is acted on.",
 	type: t.string()
 };
-const rootOption = {
+const rootOption$1 = {
 	description: "The directory the repository is found from. Defaults to the current directory.",
 	type: t.string().optional()
 };
@@ -1195,13 +544,13 @@ const pathDescription = "Asset path inside `assets/`, such as `data/rules.json`.
 function rootOf(args) {
 	return resolve(args.root ?? process.cwd());
 }
-function listCommand() {
+function listCommand$1() {
 	return command({
 		name: "list",
 		description: "List every file in a skill's assets/ folder with its size.",
 		options: {
-			skill: skillOption,
-			root: rootOption
+			skill: skillOption$1,
+			root: rootOption$1
 		},
 		async run(args) {
 			try {
@@ -1223,8 +572,8 @@ function showCommand() {
 			type: t.string()
 		}],
 		options: {
-			skill: skillOption,
-			root: rootOption
+			skill: skillOption$1,
+			root: rootOption$1
 		},
 		async run(args) {
 			try {
@@ -1247,10 +596,10 @@ function writeCommand(mode, host) {
 		}],
 		options: {
 			skill: {
-				...skillOption,
+				...skillOption$1,
 				type: t.string().optional()
 			},
-			root: rootOption,
+			root: rootOption$1,
 			content: {
 				description: "The text to write.",
 				type: t.string().optional()
@@ -1280,14 +629,13 @@ function writeCommand(mode, host) {
 					if (args.content !== void 0 || args.from !== void 0) usage("--copy takes neither --content nor --from.");
 					const home = homedir();
 					const root = rootOf(args);
-					const done = copyAsset(await referenceLayers({
+					const done = copyAsset(await assetLayers({
 						root,
 						home,
 						platform: process.platform,
 						env: process.env,
 						plugin: host.plugin,
-						defaultSkill: args.default ?? args.skill,
-						folder: "assets"
+						defaultSkill: args.default ?? args.skill
 					}), {
 						root,
 						home,
@@ -1308,7 +656,7 @@ function writeCommand(mode, host) {
 		}
 	});
 }
-function deleteCommand() {
+function deleteCommand$1() {
 	return command({
 		name: "delete",
 		description: "Delete an asset from a skill's source folder, and any folder it leaves empty.",
@@ -1318,8 +666,8 @@ function deleteCommand() {
 			type: t.string()
 		}],
 		options: {
-			skill: skillOption,
-			root: rootOption
+			skill: skillOption$1,
+			root: rootOption$1
 		},
 		async run(args) {
 			try {
@@ -1344,7 +692,7 @@ function selectCommand(options) {
 			type: t.string().optional()
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			default: {
 				description: "The calling skill's folder: its `assets/<name>.<ext>` is the `default` option.",
 				type: t.string().optional()
@@ -1362,14 +710,13 @@ function selectCommand(options) {
 			try {
 				const home = homedir();
 				const root = resolve(args.root ?? process.cwd());
-				const done = selectAsset(await referenceLayers({
+				const done = selectAsset(await assetLayers({
 					root,
 					home,
 					platform: process.platform,
 					env: process.env,
 					plugin: options.plugin,
-					defaultSkill: args.default,
-					folder: "assets"
+					defaultSkill: args.default
 				}), {
 					...args,
 					root,
@@ -1389,11 +736,11 @@ function createAssetCommand(options = {}) {
 		name: "asset",
 		description: "Manage a skill's assets/ files by path (list, show, create, update, delete), and load one by name through the tiers (load, names, where, select).",
 		commands: [
-			listCommand(),
+			listCommand$1(),
 			showCommand(),
 			writeCommand("create", options),
 			writeCommand("update", options),
-			deleteCommand(),
+			deleteCommand$1(),
 			load,
 			names,
 			where,
@@ -1402,4 +749,918 @@ function createAssetCommand(options = {}) {
 	});
 }
 //#endregion
+//#region src/references/reference-command-support.ts
+const rootOption = {
+	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()
+};
+const traceOption = {
+	description: "Add the trace: every layer checked, with its outcome, and how the result was built.",
+	type: t.boolean().optional()
+};
+const defaultOption = {
+	description: "The calling skill's folder: its `references/<name>.default.md` joins as the `default` tier.",
+	type: t.string().optional()
+};
+function layerSource(plugin) {
+	return (args, home) => referenceLayers({
+		root: args.root,
+		cwd: process.cwd(),
+		home,
+		platform: process.platform,
+		env: process.env,
+		plugin,
+		defaultSkill: args.default
+	});
+}
+/** A field with nothing to say is left out: `undefined`, an empty string, or an empty list. */
+function compact(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0 && field !== "" && !(Array.isArray(field) && !field.length)));
+}
+/**
+* A thrown failure as the one axi error value the cli prints on stdout: a `ReferenceFailure` keeps its
+* code and exits 1, or 2 for a usage error; a `CliError` passes through.
+*/
+function asCliError(error, fallback) {
+	if (isCliError(error)) throw error;
+	if (error instanceof ReferenceFailure) throw new CliError(error.message, {
+		code: error.code,
+		exitCode: error.usage ? exitCodes.usage : exitCodes.error,
+		details: error.details,
+		help: error.help
+	});
+	throw new CliError(error instanceof Error ? error.message : fallback, { cause: error });
+}
+function writeWarnings(warnings) {
+	for (const { code, message } of warnings) process.stderr.write(`warning: ${code}: ${message}\n`);
+}
+function displayTrace(trace, home) {
+	const show = (path) => collapseHome(home, path);
+	return {
+		...trace,
+		contributions: trace.contributions.map((row) => ({
+			...row,
+			path: show(row.path)
+		})),
+		layers: trace.layers.map((layer) => ({
+			...layer,
+			path: show(layer.path)
+		})),
+		projectSections: trace.projectSections.map((row) => ({
+			...row,
+			path: show(row.path)
+		}))
+	};
+}
+/** A generated document's record in the text trace: each source, recorded and installed, then the request (R46). */
+function recordLines(row, indent) {
+	const lines = (row.sources ?? []).map((source) => {
+		return `${indent}source ${source.default !== void 0 ? `default ${source.default}${source.plugin ? ` (plugin ${source.plugin})` : ""}` : `plugin ${source.plugin}`}: recorded ${source.recorded ?? "no version"}, installed ${source.status === "missing" ? "not installed" : source.installed ?? "no version"} (${source.status})`;
+	});
+	if (row.request !== void 0) lines.push(`${indent}request:`, ...row.request.replace(/\n$/, "").split("\n").map((line) => `${indent}  ${line}`));
+	return lines;
+}
+/** The text trace: a summary line, then each section with its contributions, then each layer. */
+function traceText(resolved, home) {
+	const trace = displayTrace(resolved.trace, home);
+	const lines = [`${resolved.name}: ${resolved.status}; stack: ${trace.stack.join(" → ") || "none"}; built by ${trace.builtBy}; harnesses: ${trace.harnesses.join(", ") || "none detected"}`];
+	if (resolved.message) lines.push(`  ${resolved.message}`);
+	if (trace.sections.length) {
+		lines.push("sections:");
+		for (const section of trace.sections) {
+			const how = section.removedBy ? `removed by ${section.removedBy}` : section.contributions.map(({ contribution, operation }) => `${contribution} (${operation})`).join(", ") || "no text";
+			lines.push(`  ${section.path}: ${how}`);
+		}
+	}
+	lines.push("layers:");
+	for (const layer of trace.layers) {
+		const who = layer.plugin ? ` ${layer.plugin}` : layer.skill ? ` ${layer.skill}` : "";
+		const how = layer.operation ? `; ${layer.operation} from ${layer.operationFrom}` : "";
+		const extendsNote = layer.extendsOutcome ? `; extends ${layer.extendsOutcome}` : "";
+		const selection = layer.selection ? "; selection" : "";
+		const frontmatter = layer.frontmatter && Object.keys(layer.frontmatter).length ? ` ${JSON.stringify(layer.frontmatter)}` : "";
+		lines.push(`  ${layer.tier}${who} ${layer.path}: ${layer.outcome}${how}${extendsNote}${selection}${frontmatter}`);
+		lines.push(...recordLines(layer, "    "));
+	}
+	if (trace.projectSections.length) {
+		lines.push("project sections:");
+		for (const row of trace.projectSections) {
+			const frontmatter = row.frontmatter && Object.keys(row.frontmatter).length ? ` ${JSON.stringify(row.frontmatter)}` : "";
+			const from = row.plugin === void 0 ? "" : ` (plugin ${row.plugin}${row.version ? `@${row.version}` : ""})`;
+			lines.push(`  ${row.folder}${from} ${row.path}: ${row.outcome}${frontmatter}`);
+			lines.push(...recordLines(row, "    "));
+			for (const section of row.sections ?? []) {
+				const how = section.contributions.map(({ contribution, operation }) => `${contribution} (${operation})`).join(", ");
+				lines.push(`    ${section.path}: ${how || "no text"}`);
+			}
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}
+function escapeText(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttribute(value) {
+	return escapeText(value).replace(/"/g, "&quot;");
+}
+/** A name not `found`, in text: its status and code, holding its message, and its options when ambiguous. */
+function notFoundTag(entry) {
+	const options = entry.options?.length ? `; options: ${entry.options.join(", ")}` : "";
+	return `<reference name="${escapeAttribute(entry.name)}" status="${entry.status}" code="${entry.code}">${escapeText(`${entry.message ?? entry.status}${options}`)}</reference>`;
+}
+/**
+* A found name's text: the main document, then each project section wrapped with its folder, in path
+* order, keeping its own heading levels (R44). A package plugin's section also names the plugin, so
+* the agent can put the folder's own section over it (R90).
+*/
+function deliveredText(entry) {
+	const content = entry.content ?? "";
+	if (!entry.projectSections.length) return content;
+	return `${[...content.trim() ? [content.trimEnd()] : [], ...entry.projectSections.map(({ folder, plugin, content: text }) => `<project folder="${escapeAttribute(folder)}"${plugin === void 0 ? "" : ` plugin="${escapeAttribute(plugin)}"`}>\n${text}</project>`)].join("\n\n")}\n`;
+}
+/** A found name among several, in text. */
+function referenceTag(name, content) {
+	return `<reference name="${escapeAttribute(name)}">\n${content}</reference>`;
+}
+const scopeOption = {
+	description: "Tier to write: repo (default), `.agents/references/` at the root, or user, `~/.agents/references/`.",
+	type: t.string().optional()
+};
+const inOption = {
+	description: "A folder strictly below the root, which must exist and not be ignored by git: acts on its project section, `<folder>/.agents/references/<name>.md`.",
+	type: t.string().optional()
+};
+/** The root a write checks its usage against before the layers are read: `--root`, else the one found from the working folder. */
+function givenRoot(root) {
+	return root === void 0 ? findRoot(process.cwd()) : resolve(root);
+}
+const pluginOption = {
+	description: "A plugin's source folder in this repository: acts on its `references/<name>.md`.",
+	type: t.string().optional()
+};
+const skillOption = {
+	description: "A skill's source folder in this repository: acts on its `references/<name>.default.md`.",
+	type: t.string().optional()
+};
+//#endregion
+//#region src/references/reference-check.command.ts
+function checkCommand(layersFor) {
+	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.",
+		arguments: [{
+			name: "names",
+			description: "Reference names, without the `.md` extension; `<plugin>/<name>` builds that plugin’s own stack.",
+			type: t.array(t.string()).optional()
+		}],
+		options: {
+			root: rootOption,
+			trace: {
+				...traceOption,
+				description: "Add every entry checked, with its kind and unsupported sections."
+			}
+		},
+		async run(args) {
+			try {
+				const home = homedir();
+				const entries = checkReferences(await layersFor(args, home), {
+					names: args.names ?? [],
+					display: (path) => collapseHome(home, path)
+				});
+				const failing = entries.filter((entry) => entry.failures.length);
+				const strip = (failures) => failures.map(({ check, message }) => ({
+					check,
+					message
+				}));
+				const report = compact({
+					failed: failing.map(({ name, loadedBy, failures, warnings }) => compact({
+						name,
+						loadedBy,
+						failures: strip(failures),
+						warnings
+					})),
+					warned: entries.filter((entry) => !entry.failures.length && entry.warnings.length).map(({ name, loadedBy, warnings }) => compact({
+						name,
+						loadedBy,
+						warnings
+					})),
+					passed: entries.length - failing.length,
+					references: args.trace ? entries.map(({ name, loadedBy, kind, status, failures, unsupported, warnings }) => compact({
+						name,
+						loadedBy,
+						kind,
+						status,
+						failures: strip(failures),
+						unsupported,
+						warnings
+					})) : void 0
+				});
+				return result(report);
+			} catch (error) {
+				return asCliError(error, "Reference check failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference-create.command.ts
+function createCommand(layersFor) {
+	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.",
+		arguments: [{
+			name: "name",
+			description: "Reference name, without the `.md` extension.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			scope: scopeOption,
+			in: inOption,
+			plugin: pluginOption,
+			default: skillOption,
+			merge: {
+				description: "How it applies over what is below: replace, patch (default), combine, or remove. remove writes no body.",
+				type: t.string().optional()
+			},
+			template: {
+				description: "File whose text is written as it is, frontmatter included. Defaults to a built-in template of top-level `##` sections.",
+				type: t.string().optional()
+			},
+			implements: {
+				description: "Interface id to implement: the interface's sections become `##` headings, each stubbed `**Unsupported.**` with what it holds, and `merge: replace`; with --in, a project section with neither. Not with --template.",
+				type: t.string().optional()
+			},
+			"dry-run": {
+				description: "Print the target path and the exact content, and write nothing.",
+				type: t.boolean().optional()
+			},
+			trace: {
+				...traceOption,
+				description: "After the write, add the trace, in which the new file applies."
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const display = (path) => collapseHome(home, path);
+				const request = {
+					root: givenRoot(args.root),
+					home,
+					name: args.name,
+					scope: args.scope,
+					in: args.in,
+					plugin: args.plugin,
+					default: args.default,
+					merge: args.merge,
+					template: args.template,
+					implements: args.implements,
+					dryRun: args["dry-run"]
+				};
+				validateWrite({
+					command: "create",
+					...request
+				});
+				const layers = await layersFor({
+					root: args.root,
+					default: args.default
+				}, home);
+				const created = createContribution(layers, {
+					...request,
+					root: layers.root ?? request.root
+				}, { display });
+				const report = compact({
+					path: display(created.path),
+					folder: created.folder,
+					hint: created.dryRun ? "Nothing was written. Run again without --dry-run to write it." : `Run \`load ${created.name}\` for the composed document.`,
+					content: created.dryRun ? created.content : void 0,
+					hints: created.hints,
+					warnings: created.warnings,
+					trace: args.trace && created.after ? displayTrace(created.after.trace, home) : void 0
+				});
+				if (format !== "text") return result(report);
+				writeWarnings(created.warnings);
+				for (const hint of created.hints) process.stderr.write(`hint: ${hint}\n`);
+				if (args.trace && created.after) process.stderr.write(traceText(created.after, home));
+				return document(created.dryRun ? `${report.path}\n\n${created.content}` : `${report.path}\n\n${report.hint}\n`);
+			} catch (error) {
+				return asCliError(error, "Reference creation failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference-customize.command.ts
+function baseReport(customized) {
+	const base = customized.base;
+	const resolved = base?.resolved;
+	return compact({
+		status: resolved?.status ?? "missing",
+		stack: resolved?.trace.stack,
+		content: base?.content ?? "",
+		projectSections: base?.projectSections.map(({ folder, content }) => ({
+			folder,
+			content
+		}))
+	});
+}
+function baseText(customized) {
+	const base = customized.base;
+	if (!base) return "";
+	if (!base.content && !base.projectSections.length && base.resolved.status !== "found") return `${notFoundTag(base.resolved)}\n`;
+	return deliveredText({
+		...base.resolved,
+		content: base.content,
+		projectSections: base.projectSections
+	});
+}
+function report(customized, args, home) {
+	const display = (path) => collapseHome(home, path);
+	const after = customized.after;
+	return compact({
+		path: display(customized.path),
+		folder: customized.folder,
+		metadataFile: customized.metadataFile === void 0 ? void 0 : display(customized.metadataFile),
+		code: customized.code,
+		message: customized.message,
+		extends: customized.extends,
+		deleted: customized.deleted,
+		status: after?.status,
+		stack: after?.trace.stack,
+		answer: after ? describeAnswer(after, display) : void 0,
+		hint: customized.dryRun ? "Nothing was written. Run again without --dry-run to write it." : customized.code ? void 0 : `Run \`load ${customized.name}\` for the composed document.`,
+		content: customized.dryRun ? customized.content : void 0,
+		metadataContent: customized.dryRun ? customized.metadataContent : void 0,
+		hints: customized.hints,
+		warnings: customized.warnings,
+		trace: args.trace && after && !customized.code ? displayTrace(after.trace, home) : void 0
+	});
+}
+function text(customized, shown) {
+	if (customized.code) return `${shown.path}\n\n${customized.code}: ${customized.message}\n`;
+	if (customized.dryRun) {
+		const head = customized.deleted ? "would delete the file, left with nothing in it.\n" : customized.content ?? "";
+		const meta = customized.metadataContent === void 0 ? "" : `\n${shown.metadataFile}\n\n${customized.metadataContent}`;
+		return `${shown.path}\n\n${head}${meta}`;
+	}
+	if (customized.action === "cleared") {
+		const what = customized.deleted ? "selection removed; the file was left empty and deleted" : "selection removed";
+		return `${shown.path}\n\n${what}. ${shown.answer}\n`;
+	}
+	if (customized.action === "selection") return `${shown.path}\n\nextends: ${JSON.stringify(customized.extends)}. ${shown.answer}\n`;
+	const meta = shown.metadataFile ? ` Its record is in ${shown.metadataFile}.` : "";
+	return `${shown.path}\n\n${shown.hint}${meta}\n`;
+}
+function customizeCommand(layersFor) {
+	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.",
+			type: t.string()
+		}, {
+			name: "steps",
+			description: "More steps for --extends, so `--extends a b` lists both, bottom first.",
+			type: t.array(t.string()).optional()
+		}],
+		options: {
+			root: rootOption,
+			scope: scopeOption,
+			in: {
+				...inOption,
+				description: `${inOption.description} Takes no --extends or --merge.`
+			},
+			default: {
+				description: "The calling skill's folder, read only: its `references/<name>.default.md` joins the stack as the `default` tier.",
+				type: t.string().optional()
+			},
+			plugin: {
+				description: "Not accepted: customize never writes a plugin's file; an author uses `create --plugin`.",
+				type: t.string().optional()
+			},
+			extends: {
+				description: "The picks, bottom first: each a plugin holding the name, `<plugin>:<merge>` (such as `house-style:combine`), or `default`; `none` removes them. A file with no body is a selection.",
+				type: t.array(t.string()).optional()
+			},
+			"extends-file": {
+				description: "A YAML file holding the whole `extends` list, with every step key (`merge`, `extends`, `sections`).",
+				type: t.string().optional()
+			},
+			request: {
+				description: "A file holding the customizer's request, in their own words; recorded as `request`. Needs --body.",
+				type: t.string().optional()
+			},
+			body: {
+				description: "A file holding the body the generator wrote; written as given, with the picks, sources, and request recorded. Needs --request.",
+				type: t.string().optional()
+			},
+			merge: {
+				description: "How the body applies over what is below: patch (default), combine, or replace for a whole document.",
+				type: t.string().optional()
+			},
+			implements: {
+				description: "Interface id the body implements: a whole document recording `implements` and `merge: replace`; with --in, a project section from the interface's stub.",
+				type: t.string().optional()
+			},
+			base: {
+				description: "Print what the generator reads for the target, and write nothing: the name resolved with the picks, leaving out the target file, managed text, the tier above, and personal text; with --implements, the interface's stub first.",
+				type: t.boolean().optional()
+			},
+			"dry-run": {
+				description: "Print the target path and the exact content, and write nothing.",
+				type: t.boolean().optional()
+			},
+			trace: {
+				...traceOption,
+				description: "After the write, add the trace, in which the written file applies."
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const display = (path) => collapseHome(home, path);
+				const picks = args.extends === void 0 ? void 0 : [...args.extends, ...args.steps ?? []];
+				const request = {
+					root: givenRoot(args.root),
+					home,
+					name: args.name,
+					scope: args.scope,
+					in: args.in,
+					plugin: args.plugin,
+					default: args.default,
+					extends: picks,
+					extendsFile: args["extends-file"],
+					request: args.request,
+					body: args.body,
+					merge: args.merge,
+					implements: args.implements,
+					base: args.base,
+					dryRun: args["dry-run"]
+				};
+				validateWrite({
+					command: "customize",
+					...request
+				});
+				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);
+				const customized = customizeContribution(layers, {
+					...request,
+					root: layers.root ?? request.root
+				}, { display });
+				if (customized.action === "base") {
+					if (format !== "text") return result(baseReport(customized));
+					return document(baseText(customized));
+				}
+				const shown = report(customized, args, home);
+				if (format !== "text") return result(shown);
+				writeWarnings(customized.warnings);
+				for (const hint of customized.hints) process.stderr.write(`hint: ${hint}\n`);
+				if (args.trace && customized.after && !customized.code) process.stderr.write(traceText(customized.after, home));
+				return document(text(customized, shown));
+			} catch (error) {
+				return asCliError(error, "Reference customization failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference-delete.command.ts
+function deleteReport(deleted, home) {
+	const selection = deleted.selection ? `the selection extends: [${deleted.selection.join(", ")}] went with it; run \`reference customize ${deleted.name} --extends ${deleted.selection.join(" ")}\` to restore it` : void 0;
+	return compact({
+		path: collapseHome(home, deleted.path),
+		folder: deleted.folder,
+		metadataFile: deleted.metadataFile === void 0 ? void 0 : collapseHome(home, deleted.metadataFile),
+		code: deleted.code,
+		message: deleted.message,
+		dryRun: deleted.dryRun || void 0,
+		status: deleted.after.status,
+		stack: deleted.after.trace.stack,
+		answer: describeAnswer(deleted.after, (path) => collapseHome(home, path)),
+		selection,
+		options: deleted.after.options
+	});
+}
+function deleteCommand(layersFor) {
+	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.",
+		arguments: [{
+			name: "name",
+			description: "Reference name, without the `.md` extension.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			scope: {
+				...scopeOption,
+				description: "Tier to delete from: repo (default) or user."
+			},
+			in: inOption,
+			plugin: pluginOption,
+			default: skillOption,
+			"dry-run": {
+				description: "Print the file that would be deleted and what would answer the name then, and delete nothing.",
+				type: t.boolean().optional()
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const request = {
+					root: givenRoot(args.root),
+					home,
+					name: args.name,
+					scope: args.scope,
+					in: args.in,
+					plugin: args.plugin,
+					default: args.default,
+					dryRun: args["dry-run"]
+				};
+				validateWrite({
+					command: "delete",
+					...request
+				});
+				const layers = await layersFor({
+					root: args.root,
+					default: args.default
+				}, home);
+				const deleted = deleteContribution(layers, {
+					...request,
+					root: layers.root ?? request.root
+				}, { display: (path) => collapseHome(home, path) });
+				const report = deleteReport(deleted, home);
+				if (format !== "text") return result(report);
+				if (deleted.code) return document(`${report.path}\n\n${deleted.code}: ${deleted.message}\n`);
+				const selection = report.selection ? ` Also, ${report.selection}.` : "";
+				const metadata = report.metadataFile ? ` Its metadata file ${report.metadataFile} went with it.` : "";
+				return document(`${report.path}\n\n${deleted.dryRun ? "would delete" : "deleted"}. ${report.answer}${metadata}${selection}\n`);
+			} catch (error) {
+				return asCliError(error, "Reference deletion failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference-implementations.command.ts
+function parseAccept(value) {
+	if (value === void 0) return void 0;
+	const versions = value.split(",").map((part) => part.trim());
+	if (!versions.length || versions.some((part) => !/^[1-9]\d*$/.test(part))) throw new ReferenceFailure("option-invalid", `--accept is a comma-separated list of versions, such as 1,2; got "${value}".`, { details: {
+		option: "--accept",
+		value
+	} });
+	return versions.map(Number);
+}
+function implementationsCommand(layersFor) {
+	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.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			accept: {
+				description: "Versions the consumer knows, comma-separated, such as 1,2. Defaults to the interface's `versions`.",
+				type: t.string().optional()
+			},
+			trace: {
+				...traceOption,
+				description: "Add each one's name, tier, and version, the interface's cardinality and accepted versions, and the ones left out with why."
+			}
+		},
+		async run(args) {
+			try {
+				const accept = parseAccept(args.accept);
+				const home = homedir();
+				const found = referenceImplementations(args.id, await layersFor(args, home), {
+					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
+				}));
+				return result(report);
+			} catch (error) {
+				return asCliError(error, "Implementation lookup failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference-list.command.ts
+function listCommand(layersFor) {
+	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.",
+		arguments: [{
+			name: "pattern",
+			description: "Exact name pattern, where `*` stands for any run of characters, such as `project-tracker.capabilities.*`.",
+			type: t.string().optional()
+		}],
+		options: {
+			root: rootOption,
+			trace: {
+				...traceOption,
+				description: "Add one row per name per layer holding it, with its outcome."
+			}
+		},
+		async run(args) {
+			try {
+				const home = homedir();
+				const display = (path) => collapseHome(home, path);
+				const listing = listReferences(await layersFor(args, home), {
+					display,
+					pattern: args.pattern
+				});
+				const traced = args.trace && listing.layers.length > 0;
+				if (!listing.references.length && !traced && !listing.warnings.length) return empty(args.pattern ? `0 references match "${args.pattern}"` : "0 references — no layer holds one", { help: [...listing.defaults ? [listing.defaults] : [], args.pattern ? "Run `reference list` with no pattern for every name, or `reference search <query>` by topic." : "Run `reference create <name>` to start one."] });
+				const report = { references: listing.references.map((row) => compact({
+					name: row.name,
+					description: row.description,
+					format: row.format,
+					status: row.status === "found" ? void 0 : row.status,
+					code: row.code,
+					options: row.options
+				})) };
+				if (listing.defaults) report.defaults = listing.defaults;
+				if (args.trace) report.layers = listing.layers.map((row) => compact({
+					...row,
+					path: display(row.path)
+				}));
+				if (listing.warnings.length) report.warnings = listing.warnings;
+				return result(report);
+			} catch (error) {
+				return asCliError(error, "Reference listing failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference-load.command.ts
+function loadEntry(resolved, home, { metadata, trace }) {
+	if (resolved.status === "found" && !resolved.warnings.length && !resolved.projectSections.length && !metadata && !trace && resolved.format === "markdown") return resolved.content;
+	return compact({
+		name: resolved.name,
+		status: resolved.status,
+		content: resolved.content,
+		projectSections: resolved.projectSections.map(({ folder, plugin, content }) => plugin === void 0 ? {
+			folder,
+			content
+		} : {
+			folder,
+			plugin,
+			content
+		}),
+		format: resolved.format === "markdown" ? void 0 : resolved.format,
+		code: resolved.code,
+		options: resolved.options,
+		metadata: metadata ? resolved.metadata : void 0,
+		warnings: resolved.warnings,
+		trace: trace ? displayTrace(resolved.trace, home) : void 0
+	});
+}
+/** One entry per name asked, as the array itself rather than under a `result` key. */
+const bareArray = {
+	toon: (entries) => encode(entries, "toon"),
+	json: (entries) => encode(entries, "json")
+};
+/** One found name prints alone; several, and any name not `found`, print as `<reference>` tags in the order asked. */
+function loadText(resolved) {
+	const tag = (entry) => entry.status === "found" ? referenceTag(entry.name, deliveredText(entry)) : notFoundTag(entry);
+	if (resolved.length === 1) {
+		const [only] = resolved;
+		return document(only.status === "found" ? deliveredText(only) : notFoundTag(only));
+	}
+	return document(resolved.map(tag).join("\n\n"));
+}
+function loadCommand(layersFor) {
+	return command({
+		name: "load",
+		description: "Print one or more references, each composed from its contributions as their extends and merge declare.",
+		arguments: [{
+			name: "names",
+			description: "Reference names, without the `.md` extension; `<plugin>/<name>` builds that plugin’s own stack.",
+			type: t.array(t.string())
+		}],
+		options: {
+			root: rootOption,
+			default: defaultOption,
+			metadata: {
+				description: "Make every entry a record with its status and composed frontmatter.",
+				type: t.boolean().optional()
+			},
+			trace: traceOption
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				if (!args.names.length) throw new ReferenceFailure("name-missing", "name at least one reference to load.", { help: "Run `reference load <name>...`, or `reference list` for every name." });
+				for (const name of args.names) requireName(name);
+				const home = homedir();
+				const layers = await layersFor(args, home);
+				const display = (path) => collapseHome(home, path);
+				const lookup = interfaceLookup(layers, { display });
+				const resolved = args.names.map((name) => {
+					const entry = resolveReference(parseReferenceName(name), layers, { display });
+					const checked = checkResolved(entry, lookup);
+					entry.warnings.push(...checked.warnings);
+					for (const failure of checked.failures) {
+						if (failure.check === "compose") continue;
+						entry.warnings.push({
+							code: "interface-check",
+							message: `it fails its interface check (${failure.check}): ${failure.message}`
+						});
+					}
+					return entry;
+				});
+				if (format === "text") {
+					for (const entry of resolved) {
+						writeWarnings(entry.warnings);
+						if (args.trace) process.stderr.write(traceText(entry, home));
+					}
+					return loadText(resolved);
+				}
+				const flags = {
+					metadata: Boolean(args.metadata),
+					trace: Boolean(args.trace)
+				};
+				return result(resolved.map((entry) => loadEntry(entry, home, flags)), { render: bareArray });
+			} catch (error) {
+				return asCliError(error, "Reference lookup failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference-search.command.ts
+function searchCommand(layersFor) {
+	return command({
+		name: "search",
+		description: "Find references by name, description, tags, headings, or body, best match first.",
+		arguments: [{
+			name: "query",
+			description: "What the reference is about.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			trace: {
+				...traceOption,
+				description: "Add the tier and plugin or skill of each match."
+			}
+		},
+		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."] });
+				const report = compact({
+					references: matches.map(({ name, description, match, folder, tier, plugin, skill, loadedBy }) => compact(args.trace ? {
+						name,
+						description,
+						match,
+						folder,
+						loadedBy,
+						tier,
+						plugin,
+						skill
+					} : {
+						name,
+						description,
+						match,
+						folder,
+						loadedBy
+					})),
+					defaults
+				});
+				return result(report);
+			} catch (error) {
+				return asCliError(error, "Reference search failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference-where.command.ts
+function whereCommand(layersFor) {
+	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.",
+		arguments: [{
+			name: "name",
+			description: "Reference name, without the `.md` extension.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			default: defaultOption,
+			in: {
+				...inOption,
+				description: "A folder strictly below the root: also give its project section's file."
+			},
+			trace: {
+				...traceOption,
+				description: "Add every layer checked, with its outcome."
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const display = (path) => collapseHome(home, path);
+				const layers = await layersFor(args, home);
+				const report = whereReference(args.name, layers, {
+					root: layers.root ?? givenRoot(args.root),
+					display,
+					in: args.in
+				});
+				const output = compact({
+					name: report.name,
+					status: report.status,
+					files: report.files,
+					headings: report.headings,
+					used: report.used,
+					options: report.options,
+					hint: report.used.length ? `${report.used.join(", ")} ${report.used.length === 1 ? "is" : "are"} read-only; a customization goes in one of the files.` : void 0,
+					layers: args.trace ? report.layers.map((layer) => ({
+						...layer,
+						path: display(layer.path)
+					})) : void 0,
+					warnings: report.warnings
+				});
+				if (format === "text") writeWarnings(report.warnings);
+				return result(output);
+			} catch (error) {
+				return asCliError(error, "Reference placement lookup failed.");
+			}
+		}
+	});
+}
+//#endregion
+//#region src/references/reference.command.ts
+/** A factory, so each host CLI names itself as the plugin whose own references come first. */
+function createReferenceCommands({ plugin } = {}) {
+	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)
+	};
+}
+function createReferenceCommand(options = {}) {
+	const { load, list, search, where, create, customize, delete: remove, 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.",
+		commands: [
+			load,
+			list,
+			search,
+			where,
+			create,
+			customize,
+			remove,
+			implementations,
+			check
+		]
+	});
+}
+//#endregion
 export { createAssetCommand, createReferenceCommand, createReferenceCommands };