@duyquangnvx/create-agent-cli 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.23.0 (2026-11-03)
+
+### Added
+
+- A Global install of a CLI with several Commands runs a Release check: at most once a day a run asks the Install registry, in a detached process, for the latest release, and later runs give the Notice ``<cli> X.Y.Z is out, this is A.B.C; run `<cli> update` `` while the CLI is behind. No run waits on it. `CI`, or `<NAME>_NO_RELEASE_CHECK=1` for one CLI, turns it off; it keeps its answer in `$XDG_CACHE_HOME/<name>/release-check.json`, by default under `~/.cache`.
+
+## v0.22.0 (2026-11-02)
+
+### Added
+
+- The hint of `UNKNOWN_OPTION`, `UNKNOWN_COMMAND` and `INVALID_INPUT` names each Skill copy whose `metadata.version` differs from the build's, for a Skill Hub or a Packaged skill, and says to run `doctor` to update it. A CLI's skill can drop its line on a flag or Command it names that the CLI does not know.
+- The scaffolded setup reference of a Global install says what to do when the user installed the CLI but the shell finds none, under nvm. A CLI's skill can drop its own `command not found` row.
+
+### Changed
+
+- `REGISTRY_AUTH` from npm's `E403` under a Coding agent hints that the agent's sandbox may refuse the registry: the user types `!` and runs it again, or allows the registry in the sandbox's network list, and logs in only if it fails outside the sandbox too. `update`, the install and `doctor`'s `registry` row all give it. A CLI's skill can drop its row saying that `REGISTRY_AUTH` is no refused login, and its `INTERNAL` row too: that hint already names `<NAME>_DEBUG=1`.
+- The scaffolded skill drops what the agent sees anyway: `SKILL.md` loses its When to use section, which belongs in the description, its paragraph on `--json`, `--dry-run` and `--confirm`, and its description of the error format; the setup reference's Check no longer describes `doctor`'s rows. The shipping guide says a skill line earns its place only when no `--help`, output, hint or `doctor` row says it.
+
 ## v0.21.0 (2026-10-29)
 
 ### Added

package/dist/bin.js

@@ -5959,8 +5959,12 @@ async function orMissing(pending) {
 function isNothingThere(error) {
 	return isMissingFile(error) || errnoOf(error) === "ENOTDIR";
 }
+/** The CLI's own environment variable, such as `TOOL_DEBUG` for `cliVariable("tool", "DEBUG")`. */
+function cliVariable(cliName, suffix) {
+	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_${suffix}`;
+}
 function debugVariable(cliName) {
-	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
+	return cliVariable(cliName, "DEBUG");
 }
 function messageOf(error) {
 	return error instanceof Error ? error.message : String(error);
@@ -7081,9 +7085,9 @@ function secretRows(secrets, commands) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "75fd8d7",
+		"sha": "71583a7",
 		"dirty": false,
-		"builtAt": "2026-10-29T03:29:07.000Z"
+		"builtAt": "2026-11-03T06:40:47.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -7092,6 +7096,40 @@ function versionLine({ version }) {
 	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
 }
 //#endregion
+//#region ../agent-cli/dist/context/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/built-ins/semver.js
 const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
 const ENGINE = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
@@ -7231,8 +7269,14 @@ function tail$1(stderr) {
 	const lines = lastLines(stderr, STDERR_TAIL_LINES);
 	return lines === "" ? "" : `\n${lines}`;
 }
+function authHint(code, ctx) {
+	const { label: registry, loginHint } = ctx.registry;
+	const login = `${loginHint}, then ${RUN_AGAIN}`;
+	if (code !== "E403" || !isAgent(ctx.env)) return login;
+	return `a Coding agent's sandbox may refuse ${registry} with a 403: ask your user to type ! and ${RUN_AGAIN}, or to allow ${registry} in the sandbox's network list; if it fails outside the sandbox too, ${login}`;
+}
 function failureOf(call, answer, ctx) {
-	const { label: registry, package: name, loginHint, unreachableHint } = ctx.registry;
+	const { label: registry, package: name, unreachableHint } = ctx.registry;
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
 	const next = [ctx.rerun];
@@ -7245,7 +7289,7 @@ function failureOf(call, answer, ctx) {
 	if (code !== void 0 && AUTH_CODES.has(code)) return new CliError({
 		code: REGISTRY_AUTH,
 		message: `${registry} refused npm's credentials (${code})${output}`,
-		hint: `${loginHint}, then ${RUN_AGAIN}`,
+		hint: authHint(code, ctx),
 		next
 	});
 	if (call === "view" && code === "E404") return noLatest(ctx, `npm found no ${name}@latest on ${registry}: no version of it is published there`);
