@duyquangnvx/create-agent-cli 0.13.0 → 0.14.0

package/dist/bin.js

@@ -5803,6 +5803,15 @@ function errnoOf(error) {
 function isMissingFile(error) {
 	return errnoOf(error) === "ENOENT";
 }
+/** What `pending` resolves with, or undefined when it fails because a file is missing. */
+async function orMissing(pending) {
+	try {
+		return await pending;
+	} catch (error) {
+		if (isMissingFile(error)) return void 0;
+		throw error;
+	}
+}
 function isNothingThere(error) {
 	return isMissingFile(error) || errnoOf(error) === "ENOTDIR";
 }
@@ -6142,8 +6151,8 @@ const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
 function quoted$1(token) {
 	return SHELL_SAFE.test(token) ? token : `'${token.replaceAll("'", `'\\''`)}'`;
 }
-function pasteable(cliName, tokens, stdinArg) {
-	const line = [cliName, ...tokens].map(quoted$1).join(" ");
+function pasteable(runAs, tokens, stdinArg) {
+	const line = [runAs, ...tokens.map(quoted$1)].join(" ");
 	return stdinArg === void 0 ? line : `${line} < <${stdinArg} file>`;
 }
 function split(argv) {
@@ -6173,10 +6182,10 @@ function without(flag, takes, tokens) {
 * The caller's command line as typed, ready to paste, with each flag in `remove` dropped along with
 * its value, the words in `add` placed before any `--`, and the stdin arg's file redirected in.
 */
-function commandLineOf({ cliName, argv, flags, stdinArg }, { add = [], remove = [] } = {}) {
+function commandLineOf({ runAs, argv, flags, stdinArg }, { add = [], remove = [] } = {}) {
 	const { options, operands } = split(argv);
 	const takes = new Map(flags.map((known) => [known.flag, known.takes]));
-	return pasteable(cliName, [
+	return pasteable(runAs, [
 		...remove.reduce((tokens, flag) => without(flag, takes.get(flag) ?? "nothing", tokens), options),
 		...add,
 		...operands
@@ -6189,9 +6198,9 @@ function renamed(token, renames) {
 	return value.length === 0 ? name : `${name}=${value.join("=")}`;
 }
 /** The caller's command line, ready to paste, with each flag in `renames` typed as its new name. */
-function commandLineRenaming({ cliName, argv, stdinArg }, renames) {
+function commandLineRenaming({ runAs, argv, stdinArg }, renames) {
 	const { options, operands } = split(argv);
-	return pasteable(cliName, [...options.map((token) => renamed(token, renames)), ...operands], stdinArg);
+	return pasteable(runAs, [...options.map((token) => renamed(token, renames)), ...operands], stdinArg);
 }
 //#endregion
 //#region ../agent-cli/dist/usage.js
@@ -6478,13 +6487,22 @@ function isCommand(node) {
 	return typeof node.effect === "string";
 }
 //#endregion
+//#region ../agent-cli/dist/run-as.js
+/**
+* The Run-as: how every command line the Runtime gives its caller starts. A Dependency install runs
+* the copy the project pins, so it is `npx -q --no-install <bin>`; otherwise the bare name (ADR 0011).
+*/
+function runAsOf(cli) {
+	return cli.install?.mode === "dependency" ? `npx -q --no-install ${cli.name}` : cli.name;
+}
+//#endregion
 //#region ../agent-cli/dist/project.js
 const PROJECT_INVALID = "PROJECT_INVALID";
-function invalid(path, problem, options) {
+function invalid(path, problem, callerLine, options) {
 	return new CliError({
 		code: PROJECT_INVALID,
 		message: `the Project file ${path} is invalid: ${problem}`,
-		hint: `fix ${path}, then run the command again`
+		hint: `fix ${path}, then run \`${callerLine}\` again`
 	}, options);
 }
 function readText(path, fileError) {
@@ -6498,30 +6516,30 @@ function readText(path, fileError) {
 		});
 	}
 }
