@duyquangnvx/create-agent-cli 0.14.0 → 0.15.1

package/dist/bin.js

@@ -5869,13 +5869,22 @@ function debugTrace(error, format) {
 function errorsOf(error) {
 	return error instanceof AggregateError && error.errors.length > 0 ? error.errors.flatMap(errorsOf) : [error];
 }
+/** The `details` field that `error`'s code declares for text mode to print, when it holds a string. */
+function printedDetail(error, format) {
+	if (!(error instanceof CliError)) return void 0;
+	const key = format.errors[error.code]?.print;
+	const { details } = error;
+	if (key === void 0 || typeof details !== "object" || details === null) return void 0;
+	const value = Reflect.get(details, key);
+	return typeof value === "string" ? value : void 0;
+}
 function errorLines(error, format) {
 	const fields = fieldsOf$1(error, format);
-	const stack = debugTrace(error, format);
+	const blocks = [printedDetail(error, format), debugTrace(error, format)].filter((block) => block !== void 0);
 	const { style } = format;
 	const label = style.red(format.isBug(error) ? "internal error:" : "error:");
-	const trace = stack === void 0 ? "" : `${stack}\n`;
-	return `${label} ${fields.message}\n${trace}${style.cyan("hint:")} ${fields.hint}\n`;
+	const between = blocks.map((block) => `${block}\n`).join("");
+	return `${label} ${fields.message}\n${between}${style.cyan("hint:")} ${fields.hint}\n`;
 }
 function formatRuntimeError(error, format) {
 	const errors = errorsOf(error);
@@ -6487,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) {
@@ -6610,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) {
@@ -6994,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([
@@ -7013,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 [
@@ -7177,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(" ")}`,
@@ -7245,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;
@@ -7293,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;
@@ -7332,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
@@ -7386,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":
@@ -7396,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;
@@ -7426,16 +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) };
+function checkOf$1(cli, install, runAs, { bin, node }) {
+	let survey;
+	const surveyed = (cwd) => {
+		survey ??= surveyDependency(install, bin, cwd);
+		return survey;
+	};
+	return {
+		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)
+			};
+		}
+	};
+}
+/** 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 {
-		registry: registryOf(install, root?.dir),
-		cwd: root?.dir ?? cwd,
-		advise: (latest) => adviceFor(install, root, latest)
+		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;
@@ -7493,411 +7453,123 @@ 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;
+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 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 {
-		copies,
-		fix: fixFor(cli.name, copies, source)
+		kind: "hub",
+		builtIns: {},
+		rows: [{
+			name: "skill",
+			advisory: true,
+			run: (ctx) => findingAt(cli.version, ctx)
+		}],
+		notice: async () => {},
+		findingAt
 	};
 }
 //#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;
+//#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 project root and the Skill copy under it, as `skill install` writes it. */
-async function skillCopyOf(cli, cwd) {
-	const root = await projectRootOf(cwd);
+function markersOf(name) {
 	return {
-		root,
-		copy: join(root, ".claude", "skills", cli.name)
+		begin: `<!-- BEGIN:${name} -->`,
+		end: `<!-- END:${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();
+/** `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 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;
+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"
+	};
+	if (withBlock(cli, install, existing) === existing) return {
+		path,
+		block,
+		change: null
+	};
 	return {
-		packageVersion,
-		copyVersion,
-		same: copyVersion === packageVersion
+		path,
+		block,
+		change: existing.includes(markersOf(cli.name).begin) ? "rewrite" : "add"
 	};
 }
-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;
+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`];
 }
-/** What the `skill` row of a Packaged skill carries under `--json` beside its message. */
-const packagedSkillDetailsSchema = object({
-	copy: string(),
-	copyVersion: string().nullable(),
-	packageVersion: string().nullable(),
-	/** A personal copy, which Claude Code prefers over the project's. */
-	home: string().optional()
-});
-function versionLabel(version) {
-	return version ?? "(no metadata.version)";
-}
-function compared(name, { copy, copyVersion, packageVersion }, same) {
-	const stated = `${copy} ${versionLabel(copyVersion)}`;
-	return same ? `${stated}, the version ${name} ships` : `${stated} differs from the ${versionLabel(packageVersion)} that ${name} ships`;
-}
-/** The `skill` row of a Packaged skill: the project root's copy against the package's, and any under home. */
-async function packagedSkillFinding(cli, folder, ctx) {
-	const { copy } = await skillCopyOf(cli, ctx.cwd);
-	const versions = await skillVersionsOf(join(ctx.packageRoot, folder), copy);
-	const { packageVersion } = versions;
-	const copyVersion = versions.copyVersion ?? null;
-	const home = await personalCopyOf(cli.name, copy, ctx);
-	const skill = {
-		copy,
-		copyVersion,
-		packageVersion,
-		...home === void 0 ? {} : { home }
-	};
-	const head = versions.copyVersion === void 0 ? `no copy of the ${cli.name} skill at ${copy}` : compared(cli.name, skill, versions.same);
-	const message = home === void 0 ? head : `${head}; remove ${home}: Claude Code prefers a personal skill over the project's`;
-	if (!versions.same) return {
-		state: "problem",
-		message,
-		fix: `${runAsOf(cli)} skill install`,
-		skill
-	};
-	return home === void 0 ? {
-		state: "ok",
-		message,
-		skill
-	} : {
-		state: "problem",
-		message,
-		skill
-	};
-}
-//#endregion
-//#region ../agent-cli/dist/built-ins/doctor-rows.js
-function ok(message) {
-	return {
-		state: "ok",
-		message
-	};
-}
-function noInstall(cli) {
-	return {
-		state: "skipped",
-		message: `not checked: ${cli.name} declares no install`
-	};
-}
-function buildRow(cli) {
+function agentsRow(cli, install) {
 	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 {
+		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
 			};
-		}
-	};
-}
-/** 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 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) : {
+			const holds = `${path} holds the ${cli.name} block`;
+			const [edit] = await handEditsAt(root);
+			return edit === void 0 ? {
 				state: "ok",
-				message,
-				fix
+				message: holds
+			} : {
+				state: "problem",
+				message: `${holds}; ${edit}`
 			};
 		}
 	};
 }
-/** 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)
-	];
-}
-//#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;
@@ -8230,7 +7902,33 @@ async function probeOutputs({ files, cwd, fileError }, outputs) {
 	}));
 }
 //#endregion
-//#region ../agent-cli/dist/built-ins/skill-install.js
+//#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()),
@@ -8245,46 +7943,11 @@ async function sameContent(left, right) {
 	const [a, b] = await Promise.all([readFile(left), readFile(right)]);
 	return a.equals(b);
 }
-/** One paragraph telling every session that the CLI exists, how to run it and which skill to load. */
-function agentsBlock(cli) {
-	const { install } = cli;
-	const where = install?.mode === "dependency" ? `, and only from a package that has \`${install.package}\` in its dependencies; from anywhere else npx reports the package missing` : "";
-	const what = cli.description.replace(/\.$/, "");
-	return `\`${cli.name}\`: ${what}. Run it as \`${runAsOf(cli)}\`${where}. Load the \`${cli.name}\` skill before using it.`;
-}
-function markersOf(name) {
-	return {
-		begin: `<!-- BEGIN:${name} -->`,
-		end: `<!-- END:${name} -->`
-	};
-}
-/** `text` with the block between its markers, appended when they are missing; nothing else changes. */
-function withBlock(text, block, { begin, end }) {
-	const whole = `${begin}\n${block}\n${end}`;
-	const start = text.indexOf(begin);
-	const stop = start === -1 ? -1 : text.indexOf(end, start);
-	if (stop !== -1) return `${text.slice(0, start)}${whole}${text.slice(stop + end.length)}`;
-	if (text === "") return `${whole}\n`;
-	return `${text}${text.endsWith("\n") ? "" : "\n"}\n${whole}\n`;
-}
-function blockChangeOf(existing, block, markers) {
-	if (existing === void 0) return "create";
-	if (withBlock(existing, block, markers) === existing) return null;
-	return existing.includes(markers.begin) ? "rewrite" : "add";
-}
-async function handEditsAt(root) {
-	const claudeMd = join(root, "CLAUDE.md");
-	const text = await orMissing(readFile(claudeMd, "utf8"));
-	if (text === void 0 || text.split(/\r?\n/).some((line) => line.trim() === "@AGENTS.md")) return [];
-	return [`add a line \`@AGENTS.md\` to ${claudeMd}, so Claude Code reads AGENTS.md`];
-}
-async function planOf(cli, folder, cwd, packageRoot) {
+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)]);
 	const differs = await Promise.all(shipped.map(async (file) => present.includes(file) && !await sameContent(join(source, file), join(copy, file))));
-	const agentsPath = join(root, "AGENTS.md");
-	const block = agentsBlock(cli);
 	return {
 		source,
 		copy,
@@ -8292,11 +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: {
-			path: agentsPath,
-			block,
-			change: blockChangeOf(await orMissing(readFile(agentsPath, "utf8")), block, markersOf(cli.name))
-		},
+		agentsMd: await agentsMdAt(cli, install, root),
 		handEdits: await handEditsAt(root)
 	};
 }
@@ -8336,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",
@@ -8351,16 +8010,16 @@ 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);
 			for (const file of [...plan.write, ...plan.replace]) await ctx.files.write(join(plan.copy, file), await readFile(join(plan.source, file)));
 			for (const file of plan.remove) await ctx.files.remove(join(plan.copy, file));