@@ -7321,15 +7365,18 @@ async function installGlobally(version, ctx) {
 		...ctx.registry.flags
 	], ctx, null);
 }
-async function latestVersion(ctx) {
-	const { package: name, label: registry, flags } = ctx.registry;
-	const answer = await runNpm("view", [
+function latestViewArgs({ package: name, flags }) {
+	return [
 		"view",
 		`${name}@latest`,
 		"version",
 		"--json",
 		...flags
-	], ctx);
+	];
+}
+async function latestVersion(ctx) {
+	const { package: name, label: registry } = ctx.registry;
+	const answer = await runNpm("view", latestViewArgs(ctx.registry), ctx);
 	const version = versionInViewAnswer(answer);
 	if (version === void 0) throw noLatest(ctx, `npm answered no version for ${name}@latest on ${registry}: ${answer.trim()}`);
 	return version;
@@ -7571,7 +7618,8 @@ function dependencyInstall(cli, install) {
 		runAs,
 		builtIns: () => ({}),
 		exitClasses: [],
-		check: (launch) => checkOf$1(cli, install, runAs, launch)
+		check: (launch) => checkOf$1(cli, install, runAs, launch),
+		notice: async () => {}
 	};
 }
 //#endregion
@@ -7669,6 +7717,7 @@ function hubSkill(cli, from) {
 			run: async (ctx) => findingOf(await skillCopies(cli.name, cli.version, ctx))
 		}],
 		notice: async () => {},
+		differing: async (place) => (await skillCopies(cli.name, cli.version, place)).filter(({ state }) => state !== "current" && state !== "unreadable").map(describeCopy),
 		nextAt: async (version, ctx) => {
 			const copies = await skillCopies(cli.name, version, ctx);
 			const fix = fixFor(cli.name, copies, from);
@@ -7751,40 +7800,6 @@ function agentsRow(agents, install) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/context/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/context/errno.js
 const PERMISSION_DENIED = "PERMISSION_DENIED";
 const DISK_FULL = "DISK_FULL";
@@ -8305,6 +8320,15 @@ function packagedSkill(cli, { packaged: folder, agents: text }, install) {
 			run: (ctx) => findingOf(cli, folder, install, ctx)
 		}, ...agents === void 0 ? [] : [agentsRow(agents, install)]],
 		notice: (launch, ctx) => notice(cli, folder, install, launch, ctx),
+		differing: async ({ cwd, packageRoot }) => {
+			const { copy } = await skillCopyOf(cli, cwd);
+			const { copyVersion, packageVersion, same } = await skillVersionsOf(join(packageRoot, folder), copy);
+			return copyVersion === void 0 || same ? [] : [compared(cli.name, {
+				copy,
+				copyVersion,
+				packageVersion
+			}, false)];
+		},
 		nextAt: async (_version, ctx) => {
 			const { fix } = await findingOf(cli, folder, install, ctx);
 			return fix === void 0 ? [] : [fix];
@@ -8672,6 +8696,127 @@ function updateCommand(cli, install, skill, { bin, node }) {
 	});
 }
 //#endregion
