cyber-agentkit 1.0.0 → 1.1.0

package/dist/commands.js

@@ -1,7 +1,7 @@
-import { C as userReferencesDir, E as require_dist, M as pluginManifestName, S as repositoryRoot, _ as parseSections, a as interfaceLookup, b as projectReferencesDir, c as readExtends, d as parseReferenceName, f as fitsName, g as parseDocument, h as isMergeOperation, i as checkResolved, m as hasBody, n as referenceImplementations, o as listReferences, p as frontmatterPattern, r as checkReferences, s as searchReferences, t as whereReference, u as resolveReference, v as canonical, w as skillName, x as referenceLayers } from "./reference-where-BhymfNgA.js";
-import { dirname, join, resolve, sep } from "node:path";
+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 { homedir } from "node:os";
-import { existsSync, mkdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+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 { command, exitCodes, t } from "clibuilder";
 import { CliError, document, encode, isCliError, printAnswer, result } from "clibuilder/axi";
 //#region src/command-output/collapse-home.ts
@@ -286,12 +286,20 @@ function selectContribution(layers, args, options = {}) {
 		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")] : [target.path]).find((candidate) => candidate !== options.without && existsSync(candidate));
+	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);
@@ -316,7 +324,7 @@ function deleteContribution(layers, args, options = {}) {
 }
 //#endregion
 //#region src/references/reference.command.ts
-const rootOption = {
+const rootOption$1 = {
 	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()
 };
@@ -328,14 +336,15 @@ 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) {
+function layerSource(plugin, folder = "references") {
 	return (args, home) => referenceLayers({
 		root: args.root ?? process.cwd(),
 		home,
 		platform: process.platform,
 		env: process.env,
 		plugin,
-		defaultSkill: args.default
+		defaultSkill: args.default,
+		folder
 	});
 }
 /** A field with nothing to say is left out: `undefined`, an empty string, or an empty list. */
@@ -343,7 +352,7 @@ function compact(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(error, fallback) {
+function fail$1(error, fallback) {
 	if (isCliError(error)) throw error;
 	if (error instanceof ReferenceWriteError) {
 		process.stderr.write(`error: ${error.code}: ${error.message}\n`);
@@ -352,7 +361,7 @@ function fail(error, fallback) {
 	process.stderr.write(`error: ${error instanceof Error ? error.message : fallback}\n`);
 	throw CliError.reported(exitCodes.error);
 }
-function usage(message) {
+function usage$1(message) {
 	process.stderr.write(`error: usage: ${message}\n`);
 	throw CliError.reported(exitCodes.usage);
 }
@@ -408,11 +417,12 @@ function errorText(entry) {
 	return `${entry.name}: ${entry.message}${options}`;
 }
 function showEntry(resolved, home, { metadata, trace }) {
-	if (resolved.status === "found" && !resolved.warnings.length && !metadata && !trace) return resolved.content;
+	if (resolved.status === "found" && !resolved.warnings.length && !metadata && !trace && resolved.format === "markdown") return resolved.content;
 	return compact({
 		name: resolved.name,
 		status: resolved.status,
 		content: resolved.content,
+		format: resolved.format === "markdown" ? void 0 : resolved.format,
 		code: resolved.code,
 		options: resolved.options,
 		metadata: metadata ? resolved.metadata : void 0,
@@ -433,9 +443,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(layersFor) {
+function showCommand$1(layersFor, name = "show") {
 	return command({
-		name: "show",
+		name,
 		description: "Print one or more references, each composed from its contributions as their extends and merge declare.",
 		arguments: [{
 			name: "names",
@@ -443,7 +453,7 @@ function showCommand(layersFor) {
 			type: t.array(t.string())
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			default: defaultOption,
 			metadata: {
 				description: "Make every entry a record with its status and composed frontmatter.",
@@ -453,7 +463,7 @@ function showCommand(layersFor) {
 		},
 		async run(args) {
 			const format = this.format;
-			if (!args.names.length) usage("name at least one reference.");
+			if (!args.names.length) usage$1("name at least one reference.");
 			try {
 				const home = homedir();
 				const layers = await layersFor(args, home);
@@ -488,14 +498,14 @@ function showCommand(layersFor) {
 				const answer = result(resolved.map((entry) => showEntry(entry, home, flags)), { render: bareArray });
 				return ok ? answer : answerThenFail(answer, format);
 			} catch (error) {
-				return fail(error, "Reference lookup failed.");
+				return fail$1(error, "Reference lookup failed.");
 			}
 		}
 	});
 }
-function listCommand(layersFor) {
+function listCommand$1(layersFor, name = "list") {
 	return command({
-		name: "list",
+		name,
 		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",
@@ -503,7 +513,7 @@ function listCommand(layersFor) {
 			type: t.string().optional()
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			trace: {
 				...traceOption,
 				description: "Add one row per name per layer holding it, with its outcome."
@@ -521,6 +531,7 @@ function listCommand(layersFor) {
 					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",
@@ -533,7 +544,7 @@ function listCommand(layersFor) {
 				if (listing.warnings.length) report.warnings = listing.warnings;
 				return result(report);
 			} catch (error) {
-				return fail(error, "Reference listing failed.");
+				return fail$1(error, "Reference listing failed.");
 			}
 		}
 	});
@@ -548,7 +559,7 @@ function searchCommand(layersFor) {
 			type: t.string()
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			trace: {
 				...traceOption,
 				description: "Add the tier and plugin or skill of each match."
@@ -556,7 +567,7 @@ function searchCommand(layersFor) {
 		},
 		async run(args) {
 			const query = args.query.trim();
-			if (!query) usage("search needs a query.");
+			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) });
@@ -579,14 +590,14 @@ function searchCommand(layersFor) {
 				});
 				return result(report);
 			} catch (error) {
-				return fail(error, "Reference search failed.");
+				return fail$1(error, "Reference search failed.");
 			}
 		}
 	});
 }
-function whereCommand(layersFor) {
+function whereCommand(layersFor, assets = false, name = "where") {
 	return command({
-		name: "where",
+		name,
 		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",
@@ -594,7 +605,7 @@ function whereCommand(layersFor) {
 			type: t.string()
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			default: defaultOption,
 			trace: {
 				...traceOption,
@@ -608,7 +619,8 @@ function whereCommand(layersFor) {
 				const display = (path) => collapseHome(home, path);
 				const report = whereReference(args.name, await layersFor(args, home), {
 					root: resolve(args.root ?? process.cwd()),
-					display
+					display,
+					assets
 				});
 				const output = compact({
 					name: report.name,
@@ -627,7 +639,7 @@ function whereCommand(layersFor) {
 				process.stderr.write(`error: reference-invalid: ${parseReferenceName(args.name).invalid}\n`);
 				return answerThenFail(answer, format);
 			} catch (error) {
-				return fail(error, "Reference placement lookup failed.");
+				return fail$1(error, "Reference placement lookup failed.");
 			}
 		}
 	});
@@ -635,7 +647,7 @@ function whereCommand(layersFor) {
 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(`--accept is a comma-separated list of versions, such as 1,2; got "${value}".`);
+	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);
 }
 function implementationsCommand(layersFor) {
@@ -648,7 +660,7 @@ function implementationsCommand(layersFor) {
 			type: t.string()
 		}],
 		options: {
-			root: rootOption,
+			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()
@@ -688,7 +700,7 @@ function implementationsCommand(layersFor) {
 				}));
 				return result(report);
 			} catch (error) {
-				return fail(error, "Implementation lookup failed.");
+				return fail$1(error, "Implementation lookup failed.");
 			}
 		}
 	});
@@ -703,7 +715,7 @@ function checkCommand(layersFor) {
 			type: t.array(t.string()).optional()
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			trace: {
 				...traceOption,
 				description: "Add every entry checked, with its kind and unsupported sections."
@@ -743,7 +755,7 @@ function checkCommand(layersFor) {
 				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(error, "Reference check failed.");
+				return fail$1(error, "Reference check failed.");
 			}
 		}
 	});
@@ -756,7 +768,7 @@ const pluginOption = {
 	description: "A plugin's source folder in this repository: acts on its `references/<name>.md`.",
 	type: t.string().optional()
 };
-const skillOption = {
+const skillOption$1 = {
 	description: "A skill's source folder in this repository: acts on its `references/<name>.default.md`.",
 	type: t.string().optional()
 };
@@ -770,10 +782,10 @@ function createCommand(layersFor) {
 			type: t.string()
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			scope: scopeOption,
 			plugin: pluginOption,
-			default: skillOption,
+			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()
@@ -828,12 +840,12 @@ function createCommand(layersFor) {
 				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(error, "Reference creation failed.");
+				return fail$1(error, "Reference creation failed.");
 			}
 		}
 	});
 }
-function selectCommand(layersFor) {
+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.",
@@ -847,7 +859,7 @@ function selectCommand(layersFor) {
 			type: t.array(t.string()).optional()
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			scope: scopeOption,
 			clear: {
 				description: "Remove the selection; a file left with nothing in it is deleted.",
@@ -881,7 +893,7 @@ function selectCommand(layersFor) {
 				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(error, "Reference selection failed.");
+				return fail$1(error, "Reference selection failed.");
 			}
 		}
 	});
@@ -898,7 +910,7 @@ function deleteReport(deleted, home) {
 		options: deleted.after.options
 	});
 }
-function deleteCommand(layersFor) {
+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.",
@@ -908,13 +920,13 @@ function deleteCommand(layersFor) {
 			type: t.string()
 		}],
 		options: {
-			root: rootOption,
+			root: rootOption$1,
 			scope: {
 				...scopeOption,
 				description: "Tier to delete from: project (default) or user."
 			},
 			plugin: pluginOption,
-			default: skillOption,
+			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()
@@ -942,7 +954,7 @@ function deleteCommand(layersFor) {
 				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(error, "Reference deletion failed.");
+				return fail$1(error, "Reference deletion failed.");
 			}
 		}
 	});
@@ -951,13 +963,13 @@ function deleteCommand(layersFor) {
 function createReferenceCommands({ plugin } = {}) {
 	const layersFor = layerSource(plugin);
 	return {
-		show: showCommand(layersFor),
-		list: listCommand(layersFor),
+		show: showCommand$1(layersFor),
+		list: listCommand$1(layersFor),
 		search: searchCommand(layersFor),
 		where: whereCommand(layersFor),
 		create: createCommand(layersFor),
-		select: selectCommand(layersFor),
-		delete: deleteCommand(layersFor),
+		select: selectCommand$1(layersFor),
+		delete: deleteCommand$1(layersFor),
 		check: checkCommand(layersFor),
 		implementations: implementationsCommand(layersFor)
 	};
@@ -980,5 +992,414 @@ function createReferenceCommand(options = {}) {
 		]
 	});
 }
+/**
+* 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");
+}
+/** An asset path: relative, `/`-separated, with no `..` or empty part. */
+function assetFile(dir, path) {
+	const parts = path.split("/");
+	if (!path || path.includes("\\") || path.startsWith("/") || parts.some((part) => part === "" || part === "." || part === "..")) throw new AssetError("path-invalid", `"${path}" is not an asset path. Use a relative path inside assets/, with "/" separators and no "..".`, true);
+	return join(dir, ...parts);
+}
+/** True when the real location of an existing file or its nearest existing parent stays inside the folder. */
+function contained(dir, file) {
+	if (!existsSync(dir)) return true;
+	const base = realpathSync(dir);
+	let probe = file;
+	while (!existsSync(probe)) probe = dirname(probe);
+	const real = realpathSync(probe);
+	return real === base || real.startsWith(base + sep);
+}
+function guard(dir, file, path) {
+	if (!contained(dir, file)) throw new AssetError("path-invalid", `"${path}" leaves the assets/ folder through a link.`, true);
+}
+function listAssets(skill, root) {
+	const dir = assetsDir(skill, root, false);
+	const entries = [];
+	const walk = (folder, prefix) => {
+		let items;
+		try {
+			items = readdirSync(folder, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const item of items) {
+			const full = join(folder, item.name);
+			const stat = lstatSync(full);
+			if (stat.isSymbolicLink()) continue;
+			if (stat.isDirectory()) walk(full, `${prefix}${item.name}/`);
+			else if (stat.isFile()) entries.push({
+				path: `${prefix}${item.name}`,
+				bytes: stat.size
+			});
+		}
+	};
+	walk(dir, "");
+	return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
+function showAsset(skill, root, path) {
+	const dir = assetsDir(skill, root, false);
+	const file = assetFile(dir, path);
+	guard(dir, file, path);
+	if (!existsSync(file) || !lstatSync(file).isFile()) throw new AssetError("no-file", `${path} does not exist in assets/.`);
+	const bytes = readFileSync(file);
+	if (bytes.includes(0)) throw new AssetError("binary", `${path} is binary (${bytes.length} bytes); point to it by path instead of showing it.`);
+	return bytes.toString("utf8");
+}
+function writeAsset(mode, skill, root, path, content) {
+	const dir = assetsDir(skill, root, true);
+	const file = assetFile(dir, path);
+	guard(dir, file, path);
+	const exists = existsSync(file);
+	if (mode === "create" && exists) throw new AssetError("exists", `${path} already exists in assets/; use update to replace it.`);
+	if (mode === "update" && !exists) throw new AssetError("no-file", `${path} does not exist in assets/; use create to add it.`);
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, content);
+	return file;
+}
+function deleteAsset(skill, root, path) {
+	const dir = assetsDir(skill, root, true);
+	const file = assetFile(dir, path);
+	guard(dir, file, path);
+	if (!existsSync(file) || !lstatSync(file).isFile()) throw new AssetError("no-file", `${path} does not exist in assets/.`);
+	rmSync(file);
+	for (let folder = dirname(file); folder !== dir && folder.startsWith(dir + sep); folder = dirname(folder)) try {
+		rmdirSync(folder);
+	} catch {
+		break;
+	}
+	return file;
+}
+//#endregion
+//#region src/assets/copy-asset.ts
+/**
+* Creates `<name>.<ext>` in the project or user `assets/` folder as a copy of the file another tier or
+* plugin holds, so it can be edited as an override. The managed tier is never a source: it is policy an
+* administrator keeps out of repositories and home folders, and a copy would show stale text as if it
+* were in effect (the managed file would still win).
+*/
+function copyAsset(layers, args) {
+	const name = parseReferenceName(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 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 (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 });
+	copyFileSync(source.path, path);
+	return {
+		path,
+		source: source.path,
+		from: args.copy
+	};
+}
+//#endregion
+//#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;
+	return [...found.filter(({ tier, file }) => tier === "plugin" && file).map(({ plugin }) => plugin), ...found.some(({ tier, file }) => tier === "default" && file) ? ["default"] : []];
+}
+/**
+* Writes `<name>.select` in the project or user `assets/` folder: one line, the plugin or `default` that
+* answers the name. Nothing else is in the file, and nothing extends or merges.
+*/
+function selectAsset(layers, args) {
+	const name = parseReferenceName(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`);
+	if (args.clear) {
+		if (!existsSync(path)) throw new AssetError("no-file", `${path} does not exist, so there is no selection to clear.`);
+		rmSync(path);
+	} else {
+		const held = options(layers, name.name);
+		if (!args.option || !held.includes(args.option)) throw new AssetError("option-invalid", `"${args.option ?? ""}" cannot be selected for "${name.name}". Options: ${held.join(", ") || "none, no plugin or default holds it"}.`, !args.option);
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, `${args.option}\n`);
+	}
+	const result = {
+		path,
+		cleared: Boolean(args.clear),
+		after: resolveReference(name.name, layers, { without: args.clear ? path : void 0 })
+	};
+	return args.clear ? result : {
+		...result,
+		selected: args.option
+	};
+}
+//#endregion
+//#region src/assets/asset.command.ts
+const skillOption = {
+	description: "A skill's source folder in this repository: its `assets/` folder is acted on.",
+	type: t.string()
+};
+const rootOption = {
+	description: "The directory the repository is found from. Defaults to the current directory.",
+	type: t.string().optional()
+};
+function fail(error, fallback) {
+	if (isCliError(error)) throw error;
+	if (error instanceof AssetError) {
+		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);
+}
+function usage(message) {
+	process.stderr.write(`error: usage: ${message}\n`);
+	throw CliError.reported(exitCodes.usage);
+}
+const pathDescription = "Asset path inside `assets/`, such as `data/rules.json`.";
+function rootOf(args) {
+	return resolve(args.root ?? process.cwd());
+}
+function listCommand() {
+	return command({
+		name: "list",
+		description: "List every file in a skill's assets/ folder with its size.",
+		options: {
+			skill: skillOption,
+			root: rootOption
+		},
+		async run(args) {
+			try {
+				const entries = listAssets(args.skill, rootOf(args));
+				return result({ assets: entries.length ? entries : "0 assets — the skill holds none" });
+			} catch (error) {
+				return fail(error, "Asset listing failed.");
+			}
+		}
+	});
+}
+function showCommand() {
+	return command({
+		name: "show",
+		description: "Print a text asset as written.",
+		arguments: [{
+			name: "path",
+			description: pathDescription,
+			type: t.string()
+		}],
+		options: {
+			skill: skillOption,
+			root: rootOption
+		},
+		async run(args) {
+			try {
+				return document(showAsset(args.skill, rootOf(args), args.path));
+			} catch (error) {
+				return fail(error, "Asset read failed.");
+			}
+		}
+	});
+}
+function writeCommand(mode, host) {
+	const create = mode === "create";
+	return command({
+		name: mode,
+		description: create ? "Add a new asset: by path in a skill from --content or --from, or, with --copy, by name in the project or user assets folder as a copy of what a plugin, the default, or another tier holds (never the managed tier). Never overwrites a file." : "Replace an existing asset from --content or --from.",
+		arguments: [{
+			name: "path",
+			description: `${pathDescription} With --copy, the asset name.`,
+			type: t.string()
+		}],
+		options: {
+			skill: {
+				...skillOption,
+				type: t.string().optional()
+			},
+			root: rootOption,
+			content: {
+				description: "The text to write.",
+				type: t.string().optional()
+			},
+			from: {
+				description: "A local file whose bytes to write.",
+				type: t.string().optional()
+			},
+			...create ? {
+				default: {
+					description: "With --copy, the calling skill's folder: its `assets/<name>.<ext>` is the `default` source.",
+					type: t.string().optional()
+				},
+				copy: {
+					description: "Copy the asset of this source: a plugin's name, `default` (the skill's own file), `project`, or `user`. `managed` is refused.",
+					type: t.string().optional()
+				},
+				scope: {
+					description: "With --copy, where the copy goes: project (default), `.agents/assets/`, or user, `~/.agents/assets/`.",
+					type: t.string().optional()
+				}
+			} : {}
+		},
+		async run(args) {
+			try {
+				if (args.copy !== void 0) {
+					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({
+						root,
+						home,
+						platform: process.platform,
+						env: process.env,
+						plugin: host.plugin,
+						defaultSkill: args.default ?? args.skill,
+						folder: "assets"
+					}), {
+						root,
+						home,
+						name: args.path,
+						scope: args.scope ?? "project",
+						copy: args.copy
+					});
+					return document(`${done.path}\n\ncopied from ${done.from}. Edit it; it now answers over the plugin tier.\n`);
+				}
+				if (!args.skill) usage("pass --skill, or --copy to create an override by name.");
+				if (args.content === void 0 === (args.from === void 0)) usage("pass exactly one of --content and --from.");
+				const content = args.content ?? readFileSync(resolve(args.from), "utf8");
+				const file = writeAsset(mode, args.skill, rootOf(args), args.path, content);
+				return document(`${file}\n\n${create ? "created" : "updated"}.\n`);
+			} catch (error) {
+				return fail(error, `Asset ${mode} failed.`);
+			}
+		}
+	});
+}
+function deleteCommand() {
+	return command({
+		name: "delete",
+		description: "Delete an asset from a skill's source folder, and any folder it leaves empty.",
+		arguments: [{
+			name: "path",
+			description: pathDescription,
+			type: t.string()
+		}],
+		options: {
+			skill: skillOption,
+			root: rootOption
+		},
+		async run(args) {
+			try {
+				return document(`${deleteAsset(args.skill, rootOf(args), args.path)}\n\ndeleted.\n`);
+			} catch (error) {
+				return fail(error, "Asset deletion failed.");
+			}
+		}
+	});
+}
+function selectCommand(options) {
+	return command({
+		name: "select",
+		description: "Choose which plugin, or the skill itself, answers an asset name that several hold, by writing `<name>.select` in the project or user assets folder.",
+		arguments: [{
+			name: "name",
+			description: "Asset name, without its extension.",
+			type: t.string()
+		}, {
+			name: "option",
+			description: "A plugin name, or `default` for the skill's own file. Not used with --clear.",
+			type: t.string().optional()
+		}],
+		options: {
+			root: rootOption,
+			default: {
+				description: "The calling skill's folder: its `assets/<name>.<ext>` is the `default` option.",
+				type: t.string().optional()
+			},
+			scope: {
+				description: "Where to write: project (default), `.agents/assets/`, or user, `~/.agents/assets/`.",
+				type: t.string().optional()
+			},
+			clear: {
+				description: "Remove the selection.",
+				type: t.boolean().optional()
+			}
+		},
+		async run(args) {
+			try {
+				const home = homedir();
+				const root = resolve(args.root ?? process.cwd());
+				const done = selectAsset(await referenceLayers({
+					root,
+					home,
+					platform: process.platform,
+					env: process.env,
+					plugin: options.plugin,
+					defaultSkill: args.default,
+					folder: "assets"
+				}), {
+					...args,
+					root,
+					home
+				});
+				const answer = done.after.status === "found" ? `${args.name} now answers from ${done.after.trace.stack.join(", ") || "a tier"}.` : `${args.name} is ${done.after.status}: ${done.after.message ?? ""}`;
+				return document(`${done.path}\n\n${done.cleared ? "selection cleared" : `selected ${done.selected}`}. ${answer}\n`);
+			} catch (error) {
+				return fail(error, "Asset selection failed.");
+			}
+		}
+	});
+}
+function createAssetCommand(options = {}) {
+	const { load, names, where } = createAssetResolveCommands(options);
+	return command({
+		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(),
+			showCommand(),
+			writeCommand("create", options),
+			writeCommand("update", options),
+			deleteCommand(),
+			load,
+			names,
+			where,
+			selectCommand(options)
+		]
+	});
+}
 //#endregion
-export { createReferenceCommand, createReferenceCommands };
+export { createAssetCommand, createReferenceCommand, createReferenceCommands };