@duyquangnvx/create-agent-cli 0.22.0 → 0.24.0

package/dist/bin.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
+import { basename, delimiter, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { spawn } from "node:child_process";
 import { constants, homedir, tmpdir } from "node:os";
 import { parseArgs, parseEnv } from "node:util";
 import { constants as constants$1, existsSync, readFileSync, realpathSync } from "node:fs";
 import { access, chmod, link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 //#region ../../node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/core/util.js
@@ -5959,8 +5959,12 @@ async function orMissing(pending) {
 function isNothingThere(error) {
 	return isMissingFile(error) || errnoOf(error) === "ENOTDIR";
 }
+/** The CLI's own environment variable, such as `TOOL_DEBUG` for `cliVariable("tool", "DEBUG")`. */
+function cliVariable(cliName, suffix) {
+	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_${suffix}`;
+}
 function debugVariable(cliName) {
-	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
+	return cliVariable(cliName, "DEBUG");
 }
 function messageOf(error) {
 	return error instanceof Error ? error.message : String(error);
@@ -7081,9 +7085,9 @@ function secretRows(secrets, commands) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "4664298",
+		"sha": "45caa4e",
 		"dirty": false,
-		"builtAt": "2026-11-02T04:03:08.000Z"
+		"builtAt": "2026-11-05T07:43:22.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -7233,6 +7237,16 @@ function installCommandLine(registry, version = "latest") {
 		...registry.flags
 	].join(" ");
 }
+/** The line that sets a Global install up, run before the CLI is on the machine. */
+function setupCommandLine({ package: name, flags }) {
+	return [
+		"npx",
+		"-y",
+		...flags,
+		`${name}@latest`,
+		"setup"
+	].join(" ");
+}
 function npmOf(ctx, windows) {
 	const beside = ctx.node === void 0 ? void 0 : join(dirname(ctx.node), windows ? "npm.cmd" : "npm");
 	if (beside === void 0 || !existsSync(beside)) return {
@@ -7276,13 +7290,13 @@ function failureOf(call, answer, ctx) {
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
 	const next = [ctx.rerun];
-	if (code !== void 0 && NETWORK_CODES.has(code)) return new CliError({
+	if (code !== void 0 && NETWORK_CODES.has(code)) return runtimeError({
 		code: REGISTRY_UNREACHABLE,
 		message: `npm could not reach ${registry} (${code})${output}`,
 		hint: `${unreachableHint}, then ${RUN_AGAIN}`,
 		next
 	});
-	if (code !== void 0 && AUTH_CODES.has(code)) return new CliError({
+	if (code !== void 0 && AUTH_CODES.has(code)) return runtimeError({
 		code: REGISTRY_AUTH,
 		message: `${registry} refused npm's credentials (${code})${output}`,
 		hint: authHint(code, ctx),
@@ -7295,7 +7309,7 @@ function failureOf(call, answer, ctx) {
 		hint: `fix what npm reports, then ${RUN_AGAIN} with the first Next step, or install it yourself with the second`,
 		next: [...next, wholeLine(installCommandLine(ctx.registry))]
 	});
-	return new CliError({
+	return runtimeError({
 		code: NPM_FAILED,
 		message: `npm ${call} failed with exit code ${answer.exitCode}${output}`,
 		hint: `fix what npm reports, then ${RUN_AGAIN}`,
@@ -7361,15 +7375,18 @@ async function installGlobally(version, ctx) {
 		...ctx.registry.flags
 	], ctx, null);
 }
-async function latestVersion(ctx) {
-	const { package: name, label: registry, flags } = ctx.registry;
-	const answer = await runNpm("view", [
+function latestViewArgs({ package: name, flags }) {
+	return [
 		"view",
 		`${name}@latest`,
 		"version",
 		"--json",
 		...flags
-	], ctx);
+	];
+}
+async function latestVersion(ctx) {
+	const { package: name, label: registry } = ctx.registry;
+	const answer = await runNpm("view", latestViewArgs(ctx.registry), ctx);
 	const version = versionInViewAnswer(answer);
 	if (version === void 0) throw noLatest(ctx, `npm answered no version for ${name}@latest on ${registry}: ${answer.trim()}`);
 	return version;
@@ -7611,184 +7628,8 @@ function dependencyInstall(cli, install) {
 		runAs,
 		builtIns: () => ({}),
 		exitClasses: [],
-		check: (launch) => checkOf$1(cli, install, runAs, launch)
-	};
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/skill/hub.js
-const SKILL_DIRS = [[".claude", "skills"], [".agents", "skills"]];
-const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
-const METADATA_VERSION = /^metadata:[ \t]*\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$/m;
-/** The version a SKILL.md's frontmatter `metadata.version` states. */
-function skillVersionIn(skill) {
-	const frontmatter = FRONTMATTER.exec(skill)?.[1];
-	return frontmatter === void 0 ? void 0 : METADATA_VERSION.exec(`${frontmatter}\n`)?.[1];
-}
-function homeOf(env) {
-	return env.HOME ?? env.USERPROFILE ?? homedir();
-}
-async function copyAt(path, version) {
-	let skill;
-	try {
-		skill = await readFile(join(path, "SKILL.md"), "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return;
-		return {
-			path,
-			version: void 0,
-			state: "unreadable"
-		};
-	}
-	const stated = skillVersionIn(skill);
-	if (stated === void 0 || !isVersion(stated) || !isVersion(version)) return {
-		path,
-		version: stated,
-		state: "unversioned"
-	};
-	return {
-		path,
-		version: stated,
-		state: standingOf$1(stated, version)
-	};
-}
-async function skillCopies(cliName, version, { cwd, env }) {
-	const paths = [cwd, homeOf(env)].flatMap((root) => SKILL_DIRS.map((dir) => join(root, ...dir, cliName)));
-	const seen = /* @__PURE__ */ new Set();
-	const copies = [];
-	for (const path of paths) {
-		const copy = await copyAt(path, version);
-		const real = copy === void 0 ? void 0 : await realpath(path);
-		if (copy !== void 0 && real !== void 0 && !seen.has(real)) {
-			seen.add(real);
-			copies.push(copy);
-		}
-	}
-	return copies;
-}
-const has = (copies, wanted) => copies.some(({ state }) => state === wanted);
-function addLineOf(cliName, from) {
-	return "add" in from ? from.add : `npx -y skills add ${from.source} --skill ${cliName} -g`;
-}
-function fixFor(cliName, copies, from) {
-	const update = `npx -y skills update ${cliName}`;
-	const add = from === void 0 ? void 0 : addLineOf(cliName, from);
-	if (copies.length === 0) return add;
-	if (has(copies, "unversioned") && add !== void 0) return has(copies, "behind") ? `${update} && ${add}` : add;
-	return has(copies, "behind") || has(copies, "unversioned") ? update : void 0;
-}
-const SKILL_STATE_NOTES = {
-	current: "the same as this build",
-	behind: "older than this build",
-	ahead: "newer than this build",
-	unversioned: "states no metadata.version",
-	unreadable: "could not be read"
-};
-function describeCopy({ path, version, state }) {
-	return `${path}${version === void 0 ? "" : ` ${version}`} (${SKILL_STATE_NOTES[state]})`;
-}
-/** A skill on a Skill Hub, which `from` says how to install; without it, no line adds it. */
-function hubSkill(cli, from) {
-	const findingOf = (copies) => {
-		const fix = fixFor(cli.name, copies, from);
-		const message = copies.length === 0 ? `no copy of the ${cli.name} skill is installed` : copies.map(describeCopy).join("; ");
-		return fix === void 0 ? {
-			state: "ok",
-			message
-		} : {
-			state: "ok",
-			message,
-			fix
-		};
-	};
-	return {
-		kind: "hub",
-		builtIns: {},
-		rows: [{
-			name: "skill",
-			advisory: true,
-			run: async (ctx) => findingOf(await skillCopies(cli.name, cli.version, ctx))
-		}],
-		notice: async () => {},
-		differing: async (place) => (await skillCopies(cli.name, cli.version, place)).filter(({ state }) => state !== "current" && state !== "unreadable").map(describeCopy),
-		nextAt: async (version, ctx) => {
-			const copies = await skillCopies(cli.name, version, ctx);
-			const fix = fixFor(cli.name, copies, from);
-			return fix === void 0 ? [] : [fix];
-		}
-	};
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/agents-md.js
-function markersOf(name) {
-	return {
-		begin: `<!-- BEGIN:${name} -->`,
-		end: `<!-- END:${name} -->`
-	};
-}
-/** `text` with the CLI's Agents section between its markers, appended when they are missing; nothing else changes. */
-function withSection({ name, text: section }, text) {
-	const { begin, end } = markersOf(name);
-	const whole = `${begin}\n${section}\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`;
-}
-async function agentsMdAt(agents, root) {
-	const path = join(root, "AGENTS.md");
-	const existing = await orMissing(readFile(path, "utf8"));
-	if (existing === void 0) return {
-		path,
-		agents,
-		change: "create"
-	};
-	if (withSection(agents, existing) === existing) return {
-		path,
-		agents,
-		change: null
-	};
-	return {
-		path,
-		agents,
-		change: existing.includes(markersOf(agents.name).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`];
-}
-function agentsRow(agents, install) {
-	const { name } = agents;
-	return {
-		name: "agents",
-		advisory: true,
-		run: async (ctx) => {
-			const root = await projectRootOf(ctx.cwd);
-			const { path, change } = await agentsMdAt(agents, root);
-			const fix = `${install.runAs} skill install`;
-			if (change === "rewrite") return {
-				state: "problem",
-				message: `${path} holds a ${name} Agents section other than the one ${fix} writes`,
-				fix
-			};
-			if (change !== null) return {
-				state: "problem",
-				message: `${path} holds no ${name} Agents section, so sessions in this repo do not know ${name}`,
-				fix
-			};
-			const holds = `${path} holds the ${name} Agents section`;
-			const [edit] = await handEditsAt(root);
-			return edit === void 0 ? {
-				state: "ok",
-				message: holds
-			} : {
-				state: "problem",
-				message: `${holds}; ${edit}`
-			};
-		}
+		check: (launch) => checkOf$1(cli, install, runAs, launch),
+		notice: async () => {}
 	};
 }
 //#endregion
@@ -7854,259 +7695,208 @@ function classifyErrno(error, context) {
 	}
 }
 //#endregion
-//#region ../agent-cli/dist/context/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`);
+//#region ../agent-cli/dist/context/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(rerun) {
+	return new CliError({
+		code: INTERRUPTED,
+		message: "interrupted before it finished",
+		hint: "to finish it, run the Next step, unless it was stopped on purpose; if a tool timeout stopped it, give it longer",
+		next: [rerun]
+	});
 }
-function isAlive(pid) {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return errnoOf(error) === "EPERM";
-	}
+const BOUND_WORDS = {
+	deadline: "deadline",
+	ignoreStop: "timeout"
+};
+function waitHint(bound) {
+	return bound === "ignoreStop" ? "the call may have been billed: ask your user before running the Next step" : "run the Next step later, when the service it waits on may answer faster";
 }
-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));
+function deadlineError(commandLine, ms, advice, bound = "deadline") {
+	return new CliError({
+		code: DEADLINE_EXCEEDED,
+		message: `${commandLine} ran past its ${ms} ms ${BOUND_WORDS[bound]}`,
+		...advice
 	});
-	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 function writeWithMode(path, data, mode) {
-	if (mode === void 0) {
-		await writeFile(path, data);
-		return;
+/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
+var RunControl = class {
+	signal;
+	#controller = new AbortController();
+	#commandLine;
+	#rerun;
+	#outer;
+	#onOuterAbort = () => this.#controller.abort(interruptedError(this.#rerun));
+	/** 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 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, rerun, outer, clock, progress, runDeadline }) {
+		this.#commandLine = commandLine;
+		this.#rerun = rerun;
+		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, advice } = runDeadline;
+			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, advice())));
+		}
 	}
-	await writeFile(path, data, { mode });
-	await chmod(path, mode);
-}
-/** 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);
+	deadline(ms, options = {}) {
+		return options.ignoreStop === true ? this.#abortsAfter(ms, "ignoreStop") : AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
 	}
-}
-/** 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;
+	#abortsAfter(ms, bound) {
+		const controller = new AbortController();
+		after(this.#clock, ms, this.#disposed.signal, () => {
+			const advice = {
+				hint: waitHint(bound),
+				next: [this.#rerun]
+			};
+			const reason = deadlineError(this.#commandLine, ms, advice, bound);
+			this.#abortReasons.add(reason);
+			controller.abort(reason);
+		});
+		return controller.signal;
 	}
-	await handle.close();
-}
-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);
-	}
-}
-/** 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 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();
 		}
-	};
-}
-/**
-* `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);
+	}
+	/** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
+	async settle(work) {
 		try {
-			return await work(target);
-		} catch (error) {
-			throw fileError(error, {
-				path: target,
-				access
-			});
+			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();
 		}
 	}
-	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))
-	};
-}
+	/**
+	* 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 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/context/outputs.js
-const OUTPUT_EXISTS = "OUTPUT_EXISTS";
-/** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
-async function checkOutputs({ rerun, 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: `once the user agrees to replace ${them}, run the Next step`,
-		next: [rerun({ add: [FORCE_FLAG.flag] })]
+//#region ../agent-cli/dist/built-ins/install/global-npm.js
+const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
+/** Where npm puts global packages under its global prefix. */
+function globalModulesDir(prefix) {
+	return process.platform === "win32" ? join(prefix, "node_modules") : join(prefix, "lib", "node_modules");
+}
+function notGlobal(ctx, message) {
+	return runtimeError({
+		code: NOT_GLOBAL_INSTALL,
+		message,
+		hint: "install it by running the Next step, so its update Command can replace it",
+		next: [wholeLine(setupCommandLine(ctx.registry))]
 	});
 }
-/** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
-function outputsGuard(files, cwd) {
-	const unwritten = /* @__PURE__ */ new Set();
-	let forceStep = [];
-	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: "once the user agrees to replace it, run the Next step",
-				next: [forceStep]
-			}, { cause: error });
-		}
-	};
+/**
+* The global npm install this copy runs from, found by asking npm for its global prefix.
+* `bin` is the script that started the CLI; throws `NOT_GLOBAL_INSTALL` when it is not inside that install.
+*/
+async function globalInstallOf(bin, ctx) {
+	if (bin === void 0) throw notGlobal(ctx, `${ctx.cliName} runs from source, not from an npm install`);
+	const prefix = await globalPrefix(ctx);
+	const packageDir = join(globalModulesDir(prefix), ctx.registry.package);
+	const installed = await orMissing(realpath(packageDir));
+	const here = await orMissing(realpath(bin)) ?? bin;
+	if (installed === void 0 || !isInside(installed, here)) throw notGlobal(ctx, `${ctx.cliName} runs from ${here}, not from npm's global install at ${packageDir}`);
+	if ((await lstat(packageDir)).isSymbolicLink()) throw notGlobal(ctx, `${ctx.cliName} runs from a link to ${installed} (npm link), not from an npm install`);
 	return {
-		files: {
-			...files,
-			write: (path, data, options) => unwritten.has(resolve(cwd, path)) ? exclusiveWrite(path, data, options) : files.write(path, data, options)
-		},
-		guard: (outputs, step) => {
-			forceStep = step;
-			for (const path of outputs) unwritten.add(resolve(cwd, path));
-		}
+		prefix,
+		packageDir
 	};
 }
-/**
-* 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"
-			});
-		}
-	}));
+const NPMJS = "https://registry.npmjs.org/";
+/** The flag that points npm at the CLI's registry; none for npmjs, npm's default. */
+function registryFlags({ package: name, registry }) {
+	if (registry === NPMJS) return [];
+	const scope = scopeOf(name);
+	return [scope === void 0 ? `--registry=${registry}` : `--${scope}:registry=${registry}`];
 }
-//#endregion
-//#region ../agent-cli/dist/built-ins/skill/install-command.js
-/** The project root and the Skill copy under it, as `skill install` writes it. */
-async function skillCopyOf(cli, cwd) {
-	const root = await projectRootOf(cwd);
+/** The line that sets a Global install up, run before the CLI is on the machine. */
+function setupLineOf(install) {
+	return setupCommandLine(globalRegistry(install));
+}
+function globalRegistry(install) {
+	const { package: name, registry } = install;
 	return {
-		root,
-		copy: join(root, ".claude", "skills", cli.name)
+		package: name,
+		label: registry,
+		flags: registryFlags(install),
+		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}`
 	};
 }
+/** npm for a Global install, run in the working directory. */
+function globalNpm(cli, install, ctx, node) {
+	return npmContext(cli, globalRegistry(install), ctx, node, ctx.cwd);
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/skill/sync.js
 /** Every file under `dir`, relative to it and sorted; none when `dir` is missing. */
 async function filesIn(dir) {
 	return (await orMissing(readdir(dir, {
@@ -8114,34 +7904,11 @@ async function filesIn(dir) {
 		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
-	};
-}
-const installSchema = object({
-	copy: string(),
-	written: array(string()),
-	removed: array(string()),
-	agentsMd: object({
-		path: string(),
-		changed: boolean()
-	}).nullable(),
-	handEdits: array(string())
-});
 async function sameContent(left, right) {
 	const [a, b] = await Promise.all([readFile(left), readFile(right)]);
 	return a.equals(b);
 }
-async function planOf(cli, folder, agents, cwd, packageRoot) {
-	const source = join(packageRoot, folder);
-	const { root, copy } = await skillCopyOf(cli, cwd);
+async function syncOf(source, copy) {
 	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))));
 	return {
@@ -8149,604 +7916,1000 @@ async function planOf(cli, folder, agents, cwd, packageRoot) {
 		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: agents === void 0 ? null : await agentsMdAt(agents, root),
-		handEdits: agents === void 0 ? [] : await handEditsAt(root)
+		remove: present.filter((file) => !shipped.includes(file))
+	};
+}
+async function applySync(sync, ctx) {
+	for (const file of [...sync.write, ...sync.replace]) await ctx.files.write(join(sync.copy, file), await readFile(join(sync.source, file)));
+	for (const file of sync.remove) await ctx.files.remove(join(sync.copy, file));
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/skill/home.js
+const SKILL_DIRS = [[".claude", "skills"], [".agents", "skills"]];
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+const METADATA_VERSION = /^metadata:[ \t]*\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$/m;
+/** The version a SKILL.md's frontmatter `metadata.version` states. */
+function skillVersionIn(skill) {
+	const frontmatter = FRONTMATTER.exec(skill)?.[1];
+	return frontmatter === void 0 ? void 0 : METADATA_VERSION.exec(`${frontmatter}\n`)?.[1];
+}
+/** How the row words a copy that states a version, which only a skill from before CLI docs does. */
+function statedVersionNote(version) {
+	return `states metadata.version ${version}: an older skill that CLI docs replace`;
+}
+function homeOf(env) {
+	return env.HOME ?? env.USERPROFILE ?? homedir();
+}
+/** The home folders of the Skill copy; the skills installer may have made one a link to the other. */
+async function homeCopiesOf(name, env) {
+	const paths = SKILL_DIRS.map((dir) => join(homeOf(env), ...dir, name));
+	const reals = await Promise.all(paths.map(async (path) => orMissing(realpath(path))));
+	return paths.filter((_path, index) => {
+		const real = reals[index];
+		return real === void 0 || reals.indexOf(real) === index;
+	});
+}
+const homeSyncSchema = object({
+	copies: array(string()),
+	written: array(string()),
+	removed: array(string())
+});
+/**
+* Makes each home Skill copy match the folder in the package at `packageDir`. Null when the CLI
+* declares no skill, or that package ships none, which must not empty a copy.
+*/
+async function syncHome(cli, packageDir, ctx) {
+	if (cli.skill === void 0) return null;
+	const source = join(packageDir, cli.skill.folder);
+	if ((await filesIn(source)).length === 0) return null;
+	const copies = await homeCopiesOf(cli.name, ctx.env);
+	const syncs = await Promise.all(copies.map((copy) => syncOf(source, copy)));
+	for (const sync of syncs) await applySync(sync, ctx);
+	return {
+		copies,
+		written: syncs.flatMap((sync) => [...sync.write, ...sync.replace]),
+		removed: syncs.flatMap((sync) => sync.remove)
+	};
+}
+/** What a dry run says of the copies, since the release's files may not be on disk yet. */
+function renderPlannedSync(name, copies) {
+	return copies.length === 0 ? [] : [`would make the ${name} skill at ${copies.join(", ")} match the release`];
+}
+function renderHomeSync(name, sync) {
+	if (sync === null) return [];
+	const at = sync.copies.join(", ");
+	return sync.written.length + sync.removed.length === 0 ? [`the ${name} skill at ${at} already matches the package`] : [`copied the ${name} skill to ${at}: wrote ${sync.written.length} files, removed ${sync.removed.length}`];
+}
+async function homeCopyAt(path) {
+	try {
+		return {
+			path,
+			state: "readable",
+			stated: skillVersionIn(await readFile(join(path, "SKILL.md"), "utf8"))
+		};
+	} catch (error) {
+		return {
+			path,
+			state: isMissingFile(error) ? "missing" : "unreadable"
+		};
+	}
+}
+function describeCopy(copy) {
+	if (copy.state === "missing") return `no copy at ${copy.path}`;
+	if (copy.state !== "readable") return `${copy.path} (could not be read)`;
+	return copy.stated === void 0 ? copy.path : `${copy.path} (${statedVersionNote(copy.stated)})`;
+}
+async function findingOf$1(cli, folder, install, ctx) {
+	const paths = await homeCopiesOf(cli.name, ctx.env);
+	const [copies, shipped] = await Promise.all([Promise.all(paths.map(homeCopyAt)), orMissing(readFile(join(ctx.packageRoot, folder, "SKILL.md"), "utf8"))]);
+	const message = copies.map(describeCopy).join("; ");
+	const shipsStated = shipped !== void 0 && skillVersionIn(shipped) !== void 0;
+	return copies.every((copy) => copy.state === "readable" && (copy.stated === void 0 || shipsStated)) ? {
+		state: "ok",
+		message
+	} : {
+		state: "problem",
+		message,
+		fix: `${install.runAs} setup`
+	};
+}
+/** A skill the package ships, which `setup` and `update` copy under home. */
+function homeSkill(cli, { folder }, install) {
+	return {
+		builtIns: {},
+		rows: [{
+			name: "skill",
+			advisory: true,
+			run: (ctx) => findingOf$1(cli, folder, install, ctx)
+		}]
+	};
+}
+//#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, ""));
+}
+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 {
+		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
+	} catch (error) {
+		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);
+}
+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}`;
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/setup.js
+const NOT_ON_PATH = "NOT_ON_PATH";
+const setupSchema = object({
+	version: string(),
+	prefix: string(),
+	installed: boolean(),
+	skill: homeSyncSchema.nullable(),
+	upgrades: array(upgradeSchema),
+	docs: string().nullable()
+});
+const installedManifest = object({ version: string() });
+async function versionAt(packageDir) {
+	const text = await orMissing(readFile(join(packageDir, "package.json"), "utf8"));
+	if (text === void 0) return null;
+	try {
+		const parsed = installedManifest.safeParse(JSON.parse(text));
+		return parsed.success ? parsed.data.version : null;
+	} catch (error) {
+		if (error instanceof SyntaxError) return null;
+		throw error;
+	}
+}
+function npmOfSetup(cli, install, ctx, node) {
+	return {
+		...globalNpm(cli, install, ctx, node),
+		rerun: wholeLine(setupLineOf(install))
 	};
 }
-const SECTION_VERBS = {
-	create: "create",
-	add: "add the Agents section to",
-	rewrite: "rewrite the Agents section 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 { agentsMd } = plan;
-	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,
-		...agentsMd === null ? [] : [agentsMd.change === null ? `${agentsMd.path} already holds the ${cli.name} Agents section` : `would ${SECTION_VERBS[agentsMd.change]} ${agentsMd.path}:\n${agentsMd.agents.text}`],
-		...plan.handEdits.map((edit) => `by hand: ${edit}`)
-	].join("\n");
+function needsInstall({ from, latest }) {
+	return from === null || standingOf$1(from, latest) === "behind";
 }
-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 === null ? [] : [agentsMd.changed ? `wrote the ${cli.name} Agents section in ${agentsMd.path}` : `${agentsMd.path} already holds the ${cli.name} Agents section`],
-		...data.handEdits.map((edit) => `by hand: ${edit}`)
-	].join("\n");
+function binDirOf(prefix) {
+	return process.platform === "win32" ? prefix : join(prefix, "bin");
 }
-function editedRemovals(plan, ctx) {
-	const them = plan.remove.length === 1 ? "it" : "them";
-	return new CliError({
-		code: OUTPUT_EXISTS,
-		message: `skill install would remove ${plan.remove.map((file) => join(plan.copy, file)).join(", ")}`,
-		hint: `once the user agrees to remove ${them}, run the Next step`,
-		next: [ctx.rerun({ add: [FORCE_FLAG.flag] })]
+async function canonical(path) {
+	return normalize(await realpath(path).catch(() => path));
+}
+async function assertOnPath(cli, prefix, node, ctx) {
+	const binDir = binDirOf(prefix);
+	const wanted = await canonical(binDir);
+	const entries = pathOf(ctx.env).split(delimiter).filter(Boolean);
+	if ((await Promise.all(entries.map(canonical))).includes(wanted)) return;
+	throw runtimeError({
+		code: NOT_ON_PATH,
+		message: `${cli.name} is installed in ${binDir}, by the npm of ${node ?? "the Node on PATH"}, a folder not on this shell's PATH`,
+		hint: `add ${binDir} to PATH, or ask your user which Node their terminal runs and run this under it`,
+		next: []
 	});
 }
-/** The built-in `skill install`, for a CLI whose skill ships in its package. */
-function skillInstallCommand(cli, folder, agents) {
+const REFUSED = /* @__PURE__ */ new Set([
+	PERMISSION_DENIED,
+	DISK_FULL,
+	INSTALL_FAILED
+]);
+function withSetupLine(error, install) {
+	if (!(error instanceof CliError) || !REFUSED.has(error.code)) return error;
+	return runtimeError({
+		code: error.code,
+		message: error.message,
+		hint: error.code === "INSTALL_FAILED" ? "fix what npm reports, then run the Next step; if a sandbox refused it, ask your user to type ! then that line" : error.hint,
+		next: [wholeLine(setupLineOf(install))]
+	}, { cause: error });
+}
+function renderSetup(cli, install, setup) {
+	const { version, prefix, docs } = setup;
+	return [
+		setup.installed ? `installed ${install.package}@${version} with the npm under ${prefix}` : `${install.package}@${version} is already installed under ${prefix}`,
+		...renderHomeSync(cli.name, setup.skill),
+		...setup.upgrades.map(renderUpgrade),
+		...docs === null ? [] : [`docs ${docs}`, `Read that folder before using ${cli.name}.`]
+	].join("\n");
+}
+/** The built-in `setup`, which runs from any copy, such as npx's, so it never asks to be the global one. */
+function setupCommand(cli, install, { node }) {
 	return defineCommand$1({
-		description: agents === void 0 ? "copy this CLI's skill into the project" : "copy this CLI's skill into the project and write its Agents section",
+		description: "install this CLI and its skill on this machine",
 		examples: [{
-			command: `${cli.name} skill install`,
-			note: "install the skill this version ships"
+			command: `${cli.name} setup`,
+			note: "install the latest version and the skill"
 		}, {
-			command: `${cli.name} skill install --dry-run`,
+			command: `${cli.name} setup --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, agents, 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 { agentsMd } = plan;
-			if (agentsMd !== null && agentsMd.change !== null) {
-				const existing = await orMissing(readFile(agentsMd.path, "utf8")) ?? "";
-				await ctx.files.write(agentsMd.path, withSection(agentsMd.agents, existing));
-			}
+		output: setupSchema,
+		plan: async (_input, ctx) => {
+			const npm = npmOfSetup(cli, install, ctx, node);
+			const prefix = await globalPrefix(npm);
+			const packageDir = join(globalModulesDir(prefix), install.package);
+			if ((await orMissing(lstat(packageDir)))?.isSymbolicLink() === true) throw runtimeError({
+				code: NOT_GLOBAL_INSTALL,
+				message: `${packageDir} is a link (npm link), which an install would replace`,
+				hint: "remove the link with npm unlink, then run the Next step",
+				next: [wholeLine(setupLineOf(install))]
+			});
 			return {
-				copy: plan.copy,
-				written: [...plan.write, ...plan.replace].sort(),
-				removed: [...plan.remove],
-				agentsMd: agentsMd === null ? null : {
-					path: agentsMd.path,
-					changed: agentsMd.change !== null
-				},
-				handEdits: [...plan.handEdits]
+				package: install.package,
+				from: await versionAt(packageDir),
+				latest: await latestVersion(npm),
+				prefix,
+				packageDir,
+				copies: cli.skill === void 0 ? [] : await homeCopiesOf(cli.name, ctx.env)
 			};
 		},
-		render: (data) => renderInstalled(cli, data),
-		renderPlan: (plan) => renderPlan(cli, plan)
+		apply: async (plan, ctx) => {
+			const { from, latest, prefix, packageDir } = plan;
+			const installs = needsInstall(plan);
+			const skill = await ctx.runToEnd(`installing ${plan.package}@${latest}`, async () => {
+				if (installs) {
+					ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
+					await installGlobally(latest, npmOfSetup(cli, install, ctx, node));
+				}
+				return syncHome(cli, packageDir, ctx);
+			}).catch((error) => {
+				throw withSetupLine(error, install);
+			});
+			const setup = {
+				version: installs || from === null ? latest : from,
+				prefix,
+				installed: installs,
+				skill,
+				upgrades: installs && from !== null ? await upgradesOf(packageDir, from, latest) : [],
+				docs: cli.docs === void 0 ? null : join(packageDir, cli.docs)
+			};
+			ctx.deliver(setup);
+			if (ctx.signal.aborted) throw new CliError({
+				code: INTERRUPTED,
+				message: `interrupted, but ${plan.package}@${setup.version} and its skill are already in place`,
+				hint: "nothing to run again"
+			});
+			await assertOnPath(cli, prefix, node, ctx);
+			return setup;
+		},
+		render: (setup) => renderSetup(cli, install, setup),
+		renderPlan: (plan) => [needsInstall(plan) ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}` : `${plan.package}@${plan.from} is already installed under ${plan.prefix}`, ...renderPlannedSync(cli.name, plan.copies)].join("\n")
 	});
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/skill/packaged.js
-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()
+//#region ../agent-cli/dist/built-ins/update.js
+const updateSchema = object({
+	from: string(),
+	latest: string(),
+	installed: object({
+		version: string(),
+		prefix: string()
+	}).nullable(),
+	skill: homeSyncSchema.nullable(),
+	upgrades: array(upgradeSchema)
 });
-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 project root's copy against the package's, and any under home. */
-async function findingOf(cli, folder, install, 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: `${install.runAs} skill install`,
-		skill
-	};
-	return home === void 0 ? {
-		state: "ok",
-		message,
-		skill
-	} : {
-		state: "problem",
-		message,
-		skill
-	};
-}
-async function notice(cli, folder, install, { builtIn, bin }, ctx) {
-	if (builtIn || bin === void 0 || cli.commands === void 0) return;
-	let finding;
-	try {
-		finding = await findingOf(cli, folder, install, ctx);
-	} catch (error) {
-		if (errnoOf(error) === void 0) throw error;
-		ctx.notice(`could not check the ${cli.name} skill: ${messageOf(error)}`);
-		return;
-	}
-	if (finding.state !== "problem") return;
-	ctx.notice(finding.fix === void 0 ? finding.message : `${finding.message}; run \`${finding.fix}\``);
-}
-/** A skill shipped in the package at `packaged`, which `skill install` copies to the project root. */
-function packagedSkill(cli, { packaged: folder, agents: text }, install) {
-	const agents = text === void 0 ? void 0 : {
-		name: cli.name,
-		text
-	};
-	return {
-		kind: "packaged",
-		builtIns: { skill: { install: skillInstallCommand(cli, folder, agents) } },
-		rows: [{
-			name: "skill",
-			advisory: true,
-			run: (ctx) => findingOf(cli, folder, install, ctx)
-		}, ...agents === void 0 ? [] : [agentsRow(agents, install)]],
-		notice: (launch, ctx) => notice(cli, folder, install, launch, ctx),
-		differing: async ({ cwd, packageRoot }) => {
-			const { copy } = await skillCopyOf(cli, cwd);
-			const { copyVersion, packageVersion, same } = await skillVersionsOf(join(packageRoot, folder), copy);
-			return copyVersion === void 0 || same ? [] : [compared(cli.name, {
-				copy,
-				copyVersion,
-				packageVersion
-			}, false)];
-		},
-		nextAt: async (_version, ctx) => {
-			const { fix } = await findingOf(cli, folder, install, ctx);
-			return fix === void 0 ? [] : [fix];
-		}
-	};
+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`;
 }
-//#endregion
-//#region ../agent-cli/dist/built-ins/skill/skill.js
-/** A Packaged skill, or else a Skill Hub's, also for a CLI that declares no `skill`. */
-function skillOf$1(cli, install) {
-	const { skill } = cli;
-	return skill !== void 0 && "packaged" in skill ? packagedSkill(cli, skill, install) : hubSkill(cli, skill);
+function renderUpdate(cli, install, update) {
+	const { installed } = update;
+	const skill = renderHomeSync(cli.name, update.skill);
+	return installed === null ? [nothingToInstall(update), ...skill].join("\n") : [
+		`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`,
+		...skill,
+		...update.upgrades.map(renderUpgrade)
+	].join("\n");
 }
-//#endregion
-//#region ../agent-cli/dist/context/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(rerun) {
+function interruptedAfterInstall(plan) {
 	return new CliError({
 		code: INTERRUPTED,
-		message: "interrupted before it finished",
-		hint: "to finish it, run the Next step, unless it was stopped on purpose; if a tool timeout stopped it, give it longer",
-		next: [rerun]
-	});
-}
-const BOUND_WORDS = {
-	deadline: "deadline",
-	ignoreStop: "timeout"
-};
-function waitHint(bound) {
-	return bound === "ignoreStop" ? "the call may have been billed: ask your user before running the Next step" : "run the Next step later, when the service it waits on may answer faster";
-}
-function deadlineError(commandLine, ms, advice, bound = "deadline") {
-	return new CliError({
-		code: DEADLINE_EXCEEDED,
-		message: `${commandLine} ran past its ${ms} ms ${BOUND_WORDS[bound]}`,
-		...advice
+		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"
 	});
 }
-/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
-var RunControl = class {
-	signal;
-	#controller = new AbortController();
-	#commandLine;
-	#rerun;
-	#outer;
-	#onOuterAbort = () => this.#controller.abort(interruptedError(this.#rerun));
-	/** 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 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, rerun, outer, clock, progress, runDeadline }) {
-		this.#commandLine = commandLine;
-		this.#rerun = rerun;
-		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, advice } = runDeadline;
-			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, advice())));
-		}
-	}
-	deadline(ms, options = {}) {
-		return options.ignoreStop === true ? this.#abortsAfter(ms, "ignoreStop") : AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
-	}
-	#abortsAfter(ms, bound) {
-		const controller = new AbortController();
-		after(this.#clock, ms, this.#disposed.signal, () => {
-			const advice = {
-				hint: waitHint(bound),
-				next: [this.#rerun]
+/** The built-in `update`, for a CLI installed globally with npm. */
+function updateCommand(cli, install, { bin, node }) {
+	return defineCommand$1({
+		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,
+				copies: cli.skill === void 0 ? [] : await homeCopiesOf(cli.name, ctx.env)
 			};
-			const reason = deadlineError(this.#commandLine, ms, advice, 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();
-		}
+		},
+		apply: async (plan, ctx) => {
+			const { from, latest, prefix } = plan;
+			if (standingOf$1(from, latest) !== "behind") return {
+				from,
+				latest,
+				installed: null,
+				skill: await syncHome(cli, plan.packageDir, ctx),
+				upgrades: []
+			};
+			ctx.signal.throwIfAborted();
+			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
+			const skill = await ctx.runToEnd(`installing ${plan.package}@${latest}`, async () => {
+				await installGlobally(latest, globalNpm(cli, install, ctx, node));
+				return syncHome(cli, plan.packageDir, ctx);
+			});
+			const update = {
+				from,
+				latest,
+				installed: {
+					version: latest,
+					prefix
+				},
+				skill,
+				upgrades: await upgradesOf(plan.packageDir, from, latest)
+			};
+			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), ...renderPlannedSync(cli.name, plan.copies)].join("\n")
+	});
+}
+//#endregion
+//#region ../agent-cli/dist/context/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";
 	}
-	/** 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();
-		}
+}
+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;
 	}
-	/**
-	* 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 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);
+}
+async function writeWithMode(path, data, mode) {
+	if (mode === void 0) {
+		await writeFile(path, data);
+		return;
 	}
-	#abortIn(error) {
-		if (error instanceof CliError) return void 0;
-		return causesOf(error).find((each) => each instanceof CliError && this.#abortReasons.has(each));
+	await writeFile(path, data, { mode });
+	await chmod(path, mode);
+}
+/** 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);
 	}
-	#onStop() {
-		for (const name of this.#steps.values()) this.#finishing(name);
-		this.#startGrace();
+}
+/** 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;
 	}
-	#finishing(name) {
-		this.#progress(`finishing ${name}`);
+	await handle.close();
+}
+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);
 	}
-	#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));
+}
+/** 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;
+			}
+		}
+	};
+}
+/**
+* `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
+			});
 		}
 	}
-	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);
-	}
-};
+	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))
+	};
+}
 //#endregion
-//#region ../agent-cli/dist/built-ins/install/global-npm.js
-const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
-/** Where npm puts global packages under its global prefix. */
-function globalModulesDir(prefix) {
-	return process.platform === "win32" ? join(prefix, "node_modules") : join(prefix, "lib", "node_modules");
+//#region ../agent-cli/dist/built-ins/install/release-check.js
+const CHECK_INTERVAL_MS = 864e5;
+const checkSchema = object({
+	checkedAt: number(),
+	latest: string().optional(),
+	error: string().optional()
+});
+const CHECK_SCRIPT = `
+const { spawnSync } = require("node:child_process");
+const { mkdtempSync, renameSync, rmSync, writeFileSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+const [file, checkedAt, previous, npm, ...args] = process.argv.slice(1);
+const windows = process.platform === "win32";
+const cache = mkdtempSync(join(tmpdir(), "release-check-"));
+const write = (check) => {
+  const temp = file + "." + process.pid + ".tmp";
+  writeFileSync(temp, JSON.stringify({ checkedAt: Number(checkedAt), ...check }));
+  renameSync(temp, file);
+};
+const latestOf = (stdout) => {
+  try {
+    const parsed = JSON.parse(stdout);
+    const latest = Array.isArray(parsed) ? parsed.at(-1) : parsed;
+    return typeof latest === "string" && /^\\d+\\.\\d+\\.\\d+/.test(latest) ? latest : undefined;
+  } catch {
+    return undefined;
+  }
+};
+try {
+  const answer = spawnSync(windows ? '"' + npm + '"' : npm, args, {
+    encoding: "utf8",
+    shell: windows,
+    windowsHide: true,
+    env: { ...process.env, npm_config_cache: join(cache, "cache"), npm_config_logs_max: "0" },
+  });
+  const latest = answer.status === 0 ? latestOf(answer.stdout) : undefined;
+  if (latest !== undefined) {
+    write({ latest });
+  } else {
+    const said = (answer.stderr || "").trim().split(/\\r?\\n/).slice(0, 5).join("; ");
+    const error = answer.error ? answer.error.message : said || "npm answered " + answer.stdout.trim();
+    write({ latest: previous || undefined, error });
+  }
+} finally {
+  rmSync(cache, { recursive: true, force: true });
+}
+`;
+function isOff(cliName, env) {
+	return Boolean(env[cliVariable(cliName, "NO_RELEASE_CHECK")] || env.CI);
+}
+function cacheFileOf(cliName, env) {
+	const cache = env.XDG_CACHE_HOME || join(env.HOME || env.USERPROFILE || homedir(), ".cache");
+	return join(cache, cliName, "release-check.json");
+}
+function parsedCheck(text) {
+	try {
+		return checkSchema.safeParse(JSON.parse(text)).data;
+	} catch {
+		return;
+	}
 }
-function notGlobal(ctx, message) {
-	return runtimeError({
-		code: NOT_GLOBAL_INSTALL,
-		message,
-		hint: "install it with npm by running the Next step, so its update Command can replace it",
-		next: [wholeLine(installCommandLine(ctx.registry))]
-	});
+async function lastCheck(file) {
+	const text = await orMissing(readFile(file, "utf8"));
+	return text === void 0 ? void 0 : parsedCheck(text);
+}
+async function writeCheck(file, check) {
+	await mkdir(dirname(file), { recursive: true });
+	const temp = tempPathOf(file);
+	await writeFile(temp, JSON.stringify(check));
+	await rename(temp, file);
+}
+async function startCheck(cli, install, file, last, { node }, ctx) {
+	const checkedAt = ctx.clock.now();
+	const previous = last?.latest ?? "";
+	await writeCheck(file, {
+		checkedAt,
+		latest: last?.latest
+	});
+	const npm = globalNpm(cli, install, ctx, node);
+	const { path, env } = npmOf(npm, process.platform === "win32");
+	await ctx.spawnDetached(process.execPath, [
+		"-e",
+		CHECK_SCRIPT,
+		file,
+		String(checkedAt),
+		previous,
+		path,
+		...latestViewArgs(npm.registry)
+	], { env });
+}
+function debugLine(cli, ctx, text) {
+	if (isDebug({
+		env: ctx.env,
+		cliName: cli.name
+	})) ctx.progress(`release check failed: ${text}`);
 }
 /**
-* The global npm install this copy runs from, found by asking npm for its global prefix.
-* `bin` is the script that started the CLI; throws `NOT_GLOBAL_INSTALL` when it is not inside that install.
+* Tells the caller of a newer release that an earlier Release check found, and starts the next
+* check once the last is a day old.
 */
-async function globalInstallOf(bin, ctx) {
-	if (bin === void 0) throw notGlobal(ctx, `${ctx.cliName} runs from source, not from an npm install`);
-	const prefix = await globalPrefix(ctx);
-	const packageDir = join(globalModulesDir(prefix), ctx.registry.package);
-	const installed = await orMissing(realpath(packageDir));
-	const here = await orMissing(realpath(bin)) ?? bin;
-	if (installed === void 0 || !isInside(installed, here)) throw notGlobal(ctx, `${ctx.cliName} runs from ${here}, not from npm's global install at ${packageDir}`);
-	if ((await lstat(packageDir)).isSymbolicLink()) throw notGlobal(ctx, `${ctx.cliName} runs from a link to ${installed} (npm link), not from an npm install`);
+async function releaseCheck(cli, install, runAs, launch, ctx) {
+	if (launch.builtIn || launch.bin === void 0 || cli.commands === void 0) return;
+	if (isOff(cli.name, ctx.env)) return;
+	try {
+		await checkAndTell(cli, install, runAs, launch, ctx);
+	} catch (error) {
+		if (errnoOf(error) === void 0 && !(error instanceof CliError)) throw error;
+		debugLine(cli, ctx, messageOf(error));
+	}
+}
+async function checkAndTell(cli, install, runAs, launch, ctx) {
+	const file = cacheFileOf(cli.name, ctx.env);
+	const last = await lastCheck(file);
+	if (last?.error !== void 0) debugLine(cli, ctx, last.error);
+	if (last === void 0 || ctx.clock.now() - last.checkedAt >= CHECK_INTERVAL_MS) await startCheck(cli, install, file, last, launch, ctx);
+	const latest = last?.latest;
+	if (latest === void 0 || !isVersion(latest) || compareVersions(latest, cli.version) <= 0) return;
+	ctx.notice(`${cli.name} ${latest} is out, this is ${cli.version}; run \`${runAs} update\``);
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/install/global.js
+function checkOf(cli, install, { bin, node }) {
 	return {
-		prefix,
-		packageDir
+		install: async (ctx) => {
+			const npm = globalNpm(cli, install, ctx, node);
+			try {
+				return {
+					state: "ok",
+					message: `a global npm install under ${(await globalInstallOf(bin, npm)).prefix}`
+				};
+			} catch (error) {
+				if (error instanceof CliError && error.code === "NOT_GLOBAL_INSTALL") return {
+					state: "problem",
+					message: error.message,
+					fix: setupLineOf(install)
+				};
+				throw error;
+			}
+		},
+		release: async (ctx) => {
+			const fix = `${cli.name} update`;
+			return {
+				npm: globalNpm(cli, install, ctx, node),
+				advise: () => ({ fix })
+			};
+		}
 	};
 }
-const NPMJS = "https://registry.npmjs.org/";
-/** The flag that points npm at the CLI's registry; none for npmjs, npm's default. */
-function registryFlags({ package: name, registry }) {
-	if (registry === NPMJS) return [];
-	const scope = scopeOf(name);
-	return [scope === void 0 ? `--registry=${registry}` : `--${scope}:registry=${registry}`];
+/** The Install of a CLI installed once per machine with npm, which `setup` puts there and `update` replaces. */
+function globalInstall(cli, install) {
+	const adapter = {
+		runAs: runAsOf(cli),
+		builtIns: (launch) => ({
+			setup: setupCommand(cli, install, launch),
+			update: updateCommand(cli, install, launch)
+		}),
+		exitClasses: ["source"],
+		check: (launch) => checkOf(cli, install, launch),
+		notice: (launch, ctx) => releaseCheck(cli, install, adapter.runAs, launch, ctx)
+	};
+	return adapter;
 }
-function globalRegistry(install) {
-	const { package: name, registry } = install;
+//#endregion
+//#region ../agent-cli/dist/built-ins/install/install.js
+const noNotice = async () => {};
+function noInstall(cli) {
+	const skipped = async () => ({
+		state: "skipped",
+		message: `not checked: ${cli.name} declares no install`
+	});
 	return {
-		package: name,
-		label: registry,
-		flags: registryFlags(install),
-		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}`
+		runAs: runAsOf(cli),
+		builtIns: () => ({}),
+		exitClasses: [],
+		check: () => ({
+			install: skipped,
+			release: async () => ({ skipped: await skipped() })
+		}),
+		notice: noNotice
 	};
 }
-/** npm for a Global install, run in the working directory. */
-function globalNpm(cli, install, ctx, node) {
-	return npmContext(cli, globalRegistry(install), ctx, node, ctx.cwd);
+function installOf(cli) {
+	const { install } = cli;
+	if (install === void 0) return noInstall(cli);
+	return install.mode === "global" ? globalInstall(cli, install) : dependencyInstall(cli, install);
 }
 //#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;
+//#region ../agent-cli/dist/built-ins/agents-md.js
+function markersOf(name) {
+	return {
+		begin: `<!-- BEGIN:${name} -->`,
+		end: `<!-- END:${name} -->`
+	};
 }
-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, ""));
+/** `text` with the CLI's Agents section between its markers, appended when they are missing; nothing else changes. */
+function withSection({ name, text: section }, text) {
+	const { begin, end } = markersOf(name);
+	const whole = `${begin}\n${section}\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 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
-	}];
+async function agentsMdAt(agents, root) {
+	const path = join(root, "AGENTS.md");
+	const existing = await orMissing(readFile(path, "utf8"));
+	if (existing === void 0) return {
+		path,
+		agents,
+		change: "create"
+	};
+	if (withSection(agents, existing) === existing) return {
+		path,
+		agents,
+		change: null
+	};
+	return {
+		path,
+		agents,
+		change: existing.includes(markersOf(agents.name).begin) ? "rewrite" : "add"
+	};
 }
-/**
-* 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 {
-		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
-	} catch (error) {
-		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 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`];
+}
+function agentsRow(agents, install) {
+	const { name } = agents;
+	return {
+		name: "agents",
+		advisory: true,
+		run: async (ctx) => {
+			const root = await projectRootOf(ctx.cwd);
+			const { path, change } = await agentsMdAt(agents, root);
+			const fix = `${install.runAs} skill install`;
+			if (change === "rewrite") return {
+				state: "problem",
+				message: `${path} holds a ${name} Agents section other than the one ${fix} writes`,
+				fix
+			};
+			if (change !== null) return {
+				state: "problem",
+				message: `${path} holds no ${name} Agents section, so sessions in this repo do not know ${name}`,
+				fix
+			};
+			const holds = `${path} holds the ${name} Agents section`;
+			const [edit] = await handEditsAt(root);
+			return edit === void 0 ? {
+				state: "ok",
+				message: holds
+			} : {
+				state: "problem",
+				message: `${holds}; ${edit}`
+			};
+		}
+	};
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/update.js
-const updateSchema = object({
-	from: string(),
-	latest: string(),
-	installed: object({
-		version: string(),
-		prefix: string()
+//#region ../agent-cli/dist/built-ins/skill/install-command.js
+/** 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)
+	};
+}
+const installSchema = object({
+	copy: string(),
+	written: array(string()),
+	removed: array(string()),
+	agentsMd: object({
+		path: string(),
+		changed: boolean()
 	}).nullable(),
-	upgrades: array(upgradeSchema),
-	next: array(string())
+	handEdits: 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`;
-}
-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}`;
+async function planOf(cli, folder, agents, cwd, packageRoot) {
+	const { root, copy } = await skillCopyOf(cli, cwd);
+	return {
+		...await syncOf(join(packageRoot, folder), copy),
+		agentsMd: agents === void 0 ? null : await agentsMdAt(agents, root),
+		handEdits: agents === void 0 ? [] : await handEditsAt(root)
+	};
 }
-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 SECTION_VERBS = {
+	create: "create",
+	add: "add the Agents section to",
+	rewrite: "rewrite the Agents section 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 { agentsMd } = plan;
+	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,
+		...agentsMd === null ? [] : [agentsMd.change === null ? `${agentsMd.path} already holds the ${cli.name} Agents section` : `would ${SECTION_VERBS[agentsMd.change]} ${agentsMd.path}:\n${agentsMd.agents.text}`],
+		...plan.handEdits.map((edit) => `by hand: ${edit}`)
+	].join("\n");
 }
-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"
-	});
+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 === null ? [] : [agentsMd.changed ? `wrote the ${cli.name} Agents section in ${agentsMd.path}` : `${agentsMd.path} already holds the ${cli.name} Agents section`],
+		...data.handEdits.map((edit) => `by hand: ${edit}`)
+	].join("\n");
 }
-/** The built-in `update`, for a CLI installed globally with npm. */
-function updateCommand(cli, install, skill, { bin, node }) {
+/** The built-in `skill install`, for a CLI whose skill ships in its package. */
+function skillInstallCommand(cli, folder, agents) {
 	return defineCommand$1({
-		description: "install the latest version of this CLI from its registry",
+		description: agents === void 0 ? "copy this CLI's skill into the project" : "copy this CLI's skill into the project and write its Agents section",
 		examples: [{
-			command: `${cli.name} update`,
-			note: "install the latest version and show what changed"
+			command: `${cli.name} skill install`,
+			note: "install the skill this version ships"
 		}, {
-			command: `${cli.name} update --dry-run`,
-			note: "show the version it would install"
+			command: `${cli.name} skill install --dry-run`,
+			note: "show what it would change"
 		}],
 		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
-			};
-		},
+		output: installSchema,
+		plan: (_input, ctx) => planOf(cli, folder, agents, ctx.cwd, ctx.packageRoot),
 		apply: async (plan, ctx) => {
-			const { from, latest, prefix } = plan;
-			if (standingOf$1(from, latest) !== "behind") return {
-				from,
-				latest,
-				installed: null,
-				upgrades: [],
-				next: await skill.nextAt(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
+			await applySync(plan, ctx);
+			const { agentsMd } = plan;
+			if (agentsMd !== null && agentsMd.change !== null) {
+				const existing = await orMissing(readFile(agentsMd.path, "utf8")) ?? "";
+				await ctx.files.write(agentsMd.path, withSection(agentsMd.agents, existing));
+			}
+			return {
+				copy: plan.copy,
+				written: [...plan.write, ...plan.replace].sort(),
+				removed: [...plan.remove],
+				agentsMd: agentsMd === null ? null : {
+					path: agentsMd.path,
+					changed: agentsMd.change !== null
 				},
-				upgrades: await upgradesOf(plan.packageDir, from, latest),
-				next: await skill.nextAt(latest, ctx)
+				handEdits: [...plan.handEdits]
 			};
-			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)
+		render: (data) => renderInstalled(cli, data),
+		renderPlan: (plan) => renderPlan(cli, plan)
 	});
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/install/global.js
-function checkOf(cli, install, { bin, node }) {
-	return {
-		install: async (ctx) => {
-			const npm = globalNpm(cli, install, ctx, node);
-			try {
-				return {
-					state: "ok",
-					message: `a global npm install under ${(await globalInstallOf(bin, npm)).prefix}`
-				};
-			} catch (error) {
-				if (error instanceof CliError && error.code === "NOT_GLOBAL_INSTALL") return {
-					state: "problem",
-					message: error.message,
-					fix: installCommandLine(npm.registry)
-				};
-				throw error;
-			}
-		},
-		release: async (ctx) => {
-			const fix = `${cli.name} update`;
-			return {
-				npm: globalNpm(cli, install, ctx, node),
-				advise: () => ({ fix })
-			};
-		}
-	};
+//#region ../agent-cli/dist/built-ins/skill/project.js
+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;
 }
-/** The Install of a CLI installed once per machine with npm, which `update` replaces. */
-function globalInstall(cli, install) {
-	const adapter = {
-		runAs: runAsOf(cli),
-		builtIns: (launch) => ({ update: updateCommand(cli, install, skillOf$1(cli, adapter), launch) }),
-		exitClasses: ["source"],
-		check: (launch) => checkOf(cli, install, launch)
+/** The project root's copy against the package's, and any under home. */
+async function findingOf(cli, folder, install, ctx) {
+	const { copy } = await skillCopyOf(cli, ctx.cwd);
+	const [installed, shipped] = await Promise.all([orMissing(readFile(join(copy, "SKILL.md"), "utf8")), readFile(join(ctx.packageRoot, folder, "SKILL.md"), "utf8")]);
+	const stated = installed === void 0 ? void 0 : skillVersionIn(installed);
+	const left = stated !== void 0 && skillVersionIn(shipped) === void 0;
+	const found = left ? `${copy} (${statedVersionNote(stated)})` : copy;
+	const head = installed === void 0 ? `no copy of the ${cli.name} skill at ${copy}` : found;
+	const home = await personalCopyOf(cli.name, copy, ctx);
+	const message = home === void 0 ? head : `${head}; remove ${home}: Claude Code prefers a personal skill over the project's`;
+	if (installed === void 0 || left) return {
+		state: "problem",
+		message,
+		fix: `${install.runAs} skill install`
+	};
+	return home === void 0 ? {
+		state: "ok",
+		message
+	} : {
+		state: "problem",
+		message
 	};
-	return adapter;
 }
-//#endregion
-//#region ../agent-cli/dist/built-ins/install/install.js
-function noInstall(cli) {
-	const skipped = async () => ({
-		state: "skipped",
-		message: `not checked: ${cli.name} declares no install`
-	});
+/** A skill the package ships in `folder`, which `skill install` copies to the project root. */
+function projectSkill(cli, { folder, agents: text }, install) {
+	const agents = text === void 0 ? void 0 : {
+		name: cli.name,
+		text
+	};
 	return {
-		runAs: runAsOf(cli),
-		builtIns: () => ({}),
-		exitClasses: [],
-		check: () => ({
-			install: skipped,
-			release: async () => ({ skipped: await skipped() })
-		})
+		builtIns: { skill: { install: skillInstallCommand(cli, folder, agents) } },
+		rows: [{
+			name: "skill",
+			advisory: true,
+			run: (ctx) => findingOf(cli, folder, install, ctx)
+		}, ...agents === void 0 ? [] : [agentsRow(agents, install)]]
 	};
 }
-function installOf(cli) {
-	const { install } = cli;
-	if (install === void 0) return noInstall(cli);
-	return install.mode === "global" ? globalInstall(cli, install) : dependencyInstall(cli, install);
+//#endregion
+//#region ../agent-cli/dist/built-ins/skill/skill.js
+const noSkill = ({ name }) => ({
+	builtIns: {},
+	rows: [{
+		name: "skill",
+		advisory: true,
+		run: async () => ({
+			state: "skipped",
+			message: `not checked: ${name} declares no skill`
+		})
+	}]
+});
+/** A Global install's Skill copy goes under home; any other goes under the project. */
+function skillOf(cli, install) {
+	const { skill } = cli;
+	if (skill === void 0) return noSkill(cli);
+	return cli.install?.mode === "global" ? homeSkill(cli, skill, install) : projectSkill(cli, skill, install);
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/doctor-rows.js
@@ -8883,7 +9046,7 @@ function doctorChecks(cli, launch, scope) {
 			...secretRows(cli.secrets ?? [], cli.commands),
 			installRow(check),
 			registryRow(cli, check),
-			...skillOf$1(cli, install).rows
+			...skillOf(cli, install).rows
 		],
 		tools: new Set(tools.map(({ name }) => name))
 	};
@@ -8901,8 +9064,7 @@ const reportSchema = object({
 		]),
 		message: string(),
 		fix: string().optional(),
-		code: string().optional(),
-		skill: packagedSkillDetailsSchema.optional()
+		code: string().optional()
 	})),
 	next: array(string())
 });
@@ -9037,15 +9199,15 @@ function doctorCommand(cli, launch) {
 //#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, and
-* `skill install` only for a Packaged skill.
+* The Commands the Runtime adds to a multi-Command CLI: `setup` and `update` only for a Global
+* install, and `skill install` only for a skill whose copy goes under the project.
 */
 function builtInCommands(cli, launch) {
 	const install = installOf(cli);
 	return {
 		doctor: doctorCommand(cli, launch),
 		...install.builtIns(launch),
-		...skillOf$1(cli, install).builtIns
+		...skillOf(cli, install).builtIns
 	};
 }
 //#endregion
@@ -9182,6 +9344,7 @@ const RUNTIME_EXIT_CLASSES = {
 	PROJECT_INVALID: "operator",
 	DOCTOR_PROBLEMS: "operator",
 	NOT_GLOBAL_INSTALL: "operator",
+	NOT_ON_PATH: "operator",
 	REGISTRY_UNREACHABLE: "operator",
 	REGISTRY_AUTH: "operator",
 	INSTALL_FAILED: "operator",
@@ -9255,20 +9418,22 @@ function checkTree(commands, path, table) {
 		else checkTree(node, at, table);
 	}
 }
-function checkSkillAdd({ name, skill }) {
-	if (skill === void 0 || !("add" in skill)) return;
-	const declares = `${name} declares skill.add ${JSON.stringify(skill.add)}`;
-	if (skill.add.trim() === "") throw new Error(`${declares}, which is empty`);
-	if (/[\r\n]/.test(skill.add)) throw new Error(`${declares}, which holds a line break`);
+function checkSkill({ name, skill, install }) {
+	if (skill?.agents !== void 0 && install?.mode === "global") throw new Error(`${name} declares an Agents section on a Global install, which has no repo to write it to`);
+}
+function checkDocs({ name, docs }) {
+	if (docs === void 0) return;
+	if (!(docs !== "" && !isAbsolute(docs) && !normalize(docs).startsWith(".."))) throw new Error(`${name} declares docs ${JSON.stringify(docs)}: name a folder inside its package, relative to the package root`);
 }
 function checkCli(cli) {
 	const table = errorTableOf(cli);
-	checkSkillAdd(cli);
+	checkDocs(cli);
 	if (cli.commands === void 0) {
 		checkCommand(cli.command, commandLabel([], cli.name).join(" "), table);
-		if (skillOf$1(cli, installOf(cli)).kind === "packaged") throw new Error(`${cli.name} declares a Packaged skill, which only a CLI with several Commands can install`);
+		if (cli.skill !== void 0) throw new Error(`${cli.name} declares a skill, which only a CLI with several Commands can install`);
 		return cli;
 	}
+	checkSkill(cli);
 	const { commands } = cli;
 	checkTree(commands, [], table);
 	const taken = Object.keys(builtInCommands(cli, {
@@ -9372,30 +9537,6 @@ function startSideTask(sideTask, runWith, { clock, failed }) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/skill/usage-hint.js
-const SKILL_USAGE_CODES = /* @__PURE__ */ new Set([
-	UNKNOWN_OPTION,
-	UNKNOWN_COMMAND,
-	INVALID_INPUT
-]);
-/** A usage error whose hint names each Skill copy that differs from this build, since one may have named the input. */
-async function withDifferingSkill(error, cli, place, runAs) {
-	if (!(error instanceof UsageError) || !SKILL_USAGE_CODES.has(error.code)) return error;
-	let differing;
-	try {
-		differing = await skillOf$1(cli, installOf(cli)).differing(place);
-	} catch (lookup) {
-		if (errnoOf(lookup) === void 0) throw lookup;
-		return error;
-	}
-	if (differing.length === 0) return error;
-	return new UsageError({
-		code: error.code,
-		message: error.message,
-		hint: `${error.hint}; the ${cli.name} skill may name what this build does not know: ${differing.join("; ")}; run \`${runAs} doctor\` to see how to update it`
-	});
-}
-//#endregion
 //#region ../agent-cli/dist/command-line/suggest.js
 const MAX_DISTANCE = 3;
 const MIN_SIMILARITY = .4;
@@ -10147,7 +10288,11 @@ function helpResult(node, root, cli, { style, json }) {
 }
 function versionResult(cli, packageRoot) {
 	return {
-		stdout: `${(buildStamp() === void 0 ? [versionLine(cli)] : [versionLine(cli), `changelog ${join(packageRoot, "CHANGELOG.md")}`]).join("\n")}\n`,
+		stdout: `${[
+			versionLine(cli),
+			...buildStamp() === void 0 ? [] : [`changelog ${join(packageRoot, "CHANGELOG.md")}`],
+			...cli.docs === void 0 ? [] : [`docs ${join(packageRoot, cli.docs)}`]
+		].join("\n")}\n`,
 		stderr: "",
 		exitCode: SUCCESS_EXIT_CODE
 	};
@@ -10214,6 +10359,77 @@ function checkOperator({ operator, commandLine }, env, rerun) {
 	});
 }
 //#endregion
+//#region ../agent-cli/dist/context/outputs.js
+const OUTPUT_EXISTS = "OUTPUT_EXISTS";
+/** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
+async function checkOutputs({ rerun, 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: `once the user agrees to replace ${them}, run the Next step`,
+		next: [rerun({ add: [FORCE_FLAG.flag] })]
+	});
+}
+/** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
+function outputsGuard(files, cwd) {
+	const unwritten = /* @__PURE__ */ new Set();
+	let forceStep = [];
+	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: "once the user agrees to replace it, run the Next step",
+				next: [forceStep]
+			}, { 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, step) => {
+			forceStep = step;
+			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/context/spill.js
 const STDOUT_BUDGET_CHARS = 3e4;
 const SPILL_RETENTION_MS = 6048e5;
@@ -11106,11 +11322,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			});
 		});
 	} catch (error) {
-		return failed(await withDifferingSkill(error, cli, {
-			cwd,
-			env,
-			packageRoot
-		}, invocation.runAs), noSideTask);
+		return failed(error, noSideTask);
 	}
 	const { input, flags } = parsed;
 	resumed = command.deadline?.resume(input, rerunOf);
@@ -11178,9 +11390,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	let served = false;
 	let settled;
 	try {
-		const outcome = await control.settle(skillOf$1(cli, installOf(cli)).notice({
+		const outcome = await control.settle(noticesOf(cli, {
 			builtIn,
-			bin: options.bin
+			bin: options.bin,
+			node: options.node
 		}, ctx).then(() => execute(command, input, ctx, {
 			dryRun: flags.dryRun,
 			confirm: flags.confirm,
@@ -11240,6 +11453,9 @@ function once(build) {
 		throw outcome.error;
 	};
 }
+async function noticesOf(cli, launch, ctx) {
+	await installOf(cli).notice(launch, ctx);
+}
 //#endregion
 //#region ../agent-cli/dist/style.js
 function colourEnabled(env, stdoutIsTTY) {
@@ -11322,16 +11538,10 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 			...format,
 			json: routed.json
 		}));
-		case "usage error": {
-			const place = {
-				...options,
-				packageRoot: packageRootOf(options.bin, options.cwd)
-			};
-			return ranAlone(errorResult(await withDifferingSkill(routed.error, cli, place, runAs), {
-				...misused(routed.node),
-				json: routed.json
-			}));
-		}
+		case "usage error": return ranAlone(errorResult(routed.error, {
+			...misused(routed.node),
+			json: routed.json
+		}));
 		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(cli, routed, options, write, misused(routed.spec)));
 	}
 }
@@ -11394,7 +11604,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.22.0",
+	version: "0.24.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },
@@ -11443,80 +11653,35 @@ function fill(text, values, quoted) {
 //#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: "global",\n`;
-const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub: { git }` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, or set `skill.add` to the whole line that installs the skill and `skillHub: { api }` to the API Skill Hub each release publishes the skill to. Then put here what `node dist/bin.js doctor` gives in its `skill` row: the line of its fix, after `! `. -->";
-function skillHubOf({ git, api, add }) {
-	if (git !== void 0 && api !== void 0) throw new UsageError({
-		code: "SKILL_HOMES_CONFLICT",
-		message: "--skill-hub-git and --skill-hub-api each name the Skill Hub the skill goes to",
-		hint: "pass one of them"
-	});
-	if (api !== void 0 && add === void 0) throw new UsageError({
-		code: "SKILL_ADD_MISSING",
-		message: "--skill-hub-api needs --skill-add, the whole line that installs the skill from the hub",
-		hint: "add --skill-add with the hub's install line for the skill"
-	});
-	if (add !== void 0 && api === void 0) throw new UsageError({
-		code: "SKILL_HUB_API_MISSING",
-		message: "--skill-add is the install line of an API Skill Hub, which --skill-hub-api names",
-		hint: "add --skill-hub-api with the hub's URL"
-	});
-	if (add !== void 0 && (add.trim() === "" || /[\r\n]/.test(add))) throw new UsageError({
-		code: "SKILL_ADD_INVALID",
-		message: `--skill-add ${JSON.stringify(add)} is not one command line`,
-		hint: "pass the hub's install line for the skill, on one line"
-	});
-	if (git !== void 0) return {
-		kind: "git",
-		url: git
-	};
-	return api === void 0 || add === void 0 ? void 0 : {
-		kind: "api",
-		url: api,
-		add
-	};
-}
-function installModeOf(flags, dependency, binName) {
-	const skillHub = skillHubOf(flags);
-	if (skillHub !== void 0 && dependency) throw new UsageError({
-		code: "SKILL_HOMES_CONFLICT",
-		message: `--skill-hub-${skillHub.kind} 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-${skillHub.kind} for a global one whose skill each release puts on a Skill Hub`
-	});
-	if ((skillHub !== void 0 || dependency) && !SKILL_NAME.test(binName)) throw new UsageError({
+const TEMPLATE_REGISTRY = "https://registry.npmjs.org/";
+function installModeOf(dependency, binName) {
+	if (!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-${skillHub?.kind}`}`
+		hint: "choose a name such as my-cli"
 	});
-	return dependency ? { mode: "dependency" } : {
-		mode: "global",
-		skillHub
-	};
-}
-function skillLineOf(skillHub, binName) {
-	if (skillHub === void 0) return NO_SKILL_HUB;
-	return skillHub.kind === "git" ? `\`! npx -y skills add ${skillHub.url} --skill ${binName} -g\`` : `\`! ${skillHub.add}\``;
+	return dependency ? "dependency" : "global";
 }
 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([
+	const [installLines, skillCheck, installSteps, updateSteps, sandbox, whenMissing] = await Promise.all([
 		partial("installLines"),
 		partial("skillCheck"),
 		partial("installSteps"),
 		partial("updateSteps"),
-		partial("sandbox")
+		partial("sandbox"),
+		partial("whenMissing")
 	]);
 	return {
 		installLines,
 		skillCheck,
 		installSteps,
 		updateSteps,
-		sandbox
+		sandbox,
+		whenMissing
 	};
 }
-async function globalSetup(skillHub, packageName, binName) {
-	const skillLine = skillLineOf(skillHub, binName);
+async function globalSetup(packageName, binName) {
 	const runAs = runAsOf({ name: binName });
 	return {
 		values: {
@@ -11526,24 +11691,16 @@ async function globalSetup(skillHub, packageName, binName) {
 				packageName,
 				binName,
 				runAs,
-				skillLine
+				setupLine: setupLineOf({
+					mode: "global",
+					package: packageName,
+					registry: TEMPLATE_REGISTRY
+				})
 			})
 		},
-		edits: skillHub === void 0 ? [] : [{
-			file: "src/cli.ts",
-			find: COMMANDS_ANCHOR,
-			replace: `  skill: ${skillOf(skillHub)},\n${COMMANDS_ANCHOR}`
-		}, {
-			file: "scripts/release.ts",
-			find: "  smoke: {",
-			replace: `  skillHub: { ${skillHub.kind}: ${JSON.stringify(skillHub.url)} },\n  smoke: {`
-		}],
-		files: []
+		edits: []
 	};
 }
-function skillOf(skillHub) {
-	return skillHub.kind === "git" ? `{ source: ${JSON.stringify(skillHub.url)} }` : `{ add: ${JSON.stringify(skillHub.add)} }`;
-}
 async function dependencySetup(packageName, binName) {
 	const runAs = runAsOf({
 		name: binName,
@@ -11564,18 +11721,13 @@ async function dependencySetup(packageName, binName) {
 		},
 		edits: [{
 			file: "src/cli.ts",
-			find: GLOBAL_INSTALL,
+			find: `  install: "global",\n`,
 			replace: `  install: "dependency",\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);
+	return install === "global" ? globalSetup(packageName, binName) : dependencySetup(packageName, binName);
 }
 //#endregion
 //#region src/steps.ts
@@ -11728,9 +11880,6 @@ async function editManifest(root, edit) {
 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({
 		code: "TARGET_NOT_EMPTY",
@@ -11756,18 +11905,11 @@ await runProcess(defineCli({
 			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"),
-			skillHubGit: 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 a git Skill Hub each release commits the CLI's skill to"),
-			skillHubApi: url({ protocol: /^https$/ }).optional().describe("the https URL of an API Skill Hub each release publishes the CLI's skill to"),
-			skillAdd: string().optional().describe("the whole line that installs the CLI's skill from the API Skill Hub"),
-			dependency: boolean().default(false).describe("install the CLI per project, as a devDependency, with its skill shipped inside the package")
+			dependency: boolean().default(false).describe("install the CLI per project, as a devDependency, with its skill copied into the project")
 		}),
-		plan: async ({ name, description, install, git, repository, skillHubGit, skillHubApi, skillAdd, dependency }, ctx) => {
+		plan: async ({ name, description, install, git, repository, dependency }, ctx) => {
 			const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
-			const mode = installModeOf({
-				git: skillHubGit,
-				api: skillHubApi,
-				add: skillAdd
-			}, dependency, binName);
+			const mode = installModeOf(dependency, binName);
 			const path = resolve(ctx.cwd, binName);
 			await ensureFree(path);
 			const setup = await installSetupOf(mode, name, binName);
@@ -11790,8 +11932,7 @@ await runProcess(defineCli({
 				}),
 				install,
 				repository,
-				edits: setup.edits,
-				manifestFiles: setup.files
+				edits: setup.edits
 			};
 		},
 		apply: async (plan, ctx) => {
@@ -11799,7 +11940,6 @@ await runProcess(defineCli({
 			await writeTemplate(plan.path, plan.files, plan.values);
 			if (plan.repository !== void 0) await setRepository(plan.path, plan.repository);
 			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,