+//#region ../agent-cli/dist/built-ins/install/release-check.js
+const CHECK_INTERVAL_MS = 864e5;
+const checkSchema = object({
+	checkedAt: number(),
+	latest: string().optional(),
+	error: string().optional()
+});
+const CHECK_SCRIPT = `
+const { spawnSync } = require("node:child_process");
+const { mkdtempSync, renameSync, rmSync, writeFileSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+const [file, checkedAt, previous, npm, ...args] = process.argv.slice(1);
+const windows = process.platform === "win32";
+const cache = mkdtempSync(join(tmpdir(), "release-check-"));
+const write = (check) => {
+  const temp = file + "." + process.pid + ".tmp";
+  writeFileSync(temp, JSON.stringify({ checkedAt: Number(checkedAt), ...check }));
+  renameSync(temp, file);
+};
+const latestOf = (stdout) => {
+  try {
+    const parsed = JSON.parse(stdout);
+    const latest = Array.isArray(parsed) ? parsed.at(-1) : parsed;
+    return typeof latest === "string" && /^\\d+\\.\\d+\\.\\d+/.test(latest) ? latest : undefined;
+  } catch {
+    return undefined;
+  }
+};
+try {
+  const answer = spawnSync(windows ? '"' + npm + '"' : npm, args, {
+    encoding: "utf8",
+    shell: windows,
+    windowsHide: true,
+    env: { ...process.env, npm_config_cache: join(cache, "cache"), npm_config_logs_max: "0" },
+  });
+  const latest = answer.status === 0 ? latestOf(answer.stdout) : undefined;
+  if (latest !== undefined) {
+    write({ latest });
+  } else {
+    const said = (answer.stderr || "").trim().split(/\\r?\\n/).slice(0, 5).join("; ");
+    const error = answer.error ? answer.error.message : said || "npm answered " + answer.stdout.trim();
+    write({ latest: previous || undefined, error });
+  }
+} finally {
+  rmSync(cache, { recursive: true, force: true });
+}
+`;
+function isOff(cliName, env) {
+	return Boolean(env[cliVariable(cliName, "NO_RELEASE_CHECK")] || env.CI);
+}
+function cacheFileOf(cliName, env) {
+	const cache = env.XDG_CACHE_HOME || join(env.HOME || env.USERPROFILE || homedir(), ".cache");
+	return join(cache, cliName, "release-check.json");
+}
+function parsedCheck(text) {
+	try {
+		return checkSchema.safeParse(JSON.parse(text)).data;
+	} catch {
+		return;
+	}
+}
+async function lastCheck(file) {
+	const text = await orMissing(readFile(file, "utf8"));
+	return text === void 0 ? void 0 : parsedCheck(text);
+}
+async function writeCheck(file, check) {
+	await mkdir(dirname(file), { recursive: true });
+	const temp = tempPathOf(file);
+	await writeFile(temp, JSON.stringify(check));
+	await rename(temp, file);
+}
+async function startCheck(cli, install, file, last, { node }, ctx) {
+	const checkedAt = ctx.clock.now();
+	const previous = last?.latest ?? "";
+	await writeCheck(file, {
+		checkedAt,
+		latest: last?.latest
+	});
+	const npm = globalNpm(cli, install, ctx, node);
+	const { path, env } = npmOf(npm, process.platform === "win32");
+	await ctx.spawnDetached(process.execPath, [
+		"-e",
+		CHECK_SCRIPT,
+		file,
+		String(checkedAt),
+		previous,
+		path,
+		...latestViewArgs(npm.registry)
+	], { env });
+}
+function debugLine(cli, ctx, text) {
+	if (isDebug({
+		env: ctx.env,
+		cliName: cli.name
+	})) ctx.progress(`release check failed: ${text}`);
+}
+/**
+* Tells the caller of a newer release that an earlier Release check found, and starts the next
+* check once the last is a day old.
+*/
+async function releaseCheck(cli, install, runAs, launch, ctx) {
+	if (launch.builtIn || launch.bin === void 0 || cli.commands === void 0) return;
+	if (isOff(cli.name, ctx.env)) return;
+	try {
+		await checkAndTell(cli, install, runAs, launch, ctx);
+	} catch (error) {
+		if (errnoOf(error) === void 0 && !(error instanceof CliError)) throw error;
+		debugLine(cli, ctx, messageOf(error));
+	}
+}
+async function checkAndTell(cli, install, runAs, launch, ctx) {
+	const file = cacheFileOf(cli.name, ctx.env);
+	const last = await lastCheck(file);
+	if (last?.error !== void 0) debugLine(cli, ctx, last.error);
+	if (last === void 0 || ctx.clock.now() - last.checkedAt >= CHECK_INTERVAL_MS) await startCheck(cli, install, file, last, launch, ctx);
+	const latest = last?.latest;
+	if (latest === void 0 || !isVersion(latest) || compareVersions(latest, cli.version) <= 0) return;
+	ctx.notice(`${cli.name} ${latest} is out, this is ${cli.version}; run \`${runAs} update\``);
+}
+//#endregion
 //#region ../agent-cli/dist/built-ins/install/global.js
 function checkOf(cli, install, { bin, node }) {
 	return {
@@ -8706,12 +8851,14 @@ function globalInstall(cli, install) {
 		runAs: runAsOf(cli),
 		builtIns: (launch) => ({ update: updateCommand(cli, install, skillOf$1(cli, adapter), launch) }),
 		exitClasses: ["source"],
-		check: (launch) => checkOf(cli, install, launch)
+		check: (launch) => checkOf(cli, install, launch),
+		notice: (launch, ctx) => releaseCheck(cli, install, adapter.runAs, launch, ctx)
 	};
 	return adapter;
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/install/install.js
+const noNotice = async () => {};
 function noInstall(cli) {
 	const skipped = async () => ({
 		state: "skipped",
@@ -8724,7 +8871,8 @@ function noInstall(cli) {
 		check: () => ({
 			install: skipped,
 			release: async () => ({ skipped: await skipped() })
-		})
+		}),
+		notice: noNotice
 	};
 }
 function installOf(cli) {
@@ -9356,6 +9504,30 @@ function startSideTask(sideTask, runWith, { clock, failed }) {
 	};
 }
 //#endregion
+//#region ../agent-cli/dist/built-ins/skill/usage-hint.js
+const SKILL_USAGE_CODES = /* @__PURE__ */ new Set([
+	UNKNOWN_OPTION,
+	UNKNOWN_COMMAND,
+	INVALID_INPUT
+]);
+/** A usage error whose hint names each Skill copy that differs from this build, since one may have named the input. */
+async function withDifferingSkill(error, cli, place, runAs) {
+	if (!(error instanceof UsageError) || !SKILL_USAGE_CODES.has(error.code)) return error;
+	let differing;
+	try {
+		differing = await skillOf$1(cli, installOf(cli)).differing(place);
+	} catch (lookup) {
+		if (errnoOf(lookup) === void 0) throw lookup;
+		return error;
+	}
+	if (differing.length === 0) return error;
+	return new UsageError({
+		code: error.code,
+		message: error.message,
+		hint: `${error.hint}; the ${cli.name} skill may name what this build does not know: ${differing.join("; ")}; run \`${runAs} doctor\` to see how to update it`
+	});
+}
+//#endregion
 //#region ../agent-cli/dist/command-line/suggest.js
 const MAX_DISTANCE = 3;
 const MIN_SIMILARITY = .4;
@@ -11066,7 +11238,11 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			});
 		});
 	} catch (error) {
-		return failed(error, noSideTask);
+		return failed(await withDifferingSkill(error, cli, {
+			cwd,
+			env,
+			packageRoot
+		}, invocation.runAs), noSideTask);
 	}
 	const { input, flags } = parsed;
 	resumed = command.deadline?.resume(input, rerunOf);