-function parsed(path, text, schema) {
+function parsed(path, text, schema, callerLine) {
 	let json;
 	try {
 		json = JSON.parse(text);
 	} catch (error) {
-		throw invalid(path, messageOf(error), { cause: error });
+		throw invalid(path, messageOf(error), callerLine, { cause: error });
 	}
 	const result = schema.safeParse(json);
-	if (!result.success) throw invalid(path, prettifyError(result.error));
+	if (!result.success) throw invalid(path, prettifyError(result.error), callerLine);
 	return result.data;
 }
-function projectFrom(projectFile, folder, fileError) {
+function projectFrom(projectFile, folder, scope) {
 	const path = join(folder, projectFile.file);
-	const text = readText(path, fileError);
+	const text = readText(path, scope.fileError);
 	if (text !== void 0) return {
 		root: folder,
-		settings: parsed(path, text, projectFile.schema)
+		settings: parsed(path, text, projectFile.schema, scope.callerLine)
 	};
 	const parent = dirname(folder);
-	return parent === folder ? void 0 : projectFrom(projectFile, parent, fileError);
+	return parent === folder ? void 0 : projectFrom(projectFile, parent, scope);
 }
 /** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
-function projectOf(projectFile, cwd, fileError) {
-	return projectFrom(projectFile, resolve(cwd), fileError);
+function projectOf(projectFile, cwd, scope) {
+	return projectFrom(projectFile, resolve(cwd), scope);
 }
 //#endregion
 //#region ../agent-cli/dist/tools.js
@@ -6554,7 +6572,7 @@ async function findTool(name, env) {
 	for (const file of candidates) if (await isExecutable(file)) return file;
 }
 /** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
-async function checkTools(tools, env) {
+async function checkTools(tools, env, callerLine) {
 	const found = await Promise.all(tools.map((tool) => findTool(tool.name, env)));
 	const missing = tools.filter((_tool, index) => found[index] === void 0);
 	if (missing.length === 0) return;
@@ -6562,7 +6580,7 @@ async function checkTools(tools, env) {
 	throw new CliError({
 		code: TOOL_MISSING,
 		message: `${missing.length === 1 ? "a tool it runs is" : "tools it runs are"} not on PATH: ${names}`,
-		hint: `install ${missing.length === 1 ? "it" : "them"}, then run the same command again: ${missing.map(({ install }) => install).join("; ")}`
+		hint: `install ${missing.map(({ name, install }) => `${name} (\`${install}\`)`).join(", ")}, then run \`${callerLine}\` again`
 	});
 }
 function toolsIn(node) {
@@ -6717,11 +6735,7 @@ async function feed(stdin, input, signal) {
 */
 async function spawnChild(command, args, { cwd, env, signal, onLine, stdin, detached = false }) {
 	signal.throwIfAborted();
-	const launch = process.platform === "win32" ? await windowsLaunch(command, args, env) : {
-		command,
-		args,
-		shell: false
-	};
+	const launch = await launchOf(command, args, env);
 	signal.throwIfAborted();
 	return new Promise((resolve, reject) => {
 		const child = spawn(launch.command, launch.args, {
@@ -6786,6 +6800,38 @@ async function spawnChild(command, args, { cwd, env, signal, onLine, stdin, deta
 		});
 	});
 }
+async function launchOf(command, args, env) {
+	return process.platform === "win32" ? windowsLaunch(command, args, env) : {
+		command,
+		args,
+		shell: false
+	};
+}
+/**
+* Starts a child in its own process group (its own console on Windows) with no stdio, and settles
+* once it has started; the parent neither waits for it nor keeps it from exiting.
+*/
+const realSpawnDetached = async (command, args, { cwd, env }) => {
+	const launch = await launchOf(command, args, env);
+	return new Promise((resolve, reject) => {
+		const child = spawn(launch.command, launch.args, {
+			cwd,
+			env,
+			shell: launch.shell,
+			windowsHide: true,
+			stdio: "ignore",
+			detached: true
+		});
+		child.unref();
+		child.once("error", reject);
+		child.once("spawn", () => {
+			child.off("error", reject);
+			const { pid } = child;
+			if (pid === void 0) reject(/* @__PURE__ */ new Error(`${command} started without a pid`));
+			else resolve({ pid });
+		});
+	});
+};
 const realSpawn = (command, args, options) => spawnChild(command, args, options);
 function failedError(command, { exitCode, stderr }) {
 	const tail = lastLines(stderr, STDERR_TAIL_LINES$1);
@@ -6795,15 +6841,15 @@ function failedError(command, { exitCode, stderr }) {
 		hint: `the output of ${command} above says why it failed`
 	});
 }
-function missingError(command, cause) {
+function missingError(command, callerLine, cause) {
 	return new CliError({
 		code: TOOL_MISSING,
 		message: `${command} could not be started: it is not on PATH`,
-		hint: `install ${command}, then run the same command again`
+		hint: `install ${command}, then run \`${callerLine}\` again`
 	}, { cause });
 }
-function startError(command, error, fileError) {
-	if (isMissingFile(error)) return missingError(command, error);
+function startError(command, error, { fileError, callerLine }) {
+	if (isMissingFile(error)) return missingError(command, callerLine, error);
 	return fileError(error, {
 		path: command,
 		access: "read"
@@ -6833,8 +6879,7 @@ function reportingLines(onLine, onError) {
 		}
 	};
 }
-/** `ctx.spawn`: `spawn` bound to the run, its start failures classified by errno. */
-function contextSpawn(run, defaults, fileError) {
+function contextSpawn(run, defaults, scope) {
 	return async (command, args = [], options = {}) => {
 		let callerFailure;
 		const caller = (error) => {
@@ -6850,12 +6895,26 @@ function contextSpawn(run, defaults, fileError) {
 				stdin: reporting(options.stdin, caller)
 			});
 		} catch (error) {
-			throw callerFailure?.error === error ? error : startError(command, error, fileError);
+			throw callerFailure?.error === error ? error : startError(command, error, scope);
 		}
 		if (options.check === true && result.exitCode !== 0) throw failedError(command, result);
 		return result;
 	};
 }
+/** `ctx.spawnDetached`: `run` bound to the run's cwd and env, its start failures classified by errno. */
+function contextSpawnDetached(run, defaults, scope) {
+	return async (command, args = [], options = {}) => {
+		defaults.signal.throwIfAborted();
+		try {
+			return await run(command, args, {
+				cwd: options.cwd ?? defaults.cwd,
+				env: options.env ?? defaults.env
+			});
+		} catch (error) {
+			throw startError(command, error, scope);
+		}
+	};
+}
 //#endregion
 //#region ../agent-cli/dist/built-ins/semver.js
 const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
@@ -6927,6 +6986,7 @@ const NO_LATEST = "NO_LATEST";
 function npmContext(cli, registry, ctx, node, cwd) {
 	return {
 		cliName: cli.name,
+		callerLine: ctx.commandLine(),
 		registry,
 		cwd,
 		env: ctx.env,
@@ -6966,8 +7026,8 @@ function globalRegistry(install) {
 		package: name,
 		label: registry,
 		flags: registryFlags(install),
-		unreachableHint: "check the network or VPN, then run it again",
-		loginHint: `log in to ${registry} (npm login --registry=${registry}) or set its token in ~/.npmrc, then run it again`,
+		unreachableHint: "check the network or VPN",
+		loginHint: `log in to ${registry} (\`npm login --registry=${registry}\`) or set its token in ~/.npmrc`,
 		missingHint: `check that ${name} is published on ${registry}`
 	};
 }
@@ -7021,26 +7081,27 @@ function failureOf(call, answer, ctx) {
 	const { label: registry, package: name, loginHint, unreachableHint } = ctx.registry;
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
+	const rerun = `run \`${ctx.callerLine}\` again`;
 	if (code !== void 0 && NETWORK_CODES.has(code)) return new CliError({
 		code: REGISTRY_UNREACHABLE,
 		message: `npm could not reach ${registry} (${code})${output}`,
-		hint: unreachableHint
+		hint: `${unreachableHint}, then ${rerun}`
 	});
 	if (code !== void 0 && AUTH_CODES.has(code)) return new CliError({
 		code: REGISTRY_AUTH,
 		message: `${registry} refused npm's credentials (${code})${output}`,
-		hint: loginHint
+		hint: `${loginHint}, then ${rerun}`
 	});
 	if (call === "view" && code === "E404") return noLatest(ctx, `npm found no ${name}@latest on ${registry}: no version of it is published there`);
 	if (call === "install") return new CliError({
 		code: INSTALL_FAILED,
 		message: `npm could not install ${name}${code === void 0 ? "" : ` (${code})`}${output}`,
-		hint: `fix what npm reports, then run it again, or install it yourself: ${installCommandLine(ctx.registry)}`
+		hint: `fix what npm reports, then ${rerun}, or install it yourself: \`${installCommandLine(ctx.registry)}\``
 	});
 	return new CliError({
 		code: NPM_FAILED,
 		message: `npm ${call} failed with exit code ${answer.exitCode}${output}`,
-		hint: "fix what npm reports, then run it again"
+		hint: `fix what npm reports, then ${rerun}`
 	});
 }
 function noLatest(ctx, message) {
@@ -7176,17 +7237,19 @@ const LINES = {
 	pnpm: {
 		upgrade: (packages) => `pnpm up --latest ${packages.join(" ")}`,
 		add: (packages) => `pnpm add -D ${packages.join(" ")}`,
-		reinstall: "pnpm install",
-		exec: (cli) => `pnpm exec ${cli}`
+		install: "pnpm install"
 	},
 	npm: {
 		upgrade: (packages) => `npm install ${packages.map((name) => `${name}@latest`).join(" ")}`,
 		add: (packages) => `npm install -D ${packages.join(" ")}`,
-		reinstall: "npm install",
-		exec: (cli) => `npx ${cli}`
+		install: "npm install"
 	}
 };
-const manifestSchema$1 = object({ packageManager: string().optional() });
+const manifestSchema$1 = object({
+	packageManager: string().optional(),
+	dependencies: record(string(), unknown()).optional(),
+	devDependencies: record(string(), unknown()).optional()
+});
 const packageSchema = object({ version: string() });
 /** `dir` and every folder above it, nearest first. */
 function ancestorsOf(dir) {
@@ -7202,7 +7265,7 @@ async function exists(path) {
 		throw error;
 	}
 }
-async function declaredManager(dir) {
+async function manifestIn(dir) {
 	let text;
 	try {
 		text = await readFile(join(dir, "package.json"), "utf8");
@@ -7216,15 +7279,30 @@ async function declaredManager(dir) {
 	} catch {
 		return;
 	}
-	const name = manifestSchema$1.safeParse(manifest).data?.packageManager?.split("@")[0];
+	return manifestSchema$1.safeParse(manifest).data;
+}
+async function declaredManager(dir) {
+	const name = (await manifestIn(dir))?.packageManager?.split("@")[0];
 	return MANAGERS.find((manager) => manager === name);
 }
+async function manifestListing(name, cwd, root) {
+	const dirs = ancestorsOf(cwd);
+	const top = root === void 0 ? dirs.length : dirs.indexOf(root.dir) + 1;
+	for (const dir of dirs.slice(0, top)) {
+		const manifest = await manifestIn(dir);
+		if (manifest?.dependencies?.[name] !== void 0 || manifest?.devDependencies?.[name] !== void 0) return join(dir, "package.json");
+	}
+}
 async function lockfileRootOf(cwd) {
 	for (const dir of ancestorsOf(cwd)) for (const [file, kind] of LOCKFILES) if (await exists(join(dir, file))) return {
 		dir,
 		manager: await declaredManager(dir) ?? kind
 	};
 }
+/** The package manager's project root: the folder of the nearest lockfile, or `cwd` without one. */
+async function projectRootOf(cwd) {
+	return (await lockfileRootOf(cwd))?.dir ?? cwd;
+}
 async function versionIn(manifest) {
 	try {
 		return packageSchema.parse(JSON.parse(await readFile(manifest, "utf8"))).version;
@@ -7233,7 +7311,7 @@ async function versionIn(manifest) {
 		throw error;
 	}
 }
-async function standingOf(install, bin, cwd) {
+async function standingOf(install, bin, cwd, root) {
 	if (bin === void 0) return { kind: "source" };
 	for (const projectDir of ancestorsOf(cwd)) {
 		const folder = join(projectDir, "node_modules", install.package);
@@ -7267,14 +7345,18 @@ async function standingOf(install, bin, cwd) {
 			runningFrom
 		};
 	}
-	return { kind: "missing" };
+	const manifest = await manifestListing(install.package, cwd, root);
+	return manifest === void 0 ? { kind: "missing" } : {
+		kind: "listed",
+		manifest
+	};
 }
 async function surveyDependency(install, bin, cwd) {
-	const [root, standing] = await Promise.all([lockfileRootOf(cwd), standingOf(install, bin, cwd)]);
+	const root = await lockfileRootOf(cwd);
 	return {
 		cwd,
 		root,
-		standing
+		standing: await standingOf(install, bin, cwd, root)
 	};
 }
 function packagesOf(install) {
@@ -7289,6 +7371,10 @@ function skippedFor(cli, install, standing) {
 		message: standing.kind === "source" ? `not checked: ${cli.name} runs from source, not from an install` : `not checked: ${install.package} links to ${standing.copy.realDir}, so the workspace decides its version`
 	};
 }
+function searchedFrom(cwd, root) {
+	if (root === void 0) return `at or above ${cwd}`;
+	return root.dir === cwd ? `at ${cwd}` : `from ${cwd} up to ${root.dir}`;
+}
 function problem(message, fix) {
 	return fix === void 0 ? {
 		state: "problem",
@@ -7305,11 +7391,12 @@ function dependencyInstallFinding(cli, install, { cwd, root, standing }) {
 	switch (standing.kind) {
 		case "source":
 		case "linked": return skippedFor(cli, install, standing);
-		case "missing": return problem(`no package at or above ${cwd} depends on ${install.package}`, lines?.add(packagesOf(install)));
-		case "unreadable": return problem(`${standing.manifest} is not a package.json with a version: ${standing.reason}`, lines?.reinstall);
+		case "missing": return problem(`no package ${searchedFrom(cwd, root)} depends on ${install.package}`, lines?.add(packagesOf(install)));
+		case "listed": return problem(`${standing.manifest} lists ${install.package}, but no copy of it is installed at or above ${cwd}`, lines?.install);
+		case "unreadable": return problem(`${standing.manifest} is not a package.json with a version: ${standing.reason}`, lines?.install);
 		case "other": {
 			const { copy, runningFrom } = standing;
-			return problem(`${cli.name} runs from ${runningFrom}, not from this project's ${install.package} ${copy.version} at ${copy.realDir}`, lines?.exec(cli.name));
+			return problem(`${cli.name} runs from ${runningFrom}, not from this project's ${install.package} ${copy.version} at ${copy.realDir}`, `${runAsOf(cli)} doctor`);
 		}
 		case "installed": {
 			const { copy } = standing;
@@ -7328,8 +7415,8 @@ function registryOf({ package: name }, root) {
 		package: name,
 		label: `the registry npm uses for ${name}`,
 		flags: [],
-		unreachableHint: scope === void 0 ? "check the network or VPN, then run it again" : `check the network or VPN and the ${scope}:registry that ${npmrc} sets, then run it again`,
-		loginHint: `log in to it (npm login${scope === void 0 ? "" : ` --scope=${scope}`}) or set its token in ${npmrc}, then run it again`,
+		unreachableHint: scope === void 0 ? "check the network or VPN" : `check the network or VPN and the ${scope}:registry that ${npmrc} sets`,
+		loginHint: `log in to it (\`npm login${scope === void 0 ? "" : ` --scope=${scope}`}\`) or set its token in ${npmrc}`,
 		missingHint: scope === void 0 ? `check that ${name} is published on the registry ${npmrc} names` : `check that ${name} is published, and that ${npmrc} maps ${scope} to its registry: ${scope}:registry=<url>`
 	};
 }
@@ -7408,9 +7495,93 @@ function fixFor(cliName, copies, source) {
 }
 async function skillReport(cli, version, ctx) {
 	const copies = await skillCopies(cli.name, version, ctx);
+	const source = cli.skill !== void 0 && "source" in cli.skill ? cli.skill.source : void 0;
 	return {
 		copies,
-		fix: fixFor(cli.name, copies, cli.skill?.source)
+		fix: fixFor(cli.name, copies, source)
+	};
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/packaged-skill.js
+/** The folder, relative to the package root, of a CLI's Packaged skill, if it declares one. */
+function packagedFolderOf(cli) {
+	return cli.skill !== void 0 && "packaged" in cli.skill ? cli.skill.packaged : void 0;
+}
+/** The project root and the Skill copy under it, as `skill install` writes it. */
+async function skillCopyOf(cli, cwd) {
+	const root = await projectRootOf(cwd);
+	return {
+		root,
+		copy: join(root, ".claude", "skills", cli.name)
+	};
+}
+/** Every file under `dir`, relative to it and sorted; none when `dir` is missing. */
+async function filesIn(dir) {
+	return (await orMissing(readdir(dir, {
+		recursive: true,
+		withFileTypes: true
+	})) ?? []).filter((entry) => entry.isFile()).map((entry) => relative(dir, join(entry.parentPath, entry.name))).sort();
+}
+/** The versions of the package's skill in `source` and of its copy in `copy`. */
+async function skillVersionsOf(source, copy) {
+	const [shipped, installed] = await Promise.all([readFile(join(source, "SKILL.md"), "utf8"), orMissing(readFile(join(copy, "SKILL.md"), "utf8"))]);
+	const packageVersion = skillVersionIn(shipped) ?? null;
+	const copyVersion = installed === void 0 ? void 0 : skillVersionIn(installed) ?? null;
+	return {
+		packageVersion,
+		copyVersion,
+		same: copyVersion === packageVersion
+	};
+}
+async function personalCopyOf(name, copy, ctx) {
+	const home = join(homeOf(ctx.env), ".claude", "skills", name);
+	const real = await orMissing(realpath(home));
+	return real === void 0 || real === await orMissing(realpath(copy)) ? void 0 : home;
+}
+/** What the `skill` row of a Packaged skill carries under `--json` beside its message. */
+const packagedSkillDetailsSchema = object({
+	copy: string(),
+	copyVersion: string().nullable(),
+	packageVersion: string().nullable(),
+	/** A personal copy, which Claude Code prefers over the project's. */
+	home: string().optional()
+});
+function versionLabel(version) {
+	return version ?? "(no metadata.version)";
+}
+function compared(name, { copy, copyVersion, packageVersion }, same) {
+	const stated = `${copy} ${versionLabel(copyVersion)}`;
+	return same ? `${stated}, the version ${name} ships` : `${stated} differs from the ${versionLabel(packageVersion)} that ${name} ships`;
+}
+/** The `skill` row of a Packaged skill: the project root's copy against the package's, and any under home. */
+async function packagedSkillFinding(cli, folder, ctx) {
+	const { copy } = await skillCopyOf(cli, ctx.cwd);
+	const versions = await skillVersionsOf(join(ctx.packageRoot, folder), copy);
+	const { packageVersion } = versions;
+	const copyVersion = versions.copyVersion ?? null;
+	const home = await personalCopyOf(cli.name, copy, ctx);
+	const skill = {
+		copy,
+		copyVersion,
+		packageVersion,
+		...home === void 0 ? {} : { home }
+	};
+	const head = versions.copyVersion === void 0 ? `no copy of the ${cli.name} skill at ${copy}` : compared(cli.name, skill, versions.same);
+	const message = home === void 0 ? head : `${head}; remove ${home}: Claude Code prefers a personal skill over the project's`;
+	if (!versions.same) return {
+		state: "problem",
+		message,
+		fix: `${runAsOf(cli)} skill install`,
+		skill
+	};
+	return home === void 0 ? {
+		state: "ok",
+		message,
+		skill
+	} : {
+		state: "problem",
+		message,
+		skill
 	};
 }
 //#endregion
@@ -7475,7 +7646,10 @@ function readProject(projectFile, ctx) {
 	try {
 		return {
 			ok: true,
-			project: projectOf(projectFile, ctx.cwd, ctx.fileError)
+			project: projectOf(projectFile, ctx.cwd, {
+				fileError: ctx.fileError,
+				callerLine: ctx.commandLine()
+			})
 		};
 	} catch (error) {
 		return {
@@ -7577,9 +7751,12 @@ function describeCopy({ path, version, state }) {
 	return `${path}${version === void 0 ? "" : ` ${version}`} (${SKILL_STATE_NOTES[state]})`;
 }
 function skillRow(cli) {
+	const packaged = packagedFolderOf(cli);
 	return {
 		name: "skill",
+		advisory: true,
 		run: async (ctx) => {
+			if (packaged !== void 0) return packagedSkillFinding(cli, packaged, ctx);
 			const { copies, fix } = await skillReport(cli, cli.version, ctx);
 			const message = copies.length === 0 ? `no copy of the ${cli.name} skill is installed` : copies.map(describeCopy).join("; ");
 			return fix === void 0 ? ok(message) : {
@@ -7620,7 +7797,8 @@ const reportSchema = object({
 		]),
 		message: string(),
 		fix: string().optional(),
-		code: string().optional()
+		code: string().optional(),
+		skill: packagedSkillDetailsSchema.optional()
 	})),
 	next: array(string())
 });
@@ -7676,11 +7854,11 @@ function render({ rows, next }, style) {
 		return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
 	}), ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
 }
-function failure(cliName, problems) {
+function failure(cliName, callerLine, problems) {
 	const errors = problems.map(({ check, message, fix, code }) => new CliError({
 		code: code ?? "DOCTOR_PROBLEMS",
 		message: `${cliName} doctor found a problem in ${check}: ${message}`,
-		hint: fix === void 0 ? "the row says what is wrong" : `run ${fix}, then run doctor again`
+		hint: fix === void 0 ? "the row says what is wrong" : `run \`${fix}\`, then run \`${callerLine}\` again`
 	}));
 	return new AggregateError(errors);
 }
@@ -7690,10 +7868,10 @@ function doctorCommand(cli, launch) {
 		name: "doctor",
 		description: "check the setup and say what fixes each problem",
 		examples: [{
-			command: `${cli.name} doctor`,
+			command: `${runAsOf(cli)} doctor`,
 			note: "check the setup and list the commands that fix it"
 		}, {
-			command: `${cli.name} doctor --json`,
+			command: `${runAsOf(cli)} doctor --json`,
 			note: "get the rows and fixes as data"
 		}],
 		effect: "read",
@@ -7713,7 +7891,7 @@ function doctorCommand(cli, launch) {
 			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
 			if (problems.length > 0) {
 				ctx.deliver(report);
-				throw failure(cli.name, problems);
+				throw failure(cli.name, ctx.commandLine(), problems);
 			}
 			return report;
 		},
@@ -7721,683 +7899,841 @@ function doctorCommand(cli, launch) {
 	});
 }
 //#endregion
-//#region ../agent-cli/dist/interrupts.js
-const INTERRUPTED = "INTERRUPTED";
-const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
-/** How long an interrupted Command may take to settle before the run ends without it. */
-const GRACE_MS = 3e3;
-const GRACE_OVER = Symbol("grace over");
-function interruptedError() {
-	return new CliError({
-		code: INTERRUPTED,
-		message: "interrupted before it finished",
-		hint: "run the command again"
-	});
+//#region ../agent-cli/dist/agent.js
+const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
+const isSet = (name) => (env) => (env[name] ?? "") !== "";
+const equals = (name, value) => (env) => env[name] === value;
+const MARKERS = [
+	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
+	equals("AGENT", "amp"),
+	isSet("CODEX_SANDBOX"),
+	isSet("CODEX_CI"),
+	isSet("CODEX_THREAD_ID"),
+	isSet("GEMINI_CLI"),
+	isSet("COPILOT_CLI"),
+	isSet("OPENCODE"),
+	isSet("ANTIGRAVITY_AGENT"),
+	isSet("AUGMENT_AGENT"),
+	isSet("REPL_ID"),
+	isSet("CLAUDE_CODE_IS_COWORK"),
+	isSet("CLAUDECODE"),
+	isSet("CLAUDE_CODE"),
+	isSet("CURSOR_TRACE_ID"),
+	isSet("CURSOR_AGENT"),
+	equals("CURSOR_EXTENSION_HOST_ROLE", "agent-exec"),
+	equals("TERM_PROGRAM", "kiro"),
+	(env) => ["/.pi/agent", "\\.pi\\agent"].some((dir) => (env.PATH ?? "").includes(dir)),
+	isSet("GOOSE_PROVIDER")
+];
+/**
+* Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
+* in a PTY, so a TTY alone doesn't mean a person is watching.
+*/
+function isAgent(env) {
+	return MARKERS.some((marker) => marker(env));
 }
-const WAIT_HINT = "run it again later, when the service it waits on may answer faster";
-function deadlineError(commandLine, ms, hint, bound = "deadline") {
-	return new CliError({
-		code: DEADLINE_EXCEEDED,
-		message: `${commandLine} ran past its ${ms} ms ${bound}`,
-		hint
-	});
+//#endregion
+//#region ../agent-cli/dist/errno.js
+const PERMISSION_DENIED = "PERMISSION_DENIED";
+const DISK_FULL = "DISK_FULL";
+const NOT_FOUND = "NOT_FOUND";
+const ALREADY_EXISTS = "ALREADY_EXISTS";
+const NOT_A_FILE = "NOT_A_FILE";
+function permissionHint({ path, access, callerLine, env, platform }) {
+	if (platform === "win32") return `a program may hold ${path} open: close it, then run \`${callerLine}\` again`;
+	if (!isAgent(env)) return `check the permissions of ${path} and its folder`;
+	return `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`;
 }
-/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
-var RunControl = class {
-	signal;
-	#controller = new AbortController();
-	#commandLine;
-	#outer;
-	#onOuterAbort = () => this.#controller.abort(interruptedError());
-	/** Each running must-finish step, tracked until it settles, with its name. */
-	#steps = /* @__PURE__ */ new Map();
-	#progress;
-	#clock;
-	#disposed = new AbortController();
-	/** The reasons this run's deadlines and timeouts aborted with, to tell them in a Command's error. */
-	#abortReasons = /* @__PURE__ */ new WeakSet();
-	#graceCancel = new AbortController();
-	#endGrace = () => {};
-	#graceOver = new Promise((resolve) => {
-		this.#endGrace = resolve;
+function fileErrorOf(scope) {
+	return (error, at) => classifyErrno(error, {
+		...at,
+		...scope
 	});
-	constructor({ commandLine, outer, clock, progress, runDeadline }) {
-		this.#commandLine = commandLine;
-		this.#outer = outer;
-		this.#clock = clock;
-		this.#progress = progress;
-		this.signal = this.#controller.signal;
-		this.signal.addEventListener("abort", () => this.#onStop(), { once: true });
-		if (outer?.aborted === true) this.#onOuterAbort();
-		else outer?.addEventListener("abort", this.#onOuterAbort, { once: true });
-		if (runDeadline !== void 0) {
-			const { ms, hint } = runDeadline;
-			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, hint())));
-		}
-	}
-	deadline(ms) {
-		return AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
+}
+function classifyErrno(error, context) {
+	const { path } = context;
+	switch (errnoOf(error)) {
+		case "EACCES":
+		case "EPERM":
+		case "EROFS":
+		case "EBUSY": return new CliError({
+			code: PERMISSION_DENIED,
+			message: `permission denied: ${path}`,
+			hint: permissionHint(context)
+		}, { cause: error });
+		case "ENOSPC":
+		case "EDQUOT": return new CliError({
+			code: DISK_FULL,
+			message: `no space left on the disk holding ${path}`,
+			hint: `free space on that disk, then run \`${context.callerLine}\` again`
+		}, { cause: error });
+		case "ENOENT":
+		case "ENOTDIR":
+		case "ENAMETOOLONG": return new CliError({
+			code: NOT_FOUND,
+			message: `not found: ${path}`,
+			hint: `check that ${path} and its folder exist`
+		}, { cause: error });
+		case "EEXIST": return new CliError({
+			code: ALREADY_EXISTS,
+			message: `already exists: ${path}`,
+			hint: `pass another path, or remove ${path}`
+		}, { cause: error });
+		case "EISDIR": return new CliError({
+			code: NOT_A_FILE,
+			message: `not a file: ${path} is a folder`,
+			hint: `pass the path of a file, not of the folder ${path}`
+		}, { cause: error });
+		default: return error;
 	}
-	timeout(ms) {
-		return this.#abortsAfter(ms, "timeout");
+}
+//#endregion
+//#region ../agent-cli/dist/files.js
+const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
+/** Where the Runtime writes `path` before moving it into place; a dead writer's is swept. */
+function tempPathOf(path) {
+	return join(dirname(path), `.${basename(path)}.agent-cli-${process.pid}.tmp`);
+}
+function isAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return errnoOf(error) === "EPERM";
 	}
-	#abortsAfter(ms, bound) {
-		const controller = new AbortController();
-		after(this.#clock, ms, this.#disposed.signal, () => {
-			const reason = deadlineError(this.#commandLine, ms, WAIT_HINT, bound);
-			this.#abortReasons.add(reason);
-			controller.abort(reason);
-		});
-		return controller.signal;
+}
+async function sweep(folder) {
+	const dead = (await readdir(folder)).filter((name) => {
+		const pid = TEMP_FILE.exec(name)?.[1];
+		return pid !== void 0 && !isAlive(Number(pid));
+	});
+	await Promise.all(dead.map((name) => rm(join(folder, name), { force: true })));
+}
+/** The file a symlink at `path` points to, so a replacing write keeps the link. */
+async function targetOf$1(path) {
+	try {
+		return await realpath(path);
+	} catch (error) {
+		if (isMissingFile(error)) return path;
+		throw error;
 	}
-	async runToEnd(name, work) {
-		this.#graceCancel.abort();
-		if (this.signal.aborted) this.#finishing(name);
-		const step = work();
-		const settled = step.then(() => {}, () => {});
-		this.#steps.set(settled, name);
-		try {
-			return await step;
-		} finally {
-			this.#steps.delete(settled);
-			this.#startGrace();
-		}
+}
+async function writeWithMode(path, data, mode) {
+	if (mode === void 0) {
+		await writeFile(path, data);
+		return;
 	}
-	/** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
-	async settle(work) {
-		try {
-			const value = await Promise.race([work, this.#graceOver]);
-			if (this.signal.aborted || value === GRACE_OVER) throw this.signal.reason;
-			return value;
-		} finally {
-			await this.#stepsDone();
-			this.close();
-		}
-	}
-	/**
-	* The error a run ends with: an interrupt or the run deadline outranks what the Command threw,
-	* unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
-	* Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's or timeout's
-	* abort is reported as that abort, so a declared error keeps its own code.
-	*/
-	errorAfter(error) {
-		if (this.signal.aborted) return error instanceof CliError && error.code === "INTERRUPTED" ? error : this.signal.reason;
-		const leaves = errorsOf(error).map((leaf) => this.#abortIn(leaf) ?? leaf);
-		return leaves.length === 1 ? leaves[0] : new AggregateError(leaves);
-	}
-	#abortIn(error) {
-		if (error instanceof CliError) return void 0;
-		return causesOf(error).find((each) => each instanceof CliError && this.#abortReasons.has(each));
-	}
-	#onStop() {
-		for (const name of this.#steps.values()) this.#finishing(name);
-		this.#startGrace();
-	}
-	#finishing(name) {
-		this.#progress(`finishing ${name}`);
-	}
-	#startGrace() {
-		if (this.signal.aborted && this.#steps.size === 0) {
-			this.#graceCancel.abort();
-			this.#graceCancel = new AbortController();
-			after(this.#clock, GRACE_MS, this.#graceCancel.signal, () => this.#endGrace(GRACE_OVER));
-		}
-	}
-	async #stepsDone() {
-		while (this.#steps.size > 0) await Promise.all(this.#steps.keys());
-	}
-	/** Stops the run's timers and its hold on the caller's signal, for a run that never settles. */
-	close() {
-		this.#graceCancel.abort();
-		this.#disposed.abort();
-		this.#outer?.removeEventListener("abort", this.#onOuterAbort);
-	}
-};
-//#endregion
-//#region ../agent-cli/dist/built-ins/upgrades.js
-/** A skipped release's Upgrade steps, or its whole section when it lists none. */
-const upgradeSchema = union([object({
-	version: string(),
-	steps: array(string())
-}), object({
-	version: string(),
-	notes: string()
-})]);
-const RELEASE_HEADING = /^## v?(\S+)/;
-const UPGRADE_HEADING = /^### Upgrade from v\S+$/;
-const HEADING = /^#{1,6} /;
-const ITEM = /^[-*] /;
-const NOTHING_TO_DO = /^nothing to do\.?$/i;
-function releasesIn(changelog) {
-	const releases = [];
-	let current;
-	for (const line of changelog.split(/\r?\n/)) {
-		const heading = RELEASE_HEADING.exec(line);
-		if (heading !== null) {
-			const version = heading[1] ?? "";
-			current = isVersion(version) ? {
-				version,
-				lines: []
-			} : void 0;
-			if (current !== void 0) releases.push(current);
-		} else current?.lines.push(line);
-	}
-	return releases;
-}
-function listedSteps(lines) {
-	const start = lines.findIndex((line) => UPGRADE_HEADING.test(line.trimEnd()));
-	if (start === -1) return [];
-	const end = lines.findIndex((line, i) => i > start && HEADING.test(line));
-	const body = lines.slice(start + 1, end === -1 ? void 0 : end).filter((line) => line.trim() !== "");
-	const starts = body.flatMap((line, i) => ITEM.test(line) ? [i] : []);
-	return starts.map((first, i) => body.slice(first, starts[i + 1]).map((line) => line.trim()).join(" ").replace(ITEM, ""));
+	await writeFile(path, data, { mode });
+	await chmod(path, mode);
 }
-function upgradeOf({ version, lines }) {
-	const listed = listedSteps(lines);
-	if (listed.length === 0) return [{
-		version,
-		notes: lines.join("\n").trim()
-	}];
-	const todo = listed.filter((step) => !NOTHING_TO_DO.test(step));
-	return todo.length === 0 ? [] : [{
-		version,
-		steps: todo
-	}];
+/** What `link` answers on a file system without hard links, such as exFAT. */
+const NO_HARD_LINKS = /* @__PURE__ */ new Set([
+	"EPERM",
+	"ENOTSUP",
+	"EXDEV"
+]);
+/** A link fails atomically when `path` is taken, so no reader ever sees half a file there. */
+async function linkNew(temp, path, data, mode) {
+	try {
+		await link(temp, path);
+	} catch (error) {
+		if (!NO_HARD_LINKS.has(errnoOf(error))) throw error;
+		await createNew(path, data, mode);
+	}
 }
-/**
-* What each release after `from` up to `to` asks of the operator, oldest first, from the
-* CHANGELOG.md in `packageDir`; none when the package ships no CHANGELOG.
-*/
-async function upgradesOf(packageDir, from, to) {
-	let changelog;
+/** A file this call created and could not finish is removed, so a rerun does not find half of it. */
+async function createNew(path, data, mode) {
+	const handle = await open(path, "wx", mode);
 	try {
-		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
+		await handle.writeFile(data);
+		if (mode !== void 0) await handle.chmod(mode);
 	} catch (error) {
-		if (isMissingFile(error)) return [];
+		await handle.close();
+		await rm(path, { force: true });
 		throw error;
 	}
-	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version)).flatMap(upgradeOf);
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/update.js
-const updateSchema = object({
-	from: string(),
-	latest: string(),
-	installed: object({
-		version: string(),
-		prefix: string()
-	}).nullable(),
-	upgrades: array(upgradeSchema),
-	next: array(string())
-});
-function nothingToInstall({ from, latest }) {
-	return standingOf$1(from, latest) === "current" ? `already on ${from}, the latest release: nothing to install` : `${from} is newer than the latest release ${latest}: nothing to install`;
+	await handle.close();
 }
-function renderUpgrade(upgrade) {
-	return "steps" in upgrade ? [`\nupgrade steps for ${upgrade.version}:`, ...upgrade.steps.map((step) => `- ${step}`)].join("\n") : `\nchanges in ${upgrade.version}:\n${upgrade.notes}`;
+const RENAME_ATTEMPTS = 10;
+const RENAME_BACKOFF_MS = 10;
+const HELD_BY_ANOTHER_PROGRAM = /* @__PURE__ */ new Set(["EPERM", "EBUSY"]);
+async function renameRetrying(from, to) {
+	for (let attempt = 1;; attempt++) try {
+		await rename(from, to);
+		return;
+	} catch (error) {
+		if (!(process.platform === "win32" && HELD_BY_ANOTHER_PROGRAM.has(errnoOf(error))) || attempt === RENAME_ATTEMPTS) throw error;
+		await setTimeout$1(attempt * RENAME_BACKOFF_MS);
+	}
 }
-function renderUpdate(cli, install, update) {
-	const { installed } = update;
-	const head = installed === null ? [nothingToInstall(update)] : [`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`, ...update.upgrades.map(renderUpgrade)];
-	const next = update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${update.latest}`);
-	return (next.length === 0 ? head : [
-		...head,
-		"",
-		...next
-	]).join("\n");
+/** Real files for one run: the first write to each folder sweeps the temp files of dead writers. */
+function realFiles() {
+	const swept = /* @__PURE__ */ new Set();
+	return {
+		exists: async (path) => {
+			try {
+				await access(path);
+				return true;
+			} catch (error) {
+				if (isNothingThere(error)) return false;
+				throw error;
+			}
+		},
+		write: async (path, data, options = {}) => {
+			await mkdir(dirname(path), { recursive: true });
+			const target = options.exclusive === true ? path : await targetOf$1(path);
+			const folder = dirname(target);
+			if (!swept.has(folder)) {
+				await sweep(folder);
+				swept.add(folder);
+			}
+			const temp = tempPathOf(target);
+			try {
+				await writeWithMode(temp, data, options.mode);
+				if (options.exclusive === true) {
+					await linkNew(temp, target, data, options.mode);
+					await rm(temp);
+				} else await renameRetrying(temp, target);
+			} catch (error) {
+				await rm(temp, { force: true });
+				throw error;
+			}
+		},
+		read: (path) => readFile(path),
+		list: (folder) => readdir(folder),
+		remove: (path) => rm(path, {
+			recursive: true,
+			force: true
+		}),
+		mkdir: async (path, options) => {
+			const mode = options?.mode;
+			if (options?.exclusive !== true) {
+				await mkdir(path, {
+					recursive: true,
+					mode
+				});
+				return;
+			}
+			await mkdir(dirname(path), {
+				recursive: true,
+				mode
+			});
+			await mkdir(path, { mode });
+		},
+		stat: async (path) => {
+			try {
+				const { size, dev, ino } = await stat(path, { bigint: true });
+				return {
+					size: Number(size),
+					id: `${dev}:${ino}`
+				};
+			} catch (error) {
+				if (isNothingThere(error)) return void 0;
+				throw error;
+			}
+		}
+	};
 }
-async function skillNext(cli, latest, ctx) {
-	const { fix } = await skillReport(cli, latest, ctx);
-	return fix === void 0 ? [] : [fix];
+/**
+* `files` resolving paths against `cwd`, its failures classified by errno; `list` drops the
+* Runtime's temp files and sorts.
+*/
+function classifiedFiles(files, { cwd, fileError }) {
+	async function at(access, path, work) {
+		const target = resolve(cwd, path);
+		try {
+			return await work(target);
+		} catch (error) {
+			throw fileError(error, {
+				path: target,
+				access
+			});
+		}
+	}
+	return {
+		exists: (path) => at("read", path, (target) => files.exists(target)),
+		write: (path, data, options) => at("write", path, (target) => files.write(target, data, options)),
+		read: (path) => at("read", path, (target) => files.read(target)),
+		list: (folder) => at("read", folder, async (target) => (await files.list(target)).filter((name) => !TEMP_FILE.test(name)).sort()),
+		remove: (path) => at("write", path, (target) => files.remove(target)),
+		mkdir: (path, options) => at("write", path, (target) => files.mkdir(target, options)),
+		stat: (path) => at("read", path, (target) => files.stat(target))
+	};
 }
-function interruptedAfterInstall(plan) {
-	return new CliError({
-		code: INTERRUPTED,
-		message: `interrupted, but ${plan.package}@${plan.latest} had already been installed with the npm under ${plan.prefix}, replacing ${plan.from}`,
-		hint: "nothing to run again: run the commands under next"
+//#endregion
+//#region ../agent-cli/dist/outputs.js
+const OUTPUT_EXISTS = "OUTPUT_EXISTS";
+/** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
+async function checkOutputs({ invocation, commandLine, force, files }, outputs) {
+	if (outputs === void 0 || force) return;
+	const found = await Promise.all(outputs.map((path) => files.exists(path)));
+	const existing = outputs.filter((_path, index) => found[index]);
+	if (existing.length === 0) return;
+	const them = existing.length === 1 ? "it" : "them";
+	throw new CliError({
+		code: OUTPUT_EXISTS,
+		message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
+		hint: `to replace ${them}, run \`${commandLineOf(invocation, { add: [FORCE_FLAG.flag] })}\``
 	});
 }
-/** The built-in `update`, for a CLI installed globally with npm. */
-function updateCommand(cli, install, { bin, node }) {
-	return defineCommand$1({
-		name: "update",
-		description: "install the latest version of this CLI from its registry",
-		examples: [{
-			command: `${cli.name} update`,
-			note: "install the latest version and show what changed"
-		}, {
-			command: `${cli.name} update --dry-run`,
-			note: "show the version it would install"
-		}],
-		effect: "write",
-		output: updateSchema,
-		plan: async (_input, ctx) => {
-			const npm = globalNpm(cli, install, ctx, node);
-			const copy = await globalInstallOf(bin, npm);
-			return {
-				package: install.package,
-				from: cli.version,
-				latest: await latestVersion(npm),
-				prefix: copy.prefix,
-				packageDir: copy.packageDir
-			};
-		},
-		apply: async (plan, ctx) => {
-			const { from, latest, prefix } = plan;
-			if (standingOf$1(from, latest) !== "behind") return {
-				from,
-				latest,
-				installed: null,
-				upgrades: [],
-				next: await skillNext(cli, latest, ctx)
-			};
-			ctx.signal.throwIfAborted();
-			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
-			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, globalNpm(cli, install, ctx, node)));
-			const update = {
-				from,
-				latest,
-				installed: {
-					version: latest,
-					prefix
-				},
-				upgrades: await upgradesOf(plan.packageDir, from, latest),
-				next: await skillNext(cli, latest, ctx)
-			};
-			if (ctx.signal.aborted) {
-				ctx.deliver(update);
-				throw interruptedAfterInstall(plan);
-			}
-			return update;
+/** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
+function outputsGuard(files, cwd) {
+	const unwritten = /* @__PURE__ */ new Set();
+	let forceLine = "";
+	const exclusiveWrite = async (path, data, options) => {
+		const target = resolve(cwd, path);
+		unwritten.delete(target);
+		try {
+			await files.write(path, data, {
+				...options,
+				exclusive: true
+			});
+		} catch (error) {
+			unwritten.add(target);
+			if (!(error instanceof CliError) || error.code !== "ALREADY_EXISTS") throw error;
+			throw new CliError({
+				code: ALREADY_EXISTS,
+				message: error.message,
+				hint: `to replace it, run \`${forceLine}\``
+			}, { cause: error });
+		}
+	};
+	return {
+		files: {
+			...files,
+			write: (path, data, options) => unwritten.has(resolve(cwd, path)) ? exclusiveWrite(path, data, options) : files.write(path, data, options)
 		},
-		render: (update) => renderUpdate(cli, install, update),
-		renderPlan: (plan) => standingOf$1(plan.from, plan.latest) === "behind" ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}, replacing ${plan.from}` : nothingToInstall(plan)
-	});
+		guard: (outputs, line) => {
+			forceLine = line;
+			for (const path of outputs) unwritten.add(resolve(cwd, path));
+		}
+	};
+}
+/**
+* Creates each output folder and a temp file in it, so a sandbox denial fails before `apply`
+* spends anything. The temp file's name is the Runtime's, so a crashed run's leftover is swept.
+*/
+async function probeOutputs({ files, cwd, fileError }, outputs) {
+	const folders = new Set(outputs.map((path) => dirname(resolve(cwd, path))));
+	await Promise.all([...folders].map(async (folder) => {
+		const probe = tempPathOf(join(folder, "outputs-probe"));
+		try {
+			await files.mkdir(folder);
+			await files.write(probe, "");
+			await files.remove(probe);
+		} catch (error) {
+			throw fileError(error, {
+				path: folder,
+				access: "write"
+			});
+		}
+	}));
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/commands.js
-/** The Commands the Runtime adds to a multi-Command CLI: `update` only for a Global install. */
-function builtInCommands(cli, launch) {
+//#region ../agent-cli/dist/built-ins/skill-install.js
+const installSchema = object({
+	copy: string(),
+	written: array(string()),
+	removed: array(string()),
+	agentsMd: object({
+		path: string(),
+		changed: boolean()
+	}),
+	handEdits: array(string())
+});
+async function sameContent(left, right) {
+	const [a, b] = await Promise.all([readFile(left), readFile(right)]);
+	return a.equals(b);
+}
+/** One paragraph telling every session that the CLI exists, how to run it and which skill to load. */
+function agentsBlock(cli) {
+	const { install } = cli;
+	const where = install?.mode === "dependency" ? `, and only from a package that has \`${install.package}\` in its dependencies; from anywhere else npx reports the package missing` : "";
+	const what = cli.description.replace(/\.$/, "");
+	return `\`${cli.name}\`: ${what}. Run it as \`${runAsOf(cli)}\`${where}. Load the \`${cli.name}\` skill before using it.`;
+}
+function markersOf(name) {
 	return {
-		doctor: doctorCommand(cli, launch),
-		...cli.install?.mode === "global" ? { update: updateCommand(cli, cli.install, launch) } : {}
+		begin: `<!-- BEGIN:${name} -->`,
+		end: `<!-- END:${name} -->`
+	};
+}
+/** `text` with the block between its markers, appended when they are missing; nothing else changes. */
+function withBlock(text, block, { begin, end }) {
+	const whole = `${begin}\n${block}\n${end}`;
+	const start = text.indexOf(begin);
+	const stop = start === -1 ? -1 : text.indexOf(end, start);
+	if (stop !== -1) return `${text.slice(0, start)}${whole}${text.slice(stop + end.length)}`;
+	if (text === "") return `${whole}\n`;
+	return `${text}${text.endsWith("\n") ? "" : "\n"}\n${whole}\n`;
+}
+function blockChangeOf(existing, block, markers) {
+	if (existing === void 0) return "create";
+	if (withBlock(existing, block, markers) === existing) return null;
+	return existing.includes(markers.begin) ? "rewrite" : "add";
+}
+async function handEditsAt(root) {
+	const claudeMd = join(root, "CLAUDE.md");
+	const text = await orMissing(readFile(claudeMd, "utf8"));
+	if (text === void 0 || text.split(/\r?\n/).some((line) => line.trim() === "@AGENTS.md")) return [];
+	return [`add a line \`@AGENTS.md\` to ${claudeMd}, so Claude Code reads AGENTS.md`];
+}
+async function planOf(cli, folder, cwd, packageRoot) {
+	const source = join(packageRoot, folder);
+	const { root, copy } = await skillCopyOf(cli, cwd);
+	const [shipped, present] = await Promise.all([filesIn(source), filesIn(copy)]);
+	const differs = await Promise.all(shipped.map(async (file) => present.includes(file) && !await sameContent(join(source, file), join(copy, file))));
+	const agentsPath = join(root, "AGENTS.md");
+	const block = agentsBlock(cli);
+	return {
+		source,
+		copy,
+		write: shipped.filter((file) => !present.includes(file)),
+		replace: shipped.filter((_file, index) => differs[index]),
+		remove: present.filter((file) => !shipped.includes(file)),
+		sameVersion: (await skillVersionsOf(source, copy)).same,
+		agentsMd: {
+			path: agentsPath,
+			block,
+			change: blockChangeOf(await orMissing(readFile(agentsPath, "utf8")), block, markersOf(cli.name))
+		},
+		handEdits: await handEditsAt(root)
 	};
 }
-//#endregion
-//#region ../agent-cli/dist/confirm.js
-const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
-const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
-function checkConfirmation({ invocation, commandLine, given }, expected) {
-	if (given === expected) return;
-	const hint = `to confirm, run \`${commandLineOf(invocation, {
-		remove: [CONFIRM_FLAG.flag],
-		add: [CONFIRM_FLAG.flag, expected]
-	})}\``;
-	if (given === void 0) throw new UsageError({
-		code: CONFIRMATION_REQUIRED,
-		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
-		hint
-	});
-	throw new UsageError({
-		code: CONFIRMATION_MISMATCH,
-		message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
-		hint
+const BLOCK_VERBS = {
+	create: "create",
+	add: "add the block to",
+	rewrite: "rewrite the block in"
+};
+function renderPlan(cli, plan) {
+	const files = [
+		...plan.write.map((file) => `  write ${file}`),
+		...plan.replace.map((file) => `  replace ${file}`),
+		...plan.remove.map((file) => `  remove ${file}`)
+	];
+	const { path, block, change } = plan.agentsMd;
+	return [
+		files.length === 0 ? `the ${cli.name} skill at ${plan.copy} already matches the package` : `would copy the ${cli.name} skill to ${plan.copy}:`,
+		...files,
+		change === null ? `${path} already holds the ${cli.name} block` : `would ${BLOCK_VERBS[change]} ${path}:\n${block}`,
+		...plan.handEdits.map((edit) => `by hand: ${edit}`)
+	].join("\n");
+}
+function renderInstalled(cli, data) {
+	const { written, removed, agentsMd } = data;
+	return [
+		written.length + removed.length === 0 ? `the ${cli.name} skill at ${data.copy} already matches the package` : `copied the ${cli.name} skill to ${data.copy}: wrote ${written.length} files, removed ${removed.length}`,
+		agentsMd.changed ? `wrote the ${cli.name} block in ${agentsMd.path}` : `${agentsMd.path} already holds the ${cli.name} block`,
+		...data.handEdits.map((edit) => `by hand: ${edit}`)
+	].join("\n");
+}
+function editedRemovals(plan, ctx) {
+	const them = plan.remove.length === 1 ? "it" : "them";
+	return new CliError({
+		code: OUTPUT_EXISTS,
+		message: `\`${ctx.commandLine()}\` would remove ${plan.remove.map((file) => join(plan.copy, file)).join(", ")}`,
+		hint: `to remove ${them}, run \`${ctx.commandLine({ add: [FORCE_FLAG.flag] })}\``
 	});
 }
-//#endregion
-//#region ../agent-cli/dist/cost.js
-const NOT_CONFIRMED = "NOT_CONFIRMED";
-/** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
-function checkCost({ invocation, commandLine, yes }, cost) {
-	if (cost === void 0 || yes) return;
-	throw new CliError({
-		code: NOT_CONFIRMED,
-		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
-		hint: `to approve the cost, run \`${commandLineOf(invocation, { add: [YES_FLAG.flag] })}\``
+/** The built-in `skill install`, for a CLI whose skill ships in its package. */
+function skillInstallCommand(cli, folder) {
+	const runAs = runAsOf(cli);
+	return defineCommand$1({
+		name: "install",
+		description: "copy this CLI's skill into the project and write its AGENTS.md block",
+		examples: [{
+			command: `${runAs} skill install`,
+			note: "install the skill this version ships"
+		}, {
+			command: `${runAs} skill install --dry-run`,
+			note: "show what it would change"
+		}],
+		effect: "write",
+		output: installSchema,
+		force: "replace or remove hand-edited files of a skill copy at the package's version",
+		plan: (_input, ctx) => planOf(cli, folder, ctx.cwd, ctx.packageRoot),
+		outputs: (plan) => plan.sameVersion ? [...plan.write, ...plan.replace].map((file) => join(plan.copy, file)) : [],
+		apply: async (plan, ctx) => {
+			if (plan.sameVersion && plan.remove.length > 0 && !ctx.force) throw editedRemovals(plan, ctx);
+			for (const file of [...plan.write, ...plan.replace]) await ctx.files.write(join(plan.copy, file), await readFile(join(plan.source, file)));
+			for (const file of plan.remove) await ctx.files.remove(join(plan.copy, file));
+			const { path, block, change } = plan.agentsMd;
+			if (change !== null) {
+				const existing = await orMissing(readFile(path, "utf8")) ?? "";
+				await ctx.files.write(path, withBlock(existing, block, markersOf(cli.name)));
+			}
+			return {
+				copy: plan.copy,
+				written: [...plan.write, ...plan.replace].sort(),
+				removed: [...plan.remove],
+				agentsMd: {
+					path,
+					changed: change !== null
+				},
+				handEdits: [...plan.handEdits]
+			};
+		},
+		render: (data) => renderInstalled(cli, data),
+		renderPlan: (plan) => renderPlan(cli, plan)
 	});
 }
 //#endregion
-//#region ../agent-cli/dist/agent.js
-const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
-const isSet = (name) => (env) => (env[name] ?? "") !== "";
-const equals = (name, value) => (env) => env[name] === value;
-const MARKERS = [
-	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
-	equals("AGENT", "amp"),
-	isSet("CODEX_SANDBOX"),
-	isSet("CODEX_CI"),
-	isSet("CODEX_THREAD_ID"),
-	isSet("GEMINI_CLI"),
-	isSet("COPILOT_CLI"),
-	isSet("OPENCODE"),
-	isSet("ANTIGRAVITY_AGENT"),
-	isSet("AUGMENT_AGENT"),
-	isSet("REPL_ID"),
-	isSet("CLAUDE_CODE_IS_COWORK"),
-	isSet("CLAUDECODE"),
-	isSet("CLAUDE_CODE"),
-	isSet("CURSOR_TRACE_ID"),
-	isSet("CURSOR_AGENT"),
-	equals("CURSOR_EXTENSION_HOST_ROLE", "agent-exec"),
-	equals("TERM_PROGRAM", "kiro"),
-	(env) => ["/.pi/agent", "\\.pi\\agent"].some((dir) => (env.PATH ?? "").includes(dir)),
-	isSet("GOOSE_PROVIDER")
-];
-/**
-* Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
-* in a PTY, so a TTY alone doesn't mean a person is watching.
-*/
-function isAgent(env) {
-	return MARKERS.some((marker) => marker(env));
+//#region ../agent-cli/dist/interrupts.js
+const INTERRUPTED = "INTERRUPTED";
+const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
+/** How long an interrupted Command may take to settle before the run ends without it. */
+const GRACE_MS = 3e3;
+const GRACE_OVER = Symbol("grace over");
+function interruptedError(callerLine) {
+	return new CliError({
+		code: INTERRUPTED,
+		message: "interrupted before it finished",
+		hint: `to finish it, run \`${callerLine}\` again, unless it was stopped on purpose; if a tool timeout stopped it, give it longer`
+	});
 }
-//#endregion
-//#region ../agent-cli/dist/errno.js
-const PERMISSION_DENIED = "PERMISSION_DENIED";
-const DISK_FULL = "DISK_FULL";
-const NOT_FOUND = "NOT_FOUND";
-const ALREADY_EXISTS = "ALREADY_EXISTS";
-const NOT_A_FILE = "NOT_A_FILE";
-function permissionHint({ path, access, callerLine, env, platform }) {
-	if (platform === "win32") return `a program may hold ${path} open: close it, then run the same command again`;
-	if (!isAgent(env)) return `check the permissions of ${path} and its folder`;
-	return `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`;
+function waitHint(callerLine, bound) {
+	return bound === "timeout" ? `the call may have been billed: ask your user before running \`${callerLine}\` again` : `run \`${callerLine}\` again later, when the service it waits on may answer faster`;
 }
-function fileErrorOf(scope) {
-	return (error, at) => classifyErrno(error, {
-		...at,
-		...scope
+function deadlineError(commandLine, ms, hint, bound = "deadline") {
+	return new CliError({
+		code: DEADLINE_EXCEEDED,
+		message: `${commandLine} ran past its ${ms} ms ${bound}`,
+		hint
 	});
 }
-function classifyErrno(error, context) {
-	const { path } = context;
-	switch (errnoOf(error)) {
-		case "EACCES":
-		case "EPERM":
-		case "EROFS":
-		case "EBUSY": return new CliError({
-			code: PERMISSION_DENIED,
-			message: `permission denied: ${path}`,
-			hint: permissionHint(context)
-		}, { cause: error });
-		case "ENOSPC":
-		case "EDQUOT": return new CliError({
-			code: DISK_FULL,
-			message: `no space left on the disk holding ${path}`,
-			hint: "free space on that disk, then run the same command again"
-		}, { cause: error });
-		case "ENOENT":
-		case "ENOTDIR":
-		case "ENAMETOOLONG": return new CliError({
-			code: NOT_FOUND,
-			message: `not found: ${path}`,
-			hint: `check that ${path} and its folder exist`
-		}, { cause: error });
-		case "EEXIST": return new CliError({
-			code: ALREADY_EXISTS,
-			message: `already exists: ${path}`,
-			hint: `pass another path, or remove ${path}`
-		}, { cause: error });
-		case "EISDIR": return new CliError({
-			code: NOT_A_FILE,
-			message: `not a file: ${path} is a folder`,
-			hint: `pass the path of a file, not of the folder ${path}`
-		}, { cause: error });
-		default: return error;
+/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
+var RunControl = class {
+	signal;
+	#controller = new AbortController();
+	#commandLine;
+	#callerLine;
+	#outer;
+	#onOuterAbort = () => this.#controller.abort(interruptedError(this.#callerLine));
+	/** Each running must-finish step, tracked until it settles, with its name. */
+	#steps = /* @__PURE__ */ new Map();
+	#progress;
+	#clock;
+	#disposed = new AbortController();
+	/** The reasons this run's deadlines and timeouts aborted with, to tell them in a Command's error. */
+	#abortReasons = /* @__PURE__ */ new WeakSet();
+	#graceCancel = new AbortController();
+	#endGrace = () => {};
+	#graceOver = new Promise((resolve) => {
+		this.#endGrace = resolve;
+	});
+	constructor({ commandLine, callerLine, outer, clock, progress, runDeadline }) {
+		this.#commandLine = commandLine;
+		this.#callerLine = callerLine;
+		this.#outer = outer;
+		this.#clock = clock;
+		this.#progress = progress;
+		this.signal = this.#controller.signal;
+		this.signal.addEventListener("abort", () => this.#onStop(), { once: true });
+		if (outer?.aborted === true) this.#onOuterAbort();
+		else outer?.addEventListener("abort", this.#onOuterAbort, { once: true });
+		if (runDeadline !== void 0) {
+			const { ms, hint } = runDeadline;
+			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, hint())));
+		}
+	}
+	deadline(ms) {
+		return AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
+	}
+	timeout(ms) {
+		return this.#abortsAfter(ms, "timeout");
+	}
+	#abortsAfter(ms, bound) {
+		const controller = new AbortController();
+		after(this.#clock, ms, this.#disposed.signal, () => {
+			const reason = deadlineError(this.#commandLine, ms, waitHint(this.#callerLine, bound), bound);
+			this.#abortReasons.add(reason);
+			controller.abort(reason);
+		});
+		return controller.signal;
+	}
+	async runToEnd(name, work) {
+		this.#graceCancel.abort();
+		if (this.signal.aborted) this.#finishing(name);
+		const step = work();
+		const settled = step.then(() => {}, () => {});
+		this.#steps.set(settled, name);
+		try {
+			return await step;
+		} finally {
+			this.#steps.delete(settled);
+			this.#startGrace();
+		}
+	}
+	/** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
+	async settle(work) {
+		try {
+			const value = await Promise.race([work, this.#graceOver]);
+			if (this.signal.aborted || value === GRACE_OVER) throw this.signal.reason;
+			return value;
+		} finally {
+			await this.#stepsDone();
+			this.close();
+		}
+	}
+	/**
+	* The error a run ends with: an interrupt or the run deadline outranks what the Command threw,
+	* unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
+	* Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's or timeout's
+	* abort is reported as that abort, so a declared error keeps its own code.
+	*/
+	errorAfter(error) {
+		if (this.signal.aborted) return error instanceof CliError && error.code === "INTERRUPTED" ? error : this.signal.reason;
+		const leaves = errorsOf(error).map((leaf) => this.#abortIn(leaf) ?? leaf);
+		return leaves.length === 1 ? leaves[0] : new AggregateError(leaves);
+	}
+	#abortIn(error) {
+		if (error instanceof CliError) return void 0;
+		return causesOf(error).find((each) => each instanceof CliError && this.#abortReasons.has(each));
 	}
-}
-//#endregion
-//#region ../agent-cli/dist/operator.js
-const NEEDS_OPERATOR = "NEEDS_OPERATOR";
-/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
-function checkOperator({ operator, commandLine }, env, callerLine) {
-	if (!operator || !isAgent(env)) return;
-	throw new CliError({
-		code: NEEDS_OPERATOR,
-		message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
-		hint: `ask the operator to type: ! ${callerLine}`
-	});
-}
+	#onStop() {
+		for (const name of this.#steps.values()) this.#finishing(name);
+		this.#startGrace();
+	}
+	#finishing(name) {
+		this.#progress(`finishing ${name}`);
+	}
+	#startGrace() {
+		if (this.signal.aborted && this.#steps.size === 0) {
+			this.#graceCancel.abort();
+			this.#graceCancel = new AbortController();
+			after(this.#clock, GRACE_MS, this.#graceCancel.signal, () => this.#endGrace(GRACE_OVER));
+		}
+	}
+	async #stepsDone() {
+		while (this.#steps.size > 0) await Promise.all(this.#steps.keys());
+	}
+	/** Stops the run's timers and its hold on the caller's signal, for a run that never settles. */
+	close() {
+		this.#graceCancel.abort();
+		this.#disposed.abort();
+		this.#outer?.removeEventListener("abort", this.#onOuterAbort);
+	}
+};
 //#endregion
-//#region ../agent-cli/dist/files.js
-const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
-/** Where the Runtime writes `path` before moving it into place; a dead writer's is swept. */
-function tempPathOf(path) {
-	return join(dirname(path), `.${basename(path)}.agent-cli-${process.pid}.tmp`);
-}
-function isAlive(pid) {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return errnoOf(error) === "EPERM";
+//#region ../agent-cli/dist/built-ins/upgrades.js
+/** A skipped release's Upgrade steps, or its whole section when it lists none. */
+const upgradeSchema = union([object({
+	version: string(),
+	steps: array(string())
+}), object({
+	version: string(),
+	notes: string()
+})]);
+const RELEASE_HEADING = /^## v?(\S+)/;
+const UPGRADE_HEADING = /^### Upgrade from v\S+$/;
+const HEADING = /^#{1,6} /;
+const ITEM = /^[-*] /;
+const NOTHING_TO_DO = /^nothing to do\.?$/i;
+function releasesIn(changelog) {
+	const releases = [];
+	let current;
+	for (const line of changelog.split(/\r?\n/)) {
+		const heading = RELEASE_HEADING.exec(line);
+		if (heading !== null) {
+			const version = heading[1] ?? "";
+			current = isVersion(version) ? {
+				version,
+				lines: []
+			} : void 0;
+			if (current !== void 0) releases.push(current);
+		} else current?.lines.push(line);
 	}
+	return releases;
 }
-async function sweep(folder) {
-	const dead = (await readdir(folder)).filter((name) => {
-		const pid = TEMP_FILE.exec(name)?.[1];
-		return pid !== void 0 && !isAlive(Number(pid));
-	});
-	await Promise.all(dead.map((name) => rm(join(folder, name), { force: true })));
+function listedSteps(lines) {
+	const start = lines.findIndex((line) => UPGRADE_HEADING.test(line.trimEnd()));
+	if (start === -1) return [];
+	const end = lines.findIndex((line, i) => i > start && HEADING.test(line));
+	const body = lines.slice(start + 1, end === -1 ? void 0 : end).filter((line) => line.trim() !== "");
+	const starts = body.flatMap((line, i) => ITEM.test(line) ? [i] : []);
+	return starts.map((first, i) => body.slice(first, starts[i + 1]).map((line) => line.trim()).join(" ").replace(ITEM, ""));
 }
-/** The file a symlink at `path` points to, so a replacing write keeps the link. */
-async function targetOf$1(path) {
+function upgradeOf({ version, lines }) {
+	const listed = listedSteps(lines);
+	if (listed.length === 0) return [{
+		version,
+		notes: lines.join("\n").trim()
+	}];
+	const todo = listed.filter((step) => !NOTHING_TO_DO.test(step));
+	return todo.length === 0 ? [] : [{
+		version,
+		steps: todo
+	}];
+}
+/**
+* What each release after `from` up to `to` asks of the operator, oldest first, from the
+* CHANGELOG.md in `packageDir`; none when the package ships no CHANGELOG.
+*/
+async function upgradesOf(packageDir, from, to) {
+	let changelog;
 	try {
-		return await realpath(path);
+		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
 	} catch (error) {
-		if (isMissingFile(error)) return path;
+		if (isMissingFile(error)) return [];
 		throw error;
 	}
+	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version)).flatMap(upgradeOf);
 }
-async function writeWithMode(path, data, mode) {
-	if (mode === void 0) {
-		await writeFile(path, data);
-		return;
-	}
-	await writeFile(path, data, { mode });
-	await chmod(path, mode);
+//#endregion
+//#region ../agent-cli/dist/built-ins/update.js
+const updateSchema = object({
+	from: string(),
+	latest: string(),
+	installed: object({
+		version: string(),
+		prefix: string()
+	}).nullable(),
+	upgrades: array(upgradeSchema),
+	next: array(string())
+});
+function nothingToInstall({ from, latest }) {
+	return standingOf$1(from, latest) === "current" ? `already on ${from}, the latest release: nothing to install` : `${from} is newer than the latest release ${latest}: nothing to install`;
 }
-/** What `link` answers on a file system without hard links, such as exFAT. */
-const NO_HARD_LINKS = /* @__PURE__ */ new Set([
-	"EPERM",
-	"ENOTSUP",
-	"EXDEV"
-]);
-/** A link fails atomically when `path` is taken, so no reader ever sees half a file there. */
-async function linkNew(temp, path, data, mode) {
-	try {
-		await link(temp, path);
-	} catch (error) {
-		if (!NO_HARD_LINKS.has(errnoOf(error))) throw error;
-		await createNew(path, data, mode);
-	}
+function renderUpgrade(upgrade) {
+	return "steps" in upgrade ? [`\nupgrade steps for ${upgrade.version}:`, ...upgrade.steps.map((step) => `- ${step}`)].join("\n") : `\nchanges in ${upgrade.version}:\n${upgrade.notes}`;
 }
-/** A file this call created and could not finish is removed, so a rerun does not find half of it. */
-async function createNew(path, data, mode) {
-	const handle = await open(path, "wx", mode);
-	try {
-		await handle.writeFile(data);
-		if (mode !== void 0) await handle.chmod(mode);
-	} catch (error) {
-		await handle.close();
-		await rm(path, { force: true });
-		throw error;
-	}
-	await handle.close();
+function renderUpdate(cli, install, update) {
+	const { installed } = update;
+	const head = installed === null ? [nothingToInstall(update)] : [`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`, ...update.upgrades.map(renderUpgrade)];
+	const next = update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${update.latest}`);
+	return (next.length === 0 ? head : [
+		...head,
+		"",
+		...next
+	]).join("\n");
 }
-const RENAME_ATTEMPTS = 10;
-const RENAME_BACKOFF_MS = 10;
-const HELD_BY_ANOTHER_PROGRAM = /* @__PURE__ */ new Set(["EPERM", "EBUSY"]);
-async function renameRetrying(from, to) {
-	for (let attempt = 1;; attempt++) try {
-		await rename(from, to);
-		return;
-	} catch (error) {
-		if (!(process.platform === "win32" && HELD_BY_ANOTHER_PROGRAM.has(errnoOf(error))) || attempt === RENAME_ATTEMPTS) throw error;
-		await setTimeout$1(attempt * RENAME_BACKOFF_MS);
-	}
+async function skillNext(cli, latest, ctx) {
+	const packaged = packagedFolderOf(cli);
+	const finding = packaged === void 0 ? await skillReport(cli, latest, ctx) : await packagedSkillFinding(cli, packaged, ctx);
+	return "fix" in finding && finding.fix !== void 0 ? [finding.fix] : [];
 }
-/** Real files for one run: the first write to each folder sweeps the temp files of dead writers. */
-function realFiles() {
-	const swept = /* @__PURE__ */ new Set();
-	return {
-		exists: async (path) => {
-			try {
-				await access(path);
-				return true;
-			} catch (error) {
-				if (isNothingThere(error)) return false;
-				throw error;
-			}
-		},
-		write: async (path, data, options = {}) => {
-			await mkdir(dirname(path), { recursive: true });
-			const target = options.exclusive === true ? path : await targetOf$1(path);
-			const folder = dirname(target);
-			if (!swept.has(folder)) {
-				await sweep(folder);
-				swept.add(folder);
-			}
-			const temp = tempPathOf(target);
-			try {
-				await writeWithMode(temp, data, options.mode);
-				if (options.exclusive === true) {
-					await linkNew(temp, target, data, options.mode);
-					await rm(temp);
-				} else await renameRetrying(temp, target);
-			} catch (error) {
-				await rm(temp, { force: true });
-				throw error;
-			}
-		},
-		read: (path) => readFile(path),
-		list: (folder) => readdir(folder),
-		remove: (path) => rm(path, {
-			recursive: true,
-			force: true
-		}),
-		mkdir: async (path, options) => {
-			const mode = options?.mode;
-			if (options?.exclusive !== true) {
-				await mkdir(path, {
-					recursive: true,
-					mode
-				});
-				return;
-			}
-			await mkdir(dirname(path), {
-				recursive: true,
-				mode
-			});
-			await mkdir(path, { mode });
+function interruptedAfterInstall(plan) {
+	return new CliError({
+		code: INTERRUPTED,
+		message: `interrupted, but ${plan.package}@${plan.latest} had already been installed with the npm under ${plan.prefix}, replacing ${plan.from}`,
+		hint: "nothing to run again: run the commands under next"
+	});
+}
+/** The built-in `update`, for a CLI installed globally with npm. */
+function updateCommand(cli, install, { bin, node }) {
+	return defineCommand$1({
+		name: "update",
+		description: "install the latest version of this CLI from its registry",
+		examples: [{
+			command: `${cli.name} update`,
+			note: "install the latest version and show what changed"
+		}, {
+			command: `${cli.name} update --dry-run`,
+			note: "show the version it would install"
+		}],
+		effect: "write",
+		output: updateSchema,
+		plan: async (_input, ctx) => {
+			const npm = globalNpm(cli, install, ctx, node);
+			const copy = await globalInstallOf(bin, npm);
+			return {
+				package: install.package,
+				from: cli.version,
+				latest: await latestVersion(npm),
+				prefix: copy.prefix,
+				packageDir: copy.packageDir
+			};
 		},
-		stat: async (path) => {
-			try {
-				const { size, dev, ino } = await stat(path, { bigint: true });
-				return {
-					size: Number(size),
-					id: `${dev}:${ino}`
-				};
-			} catch (error) {
-				if (isNothingThere(error)) return void 0;
-				throw error;
+		apply: async (plan, ctx) => {
+			const { from, latest, prefix } = plan;
+			if (standingOf$1(from, latest) !== "behind") return {
+				from,
+				latest,
+				installed: null,
+				upgrades: [],
+				next: await skillNext(cli, latest, ctx)
+			};
+			ctx.signal.throwIfAborted();
+			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
+			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, globalNpm(cli, install, ctx, node)));
+			const update = {
+				from,
+				latest,
+				installed: {
+					version: latest,
+					prefix
+				},
+				upgrades: await upgradesOf(plan.packageDir, from, latest),
+				next: await skillNext(cli, latest, ctx)
+			};
+			if (ctx.signal.aborted) {
+				ctx.deliver(update);
+				throw interruptedAfterInstall(plan);
 			}
-		}
-	};
+			return update;
+		},
+		render: (update) => renderUpdate(cli, install, update),
+		renderPlan: (plan) => standingOf$1(plan.from, plan.latest) === "behind" ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}, replacing ${plan.from}` : nothingToInstall(plan)
+	});
 }
+//#endregion
+//#region ../agent-cli/dist/built-ins/commands.js
 /**
-* `files` resolving paths against `cwd`, its failures classified by errno; `list` drops the
-* Runtime's temp files and sorts.
+* The Commands the Runtime adds to a multi-Command CLI: `update` only for a Global install, and
+* `skill install` only for a Packaged skill.
 */
-function classifiedFiles(files, { cwd, fileError }) {
-	async function at(access, path, work) {
-		const target = resolve(cwd, path);
-		try {
-			return await work(target);
-		} catch (error) {
-			throw fileError(error, {
-				path: target,
-				access
-			});
-		}
-	}
+function builtInCommands(cli, launch) {
+	const packaged = packagedFolderOf(cli);
 	return {
-		exists: (path) => at("read", path, (target) => files.exists(target)),
-		write: (path, data, options) => at("write", path, (target) => files.write(target, data, options)),
-		read: (path) => at("read", path, (target) => files.read(target)),
-		list: (folder) => at("read", folder, async (target) => (await files.list(target)).filter((name) => !TEMP_FILE.test(name)).sort()),
-		remove: (path) => at("write", path, (target) => files.remove(target)),
-		mkdir: (path, options) => at("write", path, (target) => files.mkdir(target, options)),
-		stat: (path) => at("read", path, (target) => files.stat(target))
+		doctor: doctorCommand(cli, launch),
+		...cli.install?.mode === "global" ? { update: updateCommand(cli, cli.install, launch) } : {},
+		...packaged === void 0 ? {} : { skill: { install: skillInstallCommand(cli, packaged) } }
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/outputs.js
-const OUTPUT_EXISTS = "OUTPUT_EXISTS";
-/** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
-async function checkOutputs({ invocation, commandLine, force, files }, outputs) {
-	if (outputs === void 0 || force) return;
-	const found = await Promise.all(outputs.map((path) => files.exists(path)));
-	const existing = outputs.filter((_path, index) => found[index]);
-	if (existing.length === 0) return;
-	const them = existing.length === 1 ? "it" : "them";
-	throw new CliError({
-		code: OUTPUT_EXISTS,
-		message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
-		hint: `to replace ${them}, run \`${commandLineOf(invocation, { add: [FORCE_FLAG.flag] })}\``
+//#region ../agent-cli/dist/confirm.js
+const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
+const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
+function checkConfirmation({ invocation, commandLine, given }, expected) {
+	if (given === expected) return;
+	const hint = `to confirm, run \`${commandLineOf(invocation, {
+		remove: [CONFIRM_FLAG.flag],
+		add: [CONFIRM_FLAG.flag, expected]
+	})}\``;
+	if (given === void 0) throw new UsageError({
+		code: CONFIRMATION_REQUIRED,
+		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
+		hint
+	});
+	throw new UsageError({
+		code: CONFIRMATION_MISMATCH,
+		message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
+		hint
 	});
 }
-/** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
-function outputsGuard(files, cwd) {
-	const unwritten = /* @__PURE__ */ new Set();
-	let forceLine = "";
-	const exclusiveWrite = async (path, data, options) => {
-		const target = resolve(cwd, path);
-		unwritten.delete(target);
-		try {
-			await files.write(path, data, {
-				...options,
-				exclusive: true
-			});
-		} catch (error) {
-			unwritten.add(target);
-			if (!(error instanceof CliError) || error.code !== "ALREADY_EXISTS") throw error;
-			throw new CliError({
-				code: ALREADY_EXISTS,
-				message: error.message,
-				hint: `to replace it, run \`${forceLine}\``
-			}, { cause: error });
-		}
-	};
-	return {
-		files: {
-			...files,
-			write: (path, data, options) => unwritten.has(resolve(cwd, path)) ? exclusiveWrite(path, data, options) : files.write(path, data, options)
-		},
-		guard: (outputs, line) => {
-			forceLine = line;
-			for (const path of outputs) unwritten.add(resolve(cwd, path));
-		}
-	};
+//#endregion
+//#region ../agent-cli/dist/cost.js
+const NOT_CONFIRMED = "NOT_CONFIRMED";
+/** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
+function checkCost({ invocation, commandLine, yes }, cost) {
+	if (cost === void 0 || yes) return;
+	throw new CliError({
+		code: NOT_CONFIRMED,
+		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
+		hint: `to approve the cost, run \`${commandLineOf(invocation, { add: [YES_FLAG.flag] })}\``
+	});
 }
-/**
-* Creates each output folder and a temp file in it, so a sandbox denial fails before `apply`
-* spends anything. The temp file's name is the Runtime's, so a crashed run's leftover is swept.
-*/
-async function probeOutputs({ files, cwd, fileError }, outputs) {
-	const folders = new Set(outputs.map((path) => dirname(resolve(cwd, path))));
-	await Promise.all([...folders].map(async (folder) => {
-		const probe = tempPathOf(join(folder, "outputs-probe"));
-		try {
-			await files.mkdir(folder);
-			await files.write(probe, "");
-			await files.remove(probe);
-		} catch (error) {
-			throw fileError(error, {
-				path: folder,
-				access: "write"
-			});
-		}
-	}));
+//#endregion
+//#region ../agent-cli/dist/operator.js
+const NEEDS_OPERATOR = "NEEDS_OPERATOR";
+/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
+function checkOperator({ operator, commandLine }, env, callerLine) {
+	if (!operator || !isAgent(env)) return;
+	throw new CliError({
+		code: NEEDS_OPERATOR,
+		message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
+		hint: `ask the operator to type: ! ${callerLine}`
+	});
 }
 //#endregion
 //#region ../agent-cli/dist/exit-classes.js
@@ -8500,7 +8836,10 @@ function checkOwnCodes(cli) {
 }
 function defineCli$1(cli) {
 	checkOwnCodes(cli);
-	if (cli.commands === void 0) return cli;
+	if (cli.commands === void 0) {
+		if (packagedFolderOf(cli) !== void 0) throw new Error(`${cli.name} declares a Packaged skill, which only a CLI with several Commands can install`);
+		return cli;
+	}
 	const { commands } = cli;
 	const taken = Object.keys(builtInCommands(cli, {
 		bin: void 0,
@@ -8667,7 +9006,7 @@ function examplesSection(examples, style) {
 }
 /** The CLI's own help: a listing or its single Command's help, ending with exit codes and examples. */
 function cliHelp(cli, root, style) {
-	return lines(...root.kind === "command" ? commandLines(root, style, { examples: false }) : listingLines(`${root.commandLine} ${cli.version}`, root, style, cli.description), ...section("Exit codes", exitCodeRows(cli), style), ...examplesSection(rootExamples(root), style));
+	return lines(...root.kind === "command" ? commandLines(root, style, { examples: false }) : listingLines(`${cli.name} ${cli.version}`, root, style, cli.description), ...section("Exit codes", exitCodeRows(cli), style), ...examplesSection(rootExamples(root), style));
 }
 function groupHelp(group, style) {
 	return lines(...listingLines(group.commandLine, group, style));
@@ -8765,12 +9104,13 @@ function errorsData(errors) {
 		details: declaration.details === void 0 ? null : toJSONSchema(declaration.details, { unrepresentable: "any" })
 	}]));
 }
-function cliHelpJson({ version, description, errors }, root) {
+function cliHelpJson({ name, version, description, errors }, root) {
 	return printed$1({
-		name: root.commandLine,
+		name,
 		version,
 		description,
 		...nodeData(root),
+		name,
 		errors: errorsData(errors ?? {})
 	});
 }
@@ -8798,7 +9138,14 @@ function printed(value, render, { json, invocation, style, fields }) {
 }
 /** A progress message as stderr carries it: one JSON object per line under `--json` (ADR 0006). */
 function progressLine(message, json) {
-	return json ? `${JSON.stringify({ progress: message })}\n` : `${message}\n`;
+	return stderrLine("progress", message, json);
+}
+/** A Notice as stderr carries it, a JSON line like progress under `--json`. */
+function noticeLine(text, json) {
+	return stderrLine("notice", text, json);
+}
+function stderrLine(key, text, json) {
+	return json ? `${JSON.stringify({ [key]: text })}\n` : `${text}\n`;
 }
 function errorText(error, format) {
 	const text = formatRuntimeError(error, {
@@ -8819,7 +9166,7 @@ function startedOutput(outcome, format, spill) {
 		fields: void 0
 	}, spill);
 }
-/** A serve Command stopped after it started: stopping it is how it is meant to end. */
+/** A serve Command stopped, or ended itself, after it started: that is how it is meant to end. */
 const STOPPED_RESULT = {
 	stdout: "",
 	stderr: "",
@@ -9045,16 +9392,26 @@ function dryRunOutcome(command, plan) {
 		].join("\n")
 	};
 }
+function serveContextOf(ctx, end) {
+	const serveCtx = Object.create(ctx);
+	return Object.assign(serveCtx, { end });
+}
 async function execute(command, input, ctx, { dryRun, confirm, yes, page, invocation, commandLine, started, files, guardOutputs }) {
-	await checkTools(command.tools ?? [], ctx.env);
+	await checkTools(command.tools ?? [], ctx.env, ctx.commandLine());
 	if (command.rows !== void 0) return outcomeOf(await command.run({
 		...input,
 		...page
 	}, ctx), (data, style) => command.render(data, style));
 	if (command.effect === "read") return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
 	if (command.effect === "serve") {
-		await started(outcomeOf(await command.start(input, ctx), (value, style) => command.render(value, style)));
-		return untilAborted(ctx.signal);
+		let end = () => {};
+		const ended = new Promise((resolve) => {
+			end = resolve;
+		});
+		const outcome = outcomeOf(await command.start(input, serveContextOf(ctx, end)), (value, style) => command.render(value, style));
+		await started(outcome);
+		await Promise.race([ended, untilAborted(ctx.signal)]);
+		return outcome;
 	}
 	const plan = await command.plan(input, ctx);
 	if (dryRun) return dryRunOutcome(command, plan);
@@ -9396,12 +9753,19 @@ function selfOf(name, bin) {
 		bin
 	];
 }
+const unfakedSpawnDetached = async () => {
+	throw new Error("runCli was given a fake spawn but no spawnDetached: pass spawnDetached to runCli, so the test starts no real child");
+};
+function spawnDetachedOf({ spawn, spawnDetached }) {
+	if (spawnDetached !== void 0) return spawnDetached;
+	return spawn === void 0 ? realSpawnDetached : unfakedSpawnDetached;
+}
 function portsOf(cli, replacement) {
 	if (replacement !== void 0) return () => replacement;
 	return cli.ports ?? (() => ({}));
 }
 function portsBaseOf(scope, signal) {
-	const { cli, options, packageRoot, progress, fileError, clock, files } = scope;
+	const { cli, options, packageRoot, progress, fileError, callerLine, clock, files } = scope;
 	const { cwd, env } = options;
 	const envFile = envFileOf(cli.name, env);
 	return {
@@ -9426,11 +9790,22 @@ function portsBaseOf(scope, signal) {
 			cwd,
 			env,
 			signal
-		}, fileError)
+		}, {
+			fileError,
+			callerLine
+		}),
+		spawnDetached: contextSpawnDetached(spawnDetachedOf(options), {
+			cwd,
+			env,
+			signal
+		}, {
+			fileError,
+			callerLine
+		})
 	};
 }
 function contextOf(portsBase, control, parts) {
-	const { ports, project, force, commandLine, deliver } = parts;
+	const { ports, project, force, commandLine, deliver, notice } = parts;
 	return {
 		...portsBase,
 		deadline: (ms) => control.deadline(ms),
@@ -9443,7 +9818,8 @@ function contextOf(portsBase, control, parts) {
 		force,
 		commandLine,
 		poll: (check, { intervalMs, signal: stop }) => poll(portsBase.clock, check, intervalMs, stop === void 0 ? control.signal : AbortSignal.any([control.signal, stop])),
-		deliver
+		deliver,
+		notice
 	};
 }
 /** Leaves the Side task running, so the caller writes the result before it waits for it. */
@@ -9462,8 +9838,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		flags: knownFlags(routed.spec),
 		stdinArg: stdinArgOf(routed)
 	};
+	const typedLine = (change) => commandLineOf(invocation, change);
+	const rerunLine = typedLine();
 	const fileError = fileErrorOf({
-		callerLine: commandLineOf(invocation),
+		callerLine: rerunLine,
 		env,
 		platform
 	});
@@ -9473,20 +9851,20 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		json: routed.json,
 		invocation
 	};
-	const typedLine = (change) => commandLineOf(invocation, change);
-	const callerLine = commandLineOf({
+	const pipedLine = commandLineOf({
 		...invocation,
 		stdinArg: void 0
 	});
 	let resumeHint;
 	const control = new RunControl({
 		commandLine,
+		callerLine: rerunLine,
 		outer: options.signal,
 		clock,
 		progress,
 		runDeadline: command.deadline === void 0 ? void 0 : {
 			ms: command.deadline.ms,
-			hint: () => resumeHint ?? stdinNeverEndedHint(callerLine)
+			hint: () => resumeHint ?? stdinNeverEndedHint(pipedLine)
 		}
 	});
 	const failed = (error, finishSideTask) => {
@@ -9503,7 +9881,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			if (isTerminal(stdin)) progress(readingLine(field.name, platform));
 			return readStdin(stdin, control.signal, {
 				clock,
-				stalled: () => stdinStalled(callerLine)
+				stalled: () => stdinStalled(pipedLine)
 			});
 		});
 	} catch (error) {
@@ -9521,6 +9899,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		packageRoot,
 		progress,
 		fileError,
+		callerLine: rerunLine,
 		clock,
 		files: outputs.files
 	};
@@ -9544,7 +9923,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	});
 	let project;
 	try {
-		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, fileError);
+		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, {
+			fileError,
+			callerLine: rerunLine
+		});
 	} catch (error) {
 		return failed(error, finishSideTask);
 	}
@@ -9554,6 +9936,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		project,
 		force: flags.force,
 		commandLine: typedLine,
+		notice: (text) => write.stderr(noticeLine(text, routed.json)),
 		deliver: (data) => {
 			delivered = deliveredOutcome(command, data);
 		}
@@ -9569,22 +9952,27 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	let served = false;
 	let settled;
 	try {
+		const outcome = await control.settle(execute(command, input, ctx, {
+			dryRun: flags.dryRun,
+			confirm: flags.confirm,
+			yes: flags.yes,
+			page: flags.page,
+			invocation,
+			commandLine,
+			started: async (outcome) => {
+				write.stdout(await startedOutput(outcome, format, spill));
+				served = true;
+			},
+			files,
+			guardOutputs: outputs.guard
+		}));
+		if (served) return {
+			result: STOPPED_RESULT,
+			finishSideTask
+		};
 		settled = {
 			ok: true,
-			outcome: await control.settle(execute(command, input, ctx, {
-				dryRun: flags.dryRun,
-				confirm: flags.confirm,
-				yes: flags.yes,
-				page: flags.page,
-				invocation,
-				commandLine,
-				started: async (outcome) => {
-					write.stdout(await startedOutput(outcome, format, spill));
-					served = true;
-				},
-				files,
-				guardOutputs: outputs.guard
-			}))
+			outcome
 		};
 	} catch (error) {
 		if (served && control.signal.aborted) return {
@@ -9676,12 +10064,13 @@ async function runWithProgress(cli, argv, options, write, stopNotice) {
 	return result;
 }
 async function routeAndRun(cli, argv, options, write, stopNotice) {
+	const runAs = runAsOf(cli);
 	const format = {
 		cliName: cli.name,
 		env: options.env,
 		style: styleFor(options.env, options.stdoutIsTTY === true),
 		invocation: {
-			cliName: cli.name,
+			runAs,
 			argv,
 			flags: []
 		},
@@ -9690,9 +10079,9 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 		stop: options.signal
 	};
 	const root = cli.commands === void 0 ? {
-		...commandSpec(cli.name, cli.command),
+		...commandSpec(runAs, cli.command),
 		description: cli.description
-	} : groupSpec(cli.name, cli.commands, builtInCommands(cli, {
+	} : groupSpec(runAs, cli.commands, builtInCommands(cli, {
 		bin: options.bin,
 		node: options.node
 	}));
@@ -9759,16 +10148,131 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.13.0";
+var version$1 = "0.14.0";
 var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "1c3a29e",
+	"sha": "f114cf0",
 	"dirty": false,
-	"builtAt": "2026-10-23T05:43:49.000Z"
+	"builtAt": "2026-10-27T02:06:04.000Z"
 };
 //#endregion
+//#region src/fill.ts
+/** `text` with each `{{key}}` replaced by its value; `quoted` escapes values that land inside a double-quoted string. */
+function fill(text, values, quoted) {
+	return text.replaceAll(/\{\{(\w+)\}\}/g, (placeholder, key) => {
+		const value = Object.hasOwn(values, key) ? values[key] : void 0;
+		if (value === void 0) throw new Error(`template placeholder ${placeholder} has no value`);
+		return quoted ? JSON.stringify(value).slice(1, -1) : value;
+	});
+}
+//#endregion
+//#region src/install-mode.ts
+const PARTIALS_DIR = fileURLToPath(new URL("../partials/", import.meta.url));
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const COMMANDS_ANCHOR = "  commands: {";
+const GLOBAL_INSTALL = `  install: {
+    mode: "global",
+    package: manifest.name,
+    registry: manifest.publishConfig.registry,
+  },
+`;
+const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, then put here the `! npx -y skills add` line that `node dist/bin.js doctor` gives as the `skill` row's fix. -->";
+function installModeOf(skillHub, dependency, binName) {
+	if (skillHub !== void 0 && dependency) throw new UsageError({
+		code: "SKILL_HOMES_CONFLICT",
+		message: "--skill-hub and --dependency each name where the skill comes from: a Dependency install ships it inside the package",
+		hint: "pass --dependency for a CLI each project pins, or --skill-hub for a global one whose skill each release commits to a Skill Hub"
+	});
+	if ((skillHub !== void 0 || dependency) && !SKILL_NAME.test(binName)) throw new UsageError({
+		code: "SKILL_NAME_INVALID",
+		message: `${binName} cannot name a skill, whose names are lowercase letters, digits and single hyphens`,
+		hint: `choose a name such as my-cli, or leave out ${dependency ? "--dependency" : "--skill-hub"}`
+	});
+	return dependency ? { mode: "dependency" } : {
+		mode: "global",
+		skillHub
+	};
+}
+async function partialsOf(mode, values) {
+	const partial = async (name) => fill(await readFile(join(PARTIALS_DIR, mode, `${name}.md`), "utf8"), values, false).trimEnd();
+	const [installLines, skillCheck, installSteps, updateSteps, sandbox] = await Promise.all([
+		partial("installLines"),
+		partial("skillCheck"),
+		partial("installSteps"),
+		partial("updateSteps"),
+		partial("sandbox")
+	]);
+	return {
+		installLines,
+		skillCheck,
+		installSteps,
+		updateSteps,
+		sandbox
+	};
+}
+async function globalSetup(skillHub, packageName, binName) {
+	const skillLine = skillHub === void 0 ? NO_SKILL_HUB : `\`! npx -y skills add ${skillHub} --skill ${binName} -g\``;
+	const runAs = runAsOf({ name: binName });
+	const url = JSON.stringify(skillHub);
+	return {
+		values: {
+			runAs,
+			doctorBin: "",
+			...await partialsOf("global", {
+				packageName,
+				binName,
+				runAs,
+				skillLine
+			})
+		},
+		edits: skillHub === void 0 ? [] : [{
+			file: "src/cli.ts",
+			find: COMMANDS_ANCHOR,
+			replace: `  skill: { source: ${url} },\n${COMMANDS_ANCHOR}`
+		}, {
+			file: "scripts/release.ts",
+			find: "  smoke: {",
+			replace: `  skillHub: ${url},\n  smoke: {`
+		}],
+		files: []
+	};
+}
+async function dependencySetup(packageName, binName) {
+	const runAs = runAsOf({
+		name: binName,
+		install: {
+			mode: "dependency",
+			package: packageName
+		}
+	});
+	return {
+		values: {
+			runAs,
+			doctorBin: "src/bin.ts",
+			...await partialsOf("dependency", {
+				packageName,
+				binName,
+				runAs
+			})
+		},
+		edits: [{
+			file: "src/cli.ts",
+			find: GLOBAL_INSTALL,
+			replace: `  install: { mode: "dependency", package: manifest.name },\n`
+		}, {
+			file: "src/cli.ts",
+			find: COMMANDS_ANCHOR,
+			replace: `  skill: { packaged: "skills/${binName}" },\n${COMMANDS_ANCHOR}`
+		}],
+		files: ["skills"]
+	};
+}
+async function installSetupOf(install, packageName, binName) {
+	return install.mode === "global" ? globalSetup(install.skillHub, packageName, binName) : dependencySetup(packageName, binName);
+}
+//#endregion
 //#region src/steps.ts
 const stepErrors = defineErrors({ STEP_FAILED: { class: "operator" } });
 const INSTALL = [{
@@ -9878,13 +10382,6 @@ async function templateFiles(values) {
 	}));
 }
 const QUOTED_EXTENSIONS = /* @__PURE__ */ new Set([".json", ".ts"]);
-function fill(text, values, quoted) {
-	return text.replaceAll(/\{\{(\w+)\}\}/g, (placeholder, key) => {
-		if (!Object.hasOwn(values, key)) throw new Error(`template placeholder ${placeholder} has no value`);
-		const value = values[key];
-		return quoted ? JSON.stringify(value).slice(1, -1) : value;
-	});
-}
 async function writeTemplate(root, files, values) {
 	for (const file of files) {
 		const text = await readFile(join(TEMPLATE_DIR, file.source), "utf8");
@@ -9900,17 +10397,6 @@ const version = version$1;
 //#region src/create.ts
 const { defineCommand } = agentCli();
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?([a-z0-9][a-z0-9._-]*)$/;
-const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, then put here the `! npx -y skills add` line that `node dist/bin.js doctor` gives as the `skill` row's fix. -->";
-const SKILL_HUB_ANCHORS = [{
-	file: "src/cli.ts",
-	before: "  commands: {",
-	line: (hub) => `  skill: { source: ${JSON.stringify(hub)} },\n`
-}, {
-	file: "scripts/release.ts",
-	before: "  smoke: {",
-	line: (hub) => `  skillHub: ${JSON.stringify(hub)},\n`
-}];
 function errorCode(error) {
 	return error instanceof Error && "code" in error ? error.code : void 0;
 }
@@ -9923,30 +10409,24 @@ async function isFree(path) {
 		throw error;
 	}
 }
-function skillInstallLine(skillHub, binName) {
-	return skillHub === void 0 ? NO_SKILL_HUB : `\`! npx -y skills add ${skillHub} --skill ${binName} -g\``;
-}
-async function setSkillHub(root, skillHub) {
-	for (const { file, before, line } of SKILL_HUB_ANCHORS) {
-		const path = join(root, file);
-		const text = await readFile(path, "utf8");
-		if (!text.includes(before)) throw new Error(`the template's ${file} has no \`${before}\` line to put the Skill Hub before`);
-		await writeFile(path, text.replace(before, `${line(skillHub)}${before}`));
-	}
+async function applyEdit(root, { file, find, replace }) {
+	const path = join(root, file);
+	const text = await readFile(path, "utf8");
+	if (!text.includes(find)) throw new Error(`the template's ${file} has no \`${find.trim()}\` to replace`);
+	await writeFile(path, text.replace(find, replace));
 }
 const MANIFEST = record(string(), unknown());
-async function setRepository(root, repository) {
+async function editManifest(root, edit) {
 	const path = join(root, "package.json");
 	const manifest = MANIFEST.parse(JSON.parse(await readFile(path, "utf8")));
-	const entries = Object.entries(manifest).flatMap((entry) => entry[0] === "description" ? [entry, ["repository", repository]] : [entry]);
+	const entries = edit(Object.entries(manifest));
 	await writeFile(path, `${JSON.stringify(Object.fromEntries(entries), null, 2)}\n`);
 }
-function ensureSkillName(binName) {
-	if (!SKILL_NAME.test(binName)) throw new UsageError({
-		code: "SKILL_NAME_INVALID",
-		message: `${binName} cannot name a skill in a Skill Hub, whose names are lowercase letters, digits and single hyphens`,
-		hint: "choose a name such as my-cli, or leave out --skill-hub"
-	});
+async function setRepository(root, repository) {
+	await editManifest(root, (entries) => entries.flatMap((entry) => entry[0] === "description" ? [entry, ["repository", repository]] : [entry]));
+}
+async function addFiles(root, files) {
+	await editManifest(root, (entries) => entries.map(([key, value]) => key === "files" && Array.isArray(value) ? [key, [...value, ...files]] : [key, value]));
 }
 async function ensureFree(path) {
 	if (!await isFree(path)) throw new UsageError({
@@ -9969,20 +10449,22 @@ const create = defineCommand({
 		install: boolean().default(true).describe("run pnpm install"),
 		git: boolean().default(true).describe("create a git repository with an initial commit"),
 		repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository"),
-		skillHub: url({ protocol: /^https$/ }).refine((url) => new URL(url).search === "" && new URL(url).hash === "", "must name the hub's repository with no query or fragment").refine((url) => new URL(url).pathname.endsWith(".git"), "must end in .git").optional().describe("the https git URL of the Skill Hub each release commits the CLI's skill to")
+		skillHub: url({ protocol: /^https$/ }).refine((url) => new URL(url).search === "" && new URL(url).hash === "", "must name the hub's repository with no query or fragment").refine((url) => new URL(url).pathname.endsWith(".git"), "must end in .git").optional().describe("the https git URL of the Skill Hub each release commits the CLI's skill to"),
+		dependency: boolean().default(false).describe("install the CLI per project, as a devDependency, with its skill shipped inside the package")
 	}),
-	plan: async ({ name, description, install, git, repository, skillHub }, ctx) => {
+	plan: async ({ name, description, install, git, repository, skillHub, dependency }, ctx) => {
 		const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
-		if (skillHub !== void 0) ensureSkillName(binName);
+		const mode = installModeOf(skillHub, dependency, binName);
 		const path = resolve(ctx.cwd, binName);
 		await ensureFree(path);
+		const setup = await installSetupOf(mode, name, binName);
 		const values = {
 			packageName: name,
 			binName,
 			description,
 			debugVariable: debugVariable(binName),
 			runtimeVersion: version,
-			skillInstall: skillInstallLine(skillHub, binName)
+			...setup.values
 		};
 		return {
 			path,
@@ -9994,14 +10476,16 @@ const create = defineCommand({
 			}),
 			install,
 			repository,
-			skillHub
+			edits: setup.edits,
+			manifestFiles: setup.files
 		};
 	},
 	apply: async (plan, ctx) => {
 		await mkdir(plan.path, { recursive: true });
 		await writeTemplate(plan.path, plan.files, plan.values);
 		if (plan.repository !== void 0) await setRepository(plan.path, plan.repository);
-		if (plan.skillHub !== void 0) await setSkillHub(plan.path, plan.skillHub);
+		for (const edit of plan.edits) await applyEdit(plan.path, edit);
+		if (plan.manifestFiles.length > 0) await addFiles(plan.path, plan.manifestFiles);
 		await runSteps(plan.steps, plan.path, ctx);
 		return {
 			path: plan.path,