@duyquangnvx/create-agent-cli 0.15.0 → 0.15.1

package/dist/bin.js

@@ -6496,15 +6496,6 @@ function isCommand(node) {
 	return typeof node.effect === "string";
 }
 //#endregion
-//#region ../agent-cli/dist/run-as.js
-/**
-* The Run-as: how every command line the Runtime gives its caller starts. A Dependency install runs
-* the copy the project pins, so it is `npx -q --no-install <bin>`; otherwise the bare name (ADR 0011).
-*/
-function runAsOf(cli) {
-	return cli.install?.mode === "dependency" ? `npx -q --no-install ${cli.name}` : cli.name;
-}
-//#endregion
 //#region ../agent-cli/dist/project.js
 const PROJECT_INVALID = "PROJECT_INVALID";
 function invalid(path, problem, callerLine, options) {
@@ -6619,6 +6610,69 @@ function versionLine({ version, build }) {
 	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
 }
 //#endregion
+//#region ../agent-cli/dist/project-root.js
+const MANAGERS = [
+	"pnpm",
+	"npm",
+	"yarn",
+	"bun"
+];
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["package-lock.json", "npm"],
+	["yarn.lock", "yarn"],
+	["bun.lock", "bun"],
+	["bun.lockb", "bun"]
+];
+const manifestSchema$1 = object({
+	packageManager: string().optional(),
+	dependencies: record(string(), unknown()).optional(),
+	devDependencies: record(string(), unknown()).optional()
+});
+/** `dir` and every folder above it, nearest first. */
+function ancestorsOf(dir) {
+	const parent = dirname(dir);
+	return parent === dir ? [dir] : [dir, ...ancestorsOf(parent)];
+}
+async function exists(path) {
+	return await orMissing(stat(path)) !== void 0;
+}
+/** Whether `path` lies strictly inside `dir`. */
+function isInside(dir, path) {
+	const inner = relative(dir, path);
+	return inner !== "" && !inner.startsWith("..") && !isAbsolute(inner);
+}
+async function manifestIn(dir) {
+	let text;
+	try {
+		text = await readFile(join(dir, "package.json"), "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return void 0;
+		throw error;
+	}
+	let manifest;
+	try {
+		manifest = JSON.parse(text);
+	} catch {
+		return;
+	}
+	return manifestSchema$1.safeParse(manifest).data;
+}
+async function declaredManager(dir) {
+	const name = (await manifestIn(dir))?.packageManager?.split("@")[0];
+	return MANAGERS.find((manager) => manager === name);
+}
+async function lockfileRootOf(cwd) {
+	for (const dir of ancestorsOf(cwd)) for (const [file, kind] of LOCKFILES) if (await exists(join(dir, file))) return {
+		dir,
+		manager: await declaredManager(dir) ?? kind
+	};
+}
+/** The package manager's project root: the folder of the nearest lockfile, or `cwd` without one. */
+async function projectRootOf(cwd) {
+	return (await lockfileRootOf(cwd))?.dir ?? cwd;
+}
+//#endregion
 //#region ../agent-cli/dist/tail.js
 /** The last `count` lines of a child's output, trimmed; empty when it wrote nothing. */
 function lastLines(output, count) {
@@ -7003,7 +7057,6 @@ function npmContext(cli, registry, ctx, node, cwd) {
 		node
 	};
 }
-const NPMJS = "https://registry.npmjs.org/";
 const STDERR_TAIL_LINES = 10;
 const RM_RETRIES = 3;
 const NETWORK_CODES = /* @__PURE__ */ new Set([
@@ -7022,28 +7075,6 @@ const NPM_CODE = /^npm (?:error|ERR!) code (\S+)$/m;
 function scopeOf(name) {
 	return /^(@[^/]+)\//.exec(name)?.[1];
 }
-/** 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 registry a Global install declares. */
-function globalRegistry(install) {
-	const { package: name, registry } = 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}`
-	};
-}
-/** npm for a Global install, run where the CLI was started. */
-function globalNpm(cli, install, ctx, node) {
-	return npmContext(cli, globalRegistry(install), ctx, node, process.cwd());
-}
 /** The command a person runs to install the CLI globally from its registry. */
 function installCommandLine(registry, version = "latest") {
 	return [
@@ -7186,62 +7217,13 @@ async function latestVersion(ctx) {
 	return version;
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/global-install.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 new CliError({
-		code: NOT_GLOBAL_INSTALL,
-		message,
-		hint: `install it with npm, so \`${ctx.cliName} update\` can replace it: ${installCommandLine(ctx.registry)}`
-	});
-}
-async function realpathOrUndefined(path) {
-	return realpath(path).catch((error) => {
-		if (isMissingFile(error)) return void 0;
-		throw error;
-	});
-}
-/** Whether `path` lies strictly inside `dir`. */
-function isInside(dir, path) {
-	const inner = relative(dir, path);
-	return inner !== "" && !inner.startsWith("..") && !isAbsolute(inner);
-}
-/**
-* 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 realpathOrUndefined(packageDir);
-	const here = await realpathOrUndefined(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 {
-		prefix,
-		packageDir
-	};
+//#region ../agent-cli/dist/built-ins/install/run-as.js
+/** The Run-as: the bare name, or `npx -q --no-install <bin>` for a Dependency install (ADR 0011). */
+function runAsOf({ name, install }) {
+	return install?.mode === "dependency" ? `npx -q --no-install ${name}` : name;
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/dependency-install.js
-const MANAGERS = [
-	"pnpm",
-	"npm",
-	"yarn",
-	"bun"
-];
-const LOCKFILES = [
-	["pnpm-lock.yaml", "pnpm"],
-	["package-lock.json", "npm"],
-	["yarn.lock", "yarn"],
-	["bun.lock", "bun"],
-	["bun.lockb", "bun"]
-];
+//#region ../agent-cli/dist/built-ins/install/dependency.js
 const LINES = {
 	pnpm: {
 		upgrade: (packages) => `pnpm up --latest ${packages.join(" ")}`,
@@ -7254,46 +7236,7 @@ const LINES = {
 		install: "npm install"
 	}
 };
-const manifestSchema$1 = object({
-	packageManager: string().optional(),
-	dependencies: record(string(), unknown()).optional(),
-	devDependencies: record(string(), unknown()).optional()
-});
 const packageSchema = object({ version: string() });
-/** `dir` and every folder above it, nearest first. */
-function ancestorsOf(dir) {
-	const parent = dirname(dir);
-	return parent === dir ? [dir] : [dir, ...ancestorsOf(parent)];
-}
-async function exists(path) {
-	try {
-		await stat(path);
-		return true;
-	} catch (error) {
-		if (isMissingFile(error)) return false;
-		throw error;
-	}
-}
-async function manifestIn(dir) {
-	let text;
-	try {
-		text = await readFile(join(dir, "package.json"), "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return void 0;
-		throw error;
-	}
-	let manifest;
-	try {
-		manifest = JSON.parse(text);
-	} catch {
-		return;
-	}
-	return manifestSchema$1.safeParse(manifest).data;
-}
-async function declaredManager(dir) {
-	const name = (await manifestIn(dir))?.packageManager?.split("@")[0];
-	return MANAGERS.find((manager) => manager === name);
-}
 async function manifestListing(name, cwd, root) {
 	const dirs = ancestorsOf(cwd);
 	const top = root === void 0 ? dirs.length : dirs.indexOf(root.dir) + 1;
@@ -7302,16 +7245,6 @@ async function manifestListing(name, cwd, root) {
 		if (manifest?.dependencies?.[name] !== void 0 || manifest?.devDependencies?.[name] !== void 0) return join(dir, "package.json");
 	}
 }
-async function lockfileRootOf(cwd) {
-	for (const dir of ancestorsOf(cwd)) for (const [file, kind] of LOCKFILES) if (await exists(join(dir, file))) return {
-		dir,
-		manager: await declaredManager(dir) ?? kind
-	};
-}
-/** The package manager's project root: the folder of the nearest lockfile, or `cwd` without one. */
-async function projectRootOf(cwd) {
-	return (await lockfileRootOf(cwd))?.dir ?? cwd;
-}
 async function versionIn(manifest) {
 	try {
 		return packageSchema.parse(JSON.parse(await readFile(manifest, "utf8"))).version;
@@ -7341,10 +7274,7 @@ async function standingOf(install, bin, cwd, root) {
 			kind: "linked",
 			copy
 		};
-		const runningFrom = await realpath(bin).catch((error) => {
-			if (isMissingFile(error)) return bin;
-			throw error;
-		});
+		const runningFrom = await orMissing(realpath(bin)) ?? bin;
 		return isInside(copy.realDir, runningFrom) ? {
 			kind: "installed",
 			copy
@@ -7395,7 +7325,7 @@ function problem(message, fix) {
 	};
 }
 /** The `install` row of a Dependency install. */
-function dependencyInstallFinding(cli, install, { cwd, root, standing }) {
+function installFinding(cli, runAs, install, { cwd, root, standing }) {
 	const lines = root === void 0 ? void 0 : LINES[root.manager];
 	switch (standing.kind) {
 		case "source":
@@ -7405,7 +7335,7 @@ function dependencyInstallFinding(cli, install, { cwd, root, standing }) {
 		case "unreadable": return problem(`${standing.manifest} is not a package.json with a version: ${standing.reason}`, lines?.install);
 		case "other": {
 			const { copy, runningFrom } = standing;
-			return problem(`${cli.name} runs from ${runningFrom}, not from this project's ${install.package} ${copy.version} at ${copy.realDir}`, `${runAsOf(cli)} doctor`);
+			return problem(`${cli.name} runs from ${runningFrom}, not from this project's ${install.package} ${copy.version} at ${copy.realDir}`, `${runAs} doctor`);
 		}
 		case "installed": {
 			const { copy } = standing;
@@ -7435,97 +7365,37 @@ function adviceFor(install, root, latest) {
 	if (lines !== void 0) return { fix: lines.upgrade(packages) };
 	return { note: `move ${packages.length === 1 ? packages[0] : `${packages.slice(0, -1).join(", ")} and ${packages.at(-1)}`} to ${latest} with ${root?.manager ?? "the project's package manager"}` };
 }
-function dependencyRelease(cli, install, { cwd, root, standing }) {
-	if (isUnchecked(standing)) return { skipped: skippedFor(cli, install, standing) };
-	return {
-		registry: registryOf(install, root?.dir),
-		cwd: root?.dir ?? cwd,
-		advise: (latest) => adviceFor(install, root, latest)
-	};
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/agents-md.js
-/** One paragraph telling every session that the CLI exists, how to run it and which skill to load. */
-function agentsBlock(cli) {
-	const { install } = cli;
-	const where = install?.mode === "dependency" ? `, and only from a package that has \`${install.package}\` in its dependencies; from anywhere else npx reports the package missing` : "";
-	const what = cli.description.replace(/\.$/, "");
-	return `\`${cli.name}\`: ${what}. Run it as \`${runAsOf(cli)}\`${where}. Load the \`${cli.name}\` skill before using it.`;
-}
-function markersOf(name) {
-	return {
-		begin: `<!-- BEGIN:${name} -->`,
-		end: `<!-- END:${name} -->`
-	};
-}
-/** `text` with the CLI's block between its markers, appended when they are missing; nothing else changes. */
-function withBlock(cli, text) {
-	const { begin, end } = markersOf(cli.name);
-	const whole = `${begin}\n${agentsBlock(cli)}\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(cli, root) {
-	const path = join(root, "AGENTS.md");
-	const existing = await orMissing(readFile(path, "utf8"));
-	const block = agentsBlock(cli);
-	if (existing === void 0) return {
-		path,
-		block,
-		change: "create"
-	};
-	if (withBlock(cli, existing) === existing) return {
-		path,
-		block,
-		change: null
+function checkOf$1(cli, install, runAs, { bin, node }) {
+	let survey;
+	const surveyed = (cwd) => {
+		survey ??= surveyDependency(install, bin, cwd);
+		return survey;
 	};
 	return {
-		path,
-		block,
-		change: existing.includes(markersOf(cli.name).begin) ? "rewrite" : "add"
+		install: async (ctx) => installFinding(cli, runAs, install, await surveyed(ctx.cwd)),
+		release: async (ctx) => {
+			const { cwd, root, standing } = await surveyed(ctx.cwd);
+			if (isUnchecked(standing)) return { skipped: skippedFor(cli, install, standing) };
+			return {
+				npm: npmContext(cli, registryOf(install, root?.dir), ctx, node, root?.dir ?? cwd),
+				advise: (latest) => adviceFor(install, root, latest)
+			};
+		}
 	};
 }
-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(cli) {
+/** The Install of a CLI each project pins as a dependency, run through npx (ADR 0011). */
+function dependencyInstall(cli, install) {
+	const runAs = runAsOf(cli);
 	return {
-		name: "agents",
-		advisory: true,
-		run: async (ctx) => {
-			const root = await projectRootOf(ctx.cwd);
-			const { path, change } = await agentsMdAt(cli, root);
-			const fix = `${runAsOf(cli)} skill install`;
-			if (change === "rewrite") return {
-				state: "problem",
-				message: `${path} holds a ${cli.name} block other than the one ${fix} writes`,
-				fix
-			};
-			if (change !== null) return {
-				state: "problem",
-				message: `${path} holds no ${cli.name} block, so sessions in this repo do not know ${cli.name}`,
-				fix
-			};
-			const holds = `${path} holds the ${cli.name} block`;
-			const [edit] = await handEditsAt(root);
-			return edit === void 0 ? {
-				state: "ok",
-				message: holds
-			} : {
-				state: "problem",
-				message: `${holds}; ${edit}`
-			};
-		}
+		runAs,
+		builtIns: () => ({}),
+		exitClasses: [],
+		agentsCaveat: `and only from a package that has \`${install.package}\` in its dependencies; from anywhere else npx reports the package missing`,
+		check: (launch) => checkOf$1(cli, install, runAs, launch)
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/skills.js
+//#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;
@@ -7583,473 +7453,168 @@ function fixFor(cliName, copies, source) {
 	if (has("unversioned") && add !== void 0) return has("behind") ? `${update} && ${add}` : add;
 	return has("behind") || has("unversioned") ? update : void 0;
 }
-async function skillReport(cli, version, ctx) {
-	const copies = await skillCopies(cli.name, version, ctx);
-	const source = cli.skill !== void 0 && "source" in cli.skill ? cli.skill.source : void 0;
-	return {
-		copies,
-		fix: fixFor(cli.name, copies, source)
-	};
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/packaged-skill.js
-/** The folder, relative to the package root, of a CLI's Packaged skill, if it declares one. */
-function packagedFolderOf(cli) {
-	return cli.skill !== void 0 && "packaged" in cli.skill ? cli.skill.packaged : void 0;
+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]})`;
 }
-/** The project root and the Skill copy under it, as `skill install` writes it. */
-async function skillCopyOf(cli, cwd) {
-	const root = await projectRootOf(cwd);
+/** A skill that `npx skills add` installs from `source`, the Skill Hub; with no `source`, no line adds it. */
+function hubSkill(cli, source) {
+	const findingAt = async (version, ctx) => {
+		const copies = await skillCopies(cli.name, version, ctx);
+		const fix = fixFor(cli.name, copies, source);
+		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 {
-		root,
-		copy: join(root, ".claude", "skills", cli.name)
+		kind: "hub",
+		builtIns: {},
+		rows: [{
+			name: "skill",
+			advisory: true,
+			run: (ctx) => findingAt(cli.version, ctx)
+		}],
+		notice: async () => {},
+		findingAt
 	};
 }
-/** Every file under `dir`, relative to it and sorted; none when `dir` is missing. */
-async function filesIn(dir) {
-	return (await orMissing(readdir(dir, {
-		recursive: true,
-		withFileTypes: true
-	})) ?? []).filter((entry) => entry.isFile()).map((entry) => relative(dir, join(entry.parentPath, entry.name))).sort();
+//#endregion
+//#region ../agent-cli/dist/built-ins/agents-md.js
+/** One paragraph telling every session that the CLI exists, how to run it and which skill to load. */
+function agentsBlock(cli, { runAs, agentsCaveat }) {
+	const what = cli.description.replace(/\.$/, "");
+	const run = `Run it as \`${runAs}\`${agentsCaveat === void 0 ? "" : `, ${agentsCaveat}`}`;
+	return `\`${cli.name}\`: ${what}. ${run}. Load the \`${cli.name}\` skill before using it.`;
 }
-/** 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;
+function markersOf(name) {
 	return {
-		packageVersion,
-		copyVersion,
-		same: copyVersion === packageVersion
+		begin: `<!-- BEGIN:${name} -->`,
+		end: `<!-- END:${name} -->`
 	};
 }
-async function personalCopyOf(name, copy, ctx) {
-	const home = join(homeOf(ctx.env), ".claude", "skills", name);
-	const real = await orMissing(realpath(home));
-	return real === void 0 || real === await orMissing(realpath(copy)) ? void 0 : home;
-}
-/** What the `skill` row of a Packaged skill carries under `--json` beside its message. */
-const packagedSkillDetailsSchema = object({
-	copy: string(),
-	copyVersion: string().nullable(),
-	packageVersion: string().nullable(),
-	/** A personal copy, which Claude Code prefers over the project's. */
-	home: string().optional()
-});
-function versionLabel(version) {
-	return version ?? "(no metadata.version)";
-}
-function compared(name, { copy, copyVersion, packageVersion }, same) {
-	const stated = `${copy} ${versionLabel(copyVersion)}`;
-	return same ? `${stated}, the version ${name} ships` : `${stated} differs from the ${versionLabel(packageVersion)} that ${name} ships`;
+/** `text` with the CLI's block between its markers, appended when they are missing; nothing else changes. */
+function withBlock(cli, install, text) {
+	const { begin, end } = markersOf(cli.name);
+	const whole = `${begin}\n${agentsBlock(cli, install)}\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`;
 }
-/** The `skill` row of a Packaged skill: the project root's copy against the package's, and any under home. */
-async function packagedSkillFinding(cli, folder, ctx) {
-	const { copy } = await skillCopyOf(cli, ctx.cwd);
-	const versions = await skillVersionsOf(join(ctx.packageRoot, folder), copy);
-	const { packageVersion } = versions;
-	const copyVersion = versions.copyVersion ?? null;
-	const home = await personalCopyOf(cli.name, copy, ctx);
-	const skill = {
-		copy,
-		copyVersion,
-		packageVersion,
-		...home === void 0 ? {} : { home }
-	};
-	const head = versions.copyVersion === void 0 ? `no copy of the ${cli.name} skill at ${copy}` : compared(cli.name, skill, versions.same);
-	const message = home === void 0 ? head : `${head}; remove ${home}: Claude Code prefers a personal skill over the project's`;
-	if (!versions.same) return {
-		state: "problem",
-		message,
-		fix: `${runAsOf(cli)} skill install`,
-		skill
-	};
-	return home === void 0 ? {
-		state: "ok",
-		message,
-		skill
-	} : {
-		state: "problem",
-		message,
-		skill
+async function agentsMdAt(cli, install, root) {
+	const path = join(root, "AGENTS.md");
+	const existing = await orMissing(readFile(path, "utf8"));
+	const block = agentsBlock(cli, install);
+	if (existing === void 0) return {
+		path,
+		block,
+		change: "create"
 	};
-}
-/** Gives a Packaged skill's `skill` row problem as a Notice, since an agent rarely runs `doctor`. */
-async function noticeSkillCopy(cli, { builtIn, bin }, ctx) {
-	if (builtIn || bin === void 0 || cli.commands === void 0) return;
-	const folder = packagedFolderOf(cli);
-	if (folder === void 0) return;
-	let finding;
-	try {
-		finding = await packagedSkillFinding(cli, folder, 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}\``);
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/doctor-rows.js
-function ok(message) {
-	return {
-		state: "ok",
-		message
+	if (withBlock(cli, install, existing) === existing) return {
+		path,
+		block,
+		change: null
 	};
-}
-function noInstall(cli) {
 	return {
-		state: "skipped",
-		message: `not checked: ${cli.name} declares no install`
+		path,
+		block,
+		change: existing.includes(markersOf(cli.name).begin) ? "rewrite" : "add"
 	};
 }
-function buildRow(cli) {
-	return {
-		name: "build",
-		run: () => ok(versionLine(cli))
-	};
+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 nodeRow(cli) {
+function agentsRow(cli, install) {
 	return {
-		name: "node",
-		run: () => {
-			const found = process.versions.node;
-			const range = cli.engines?.node;
-			if (range === void 0) return ok(`Node ${found}; ${cli.name} declares no engines.node to check it against`);
-			const minimum = engineMinimum(range);
-			if (minimum === void 0) return {
+		name: "agents",
+		advisory: true,
+		run: async (ctx) => {
+			const root = await projectRootOf(ctx.cwd);
+			const { path, change } = await agentsMdAt(cli, install, root);
+			const fix = `${install.runAs} skill install`;
+			if (change === "rewrite") return {
 				state: "problem",
-				message: `${cli.name} declares engines.node "${range}", which doctor cannot read: only >=X.Y.Z is supported`
+				message: `${path} holds a ${cli.name} block other than the one ${fix} writes`,
+				fix
 			};
-			if (meetsMinimum(found, minimum)) return ok(`Node ${found} meets ${range}`);
-			const major = minimum[0];
-			return {
+			if (change !== null) return {
 				state: "problem",
-				message: `${cli.name} runs on Node ${found}, older than the ${range} it needs; install Node ${minimum.join(".")} or newer and make it the default`,
-				fix: `nvm install ${major} && nvm alias default ${major}`
+				message: `${path} holds no ${cli.name} block, so sessions in this repo do not know ${cli.name}`,
+				fix
+			};
+			const holds = `${path} holds the ${cli.name} block`;
+			const [edit] = await handEditsAt(root);
+			return edit === void 0 ? {
+				state: "ok",
+				message: holds
+			} : {
+				state: "problem",
+				message: `${holds}; ${edit}`
 			};
 		}
 	};
 }
-/** A row's thrown error as its problem: a `CliError` with its hint and code, anything else a bug. */
-function problemOfError(name, error) {
-	if (error instanceof CliError) return {
-		state: "problem",
-		message: `${error.message}; ${error.hint}`,
-		code: error.code
-	};
-	return {
-		state: "problem",
-		message: `the ${name} row hit a bug: ${messageOf(error)}`
-	};
-}
-function readProject(projectFile, ctx) {
-	if (projectFile === void 0) return {
-		ok: true,
-		project: void 0
-	};
-	try {
-		return {
-			ok: true,
-			project: projectOf(projectFile, ctx.cwd, {
-				fileError: ctx.fileError,
-				callerLine: ctx.commandLine()
-			})
-		};
-	} catch (error) {
-		return {
-			ok: false,
-			error
-		};
-	}
+//#endregion
+//#region ../agent-cli/dist/agent.js
+const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
+const isSet = (name) => (env) => (env[name] ?? "") !== "";
+const equals = (name, value) => (env) => env[name] === value;
+const MARKERS = [
+	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
+	equals("AGENT", "amp"),
+	isSet("CODEX_SANDBOX"),
+	isSet("CODEX_CI"),
+	isSet("CODEX_THREAD_ID"),
+	isSet("GEMINI_CLI"),
+	isSet("COPILOT_CLI"),
+	isSet("OPENCODE"),
+	isSet("ANTIGRAVITY_AGENT"),
+	isSet("AUGMENT_AGENT"),
+	isSet("REPL_ID"),
+	isSet("CLAUDE_CODE_IS_COWORK"),
+	isSet("CLAUDECODE"),
+	isSet("CLAUDE_CODE"),
+	isSet("CURSOR_TRACE_ID"),
+	isSet("CURSOR_AGENT"),
+	equals("CURSOR_EXTENSION_HOST_ROLE", "agent-exec"),
+	equals("TERM_PROGRAM", "kiro"),
+	(env) => ["/.pi/agent", "\\.pi\\agent"].some((dir) => (env.PATH ?? "").includes(dir)),
+	isSet("GOOSE_PROVIDER")
+];
+/**
+* Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
+* in a PTY, so a TTY alone doesn't mean a person is watching.
+*/
+function isAgent(env) {
+	return MARKERS.some((marker) => marker(env));
 }
-function projectRow({ file }, read) {
-	return {
-		name: "project",
-		run: (ctx) => {
-			if (!read.ok) return problemOfError("project", read.error);
-			return ok(read.project === void 0 ? `none found: no ${file} at or above ${ctx.cwd}` : join(read.project.root, file));
-		}
-	};
-}
-function surveyOnce(bin) {
-	let survey;
-	return (install, cwd) => {
-		survey ??= surveyDependency(install, bin, cwd);
-		return survey;
-	};
-}
-function installRow(cli, { bin, node }, survey) {
-	return {
-		name: "install",
-		advisory: true,
-		run: async (ctx) => {
-			const { install } = cli;
-			if (install === void 0) return noInstall(cli);
-			if (install.mode === "dependency") return dependencyInstallFinding(cli, install, await survey(install, ctx.cwd));
-			const npm = globalNpm(cli, install, ctx, node);
-			try {
-				return ok(`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;
-			}
-		}
-	};
-}
-async function releaseLookupOf(cli, install, ctx, node, survey) {
-	if (install.mode === "global") {
-		const fix = `${cli.name} update`;
-		return {
-			npm: globalNpm(cli, install, ctx, node),
-			advise: () => ({ fix })
-		};
-	}
-	const release = dependencyRelease(cli, install, await survey(install, ctx.cwd));
-	if ("skipped" in release) return release;
-	return {
-		npm: npmContext(cli, release.registry, ctx, node, release.cwd),
-		advise: release.advise
-	};
-}
-function registryRow(cli, { node }, survey) {
-	return {
-		name: "registry",
-		advisory: true,
-		run: async (ctx) => {
-			const { install } = cli;
-			if (install === void 0) return noInstall(cli);
-			const lookup = await releaseLookupOf(cli, install, ctx, node, survey);
-			if ("skipped" in lookup) return lookup.skipped;
-			const { npm, advise } = lookup;
-			const latest = await latestVersion(npm);
-			const standing = standingOf$1(cli.version, latest);
-			const head = `${npm.registry.label} has ${latest} as latest: this build`;
-			if (standing === "behind") {
-				const message = `${head} (${cli.version}) is older`;
-				const advice = advise(latest);
-				return "fix" in advice ? {
-					state: "problem",
-					message,
-					fix: advice.fix
-				} : {
-					state: "problem",
-					message: `${message}; ${advice.note}`
-				};
-			}
-			return ok(`${head} is ${standing === "current" ? "current" : `newer (${cli.version})`}`);
-		}
-	};
-}
-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]})`;
-}
-function skillRow(cli) {
-	const packaged = packagedFolderOf(cli);
-	return {
-		name: "skill",
-		advisory: true,
-		run: async (ctx) => {
-			if (packaged !== void 0) return packagedSkillFinding(cli, packaged, ctx);
-			const { copies, fix } = await skillReport(cli, cli.version, ctx);
-			const message = copies.length === 0 ? `no copy of the ${cli.name} skill is installed` : copies.map(describeCopy).join("; ");
-			return fix === void 0 ? ok(message) : {
-				state: "ok",
-				message,
-				fix
-			};
-		}
-	};
-}
-/** Every row `doctor` reports, in order: the fixed rows around the CLI's own and its tools'. */
-function doctorChecks(cli, launch, read) {
-	const survey = surveyOnce(launch.bin);
-	return [
-		buildRow(cli),
-		nodeRow(cli),
-		...cli.project === void 0 ? [] : [projectRow(cli.project, read)],
-		...cli.doctor ?? [],
-		...toolRows(cli.tools ?? [], cli.commands),
-		installRow(cli, launch, survey),
-		registryRow(cli, launch, survey),
-		skillRow(cli),
-		...packagedFolderOf(cli) === void 0 ? [] : [agentsRow(cli)]
-	];
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/doctor.js
-const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
-const DEFAULT_DEADLINE_MS = 1e4;
-const MS_PER_SECOND = 1e3;
-const MIN_LABEL_WIDTH = 8;
-const reportSchema = object({
-	rows: array(object({
-		check: string(),
-		state: _enum([
-			"ok",
-			"problem",
-			"skipped"
-		]),
-		message: string(),
-		fix: string().optional(),
-		code: string().optional(),
-		skill: packagedSkillDetailsSchema.optional()
-	})),
-	next: array(string())
-});
-function problemOf(check, error, { signal, deadline, ms }) {
-	if (!signal.aborted && deadline.aborted && error === deadline.reason) return {
-		state: "problem",
-		message: `${check.name} did not answer within ${ms / MS_PER_SECOND} s`
-	};
-	return problemOfError(check.name, error);
-}
-function rowContext(ctx, signal, read) {
-	return Object.create(ctx, {
-		signal: { value: signal },
-		project: { get: () => {
-			if (!read.ok) throw read.error;
-			return read.project;
-		} }
-	});
-}
-async function rowOf(check, ctx, read) {
-	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
-	const signal = ctx.deadline(ms);
-	let finding;
-	try {
-		finding = await Promise.race([Promise.resolve().then(() => check.run(rowContext(ctx, signal, read))), untilAborted(signal)]);
-	} catch (error) {
-		if (ctx.signal.aborted) return void 0;
-		finding = !read.ok && error === read.error ? {
-			state: "skipped",
-			message: "the Project file is unusable; the project row says why"
-		} : problemOf(check, error, {
-			signal: ctx.signal,
-			deadline: signal,
-			ms
-		});
-	}
-	return {
-		row: {
-			check: check.name,
-			...finding
-		},
-		advisory: check.advisory === true
-	};
-}
-function nextOf(rows) {
-	return [...new Set(rows.flatMap(({ fix }) => fix === void 0 ? [] : [fix]))];
-}
-function render({ rows, next }, style) {
-	const width = Math.max(MIN_LABEL_WIDTH, ...rows.map(({ check }) => check.length)) + 2;
-	const stateWidth = Math.max(...rows.map(({ state }) => state.length)) + 2;
-	return [...rows.map(({ check, state, message }) => {
-		const label = state === "problem" ? style.red(state) : state;
-		return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
-	}), ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
-}
-function failure(cliName, callerLine, problems) {
-	const errors = problems.map(({ check, message, fix, code }) => new CliError({
-		code: code ?? "DOCTOR_PROBLEMS",
-		message: `${cliName} doctor found a problem in ${check}: ${message}`,
-		hint: fix === void 0 ? "the row says what is wrong" : `run \`${fix}\`, then run \`${callerLine}\` again`
-	}));
-	return new AggregateError(errors);
-}
-/** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
-function doctorCommand(cli, launch) {
-	return defineCommand$1({
-		name: "doctor",
-		description: "check the setup and say what fixes each problem",
-		examples: [{
-			command: `${runAsOf(cli)} doctor`,
-			note: "check the setup and list the commands that fix it"
-		}, {
-			command: `${runAsOf(cli)} doctor --json`,
-			note: "get the rows and fixes as data"
-		}],
-		effect: "read",
-		output: reportSchema,
-		run: async (_input, ctx) => {
-			const read = readProject(cli.project, ctx);
-			const checked = (await Promise.all(doctorChecks(cli, launch, read).map((check) => rowOf(check, ctx, read)))).filter((row) => row !== void 0);
-			const rows = checked.map(({ row }) => row);
-			const report = {
-				rows,
-				next: nextOf(rows)
-			};
-			if (ctx.signal.aborted) {
-				ctx.deliver(report);
-				ctx.signal.throwIfAborted();
-			}
-			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
-			if (problems.length > 0) {
-				ctx.deliver(report);
-				throw failure(cli.name, ctx.commandLine(), problems);
-			}
-			return report;
-		},
-		render
-	});
-}
-//#endregion
-//#region ../agent-cli/dist/agent.js
-const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
-const isSet = (name) => (env) => (env[name] ?? "") !== "";
-const equals = (name, value) => (env) => env[name] === value;
-const MARKERS = [
-	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
-	equals("AGENT", "amp"),
-	isSet("CODEX_SANDBOX"),
-	isSet("CODEX_CI"),
-	isSet("CODEX_THREAD_ID"),
-	isSet("GEMINI_CLI"),
-	isSet("COPILOT_CLI"),
-	isSet("OPENCODE"),
-	isSet("ANTIGRAVITY_AGENT"),
-	isSet("AUGMENT_AGENT"),
-	isSet("REPL_ID"),
-	isSet("CLAUDE_CODE_IS_COWORK"),
-	isSet("CLAUDECODE"),
-	isSet("CLAUDE_CODE"),
-	isSet("CURSOR_TRACE_ID"),
-	isSet("CURSOR_AGENT"),
-	equals("CURSOR_EXTENSION_HOST_ROLE", "agent-exec"),
-	equals("TERM_PROGRAM", "kiro"),
-	(env) => ["/.pi/agent", "\\.pi\\agent"].some((dir) => (env.PATH ?? "").includes(dir)),
-	isSet("GOOSE_PROVIDER")
-];
-/**
-* Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
-* in a PTY, so a TTY alone doesn't mean a person is watching.
-*/
-function isAgent(env) {
-	return MARKERS.some((marker) => marker(env));
-}
-//#endregion
-//#region ../agent-cli/dist/errno.js
-const PERMISSION_DENIED = "PERMISSION_DENIED";
-const DISK_FULL = "DISK_FULL";
-const NOT_FOUND = "NOT_FOUND";
-const ALREADY_EXISTS = "ALREADY_EXISTS";
-const NOT_A_FILE = "NOT_A_FILE";
-function permissionHint({ path, access, callerLine, env, platform }) {
-	if (platform === "win32") return `a program may hold ${path} open: close it, then run \`${callerLine}\` again`;
-	if (!isAgent(env)) return `check the permissions of ${path} and its folder`;
-	return `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`;
+//#endregion
+//#region ../agent-cli/dist/errno.js
+const PERMISSION_DENIED = "PERMISSION_DENIED";
+const DISK_FULL = "DISK_FULL";
+const NOT_FOUND = "NOT_FOUND";
+const ALREADY_EXISTS = "ALREADY_EXISTS";
+const NOT_A_FILE = "NOT_A_FILE";
+function permissionHint({ path, access, callerLine, env, platform }) {
+	if (platform === "win32") return `a program may hold ${path} open: close it, then run \`${callerLine}\` again`;
+	if (!isAgent(env)) return `check the permissions of ${path} and its folder`;
+	return `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`;
 }
 function fileErrorOf(scope) {
 	return (error, at) => classifyErrno(error, {
@@ -8337,22 +7902,48 @@ async function probeOutputs({ files, cwd, fileError }, outputs) {
 	}));
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/skill-install.js
-const installSchema = object({
-	copy: string(),
-	written: array(string()),
-	removed: array(string()),
-	agentsMd: object({
-		path: string(),
-		changed: boolean()
-	}),
-	handEdits: array(string())
-});
-async function sameContent(left, right) {
-	const [a, b] = await Promise.all([readFile(left), readFile(right)]);
+//#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)
+	};
+}
+/** Every file under `dir`, relative to it and sorted; none when `dir` is missing. */
+async function filesIn(dir) {
+	return (await orMissing(readdir(dir, {
+		recursive: true,
+		withFileTypes: true
+	})) ?? []).filter((entry) => entry.isFile()).map((entry) => relative(dir, join(entry.parentPath, entry.name))).sort();
+}
+/** The versions of the package's skill in `source` and of its copy in `copy`. */
+async function skillVersionsOf(source, copy) {
+	const [shipped, installed] = await Promise.all([readFile(join(source, "SKILL.md"), "utf8"), orMissing(readFile(join(copy, "SKILL.md"), "utf8"))]);
+	const packageVersion = skillVersionIn(shipped) ?? null;
+	const copyVersion = installed === void 0 ? void 0 : skillVersionIn(installed) ?? null;
+	return {
+		packageVersion,
+		copyVersion,
+		same: copyVersion === packageVersion
+	};
+}
+const installSchema = object({
+	copy: string(),
+	written: array(string()),
+	removed: array(string()),
+	agentsMd: object({
+		path: string(),
+		changed: boolean()
+	}),
+	handEdits: array(string())
+});
+async function sameContent(left, right) {
+	const [a, b] = await Promise.all([readFile(left), readFile(right)]);
 	return a.equals(b);
 }
-async function planOf(cli, folder, cwd, packageRoot) {
+async function planOf(cli, folder, install, cwd, packageRoot) {
 	const source = join(packageRoot, folder);
 	const { root, copy } = await skillCopyOf(cli, cwd);
 	const [shipped, present] = await Promise.all([filesIn(source), filesIn(copy)]);
@@ -8364,7 +7955,7 @@ async function planOf(cli, folder, cwd, packageRoot) {
 		replace: shipped.filter((_file, index) => differs[index]),
 		remove: present.filter((file) => !shipped.includes(file)),
 		sameVersion: (await skillVersionsOf(source, copy)).same,
-		agentsMd: await agentsMdAt(cli, root),
+		agentsMd: await agentsMdAt(cli, install, root),
 		handEdits: await handEditsAt(root)
 	};
 }
@@ -8404,8 +7995,8 @@ function editedRemovals(plan, ctx) {
 	});
 }
 /** The built-in `skill install`, for a CLI whose skill ships in its package. */
-function skillInstallCommand(cli, folder) {
-	const runAs = runAsOf(cli);
+function skillInstallCommand(cli, folder, install) {
+	const { runAs } = install;
 	return defineCommand$1({
 		name: "install",
 		description: "copy this CLI's skill into the project and write its AGENTS.md block",
@@ -8419,7 +8010,7 @@ function skillInstallCommand(cli, folder) {
 		effect: "write",
 		output: installSchema,
 		force: "replace or remove hand-edited files of a skill copy at the package's version",
-		plan: (_input, ctx) => planOf(cli, folder, ctx.cwd, ctx.packageRoot),
+		plan: (_input, ctx) => planOf(cli, folder, install, 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);
@@ -8428,7 +8019,7 @@ function skillInstallCommand(cli, folder) {
 			const { path, change } = plan.agentsMd;
 			if (change !== null) {
 				const existing = await orMissing(readFile(path, "utf8")) ?? "";
-				await ctx.files.write(path, withBlock(cli, existing));
+				await ctx.files.write(path, withBlock(cli, install, existing));
 			}
 			return {
 				copy: plan.copy,
@@ -8446,6 +8037,93 @@ function skillInstallCommand(cli, folder) {
 	});
 }
 //#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()
+});
+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 `folder`, which `skill install` copies to the project root. */
+function packagedSkill(cli, folder, install) {
+	return {
+		kind: "packaged",
+		builtIns: { skill: { install: skillInstallCommand(cli, folder, install) } },
+		rows: [{
+			name: "skill",
+			advisory: true,
+			run: (ctx) => findingOf(cli, folder, install, ctx)
+		}, agentsRow(cli, install)],
+		notice: (launch, ctx) => notice(cli, folder, install, launch, ctx),
+		findingAt: (_version, ctx) => findingOf(cli, folder, install, ctx)
+	};
+}
+//#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(cli, install) {
+	const { skill } = cli;
+	return skill !== void 0 && "packaged" in skill ? packagedSkill(cli, skill.packaged, install) : hubSkill(cli, skill?.source);
+}
+//#endregion
 //#region ../agent-cli/dist/interrupts.js
 const INTERRUPTED = "INTERRUPTED";
 const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
@@ -8583,6 +8261,59 @@ var RunControl = class {
 	}
 };
 //#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");
+}
+function notGlobal(ctx, message) {
+	return new CliError({
+		code: NOT_GLOBAL_INSTALL,
+		message,
+		hint: `install it with npm, so \`${ctx.cliName} update\` can replace it: ${installCommandLine(ctx.registry)}`
+	});
+}
+/**
+* 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 {
+		prefix,
+		packageDir
+	};
+}
+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}`];
+}
+function globalRegistry(install) {
+	const { package: name, registry } = 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}`
+	};
+}
+/** 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/upgrades.js
 /** A skipped release's Upgrade steps, or its whole section when it lists none. */
 const upgradeSchema = union([object({
@@ -8675,10 +8406,9 @@ function renderUpdate(cli, install, update) {
 		...next
 	]).join("\n");
 }
-async function skillNext(cli, latest, ctx) {
-	const packaged = packagedFolderOf(cli);
-	const finding = packaged === void 0 ? await skillReport(cli, latest, ctx) : await packagedSkillFinding(cli, packaged, ctx);
-	return "fix" in finding && finding.fix !== void 0 ? [finding.fix] : [];
+async function skillNext(skill, latest, ctx) {
+	const { fix } = await skill.findingAt(latest, ctx);
+	return fix === void 0 ? [] : [fix];
 }
 function interruptedAfterInstall(plan) {
 	return new CliError({
@@ -8688,7 +8418,7 @@ function interruptedAfterInstall(plan) {
 	});
 }
 /** The built-in `update`, for a CLI installed globally with npm. */
-function updateCommand(cli, install, { bin, node }) {
+function updateCommand(cli, install, skill, { bin, node }) {
 	return defineCommand$1({
 		name: "update",
 		description: "install the latest version of this CLI from its registry",
@@ -8719,7 +8449,7 @@ function updateCommand(cli, install, { bin, node }) {
 				latest,
 				installed: null,
 				upgrades: [],
-				next: await skillNext(cli, latest, ctx)
+				next: await skillNext(skill, latest, ctx)
 			};
 			ctx.signal.throwIfAborted();
 			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
@@ -8732,7 +8462,7 @@ function updateCommand(cli, install, { bin, node }) {
 					prefix
 				},
 				upgrades: await upgradesOf(plan.packageDir, from, latest),
-				next: await skillNext(cli, latest, ctx)
+				next: await skillNext(skill, latest, ctx)
 			};
 			if (ctx.signal.aborted) {
 				ctx.deliver(update);
@@ -8745,17 +8475,323 @@ function updateCommand(cli, install, { bin, node }) {
 	});
 }
 //#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 })
+			};
+		}
+	};
+}
+/** 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(cli, adapter), launch) }),
+		exitClasses: ["source"],
+		agentsCaveat: void 0,
+		check: (launch) => checkOf(cli, install, launch)
+	};
+	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`
+	});
+	return {
+		runAs: runAsOf(cli),
+		builtIns: () => ({}),
+		exitClasses: [],
+		agentsCaveat: void 0,
+		check: () => ({
+			install: skipped,
+			release: async () => ({ skipped: await skipped() })
+		})
+	};
+}
+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/doctor-rows.js
+function ok(message) {
+	return {
+		state: "ok",
+		message
+	};
+}
+function buildRow(cli) {
+	return {
+		name: "build",
+		run: () => ok(versionLine(cli))
+	};
+}
+function nodeRow(cli) {
+	return {
+		name: "node",
+		run: () => {
+			const found = process.versions.node;
+			const range = cli.engines?.node;
+			if (range === void 0) return ok(`Node ${found}; ${cli.name} declares no engines.node to check it against`);
+			const minimum = engineMinimum(range);
+			if (minimum === void 0) return {
+				state: "problem",
+				message: `${cli.name} declares engines.node "${range}", which doctor cannot read: only >=X.Y.Z is supported`
+			};
+			if (meetsMinimum(found, minimum)) return ok(`Node ${found} meets ${range}`);
+			const major = minimum[0];
+			return {
+				state: "problem",
+				message: `${cli.name} runs on Node ${found}, older than the ${range} it needs; install Node ${minimum.join(".")} or newer and make it the default`,
+				fix: `nvm install ${major} && nvm alias default ${major}`
+			};
+		}
+	};
+}
+/** A row's thrown error as its problem: a `CliError` with its hint and code, anything else a bug. */
+function problemOfError(name, error) {
+	if (error instanceof CliError) return {
+		state: "problem",
+		message: `${error.message}; ${error.hint}`,
+		code: error.code
+	};
+	return {
+		state: "problem",
+		message: `the ${name} row hit a bug: ${messageOf(error)}`
+	};
+}
+function readProject(projectFile, ctx) {
+	if (projectFile === void 0) return {
+		ok: true,
+		project: void 0
+	};
+	try {
+		return {
+			ok: true,
+			project: projectOf(projectFile, ctx.cwd, {
+				fileError: ctx.fileError,
+				callerLine: ctx.commandLine()
+			})
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+function projectRow({ file }, read) {
+	return {
+		name: "project",
+		run: (ctx) => {
+			if (!read.ok) return problemOfError("project", read.error);
+			return ok(read.project === void 0 ? `none found: no ${file} at or above ${ctx.cwd}` : join(read.project.root, file));
+		}
+	};
+}
+function installRow(check) {
+	return {
+		name: "install",
+		advisory: true,
+		run: check.install
+	};
+}
+function registryRow(cli, check) {
+	return {
+		name: "registry",
+		advisory: true,
+		run: async (ctx) => {
+			const lookup = await check.release(ctx);
+			if ("skipped" in lookup) return lookup.skipped;
+			const { npm, advise } = lookup;
+			const latest = await latestVersion(npm);
+			const standing = standingOf$1(cli.version, latest);
+			const head = `${npm.registry.label} has ${latest} as latest: this build`;
+			if (standing === "behind") {
+				const message = `${head} (${cli.version}) is older`;
+				const advice = advise(latest);
+				return "fix" in advice ? {
+					state: "problem",
+					message,
+					fix: advice.fix
+				} : {
+					state: "problem",
+					message: `${message}; ${advice.note}`
+				};
+			}
+			return ok(`${head} is ${standing === "current" ? "current" : `newer (${cli.version})`}`);
+		}
+	};
+}
+/** Every row `doctor` reports, in order: the fixed rows around the CLI's own and its tools'. */
+function doctorChecks(cli, launch, read) {
+	const install = installOf(cli);
+	const check = install.check(launch);
+	return [
+		buildRow(cli),
+		nodeRow(cli),
+		...cli.project === void 0 ? [] : [projectRow(cli.project, read)],
+		...cli.doctor ?? [],
+		...toolRows(cli.tools ?? [], cli.commands),
+		installRow(check),
+		registryRow(cli, check),
+		...skillOf(cli, install).rows
+	];
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/doctor.js
+const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
+const DEFAULT_DEADLINE_MS = 1e4;
+const MS_PER_SECOND = 1e3;
+const MIN_LABEL_WIDTH = 8;
+const reportSchema = object({
+	rows: array(object({
+		check: string(),
+		state: _enum([
+			"ok",
+			"problem",
+			"skipped"
+		]),
+		message: string(),
+		fix: string().optional(),
+		code: string().optional(),
+		skill: packagedSkillDetailsSchema.optional()
+	})),
+	next: array(string())
+});
+function problemOf(check, error, { signal, deadline, ms }) {
+	if (!signal.aborted && deadline.aborted && error === deadline.reason) return {
+		state: "problem",
+		message: `${check.name} did not answer within ${ms / MS_PER_SECOND} s`
+	};
+	return problemOfError(check.name, error);
+}
+function rowContext(ctx, signal, read) {
+	return Object.create(ctx, {
+		signal: { value: signal },
+		project: { get: () => {
+			if (!read.ok) throw read.error;
+			return read.project;
+		} }
+	});
+}
+async function rowOf(check, ctx, read) {
+	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
+	const signal = ctx.deadline(ms);
+	let finding;
+	try {
+		finding = await Promise.race([Promise.resolve().then(() => check.run(rowContext(ctx, signal, read))), untilAborted(signal)]);
+	} catch (error) {
+		if (ctx.signal.aborted) return void 0;
+		finding = !read.ok && error === read.error ? {
+			state: "skipped",
+			message: "the Project file is unusable; the project row says why"
+		} : problemOf(check, error, {
+			signal: ctx.signal,
+			deadline: signal,
+			ms
+		});
+	}
+	return {
+		row: {
+			check: check.name,
+			...finding
+		},
+		advisory: check.advisory === true
+	};
+}
+function nextOf(rows) {
+	return [...new Set(rows.flatMap(({ fix }) => fix === void 0 ? [] : [fix]))];
+}
+function render({ rows, next }, style) {
+	const width = Math.max(MIN_LABEL_WIDTH, ...rows.map(({ check }) => check.length)) + 2;
+	const stateWidth = Math.max(...rows.map(({ state }) => state.length)) + 2;
+	return [...rows.map(({ check, state, message }) => {
+		const label = state === "problem" ? style.red(state) : state;
+		return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
+	}), ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
+}
+function failure(cliName, callerLine, problems) {
+	const errors = problems.map(({ check, message, fix, code }) => new CliError({
+		code: code ?? "DOCTOR_PROBLEMS",
+		message: `${cliName} doctor found a problem in ${check}: ${message}`,
+		hint: fix === void 0 ? "the row says what is wrong" : `run \`${fix}\`, then run \`${callerLine}\` again`
+	}));
+	return new AggregateError(errors);
+}
+/** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
+function doctorCommand(cli, launch) {
+	return defineCommand$1({
+		name: "doctor",
+		description: "check the setup and say what fixes each problem",
+		examples: [{
+			command: `${runAsOf(cli)} doctor`,
+			note: "check the setup and list the commands that fix it"
+		}, {
+			command: `${runAsOf(cli)} doctor --json`,
+			note: "get the rows and fixes as data"
+		}],
+		effect: "read",
+		output: reportSchema,
+		run: async (_input, ctx) => {
+			const read = readProject(cli.project, ctx);
+			const checked = (await Promise.all(doctorChecks(cli, launch, read).map((check) => rowOf(check, ctx, read)))).filter((row) => row !== void 0);
+			const rows = checked.map(({ row }) => row);
+			const report = {
+				rows,
+				next: nextOf(rows)
+			};
+			if (ctx.signal.aborted) {
+				ctx.deliver(report);
+				ctx.signal.throwIfAborted();
+			}
+			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
+			if (problems.length > 0) {
+				ctx.deliver(report);
+				throw failure(cli.name, ctx.commandLine(), problems);
+			}
+			return report;
+		},
+		render
+	});
+}
+//#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.
 */
 function builtInCommands(cli, launch) {
-	const packaged = packagedFolderOf(cli);
+	const install = installOf(cli);
 	return {
 		doctor: doctorCommand(cli, launch),
-		...cli.install?.mode === "global" ? { update: updateCommand(cli, cli.install, launch) } : {},
-		...packaged === void 0 ? {} : { skill: { install: skillInstallCommand(cli, packaged) } }
+		...install.builtIns(launch),
+		...skillOf(cli, install).builtIns
 	};
 }
 //#endregion
@@ -8879,7 +8915,7 @@ function reachableExitClasses(cli) {
 		"caller",
 		"operator",
 		"wait",
-		...cli.commands !== void 0 && cli.install !== void 0 ? ["source"] : []
+		...cli.commands === void 0 ? [] : installOf(cli).exitClasses
 	];
 	const own = Object.values(cli.errors ?? {}).map((declaration) => declaration.class);
 	return /* @__PURE__ */ new Set([...runtime, ...own]);
@@ -8905,7 +8941,7 @@ function checkOwnCodes(cli) {
 function defineCli$1(cli) {
 	checkOwnCodes(cli);
 	if (cli.commands === void 0) {
-		if (packagedFolderOf(cli) !== void 0) throw new Error(`${cli.name} declares a Packaged skill, which only a CLI with several Commands can install`);
+		if (skillOf(cli, installOf(cli)).kind === "packaged") throw new Error(`${cli.name} declares a Packaged skill, which only a CLI with several Commands can install`);
 		return cli;
 	}
 	const { commands } = cli;
@@ -10023,7 +10059,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	let served = false;
 	let settled;
 	try {
-		const outcome = await control.settle(noticeSkillCopy(cli, {
+		const outcome = await control.settle(skillOf(cli, installOf(cli)).notice({
 			builtIn,
 			bin: options.bin
 		}, ctx).then(() => execute(command, input, ctx, {
@@ -10222,14 +10258,14 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.15.0";
+var version$1 = "0.15.1";
 var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "cd3df50",
+	"sha": "da48f36",
 	"dirty": false,
-	"builtAt": "2026-10-27T04:23:15.000Z"
+	"builtAt": "2026-10-27T08:31:19.000Z"
 };
 //#endregion
 //#region src/fill.ts