@@ -11134,9 +11310,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	let served = false;
 	let settled;
 	try {
-		const outcome = await control.settle(skillOf$1(cli, installOf(cli)).notice({
+		const outcome = await control.settle(noticesOf(cli, {
 			builtIn,
-			bin: options.bin
+			bin: options.bin,
+			node: options.node
 		}, ctx).then(() => execute(command, input, ctx, {
 			dryRun: flags.dryRun,
 			confirm: flags.confirm,
@@ -11196,6 +11373,11 @@ function once(build) {
 		throw outcome.error;
 	};
 }
+async function noticesOf(cli, launch, ctx) {
+	const install = installOf(cli);
+	await skillOf$1(cli, install).notice(launch, ctx);
+	await install.notice(launch, ctx);
+}
 //#endregion
 //#region ../agent-cli/dist/style.js
 function colourEnabled(env, stdoutIsTTY) {
@@ -11278,10 +11460,16 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 			...format,
 			json: routed.json
 		}));
-		case "usage error": return ranAlone(errorResult(routed.error, {
-			...misused(routed.node),
-			json: routed.json
-		}));
+		case "usage error": {
+			const place = {
+				...options,
+				packageRoot: packageRootOf(options.bin, options.cwd)
+			};
+			return ranAlone(errorResult(await withDifferingSkill(routed.error, cli, place, runAs), {
+				...misused(routed.node),
+				json: routed.json
+			}));
+		}
 		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(cli, routed, options, write, misused(routed.spec)));
 	}
 }
@@ -11344,7 +11532,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.21.0",
+	version: "0.23.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.21.0",
+    "@duyquangnvx/agent-cli": "0.23.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },

package/partials/global/installSteps.md

@@ -1,6 +1,6 @@
 This installs the CLI. The user has installed this skill already.
 
-1. Run `node --version` and compare it with the range `npm view {{packageName}} engines.node` prints, which `doctor`'s `node` row also checks once the CLI is installed. Under nvm every Node version has its own global packages, so {{binName}} lands under the Node this shell runs. If that Node is too old, or is not the one the user's terminal runs, tell the user and let them choose before going on.
+1. Run `node --version` and compare it with the range `npm view {{packageName}} engines.node` prints, which `doctor`'s `node` row also checks once the CLI is installed. Under nvm every Node version has its own global packages, so {{binName}} lands under the Node this shell runs. If that Node is too old, or is not the one the user's terminal runs, tell the user and let them choose before going on. That is also why a {{binName}} the user installed can be missing from this shell: ask which Node their terminal runs before installing again.
 2. Hand the user the install line to type, as [Sandbox](#sandbox) says:
 
    `! npm install --global {{packageName}}@latest`

package/template/skills/{{binName}}/SKILL.md

@@ -7,7 +7,7 @@ metadata:
   version: "0.0.0"
 ---
 
-<!-- A skeleton to rewrite around {{binName}}'s real Commands. Leave flags out: `--help` is generated from the code and stays in sync with it, this file does not. -->
+<!-- A skeleton to rewrite around {{binName}}'s real Commands. A line earns its place only when no `--help`, output, hint or `doctor` row tells the agent the same thing: write down what costs it turns to work out, such as a convention, a reason, a trap, or a step that needs the user's consent. Leave flags out: `--help` is generated from the code and stays in sync with it, this file does not. What {{binName}} is for, and the nearby tasks it is not for, go in the description, which the agent always sees. -->
 
 # {{binName}}
 
@@ -19,13 +19,6 @@ metadata:
 
 The line above should show 0.0.0, the version this skill describes. If it says {{binName}} is not installed or shows another version, read [setup](references/setup.md) before anything else.
 
-## When to use
-
-<!-- The tasks {{binName}} is for, and the nearby tasks it is not for. -->
-
-- Greeting someone by name.
-- Writing a greeting card to a file, in English for free or in another language at a cost.
-
 ## Workflows
 
 <!-- Each main task as steps naming the Commands it runs, in order. Move a long workflow to a file under references/ and link it. -->
@@ -43,11 +36,9 @@ The line above should show 0.0.0, the version this skill describes. If it says {
 
 To put a message under the greeting, pass `-` after the name and pipe the message in with a heredoc, so its quotes and newlines reach the card intact.
 
-Pass `--json` whenever you parse the output: stdout then holds only the data. A Command that changes something takes `--dry-run`, which prints its Plan, the files it writes and its cost, and changes nothing: run it first when unsure. A destructive Command also needs `--confirm=<target>`, and its error's Next step gives the exact command.
-
 ## Recovering from errors
 
-Errors go to stderr and end with a `hint:` line, then a `run:` line for each command to run next, in order. Under `--json`, every stderr line is one JSON object: `{"progress":"..."}` or `{"notice":"..."}` while it runs, then `{ errors: [{ code, message, hint, next }] }` as the last line, `next` holding those commands when there are any. Do what the hint says, except for a code below:
+Do what the error's hint says, except for a code below:
 
 | Code | What to do |
 |---|---|

package/template/skills/{{binName}}/references/setup.md

@@ -8,11 +8,9 @@ Work through a section in order and stop at a step that fails. Ask the user to d
 
 ## Check
 
-Run `{{runAs}} doctor --json`. It checks the setup without changing anything and prints `{ rows, next }`.
+Run `{{runAs}} doctor --json`, which changes nothing. Hand the user each line of its `next` to type with `!`, in order, then run `doctor` again.
 
-- Each row has a `check`, a `state` (`ok`, `problem` or `skipped`) and a `message` saying what it found. A row that has a `fix` names the command that fixes it.
-- `next` lists every fix in order. Hand the user each one to type with `!`, then run `doctor` again.
-- {{skillCheck}} If the session does not show it, ask the user to type `/reload-skills`, and failing that to restart Claude Code.
+{{skillCheck}} If the session does not show it, ask the user to type `/reload-skills`, and failing that to restart Claude Code.
 
 `{{runAs}} --version` names on its second line the `CHANGELOG.md` installed with the CLI. When the user asks what changed, read it from the top, newest first, down to the version in question.