@duyquangnvx/create-agent-cli 0.16.0 → 0.18.0

package/dist/bin.js

@@ -2,8 +2,8 @@
 import { parseArgs, parseEnv } from "node:util";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { constants, existsSync, readFileSync, realpathSync } from "node:fs";
-import { access, chmod, link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { constants as constants$1, homedir, tmpdir } from "node:os";
+import { access, chmod, link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
@@ -139,7 +139,7 @@ const allowsEval = /* @__PURE__*/ cached(() => {
 		return false;
 	}
 });
-function isPlainObject(o) {
+function isPlainObject$1(o) {
 	if (isObject(o) === false) return false;
 	const ctor = o.constructor;
 	if (ctor === void 0) return true;
@@ -150,7 +150,7 @@ function isPlainObject(o) {
 	return true;
 }
 function shallowClone(o) {
-	if (isPlainObject(o)) return { ...o };
+	if (isPlainObject$1(o)) return { ...o };
 	if (Array.isArray(o)) return [...o];
 	if (o instanceof Map) return new Map(o);
 	if (o instanceof Set) return new Set(o);
@@ -238,7 +238,7 @@ function omit(schema, mask) {
 	}));
 }
 function extend(schema, shape) {
-	if (!isPlainObject(shape)) throw new Error("Invalid input to extend: expected a plain object");
+	if (!isPlainObject$1(shape)) throw new Error("Invalid input to extend: expected a plain object");
 	const checks = schema._zod.def.checks;
 	if (checks && checks.length > 0) {
 		const existingShape = sourceShape(schema);
@@ -253,7 +253,7 @@ function extended(schema, shape) {
 	return newShape;
 }
 function safeExtend(schema, shape) {
-	if (!isPlainObject(shape)) throw new Error("Invalid input to safeExtend: expected a plain object");
+	if (!isPlainObject$1(shape)) throw new Error("Invalid input to safeExtend: expected a plain object");
 	return clone(schema, mergeDefs(schema._zod.def, { shape: extended(schema, shape) }));
 }
 function merge(a, b) {
@@ -2338,7 +2338,7 @@ function mergeValues(a, b) {
 		valid: true,
 		data: a
 	};
-	if (isPlainObject(a) && isPlainObject(b)) {
+	if (isPlainObject$1(a) && isPlainObject$1(b)) {
 		const bKeys = Object.keys(b);
 		const sharedKeys = Object.keys(a).filter((key) => bKeys.indexOf(key) !== -1);
 		const newObj = {
@@ -2431,7 +2431,7 @@ const $ZodRecord = /*@__PURE__*/ $constructor("$ZodRecord", (inst, def) => {
 	memo?.attach(inst);
 	inst._zod.parse = (payload, ctx) => {
 		const input = payload.value;
-		if (!isPlainObject(input)) {
+		if (!isPlainObject$1(input)) {
 			payload.issues.push({
 				expected: "record",
 				code: "invalid_type",
@@ -4863,7 +4863,7 @@ const parse$1 = /* @__PURE__ */ _parse(ZodRealError);
 const parseAsync = /* @__PURE__ */ _parseAsync(ZodRealError);
 const safeParse = /* @__PURE__ */ _safeParse(ZodRealError);
 const safeParseAsync = /* @__PURE__ */ _safeParseAsync(ZodRealError);
-const encode = /* @__PURE__ */ _encode(ZodRealError);
+const encode$1 = /* @__PURE__ */ _encode(ZodRealError);
 const decode = /* @__PURE__ */ _decode(ZodRealError);
 const encodeAsync = /* @__PURE__ */ _encodeAsync(ZodRealError);
 const decodeAsync = /* @__PURE__ */ _decodeAsync(ZodRealError);
@@ -5015,7 +5015,7 @@ const ZodType = /*@__PURE__*/ $constructor("ZodType", (inst, def) => {
 		return validateAsync$1(this, data, params);
 	},
 	encode: function _encode(data, params) {
-		return encode(this, data, params, { callee: _encode });
+		return encode$1(this, data, params, { callee: _encode });
 	},
 	decode: function _decode(data, params) {
 		return decode(this, data, params, { callee: _decode });
@@ -5774,21 +5774,196 @@ async function poll(clock, check, intervalMs, signal) {
 	}
 }
 //#endregion
+//#region ../agent-cli/dist/command-line/tokenize.js
+const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
+function isOptionLike(word) {
+	return word !== void 0 && word.length > 1 && word[0] === "-" && !NEGATIVE_NUMBER.test(word);
+}
+function parseArgsOptions(known) {
+	return Object.fromEntries(known.map(({ flag, takes }) => [flag.slice(2), { type: takes === "value" ? "string" : "boolean" }]));
+}
+function flagItem(token, { flag, takes }, words) {
+	if (takes !== "optional value" || token.inlineValue === true) return {
+		kind: "flag",
+		flag,
+		value: token.value ?? true
+	};
+	const took = token.index + 1;
+	const next = words[took];
+	return next === void 0 || isOptionLike(next) ? {
+		kind: "flag",
+		flag,
+		value: true
+	} : {
+		kind: "flag",
+		flag,
+		value: next,
+		took
+	};
+}
+function itemOf(token, words, byFlag) {
+	const word = words[token.index] ?? "";
+	if (token.kind === "option-terminator") return { kind: "end" };
+	if (token.kind === "positional" || NEGATIVE_NUMBER.test(word)) return {
+		kind: "operand",
+		value: word
+	};
+	const flag = byFlag.get(token.rawName);
+	return flag === void 0 || flag.takes === "nothing" && token.inlineValue === true ? {
+		kind: "unknown option",
+		word
+	} : flagItem(token, flag, words);
+}
+/** Splits a Command's words into operands, unknown options and the values of known flags. */
+function tokenize(words, known) {
+	const byFlag = new Map(known.map((flag) => [flag.flag, flag]));
+	const { tokens } = parseArgs({
+		args: [...words],
+		options: parseArgsOptions(known),
+		strict: false,
+		allowPositionals: true,
+		tokens: true
+	});
+	const operands = [];
+	const unknownOptions = [];
+	const occurrences = /* @__PURE__ */ new Map();
+	const done = /* @__PURE__ */ new Set();
+	let literal = false;
+	let afterUnknownOption = false;
+	for (const token of tokens) {
+		if (done.has(token.index)) continue;
+		done.add(token.index);
+		const item = itemOf(token, words, byFlag);
+		if (item.kind === "end") literal = true;
+		else if (item.kind === "operand") {
+			operands.push({
+				value: item.value,
+				afterUnknownOption: !literal && afterUnknownOption
+			});
+			afterUnknownOption = false;
+		} else if (item.kind === "unknown option") {
+			unknownOptions.push(item.word);
+			afterUnknownOption = true;
+		} else {
+			occurrences.set(item.flag, [...occurrences.get(item.flag) ?? [], item.value]);
+			if (item.took !== void 0) done.add(item.took);
+		}
+	}
+	return {
+		operands,
+		unknownOptions,
+		values: new Map([...occurrences].map(([flag, all]) => [flag, all[all.length - 1] ?? true])),
+		occurrences
+	};
+}
+const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
+function quoted$1(token) {
+	return SHELL_SAFE.test(token) ? token : `'${token.replaceAll("'", `'\\''`)}'`;
+}
+function pasteable(runAs, tokens, stdinArg) {
+	const line = [runAs, ...tokens.map(quoted$1)].join(" ");
+	return stdinArg === void 0 ? line : `${line} < <${stdinArg} file>`;
+}
+function split(argv) {
+	const end = argv.indexOf("--");
+	return end === -1 ? {
+		options: [...argv],
+		operands: []
+	} : {
+		options: argv.slice(0, end),
+		operands: argv.slice(end)
+	};
+}
+function tookValue(takes, next) {
+	return takes === "value" || takes === "optional value" && next !== void 0 && !isOptionLike(next);
+}
+function without(flag, takes, tokens) {
+	const kept = [];
+	for (let index = 0; index < tokens.length; index += 1) {
+		const token = tokens[index] ?? "";
+		if (token === flag) {
+			if (tookValue(takes, tokens[index + 1])) index += 1;
+		} else if (!token.startsWith(`${flag}=`)) kept.push(token);
+	}
+	return kept;
+}
+/**
+* The caller's words after the CLI's name, with each flag in `remove` dropped along with its value
+* and the words in `add` placed before any `--`.
+*/
+function changedArgv({ argv, flags }, { add = [], remove = [] } = {}) {
+	const { options, operands } = split(argv);
+	const takes = new Map(flags.map((known) => [known.flag, known.takes]));
+	return [
+		...remove.reduce((tokens, flag) => without(flag, takes.get(flag) ?? "nothing", tokens), options),
+		...add,
+		...operands
+	];
+}
+/** The caller's command line as typed, ready to paste, changed as `changedArgv` does, the stdin arg's file redirected in. */
+function commandLineOf(invocation, change) {
+	return pasteable(invocation.runAs, changedArgv(invocation, change), invocation.stdinArg);
+}
+function renamed(token, renames) {
+	const [flag = token, ...value] = token.split("=");
+	const name = renames.get(flag);
+	if (name === void 0) return token;
+	return value.length === 0 ? name : `${name}=${value.join("=")}`;
+}
+/** The caller's command line, ready to paste, with each flag in `renames` typed as its new name. */
+function commandLineRenaming({ runAs, argv, stdinArg }, renames) {
+	const { options, operands } = split(argv);
+	return pasteable(runAs, [...options.map((token) => renamed(token, renames)), ...operands], stdinArg);
+}
+//#endregion
+//#region ../agent-cli/dist/next-step.js
+function wholeLine(line) {
+	return {
+		kind: "line",
+		line
+	};
+}
+function isWords(step) {
+	return Array.isArray(step);
+}
+/** The words after the Run-as, or `undefined` for a line given whole. */
+function wordsOf(step) {
+	if (isWords(step)) return step;
+	return step.kind === "rerun" ? step.words : void 0;
+}
+/** The Next step as one shell-quoted line starting with the Run-as, or the whole line as given. */
+function lineOf(step, runAs) {
+	if (isWords(step)) return pasteable(runAs, step);
+	return step.kind === "rerun" ? pasteable(runAs, step.words, step.stdinArg) : step.line;
+}
+//#endregion
 //#region ../agent-cli/dist/errors.js
 var CliError = class extends Error {
 	code;
 	hint;
 	details;
 	retryAt;
-	constructor({ code, message, hint, details, retryAt }, options) {
+	next;
+	constructor({ code, message, hint, details, retryAt, next = [] }, options) {
 		super(message, options);
 		this.name = "CliError";
 		this.code = code;
 		this.hint = hint;
 		this.details = details;
 		this.retryAt = retryAt;
+		this.next = next;
 	}
 };
+var RuntimeError = class extends CliError {
+	constructor({ next, ...fields }, options) {
+		super(fields, options);
+		this.next = next;
+	}
+};
+/** A `CliError` whose Next steps may hold a line given whole, which only the Runtime builds. */
+function runtimeError(fields, options) {
+	return new RuntimeError(fields, options);
+}
 /** The caller called the Agent CLI wrong; the same call can't succeed. */
 var UsageError = class extends CliError {
 	constructor(fields) {
@@ -5834,21 +6009,28 @@ function bugHint(format) {
 	return bugs === void 0 ? rerun : `${rerun}, then report it at ${bugs}`;
 }
 function fieldsOf$1(error, format) {
-	if (error instanceof CliError) {
-		const { code, message, hint, details, retryAt } = error;
-		return {
-			code,
-			message,
-			hint: format.isBug(error) ? bugHint(format) : hint,
-			details,
-			retryAt
-		};
-	}
-	return {
+	if (!(error instanceof CliError)) return {
 		code: INTERNAL,
 		message: messageOf(error),
 		hint: bugHint(format)
 	};
+	const { code, message, hint, details, retryAt, next } = error;
+	if (format.isBug(error)) return {
+		code,
+		message,
+		hint: bugHint(format),
+		details,
+		retryAt
+	};
+	const lines = next.map((step) => lineOf(step, format.runAs));
+	return {
+		code,
+		message,
+		hint,
+		details,
+		retryAt,
+		...lines.length === 0 ? {} : { next: lines }
+	};
 }
 function causesOf(error) {
 	return error instanceof Error && error.cause !== void 0 ? [error.cause, ...causesOf(error.cause)] : [];
@@ -5884,7 +6066,8 @@ function errorLines(error, format) {
 	const { style } = format;
 	const label = style.red(format.isBug(error) ? "internal error:" : "error:");
 	const between = blocks.map((block) => `${block}\n`).join("");
-	return `${label} ${fields.message}\n${between}${style.cyan("hint:")} ${fields.hint}\n`;
+	const runs = (fields.next ?? []).map((line) => `${style.cyan("run:")} ${line}\n`).join("");
+	return `${label} ${fields.message}\n${between}${style.cyan("hint:")} ${fields.hint}\n${runs}`;
 }
 function formatRuntimeError(error, format) {
 	const errors = errorsOf(error);
@@ -5898,7 +6081,7 @@ function formatRuntimeError(error, format) {
 	return errors.map((each) => errorLines(each, format)).join("");
 }
 //#endregion
-//#region ../agent-cli/dist/stdin.js
+//#region ../agent-cli/dist/context/stdin.js
 const STDIN_META = "stdin";
 function isStdinSchema(schema) {
 	return globalRegistry$1.get(schema)?.[STDIN_META] === true;
@@ -5972,7 +6155,7 @@ function readStdin(source, signal, idle) {
 	});
 }
 //#endregion
-//#region ../agent-cli/dist/input.js
+//#region ../agent-cli/dist/command-line/input.js
 function isWrapper(schema) {
 	return schema instanceof ZodOptional || schema instanceof ZodNullable || schema instanceof ZodDefault || schema instanceof ZodPrefault;
 }
@@ -6074,190 +6257,52 @@ function checkNoBooleanArrayOption(name, options) {
 	if (booleans.length > 0) throw new Error(`Command '${name}' declares boolean array option ${keysOf(booleans)}; a switch cannot repeat, use a boolean`);
 }
 //#endregion
-//#region ../agent-cli/dist/tokenize.js
-const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
-function isOptionLike(word) {
-	return word !== void 0 && word.length > 1 && word[0] === "-" && !NEGATIVE_NUMBER.test(word);
+//#region ../agent-cli/dist/command-line/usage.js
+const INVALID_INPUT = "INVALID_INPUT";
+const UNKNOWN_OPTION = "UNKNOWN_OPTION";
+const UNKNOWN_COMMAND = "UNKNOWN_COMMAND";
+function unknownError({ code, problem, commandLine, corrections, listed }) {
+	return new UsageError({
+		code,
+		message: `${problem} for \`${commandLine}\``,
+		hint: corrections.length === 0 ? `run \`${commandLine} --help\` to see the ${listed}` : `did you mean ${corrections.map((correction) => `\`${correction}\``).join(" or ")}?`
+	});
 }
-function parseArgsOptions(known) {
-	return Object.fromEntries(known.map(({ flag, takes }) => [flag.slice(2), { type: takes === "value" ? "string" : "boolean" }]));
+function unknownOptionError(commandLine, invocation, flag, suggestions) {
+	return unknownError({
+		code: UNKNOWN_OPTION,
+		problem: `unknown option '${flag}'`,
+		commandLine,
+		corrections: suggestions.map((name) => commandLineRenaming(invocation, /* @__PURE__ */ new Map([[flag, name]]))),
+		listed: "options"
+	});
 }
-function flagItem(token, { flag, takes }, words) {
-	if (takes !== "optional value" || token.inlineValue === true) return {
-		kind: "flag",
-		flag,
-		value: token.value ?? true
-	};
-	const took = token.index + 1;
-	const next = words[took];
-	return next === void 0 || isOptionLike(next) ? {
-		kind: "flag",
-		flag,
-		value: true
-	} : {
-		kind: "flag",
-		flag,
-		value: next,
-		took
-	};
+/** Text opening with `-` was read as an option, where the Command could have read it from stdin. */
+function stdinTextError(commandLine, invocation, word) {
+	const withStdin = commandLineOf(invocation, {
+		remove: [word],
+		add: ["-"]
+	});
+	return new UsageError({
+		code: UNKNOWN_OPTION,
+		message: `unknown option '${word}' for \`${commandLine}\``,
+		hint: `to pass text opening with \`-\`, pass \`-\` and send the text on stdin through a heredoc: \`${withStdin} <<'EOF'\`, then the text, then \`EOF\``
+	});
 }
-function itemOf(token, words, byFlag) {
-	const word = words[token.index] ?? "";
-	if (token.kind === "option-terminator") return { kind: "end" };
-	if (token.kind === "positional" || NEGATIVE_NUMBER.test(word)) return {
-		kind: "operand",
-		value: word
-	};
-	const flag = byFlag.get(token.rawName);
-	return flag === void 0 || flag.takes === "nothing" && token.inlineValue === true ? {
-		kind: "unknown option",
-		word
-	} : flagItem(token, flag, words);
+function unknownCommandError(commandLine, name, suggestions) {
+	return unknownError({
+		code: UNKNOWN_COMMAND,
+		problem: `unknown command '${name}'`,
+		commandLine,
+		corrections: suggestions.map((suggestion) => `${commandLine} ${suggestion}`),
+		listed: "commands"
+	});
 }
-/** Splits a Command's words into operands, unknown options and the values of known flags. */
-function tokenize(words, known) {
-	const byFlag = new Map(known.map((flag) => [flag.flag, flag]));
-	const { tokens } = parseArgs({
-		args: [...words],
-		options: parseArgsOptions(known),
-		strict: false,
-		allowPositionals: true,
-		tokens: true
-	});
-	const operands = [];
-	const unknownOptions = [];
-	const occurrences = /* @__PURE__ */ new Map();
-	const done = /* @__PURE__ */ new Set();
-	let literal = false;
-	let afterUnknownOption = false;
-	for (const token of tokens) {
-		if (done.has(token.index)) continue;
-		done.add(token.index);
-		const item = itemOf(token, words, byFlag);
-		if (item.kind === "end") literal = true;
-		else if (item.kind === "operand") {
-			operands.push({
-				value: item.value,
-				afterUnknownOption: !literal && afterUnknownOption
-			});
-			afterUnknownOption = false;
-		} else if (item.kind === "unknown option") {
-			unknownOptions.push(item.word);
-			afterUnknownOption = true;
-		} else {
-			occurrences.set(item.flag, [...occurrences.get(item.flag) ?? [], item.value]);
-			if (item.took !== void 0) done.add(item.took);
-		}
-	}
-	return {
-		operands,
-		unknownOptions,
-		values: new Map([...occurrences].map(([flag, all]) => [flag, all[all.length - 1] ?? true])),
-		occurrences
-	};
-}
-const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
-function quoted$1(token) {
-	return SHELL_SAFE.test(token) ? token : `'${token.replaceAll("'", `'\\''`)}'`;
-}
-function pasteable(runAs, tokens, stdinArg) {
-	const line = [runAs, ...tokens.map(quoted$1)].join(" ");
-	return stdinArg === void 0 ? line : `${line} < <${stdinArg} file>`;
-}
-function split(argv) {
-	const end = argv.indexOf("--");
-	return end === -1 ? {
-		options: [...argv],
-		operands: []
-	} : {
-		options: argv.slice(0, end),
-		operands: argv.slice(end)
-	};
-}
-function tookValue(takes, next) {
-	return takes === "value" || takes === "optional value" && next !== void 0 && !isOptionLike(next);
-}
-function without(flag, takes, tokens) {
-	const kept = [];
-	for (let index = 0; index < tokens.length; index += 1) {
-		const token = tokens[index] ?? "";
-		if (token === flag) {
-			if (tookValue(takes, tokens[index + 1])) index += 1;
-		} else if (!token.startsWith(`${flag}=`)) kept.push(token);
-	}
-	return kept;
-}
-/**
-* The caller's command line as typed, ready to paste, with each flag in `remove` dropped along with
-* its value, the words in `add` placed before any `--`, and the stdin arg's file redirected in.
-*/
-function commandLineOf({ runAs, argv, flags, stdinArg }, { add = [], remove = [] } = {}) {
-	const { options, operands } = split(argv);
-	const takes = new Map(flags.map((known) => [known.flag, known.takes]));
-	return pasteable(runAs, [
-		...remove.reduce((tokens, flag) => without(flag, takes.get(flag) ?? "nothing", tokens), options),
-		...add,
-		...operands
-	], stdinArg);
-}
-function renamed(token, renames) {
-	const [flag = token, ...value] = token.split("=");
-	const name = renames.get(flag);
-	if (name === void 0) return token;
-	return value.length === 0 ? name : `${name}=${value.join("=")}`;
-}
-/** The caller's command line, ready to paste, with each flag in `renames` typed as its new name. */
-function commandLineRenaming({ runAs, argv, stdinArg }, renames) {
-	const { options, operands } = split(argv);
-	return pasteable(runAs, [...options.map((token) => renamed(token, renames)), ...operands], stdinArg);
-}
-//#endregion
-//#region ../agent-cli/dist/usage.js
-const INVALID_INPUT = "INVALID_INPUT";
-const UNKNOWN_OPTION = "UNKNOWN_OPTION";
-const UNKNOWN_COMMAND = "UNKNOWN_COMMAND";
-function unknownError({ code, problem, commandLine, corrections, listed }) {
-	return new UsageError({
-		code,
-		message: `${problem} for \`${commandLine}\``,
-		hint: corrections.length === 0 ? `run \`${commandLine} --help\` to see the ${listed}` : `did you mean ${corrections.map((correction) => `\`${correction}\``).join(" or ")}?`
-	});
-}
-function unknownOptionError(commandLine, invocation, flag, suggestions) {
-	return unknownError({
-		code: UNKNOWN_OPTION,
-		problem: `unknown option '${flag}'`,
-		commandLine,
-		corrections: suggestions.map((name) => commandLineRenaming(invocation, /* @__PURE__ */ new Map([[flag, name]]))),
-		listed: "options"
-	});
-}
-/** Text opening with `-` was read as an option, where the Command could have read it from stdin. */
-function stdinTextError(commandLine, invocation, word) {
-	const withStdin = commandLineOf(invocation, {
-		remove: [word],
-		add: ["-"]
-	});
-	return new UsageError({
-		code: UNKNOWN_OPTION,
-		message: `unknown option '${word}' for \`${commandLine}\``,
-		hint: `to pass text opening with \`-\`, pass \`-\` and send the text on stdin through a heredoc: \`${withStdin} <<'EOF'\`, then the text, then \`EOF\``
-	});
-}
-function unknownCommandError(commandLine, name, suggestions) {
-	return unknownError({
-		code: UNKNOWN_COMMAND,
-		problem: `unknown command '${name}'`,
-		commandLine,
-		corrections: suggestions.map((suggestion) => `${commandLine} ${suggestion}`),
-		listed: "commands"
-	});
-}
-function invalidInputError(commandLine, problem) {
-	return new UsageError({
-		code: INVALID_INPUT,
-		message: problem,
-		hint: `run \`${commandLine} --help\` to see the expected input`
+function invalidInputError(commandLine, problem) {
+	return new UsageError({
+		code: INVALID_INPUT,
+		message: problem,
+		hint: `run \`${commandLine} --help\` to see the expected input`
 	});
 }
 //#endregion
@@ -6365,16 +6410,19 @@ function cursorWords(cursor) {
 function printedPage(page, invocation) {
 	return page.nextCursor === void 0 ? { items: page.items } : {
 		items: page.items,
-		next: commandLineOf(invocation, {
-			remove: [PAGE_FLAGS.cursor.flag],
-			add: cursorWords(page.nextCursor)
-		})
+		next: lineOf({
+			kind: "rerun",
+			words: changedArgv(invocation, {
+				remove: [PAGE_FLAGS.cursor.flag],
+				add: cursorWords(page.nextCursor)
+			}),
+			stdinArg: invocation.stdinArg
+		}, invocation.runAs)
 	};
 }
-/** The line that ends a rendered page, so the caller always knows whether and how to get more. */
-function pageFooter({ items, next }) {
-	const more = next === void 0 ? "no more pages" : `next page: \`${next}\``;
-	return `${items.length} shown; ${more}\n`;
+/** The lines that end a rendered page, so the caller always knows whether and how to get more. */
+function pageFooter({ items, next }, style) {
+	return next === void 0 ? `${items.length} shown; no more pages\n` : `${items.length} shown; run the Next step for the next page\n${style.cyan("run:")} ${next}\n`;
 }
 //#endregion
 //#region ../agent-cli/dist/planned.js
@@ -6383,7 +6431,7 @@ function hasPlan(command) {
 	return command.effect === "write" || command.effect === "destructive";
 }
 //#endregion
-//#region ../agent-cli/dist/flags.js
+//#region ../agent-cli/dist/command-line/flags.js
 const HELP_FLAG = "--help";
 const VERSION_FLAG = "--version";
 const ROUTING_FLAGS = [
@@ -6391,7 +6439,7 @@ const ROUTING_FLAGS = [
 	"-h",
 	VERSION_FLAG
 ];
-function nameOf(flag) {
+function nameOf$1(flag) {
 	return flag.replace(/^--?/, "");
 }
 function standardFlag(flag, { placeholder, ...rest }) {
@@ -6429,6 +6477,7 @@ const FORCE_FLAG = standardFlag("--force", {
 });
 const EFFECT_FLAGS = {
 	read: [JSON_FLAG],
+	act: [JSON_FLAG],
 	write: [JSON_FLAG, DRY_RUN_FLAG],
 	destructive: [
 		JSON_FLAG,
@@ -6443,7 +6492,7 @@ const RESERVED = new Map([
 	YES_FLAG.flag,
 	FORCE_FLAG.flag,
 	...LIST_FLAGS
-].map((flag) => [nameOf(flag), flag]));
+].map((flag) => [nameOf$1(flag), flag]));
 /** The Standard flags of a Command with this Effect and declarations, and of a List Command. */
 function standardFlagsFor(effect, { outputs, force, cost }, list) {
 	const forceFlag = force === void 0 ? FORCE_FLAG : {
@@ -6458,7 +6507,7 @@ function standardFlagsFor(effect, { outputs, force, cost }, list) {
 	];
 }
 /** Throws when the Command declares an arg or option under a Standard flag's name. */
-function checkNoStandardFlags(command) {
+function checkNoStandardFlags(command, label) {
 	const lines = [...argFields(command.args).map(({ key }) => ({
 		kind: "arg",
 		key
@@ -6469,40 +6518,46 @@ function checkNoStandardFlags(command) {
 		const flag = RESERVED.get(kebab(key));
 		return flag === void 0 ? [] : [`  ${kind} '${key}' is the Standard flag ${flag}`];
 	});
-	if (lines.length > 0) throw new Error([`Command '${command.name}' declares Standard flags the Runtime adds; rename them:`, ...lines].join("\n"));
+	if (lines.length > 0) throw new Error([`Command '${label}' declares Standard flags the Runtime adds; rename them:`, ...lines].join("\n"));
 }
 /** Throws when `force` is declared on a Command with no Plan, or says nothing. */
-function checkForce(command) {
+function checkForce(command, label) {
 	const force = "force" in command ? command.force : void 0;
 	if (force === void 0) return;
-	if (!hasPlan(command)) throw new Error(`Command '${command.name}' declares force, which only a write or destructive Command may`);
-	if (force.trim() === "") throw new Error(`Command '${command.name}' declares an empty force; say what ${FORCE_FLAG.flag} replaces`);
+	if (!hasPlan(command)) throw new Error(`Command '${label}' declares force, which only a write or destructive Command may`);
+	if (force.trim() === "") throw new Error(`Command '${label}' declares an empty force; say what ${FORCE_FLAG.flag} replaces`);
 }
 //#endregion
-//#region ../agent-cli/dist/define.js
-function checkedCommand(command) {
-	checkNoStandardFlags(command);
-	checkForce(command);
-	checkArrayArgLast(command.name, command.args);
-	checkStdinFields(command.name, command.args, command.options);
-	checkNoBooleanArrayOption(command.name, command.options);
-	return command;
+//#region ../agent-cli/dist/define-command.js
+/** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
+function checkCommand(command, label, table) {
+	checkNoStandardFlags(command, label);
+	checkForce(command, label);
+	checkArrayArgLast(label, command.args);
+	checkStdinFields(label, command.args, command.options);
+	checkNoBooleanArrayOption(label, command.options);
+	checkErrors(command, label, table);
+}
+function checkErrors(command, label, table) {
+	const unknown = (command.errors ?? []).filter((code) => !Object.hasOwn(table, code));
+	if (unknown.length > 0) throw new Error(`${label} declares ${unknown.join(", ")} in errors, a code the Error table lacks`);
 }
 function defineCommandFor() {
-	return checkedCommand;
+	return declared;
 }
-const defineCommand$1 = defineCommandFor();
-function isCommand(node) {
-	return typeof node.effect === "string";
+function declared(command) {
+	return command;
 }
+const defineCommand$1 = defineCommandFor();
 //#endregion
-//#region ../agent-cli/dist/project.js
+//#region ../agent-cli/dist/context/project.js
 const PROJECT_INVALID = "PROJECT_INVALID";
-function invalid(path, problem, callerLine, options) {
+function invalid(path, problem, rerun, options) {
 	return new CliError({
 		code: PROJECT_INVALID,
 		message: `the Project file ${path} is invalid: ${problem}`,
-		hint: `fix ${path}, then run \`${callerLine}\` again`
+		hint: `fix ${path}, then run the Next step`,
+		next: [rerun]
 	}, options);
 }
 function readText(path, fileError) {
@@ -6516,15 +6571,15 @@ function readText(path, fileError) {
 		});
 	}
 }
-function parsed(path, text, schema, callerLine) {
+function parsed(path, text, schema, rerun) {
 	let json;
 	try {
 		json = JSON.parse(text);
 	} catch (error) {
-		throw invalid(path, messageOf(error), callerLine, { cause: error });
+		throw invalid(path, messageOf(error), rerun, { cause: error });
 	}
 	const result = schema.safeParse(json);
-	if (!result.success) throw invalid(path, prettifyError(result.error), callerLine);
+	if (!result.success) throw invalid(path, prettifyError(result.error), rerun);
 	return result.data;
 }
 function projectFrom(projectFile, folder, scope) {
@@ -6532,7 +6587,7 @@ function projectFrom(projectFile, folder, scope) {
 	const text = readText(path, scope.fileError);
 	if (text !== void 0) return {
 		root: folder,
-		settings: parsed(path, text, projectFile.schema, scope.callerLine)
+		settings: parsed(path, text, projectFile.schema, scope.rerun)
 	};
 	const parent = dirname(folder);
 	return parent === folder ? void 0 : projectFrom(projectFile, parent, scope);
@@ -6542,7 +6597,110 @@ function projectOf(projectFile, cwd, scope) {
 	return projectFrom(projectFile, resolve(cwd), scope);
 }
 //#endregion
-//#region ../agent-cli/dist/tools.js
+//#region ../agent-cli/dist/define.js
+function isCommand(node) {
+	return typeof node.effect === "string";
+}
+//#endregion
+//#region ../agent-cli/dist/context/declared.js
+/**
+* What the CLI declares itself (`own`) and every Command under `commands` declares, each name once,
+* for a `doctor` row: a Command requires only its own, but `doctor` checks them all.
+*/
+function declaredIn(own, commands, needsOf) {
+	const walk = (node) => isCommand(node) ? [...needsOf(node) ?? []] : Object.values(node).flatMap(walk);
+	return [...new Map([...own, ...walk(commands)].map((need) => [need.name, need])).values()];
+}
+//#endregion
+//#region ../agent-cli/dist/context/secrets.js
+const SECRET_MISSING = "SECRET_MISSING";
+/** `$XDG_CONFIG_HOME/<cli>/.env`, with `~/.config` when the variable is unset or empty. */
+function envFileOf(cliName, env) {
+	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+	return join(config, cliName, ".env");
+}
+function readDotenv(path, fileError) {
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return {};
+		throw fileError(error, {
+			path,
+			access: "read"
+		});
+	}
+	return parseEnv(text);
+}
+/** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
+function secretOf({ envFile, env, fileError }, name) {
+	const fromEnv = env[name];
+	if (fromEnv) return {
+		value: fromEnv,
+		origin: { kind: "env" }
+	};
+	const fromFile = readDotenv(envFile, fileError)[name];
+	return fromFile ? {
+		value: fromFile,
+		origin: {
+			kind: "file",
+			path: envFile
+		}
+	} : void 0;
+}
+function missingIn(scope, secrets) {
+	return secrets.filter(({ name }) => secretOf(scope, name) === void 0);
+}
+function getItFrom({ get }) {
+	return `(get it from ${get})`;
+}
+function whereToGet(secrets) {
+	return secrets.map((secret) => `${secret.name} ${getItFrom(secret)}`).join(", ");
+}
+/** Fails with `SECRET_MISSING`, naming every missing Secret at once, unless all are set. */
+function checkSecrets(secrets, scope, rerun) {
+	const missing = missingIn(scope, secrets);
+	if (missing.length === 0) return;
+	const names = missing.map(({ name }) => name).join(", ");
+	throw new CliError({
+		code: SECRET_MISSING,
+		message: `${missing.length === 1 ? "a Secret it needs is" : "Secrets it needs are"} not set: ${names}`,
+		hint: `set ${whereToGet(missing)} in the environment or in ${scope.envFile}, then run the Next step`,
+		next: [rerun]
+	});
+}
+function originOf({ origin }) {
+	return origin.kind === "env" ? "the environment" : origin.path;
+}
+/** The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. */
+function secretRows(secrets, commands) {
+	const declared = declaredIn(secrets, commands, (command) => command.secrets);
+	if (declared.length === 0) return [];
+	return [{
+		name: "secrets",
+		run: ({ env, envFile, fileError }) => {
+			const read = declared.map((declaration) => ({
+				declaration,
+				secret: secretOf({
+					env,
+					envFile,
+					fileError
+				}, declaration.name)
+			}));
+			const missing = read.filter(({ secret }) => secret === void 0);
+			if (missing.length > 0) return {
+				state: "problem",
+				message: `${missing.map(({ declaration }) => `${declaration.name} is not set ${getItFrom(declaration)}`).join(", ")}; add ${missing.length === 1 ? "it" : "them"} to ${envFile} or the environment`
+			};
+			return {
+				state: "ok",
+				message: read.flatMap(({ declaration, secret }) => secret === void 0 ? [] : [`${declaration.name} from ${originOf(secret)}`]).join(", ")
+			};
+		}
+	}];
+}
+//#endregion
+//#region ../agent-cli/dist/context/tools.js
 const TOOL_MISSING = "TOOL_MISSING";
 const WINDOWS_EXTENSIONS = ".COM;.EXE;.BAT;.CMD";
 function pathOf(env) {
@@ -6572,23 +6730,21 @@ async function findTool(name, env) {
 	for (const file of candidates) if (await isExecutable(file)) return file;
 }
 /** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
-async function checkTools(tools, env, callerLine) {
+async function checkTools(tools, env, rerun) {
 	const found = await Promise.all(tools.map((tool) => findTool(tool.name, env)));
 	const missing = tools.filter((_tool, index) => found[index] === void 0);
 	if (missing.length === 0) return;
 	const names = missing.map(({ name }) => name).join(", ");
-	throw new CliError({
+	throw runtimeError({
 		code: TOOL_MISSING,
 		message: `${missing.length === 1 ? "a tool it runs is" : "tools it runs are"} not on PATH: ${names}`,
-		hint: `install ${missing.map(({ name, install }) => `${name} (\`${install}\`)`).join(", ")}, then run \`${callerLine}\` again`
+		hint: "run the Next steps in order: each install, then the command again",
+		next: [...missing.map(({ install }) => wholeLine(install)), rerun]
 	});
 }
-function toolsIn(node) {
-	return isCommand(node) ? [...node.tools ?? []] : Object.values(node).flatMap(toolsIn);
-}
 /** One `doctor` row per distinct tool the CLI and its Commands declare, with its install command as the fix. */
 function toolRows(tools, commands) {
-	return [...new Map([...tools, ...toolsIn(commands)].map((tool) => [tool.name, tool])).values()].map(({ name, install }) => ({
+	return declaredIn(tools, commands, (command) => command.tools).map(({ name, install }) => ({
 		name,
 		run: async (ctx) => {
 			const file = await findTool(name, ctx.env);
@@ -6605,72 +6761,18 @@ function toolRows(tools, commands) {
 }
 //#endregion
 //#region ../agent-cli/dist/version.js
-/** The first line of `--version`: the version, and the commit and time of a stamped build. */
-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 bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
+function buildStamp() {
+	return {
+		"sha": "e9645e3",
+		"dirty": false,
+		"builtAt": "2026-10-28T08:17:12.000Z"
 	};
 }
-/** 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;
+/** The first line of `--version`: the version, and the commit and time of a stamped build. */
+function versionLine({ version }) {
+	const build = buildStamp();
+	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
 }
 //#endregion
 //#region ../agent-cli/dist/tail.js
@@ -6679,7 +6781,7 @@ function lastLines(output, count) {
 	return output.trim().split("\n").slice(-count).join("\n");
 }
 //#endregion
-//#region ../agent-cli/dist/spawn.js
+//#region ../agent-cli/dist/context/spawn.js
 const TOOL_FAILED = "TOOL_FAILED";
 const STDERR_TAIL_LINES$1 = 20;
 const SIGNAL_EXIT_BASE = 128;
@@ -6904,15 +7006,16 @@ function failedError(command, { exitCode, stderr }) {
 		hint: `the output of ${command} above says why it failed`
 	});
 }
-function missingError(command, callerLine, cause) {
+function missingError(command, rerun, cause) {
 	return new CliError({
 		code: TOOL_MISSING,
 		message: `${command} could not be started: it is not on PATH`,
-		hint: `install ${command}, then run \`${callerLine}\` again`
+		hint: `install ${command}, then run the Next step`,
+		next: [rerun]
 	}, { cause });
 }
-function startError(command, error, { fileError, callerLine }) {
-	if (isMissingFile(error)) return missingError(command, callerLine, error);
+function startError(command, error, { fileError, rerun }) {
+	if (isMissingFile(error)) return missingError(command, rerun, error);
 	return fileError(error, {
 		path: command,
 		access: "read"
@@ -7049,7 +7152,7 @@ const NO_LATEST = "NO_LATEST";
 function npmContext(cli, registry, ctx, node, cwd) {
 	return {
 		cliName: cli.name,
-		callerLine: ctx.commandLine(),
+		rerun: ctx.rerun(),
 		registry,
 		cwd,
 		env: ctx.env,
@@ -7058,6 +7161,7 @@ function npmContext(cli, registry, ctx, node, cwd) {
 	};
 }
 const STDERR_TAIL_LINES = 10;
+const RUN_AGAIN = "run it again";
 const RM_RETRIES = 3;
 const NETWORK_CODES = /* @__PURE__ */ new Set([
 	"ENOTFOUND",
@@ -7121,27 +7225,31 @@ function failureOf(call, answer, ctx) {
 	const { label: registry, package: name, loginHint, unreachableHint } = ctx.registry;
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
-	const rerun = `run \`${ctx.callerLine}\` again`;
+	const next = [ctx.rerun];
 	if (code !== void 0 && NETWORK_CODES.has(code)) return new CliError({
 		code: REGISTRY_UNREACHABLE,
 		message: `npm could not reach ${registry} (${code})${output}`,
-		hint: `${unreachableHint}, then ${rerun}`
+		hint: `${unreachableHint}, then ${RUN_AGAIN}`,
+		next
 	});
 	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 ${rerun}`
+		hint: `${loginHint}, then ${RUN_AGAIN}`,
+		next
 	});
 	if (call === "view" && code === "E404") return noLatest(ctx, `npm found no ${name}@latest on ${registry}: no version of it is published there`);
-	if (call === "install") return new CliError({
+	if (call === "install") return runtimeError({
 		code: INSTALL_FAILED,
 		message: `npm could not install ${name}${code === void 0 ? "" : ` (${code})`}${output}`,
-		hint: `fix what npm reports, then ${rerun}, or install it yourself: \`${installCommandLine(ctx.registry)}\``
+		hint: `fix what npm reports, then ${RUN_AGAIN} with the first Next step, or install it yourself with the second`,
+		next: [...next, wholeLine(installCommandLine(ctx.registry))]
 	});
 	return new CliError({
 		code: NPM_FAILED,
 		message: `npm ${call} failed with exit code ${answer.exitCode}${output}`,
-		hint: `fix what npm reports, then ${rerun}`
+		hint: `fix what npm reports, then ${RUN_AGAIN}`,
+		next
 	});
 }
 function noLatest(ctx, message) {
@@ -7217,10 +7325,73 @@ async function latestVersion(ctx) {
 	return version;
 }
 //#endregion
-//#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;
+//#region ../agent-cli/dist/built-ins/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/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/install/dependency.js
@@ -7444,13 +7615,18 @@ async function skillCopies(cliName, version, { cwd, env }) {
 	}
 	return copies;
 }
-function fixFor(cliName, copies, source) {
-	const has = (wanted) => copies.some(({ state }) => state === wanted);
+const has = (copies, wanted) => copies.some(({ state }) => state === wanted);
+function fixFor(cliName, copies, from) {
 	const update = `npx -y skills update ${cliName}`;
-	const add = source === void 0 ? void 0 : `npx -y skills add ${source} --skill ${cliName} -g`;
+	const add = from !== void 0 && "source" in from ? `npx -y skills add ${from.source} --skill ${cliName} -g` : void 0;
 	if (copies.length === 0) return add;
-	if (has("unversioned") && add !== void 0) return has("behind") ? `${update} && ${add}` : add;
-	return has("behind") || has("unversioned") ? update : void 0;
+	if (has(copies, "unversioned") && add !== void 0) return has(copies, "behind") ? `${update} && ${add}` : add;
+	if (from !== void 0 && "page" in from) return has(copies, "behind") ? update : void 0;
+	return has(copies, "behind") || has(copies, "unversioned") ? update : void 0;
+}
+function pageNote(copies, from) {
+	if (from === void 0 || !("page" in from)) return;
+	return copies.length === 0 || has(copies, "unversioned") ? `copy your install line from ${from.page}` : void 0;
 }
 const SKILL_STATE_NOTES = {
 	current: "the same as this build",
@@ -7462,12 +7638,13 @@ const SKILL_STATE_NOTES = {
 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("; ");
+/** A skill on a Skill Hub, which `from` says how to install; with neither, no line adds it. */
+function hubSkill(cli, from) {
+	const findingOf = (copies) => {
+		const fix = fixFor(cli.name, copies, from);
+		const note = pageNote(copies, from);
+		const found = copies.length === 0 ? `no copy of the ${cli.name} skill is installed` : copies.map(describeCopy).join("; ");
+		const message = note === void 0 ? found : `${found}; ${note}`;
 		return fix === void 0 ? {
 			state: "ok",
 			message
@@ -7483,10 +7660,16 @@ function hubSkill(cli, source) {
 		rows: [{
 			name: "skill",
 			advisory: true,
-			run: (ctx) => findingAt(cli.version, ctx)
+			run: async (ctx) => findingOf(await skillCopies(cli.name, cli.version, ctx))
 		}],
 		notice: async () => {},
-		findingAt
+		nextAt: async (version, ctx) => {
+			const copies = await skillCopies(cli.name, version, ctx);
+			const note = pageNote(copies, from);
+			if (note !== void 0) ctx.notice(note);
+			const fix = fixFor(cli.name, copies, from);
+			return fix === void 0 ? [] : [fix];
+		}
 	};
 }
 //#endregion
@@ -7497,10 +7680,10 @@ function markersOf(name) {
 		end: `<!-- END:${name} -->`
 	};
 }
-/** `text` with the CLI's block between its markers, appended when they are missing; nothing else changes. */
-function withBlock({ name, text: block }, text) {
+/** `text` with the CLI's Agents section between its markers, appended when they are missing; nothing else changes. */
+function withSection({ name, text: section }, text) {
 	const { begin, end } = markersOf(name);
-	const whole = `${begin}\n${block}\n${end}`;
+	const whole = `${begin}\n${section}\n${end}`;
 	const start = text.indexOf(begin);
 	const stop = start === -1 ? -1 : text.indexOf(end, start);
 	if (stop !== -1) return `${text.slice(0, start)}${whole}${text.slice(stop + end.length)}`;
@@ -7515,7 +7698,7 @@ async function agentsMdAt(agents, root) {
 		agents,
 		change: "create"
 	};
-	if (withBlock(agents, existing) === existing) return {
+	if (withSection(agents, existing) === existing) return {
 		path,
 		agents,
 		change: null
@@ -7543,15 +7726,15 @@ function agentsRow(agents, install) {
 			const fix = `${install.runAs} skill install`;
 			if (change === "rewrite") return {
 				state: "problem",
-				message: `${path} holds a ${name} block other than the one ${fix} writes`,
+				message: `${path} holds a ${name} Agents section other than the one ${fix} writes`,
 				fix
 			};
 			if (change !== null) return {
 				state: "problem",
-				message: `${path} holds no ${name} block, so sessions in this repo do not know ${name}`,
+				message: `${path} holds no ${name} Agents section, so sessions in this repo do not know ${name}`,
 				fix
 			};
-			const holds = `${path} holds the ${name} block`;
+			const holds = `${path} holds the ${name} Agents section`;
 			const [edit] = await handEditsAt(root);
 			return edit === void 0 ? {
 				state: "ok",
@@ -7564,7 +7747,7 @@ function agentsRow(agents, install) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/agent.js
+//#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;
@@ -7598,16 +7781,22 @@ function isAgent(env) {
 	return MARKERS.some((marker) => marker(env));
 }
 //#endregion
-//#region ../agent-cli/dist/errno.js
+//#region ../agent-cli/dist/context/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 permissionAdvice({ path, access, rerun, env, platform }) {
+	if (platform === "win32") return {
+		hint: `a program may hold ${path} open: close it, then run the Next step`,
+		next: [rerun]
+	};
+	if (!isAgent(env)) return { hint: `check the permissions of ${path} and its folder` };
+	return {
+		hint: `your sandbox may block it: ask your user to type ! then the Next step, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`,
+		next: [rerun]
+	};
 }
 function fileErrorOf(scope) {
 	return (error, at) => classifyErrno(error, {
@@ -7624,13 +7813,14 @@ function classifyErrno(error, context) {
 		case "EBUSY": return new CliError({
 			code: PERMISSION_DENIED,
 			message: `permission denied: ${path}`,
-			hint: permissionHint(context)
+			...permissionAdvice(context)
 		}, { cause: error });
 		case "ENOSPC":
 		case "EDQUOT": return new CliError({
 			code: DISK_FULL,
 			message: `no space left on the disk holding ${path}`,
-			hint: `free space on that disk, then run \`${context.callerLine}\` again`
+			hint: "free space on that disk, then run the Next step",
+			next: [context.rerun]
 		}, { cause: error });
 		case "ENOENT":
 		case "ENOTDIR":
@@ -7653,7 +7843,7 @@ function classifyErrno(error, context) {
 	}
 }
 //#endregion
-//#region ../agent-cli/dist/files.js
+//#region ../agent-cli/dist/context/files.js
 const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
 /** Where the Runtime writes `path` before moving it into place; a dead writer's is swept. */
 function tempPathOf(path) {
@@ -7826,10 +8016,10 @@ function classifiedFiles(files, { cwd, fileError }) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/outputs.js
+//#region ../agent-cli/dist/context/outputs.js
 const OUTPUT_EXISTS = "OUTPUT_EXISTS";
 /** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
-async function checkOutputs({ invocation, commandLine, force, files }, outputs) {
+async function checkOutputs({ rerun, commandLine, force, files }, outputs) {
 	if (outputs === void 0 || force) return;
 	const found = await Promise.all(outputs.map((path) => files.exists(path)));
 	const existing = outputs.filter((_path, index) => found[index]);
@@ -7838,13 +8028,14 @@ async function checkOutputs({ invocation, commandLine, force, files }, outputs)
 	throw new CliError({
 		code: OUTPUT_EXISTS,
 		message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
-		hint: `to replace ${them}, run \`${commandLineOf(invocation, { add: [FORCE_FLAG.flag] })}\``
+		hint: `to replace ${them}, run the Next step`,
+		next: [rerun({ add: [FORCE_FLAG.flag] })]
 	});
 }
 /** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
 function outputsGuard(files, cwd) {
 	const unwritten = /* @__PURE__ */ new Set();
-	let forceLine = "";
+	let forceStep = [];
 	const exclusiveWrite = async (path, data, options) => {
 		const target = resolve(cwd, path);
 		unwritten.delete(target);
@@ -7859,7 +8050,8 @@ function outputsGuard(files, cwd) {
 			throw new CliError({
 				code: ALREADY_EXISTS,
 				message: error.message,
-				hint: `to replace it, run \`${forceLine}\``
+				hint: "to replace it, run the Next step",
+				next: [forceStep]
 			}, { cause: error });
 		}
 	};
@@ -7868,8 +8060,8 @@ function outputsGuard(files, cwd) {
 			...files,
 			write: (path, data, options) => unwritten.has(resolve(cwd, path)) ? exclusiveWrite(path, data, options) : files.write(path, data, options)
 		},
-		guard: (outputs, line) => {
-			forceLine = line;
+		guard: (outputs, step) => {
+			forceStep = step;
 			for (const path of outputs) unwritten.add(resolve(cwd, path));
 		}
 	};
@@ -7952,10 +8144,10 @@ async function planOf(cli, folder, agents, cwd, packageRoot) {
 		handEdits: agents === void 0 ? [] : await handEditsAt(root)
 	};
 }
-const BLOCK_VERBS = {
+const SECTION_VERBS = {
 	create: "create",
-	add: "add the block to",
-	rewrite: "rewrite the block in"
+	add: "add the Agents section to",
+	rewrite: "rewrite the Agents section in"
 };
 function renderPlan(cli, plan) {
 	const files = [
@@ -7967,7 +8159,7 @@ function renderPlan(cli, plan) {
 	return [
 		files.length === 0 ? `the ${cli.name} skill at ${plan.copy} already matches the package` : `would copy the ${cli.name} skill to ${plan.copy}:`,
 		...files,
-		...agentsMd === null ? [] : [agentsMd.change === null ? `${agentsMd.path} already holds the ${cli.name} block` : `would ${BLOCK_VERBS[agentsMd.change]} ${agentsMd.path}:\n${agentsMd.agents.text}`],
+		...agentsMd === null ? [] : [agentsMd.change === null ? `${agentsMd.path} already holds the ${cli.name} Agents section` : `would ${SECTION_VERBS[agentsMd.change]} ${agentsMd.path}:\n${agentsMd.agents.text}`],
 		...plan.handEdits.map((edit) => `by hand: ${edit}`)
 	].join("\n");
 }
@@ -7975,7 +8167,7 @@ function renderInstalled(cli, data) {
 	const { written, removed, agentsMd } = data;
 	return [
 		written.length + removed.length === 0 ? `the ${cli.name} skill at ${data.copy} already matches the package` : `copied the ${cli.name} skill to ${data.copy}: wrote ${written.length} files, removed ${removed.length}`,
-		...agentsMd === null ? [] : [agentsMd.changed ? `wrote the ${cli.name} block in ${agentsMd.path}` : `${agentsMd.path} already holds the ${cli.name} block`],
+		...agentsMd === null ? [] : [agentsMd.changed ? `wrote the ${cli.name} Agents section in ${agentsMd.path}` : `${agentsMd.path} already holds the ${cli.name} Agents section`],
 		...data.handEdits.map((edit) => `by hand: ${edit}`)
 	].join("\n");
 }
@@ -7983,21 +8175,20 @@ function editedRemovals(plan, ctx) {
 	const them = plan.remove.length === 1 ? "it" : "them";
 	return new CliError({
 		code: OUTPUT_EXISTS,
-		message: `\`${ctx.commandLine()}\` would remove ${plan.remove.map((file) => join(plan.copy, file)).join(", ")}`,
-		hint: `to remove ${them}, run \`${ctx.commandLine({ add: [FORCE_FLAG.flag] })}\``
+		message: `skill install would remove ${plan.remove.map((file) => join(plan.copy, file)).join(", ")}`,
+		hint: `to remove ${them}, run the Next step`,
+		next: [ctx.rerun({ add: [FORCE_FLAG.flag] })]
 	});
 }
 /** The built-in `skill install`, for a CLI whose skill ships in its package. */
-function skillInstallCommand(cli, folder, install, agents) {
-	const { runAs } = install;
+function skillInstallCommand(cli, folder, agents) {
 	return defineCommand$1({
-		name: "install",
-		description: agents === void 0 ? "copy this CLI's skill into the project" : "copy this CLI's skill into the project and write its AGENTS.md block",
+		description: agents === void 0 ? "copy this CLI's skill into the project" : "copy this CLI's skill into the project and write its Agents section",
 		examples: [{
-			command: `${runAs} skill install`,
+			command: `${cli.name} skill install`,
 			note: "install the skill this version ships"
 		}, {
-			command: `${runAs} skill install --dry-run`,
+			command: `${cli.name} skill install --dry-run`,
 			note: "show what it would change"
 		}],
 		effect: "write",
@@ -8012,7 +8203,7 @@ function skillInstallCommand(cli, folder, install, agents) {
 			const { agentsMd } = plan;
 			if (agentsMd !== null && agentsMd.change !== null) {
 				const existing = await orMissing(readFile(agentsMd.path, "utf8")) ?? "";
-				await ctx.files.write(agentsMd.path, withBlock(agentsMd.agents, existing));
+				await ctx.files.write(agentsMd.path, withSection(agentsMd.agents, existing));
 			}
 			return {
 				copy: plan.copy,
@@ -8103,45 +8294,53 @@ function packagedSkill(cli, { packaged: folder, agents: text }, install) {
 	};
 	return {
 		kind: "packaged",
-		builtIns: { skill: { install: skillInstallCommand(cli, folder, install, agents) } },
+		builtIns: { skill: { install: skillInstallCommand(cli, folder, agents) } },
 		rows: [{
 			name: "skill",
 			advisory: true,
 			run: (ctx) => findingOf(cli, folder, install, ctx)
 		}, ...agents === void 0 ? [] : [agentsRow(agents, install)]],
 		notice: (launch, ctx) => notice(cli, folder, install, launch, ctx),
-		findingAt: (_version, ctx) => findingOf(cli, folder, install, ctx)
+		nextAt: async (_version, ctx) => {
+			const { fix } = await findingOf(cli, folder, install, ctx);
+			return fix === void 0 ? [] : [fix];
+		}
 	};
 }
 //#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) {
+function skillOf$1(cli, install) {
 	const { skill } = cli;
-	return skill !== void 0 && "packaged" in skill ? packagedSkill(cli, skill, install) : hubSkill(cli, skill?.source);
+	return skill !== void 0 && "packaged" in skill ? packagedSkill(cli, skill, install) : hubSkill(cli, skill);
 }
 //#endregion
-//#region ../agent-cli/dist/interrupts.js
+//#region ../agent-cli/dist/context/interrupts.js
 const INTERRUPTED = "INTERRUPTED";
 const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
 /** How long an interrupted Command may take to settle before the run ends without it. */
 const GRACE_MS = 3e3;
 const GRACE_OVER = Symbol("grace over");
-function interruptedError(callerLine) {
+function interruptedError(rerun) {
 	return new CliError({
 		code: INTERRUPTED,
 		message: "interrupted before it finished",
-		hint: `to finish it, run \`${callerLine}\` again, unless it was stopped on purpose; if a tool timeout stopped it, give it longer`
+		hint: "to finish it, run the Next step, unless it was stopped on purpose; if a tool timeout stopped it, give it longer",
+		next: [rerun]
 	});
 }
-function waitHint(callerLine, bound) {
-	return bound === "timeout" ? `the call may have been billed: ask your user before running \`${callerLine}\` again` : `run \`${callerLine}\` again later, when the service it waits on may answer faster`;
+const BOUND_WORDS = {
+	deadline: "deadline",
+	ignoreStop: "timeout"
+};
+function waitHint(bound) {
+	return bound === "ignoreStop" ? "the call may have been billed: ask your user before running the Next step" : "run the Next step later, when the service it waits on may answer faster";
 }
-function deadlineError(commandLine, ms, hint, bound = "deadline") {
+function deadlineError(commandLine, ms, advice, bound = "deadline") {
 	return new CliError({
 		code: DEADLINE_EXCEEDED,
-		message: `${commandLine} ran past its ${ms} ms ${bound}`,
-		hint
+		message: `${commandLine} ran past its ${ms} ms ${BOUND_WORDS[bound]}`,
+		...advice
 	});
 }
 /** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
@@ -8149,24 +8348,24 @@ var RunControl = class {
 	signal;
 	#controller = new AbortController();
 	#commandLine;
-	#callerLine;
+	#rerun;
 	#outer;
-	#onOuterAbort = () => this.#controller.abort(interruptedError(this.#callerLine));
+	#onOuterAbort = () => this.#controller.abort(interruptedError(this.#rerun));
 	/** Each running must-finish step, tracked until it settles, with its name. */
 	#steps = /* @__PURE__ */ new Map();
 	#progress;
 	#clock;
 	#disposed = new AbortController();
-	/** The reasons this run's deadlines and timeouts aborted with, to tell them in a Command's error. */
+	/** The reasons this run's deadlines aborted with, to tell them in a Command's error. */
 	#abortReasons = /* @__PURE__ */ new WeakSet();
 	#graceCancel = new AbortController();
 	#endGrace = () => {};
 	#graceOver = new Promise((resolve) => {
 		this.#endGrace = resolve;
 	});
-	constructor({ commandLine, callerLine, outer, clock, progress, runDeadline }) {
+	constructor({ commandLine, rerun, outer, clock, progress, runDeadline }) {
 		this.#commandLine = commandLine;
-		this.#callerLine = callerLine;
+		this.#rerun = rerun;
 		this.#outer = outer;
 		this.#clock = clock;
 		this.#progress = progress;
@@ -8175,20 +8374,21 @@ var RunControl = class {
 		if (outer?.aborted === true) this.#onOuterAbort();
 		else outer?.addEventListener("abort", this.#onOuterAbort, { once: true });
 		if (runDeadline !== void 0) {
-			const { ms, hint } = runDeadline;
-			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, hint())));
+			const { ms, advice } = runDeadline;
+			after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, advice())));
 		}
 	}
-	deadline(ms) {
-		return AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
-	}
-	timeout(ms) {
-		return this.#abortsAfter(ms, "timeout");
+	deadline(ms, options = {}) {
+		return options.ignoreStop === true ? this.#abortsAfter(ms, "ignoreStop") : AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
 	}
 	#abortsAfter(ms, bound) {
 		const controller = new AbortController();
 		after(this.#clock, ms, this.#disposed.signal, () => {
-			const reason = deadlineError(this.#commandLine, ms, waitHint(this.#callerLine, bound), bound);
+			const advice = {
+				hint: waitHint(bound),
+				next: [this.#rerun]
+			};
+			const reason = deadlineError(this.#commandLine, ms, advice, bound);
 			this.#abortReasons.add(reason);
 			controller.abort(reason);
 		});
@@ -8221,8 +8421,8 @@ var RunControl = class {
 	/**
 	* The error a run ends with: an interrupt or the run deadline outranks what the Command threw,
 	* unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
-	* Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's or timeout's
-	* abort is reported as that abort, so a declared error keeps its own code.
+	* Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's abort is
+	* reported as that abort, so a declared error keeps its own code.
 	*/
 	errorAfter(error) {
 		if (this.signal.aborted) return error instanceof CliError && error.code === "INTERRUPTED" ? error : this.signal.reason;
@@ -8265,10 +8465,11 @@ function globalModulesDir(prefix) {
 	return process.platform === "win32" ? join(prefix, "node_modules") : join(prefix, "lib", "node_modules");
 }
 function notGlobal(ctx, message) {
-	return new CliError({
+	return runtimeError({
 		code: NOT_GLOBAL_INSTALL,
 		message,
-		hint: `install it with npm, so \`${ctx.cliName} update\` can replace it: ${installCommandLine(ctx.registry)}`
+		hint: "install it with npm by running the Next step, so its update Command can replace it",
+		next: [wholeLine(installCommandLine(ctx.registry))]
 	});
 }
 /**
@@ -8403,10 +8604,6 @@ function renderUpdate(cli, install, update) {
 		...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,
@@ -8417,7 +8614,6 @@ function interruptedAfterInstall(plan) {
 /** 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`,
@@ -8446,7 +8642,7 @@ function updateCommand(cli, install, skill, { bin, node }) {
 				latest,
 				installed: null,
 				upgrades: [],
-				next: await skillNext(skill, latest, ctx)
+				next: await skill.nextAt(latest, ctx)
 			};
 			ctx.signal.throwIfAborted();
 			ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
@@ -8459,7 +8655,7 @@ function updateCommand(cli, install, skill, { bin, node }) {
 					prefix
 				},
 				upgrades: await upgradesOf(plan.packageDir, from, latest),
-				next: await skillNext(skill, latest, ctx)
+				next: await skill.nextAt(latest, ctx)
 			};
 			if (ctx.signal.aborted) {
 				ctx.deliver(update);
@@ -8504,7 +8700,7 @@ function checkOf(cli, install, { bin, node }) {
 function globalInstall(cli, install) {
 	const adapter = {
 		runAs: runAsOf(cli),
-		builtIns: (launch) => ({ update: updateCommand(cli, install, skillOf(cli, adapter), launch) }),
+		builtIns: (launch) => ({ update: updateCommand(cli, install, skillOf$1(cli, adapter), launch) }),
 		exitClasses: ["source"],
 		check: (launch) => checkOf(cli, install, launch)
 	};
@@ -8590,7 +8786,7 @@ function readProject(projectFile, ctx) {
 			ok: true,
 			project: projectOf(projectFile, ctx.cwd, {
 				fileError: ctx.fileError,
-				callerLine: ctx.commandLine()
+				rerun: ctx.rerun()
 			})
 		};
 	} catch (error) {
@@ -8653,14 +8849,12 @@ function doctorChecks(cli, launch, read) {
 		...cli.project === void 0 ? [] : [projectRow(cli.project, read)],
 		...cli.doctor ?? [],
 		...toolRows(cli.tools ?? [], cli.commands),
+		...secretRows(cli.secrets ?? [], cli.commands),
 		installRow(check),
 		registryRow(cli, check),
-		...skillOf(cli, install).rows
+		...skillOf$1(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;
@@ -8731,24 +8925,33 @@ function render({ rows, next }, style) {
 		return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
 	}), ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
 }
-function failure(cliName, 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`
-	}));
+function failure(cliName, rerun, problems) {
+	const errors = problems.map(({ check, message, fix, code }) => {
+		const head = {
+			code: code ?? "DOCTOR_PROBLEMS",
+			message: `${cliName} doctor found a problem in ${check}: ${message}`
+		};
+		return runtimeError(fix === void 0 ? {
+			...head,
+			hint: "the row says what is wrong",
+			next: []
+		} : {
+			...head,
+			hint: "run the Next steps in order",
+			next: [wholeLine(fix), rerun]
+		});
+	});
 	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`,
+			command: `${cli.name} doctor`,
 			note: "check the setup and list the commands that fix it"
 		}, {
-			command: `${runAsOf(cli)} doctor --json`,
+			command: `${cli.name} doctor --json`,
 			note: "get the rows and fixes as data"
 		}],
 		effect: "read",
@@ -8768,7 +8971,7 @@ function doctorCommand(cli, launch) {
 			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
 			if (problems.length > 0) {
 				ctx.deliver(report);
-				throw failure(cli.name, ctx.commandLine(), problems);
+				throw failure(cli.name, ctx.rerun(), problems);
 			}
 			return report;
 		},
@@ -8786,53 +8989,104 @@ function builtInCommands(cli, launch) {
 	return {
 		doctor: doctorCommand(cli, launch),
 		...install.builtIns(launch),
-		...skillOf(cli, install).builtIns
+		...skillOf$1(cli, install).builtIns
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/confirm.js
-const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
-const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
-function checkConfirmation({ invocation, commandLine, given }, expected) {
-	if (given === expected) return;
-	const hint = `to confirm, run \`${commandLineOf(invocation, {
-		remove: [CONFIRM_FLAG.flag],
-		add: [CONFIRM_FLAG.flag, expected]
-	})}\``;
-	if (given === void 0) throw new UsageError({
-		code: CONFIRMATION_REQUIRED,
-		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
-		hint
-	});
-	throw new UsageError({
-		code: CONFIRMATION_MISMATCH,
-		message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
-		hint
-	});
+//#region ../agent-cli/dist/command-spec.js
+/** The group's Commands and groups that help and suggestions may name: hidden Commands left out. */
+function visibleCommands({ commands }) {
+	return Object.fromEntries(Object.entries(commands).filter(([, node]) => node.kind === "group" || !node.hidden));
 }
-//#endregion
-//#region ../agent-cli/dist/cost.js
-const NOT_CONFIRMED = "NOT_CONFIRMED";
-/** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
-function checkCost({ invocation, commandLine, yes }, cost) {
-	if (cost === void 0 || yes) return;
-	throw new CliError({
-		code: NOT_CONFIRMED,
-		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
-		hint: `to approve the cost, run \`${commandLineOf(invocation, { add: [YES_FLAG.flag] })}\``
+/** The words that label a Command in errors and spill files: its path, or the CLI's name for a single-Command CLI. */
+function commandLabel(path, cliName) {
+	return path.length === 0 ? [cliName] : path;
+}
+function declaredOf(command) {
+	if (!hasPlan(command)) return {
+		outputs: false,
+		force: void 0,
+		cost: false
+	};
+	return {
+		outputs: command.outputs !== void 0,
+		force: command.force,
+		cost: command.cost !== void 0
+	};
+}
+function withRunAs(example, { name, runAs }) {
+	const { command } = example;
+	return command === name || command.startsWith(`${name} `) ? {
+		...example,
+		command: `${runAs}${command.slice(name.length)}`
+	} : example;
+}
+function commandSpec(commandLine, command, { path, builtIn, names }) {
+	const list = command.rows === void 0 ? void 0 : listSpec(command.rows);
+	return {
+		kind: "command",
+		commandLine,
+		path,
+		command,
+		builtIn,
+		description: command.description,
+		help: command.help,
+		hidden: command.hidden === true,
+		operator: command.operator === true,
+		effect: command.effect,
+		examples: command.examples.map((example) => withRunAs(example, names)),
+		args: argFields(command.args),
+		options: optionFields(command.options),
+		standardFlags: standardFlagsFor(command.effect, declaredOf(command), list),
+		list,
+		output: list?.output ?? command.output
+	};
+}
+function group(commandLine, commands) {
+	return {
+		kind: "group",
+		commandLine,
+		commands
+	};
+}
+/** The root group of a multi-Command CLI: the author's Commands, then the Built-in Commands. */
+function groupSpec(names, commands, builtIns) {
+	const { runAs } = names;
+	return group(runAs, {
+		...specsOf(runAs, commands, {
+			path: [],
+			builtIn: false,
+			names
+		}),
+		...specsOf(runAs, builtIns, {
+			path: [],
+			builtIn: true,
+			names
+		})
 	});
 }
+function specsOf(commandLine, commands, { path, builtIn, names }) {
+	return Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node, {
+		path: [...path, key],
+		builtIn,
+		names
+	})]));
+}
+function specOf(commandLine, node, place) {
+	return isCommand(node) ? commandSpec(commandLine, node, place) : group(commandLine, specsOf(commandLine, node, place));
+}
 //#endregion
-//#region ../agent-cli/dist/operator.js
-const NEEDS_OPERATOR = "NEEDS_OPERATOR";
-/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
-function checkOperator({ operator, commandLine }, env, callerLine) {
-	if (!operator || !isAgent(env)) return;
-	throw new CliError({
-		code: NEEDS_OPERATOR,
-		message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
-		hint: `ask the operator to type: ! ${callerLine}`
-	});
+//#region ../agent-cli/dist/error-table.js
+/** The Error table a CLI declares, empty when it declares none. */
+function errorTableOf({ errors }) {
+	return errors ?? {};
+}
+/** The `CliError` for a code of `Table`, as `cliError` and `ctx.fail` build it. */
+function cliErrorOf(code, init, options) {
+	return new CliError({
+		...init,
+		code
+	}, options);
 }
 //#endregion
 //#region ../agent-cli/dist/exit-classes.js
@@ -8848,43 +9102,48 @@ const EXIT_CODES = {
 	bug: 70
 };
 const RUNTIME_EXIT_CLASSES = {
-	[INVALID_INPUT]: "caller",
-	[UNKNOWN_OPTION]: "caller",
-	[UNKNOWN_COMMAND]: "caller",
-	[UNKNOWN_FIELD]: "caller",
-	[CONFIRMATION_REQUIRED]: "caller",
-	[CONFIRMATION_MISMATCH]: "caller",
-	[NOT_CONFIRMED]: "operator",
-	[NEEDS_OPERATOR]: "operator",
-	[OUTPUT_EXISTS]: "caller",
-	[STDIN_STALLED]: "caller",
-	[INTERRUPTED]: "interrupted",
-	[DEADLINE_EXCEEDED]: "wait",
-	[INTERNAL]: "bug",
-	[PERMISSION_DENIED]: "operator",
-	[DISK_FULL]: "operator",
-	[NOT_FOUND]: "caller",
-	[ALREADY_EXISTS]: "caller",
-	[NOT_A_FILE]: "caller",
-	[TOOL_FAILED]: "operator",
-	[TOOL_MISSING]: "operator",
-	[PROJECT_INVALID]: "operator",
-	[DOCTOR_PROBLEMS]: "operator",
-	[NOT_GLOBAL_INSTALL]: "operator",
-	[REGISTRY_UNREACHABLE]: "operator",
-	[REGISTRY_AUTH]: "operator",
-	[INSTALL_FAILED]: "operator",
-	[NPM_FAILED]: "operator",
-	[NO_LATEST]: "source"
+	INVALID_INPUT: "caller",
+	UNKNOWN_OPTION: "caller",
+	UNKNOWN_COMMAND: "caller",
+	UNKNOWN_FIELD: "caller",
+	CONFIRMATION_REQUIRED: "caller",
+	CONFIRMATION_MISMATCH: "caller",
+	NOT_CONFIRMED: "operator",
+	NEEDS_OPERATOR: "operator",
+	OUTPUT_EXISTS: "caller",
+	STDIN_STALLED: "caller",
+	INTERRUPTED: "interrupted",
+	DEADLINE_EXCEEDED: "wait",
+	INTERNAL: "bug",
+	PERMISSION_DENIED: "operator",
+	DISK_FULL: "operator",
+	NOT_FOUND: "caller",
+	ALREADY_EXISTS: "caller",
+	NOT_A_FILE: "caller",
+	TOOL_FAILED: "operator",
+	TOOL_MISSING: "operator",
+	SECRET_MISSING: "operator",
+	PROJECT_INVALID: "operator",
+	DOCTOR_PROBLEMS: "operator",
+	NOT_GLOBAL_INSTALL: "operator",
+	REGISTRY_UNREACHABLE: "operator",
+	REGISTRY_AUTH: "operator",
+	INSTALL_FAILED: "operator",
+	NPM_FAILED: "operator",
+	NO_LATEST: "source"
 };
+function isRuntimeCode(code) {
+	return Object.hasOwn(RUNTIME_EXIT_CLASSES, code);
+}
 /** The codes of `errors` that the Runtime already declares, which a CLI cannot redeclare. */
 function runtimeCodesIn(errors) {
-	return Object.keys(errors).filter((code) => Object.hasOwn(RUNTIME_EXIT_CLASSES, code));
+	return Object.keys(errors).filter(isRuntimeCode);
 }
 function exitClassOfOne(error, errors) {
 	if (!(error instanceof CliError)) return "bug";
 	if (error instanceof UsageError) return "caller";
-	return RUNTIME_EXIT_CLASSES[error.code] ?? errors[error.code]?.class ?? "bug";
+	if (isRuntimeCode(error.code)) return RUNTIME_EXIT_CLASSES[error.code];
+	return errors[error.code]?.class ?? "bug";
 }
 function isBug(error, errors) {
 	return exitClassOfOne(error, errors) === "bug";
@@ -8912,7 +9171,7 @@ function reachableExitClasses(cli) {
 		"wait",
 		...cli.commands === void 0 ? [] : installOf(cli).exitClasses
 	];
-	const own = Object.values(cli.errors ?? {}).map((declaration) => declaration.class);
+	const own = Object.values(errorTableOf(cli)).map((declaration) => declaration.class);
 	return /* @__PURE__ */ new Set([...runtime, ...own]);
 }
 /** The signal named by an interrupt's abort reason; any other reason counts as Ctrl-C. */
@@ -8929,17 +9188,31 @@ function exitCodeOf(error, errors, stop) {
 }
 //#endregion
 //#region ../agent-cli/dist/agent-cli.js
-function checkOwnCodes(cli) {
-	const redeclared = runtimeCodesIn(cli.errors ?? {});
-	if (redeclared.length > 0) throw new Error(`${cli.name} declares ${redeclared.join(", ")}, an error code the Runtime already declares`);
+function checkOwnCodes(errors) {
+	const redeclared = runtimeCodesIn(errors);
+	if (redeclared.length > 0) throw new Error(`The Error table declares ${redeclared.join(", ")}, an error code the Runtime already declares`);
 }
-function defineCli$1(cli) {
-	checkOwnCodes(cli);
+function checkTree(commands, path, table) {
+	for (const [key, node] of Object.entries(commands)) {
+		const at = [...path, key];
+		if (isCommand(node)) checkCommand(node, at.join(" "), table);
+		else checkTree(node, at, table);
+	}
+}
+function checkSkillPage({ name, skill }) {
+	if (skill === void 0 || !("page" in skill)) return;
+	if (!URL.canParse(skill.page) || new URL(skill.page).protocol !== "https:") throw new Error(`${name} declares skill.page ${skill.page}, which is not an https URL`);
+}
+function checkCli(cli) {
+	const table = errorTableOf(cli);
+	checkSkillPage(cli);
 	if (cli.commands === void 0) {
-		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`);
+		checkCommand(cli.command, commandLabel([], cli.name).join(" "), table);
+		if (skillOf$1(cli, installOf(cli)).kind === "packaged") throw new Error(`${cli.name} declares a Packaged skill, which only a CLI with several Commands can install`);
 		return cli;
 	}
 	const { commands } = cli;
+	checkTree(commands, [], table);
 	const taken = Object.keys(builtInCommands(cli, {
 		bin: void 0,
 		node: void 0
@@ -8947,107 +9220,541 @@ function defineCli$1(cli) {
 	if (taken.length > 0) throw new Error(`${cli.name} defines ${taken.join(", ")}, a built-in Command it cannot replace`);
 	return cli;
 }
-/**
-* Declares the CLI's ports and its Project file's settings once; the `defineCommand` and
-* `defineCli` it returns type `ctx.ports` and `ctx.project`.
-*/
-function agentCli() {
-	return {
-		defineCommand: defineCommandFor(),
-		defineCli: defineCli$1
-	};
-}
-//#endregion
-//#region ../agent-cli/dist/error-table.js
-/**
-* 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;
-}
-/**
-* A `CliError` for a code of `table`, whose `details` must match the code's schema. The `hint`
-* names the next command to run and says whether running it again can help; `retryAt` (ISO 8601)
-* is allowed only on a wait-class code.
-*/
-function cliError(_table, code, init, options) {
-	return new CliError({
-		...init,
-		code
-	}, options);
-}
-//#endregion
-//#region ../agent-cli/dist/command-spec.js
-/** The group's Commands and groups that help and suggestions may name: hidden Commands left out. */
-function visibleCommands({ commands }) {
-	return Object.fromEntries(Object.entries(commands).filter(([, node]) => node.kind === "group" || !node.hidden));
+function nameOf({ name, bin }) {
+	const bins = typeof bin === "object" ? Object.keys(bin) : [];
+	const [only] = bins;
+	return bins.length === 1 && only !== void 0 ? only : name.replace(/^@[^/]+\//, "");
 }
-function declaredOf(command) {
-	if (!hasPlan(command)) return {
-		outputs: false,
-		force: void 0,
-		cost: false
+function installFrom(name, manifest, install) {
+	if (install === "dependency") return {
+		mode: "dependency",
+		package: manifest.name
 	};
-	return {
-		outputs: command.outputs !== void 0,
-		force: command.force,
-		cost: command.cost !== void 0
+	if (install !== "global") return {
+		mode: "dependency",
+		package: manifest.name,
+		lockstep: install.lockstep
 	};
-}
-const SINGLE_COMMAND = {
-	path: [],
-	builtIn: false
-};
-function commandSpec(commandLine, command, { path, builtIn } = SINGLE_COMMAND) {
-	const list = command.rows === void 0 ? void 0 : listSpec(command.rows);
+	const registry = manifest.publishConfig?.registry;
+	if (registry === void 0) throw new Error(`${name} declares a Global install, which needs publishConfig.registry in its package.json`);
 	return {
-		kind: "command",
-		commandLine,
-		path,
-		command,
-		builtIn,
-		description: command.description,
-		help: command.help,
-		hidden: command.hidden === true,
-		operator: command.operator === true,
-		effect: command.effect,
-		examples: command.examples,
-		args: argFields(command.args),
-		options: optionFields(command.options),
-		standardFlags: standardFlagsFor(command.effect, declaredOf(command), list),
-		list,
-		output: list?.output ?? command.output
+		mode: "global",
+		package: manifest.name,
+		registry
 	};
 }
-function group(commandLine, commands) {
+function resolved(cli) {
+	const { manifest, ...declared } = cli;
+	const name = nameOf(manifest);
+	const about = {
+		name,
+		version: manifest.version,
+		description: manifest.description
+	};
+	if (declared.commands === void 0) return {
+		...declared,
+		...about
+	};
+	const { install, ...rest } = declared;
 	return {
-		kind: "group",
-		commandLine,
-		commands
+		...rest,
+		...about,
+		...manifest.engines === void 0 ? {} : { engines: manifest.engines },
+		...install === void 0 ? {} : { install: installFrom(name, manifest, install) }
 	};
 }
-/** The root group of a multi-Command CLI: the author's Commands, then the Built-in Commands. */
-function groupSpec(commandLine, commands, builtIns) {
-	return group(commandLine, {
-		...specsOf(commandLine, commands, {
-			path: [],
-			builtIn: false
+/**
+* Takes the CLI's ports factory, Project file and Error table once; the `defineCommand`,
+* `defineCli` and `cliError` it returns are typed by them.
+*/
+function agentCli(values = {}) {
+	checkOwnCodes(errorTableOf(values));
+	return {
+		defineCommand: defineCommandFor(),
+		defineCli: (cli) => checkCli({
+			...resolved(cli),
+			...values
 		}),
-		...specsOf(commandLine, builtIns, {
-			path: [],
-			builtIn: true
-		})
-	});
-}
-function specsOf(commandLine, commands, { path, builtIn }) {
-	return Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node, {
-		path: [...path, key],
-		builtIn
-	})]));
-}
-function specOf(commandLine, node, place) {
-	return isCommand(node) ? commandSpec(commandLine, node, place) : group(commandLine, specsOf(commandLine, node, place));
+		cliError: cliErrorOf
+	};
+}
+//#endregion
+//#region ../agent-cli/dist/context/side-task.js
+/** How long a run waits for its Side task once its output is written. */
+const SIDE_TASK_WAIT_MS = 1e3;
+const noSideTask = async () => {};
+function waitOver() {
+	return new DOMException(`the side task ran past its ${SIDE_TASK_WAIT_MS} ms wait`, "TimeoutError");
+}
+function startSideTask(sideTask, runWith, { clock, failed }) {
+	if (sideTask === void 0) return noSideTask;
+	const controller = new AbortController();
+	const { signal } = controller;
+	const running = (async () => sideTask(runWith(signal)))().catch((error) => {
+		if (!(signal.aborted && error === signal.reason)) failed(error);
+	});
+	return async () => {
+		const waited = new AbortController();
+		const capped = new Promise((resolve) => after(clock, SIDE_TASK_WAIT_MS, waited.signal, () => {
+			const over = waitOver();
+			failed(over);
+			controller.abort(over);
+			resolve();
+		}));
+		await Promise.race([running, capped]);
+		waited.abort();
+	};
+}
+//#endregion
+//#region ../agent-cli/dist/command-line/suggest.js
+const MAX_DISTANCE = 3;
+const MIN_SIMILARITY = .4;
+function distance(a, b) {
+	const width = b.length + 1;
+	const d = Array.from({ length: (a.length + 1) * width }, (_, k) => {
+		const i = Math.floor(k / width);
+		const j = k % width;
+		return i === 0 || j === 0 ? i + j : 0;
+	});
+	const at = (i, j) => d[i * width + j] ?? 0;
+	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
+		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+		const edit = Math.min(at(i - 1, j) + 1, at(i, j - 1) + 1, at(i - 1, j - 1) + cost);
+		const transposed = i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1];
+		d[i * width + j] = transposed ? Math.min(edit, at(i - 2, j - 2) + 1) : edit;
+	}
+	return at(a.length, b.length);
+}
+function isClose(word, candidate) {
+	const length = Math.max(word.length, candidate.length);
+	const edits = distance(word, candidate);
+	return candidate.length > 1 && edits < MAX_DISTANCE && (length - edits) / length > MIN_SIMILARITY;
+}
+/** The names closest to `word`, sorted, several when they tie, or none when nothing is close. */
+function closestNames(word, names) {
+	const close = [...new Set(names)].filter((candidate) => isClose(word, candidate));
+	const best = Math.min(...close.map((candidate) => distance(word, candidate)));
+	return close.filter((candidate) => distance(word, candidate) === best).sort((a, b) => a.localeCompare(b));
+}
+/** The long flags closest to `flag`, sorted, or none for a short flag or when nothing is close. */
+function closestFlags(flag, flags) {
+	if (!flag.startsWith("--")) return [];
+	const names = flags.map((candidate) => candidate.slice(2));
+	return closestNames(flag.slice(2), names).map((name) => `--${name}`);
+}
+/** The one long flag closest to `flag`, or none when nothing is close or several tie. */
+function closestFlag(flag, flags) {
+	const closest = closestFlags(flag, flags);
+	return closest.length === 1 ? closest[0] : void 0;
+}
+//#endregion
+//#region ../agent-cli/dist/command-line/parse-input.js
+const NO_INPUT = object({});
+const WHITESPACE = /\s/;
+function knownFlags(spec) {
+	return [...spec.options.map((field) => ({
+		flag: field.label,
+		takes: field.type === "boolean" ? "nothing" : "optional value"
+	})), ...spec.standardFlags.map(({ flag, takes }) => ({
+		flag,
+		takes
+	}))];
+}
+function candidateFlags(known) {
+	return [
+		...known.map(({ flag }) => flag),
+		VERSION_FLAG,
+		HELP_FLAG
+	];
+}
+function unknownOptionsOf(words, candidates) {
+	return words.map((word) => {
+		const flag = word.split("=")[0] ?? word;
+		return {
+			flag,
+			suggestion: closestFlag(flag, candidates)
+		};
+	});
+}
+function optionValue(field, all) {
+	if (field.variadic) return variadicValue(field, (all ?? []).filter((value) => value !== true));
+	const raw = all?.[all.length - 1];
+	return field.type === "boolean" && raw === true && field.label === `--no-${field.name}` ? false : raw;
+}
+function converted(field, raw) {
+	if (Array.isArray(raw)) return raw.map((element) => converted(field, element));
+	if (field.type !== "number" || typeof raw !== "string" || raw.trim() === "") return raw;
+	const number = Number(raw);
+	return Number.isNaN(number) ? raw : number;
+}
+function variadicValue(field, values) {
+	return values.length === 0 && !field.required ? void 0 : values;
+}
+function parse(schema, values) {
+	const input = Object.fromEntries([...values].filter(([, raw]) => raw !== void 0).map(([field, raw]) => [field.key, converted(field, raw)]));
+	return schema.safeParse(input);
+}
+function issueLines(result, values, { howToPass, arrayIssueLine, reported = [], fromStdin }) {
+	if (result.success) return [];
+	return result.error.issues.flatMap((issue) => {
+		const field = [...values.keys()].find((candidate) => candidate.key === issue.path[0]);
+		if (field === void 0) return [`  ${issue.message}`];
+		if (reported.includes(field)) return [];
+		const raw = values.get(field);
+		if (raw === void 0) return [`  ${field.label}: required, ${howToPass(field)}`];
+		if (field === fromStdin) return [`  ${field.label} from stdin: ${issue.message}`];
+		return Array.isArray(raw) ? [arrayIssueLine(field, raw, issue)] : [`  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`];
+	});
+}
+function flagValuesIssueLine(field, raw, issue) {
+	const [, element] = issue.path;
+	if (typeof element === "number") return `  ${field.label} ${JSON.stringify(raw[element])}: ${issue.message}`;
+	return raw.length === 0 ? `  ${field.label}: ${issue.message}, pass ${field.usage}` : `  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`;
+}
+function operandsIssueLine(field, raw, issue, first) {
+	const [, element] = issue.path;
+	if (typeof element === "number") return `  ${field.label} ${JSON.stringify(raw[element])} (argument ${first + element}): ${issue.message}`;
+	return raw.length === 0 ? `  ${field.label}: ${issue.message}, pass them as arguments from ${first}` : `  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`;
+}
+function unknownLine({ flag, suggestion }) {
+	return `  unknown option '${flag}'${suggestion === void 0 ? "" : ` (did you mean ${suggestion}?)`}`;
+}
+function invalidInput(commandLine, invocation, unknown, otherLines) {
+	const renames = new Map(unknown.flatMap(({ flag, suggestion }) => suggestion === void 0 ? [] : [[flag, suggestion]]));
+	const correctable = otherLines.length === 0 && renames.size === unknown.length;
+	return new UsageError({
+		code: INVALID_INPUT,
+		message: [
+			`invalid input for \`${commandLine}\``,
+			...unknown.map(unknownLine),
+			...otherLines
+		].join("\n"),
+		hint: correctable ? `did you mean \`${commandLineRenaming(invocation, renames)}\`?` : `run \`${commandLine} --help\` to see the expected input`
+	});
+}
+function stdinFieldOf(spec, operands) {
+	const index = spec.args.findIndex((field) => field.stdin);
+	return operands[index]?.value === "-" ? spec.args[index] : void 0;
+}
+/** The name of the routed Command's arg given `-`, which takes its text from stdin. */
+function stdinArgOf({ spec, words }) {
+	return stdinFieldOf(spec, tokenize(words, knownFlags(spec)).operands)?.name;
+}
+async function stdinTextOf(spec, operands, read) {
+	const field = stdinFieldOf(spec, operands);
+	return field === void 0 ? void 0 : {
+		field,
+		text: await read(field)
+	};
+}
+async function parseInput(spec, words, invocation, readStdin) {
+	const { command, args: argFields, options: optionFields } = spec;
+	const pageFields = spec.list?.pageFields ?? [];
+	const known = knownFlags(spec);
+	const { operands, unknownOptions, values, occurrences } = tokenize(words, known);
+	const stdin = await stdinTextOf(spec, operands, readStdin);
+	if (values.get(CONFIRM_FLAG.flag) === true) throw invalidInputError(spec.commandLine, `option '${CONFIRM_FLAG.usage}' argument missing`);
+	const missing = [...optionFields, ...pageFields].filter((field) => field.type !== "boolean" && (field.variadic ? occurrences.get(field.label)?.includes(true) : values.get(field.label) === true));
+	const argValue = (field, index) => {
+		if (field === stdin?.field) return stdin.text;
+		if (!field.variadic) return operands[index]?.value;
+		return variadicValue(field, operands.slice(index).filter((operand) => !operand.afterUnknownOption).map((operand) => operand.value));
+	};
+	const argValues = new Map(argFields.map((field, index) => [field, argValue(field, index)]));
+	const extraOperands = argFields.some((field) => field.variadic) ? [] : operands.slice(argFields.length);
+	const valuesOf = (fields) => new Map(fields.map((field) => [field, missing.includes(field) ? void 0 : optionValue(field, occurrences.get(field.label))]));
+	const flagWording = {
+		howToPass: (field) => `pass ${field.usage}`,
+		arrayIssueLine: flagValuesIssueLine,
+		reported: missing
+	};
+	const optionValues = valuesOf(optionFields);
+	const pageValues = valuesOf(pageFields);
+	const args = parse(command.args ?? NO_INPUT, argValues);
+	const options = parse(command.options ?? NO_INPUT, optionValues);
+	const page = parse(PAGE_INPUT, pageValues);
+	const unknown = unknownOptionsOf(unknownOptions, candidateFlags(known));
+	const otherLines = [
+		...missing.map((field) => `  ${field.label}: missing value, pass ${field.usage}`),
+		...extraOperands.filter((operand) => !operand.afterUnknownOption).map((operand) => `  unexpected argument ${JSON.stringify(operand.value)}`),
+		...issueLines(args, argValues, {
+			howToPass: (field) => `pass it as argument ${argFields.indexOf(field) + 1}`,
+			arrayIssueLine: (field, raw, issue) => operandsIssueLine(field, raw, issue, argFields.indexOf(field) + 1),
+			fromStdin: stdin?.field
+		}),
+		...issueLines(options, optionValues, flagWording),
+		...issueLines(page, pageValues, flagWording)
+	];
+	if (unknown.length === 0 && otherLines.length === 0 && args.success && options.success && page.success) return {
+		input: {
+			...args.data,
+			...options.data
+		},
+		page: page.data,
+		values
+	};
+	const [onlyWord] = unknownOptions;
+	if (onlyWord !== void 0 && unknownOptions.length === 1 && WHITESPACE.test(onlyWord) && argFields.some((field) => field.stdin && argValues.get(field) === void 0)) throw stdinTextError(spec.commandLine, invocation, onlyWord);
+	const [only] = unknown;
+	if (only !== void 0 && unknown.length === 1 && otherLines.length === 0) throw unknownOptionError(spec.commandLine, invocation, only.flag, only.suggestion === void 0 ? [] : [only.suggestion]);
+	throw invalidInput(spec.commandLine, invocation, unknown, otherLines);
+}
+/**
+* The validated input and Standard flag values of the routed Command, or one usage error; the arg
+* given `-` takes its text from `readStdin`.
+*/
+async function parseCommand({ spec, words, json }, invocation, readStdin) {
+	const { input, page, values } = await parseInput(spec, words, invocation, readStdin);
+	const confirm = values.get(CONFIRM_FLAG.flag);
+	return {
+		input,
+		flags: {
+			json,
+			dryRun: values.get(DRY_RUN_FLAG.flag) === true,
+			confirm: typeof confirm === "string" ? confirm : void 0,
+			yes: values.get(YES_FLAG.flag) === true,
+			force: values.get(FORCE_FLAG.flag) === true,
+			page,
+			fields: spec.list === void 0 ? void 0 : selectedFields(values, spec.list.rowFields, spec.commandLine)
+		}
+	};
+}
+//#endregion
+//#region ../agent-cli/dist/command-line/route.js
+const GROUP_FLAGS = [
+	HELP_FLAG,
+	VERSION_FLAG,
+	JSON_FLAG.flag
+];
+function beforeEnd(words) {
+	const end = words.indexOf("--");
+	return end === -1 ? words : words.slice(0, end);
+}
+function wantsHelp(words) {
+	return beforeEnd(words).some((word) => word === "--help" || word === "-h");
+}
+function childOf(group, name) {
+	return Object.hasOwn(group.commands, name) ? group.commands[name] : void 0;
+}
+function isFlagLike(word) {
+	return word.length > 1 && word[0] === "-";
+}
+function walk(node, words, json, invocation) {
+	const help = {
+		kind: "help",
+		node,
+		json
+	};
+	if (node.kind === "command") return wantsHelp(words) ? help : {
+		kind: "command",
+		spec: node,
+		words,
+		json
+	};
+	const [first, ...rest] = words;
+	if (first === void 0) return help;
+	const child = childOf(node, first);
+	if (child !== void 0) return walk(child, rest, json, invocation);
+	if (first === "--") {
+		const [name, ...after] = rest;
+		if (name === void 0) return help;
+		const named = childOf(node, name);
+		if (named !== void 0) return walk(named, ["--", ...after], json, invocation);
+		return unknownCommand(node, name, json);
+	}
+	if (wantsHelp(words)) return help;
+	if (isFlagLike(first)) {
+		const suggestions = closestFlags(first, GROUP_FLAGS);
+		return {
+			kind: "usage error",
+			error: unknownOptionError(node.commandLine, invocation, first, suggestions),
+			node,
+			json
+		};
+	}
+	return unknownCommand(node, first, json);
+}
+function unknownCommand(group, name, json) {
+	const suggestions = closestNames(name, Object.keys(visibleCommands(group)));
+	return {
+		kind: "usage error",
+		error: unknownCommandError(group.commandLine, name, suggestions),
+		node: group,
+		json
+	};
+}
+/** Walks the caller's command line through the Commands to the one it names, or to a stop. */
+function route(root, invocation) {
+	const { argv } = invocation;
+	const options = beforeEnd(argv);
+	const json = options.includes(JSON_FLAG.flag);
+	if (options.includes("--version")) return {
+		kind: "version",
+		json
+	};
+	return walk(root, argv.filter((word, index) => !(index < options.length && word === JSON_FLAG.flag)), json, invocation);
+}
+//#endregion
+//#region ../agent-cli/dist/command-line/route-line.js
+/** Routes `argv`, the line's words after the Run-as, to a Command of `root`. */
+function routeLine(root, runAs, argv) {
+	if (!argv.ok) return {
+		ok: false,
+		reason: `it does not tokenize: ${argv.reason}`
+	};
+	const invocation = {
+		runAs,
+		argv: argv.words,
+		flags: []
+	};
+	const routed = route(root, invocation);
+	switch (routed.kind) {
+		case "usage error": return {
+			ok: false,
+			reason: routed.error.message
+		};
+		case "help":
+		case "version": return {
+			ok: false,
+			reason: "it names no Command"
+		};
+		case "command": return {
+			ok: true,
+			routed,
+			invocation
+		};
+	}
+}
+//#endregion
+//#region ../agent-cli/dist/command-line/shell-words.js
+const BLANK = /\s/;
+const SHELL_SYNTAX = /* @__PURE__ */ new Set([
+	"|",
+	"&",
+	";",
+	">",
+	"(",
+	")",
+	"$",
+	"`"
+]);
+const STDIN_REDIRECT = "<";
+const DOUBLE_QUOTE_ESCAPES = /* @__PURE__ */ new Set([
+	"$",
+	"`",
+	"\"",
+	"\\"
+]);
+function quotedFrom(line, start, quote) {
+	let word = "";
+	for (let index = start; index < line.length; index += 1) {
+		const char = line[index] ?? "";
+		if (char === quote) return {
+			word,
+			end: index + 1
+		};
+		const next = line[index + 1];
+		if (quote === "\"" && char === "\\" && next !== void 0 && DOUBLE_QUOTE_ESCAPES.has(next)) {
+			word += next;
+			index += 1;
+		} else word += char;
+	}
+}
+function skipBlanks(line, start) {
+	let index = start;
+	while (BLANK.test(line[index] ?? "")) index += 1;
+	return index;
+}
+function isBoundary(char) {
+	return BLANK.test(char) || char === STDIN_REDIRECT || SHELL_SYNTAX.has(char);
+}
+function wordFrom(line, start) {
+	let word = "";
+	let index = start;
+	while (index < line.length && !isBoundary(line[index] ?? "")) {
+		const char = line[index] ?? "";
+		if (char === "'" || char === "\"") {
+			const quoted = quotedFrom(line, index + 1, char);
+			if (quoted === void 0) return { reason: `its ${char} is never closed` };
+			word += quoted.word;
+			index = quoted.end;
+		} else if (char === "\\") {
+			word += line[index + 1] ?? "";
+			index += 2;
+		} else {
+			word += char;
+			index += 1;
+		}
+	}
+	return {
+		word,
+		end: index
+	};
+}
+/**
+* The words a POSIX shell would pass for `line`, without the file of a `< file` redirect; a reason
+* instead when a quote is left open or the line uses other shell syntax.
+*/
+function shellWords(line) {
+	const words = [];
+	let index = skipBlanks(line, 0);
+	while (index < line.length) {
+		const redirect = line[index] === STDIN_REDIRECT;
+		if (redirect) index = skipBlanks(line, index + 1);
+		const char = line[index];
+		if (char === void 0 || char === STDIN_REDIRECT) return {
+			ok: false,
+			reason: "its `<` names no file"
+		};
+		if (SHELL_SYNTAX.has(char)) return {
+			ok: false,
+			reason: `it uses the shell's \`${char}\``
+		};
+		const scanned = wordFrom(line, index);
+		if ("reason" in scanned) return {
+			ok: false,
+			reason: scanned.reason
+		};
+		if (!redirect) words.push(scanned.word);
+		index = skipBlanks(line, scanned.end);
+	}
+	return {
+		ok: true,
+		words
+	};
+}
+//#endregion
+//#region ../agent-cli/dist/check-next-steps.js
+function argvOf(words, runAs) {
+	const line = shellWords(lineOf(words, runAs));
+	const lead = shellWords(runAs);
+	if (!lead.ok) return lead;
+	if (!line.ok) return line;
+	return {
+		ok: true,
+		words: line.words.slice(lead.words.length)
+	};
+}
+/**
+* Why `step` would not run a Command of `root`, or `undefined` when it would. A line given whole is
+* not checked, since it may run another program.
+*/
+function nextStepProblem(root, runAs, step) {
+	const words = wordsOf(step);
+	if (words === void 0) return void 0;
+	const line = routeLine(root, runAs, argvOf(words, runAs));
+	if (!line.ok) return line.reason;
+	const { routed } = line;
+	const { unknownOptions } = tokenize(routed.words, knownFlags(routed.spec));
+	return unknownOptions.length === 0 ? void 0 : `unknown option ${unknownOptions.join(", ")}`;
+}
+/** `error`, or a bug naming each of its Next steps that would not run. */
+function checkedNextSteps(error, check, runAs) {
+	const problems = errorsOf(error).flatMap((leaf) => leaf instanceof CliError ? leaf.next.flatMap((step) => {
+		const problem = check(step);
+		return problem === void 0 ? [] : [`\`${lineOf(step, runAs)}\`, a Next step of ${leaf.code}: ${problem}`];
+	}) : []);
+	return problems.length === 0 ? error : new Error(`a Next step would not run: ${problems.join("; ")}`, { cause: error });
 }
 //#endregion
 //#region ../agent-cli/dist/help.js
@@ -9115,6 +9822,7 @@ function groupHelp(group, style) {
 }
 const EFFECT_NOTES = {
 	read: "changes nothing",
+	act: "changes the state of a running program, not files or services; may act again each time it runs",
 	write: "changes something; show the Plan with --dry-run",
 	destructive: "changes something hard to undo; show the Plan with --dry-run, run with --confirm",
 	serve: "changes nothing; prints its data at once, then runs until Ctrl-C, which exits 0"
@@ -9170,7 +9878,7 @@ function inputSchema(schema) {
 function optionsSchema(options) {
 	return inputSchema(object(Object.fromEntries(options.map(({ name, schema }) => [name, schema]))));
 }
-function commandData(spec) {
+function commandData(spec, table) {
 	return {
 		name: spec.commandLine,
 		description: spec.description,
@@ -9178,6 +9886,11 @@ function commandData(spec) {
 		effect: spec.effect,
 		operator: spec.operator,
 		examples: spec.examples,
+		secrets: spec.command.secrets ?? [],
+		errors: (spec.command.errors ?? []).map((code) => ({
+			code,
+			class: table[code]?.class
+		})),
 		args: inputSchema(spec.command.args ?? object({})),
 		options: optionsSchema(spec.options),
 		standardFlags: spec.standardFlags.map(({ usage, description, schema }) => ({
@@ -9188,13 +9901,13 @@ function commandData(spec) {
 		output: spec.output === void 0 ? null : toJSONSchema(spec.output, { unrepresentable: "any" })
 	};
 }
-function nodeData(node) {
-	return node.kind === "command" ? commandData(node) : groupData(node);
+function nodeData(node, table) {
+	return node.kind === "command" ? commandData(node, table) : groupData(node, table);
 }
-function groupData(group) {
+function groupData(group, table) {
 	return {
 		name: group.commandLine,
-		commands: Object.values(visibleCommands(group)).map(nodeData)
+		commands: Object.values(visibleCommands(group)).map((node) => nodeData(node, table))
 	};
 }
 function printed$1(data) {
@@ -9206,21 +9919,31 @@ function errorsData(errors) {
 		details: declaration.details === void 0 ? null : toJSONSchema(declaration.details, { unrepresentable: "any" })
 	}]));
 }
-function cliHelpJson({ name, version, description, errors }, root) {
-	return printed$1({
+function publishedTable(table, root) {
+	if (root.kind !== "command") return table;
+	const declared = new Set(root.command.errors ?? []);
+	return Object.fromEntries(Object.entries(table).filter(([code]) => declared.has(code)));
+}
+function cliHelpJson(cli, root) {
+	const { name, version, description } = cli;
+	const header = {
 		name,
 		version,
-		description,
-		...nodeData(root),
+		description
+	};
+	const table = errorTableOf(cli);
+	return printed$1({
+		...header,
+		...nodeData(root, table),
 		name,
-		errors: errorsData(errors ?? {})
+		errors: errorsData(publishedTable(table, root))
 	});
 }
-function groupHelpJson(group) {
-	return printed$1(groupData(group));
+function groupHelpJson(group, table) {
+	return printed$1(groupData(group, table));
 }
-function commandHelpJson(spec) {
-	return printed$1(commandData(spec));
+function commandHelpJson(spec, table) {
+	return printed$1(commandData(spec, table));
 }
 //#endregion
 //#region ../agent-cli/dist/output.js
@@ -9229,14 +9952,14 @@ function withTrailingNewline(text) {
 	return text === "" || text.endsWith("\n") ? text : `${text}\n`;
 }
 function printed(value, render, { json, invocation, style, fields }) {
-	if (!(value instanceof Page)) return json ? `${JSON.stringify(value)}\n` : withTrailingNewline(render(style));
+	if (!(value instanceof Page)) return json ? `${JSON.stringify(value ?? null)}\n` : withTrailingNewline(render(style));
 	const page = printedPage(value, invocation);
-	if (fields === void 0) return json ? `${JSON.stringify(page)}\n` : `${withTrailingNewline(render(style))}${pageFooter(page)}`;
+	if (fields === void 0) return json ? `${JSON.stringify(page)}\n` : `${withTrailingNewline(render(style))}${pageFooter(page, style)}`;
 	const rows = projected(page.items, fields);
 	return json ? `${JSON.stringify({
 		...page,
 		items: rows
-	})}\n` : `${renderRows(rows, fields)}${pageFooter(page)}`;
+	})}\n` : `${renderRows(rows, fields)}${pageFooter(page, style)}`;
 }
 /** A progress message as stderr carries it: one JSON object per line under `--json` (ADR 0006). */
 function progressLine(message, json) {
@@ -9252,6 +9975,7 @@ function stderrLine(key, text, json) {
 function errorText(error, format) {
 	const text = formatRuntimeError(error, {
 		...format,
+		runAs: format.invocation.runAs,
 		isBug: (each) => isBug(each, format.errors)
 	});
 	const { usageHelp, json } = format;
@@ -9275,10 +9999,11 @@ const STOPPED_RESULT = {
 	exitCode: SUCCESS_EXIT_CODE
 };
 function errorResult(error, format) {
+	const checked = format.checkNextStep === void 0 ? error : checkedNextSteps(error, format.checkNextStep, format.invocation.runAs);
 	return {
 		stdout: "",
-		stderr: errorText(error, format),
-		exitCode: exitCodeOf(error, format.errors, format.stop)
+		stderr: errorText(checked, format),
+		exitCode: exitCodeOf(checked, format.errors, format.stop)
 	};
 }
 async function commandResult(settled, format, spill) {
@@ -9292,12 +10017,18 @@ async function commandResult(settled, format, spill) {
 		return errorResult(spillError, format);
 	}
 	const { error, delivered } = settled;
+	if (delivered === void 0) return errorResult(error, format);
+	let outcome;
+	try {
+		outcome = delivered();
+	} catch (rejected) {
+		return errorResult(new AggregateError([...errorsOf(error), rejected]), format);
+	}
 	const result = errorResult(error, format);
-	if (delivered === void 0) return result;
 	try {
 		return {
 			...result,
-			stdout: await stdoutOf(delivered, format, spill)
+			stdout: await stdoutOf(outcome, format, spill)
 		};
 	} catch (spillError) {
 		const both = new AggregateError([...errorsOf(error), spillError]);
@@ -9314,7 +10045,8 @@ function textHelp(node, root, cli, style) {
 function helpOf(node, root, cli, style, json) {
 	if (!json) return textHelp(node, root, cli, style);
 	if (node === root) return cliHelpJson(cli, node);
-	return node.kind === "command" ? commandHelpJson(node) : groupHelpJson(node);
+	const table = errorTableOf(cli);
+	return node.kind === "command" ? commandHelpJson(node, table) : groupHelpJson(node, table);
 }
 function helpResult(node, root, cli, { style, json }) {
 	return {
@@ -9325,7 +10057,7 @@ function helpResult(node, root, cli, { style, json }) {
 }
 function versionResult(cli, packageRoot) {
 	return {
-		stdout: `${(cli.build === void 0 ? [versionLine(cli)] : [versionLine(cli), `changelog ${join(packageRoot, "CHANGELOG.md")}`]).join("\n")}\n`,
+		stdout: `${(buildStamp() === void 0 ? [versionLine(cli)] : [versionLine(cli), `changelog ${join(packageRoot, "CHANGELOG.md")}`]).join("\n")}\n`,
 		stderr: "",
 		exitCode: SUCCESS_EXIT_CODE
 	};
@@ -9345,509 +10077,795 @@ function packageRootOf(bin, cwd) {
 	}
 }
 //#endregion
-//#region ../agent-cli/dist/suggest.js
-const MAX_DISTANCE = 3;
-const MIN_SIMILARITY = .4;
-function distance(a, b) {
-	const width = b.length + 1;
-	const d = Array.from({ length: (a.length + 1) * width }, (_, k) => {
-		const i = Math.floor(k / width);
-		const j = k % width;
-		return i === 0 || j === 0 ? i + j : 0;
-	});
-	const at = (i, j) => d[i * width + j] ?? 0;
-	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
-		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-		const edit = Math.min(at(i - 1, j) + 1, at(i, j - 1) + 1, at(i - 1, j - 1) + cost);
-		const transposed = i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1];
-		d[i * width + j] = transposed ? Math.min(edit, at(i - 2, j - 2) + 1) : edit;
-	}
-	return at(a.length, b.length);
-}
-function isClose(word, candidate) {
-	const length = Math.max(word.length, candidate.length);
-	const edits = distance(word, candidate);
-	return candidate.length > 1 && edits < MAX_DISTANCE && (length - edits) / length > MIN_SIMILARITY;
-}
-/** The names closest to `word`, sorted, several when they tie, or none when nothing is close. */
-function closestNames(word, names) {
-	const close = [...new Set(names)].filter((candidate) => isClose(word, candidate));
-	const best = Math.min(...close.map((candidate) => distance(word, candidate)));
-	return close.filter((candidate) => distance(word, candidate) === best).sort((a, b) => a.localeCompare(b));
-}
-/** The long flags closest to `flag`, sorted, or none for a short flag or when nothing is close. */
-function closestFlags(flag, flags) {
-	if (!flag.startsWith("--")) return [];
-	const names = flags.map((candidate) => candidate.slice(2));
-	return closestNames(flag.slice(2), names).map((name) => `--${name}`);
-}
-/** The one long flag closest to `flag`, or none when nothing is close or several tie. */
-function closestFlag(flag, flags) {
-	const closest = closestFlags(flag, flags);
-	return closest.length === 1 ? closest[0] : void 0;
-}
-//#endregion
-//#region ../agent-cli/dist/route.js
-const GROUP_FLAGS = [
-	HELP_FLAG,
-	VERSION_FLAG,
-	JSON_FLAG.flag
-];
-function beforeEnd(words) {
-	const end = words.indexOf("--");
-	return end === -1 ? words : words.slice(0, end);
-}
-function wantsHelp(words) {
-	return beforeEnd(words).some((word) => word === "--help" || word === "-h");
-}
-function childOf(group, name) {
-	return Object.hasOwn(group.commands, name) ? group.commands[name] : void 0;
-}
-function isFlagLike(word) {
-	return word.length > 1 && word[0] === "-";
-}
-function walk(node, words, json, invocation) {
-	const help = {
-		kind: "help",
-		node,
-		json
-	};
-	if (node.kind === "command") return wantsHelp(words) ? help : {
-		kind: "command",
-		spec: node,
-		words,
-		json
-	};
-	const [first, ...rest] = words;
-	if (first === void 0) return help;
-	const child = childOf(node, first);
-	if (child !== void 0) return walk(child, rest, json, invocation);
-	if (first === "--") {
-		const [name, ...after] = rest;
-		if (name === void 0) return help;
-		const named = childOf(node, name);
-		if (named !== void 0) return walk(named, ["--", ...after], json, invocation);
-		return unknownCommand(node, name, json);
-	}
-	if (wantsHelp(words)) return help;
-	if (isFlagLike(first)) {
-		const suggestions = closestFlags(first, GROUP_FLAGS);
-		return {
-			kind: "usage error",
-			error: unknownOptionError(node.commandLine, invocation, first, suggestions),
-			node,
-			json
-		};
-	}
-	return unknownCommand(node, first, json);
-}
-function unknownCommand(group, name, json) {
-	const suggestions = closestNames(name, Object.keys(visibleCommands(group)));
-	return {
-		kind: "usage error",
-		error: unknownCommandError(group.commandLine, name, suggestions),
-		node: group,
-		json
+//#region ../agent-cli/dist/root-spec.js
+/** The CLI's Commands as routing and help see them, the Built-in Commands included. */
+function rootSpec(cli, launch) {
+	const names = {
+		name: cli.name,
+		runAs: runAsOf(cli)
 	};
+	return cli.commands === void 0 ? {
+		...commandSpec(names.runAs, cli.command, {
+			path: [],
+			builtIn: false,
+			names
+		}),
+		description: cli.description
+	} : groupSpec(names, cli.commands, builtInCommands(cli, launch));
 }
-/** Walks the caller's command line through the Commands to the one it names, or to a stop. */
-function route(root, invocation) {
-	const { argv } = invocation;
-	const options = beforeEnd(argv);
-	const json = options.includes(JSON_FLAG.flag);
-	if (options.includes("--version")) return {
-		kind: "version",
-		json
-	};
-	return walk(root, argv.filter((word, index) => !(index < options.length && word === JSON_FLAG.flag)), json, invocation);
+//#endregion
+//#region ../agent-cli/dist/command-errors.js
+/**
+* `error`, or a bug naming each Error table code in it that the Command does not declare in its
+* `errors`. Runtime codes are never in the table, and a built-in's failures, `doctor` rows'
+* included, belong to no declaration, so both pass.
+*/
+function checkedCodes(error, { command, path, builtIn }, cli) {
+	if (builtIn) return error;
+	const table = errorTableOf(cli);
+	const declared = new Set(command.errors ?? []);
+	const undeclared = errorsOf(error).flatMap((leaf) => leaf instanceof CliError && Object.hasOwn(table, leaf.code) && !declared.has(leaf.code) ? [leaf.code] : []);
+	if (undeclared.length === 0) return error;
+	const label = commandLabel(path, cli.name).join(" ");
+	const codes = [...new Set(undeclared)].join(", ");
+	return new Error(`\`${label}\` threw ${codes}, which its errors do not declare`, { cause: error });
 }
 //#endregion
-//#region ../agent-cli/dist/execute.js
-function outcomeOf(value, render) {
-	return {
-		value,
-		render: (style) => render(value, style)
-	};
+//#region ../agent-cli/dist/context/operator.js
+const NEEDS_OPERATOR = "NEEDS_OPERATOR";
+/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
+function checkOperator({ operator, commandLine }, env, rerun) {
+	if (!operator || !isAgent(env)) return;
+	throw new CliError({
+		code: NEEDS_OPERATOR,
+		message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
+		hint: "ask the operator to type ! then the Next step",
+		next: [rerun]
+	});
 }
-/** Delivered data as the Command prints it, which is the data its `run` or `apply` returns. */
-function deliveredOutcome(command, data) {
-	return outcomeOf(data, command.render);
+//#endregion
+//#region ../agent-cli/dist/context/spill.js
+const STDOUT_BUDGET_CHARS = 3e4;
+const SPILL_RETENTION_MS = 6048e5;
+const PREVIEW_CHARS = 2e3;
+const SPILL_FILE = /^\d{4}-\d\d-\d\dT\d\d-\d\d-\d\d\.\d{3}Z-.+\.(json|txt)$/;
+function spillName(now, label, json) {
+	return `${new Date(now).toISOString().replaceAll(":", "-")}-${label.join("-")}.${json ? "json" : "txt"}`;
 }
-function dryRunOutcome(command, plan) {
-	const renderPlan = (style) => command.renderPlan(plan, style);
-	if (command.outputs === void 0 && command.cost === void 0) return {
-		value: plan,
-		render: renderPlan
-	};
-	const outputs = command.outputs?.(plan);
-	const cost = command.cost?.(plan);
-	return {
-		value: {
-			plan,
-			...outputs === void 0 ? {} : { outputs },
-			...command.cost === void 0 ? {} : { cost: cost ?? null }
-		},
-		render: (style) => [
-			renderPlan(style),
-			...outputs === void 0 || outputs.length === 0 ? [] : ["outputs:", ...outputs.map((path) => `  ${path}`)],
-			...cost === void 0 ? [] : [`cost: ${cost}`]
-		].join("\n")
-	};
+async function pruneOne(path, cutoff) {
+	try {
+		if ((await stat(path)).mtimeMs < cutoff) await rm(path, { force: true });
+	} catch (error) {
+		if (!isMissingFile(error)) throw error;
+	}
 }
-function serveContextOf(ctx, end) {
-	const serveCtx = Object.create(ctx);
-	return Object.assign(serveCtx, { end });
+async function pruneOld(folder, cutoff) {
+	const names = (await readdir(folder)).filter((name) => SPILL_FILE.test(name));
+	await Promise.all(names.map((name) => pruneOne(join(folder, name), cutoff)));
 }
-async function execute(command, input, ctx, { dryRun, confirm, yes, page, invocation, commandLine, started, files, guardOutputs }) {
-	await checkTools(command.tools ?? [], ctx.env, ctx.commandLine());
-	if (command.rows !== void 0) return outcomeOf(await command.run({
-		...input,
-		...page
-	}, ctx), (data, style) => command.render(data, style));
-	if (command.effect === "read") return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
-	if (command.effect === "serve") {
-		let end = () => {};
-		const ended = new Promise((resolve) => {
-			end = resolve;
+async function prepare(folder, cutoff, target) {
+	try {
+		await mkdir(folder, { recursive: true });
+		await pruneOld(folder, cutoff);
+	} catch (error) {
+		throw target.fileError(error, {
+			path: folder,
+			access: "write"
 		});
-		const outcome = outcomeOf(await command.start(input, serveContextOf(ctx, end)), (value, style) => command.render(value, style));
-		await started(outcome);
-		await Promise.race([ended, untilAborted(ctx.signal)]);
-		return outcome;
 	}
-	const plan = await command.plan(input, ctx);
-	if (dryRun) return dryRunOutcome(command, plan);
-	const outputs = command.outputs?.(plan);
-	await checkOutputs({
-		invocation,
-		commandLine,
-		force: ctx.force,
-		files: ctx.files
-	}, outputs);
-	checkCost({
-		invocation,
-		commandLine,
-		yes
-	}, command.cost?.(plan));
-	if (command.effect === "destructive") checkConfirmation({
-		invocation,
-		commandLine,
-		given: confirm
-	}, command.confirm(plan));
-	if (outputs !== void 0) {
-		await probeOutputs({
-			files,
-			cwd: ctx.cwd,
-			fileError: ctx.fileError
-		}, outputs);
-		if (!ctx.force) guardOutputs(outputs, ctx.commandLine({ add: [FORCE_FLAG.flag] }));
+}
+function tempRoot(env) {
+	const { TMPDIR } = env;
+	return TMPDIR === void 0 || TMPDIR === "" ? tmpdir() : TMPDIR;
+}
+function spillTo(target) {
+	return async (printed, json) => {
+		if (printed.length <= STDOUT_BUDGET_CHARS) return printed;
+		const now = target.clock.now();
+		const folder = join(tempRoot(target.env), target.cliName);
+		await prepare(folder, now - SPILL_RETENTION_MS, target);
+		const file = join(folder, spillName(now, target.label, json));
+		await target.files.write(file, printed);
+		const bytes = Buffer.byteLength(printed);
+		const preview = printed.slice(0, PREVIEW_CHARS);
+		return json ? `${JSON.stringify({
+			file,
+			bytes,
+			preview
+		})}\n` : `file: ${file}\nbytes: ${bytes}\npreview:\n${preview}\n`;
+	};
+}
+//#endregion
+//#region ../../node_modules/.pnpm/@toon-format+toon@4.4.0/node_modules/@toon-format/toon/dist/index.mjs
+const NULL_LITERAL = "null";
+const DELIMITERS = {
+	comma: ",",
+	tab: "	",
+	pipe: "|"
+};
+const DEFAULT_DELIMITER = DELIMITERS.comma;
+/**
+* Escapes special characters in a string for encoding.
+*
+* @remarks
+* Control characters outside `\n`, `\r`, `\t`, `\\`, and `"` are emitted as `\uXXXX`.
+*/
+function escapeString(value) {
+	return value.replace(/\\/g, `\\\\`).replace(/"/g, `\\"`).replace(/\n/g, `\\n`).replace(/\r/g, `\\r`).replace(/\t/g, `\\t`).replace(/[\u0000-\u001F]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function isBooleanOrNullLiteral(token) {
+	return token === "true" || token === "false" || token === "null";
+}
+/**
+* Assigns an own data property without invoking inherited accessors.
+*
+* @remarks
+* Plain assignment of `__proto__` would hit the `Object.prototype` setter and
+* corrupt the prototype chain; `defineProperty` avoids that but is markedly
+* slower, so every other key takes plain assignment.
+*/
+function setOwnProperty(target, key, value) {
+	if (key === "__proto__") {
+		Object.defineProperty(target, key, {
+			value,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+		return;
 	}
-	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
+	target[key] = value;
 }
-const manifestSchema = object({ bugs: union([string(), object({ url: string() })]).transform((value) => typeof value === "string" ? value : value.url).optional().catch(void 0) });
-const NO_MANIFEST = {};
-function manifestAt(packageRoot) {
-	let manifest;
-	try {
-		manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-	} catch {
-		return NO_MANIFEST;
+const COMMENT_LINE_PATTERN = new RegExp(`(?:^?|\\n) *#`);
+/**
+* Pre-formatted string that the encoder emits verbatim at a primitive value
+* position, bypassing quoting, escaping, and number/keyword detection.
+*
+* Returned from a replacer for an object or array value, it is ignored and
+* the container is encoded normally.
+*/
+var RawString = class {
+	constructor(value) {
+		if (COMMENT_LINE_PATTERN.test(value)) throw new TypeError(`Raw string must not contain a line starting with "#": ${JSON.stringify(value)}`);
+		this.value = value;
+	}
+};
+function isRawString(value) {
+	return value instanceof RawString;
+}
+const SURROGATE_PATTERN = /[\uD800-\uDFFF]/;
+function normalizeValue(value) {
+	if (value === null) return null;
+	if (isRawString(value)) return value;
+	if (typeof value === "object" && value !== null && "toJSON" in value && typeof value.toJSON === "function") {
+		const next = value.toJSON();
+		if (next !== value) return normalizeValue(next);
+	}
+	if (typeof value === "string") {
+		assertNoLoneSurrogate(value, "string value");
+		return value;
+	}
+	if (typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (Object.is(value, -0)) return 0;
+		if (!Number.isFinite(value)) return null;
+		return value;
+	}
+	if (typeof value === "bigint") {
+		if (value >= Number.MIN_SAFE_INTEGER && value <= Number.MAX_SAFE_INTEGER) return Number(value);
+		return value.toString();
+	}
+	if (value instanceof Date) return value.toISOString();
+	if (Array.isArray(value)) return Array.from(value, normalizeValue);
+	if (value instanceof Set) return Array.from(value).map(normalizeValue);
+	if (value instanceof Map) return Object.fromEntries(Array.from(value, ([k, v]) => [String(k), normalizeValue(v)]));
+	if (isPlainObject(value)) {
+		const encodedValues = {};
+		for (const key in value) if (Object.hasOwn(value, key)) {
+			assertNoLoneSurrogate(key, "object key");
+			setOwnProperty(encodedValues, key, normalizeValue(value[key]));
+		}
+		return encodedValues;
+	}
+	return null;
+}
+function assertNoLoneSurrogate(value, context) {
+	if (!SURROGATE_PATTERN.test(value)) return;
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code < 55296 || code > 57343) continue;
+		const isHighSurrogate = code <= 56319;
+		const next = value.charCodeAt(index + 1);
+		if (isHighSurrogate && next >= 56320 && next <= 57343) {
+			index++;
+			continue;
+		}
+		throw new TypeError(`Cannot encode ${context} containing an unpaired surrogate U+${code.toString(16).toUpperCase()} at index ${index}`);
 	}
-	const parsed = manifestSchema.safeParse(manifest);
-	return parsed.success ? parsed.data : NO_MANIFEST;
 }
-//#endregion
-//#region ../agent-cli/dist/parse-input.js
-const NO_INPUT = object({});
-const WHITESPACE = /\s/;
-function knownFlags(spec) {
-	return [...spec.options.map((field) => ({
-		flag: field.label,
-		takes: field.type === "boolean" ? "nothing" : "optional value"
-	})), ...spec.standardFlags.map(({ flag, takes }) => ({
-		flag,
-		takes
-	}))];
+function isJsonPrimitive(value) {
+	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
-function candidateFlags(known) {
-	return [
-		...known.map(({ flag }) => flag),
-		VERSION_FLAG,
-		HELP_FLAG
-	];
+function isEncodablePrimitive(value) {
+	return isJsonPrimitive(value) || isRawString(value);
 }
-function unknownOptionsOf(words, candidates) {
-	return words.map((word) => {
-		const flag = word.split("=")[0] ?? word;
-		return {
-			flag,
-			suggestion: closestFlag(flag, candidates)
-		};
-	});
+function isJsonArray(value) {
+	return Array.isArray(value);
 }
-function optionValue(field, all) {
-	if (field.variadic) return variadicValue(field, (all ?? []).filter((value) => value !== true));
-	const raw = all?.[all.length - 1];
-	return field.type === "boolean" && raw === true && field.label === `--no-${field.name}` ? false : raw;
+function isJsonObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && !isRawString(value);
 }
-function converted(field, raw) {
-	if (Array.isArray(raw)) return raw.map((element) => converted(field, element));
-	if (field.type !== "number" || typeof raw !== "string" || raw.trim() === "") return raw;
-	const number = Number(raw);
-	return Number.isNaN(number) ? raw : number;
+function isEmptyObject(value) {
+	return Object.keys(value).length === 0;
 }
-function variadicValue(field, values) {
-	return values.length === 0 && !field.required ? void 0 : values;
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || prototype === Object.prototype;
 }
-function parse(schema, values) {
-	const input = Object.fromEntries([...values].filter(([, raw]) => raw !== void 0).map(([field, raw]) => [field.key, converted(field, raw)]));
-	return schema.safeParse(input);
+function isArrayOfPrimitives(value) {
+	return value.length === 0 || value.every((item) => isEncodablePrimitive(item));
 }
-function issueLines(result, values, { howToPass, arrayIssueLine, reported = [], fromStdin }) {
-	if (result.success) return [];
-	return result.error.issues.flatMap((issue) => {
-		const field = [...values.keys()].find((candidate) => candidate.key === issue.path[0]);
-		if (field === void 0) return [`  ${issue.message}`];
-		if (reported.includes(field)) return [];
-		const raw = values.get(field);
-		if (raw === void 0) return [`  ${field.label}: required, ${howToPass(field)}`];
-		if (field === fromStdin) return [`  ${field.label} from stdin: ${issue.message}`];
-		return Array.isArray(raw) ? [arrayIssueLine(field, raw, issue)] : [`  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`];
-	});
+function isArrayOfArrays(value) {
+	return value.length === 0 || value.every((item) => isJsonArray(item));
 }
-function flagValuesIssueLine(field, raw, issue) {
-	const [, element] = issue.path;
-	if (typeof element === "number") return `  ${field.label} ${JSON.stringify(raw[element])}: ${issue.message}`;
-	return raw.length === 0 ? `  ${field.label}: ${issue.message}, pass ${field.usage}` : `  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`;
+function isArrayOfObjects(value) {
+	return value.length === 0 || value.every((item) => isJsonObject(item));
 }
-function operandsIssueLine(field, raw, issue, first) {
-	const [, element] = issue.path;
-	if (typeof element === "number") return `  ${field.label} ${JSON.stringify(raw[element])} (argument ${first + element}): ${issue.message}`;
-	return raw.length === 0 ? `  ${field.label}: ${issue.message}, pass them as arguments from ${first}` : `  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`;
+const NUMERIC_LIKE_PATTERN = /^[+-]?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i;
+/** Narrows an arbitrary delimiter option, shared by the library and the CLI so both report it alike. */
+function assertValidDelimiter(delimiter) {
+	if (!Object.values(DELIMITERS).includes(delimiter)) throw new TypeError(`Invalid delimiter ${JSON.stringify(delimiter)}. Valid delimiters are: comma (,), tab (\\t), pipe (|)`);
 }
-function unknownLine({ flag, suggestion }) {
-	return `  unknown option '${flag}'${suggestion === void 0 ? "" : ` (did you mean ${suggestion}?)`}`;
+/**
+* Checks if a key can be used without quotes.
+*
+* @remarks
+* Valid unquoted keys must start with a letter or underscore,
+* followed by letters, digits, underscores, or dots.
+*/
+function isValidUnquotedKey(key) {
+	return /^[A-Z_][\w.]*$/i.test(key);
+}
+/** Determines if a string value can be safely encoded without quotes. */
+function isSafeUnquoted(value, delimiter = DEFAULT_DELIMITER) {
+	if (!value) return false;
+	if (/^[ \t]|[ \t]$/.test(value)) return false;
+	if (isBooleanOrNullLiteral(value) || isNumericLike(value)) return false;
+	if (value.includes(":")) return false;
+	if (value.includes("\"") || value.includes("\\")) return false;
+	if (/[[\]{}]/.test(value)) return false;
+	if (/[\u0000-\u001F]/.test(value)) return false;
+	if (value.includes(delimiter)) return false;
+	if (value.startsWith("-")) return false;
+	if (value.startsWith("#")) return false;
+	return true;
 }
-function invalidInput(commandLine, invocation, unknown, otherLines) {
-	const renames = new Map(unknown.flatMap(({ flag, suggestion }) => suggestion === void 0 ? [] : [[flag, suggestion]]));
-	const correctable = otherLines.length === 0 && renames.size === unknown.length;
-	return new UsageError({
-		code: INVALID_INPUT,
-		message: [
-			`invalid input for \`${commandLine}\``,
-			...unknown.map(unknownLine),
-			...otherLines
-		].join("\n"),
-		hint: correctable ? `did you mean \`${commandLineRenaming(invocation, renames)}\`?` : `run \`${commandLine} --help\` to see the expected input`
-	});
+function isNumericLike(value) {
+	return NUMERIC_LIKE_PATTERN.test(value);
+}
+function encodePrimitive(value, delimiter) {
+	if (isRawString(value)) return value.value;
+	if (value === null) return NULL_LITERAL;
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "number") return String(value);
+	return encodeStringLiteral(value, delimiter);
+}
+function encodeStringLiteral(value, delimiter = DEFAULT_DELIMITER) {
+	if (isSafeUnquoted(value, delimiter)) return value;
+	return `"${escapeString(value)}"`;
+}
+function encodeKey(key) {
+	if (isValidUnquotedKey(key)) return key;
+	return `"${escapeString(key)}"`;
+}
+function encodeAndJoinPrimitives(values, delimiter = DEFAULT_DELIMITER) {
+	return values.map((v) => encodePrimitive(v, delimiter)).join(delimiter);
+}
+function formatHeader(length, options) {
+	const key = options?.key;
+	const fields = options?.fields;
+	const delimiter = options?.delimiter ?? ",";
+	let header = "";
+	if (key != null) header += encodeKey(key);
+	header += `[${length}${options?.keyed ? ":" : ""}${delimiter !== DEFAULT_DELIMITER ? delimiter : ""}]`;
+	if (fields) header += `{${formatFieldSegment(fields, delimiter)}}`;
+	header += ":";
+	return header;
+}
+function formatFieldSegment(fields, delimiter) {
+	return fields.map((field) => encodeKey(field.name) + (field.children ? `{${formatFieldSegment(field.children, delimiter)}}` : "")).join(delimiter);
+}
+/** Classifies rows into a tabular field list, or undefined when they are not uniformly tabular. */
+function extractTabularFields(rows) {
+	if (rows.length === 0) return;
+	const firstKeys = Object.keys(rows[0]);
+	if (firstKeys.length === 0) return;
+	for (const row of rows) {
+		if (Object.keys(row).length !== firstKeys.length) return;
+		for (const key of firstKeys) if (!Object.hasOwn(row, key)) return;
+	}
+	const fieldNodes = [];
+	for (const key of firstKeys) {
+		const fieldNode = classifyColumn(key, rows.map((row) => row[key]));
+		if (!fieldNode) return;
+		fieldNodes.push(fieldNode);
+	}
+	return fieldNodes;
+}
+/** Classifies an object's values as a keyed tabular field list (>=2 uniform non-empty object entries), or undefined. */
+function extractKeyedTabularFields(value) {
+	const entryValues = Object.values(value);
+	if (entryValues.length < 2) return;
+	if (!entryValues.every((entryValue) => isJsonObject(entryValue) && !isEmptyObject(entryValue))) return;
+	return extractTabularFields(entryValues);
+}
+/** Reads one row's leaf cells in the field order `extractTabularFields` produced. */
+function collectRowLeaves(row, fields) {
+	const leaves = [];
+	collectLeafValues(row, fields, leaves);
+	return leaves;
+}
+function classifyColumn(name, values) {
+	if (values.every((value) => isEncodablePrimitive(value))) return { name };
+	if (!values.every((value) => isJsonObject(value) && !isEmptyObject(value))) return;
+	const children = extractTabularFields(values);
+	if (!children) return;
+	return {
+		name,
+		children
+	};
 }
-function stdinFieldOf(spec, operands) {
-	const index = spec.args.findIndex((field) => field.stdin);
-	return operands[index]?.value === "-" ? spec.args[index] : void 0;
+function collectLeafValues(row, fields, leaves) {
+	for (const field of fields) {
+		const value = row[field.name];
+		if (field.children) collectLeafValues(value, field.children, leaves);
+		else leaves.push(value);
+	}
 }
-/** The name of the routed Command's arg given `-`, which takes its text from stdin. */
-function stdinArgOf({ spec, words }) {
-	return stdinFieldOf(spec, tokenize(words, knownFlags(spec)).operands)?.name;
+function* encodeJsonValue(value, options, depth) {
+	if (isEncodablePrimitive(value)) {
+		const encodedPrimitive = typeof value === "string" && value.startsWith("") ? `"${escapeString(value)}"` : encodePrimitive(value, options.delimiter);
+		if (encodedPrimitive !== "") yield encodedPrimitive;
+		return;
+	}
+	if (isJsonArray(value)) yield* encodeArrayLines(void 0, value, depth, options);
+	else if (isJsonObject(value)) {
+		const keyedFields = extractKeyedTabularFields(value);
+		if (keyedFields) {
+			yield* encodeKeyedObjectLines(void 0, value, keyedFields, depth, options);
+			return;
+		}
+		yield* encodeObjectLines(value, depth, options);
+	}
 }
-async function stdinTextOf(spec, operands, read) {
-	const field = stdinFieldOf(spec, operands);
-	return field === void 0 ? void 0 : {
-		field,
-		text: await read(field)
-	};
+function* encodeObjectLines(value, depth, options) {
+	for (const [key, val] of Object.entries(value)) yield* encodeKeyValuePairLines(key, val, depth, options);
 }
-async function parseInput(spec, words, invocation, readStdin) {
-	const { command, args: argFields, options: optionFields } = spec;
-	const pageFields = spec.list?.pageFields ?? [];
-	const known = knownFlags(spec);
-	const { operands, unknownOptions, values, occurrences } = tokenize(words, known);
-	const stdin = await stdinTextOf(spec, operands, readStdin);
-	if (values.get(CONFIRM_FLAG.flag) === true) throw invalidInputError(spec.commandLine, `option '${CONFIRM_FLAG.usage}' argument missing`);
-	const missing = [...optionFields, ...pageFields].filter((field) => field.type !== "boolean" && (field.variadic ? occurrences.get(field.label)?.includes(true) : values.get(field.label) === true));
-	const argValue = (field, index) => {
-		if (field === stdin?.field) return stdin.text;
-		if (!field.variadic) return operands[index]?.value;
-		return variadicValue(field, operands.slice(index).filter((operand) => !operand.afterUnknownOption).map((operand) => operand.value));
-	};
-	const argValues = new Map(argFields.map((field, index) => [field, argValue(field, index)]));
-	const extraOperands = argFields.some((field) => field.variadic) ? [] : operands.slice(argFields.length);
-	const valuesOf = (fields) => new Map(fields.map((field) => [field, missing.includes(field) ? void 0 : optionValue(field, occurrences.get(field.label))]));
-	const flagWording = {
-		howToPass: (field) => `pass ${field.usage}`,
-		arrayIssueLine: flagValuesIssueLine,
-		reported: missing
-	};
-	const optionValues = valuesOf(optionFields);
-	const pageValues = valuesOf(pageFields);
-	const args = parse(command.args ?? NO_INPUT, argValues);
-	const options = parse(command.options ?? NO_INPUT, optionValues);
-	const page = parse(PAGE_INPUT, pageValues);
-	const unknown = unknownOptionsOf(unknownOptions, candidateFlags(known));
-	const otherLines = [
-		...missing.map((field) => `  ${field.label}: missing value, pass ${field.usage}`),
-		...extraOperands.filter((operand) => !operand.afterUnknownOption).map((operand) => `  unexpected argument ${JSON.stringify(operand.value)}`),
-		...issueLines(args, argValues, {
-			howToPass: (field) => `pass it as argument ${argFields.indexOf(field) + 1}`,
-			arrayIssueLine: (field, raw, issue) => operandsIssueLine(field, raw, issue, argFields.indexOf(field) + 1),
-			fromStdin: stdin?.field
-		}),
-		...issueLines(options, optionValues, flagWording),
-		...issueLines(page, pageValues, flagWording)
-	];
-	if (unknown.length === 0 && otherLines.length === 0 && args.success && options.success && page.success) return {
-		input: {
-			...args.data,
-			...options.data
-		},
-		page: page.data,
-		values
-	};
-	const [onlyWord] = unknownOptions;
-	if (onlyWord !== void 0 && unknownOptions.length === 1 && WHITESPACE.test(onlyWord) && argFields.some((field) => field.stdin && argValues.get(field) === void 0)) throw stdinTextError(spec.commandLine, invocation, onlyWord);
-	const [only] = unknown;
-	if (only !== void 0 && unknown.length === 1 && otherLines.length === 0) throw unknownOptionError(spec.commandLine, invocation, only.flag, only.suggestion === void 0 ? [] : [only.suggestion]);
-	throw invalidInput(spec.commandLine, invocation, unknown, otherLines);
+function* encodeKeyValuePairLines(key, value, depth, options) {
+	const encodedKey = encodeKey(key);
+	if (isEncodablePrimitive(value)) yield indentedLine(depth, `${encodedKey}: ${encodePrimitive(value, options.delimiter)}`, options.indentSize);
+	else if (isJsonArray(value)) yield* encodeArrayLines(key, value, depth, options);
+	else if (isJsonObject(value)) {
+		const keyedFields = extractKeyedTabularFields(value);
+		if (keyedFields) {
+			yield* encodeKeyedObjectLines(key, value, keyedFields, depth, options);
+			return;
+		}
+		yield indentedLine(depth, `${encodedKey}:`, options.indentSize);
+		if (!isEmptyObject(value)) yield* encodeObjectLines(value, depth + 1, options);
+	}
+}
+function* encodeKeyedObjectLines(key, value, fields, depth, options) {
+	const entries = Object.entries(value);
+	yield indentedLine(depth, formatHeader(entries.length, {
+		key,
+		fields,
+		delimiter: options.delimiter,
+		keyed: true
+	}), options.indentSize);
+	yield* encodeKeyedEntryRowsLines(entries, fields, depth + 1, options);
+}
+function* encodeKeyedEntryRowsLines(entries, fields, depth, options) {
+	for (const [entryKey, entryValue] of entries) {
+		const leaves = collectRowLeaves(entryValue, fields);
+		yield indentedLine(depth, `${encodeKey(entryKey)}: ${encodeAndJoinPrimitives(leaves, options.delimiter)}`, options.indentSize);
+	}
+}
+function* encodeArrayLines(key, value, depth, options) {
+	if (value.length === 0) {
+		yield indentedLine(depth, key != null ? `${encodeKey(key)}: []` : "[]", options.indentSize);
+		return;
+	}
+	if (isArrayOfPrimitives(value)) {
+		yield indentedLine(depth, encodeInlineArrayLine(value, options.delimiter, key), options.indentSize);
+		return;
+	}
+	if (isArrayOfArrays(value)) {
+		if (value.every((arr) => isArrayOfPrimitives(arr))) {
+			yield* encodeArrayOfArraysAsListItemsLines(key, value, depth, options);
+			return;
+		}
+	}
+	if (isArrayOfObjects(value)) {
+		const fields = extractTabularFields(value);
+		if (fields) yield* encodeArrayOfObjectsAsTabularLines(key, value, fields, depth, options);
+		else yield* encodeMixedArrayAsListItemsLines(key, value, depth, options);
+		return;
+	}
+	yield* encodeMixedArrayAsListItemsLines(key, value, depth, options);
+}
+function* encodeArrayOfArraysAsListItemsLines(prefix, values, depth, options) {
+	yield indentedLine(depth, formatHeader(values.length, {
+		key: prefix,
+		delimiter: options.delimiter
+	}), options.indentSize);
+	for (const arr of values) if (isArrayOfPrimitives(arr)) {
+		const arrayLine = encodeInlineArrayLine(arr, options.delimiter);
+		yield indentedListItem(depth + 1, arrayLine, options.indentSize);
+	}
+}
+function encodeInlineArrayLine(values, delimiter, prefix) {
+	const header = formatHeader(values.length, {
+		key: prefix,
+		delimiter
+	});
+	const joinedValue = encodeAndJoinPrimitives(values, delimiter);
+	if (values.length === 0) return header;
+	return `${header} ${joinedValue}`;
+}
+function* encodeArrayOfObjectsAsTabularLines(prefix, rows, fields, depth, options) {
+	yield indentedLine(depth, formatHeader(rows.length, {
+		key: prefix,
+		fields,
+		delimiter: options.delimiter
+	}), options.indentSize);
+	yield* writeTabularRowsLines(rows, fields, depth + 1, options);
+}
+function* writeTabularRowsLines(rows, fields, depth, options) {
+	for (const row of rows) yield indentedLine(depth, encodeAndJoinPrimitives(collectRowLeaves(row, fields), options.delimiter), options.indentSize);
+}
+function* encodeMixedArrayAsListItemsLines(prefix, items, depth, options) {
+	yield indentedLine(depth, formatHeader(items.length, {
+		key: prefix,
+		delimiter: options.delimiter
+	}), options.indentSize);
+	for (const item of items) yield* encodeListItemValueLines(item, depth + 1, options);
+}
+function* encodeObjectAsListItemLines(obj, depth, options) {
+	if (isEmptyObject(obj)) {
+		yield indentedLine(depth, "-", options.indentSize);
+		return;
+	}
+	const entries = Object.entries(obj);
+	const [firstKey, firstValue] = entries[0];
+	const restEntries = entries.slice(1);
+	if (isJsonArray(firstValue) && isArrayOfObjects(firstValue)) {
+		const fields = extractTabularFields(firstValue);
+		if (fields) {
+			yield indentedListItem(depth, formatHeader(firstValue.length, {
+				key: firstKey,
+				fields,
+				delimiter: options.delimiter
+			}), options.indentSize);
+			yield* writeTabularRowsLines(firstValue, fields, depth + 2, options);
+			if (restEntries.length > 0) yield* encodeObjectLines(Object.fromEntries(restEntries), depth + 1, options);
+			return;
+		}
+	}
+	if (isJsonObject(firstValue)) {
+		const keyedFields = extractKeyedTabularFields(firstValue);
+		if (keyedFields) {
+			const keyedEntries = Object.entries(firstValue);
+			yield indentedListItem(depth, formatHeader(keyedEntries.length, {
+				key: firstKey,
+				fields: keyedFields,
+				delimiter: options.delimiter,
+				keyed: true
+			}), options.indentSize);
+			yield* encodeKeyedEntryRowsLines(keyedEntries, keyedFields, depth + 2, options);
+			if (restEntries.length > 0) yield* encodeObjectLines(Object.fromEntries(restEntries), depth + 1, options);
+			return;
+		}
+	}
+	const encodedKey = encodeKey(firstKey);
+	if (isEncodablePrimitive(firstValue)) yield indentedListItem(depth, `${encodedKey}: ${encodePrimitive(firstValue, options.delimiter)}`, options.indentSize);
+	else if (isJsonArray(firstValue)) {
+		if (firstValue.length === 0) yield indentedListItem(depth, `${encodedKey}: []`, options.indentSize);
+		else if (isArrayOfPrimitives(firstValue)) yield indentedListItem(depth, `${encodedKey}${encodeInlineArrayLine(firstValue, options.delimiter)}`, options.indentSize);
+		else {
+			yield indentedListItem(depth, `${encodedKey}${formatHeader(firstValue.length, { delimiter: options.delimiter })}`, options.indentSize);
+			for (const item of firstValue) yield* encodeListItemValueLines(item, depth + 2, options);
+		}
+	} else if (isJsonObject(firstValue)) {
+		yield indentedListItem(depth, `${encodedKey}:`, options.indentSize);
+		if (!isEmptyObject(firstValue)) yield* encodeObjectLines(firstValue, depth + 2, options);
+	}
+	if (restEntries.length > 0) yield* encodeObjectLines(Object.fromEntries(restEntries), depth + 1, options);
+}
+function* encodeListItemValueLines(value, depth, options) {
+	if (isEncodablePrimitive(value)) yield indentedListItem(depth, encodePrimitive(value, options.delimiter), options.indentSize);
+	else if (isJsonArray(value)) {
+		if (isArrayOfPrimitives(value)) yield indentedListItem(depth, encodeInlineArrayLine(value, options.delimiter), options.indentSize);
+		else {
+			yield indentedListItem(depth, formatHeader(value.length, { delimiter: options.delimiter }), options.indentSize);
+			for (const item of value) yield* encodeListItemValueLines(item, depth + 1, options);
+		}
+	} else if (isJsonObject(value)) yield* encodeObjectAsListItemLines(value, depth, options);
+}
+function indentedLine(depth, content, indentSize) {
+	return " ".repeat(indentSize * depth) + content;
+}
+function indentedListItem(depth, content, indentSize) {
+	return indentedLine(depth, "- " + content, indentSize);
 }
 /**
-* The validated input and Standard flag values of the routed Command, or one usage error; the arg
-* given `-` takes its text from `readStdin`.
+* Applies a replacer function to a `JsonValue` and all its descendants.
+*
+* The replacer is called for the root (key='', path=[]), every object property
+* (key = property name), and every array element (key = string index).
 */
-async function parseCommand({ spec, words, json }, invocation, readStdin) {
-	const { input, page, values } = await parseInput(spec, words, invocation, readStdin);
-	const confirm = values.get(CONFIRM_FLAG.flag);
-	return {
-		input,
-		flags: {
-			json,
-			dryRun: values.get(DRY_RUN_FLAG.flag) === true,
-			confirm: typeof confirm === "string" ? confirm : void 0,
-			yes: values.get(YES_FLAG.flag) === true,
-			force: values.get(FORCE_FLAG.flag) === true,
-			page,
-			fields: spec.list === void 0 ? void 0 : selectedFields(values, spec.list.rowFields, spec.commandLine)
-		}
-	};
+function applyReplacer(root, replacer) {
+	const replacedRoot = replacer("", root, []);
+	if (replacedRoot === void 0) return transformChildren(root, replacer, []);
+	return transformReplaced(root, replacedRoot, replacer, []);
 }
-//#endregion
-//#region ../agent-cli/dist/secrets.js
-/** `$XDG_CONFIG_HOME/<cli>/.env`, with `~/.config` when the variable is unset or empty. */
-function envFileOf(cliName, env) {
-	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
-	return join(config, cliName, ".env");
+/**
+* Resolves a replacer's (non-`undefined`) return value at a single position.
+*
+* A `RawString` only stands in for a primitive: returned for an object or
+* array value, it is ignored and the original container is traversed normally.
+*/
+function transformReplaced(original, replaced, replacer, path) {
+	if (isRawString(replaced) && !isEncodablePrimitive(original)) return transformChildren(original, replacer, path);
+	return transformChildren(normalizeValue(replaced), replacer, path);
 }
-function readDotenv(path, fileError) {
-	let text;
-	try {
-		text = readFileSync(path, "utf8");
-	} catch (error) {
-		if (isMissingFile(error)) return {};
-		throw fileError(error, {
-			path,
-			access: "read"
-		});
+function transformChildren(value, replacer, path) {
+	if (isJsonObject(value)) return transformObject(value, replacer, path);
+	if (isJsonArray(value)) return transformArray(value, replacer, path);
+	return value;
+}
+function transformObject(obj, replacer, path) {
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) {
+		const childPath = [...path, key];
+		const replacedValue = replacer(key, value, childPath);
+		if (replacedValue === void 0) continue;
+		setOwnProperty(result, key, transformReplaced(value, replacedValue, replacer, childPath));
 	}
-	return parseEnv(text);
+	return result;
 }
-/** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
-function secretOf({ envFile, env, fileError }, name) {
-	const fromEnv = env[name];
-	if (fromEnv) return {
-		value: fromEnv,
-		origin: { kind: "env" }
+function transformArray(arr, replacer, path) {
+	const result = [];
+	for (let i = 0; i < arr.length; i++) {
+		const value = arr[i];
+		const childPath = [...path, i];
+		const replacedValue = replacer(String(i), value, childPath);
+		if (replacedValue === void 0) continue;
+		result.push(transformReplaced(value, replacedValue, replacer, childPath));
+	}
+	return result;
+}
+/**
+* Encodes a JavaScript value into TOON format string.
+*
+* @example
+* ```ts
+* encode({ name: 'Ada', age: 30 })
+* // name: Ada
+* // age: 30
+*
+* encode({ users: [{ id: 1 }, { id: 2 }] })
+* // users[2]{id}:
+* //   1
+* //   2
+*
+* encode({ tags: [] })
+* // tags: []
+*
+* encode(data, { indentSize: 4 })
+* ```
+*/
+function encode(input, options) {
+	return Array.from(encodeLines(input, options)).join("\n");
+}
+/**
+* Encodes a JavaScript value into TOON format as a sequence of lines.
+*
+* This function yields TOON lines one at a time without building the full string,
+* making it suitable for streaming large outputs to files, HTTP responses, or process stdout.
+*
+* @example
+* ```ts
+* // Stream to stdout
+* for (const line of encodeLines({ name: 'Ada', age: 30 })) {
+*   console.log(line)
+* }
+*
+* // Collect to array
+* const lines = Array.from(encodeLines(data))
+*
+* // Equivalent to encode()
+* const toonString = Array.from(encodeLines(data, options)).join('\n')
+* ```
+*/
+function encodeLines(input, options) {
+	const normalizedValue = normalizeValue(input);
+	const resolvedOptions = resolveOptions(options);
+	return encodeJsonValue(resolvedOptions.replacer ? applyReplacer(normalizedValue, resolvedOptions.replacer) : normalizedValue, resolvedOptions, 0);
+}
+function resolveOptions(options) {
+	const delimiter = options?.delimiter ?? DEFAULT_DELIMITER;
+	assertValidDelimiter(delimiter);
+	return {
+		indentSize: options?.indentSize ?? options?.indent ?? 2,
+		delimiter,
+		replacer: options?.replacer
 	};
-	const fromFile = readDotenv(envFile, fileError)[name];
-	return fromFile ? {
-		value: fromFile,
-		origin: {
-			kind: "file",
-			path: envFile
-		}
-	} : void 0;
 }
 //#endregion
-//#region ../agent-cli/dist/side-task.js
-/** How long a run waits for its Side task once its output is written. */
-const SIDE_TASK_WAIT_MS = 1e3;
-const noSideTask = async () => {};
-function waitOver() {
-	return new DOMException(`the side task ran past its ${SIDE_TASK_WAIT_MS} ms wait`, "TimeoutError");
+//#region ../agent-cli/dist/context/confirm.js
+const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
+const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
+function checkConfirmation({ rerun, commandLine, given }, expected) {
+	if (given === expected) return;
+	const advice = {
+		hint: "to confirm, run the Next step",
+		next: [rerun({
+			remove: [CONFIRM_FLAG.flag],
+			add: [CONFIRM_FLAG.flag, expected]
+		})]
+	};
+	if (given === void 0) throw new UsageError({
+		code: CONFIRMATION_REQUIRED,
+		message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
+		...advice
+	});
+	throw new UsageError({
+		code: CONFIRMATION_MISMATCH,
+		message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
+		...advice
+	});
 }
-function startSideTask(sideTask, runWith, { clock, failed }) {
-	if (sideTask === void 0) return noSideTask;
-	const controller = new AbortController();
-	const { signal } = controller;
-	const running = (async () => sideTask(runWith(signal)))().catch((error) => {
-		if (!(signal.aborted && error === signal.reason)) failed(error);
+//#endregion
+//#region ../agent-cli/dist/context/cost.js
+const NOT_CONFIRMED = "NOT_CONFIRMED";
+/** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
+function checkCost({ rerun, commandLine, yes }, cost) {
+	if (cost === void 0 || yes) return;
+	throw new CliError({
+		code: NOT_CONFIRMED,
+		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
+		hint: "to approve the cost, run the Next step",
+		next: [rerun({ add: [YES_FLAG.flag] })]
 	});
-	return async () => {
-		const waited = new AbortController();
-		const capped = new Promise((resolve) => after(clock, SIDE_TASK_WAIT_MS, waited.signal, () => {
-			const over = waitOver();
-			failed(over);
-			controller.abort(over);
-			resolve();
-		}));
-		await Promise.race([running, capped]);
-		waited.abort();
-	};
 }
 //#endregion
-//#region ../agent-cli/dist/spill.js
-const STDOUT_BUDGET_CHARS = 3e4;
-const SPILL_RETENTION_MS = 6048e5;
-const PREVIEW_CHARS = 2e3;
-const SPILL_FILE = /^\d{4}-\d\d-\d\dT\d\d-\d\d-\d\d\.\d{3}Z-.+\.(json|txt)$/;
-function spillName(now, commandName, json) {
-	return `${new Date(now).toISOString().replaceAll(":", "-")}-${commandName}.${json ? "json" : "txt"}`;
+//#region ../agent-cli/dist/execute.js
+const PLAN_INDENT = "  ";
+function outcomeOf(value, render) {
+	return {
+		value,
+		render: (style) => render(value, style)
+	};
 }
-async function pruneOne(path, cutoff) {
-	try {
-		if ((await stat(path)).mtimeMs < cutoff) await rm(path, { force: true });
-	} catch (error) {
-		if (!isMissingFile(error)) throw error;
-	}
+/**
+* The data a Command returned or delivered as it prints it: parsed by its `output` schema when it
+* declares one, so data the schema rejects fails the run as a bug.
+*/
+function dataOutcome(command, data, commandLine) {
+	const render = command.render ?? ((value) => value === void 0 ? "" : encode(value));
+	if (command.rows !== void 0 || command.output === void 0) return outcomeOf(data, render);
+	const parsed = command.output.safeParse(data);
+	if (!parsed.success) throw new Error(`\`${commandLine}\` produced data its output schema rejects:\n${prettifyError(parsed.error)}`);
+	return outcomeOf(parsed.data, render);
+}
+function indented(text) {
+	return text.split("\n").map((line) => `${PLAN_INDENT}${line}`).join("\n");
+}
+function dryRunOutcome(command, plan, commandLine) {
+	const renderPlan = (style) => command.renderPlan === void 0 ? `Would run ${commandLine}:\n${indented(encode(plan))}` : command.renderPlan(plan, style);
+	if (command.outputs === void 0 && command.cost === void 0) return {
+		value: plan,
+		render: renderPlan
+	};
+	const outputs = command.outputs?.(plan);
+	const cost = command.cost?.(plan);
+	return {
+		value: {
+			plan,
+			...outputs === void 0 ? {} : { outputs },
+			...command.cost === void 0 ? {} : { cost: cost ?? null }
+		},
+		render: (style) => [
+			renderPlan(style),
+			...outputs === void 0 || outputs.length === 0 ? [] : ["outputs:", ...outputs.map((path) => `  ${path}`)],
+			...cost === void 0 ? [] : [`cost: ${cost}`]
+		].join("\n")
+	};
 }
-async function pruneOld(folder, cutoff) {
-	const names = (await readdir(folder)).filter((name) => SPILL_FILE.test(name));
-	await Promise.all(names.map((name) => pruneOne(join(folder, name), cutoff)));
+function serveContextOf(ctx, end) {
+	const serveCtx = Object.create(ctx);
+	return Object.assign(serveCtx, { end });
 }
-async function prepare(folder, cutoff, target) {
-	try {
-		await mkdir(folder, { recursive: true });
-		await pruneOld(folder, cutoff);
-	} catch (error) {
-		throw target.fileError(error, {
-			path: folder,
-			access: "write"
+async function execute(command, input, ctx, { dryRun, confirm, yes, page, commandLine, started, files, guardOutputs }) {
+	await checkTools(command.tools ?? [], ctx.env, ctx.rerun());
+	const { env, envFile, fileError } = ctx;
+	checkSecrets(command.secrets ?? [], {
+		env,
+		envFile,
+		fileError
+	}, ctx.rerun());
+	if (command.rows !== void 0) {
+		const { render } = command;
+		return outcomeOf(await command.run({
+			...input,
+			...page
+		}, ctx), (data, style) => render === void 0 ? encode(data.items) : render(data, style));
+	}
+	if (command.effect === "read" || command.effect === "act") return dataOutcome(command, await command.run(input, ctx), commandLine);
+	if (command.effect === "serve") {
+		let end = () => {};
+		const ended = new Promise((resolve) => {
+			end = resolve;
 		});
+		const outcome = dataOutcome(command, await command.start(input, serveContextOf(ctx, end)), commandLine);
+		await started(outcome);
+		await Promise.race([ended, untilAborted(ctx.signal)]);
+		return outcome;
 	}
+	const plan = await command.plan(input, ctx);
+	if (dryRun) return dryRunOutcome(command, plan, commandLine);
+	const outputs = command.outputs?.(plan);
+	await checkOutputs({
+		rerun: ctx.rerun,
+		commandLine,
+		force: ctx.force,
+		files: ctx.files
+	}, outputs);
+	checkCost({
+		rerun: ctx.rerun,
+		commandLine,
+		yes
+	}, command.cost?.(plan));
+	if (command.effect === "destructive") checkConfirmation({
+		rerun: ctx.rerun,
+		commandLine,
+		given: confirm
+	}, command.confirm(plan));
+	if (outputs !== void 0) {
+		await probeOutputs({
+			files,
+			cwd: ctx.cwd,
+			fileError: ctx.fileError
+		}, outputs);
+		if (!ctx.force) guardOutputs(outputs, ctx.rerun({ add: [FORCE_FLAG.flag] }));
+	}
+	return dataOutcome(command, await command.apply(plan, ctx), commandLine);
 }
-function tempRoot(env) {
-	const { TMPDIR } = env;
-	return TMPDIR === void 0 || TMPDIR === "" ? tmpdir() : TMPDIR;
-}
-function spillTo(target) {
-	return async (printed, json) => {
-		if (printed.length <= STDOUT_BUDGET_CHARS) return printed;
-		const now = target.clock.now();
-		const folder = join(tempRoot(target.env), target.cliName);
-		await prepare(folder, now - SPILL_RETENTION_MS, target);
-		const file = join(folder, spillName(now, target.commandName, json));
-		await target.files.write(file, printed);
-		const bytes = Buffer.byteLength(printed);
-		const preview = printed.slice(0, PREVIEW_CHARS);
-		return json ? `${JSON.stringify({
-			file,
-			bytes,
-			preview
-		})}\n` : `file: ${file}\nbytes: ${bytes}\npreview:\n${preview}\n`;
-	};
+const manifestSchema = object({ bugs: union([string(), object({ url: string() })]).transform((value) => typeof value === "string" ? value : value.url).optional().catch(void 0) });
+const NO_MANIFEST = {};
+function manifestAt(packageRoot) {
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	} catch {
+		return NO_MANIFEST;
+	}
+	const parsed = manifestSchema.safeParse(manifest);
+	return parsed.success ? parsed.data : NO_MANIFEST;
 }
 //#endregion
 //#region ../agent-cli/dist/run-command.js
 function stdinNeverEndedHint(callerLine) {
 	return `stdin never ended: pipe the text into \`${callerLine}\`, or redirect a file into it`;
 }
+function runDeadlineAdvice(resumed, pipedLine) {
+	return resumed === void 0 ? { hint: stdinNeverEndedHint(pipedLine) } : {
+		hint: "run the Next step to continue the work",
+		next: [resumed]
+	};
+}
 function selfOf(name, bin) {
 	return bin === void 0 ? [name] : [
 		process.execPath,
@@ -9867,7 +10885,7 @@ function portsOf(cli, replacement) {
 	return cli.ports ?? (() => ({}));
 }
 function portsBaseOf(scope, signal) {
-	const { cli, options, packageRoot, progress, fileError, callerLine, clock, files } = scope;
+	const { cli, options, packageRoot, progress, fileError, rerun, clock, files } = scope;
 	const { cwd, env } = options;
 	const envFile = envFileOf(cli.name, env);
 	return {
@@ -9883,7 +10901,7 @@ function portsBaseOf(scope, signal) {
 		envFile,
 		fileError,
 		version: cli.version,
-		build: cli.build,
+		build: buildStamp(),
 		self: selfOf(cli.name, options.bin),
 		signal,
 		clock,
@@ -9894,7 +10912,7 @@ function portsBaseOf(scope, signal) {
 			signal
 		}, {
 			fileError,
-			callerLine
+			rerun
 		}),
 		spawnDetached: contextSpawnDetached(spawnDetachedOf(options), {
 			cwd,
@@ -9902,23 +10920,30 @@ function portsBaseOf(scope, signal) {
 			signal
 		}, {
 			fileError,
-			callerLine
+			rerun
 		})
 	};
 }
 function contextOf(portsBase, control, parts) {
-	const { ports, project, force, commandLine, deliver, notice } = parts;
+	const { ports, project, force, secrets = [], rerun, deliver, notice } = parts;
+	const declared = new Set(secrets.map(({ name }) => name));
 	return {
 		...portsBase,
-		deadline: (ms) => control.deadline(ms),
-		timeout: (ms) => control.timeout(ms),
+		secret: (name) => {
+			if (!declared.has(name)) throw new Error(`ctx.secret("${name}") names a Secret the Command does not declare`);
+			const secret = portsBase.secret(name);
+			if (secret === void 0) throw new Error(`ctx.secret("${name}") found no value`);
+			return secret;
+		},
+		fail: cliErrorOf,
+		deadline: (ms, options) => control.deadline(ms, options),
 		runToEnd: (name, work) => control.runToEnd(name, work),
 		get ports() {
 			return ports();
 		},
 		project,
 		force,
-		commandLine,
+		rerun,
 		poll: (check, { intervalMs, signal: stop }) => poll(portsBase.clock, check, intervalMs, stop === void 0 ? control.signal : AbortSignal.any([control.signal, stop])),
 		deliver,
 		notice
@@ -9940,10 +10965,14 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		flags: knownFlags(routed.spec),
 		stdinArg: stdinArgOf(routed)
 	};
-	const typedLine = (change) => commandLineOf(invocation, change);
-	const rerunLine = typedLine();
+	const rerunOf = (change) => ({
+		kind: "rerun",
+		words: changedArgv(invocation, change),
+		stdinArg: invocation.stdinArg
+	});
+	const rerun = rerunOf();
 	const fileError = fileErrorOf({
-		callerLine: rerunLine,
+		rerun,
 		env,
 		platform
 	});
@@ -9957,16 +10986,16 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		...invocation,
 		stdinArg: void 0
 	});
-	let resumeHint;
+	let resumed;
 	const control = new RunControl({
 		commandLine,
-		callerLine: rerunLine,
+		rerun,
 		outer: options.signal,
 		clock,
 		progress,
 		runDeadline: command.deadline === void 0 ? void 0 : {
 			ms: command.deadline.ms,
-			hint: () => resumeHint ?? stdinNeverEndedHint(pipedLine)
+			advice: () => runDeadlineAdvice(resumed, pipedLine)
 		}
 	});
 	const failed = (error, finishSideTask) => {
@@ -9978,7 +11007,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	};
 	let parsed;
 	try {
-		checkOperator(routed.spec, env, typedLine());
+		checkOperator(routed.spec, env, rerun);
 		parsed = await parseCommand(routed, invocation, (field) => {
 			if (isTerminal(stdin)) progress(readingLine(field.name, platform));
 			return readStdin(stdin, control.signal, {
@@ -9990,7 +11019,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		return failed(error, noSideTask);
 	}
 	const { input, flags } = parsed;
-	resumeHint = command.deadline?.resume(input, typedLine);
+	resumed = command.deadline?.resume(input, rerunOf);
 	const outputs = outputsGuard(classifiedFiles(files, {
 		cwd,
 		fileError
@@ -10001,7 +11030,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		packageRoot,
 		progress,
 		fileError,
-		callerLine: rerunLine,
+		rerun,
 		clock,
 		files: outputs.files
 	};
@@ -10027,7 +11056,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	try {
 		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, {
 			fileError,
-			callerLine: rerunLine
+			rerun
 		});
 	} catch (error) {
 		return failed(error, finishSideTask);
@@ -10037,15 +11066,16 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		ports: once(() => ports(portsBase)),
 		project,
 		force: flags.force,
-		commandLine: typedLine,
+		secrets: command.secrets,
+		rerun: rerunOf,
 		notice: (text) => write.stderr(noticeLine(text, routed.json)),
 		deliver: (data) => {
-			delivered = deliveredOutcome(command, data);
+			delivered = () => dataOutcome(command, data, commandLine);
 		}
 	});
 	const spill = spillTo({
 		cliName: format.cliName,
-		commandName: command.name,
+		label: commandLabel(routed.spec.path, format.cliName),
 		env,
 		clock,
 		files: outputs.files,
@@ -10054,7 +11084,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	let served = false;
 	let settled;
 	try {
-		const outcome = await control.settle(skillOf(cli, installOf(cli)).notice({
+		const outcome = await control.settle(skillOf$1(cli, installOf(cli)).notice({
 			builtIn,
 			bin: options.bin
 		}, ctx).then(() => execute(command, input, ctx, {
@@ -10062,7 +11092,6 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			confirm: flags.confirm,
 			yes: flags.yes,
 			page: flags.page,
-			invocation,
 			commandLine,
 			started: async (outcome) => {
 				write.stdout(await startedOutput(outcome, format, spill));
@@ -10086,7 +11115,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		};
 		settled = {
 			ok: false,
-			error: control.errorAfter(error),
+			error: checkedCodes(control.errorAfter(error), routed.spec, cli),
 			delivered
 		};
 	}
@@ -10170,6 +11199,10 @@ async function runWithProgress(cli, argv, options, write, stopNotice) {
 }
 async function routeAndRun(cli, argv, options, write, stopNotice) {
 	const runAs = runAsOf(cli);
+	const root = rootSpec(cli, {
+		bin: options.bin,
+		node: options.node
+	});
 	const format = {
 		cliName: cli.name,
 		env: options.env,
@@ -10180,16 +11213,10 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 			flags: []
 		},
 		json: false,
-		errors: cli.errors ?? {},
-		stop: options.signal
+		errors: errorTableOf(cli),
+		stop: options.signal,
+		...options.checkNextSteps === true ? { checkNextStep: (step) => nextStepProblem(root, runAs, step) } : {}
 	};
-	const root = cli.commands === void 0 ? {
-		...commandSpec(runAs, cli.command),
-		description: cli.description
-	} : groupSpec(runAs, cli.commands, builtInCommands(cli, {
-		bin: options.bin,
-		node: options.node
-	}));
 	const routed = route(root, format.invocation);
 	const misused = (node) => isAgent(options.env) ? {
 		...format,
@@ -10216,10 +11243,22 @@ async function ranAlone(result) {
 }
 //#endregion
 //#region ../agent-cli/dist/run-process.js
-function written(stream, text) {
-	return new Promise((resolve) => stream.write(text, () => resolve()));
+const READER_GONE = /* @__PURE__ */ new Set(["EPIPE", "EOF"]);
+function writerTo(stream) {
+	stream.on("error", (error) => {
+		if (error.code === void 0 || !READER_GONE.has(error.code)) throw error;
+	});
+	return (text) => new Promise((resolve) => {
+		if (stream.destroyed) {
+			resolve();
+			return;
+		}
+		stream.write(text, () => resolve());
+	});
 }
 async function runProcess(cli) {
+	const stdout = writerTo(process.stdout);
+	const stderr = writerTo(process.stderr);
 	const stop = new AbortController();
 	const onSignal = (signal) => {
 		if (stop.signal.aborted) process.exit(SIGNAL_EXIT_CODES[signal]);
@@ -10237,11 +11276,11 @@ async function runProcess(cli) {
 			node: process.execPath,
 			stdin: process.stdin
 		}, {
-			stdout: (text) => process.stdout.write(text),
-			stderr: (text) => process.stderr.write(text),
-			result: async ({ stdout, stderr }) => {
-				await written(process.stdout, stdout);
-				await written(process.stderr, stderr);
+			stdout: (text) => void stdout(text),
+			stderr: (text) => void stderr(text),
+			result: async (result) => {
+				await stdout(result.stdout);
+				await stderr(result.stderr);
 			}
 		}, "stopping… (Ctrl-C again to quit now)");
 		process.exitCode = result.exitCode;
@@ -10253,16 +11292,44 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.16.0";
-var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
-//#endregion
-//#region src/build.ts
-const build = {
-	"sha": "648fa57",
-	"dirty": false,
-	"builtAt": "2026-10-27T10:21:48.000Z"
+var package_default = {
+	name: "@duyquangnvx/create-agent-cli",
+	version: "0.18.0",
+	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
+	type: "module",
+	engines: { "node": ">=22.12.0" },
+	bin: { "create-agent-cli": "./dist/bin.js" },
+	files: [
+		"dist",
+		"partials",
+		"template",
+		"agents-section.md",
+		"CHANGELOG.md"
+	],
+	publishConfig: {
+		"registry": "https://registry.npmjs.org/",
+		"access": "public"
+	},
+	scripts: {
+		"build": "node -e \"require('node:fs').copyFileSync('../agent-cli/agents-section.md', 'agents-section.md')\" && tsdown",
+		"prepack": "node -e \"require('node:fs').copyFileSync('../../CHANGELOG.md', 'CHANGELOG.md')\""
+	},
+	devDependencies: {
+		"@duyquangnvx/agent-cli": "workspace:*",
+		"tsdown": "0.23.0",
+		"zod": "4.6.7"
+	}
 };
 //#endregion
+//#region src/agents-section.ts
+const AGENTS_SECTION_FILE = new URL("../agents-section.md", import.meta.url);
+function agentsSection() {
+	return readFile(AGENTS_SECTION_FILE, "utf8");
+}
+//#endregion
+//#region src/define.ts
+const { defineCli, defineCommand, cliError } = agentCli({ errors: { STEP_FAILED: { class: "operator" } } });
+//#endregion
 //#region src/fill.ts
 /** `text` with each `{{key}}` replaced by its value; `quoted` escapes values that land inside a double-quoted string. */
 function fill(text, values, quoted) {
@@ -10277,29 +11344,55 @@ function fill(text, values, quoted) {
 const PARTIALS_DIR = fileURLToPath(new URL("../partials/", import.meta.url));
 const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const COMMANDS_ANCHOR = "  commands: {";
-const GLOBAL_INSTALL = `  install: {
-    mode: "global",
-    package: manifest.name,
-    registry: manifest.publishConfig.registry,
-  },
-`;
-const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, then put here the `! npx -y skills add` line that `node dist/bin.js doctor` gives as the `skill` row's fix. -->";
-function installModeOf(skillHub, dependency, binName) {
+const GLOBAL_INSTALL = `  install: "global",\n`;
+const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub: { git }` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, or set `skill.page` to the Skill Hub's page where each user copies their own install line and `skillHub: { api }` to the API Skill Hub each release publishes the skill to. Then put here what `node dist/bin.js doctor` gives in its `skill` row: the `! npx -y skills add` line of its fix, or the sentence naming the page. -->";
+function skillHubOf({ git, api, page }) {
+	if (git !== void 0 && api !== void 0) throw new UsageError({
+		code: "SKILL_HOMES_CONFLICT",
+		message: "--skill-hub-git and --skill-hub-api each name the Skill Hub the skill goes to",
+		hint: "pass one of them"
+	});
+	if (api !== void 0 && page === void 0) throw new UsageError({
+		code: "SKILL_PAGE_MISSING",
+		message: "--skill-hub-api needs --skill-page, the hub's page where each user copies their own install line",
+		hint: "add --skill-page with the skill's page on the hub"
+	});
+	if (page !== void 0 && api === void 0) throw new UsageError({
+		code: "SKILL_HUB_API_MISSING",
+		message: "--skill-page names a page of an API Skill Hub, which --skill-hub-api names",
+		hint: "add --skill-hub-api with the hub's URL"
+	});
+	if (git !== void 0) return {
+		kind: "git",
+		url: git
+	};
+	return api === void 0 || page === void 0 ? void 0 : {
+		kind: "api",
+		url: api,
+		page
+	};
+}
+function installModeOf(flags, dependency, binName) {
+	const skillHub = skillHubOf(flags);
 	if (skillHub !== void 0 && dependency) throw new UsageError({
 		code: "SKILL_HOMES_CONFLICT",
-		message: "--skill-hub and --dependency each name where the skill comes from: a Dependency install ships it inside the package",
-		hint: "pass --dependency for a CLI each project pins, or --skill-hub for a global one whose skill each release commits to a Skill Hub"
+		message: `--skill-hub-${skillHub.kind} and --dependency each name where the skill comes from: a Dependency install ships it inside the package`,
+		hint: `pass --dependency for a CLI each project pins, or --skill-hub-${skillHub.kind} for a global one whose skill each release puts on a Skill Hub`
 	});
 	if ((skillHub !== void 0 || dependency) && !SKILL_NAME.test(binName)) throw new UsageError({
 		code: "SKILL_NAME_INVALID",
 		message: `${binName} cannot name a skill, whose names are lowercase letters, digits and single hyphens`,
-		hint: `choose a name such as my-cli, or leave out ${dependency ? "--dependency" : "--skill-hub"}`
+		hint: `choose a name such as my-cli, or leave out ${dependency ? "--dependency" : `--skill-hub-${skillHub?.kind}`}`
 	});
 	return dependency ? { mode: "dependency" } : {
 		mode: "global",
 		skillHub
 	};
 }
+function skillLineOf(skillHub, binName) {
+	if (skillHub === void 0) return NO_SKILL_HUB;
+	return skillHub.kind === "git" ? `\`! npx -y skills add ${skillHub.url} --skill ${binName} -g\`` : `The skill's line is your own: copy your install line from ${skillHub.page}, then type it.`;
+}
 async function partialsOf(mode, values) {
 	const partial = async (name) => fill(await readFile(join(PARTIALS_DIR, mode, `${name}.md`), "utf8"), values, false).trimEnd();
 	const [installLines, skillCheck, installSteps, updateSteps, sandbox] = await Promise.all([
@@ -10318,9 +11411,8 @@ async function partialsOf(mode, values) {
 	};
 }
 async function globalSetup(skillHub, packageName, binName) {
-	const skillLine = skillHub === void 0 ? NO_SKILL_HUB : `\`! npx -y skills add ${skillHub} --skill ${binName} -g\``;
+	const skillLine = skillLineOf(skillHub, binName);
 	const runAs = runAsOf({ name: binName });
-	const url = JSON.stringify(skillHub);
 	return {
 		values: {
 			runAs,
@@ -10335,15 +11427,18 @@ async function globalSetup(skillHub, packageName, binName) {
 		edits: skillHub === void 0 ? [] : [{
 			file: "src/cli.ts",
 			find: COMMANDS_ANCHOR,
-			replace: `  skill: { source: ${url} },\n${COMMANDS_ANCHOR}`
+			replace: `  skill: ${skillOf(skillHub)},\n${COMMANDS_ANCHOR}`
 		}, {
 			file: "scripts/release.ts",
 			find: "  smoke: {",
-			replace: `  skillHub: ${url},\n  smoke: {`
+			replace: `  skillHub: { ${skillHub.kind}: ${JSON.stringify(skillHub.url)} },\n  smoke: {`
 		}],
 		files: []
 	};
 }
+function skillOf(skillHub) {
+	return skillHub.kind === "git" ? `{ source: ${JSON.stringify(skillHub.url)} }` : `{ page: ${JSON.stringify(skillHub.page)} }`;
+}
 async function dependencySetup(packageName, binName) {
 	const runAs = runAsOf({
 		name: binName,
@@ -10365,7 +11460,7 @@ async function dependencySetup(packageName, binName) {
 		edits: [{
 			file: "src/cli.ts",
 			find: GLOBAL_INSTALL,
-			replace: `  install: { mode: "dependency", package: manifest.name },\n`
+			replace: `  install: "dependency",\n`
 		}, {
 			file: "src/cli.ts",
 			find: COMMANDS_ANCHOR,
@@ -10379,7 +11474,6 @@ async function installSetupOf(install, packageName, binName) {
 }
 //#endregion
 //#region src/steps.ts
-const stepErrors = defineErrors({ STEP_FAILED: { class: "operator" } });
 const INSTALL = [{
 	command: "pnpm",
 	args: ["install"]
@@ -10448,7 +11542,7 @@ function tail(output) {
 	return output.trimEnd().split(/\r?\n/).slice(-20).join("\n");
 }
 function stepFailed(problem, left, cwd, cause) {
-	return cliError(stepErrors, "STEP_FAILED", {
+	return cliError("STEP_FAILED", {
 		message: problem,
 		hint: `fix the problem, then run in ${cwd}: ${left.map(stepLine).join(" && ")}`
 	}, { cause });
@@ -10497,10 +11591,9 @@ async function writeTemplate(root, files, values) {
 }
 //#endregion
 //#region src/version.ts
-const version = version$1;
+const version = package_default.version;
 //#endregion
 //#region src/create.ts
-const { defineCommand } = agentCli();
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?([a-z0-9][a-z0-9._-]*)$/;
 function errorCode(error) {
 	return error instanceof Error && "code" in error ? error.code : void 0;
@@ -10540,82 +11633,81 @@ async function ensureFree(path) {
 		hint: "run `create-agent-cli <name>` with a name whose directory is free, or empty it first"
 	});
 }
-const create = defineCommand({
-	name: "create",
-	description: "Create a new Agent CLI project in ./<name>",
-	examples: [{
-		command: "create-agent-cli weather --description \"Weather forecasts\"",
-		note: "create ./weather, install dependencies and make the first commit"
-	}],
-	effect: "write",
-	args: object({ name: string().regex(PACKAGE_NAME, "must be a lowercase npm package name, such as weather or @me/weather").describe("package name; its unscoped part names the bin and the directory") }),
-	options: object({
-		description: string().default("An Agent CLI.").describe("one line saying what the CLI does"),
-		install: boolean().default(true).describe("run pnpm install"),
-		git: boolean().default(true).describe("create a git repository with an initial commit"),
-		repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository"),
-		skillHub: url({ protocol: /^https$/ }).refine((url) => new URL(url).search === "" && new URL(url).hash === "", "must name the hub's repository with no query or fragment").refine((url) => new URL(url).pathname.endsWith(".git"), "must end in .git").optional().describe("the https git URL of the Skill Hub each release commits the CLI's skill to"),
-		dependency: boolean().default(false).describe("install the CLI per project, as a devDependency, with its skill shipped inside the package")
-	}),
-	plan: async ({ name, description, install, git, repository, skillHub, dependency }, ctx) => {
-		const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
-		const mode = installModeOf(skillHub, dependency, binName);
-		const path = resolve(ctx.cwd, binName);
-		await ensureFree(path);
-		const setup = await installSetupOf(mode, name, binName);
-		const values = {
-			packageName: name,
-			binName,
-			description,
-			debugVariable: debugVariable(binName),
-			runtimeVersion: version,
-			...setup.values
-		};
-		return {
-			path,
-			values,
-			files: await templateFiles(values),
-			steps: stepsFor({
-				install,
-				git
-			}),
-			install,
-			repository,
-			edits: setup.edits,
-			manifestFiles: setup.files
-		};
-	},
-	apply: async (plan, ctx) => {
-		await mkdir(plan.path, { recursive: true });
-		await writeTemplate(plan.path, plan.files, plan.values);
-		if (plan.repository !== void 0) await setRepository(plan.path, plan.repository);
-		for (const edit of plan.edits) await applyEdit(plan.path, edit);
-		if (plan.manifestFiles.length > 0) await addFiles(plan.path, plan.manifestFiles);
-		await runSteps(plan.steps, plan.path, ctx);
-		return {
-			path: plan.path,
-			next: `cd ${plan.values.binName} && pnpm ${plan.install ? "test" : "install"}`
-		};
-	},
-	render: ({ path, next }) => `Created ${path}\nnext: ${next}`,
-	renderPlan: (plan) => [
-		`Would create ${plan.path}:`,
-		...plan.files.map((file) => `  create ${file.target}`),
-		...plan.steps.map((step) => `  run ${stepLine(step)}`)
-	].join("\n")
-});
-//#endregion
-//#region src/cli.ts
-const { defineCli } = agentCli();
 //#endregion
 //#region src/bin.ts
 await runProcess(defineCli({
-	name: "create-agent-cli",
-	version,
-	description,
-	build,
-	errors: stepErrors,
-	command: create
+	manifest: package_default,
+	command: defineCommand({
+		description: "Create a new Agent CLI project in ./<name>",
+		examples: [{
+			command: "create-agent-cli weather --description \"Weather forecasts\"",
+			note: "create ./weather, install dependencies and make the first commit"
+		}],
+		effect: "write",
+		errors: ["STEP_FAILED"],
+		args: object({ name: string().regex(PACKAGE_NAME, "must be a lowercase npm package name, such as weather or @me/weather").describe("package name; its unscoped part names the bin and the directory") }),
+		options: object({
+			description: string().default("An Agent CLI.").describe("one line saying what the CLI does"),
+			install: boolean().default(true).describe("run pnpm install"),
+			git: boolean().default(true).describe("create a git repository with an initial commit"),
+			repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository"),
+			skillHubGit: url({ protocol: /^https$/ }).refine((url) => new URL(url).search === "" && new URL(url).hash === "", "must name the hub's repository with no query or fragment").refine((url) => new URL(url).pathname.endsWith(".git"), "must end in .git").optional().describe("the https git URL of a git Skill Hub each release commits the CLI's skill to"),
+			skillHubApi: url({ protocol: /^https$/ }).optional().describe("the https URL of an API Skill Hub each release publishes the CLI's skill to"),
+			skillPage: url({ protocol: /^https$/ }).optional().describe("the https page of the skill on the API Skill Hub, where each user copies their own install line"),
+			dependency: boolean().default(false).describe("install the CLI per project, as a devDependency, with its skill shipped inside the package")
+		}),
+		plan: async ({ name, description, install, git, repository, skillHubGit, skillHubApi, skillPage, dependency }, ctx) => {
+			const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
+			const mode = installModeOf({
+				git: skillHubGit,
+				api: skillHubApi,
+				page: skillPage
+			}, dependency, binName);
+			const path = resolve(ctx.cwd, binName);
+			await ensureFree(path);
+			const setup = await installSetupOf(mode, name, binName);
+			const values = {
+				packageName: name,
+				binName,
+				description,
+				debugVariable: debugVariable(binName),
+				runtimeVersion: version,
+				agentsSection: await agentsSection(),
+				...setup.values
+			};
+			return {
+				path,
+				values,
+				files: await templateFiles(values),
+				steps: stepsFor({
+					install,
+					git
+				}),
+				install,
+				repository,
+				edits: setup.edits,
+				manifestFiles: setup.files
+			};
+		},
+		apply: async (plan, ctx) => {
+			await mkdir(plan.path, { recursive: true });
+			await writeTemplate(plan.path, plan.files, plan.values);
+			if (plan.repository !== void 0) await setRepository(plan.path, plan.repository);
+			for (const edit of plan.edits) await applyEdit(plan.path, edit);
+			if (plan.manifestFiles.length > 0) await addFiles(plan.path, plan.manifestFiles);
+			await runSteps(plan.steps, plan.path, ctx);
+			return {
+				path: plan.path,
+				next: `cd ${plan.values.binName} && pnpm ${plan.install ? "test" : "install"}`
+			};
+		},
+		render: ({ path, next }) => `Created ${path}\nnext: ${next}`,
+		renderPlan: (plan) => [
+			`Would create ${plan.path}:`,
+			...plan.files.map((file) => `  create ${file.target}`),
+			...plan.steps.map((step) => `  run ${stepLine(step)}`)
+		].join("\n")
+	})
 }));
 //#endregion
 export {};