-			const { path, block, change } = plan.agentsMd;
+			const { path, change } = plan.agentsMd;
 			if (change !== null) {
 				const existing = await orMissing(readFile(path, "utf8")) ?? "";
-				await ctx.files.write(path, withBlock(existing, block, markersOf(cli.name)));
+				await ctx.files.write(path, withBlock(cli, install, existing));
 			}
 			return {
 				copy: plan.copy,
@@ -8378,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";
@@ -8515,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({
@@ -8565,115 +8364,420 @@ function upgradeOf({ version, lines }) {
 		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;
+/**
+* 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);
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/update.js
+const updateSchema = object({
+	from: string(),
+	latest: string(),
+	installed: object({
+		version: string(),
+		prefix: string()
+	}).nullable(),
+	upgrades: array(upgradeSchema),
+	next: array(string())
+});
+function nothingToInstall({ from, latest }) {
+	return standingOf$1(from, latest) === "current" ? `already on ${from}, the latest release: nothing to install` : `${from} is newer than the latest release ${latest}: nothing to install`;
+}
+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}`;
+}
+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");
+}
+async function skillNext(skill, latest, ctx) {
+	const { fix } = await skill.findingAt(latest, ctx);
+	return fix === void 0 ? [] : [fix];
+}
+function interruptedAfterInstall(plan) {
+	return new CliError({
+		code: INTERRUPTED,
+		message: `interrupted, but ${plan.package}@${plan.latest} had already been installed with the npm under ${plan.prefix}, replacing ${plan.from}`,
+		hint: "nothing to run again: run the commands under next"
+	});
+}
+/** The built-in `update`, for a CLI installed globally with npm. */
+function updateCommand(cli, install, skill, { bin, node }) {
+	return defineCommand$1({
+		name: "update",
+		description: "install the latest version of this CLI from its registry",
+		examples: [{
+			command: `${cli.name} update`,
+			note: "install the latest version and show what changed"
+		}, {
+			command: `${cli.name} update --dry-run`,
+			note: "show the version it would install"
+		}],
+		effect: "write",
+		output: updateSchema,
+		plan: async (_input, ctx) => {
+			const npm = globalNpm(cli, install, ctx, node);
+			const copy = await globalInstallOf(bin, npm);
+			return {
+				package: install.package,
+				from: cli.version,
+				latest: await latestVersion(npm),
+				prefix: copy.prefix,
+				packageDir: copy.packageDir
+			};
+		},
+		apply: async (plan, ctx) => {
+			const { from, latest, prefix } = plan;
+			if (standingOf$1(from, latest) !== "behind") return {
+				from,
+				latest,
+				installed: null,
+				upgrades: [],
+				next: await skillNext(skill, latest, ctx)
+			};
+			ctx.signal.throwIfAborted();
+			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
+			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, globalNpm(cli, install, ctx, node)));
+			const update = {
+				from,
+				latest,
+				installed: {
+					version: latest,
+					prefix
+				},
+				upgrades: await upgradesOf(plan.packageDir, from, latest),
+				next: await skillNext(skill, latest, ctx)
+			};
+			if (ctx.signal.aborted) {
+				ctx.deliver(update);
+				throw interruptedAfterInstall(plan);
+			}
+			return update;
+		},
+		render: (update) => renderUpdate(cli, install, update),
+		renderPlan: (plan) => standingOf$1(plan.from, plan.latest) === "behind" ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}, replacing ${plan.from}` : nothingToInstall(plan)
+	});
+}
+//#endregion
+//#region ../agent-cli/dist/built-ins/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 {
-		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
+		return {
+			ok: true,
+			project: projectOf(projectFile, ctx.cwd, {
+				fileError: ctx.fileError,
+				callerLine: ctx.commandLine()
+			})
+		};
 	} catch (error) {
-		if (isMissingFile(error)) return [];
-		throw error;
+		return {
+			ok: false,
+			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 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/update.js
-const updateSchema = object({
-	from: string(),
-	latest: string(),
-	installed: object({
-		version: string(),
-		prefix: string()
-	}).nullable(),
-	upgrades: array(upgradeSchema),
+//#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 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 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 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}`;
+function rowContext(ctx, signal, read) {
+	return Object.create(ctx, {
+		signal: { value: signal },
+		project: { get: () => {
+			if (!read.ok) throw read.error;
+			return read.project;
+		} }
+	});
 }
-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");
+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
+	};
 }
-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] : [];
+function nextOf(rows) {
+	return [...new Set(rows.flatMap(({ fix }) => fix === void 0 ? [] : [fix]))];
 }
-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 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");
 }
