@duyquangnvx/create-agent-cli 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.30.0 (2026-11-09)
+
+### Added
+
+- A Side task learns how its run ended: `SideTaskRun` has `ended`, a promise of `RunEnd`, `{ exitCode, errors: [{ code, message }] }` with no errors on success, as the caller sees it, the Runtime's codes such as `INTERRUPTED` included. `RunEnd` and `RunEndError` are exported.
+- `defineCli({ skill })` of a Global install takes `add`, the whole line that installs the skill from its Skill Hub, so the Hub sees who installed it. `setup` then copies no skill and ends with `run: <add>`, its `--json` `skill` being `{ add }`, on every run; `update` leaves the Skill copy alone, its `skill` being `null`; and `doctor`'s `skill` row passes on any one home copy and gives `add` as the fix when there is none. `defineCli` throws on an empty or multi-line `add`, and on `add` beside any install but a Global install. Users whose copy came from the package move to the Hub when they run `setup` again, so a CLI that adds `add` asks them to.
+
+### Changed
+
+- **Breaking:** `defineCli({ sideTask })` also runs for a Command whose input is rejected, such as a missing arg or an unknown option after its name, with `dryRun` false, so a usage count also counts those runs.
+
+### Upgrade from v0.29.0
+
+- A Side task that must not count a run whose input was rejected awaits `ended` and skips that run by its error code, such as `INVALID_INPUT`.
+
+## v0.29.0 (2026-11-09)
+
+### Added
+
+- `agentCli` returns `defineDoctorCheck`, which types a `doctor` row's `ctx` by the CLI's ports and Project file and its `errors` by the Error table, so a row needs no `DoctorCheck<Ports, Settings>` annotation and a code the table lacks is a type error.
+
+### Changed
+
+- **Breaking:** `defineCommand`, as `agentCli` returns it, is one method per Effect: `defineCommand.read`, `.act`, `.write`, `.destructive`, `.serve`, and `.list` for a List Command. A Command no longer declares `effect`, which the method sets, and `defineCommand.read` no longer takes `rows`. Each method has one signature, so a type error names the property at fault, such as a `run` returning a string where `output` has a number, rather than an Effect. The scaffolded template uses the methods.
+- **Breaking:** `checkExamples` from `@duyquangnvx/agent-cli/testing` is `checkCli`, since it checks more than examples; the scaffolded template's test calls it.
+- **Breaking:** `checkCli` also fails on a Command help shows that has no example, and on an arg or option without `.describe()`, so a CLI's test that passed `checkExamples` may fail until it adds them.
+- `ctx.secret` with a name the Command does not declare is a type error that names the declared Secrets, or reads `"the Command declares no secrets"` when it declares none, rather than one about `never`.
+- The scaffolded template pins `@biomejs/biome` 2.6.2 and `@duyquangnvx/harness` 0.5.2, the versions the Runtime itself is checked with.
+
+### Upgrade from v0.28.0
+
+- Call `checkCli` where the CLI's tests called `checkExamples`, then give each Command and field it names an example or a `.describe()`.
+- Declare each Command with the method of its Effect and delete its `effect`: `defineCommand({ effect: "write", … })` becomes `defineCommand.write({ … })`, and a read Command that declares `rows` becomes `defineCommand.list({ … })`.
+
 ## v0.28.0 (2026-11-09)
 
 ### Added

package/dist/bin.js

@@ -5972,10 +5972,19 @@ function bugHint(format) {
 	const rerun = `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`;
 	return bugs === void 0 ? rerun : `${rerun}, then report it at ${bugs}`;
 }
+/** The code and message the caller sees for one error a run failed with. */
+function runEndErrorOf(error) {
+	return error instanceof CliError ? {
+		code: error.code,
+		message: error.message
+	} : {
+		code: INTERNAL,
+		message: messageOf(error)
+	};
+}
 function fieldsOf$1({ error, exitClass }, format) {
 	if (!(error instanceof CliError)) return {
-		code: INTERNAL,
-		message: messageOf(error),
+		...runEndErrorOf(error),
 		hint: bugHint(format)
 	};
 	const { code, message, hint, details, retryAt, next } = error;
@@ -7700,10 +7709,20 @@ function checkErrors(errors, label, table) {
 	if (unknown.length > 0) throw new Error(`${label} declares ${unknown.join(", ")} in errors, a code the Error table lacks`);
 }
 function defineCommandFor() {
-	return declared;
+	return {
+		list: withEffect("read"),
+		read: withEffect("read"),
+		act: withEffect("act"),
+		serve: withEffect("serve"),
+		write: withEffect("write"),
+		destructive: withEffect("destructive")
+	};
 }
-function declared(command) {
-	return command;
+function withEffect(effect) {
+	return (command) => ({
+		...command,
+		effect
+	});
 }
 const defineCommand$1 = defineCommandFor();
 //#endregion
@@ -7724,9 +7743,9 @@ function cliErrorOf(code, init, options) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "b509cf2",
+		"sha": "3c4069a",
 		"dirty": false,
-		"builtAt": "2026-11-09T01:38:28.000Z"
+		"builtAt": "2026-11-09T06:02:49.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -8388,12 +8407,19 @@ const homeSyncSchema = object({
 	written: array(string()),
 	removed: array(string())
 });
+function copiedFromPackage(skill) {
+	return skill !== void 0 && skill.add === void 0;
+}
+/** The home Skill copies `setup` and `update` write: none when the skill comes from its Skill Hub. */
+async function syncedCopiesOf(cli, ctx) {
+	return copiedFromPackage(cli.skill) ? homeCopiesOf(ctx.files, cli.name, ctx.env) : [];
+}
 /**
 * Makes each home Skill copy match the folder in the package at `packageDir`. Null when the CLI
-* declares no skill, or that package ships none, which must not empty a copy.
+* declares no skill, its Skill Hub installs it, or that package ships none, which must not empty a copy.
 */
 async function syncHome(cli, packageDir, ctx) {
-	if (cli.skill === void 0) return null;
+	if (!copiedFromPackage(cli.skill)) return null;
 	const source = join(packageDir, cli.skill.folder);
 	if ((await filesIn(ctx.files, source)).length === 0) return null;
 	const copies = await homeCopiesOf(ctx.files, cli.name, ctx.env);
@@ -8453,14 +8479,27 @@ async function findingOf$1(cli, folder, install, ctx) {
 		fix: `${install.runAs} setup`
 	};
 }
-/** A skill the package ships, which `setup` and `update` copy under home. */
-function homeSkill(cli, { folder }, install) {
+async function hubFindingOf(cli, add, ctx) {
+	const paths = await homeCopiesOf(ctx.files, cli.name, ctx.env);
+	const copies = await Promise.all(paths.map((path) => homeCopyAt(ctx.files, path)));
+	const found = copies.filter((copy) => copy.state !== "missing");
+	return found.length === 0 ? {
+		state: "problem",
+		message: copies.map(describeCopy).join("; "),
+		fix: add
+	} : {
+		state: "ok",
+		message: found.map((copy) => copy.path).join("; ")
+	};
+}
+/** A skill the package ships, which `setup` and `update` copy under home unless its Skill Hub installs it. */
+function homeSkill(cli, { folder, add }, install) {
 	return {
 		builtIns: {},
 		rows: [{
 			name: "skill",
 			advisory: true,
-			run: (ctx) => findingOf$1(cli, folder, install, ctx)
+			run: (ctx) => add === void 0 ? findingOf$1(cli, folder, install, ctx) : hubFindingOf(cli, add, ctx)
 		}]
 	};
 }
@@ -8533,7 +8572,7 @@ const setupSchema = object({
 	version: string(),
 	prefix: string(),
 	installed: boolean(),
-	skill: homeSyncSchema.nullable(),
+	skill: union([homeSyncSchema, object({ add: string() })]).nullable(),
 	upgrades: array(upgradeSchema),
 	docs: string().nullable()
 });
@@ -8593,18 +8632,28 @@ function withSetupLine(error, install) {
 		next: [wholeLine(setupLineOf(install))]
 	}, { cause: error });
 }