-/** The built-in `update`, for a CLI installed globally with npm. */
-function updateCommand(cli, install, { bin, node }) {
+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: "update",
-		description: "install the latest version of this CLI from its registry",
+		name: "doctor",
+		description: "check the setup and say what fixes each problem",
 		examples: [{
-			command: `${cli.name} update`,
-			note: "install the latest version and show what changed"
+			command: `${runAsOf(cli)} doctor`,
+			note: "check the setup and list the commands that fix it"
 		}, {
-			command: `${cli.name} update --dry-run`,
-			note: "show the version it would install"
+			command: `${runAsOf(cli)} doctor --json`,
+			note: "get the rows and fixes as data"
 		}],
-		effect: "write",
-		output: updateSchema,
-		plan: async (_input, ctx) => {
-			const npm = globalNpm(cli, install, ctx, node);
-			const copy = await globalInstallOf(bin, npm);
-			return {
-				package: install.package,
-				from: cli.version,
-				latest: await latestVersion(npm),
-				prefix: copy.prefix,
-				packageDir: copy.packageDir
-			};
-		},
-		apply: async (plan, ctx) => {
-			const { from, latest, prefix } = plan;
-			if (standingOf$1(from, latest) !== "behind") return {
-				from,
-				latest,
-				installed: null,
-				upgrades: [],
-				next: await skillNext(cli, latest, ctx)
-			};
-			ctx.signal.throwIfAborted();
-			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
-			await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, globalNpm(cli, install, ctx, node)));
-			const update = {
-				from,
-				latest,
-				installed: {
-					version: latest,
-					prefix
-				},
-				upgrades: await upgradesOf(plan.packageDir, from, latest),
-				next: await skillNext(cli, latest, ctx)
+		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(update);
-				throw interruptedAfterInstall(plan);
+				ctx.deliver(report);
+				ctx.signal.throwIfAborted();
 			}
-			return update;
+			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: (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
 	});
 }
 //#endregion
@@ -8683,11 +8787,11 @@ function updateCommand(cli, install, { bin, node }) {
 * `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
@@ -8811,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]);
@@ -8837,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;
@@ -8860,7 +8964,10 @@ function agentCli() {
 }
 //#endregion
 //#region ../agent-cli/dist/error-table.js
-/** Keeps each code's literal class and `details` schema, so `cliError` can type its throw sites. */
+/**
+* Keeps each code's literal class and `details` schema, so `cliError` can type its throw sites;
+* `print` must name a string key of the code's `details`.
+*/
 function defineErrors(table) {
 	return table;
 }
@@ -9952,7 +10059,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	let served = false;
 	let settled;
 	try {
-		const outcome = await control.settle(execute(command, input, ctx, {
+		const outcome = await control.settle(skillOf(cli, installOf(cli)).notice({
+			builtIn,
+			bin: options.bin
+		}, ctx).then(() => execute(command, input, ctx, {
 			dryRun: flags.dryRun,
 			confirm: flags.confirm,
 			yes: flags.yes,
@@ -9965,7 +10075,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			},
 			files,
 			guardOutputs: outputs.guard
-		}));
+		})));
 		if (served) return {
 			result: STOPPED_RESULT,
 			finishSideTask
@@ -10148,14 +10258,14 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.14.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": "f114cf0",
+	"sha": "da48f36",
 	"dirty": false,
-	"builtAt": "2026-10-27T02:06:04.000Z"
+	"builtAt": "2026-10-27T08:31:19.000Z"
 };
 //#endregion
 //#region src/fill.ts