+function renderNext(name, docs, skill) {
+	const read = docs === null ? [] : [`docs ${docs}`];
+	if (skill === null || !("add" in skill)) return docs === null ? read : [...read, `Read that folder before using ${name}.`];
+	const then = docs === null ? "" : `, then read that folder before using ${name}`;
+	return [
+		...read,
+		`Install the ${name} skill from its Skill Hub${then}.`,
+		`run: ${skill.add}`
+	];
+}
 function renderSetup(cli, install, setup) {
-	const { version, prefix, docs } = setup;
+	const { version, prefix, docs, skill } = setup;
 	return [
 		setup.installed ? `installed ${install.package}@${version} with the npm under ${prefix}` : `${install.package}@${version} is already installed under ${prefix}`,
-		...renderHomeSync(cli.name, setup.skill),
+		...skill !== null && "copies" in skill ? renderHomeSync(cli.name, skill) : [],
 		...setup.upgrades.map(renderUpgrade),
-		...docs === null ? [] : [`docs ${docs}`, `Read that folder before using ${cli.name}.`]
+		...renderNext(cli.name, docs, skill)
 	].join("\n");
 }
 /** The built-in `setup`, which runs from any copy, such as npx's, so it never asks to be the global one. */
 function setupCommand(cli, install, launch) {
-	return defineCommand$1({
+	return defineCommand$1.write({
 		description: "install this CLI and its skill on this machine",
 		examples: [{
 			command: `${cli.name} setup`,
@@ -8613,7 +8662,6 @@ function setupCommand(cli, install, launch) {
 			command: `${cli.name} setup --dry-run`,
 			note: "show what it would change"
 		}],
-		effect: "write",
 		errors: [
 			NOT_GLOBAL_INSTALL,
 			NOT_ON_PATH,
@@ -8636,7 +8684,7 @@ function setupCommand(cli, install, launch) {
 				latest: await latestVersion(npm),
 				prefix,
 				packageDir,
-				copies: cli.skill === void 0 ? [] : await homeCopiesOf(ctx.files, cli.name, ctx.env)
+				copies: await syncedCopiesOf(cli, ctx)
 			};
 		},
 		apply: async (plan, ctx) => {
@@ -8655,16 +8703,25 @@ function setupCommand(cli, install, launch) {
 				version: installs || from === null ? latest : from,
 				prefix,
 				installed: installs,
-				skill,
+				skill: cli.skill?.add === void 0 ? skill : { add: cli.skill.add },
 				upgrades: installs && from !== null ? await upgradesOf(ctx.files, packageDir, from, latest) : [],
 				docs: cli.docs === void 0 ? null : join(packageDir, cli.docs)
 			};
 			ctx.deliver(setup);
-			if (ctx.signal.aborted) throw new CliError({
-				code: INTERRUPTED,
-				message: `interrupted, but ${plan.package}@${setup.version} and its skill are already in place`,
-				hint: "nothing to run again"
-			});
+			if (ctx.signal.aborted) {
+				const add = cli.skill?.add;
+				if (add === void 0) throw new CliError({
+					code: INTERRUPTED,
+					message: `interrupted, but ${plan.package}@${setup.version} and its skill are already in place`,
+					hint: "nothing to run again"
+				});
+				throw runtimeError({
+					code: INTERRUPTED,
+					message: `interrupted, but ${plan.package}@${setup.version} is already installed`,
+					hint: "run the Next step to install its skill from its Skill Hub",
+					next: [wholeLine(add)]
+				});
+			}
 			await assertOnPath(cli, prefix, launch, ctx);
 			return setup;
 		},
@@ -8705,7 +8762,7 @@ function interruptedAfterInstall(plan) {
 }
 /** The built-in `update`, for a CLI installed globally with npm. */
 function updateCommand(cli, install, launch) {
-	return defineCommand$1({
+	return defineCommand$1.write({
 		description: "install the latest version of this CLI from its registry",
 		examples: [{
 			command: `${cli.name} update`,
@@ -8714,7 +8771,6 @@ function updateCommand(cli, install, launch) {
 			command: `${cli.name} update --dry-run`,
 			note: "show the version it would install"
 		}],
-		effect: "write",
 		errors: [NOT_GLOBAL_INSTALL, ...NPM_ERRORS],
 		output: updateSchema,
 		plan: async (_input, ctx) => {
@@ -8726,7 +8782,7 @@ function updateCommand(cli, install, launch) {
 				latest: await latestVersion(npm),
 				prefix: copy.prefix,
 				packageDir: copy.packageDir,
-				copies: cli.skill === void 0 ? [] : await homeCopiesOf(ctx.files, cli.name, ctx.env)
+				copies: await syncedCopiesOf(cli, ctx)
 			};
 		},
 		apply: async (plan, ctx) => {
@@ -9077,7 +9133,7 @@ function renderInstalled(cli, data) {
 }
 /** The built-in `skill install`, for a CLI whose skill ships in its package. */
 function skillInstallCommand(cli, folder, agents) {
-	return defineCommand$1({
+	return defineCommand$1.write({
 		description: agents === void 0 ? "copy this CLI's skill into the project" : "copy this CLI's skill into the project and write its Agents section",
 		examples: [{
 			command: `${cli.name} skill install`,
@@ -9086,7 +9142,6 @@ function skillInstallCommand(cli, folder, agents) {
 			command: `${cli.name} skill install --dry-run`,
 			note: "show what it would change"
 		}],
-		effect: "write",
 		output: installSchema,
 		plan: (_input, ctx) => planOf(cli, folder, agents, ctx),
 		apply: async (plan, ctx) => {
@@ -9428,7 +9483,7 @@ function checkedRows(error, problems, table) {
 }
 /** The built-in `doctor`: the fixed rows around the CLI's own, each under its own deadline. */
 function doctorCommand(cli, launch) {
-	const doctor = defineCommand$1({
+	const doctor = defineCommand$1.read({
 		description: "check the setup and say what fixes each problem",
 		examples: [{
 			command: `${cli.name} doctor`,
@@ -9437,7 +9492,6 @@ function doctorCommand(cli, launch) {
 			command: `${cli.name} doctor --json`,
 			note: "get the rows and fixes as data"
 		}],
-		effect: "read",
 		output: reportSchema,
 		run: async (_input, ctx) => {
 			const rowsScope = {
@@ -9629,12 +9683,17 @@ function checkTree(commands, path, table) {
 }
 function checkSkill({ name, skill, install }) {
 	if (skill?.agents !== void 0 && install?.mode === "global") throw new Error(`${name} declares an Agents section on a Global install, which has no repo to write it to`);
+	const add = skill?.add;
+	if (add === void 0) return;
+	if (add.trim() === "") throw new Error(`${name} declares an empty Skill Hub install line`);
+	if (/[\r\n]/.test(add)) throw new Error(`${name} declares a Skill Hub install line holding a line break`);
+	if (install?.mode !== "global") throw new Error(`${name} declares a Skill Hub install line, which only a Global install uses: any other's Skill copy goes in the project`);
 }
 function checkDocs({ name, docs }) {
 	if (docs === void 0) return;
 	if (!(docs !== "" && !isAbsolute(docs) && !normalize(docs).startsWith(".."))) throw new Error(`${name} declares docs ${JSON.stringify(docs)}: name a folder inside its package, relative to the package root`);
 }
-function checkCli(cli) {
+function checkDeclared(cli) {
 	const table = errorTableOf(cli);
 	checkDocs(cli);
 	if (cli.commands === void 0) {
@@ -9707,16 +9766,17 @@ function resolved(cli) {
 }
 /**
 * Takes the CLI's ports factory, Project file and Error table once; the `defineCommand`,
-* `defineCli` and `cliError` it returns are typed by them.
+* `defineDoctorCheck`, `defineCli` and `cliError` it returns are typed by them.
 */
 function agentCli(values = {}) {
 	checkOwnCodes(errorTableOf(values));
 	return {
 		defineCommand: defineCommandFor(),
-		defineCli: (cli) => checkCli({
+		defineCli: (cli) => checkDeclared({
 			...resolved(cli),
 			...values
 		}),
+		defineDoctorCheck: (row) => row,
 		cliError: cliErrorOf
 	};
 }
@@ -9725,17 +9785,25 @@ function agentCli(values = {}) {
 /** How long a run waits for its Side task once its output is written. */
 const SIDE_TASK_WAIT_MS = 1e3;
 const noSideTask = async () => {};
+const NO_SIDE_TASK = {
+	end: () => {},
+	finish: noSideTask
+};
 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;
+	if (sideTask === void 0) return NO_SIDE_TASK;
+	let end = () => {};
+	const ended = new Promise((resolve) => {
+		end = resolve;
+	});
 	const controller = new AbortController();
 	const { signal } = controller;
-	const running = (async () => sideTask(runWith(signal)))().catch((error) => {
+	const running = (async () => sideTask(runWith(signal, ended)))().catch((error) => {
 		if (!(signal.aborted && error === signal.reason)) failed(error);
 	});
-	return async () => {
+	const finish = async () => {
 		const waited = new AbortController();
 		const capped = new Promise((resolve) => after(clock, SIDE_TASK_WAIT_MS, waited.signal, () => {
 			const over = waitOver();
@@ -9746,6 +9814,10 @@ function startSideTask(sideTask, runWith, { clock, failed }) {
 		await Promise.race([running, capped]);
 		waited.abort();
 	};
+	return {
+		end,
+		finish
+	};
 }
 //#endregion
 //#region ../agent-cli/dist/command-line/suggest.js
@@ -10485,11 +10557,24 @@ function errorText({ leaves }, format) {
 	const { usageHelp, json } = format;
 	return usageHelp !== void 0 && !json && leaves.some((leaf) => leaf.error instanceof UsageError) ? `${text}\n${usageHelp}` : text;
 }
+function endOf(failure) {
+	return {
+		exitCode: failure.exitCode,
+		errors: failure.leaves.map((leaf) => runEndErrorOf(leaf.error))
+	};
+}
+const SUCCEEDED = {
+	exitCode: SUCCESS_EXIT_CODE,
+	errors: []
+};
 function failedResult(failure, format) {
 	return {
-		stdout: "",
-		stderr: errorText(failure, format),
-		exitCode: failure.exitCode
+		result: {
+			stdout: "",
+			stderr: errorText(failure, format),
+			exitCode: failure.exitCode
+		},
+		end: endOf(failure)
 	};
 }
 function stdoutOf({ value, render }, format, spill) {
@@ -10504,10 +10589,13 @@ function startedOutput(outcome, format, spill) {
 	}, spill);
 }
 /** A serve Command stopped, or ended itself, after it started: that is how it is meant to end. */
-const STOPPED_RESULT = {
-	stdout: "",
-	stderr: "",
-	exitCode: SUCCESS_EXIT_CODE
+const STOPPED = {
+	result: {
+		stdout: "",
+		stderr: "",
+		exitCode: SUCCESS_EXIT_CODE
+	},
+	end: SUCCEEDED
 };
 async function errorResult(error, format) {
 	return failedResult(await failureOf(error, format), format);
@@ -10515,9 +10603,12 @@ async function errorResult(error, format) {
 async function commandResult(settled, format, spill) {
 	if (settled.ok) try {
 		return {
-			stdout: await stdoutOf(settled.outcome, format, spill),
-			stderr: "",
-			exitCode: SUCCESS_EXIT_CODE
+			result: {
+				stdout: await stdoutOf(settled.outcome, format, spill),
+				stderr: "",
+				exitCode: SUCCESS_EXIT_CODE
+			},
+			end: SUCCEEDED
 		};
 	} catch (spillError) {
 		return errorResult(spillError, format);
@@ -10531,16 +10622,26 @@ async function commandResult(settled, format, spill) {
 	} catch (rejected) {
 		return failedResult(withLeaves(failure, rejected, format), format);
 	}
-	const result = failedResult(failure, format);
+	const { result, end } = failedResult(failure, format);
 	try {
 		return {
-			...result,
-			stdout: await stdoutOf(outcome, format, spill)
+			result: {
+				...result,
+				stdout: await stdoutOf(outcome, format, spill)
+			},
+			end
 		};
 	} catch (spillError) {
+		const lost = withLeaves(failure, spillError, format);
 		return {
-			...result,
-			stderr: errorText(withLeaves(failure, spillError, format), format)
+			result: {
+				...result,
+				stderr: errorText(lost, format)
+			},
+			end: {
+				...endOf(lost),
+				exitCode: result.exitCode
+			}
 		};
 	}
 }
@@ -11483,13 +11584,35 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		json: routed.json,
 		invocation
 	};
-	const failed = async (error, finishSideTask) => {
-		control.close();
+	const sideTaskOf = (dryRun) => startSideTask(builtIn ? void 0 : cli.sideTask?.bind(cli), (sideSignal, ended) => {
+		const sideBase = scope.portsBase(sideSignal);
+		const sidePorts = once(() => scope.ports(sideBase));
 		return {
-			result: await errorResult(error, format),
-			finishSideTask
+			...sideBase,
+			command: routed.spec.path,
+			dryRun,
+			ended,
+			get ports() {
+				return sidePorts();
+			}
+		};
+	}, {
+		clock,
+		failed: (error) => {
+			if (isDebug(baseFormat)) progress(`side task failed: ${traceOf(error)}`);
+		}
+	});
+	const ran = ({ result, end }, sideTask) => {
+		sideTask.end(end);
+		return {
+			result,
+			finishSideTask: sideTask.finish
 		};
 	};
+	const failed = (error) => {
+		control.close();
+		return errorResult(error, format);
+	};
 	let parsed;
 	try {
 		checkOperator(routed.spec, env, rerun);
@@ -11501,27 +11624,11 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			});
 		});
 	} catch (error) {
-		return failed(error, noSideTask);
+		return ran(await failed(error), sideTaskOf(false));
 	}
 	const { input, flags } = parsed;
 	resumed = command.deadline?.resume(input, rerunOf);
-	const finishSideTask = startSideTask(builtIn ? void 0 : cli.sideTask?.bind(cli), (sideSignal) => {
-		const sideBase = scope.portsBase(sideSignal);
-		const sidePorts = once(() => scope.ports(sideBase));
-		return {
-			...sideBase,
-			command: routed.spec.path,
-			dryRun: flags.dryRun,
-			get ports() {
-				return sidePorts();
-			}
-		};
-	}, {
-		clock,
-		failed: (error) => {
-			if (isDebug(baseFormat)) progress(`side task failed: ${traceOf(error)}`);
-		}
-	});
+	const sideTask = sideTaskOf(flags.dryRun);
 	let project;
 	try {
 		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, {
@@ -11529,7 +11636,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			rerun
 		});
 	} catch (error) {
-		return failed(error, finishSideTask);
+		return ran(await failed(error), sideTask);
 	}
 	let delivered;
 	const ctx = contextOf(scope, control, {
@@ -11565,32 +11672,23 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			},
 			outputs
 		})));
-		if (served) return {
-			result: STOPPED_RESULT,
-			finishSideTask
-		};
+		if (served) return ran(STOPPED, sideTask);
 		settled = {
 			ok: true,
 			outcome
 		};
 	} catch (error) {
-		if (served && control.signal.aborted) return {
-			result: STOPPED_RESULT,
-			finishSideTask
-		};
+		if (served && control.signal.aborted) return ran(STOPPED, sideTask);
 		settled = {
 			ok: false,
 			error,
 			delivered
 		};
 	}
-	return {
-		result: await commandResult(settled, {
-			...format,
-			fields: flags.fields
-		}, spill),
-		finishSideTask
-	};
+	return ran(await commandResult(settled, {
+		...format,
+		fields: flags.fields
+	}, spill), sideTask);
 }
 async function noticesOf(cli, launch, ctx) {
 	await installOf(cli).notice(launch, ctx);
@@ -11678,10 +11776,10 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 			...format,
 			json: routed.json
 		}));
-		case "usage error": return ranAlone(errorResult(routed.error, {
+		case "usage error": return ranAlone((await errorResult(routed.error, {
 			...misused(routed.node),
 			json: routed.json
-		}));
+		})).result);
 		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(cli, routed, options, write, misused(routed.spec)));
 	}
 }
@@ -11744,7 +11842,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.28.0",
+	version: "0.30.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },
@@ -12031,13 +12129,12 @@ async function ensureFree(path) {
 //#region src/bin.ts
 await runProcess(defineCli({
 	manifest: package_default,
-	command: defineCommand({
+	command: defineCommand.write({
 		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({

package/package.json

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

package/template/biome.json

@@ -1,4 +1,4 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.6.2/schema.json",
   "extends": ["@duyquangnvx/harness/biome"]
 }

package/template/package.json

@@ -28,9 +28,9 @@
     "release": "node scripts/release.ts"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.15",
+    "@biomejs/biome": "2.6.2",
     "@duyquangnvx/agent-cli": "{{runtimeVersion}}",
-    "@duyquangnvx/harness": "0.3.1",
+    "@duyquangnvx/harness": "0.5.2",
     "@duyquangnvx/release": "0.9.0",
     "@types/node": "^22.19.0",
     "tsdown": "0.23.0",

package/template/src/cli.ts

@@ -9,7 +9,7 @@ const { defineCli, defineCommand } = agentCli({ errors, ports });
 const FREE_LANGUAGE = "en";
 const PRICE_PER_CARD = "$0.01";
 
-const greet = defineCommand({
+const greet = defineCommand.read({
   description: "Greet someone by name",
   examples: [
     {
@@ -21,14 +21,13 @@ const greet = defineCommand({
       note: "get the greeting as JSON",
     },
   ],
-  effect: "read",
   args: z.object({
     name: z.string().min(1).describe("who to greet"),
   }),
   run: ({ name }) => ({ greeting: `Hello, ${name}!` }),
 });
 
-const card = defineCommand({
+const card = defineCommand.write({
   description: "Write a greeting card to <name>.txt",
   help:
     `A card in English is free; one in another language costs ${PRICE_PER_CARD} and needs --yes. ` +
@@ -47,7 +46,6 @@ const card = defineCommand({
       note: "sign the card from Ben and Cy",
     },
   ],
-  effect: "write",
   errors: ["LANGUAGE_UNSUPPORTED"],
   args: z.object({
     name: z

package/template/test/cli.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { type Files, runCli } from "@duyquangnvx/agent-cli";
-import { checkExamples } from "@duyquangnvx/agent-cli/testing";
+import { checkCli } from "@duyquangnvx/agent-cli/testing";
 import { describe, expect, test } from "vitest";
 import manifest from "../package.json" with { type: "json" };
 import { cli } from "../src/cli.ts";
@@ -74,8 +74,8 @@ function run(
   return runCli(cli, argv, { cwd: CWD, files, ports: { greetings }, stdin });
 }
 
-test("every example parses, names a Command and passes its schemas", async () => {
-  await checkExamples(cli);
+test("every example runs, every Command help shows has one, and every arg and option is described", async () => {
+  await checkCli(cli);
 });
 
 describe("greet", () => {