@pmelab/gtd 59.0.0 → 59.0.1

package/dist/gtd.bundle.mjs

@@ -22068,7 +22068,7 @@ const defineWorkflow = (schema, build) => {
 			options
 		},
 		then: () => {
-			throw new Error("a configured workflow is not a flow — compose fixFlow/reviewFlow instead");
+			throw new Error("a configured workflow is not a flow — await the flow functions it is built from instead");
 		}
 	});
 	return Object.assign(factory, { [FACTORY]: internals });
@@ -27851,7 +27851,7 @@ function tokenizeTitleBefore(effects, ok, nok) {
 		return code === null || markdownLineEnding(code) ? ok(code) : nok(code);
 	}
 }
-var definition, titleBefore;
+var definition$1, titleBefore;
 var init_definition = __esmMin((() => {
 	init_micromark_factory_destination();
 	init_micromark_factory_label();
@@ -27860,7 +27860,7 @@ var init_definition = __esmMin((() => {
 	init_micromark_factory_whitespace();
 	init_micromark_util_character();
 	init_micromark_util_normalize_identifier();
-	definition = {
+	definition$1 = {
 		name: "definition",
 		tokenize: tokenizeDefinition
 	};
@@ -30848,7 +30848,7 @@ var init_constructs = __esmMin((() => {
 		[57]: list,
 		[62]: blockQuote
 	};
-	contentInitial = { [91]: definition };
+	contentInitial = { [91]: definition$1 };
 	flowInitial = {
 		[-2]: codeIndented,
 		[-1]: codeIndented,
@@ -37996,7 +37996,7 @@ const landProseText = (subject) => renderFormat(FMT_LAND_PROSE, subject);
 * `gtd judge answer` (the only other caller of `planLanding`/`landFields`)
 * passes its own two-word name so the hint stays runnable verbatim.
 */
-const renderLandPlain = (fields, command = "land") => fields.subject !== null ? `${landProseText(fields.subject).trimEnd()}\n(run \`gtd ${command} --json=script | sh\` to get the landing script)\n` : noopText(fields.state);
+const renderLandPlain = (fields, command = "land") => fields.subject !== null ? `${landProseText(fields.subject).trimEnd()}\n(to land it: s=$(gtd ${command} --json=script) && sh -c "$s")\n` : noopText(fields.state);
 //#endregion
 //#region src/wire/Judge.ts
 const judgeJson = (state, questions) => JSON.stringify({
@@ -39140,7 +39140,7 @@ const dedupeDiagnostics = (diagnostics) => {
 //#endregion
 //#region src/workflow/load.ts
 init_esm();
-const configError = (diagnostics) => new GtdError(`gtd config:\n${diagnostics.filter((d) => d.severity === "error").map((d) => `  - ${formatDiagnostic(d)}`).join("\n")}`);
+const configError = (diagnostics) => new GtdError(`gtd: config:\n${diagnostics.filter((d) => d.severity === "error").map((d) => `  - ${formatDiagnostic(d)}`).join("\n")}`);
 const failOnErrors = (diagnostics) => diagnostics.some((d) => d.severity === "error") ? fail$7(configError(diagnostics)) : _void;
 const MIGRATION_DOC = "https://github.com/pmelab/gtd/blob/main/docs/configuration.md#migrating-from-gtdrc";
 /**
@@ -39156,7 +39156,7 @@ const refuseLegacyRc = gen(function* () {
 	const found = files.filter((f) => f.owned).map((f) => f.path);
 	if (found.length === 0) return;
 	return yield* fail$7(new GtdError([
-		"gtd config:",
+		"gtd: config:",
 		...found.map((file) => `  - ${file}: no longer read — delete it`),
 		"  gtd 23 removed the .gtdrc files; move each key they set:",
 		"    vars    → an option of the workflow factory in gtd.config.ts, or its `defaults` export",
@@ -39192,7 +39192,7 @@ const load = gen(function* () {
 	});
 	const loaded = yield* try_({
 		try: () => loadWorkflows(module, shipped),
-		catch: (e) => new GtdError(`gtd config:\n  - ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`)
+		catch: (e) => new GtdError(`gtd: config:\n  - ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`)
 	});
 	const compiled = loaded.config;
 	const diagnostics = dedupeDiagnostics(sortDiagnostics([...compiled.diagnostics, ...loaded.diagnostics]));
@@ -39697,7 +39697,7 @@ const replayToFirstStep = (loaded, vars, env, tree) => flatMap$4(promise(() => r
 })), (outcome) => {
 	if (outcome.kind === "rest") return succeed$3(outcome.rest.name);
 	const problem = outcome.kind === "failed" || outcome.kind === "refused" ? outcome.message.replace(/^gtd: /, "") : "the default entry must begin at a step — that step is where a finished process waits";
-	return fail$7(new GtdError(`gtd config:\n  - ${loaded.file.origin}: ${problem}`));
+	return fail$7(new GtdError(`gtd: config:\n  - ${loaded.file.origin}: ${problem}`));
 });
 /**
 * The default entry's first step — where a finished process waits — found the
@@ -39713,13 +39713,13 @@ const firstStep = (loaded, head) => gen(function* () {
 	const env = watchedEmptySettings();
 	const outcome = yield* either(replayToFirstStep(loaded, vars.settings, env.settings, empty.tree));
 	const reads = [...settingReads("process", vars), ...settingReads("environment", env)];
-	if (reads.length > 0) return yield* fail$7(new GtdError(`gtd config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start reads ${reads.join(" and ")} — that step is where a finished process waits, so it must not depend on a setting`));
+	if (reads.length > 0) return yield* fail$7(new GtdError(`gtd: config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start reads ${reads.join(" and ")} — that step is where a finished process waits, so it must not depend on a setting`));
 	if (outcome._tag === "Left") return yield* fail$7(outcome.left);
 	const name = outcome.right;
 	if (!empty.read()) return name;
 	const atHead = yield* replayToFirstStep(loaded, vars.settings, env.settings, head);
 	if (atHead === name) return name;
-	return yield* fail$7(new GtdError(`gtd config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start depends on the repository's files ("${name}" without them, "${atHead}" at HEAD) — that step is where a finished process waits, so it must not change as files do`));
+	return yield* fail$7(new GtdError(`gtd: config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start depends on the repository's files ("${name}" without them, "${atHead}" at HEAD) — that step is where a finished process waits, so it must not change as files do`));
 });
 var ConfigService = class ConfigService extends Tag("ConfigService")() {
 	static Live = succeed$2(ConfigService, { load });
@@ -39727,7 +39727,7 @@ var ConfigService = class ConfigService extends Tag("ConfigService")() {
 //#endregion
 //#region src/workflow/skills.ts
 init_esm();
-const fail$4 = (origin, message) => new GtdError(`gtd config:\n  - ${origin}: ${message}`);
+const fail$4 = (origin, message) => new GtdError(`gtd: config:\n  - ${origin}: ${message}`);
 const checkShape = (value) => {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("skills export must return an object of scope -> skill names");
 	for (const [scope, names] of Object.entries(value)) if (!Array.isArray(names) || names.some((n) => typeof n !== "string")) throw new Error(`skills export: "${scope}" must be an array of skill names`);
@@ -40514,7 +40514,7 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 	const step = outcome.rest;
 	yield* (yield* Narrator).narrate(`rest resolved: ${step.name} (awaits ${step.actor})`);
 	const stepDef = stepDefOf(step);
-	if (stepDef.mode !== void 0 && def.modes[stepDef.mode] === void 0) return yield* fail$7(/* @__PURE__ */ new Error(`gtd config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`));
+	if (stepDef.mode !== void 0 && def.modes[stepDef.mode] === void 0) return yield* fail$7(/* @__PURE__ */ new Error(`gtd: config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`));
 	const changes = ref === void 0 ? (yield* pendingChanges(git, stepDef.approve === true)).map((e) => ({
 		status: normalizeStatus(e.status),
 		path: e.path
@@ -41054,7 +41054,7 @@ const emitScripts = (required = [], optional = []) => ({
 	optional: assembleScript(optional)
 });
 /** Exported so `src/twins/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
-const DID_NOT_RUN_COMMENT = "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn";
+const DID_NOT_RUN_COMMENT = "# gtd emitted this and did NOT run it — run it with `sh` to apply it";
 const PRESENTATION_ONLY_COMMENT = "# presentation only — safe to skip";
 const PRESENTATION_FAILURE_WARNING = "printf 'gtd: presentation-only follow-up failed — continuing\\n' >&2";
 /**
@@ -42235,7 +42235,10 @@ const runLandCommand = (opts, json, out) => gen(function* () {
 const runStartCommand = (actor, workflow, varOverrides, out, commandLabel) => gen(function* () {
 	const config = yield* (yield* ConfigService).load;
 	const resolved = config.workflowNamed(workflow);
-	if (resolved === void 0) return yield* fail$7(new GtdUsageError(`gtd --workflow: unknown workflow "${workflow}" — startable: ${config.workflowNames.join(", ")}`));
+	if (resolved === void 0) {
+		const startable = config.workflowNames.length > 0 ? `startable: ${config.workflowNames.join(", ")}` : "this config exports no workflow besides its default, which an ordinary start runs";
+		return yield* fail$7(new GtdUsageError(`gtd --workflow: unknown workflow "${workflow}" — ${startable}`));
+	}
 	const rest = yield* restAt(void 0, varOverrides);
 	const started = yield* startRefusal(rest, resolved, varOverrides);
 	const plan = yield* planStart({
@@ -42249,9 +42252,24 @@ const runStartCommand = (actor, workflow, varOverrides, out, commandLabel) => ge
 		config: rest.config
 	});
 	if (plan.kind === "refusal") return yield* fail$7(new Error(plan.message));
-	out.write(landingScript(ScriptSurface.render(plan.steps)));
+	out.write(listingCommitted(landingScript(ScriptSurface.render(plan.steps)), rest.changes));
 });
+/**
+* A start commits the whole tree (`git add -A`), so its script says up front
+* which paths that is. Comment lines only: control characters are masked so a
+* path can never end the comment and become a command.
+*/
+const listingCommitted = (script, changes) => {
+	if (changes.length === 0) return script;
+	const listing = ["# commits every change in the working tree (git add -A):", ...changes.map((change) => `#   ${change.status} ${change.path.replace(/\p{Cc}/gu, "?")}`)].join("\n");
+	const at = script.indexOf("\n\n");
+	return at === -1 ? script : `${script.slice(0, at)}\n\n${listing}${script.slice(at)}`;
+};
 const doorSynopsis = (name, door) => [name, ...(door.args ?? []).map((arg) => arg.optional === true ? `[${arg.name}]` : `<${arg.name}>`)].join(" ");
+const noSuchDoor = (name, doors) => {
+	const listing = doors.size > 0 ? `doors: ${[...doors].map(([n, d]) => doorSynopsis(n, d)).join(", ")}` : "this config has no doors";
+	return new GtdUsageError(name === void 0 ? `gtd door: missing door name — ${listing}` : `gtd door: unknown door "${name}" — ${listing}`);
+};
 /**
 * `gtd door <name> [args…]`: `gtd --workflow` with the door's workflow and the
 * process settings its `vars` derive from the positional args. A wrong name or
@@ -42259,11 +42277,8 @@ const doorSynopsis = (name, door) => [name, ...(door.args ?? []).map((arg) => ar
 */
 const runDoorCommand = (name, args, out) => gen(function* () {
 	const config = yield* (yield* ConfigService).load;
-	const door = config.doors.get(name);
-	if (door === void 0) {
-		const known = [...config.doors];
-		return yield* fail$7(new GtdUsageError(`gtd door: unknown door "${name}" — doors: ${known.map(([n, d]) => doorSynopsis(n, d)).join(", ")}`));
-	}
+	const door = name === void 0 ? void 0 : config.doors.get(name);
+	if (name === void 0 || door === void 0) return yield* fail$7(noSuchDoor(name, config.doors));
 	const declared = door.args ?? [];
 	const required = declared.filter((arg) => arg.optional !== true).length;
 	if (args.length < required || args.length > declared.length) return yield* fail$7(new GtdUsageError(`gtd door ${name}: ${args.length < required ? "missing" : "too many"} arguments — usage: gtd door ${doorSynopsis(name, door)}`));
@@ -42281,6 +42296,7 @@ const runDoorCommand = (name, args, out) => gen(function* () {
 const runDoorsCommand = (json, out) => gen(function* () {
 	const doors = [...(yield* (yield* ConfigService).load).doors];
 	if (json.kind === "off") {
+		if (doors.length === 0) yield* (yield* Narrator).warn("gtd doors: this config has no doors — a workflow factory's `doors` option or the config's `doors` export adds one");
 		out.write(doors.map(([n, d]) => `${doorSynopsis(n, d)} → ${d.workflow}\n`).join(""));
 		return;
 	}
@@ -42428,6 +42444,13 @@ const runNextCommand = (json, out) => gen(function* () {
 	else if (json.kind === "select") yield* writeSelection(out, fields, json.path);
 	else {
 		const validateCommand = emitsValidatablePrompt(rendered) ? selfValidateCommand(rest.def, rest.state, rendered.mode, rendered.file) : void 0;
+		if (DEMAND_BRIEFING[fields.kind].suppressHeader) {
+			const shown = renderBeatPlain({
+				...fields,
+				kind: "message"
+			});
+			yield* narrator.warn(shown.slice(0, shown.indexOf("\n\n")));
+		}
 		out.write(renderBeatPlain(fields, validateCommand));
 	}
 });
@@ -42583,12 +42606,13 @@ const runUiCliCommand = (command, out) => gen(function* () {
 * cwds (e.g. macOS /tmp → /private/tmp) match.
 */
 const assertRunningFromRepoRoot = (git, host) => gen(function* () {
-	const topLevel = yield* git.topLevel();
-	if ((yield* host.realPath(topLevel)) !== (yield* host.realPath(host.root))) return yield* fail$7(/* @__PURE__ */ new Error(`gtd must be run from the repository root (${topLevel}); the current directory is ${host.root}`));
+	const topLevel = yield* git.topLevel().pipe(mapError$1((e) => /not a git repository/.test(e.message) ? /* @__PURE__ */ new Error("gtd: not a git repository — run gtd inside one (`git init` makes one)") : e));
+	if ((yield* host.realPath(topLevel)) !== (yield* host.realPath(host.root))) return yield* fail$7(/* @__PURE__ */ new Error(`gtd: run gtd from the repository root — cd ${shellWord(topLevel)} (the current directory is ${host.root})`));
 });
+const shellWord = (path) => /^[\w@%+=:,./-]+$/.test(path) ? path : `'${path.replace(/'/g, "'\\''")}'`;
 /** A command that derives workflow state needs at least one commit too — a commitless repository has no HEAD to resolve a `Rest` at. */
 const assertRepositoryHasCommits = (git) => gen(function* () {
-	if (!(yield* git.hasCommits())) return yield* fail$7(/* @__PURE__ */ new Error("gtd requires a repository with at least one commit — make an initial commit, then run gtd again"));
+	if (!(yield* git.hasCommits())) return yield* fail$7(/* @__PURE__ */ new Error("gtd: the repository has no commits yet — make an initial commit, then run gtd again"));
 });
 /**
 * What a command kind needs before it may run. Defined here, not in
@@ -42675,6 +42699,57 @@ const runCommand = (command, json, out) => {
 	});
 };
 //#endregion
+//#region src/cli/Help.ts
+const HELP_WIDTH = 80;
+/**
+* Word-wraps prose to `width` columns, every line prefixed by `indent`.
+* Paragraphs are separated by a blank line; a paragraph whose lines start
+* with two spaces is an example and is kept verbatim (indented, not wrapped).
+*/
+const wrapParagraph = (paragraph, width, indent) => {
+	const lines = [];
+	let line = "";
+	for (const word of paragraph.match(/\S*`[^`]*`\S*|\S+/g) ?? []) if (line !== "" && indent.length + line.length + 1 + word.length > width) {
+		lines.push(indent + line);
+		line = word;
+	} else line = line === "" ? word : `${line} ${word}`;
+	if (line !== "") lines.push(indent + line);
+	return lines;
+};
+const wrap = (text, width = HELP_WIDTH, indent = "") => text.split("\n\n").flatMap((paragraph, i) => [...i > 0 ? [""] : [], ...paragraph.startsWith("  ") ? paragraph.split("\n").map((l) => indent + l) : wrapParagraph(paragraph, width, indent)]);
+/** `term` and `description` side by side, the description wrapped into the column after `column`; a term too wide for it gets a line of its own. */
+const definition = (term, description, column) => {
+	const cell = `  ${term}`;
+	const body = wrap(description, HELP_WIDTH, " ".repeat(column));
+	if (cell.length + 1 >= column) return [cell, ...body];
+	const [first = "", ...rest] = body;
+	return [cell.padEnd(column) + first.trimStart(), ...rest];
+};
+/** Optimal-string-alignment distance: Levenshtein plus adjacent transpositions, so `nxet` is one edit from `next`. */
+const distance = (a, b) => {
+	const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => i === 0 ? j : j === 0 ? i : 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;
+		let best = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+		if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) best = Math.min(best, d[i - 2][j - 2] + 1);
+		d[i][j] = best;
+	}
+	return d[a.length][b.length];
+};
+/** The candidate closest to `word`, when it is a plausible typo of it: at most one edit per three characters, and at least one. */
+const closest = (word, candidates) => {
+	const limit = Math.max(1, Math.floor(word.length / 3));
+	let best;
+	for (const name of candidates) {
+		const d = distance(word, name);
+		if (d <= limit && (best === void 0 || d < best.d)) best = {
+			name,
+			d
+		};
+	}
+	return best?.name;
+};
+//#endregion
 //#region src/cli/Cli.ts
 init_esm();
 const nonNegativeNumber = (raw, flag) => {
@@ -42703,20 +42778,8 @@ const FLAGS = [
 		decode: ([raw]) => right(raw ?? ""),
 		scopeError: "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show`/`gtd history metrics`/`gtd history judges`/`gtd strays` — every other command prints plain text; see `gtd install` for the driver protocol briefing",
 		valueHint: "<path>",
-		help: [
-			"(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors/gtd history",
-			"list/gtd history show/gtd history metrics/gtd history judges/gtd strays only) output structured JSON. Bare --json prints the whole document;",
-			"--json=<path> (a dotted key path into that document, e.g.",
-			"kind, content, session.id) prints just that value: a",
-			"scalar raw and unquoted, a boolean as true/false, a list",
-			"one JSON entry per line — a numeric segment (e.g.",
-			"skills.0) indexes into one entry of a list field instead.",
-			"An absent optional field prints nothing and exits 0 —",
-			"including when an earlier segment of <path> is itself",
-			"absent/null (e.g. session.id at a non-prompt rest), which",
-			"never counts as unknown; an unknown path is a usage error",
-			"(exit 2)."
-		]
+		help: "Print the JSON document, or with --json=<path> one field of it (e.g. --json=kind): a scalar bare, a list one entry per line, nothing for an absent field",
+		helpFor: { strays: "Print one entry of the array (--json=0), nothing past its end" }
 	},
 	{
 		name: "--port",
@@ -42729,11 +42792,7 @@ const FLAGS = [
 		},
 		scopeError: "gtd: --port is only valid for `gtd ui`",
 		valueHint: "<n>",
-		help: [
-			"(gtd ui only) the tailscale serve port (default: the first",
-			"free of 8443, 10000, 443), or the bind port when --host",
-			"opts out of serve (default: a free port)"
-		]
+		help: "The tailscale serve port (default: the first free of 8443, 10000, 443), or with --host the port to bind (default: any free one)"
 	},
 	{
 		name: "--host",
@@ -42743,11 +42802,7 @@ const FLAGS = [
 		decode: ([raw]) => raw === void 0 || raw.trim() === "" || /[\r\n]/.test(raw) ? left("gtd: --host must be a non-empty, single-line value") : right(raw),
 		scopeError: "gtd: --host is only valid for `gtd ui`",
 		valueHint: "<addr>",
-		help: [
-			"(gtd ui only) opt out of the default tailscale serve front",
-			"door and bind this address directly instead, showing it in",
-			"the printed URL"
-		]
+		help: "Bind this address directly instead of publishing through tailscale serve"
 	},
 	{
 		name: "--self-signed",
@@ -42757,7 +42812,7 @@ const FLAGS = [
 		decode: () => right(true),
 		scopeError: "gtd: --self-signed is only valid for `gtd ui`",
 		valueHint: "",
-		help: ["(gtd ui only) generate a throwaway self-signed TLS", "certificate instead of the configured ui.cert/ui.key"]
+		help: "Bind directly with a throwaway self-signed certificate instead of the configured ui.cert/ui.key"
 	},
 	{
 		name: "--dev",
@@ -42767,7 +42822,7 @@ const FLAGS = [
 		decode: () => right(true),
 		scopeError: "gtd: --dev is only valid for `gtd ui`",
 		valueHint: "",
-		help: ["(gtd ui only) run against local development sources", "instead of the packaged build"]
+		help: "Serve local development sources instead of the packaged build"
 	},
 	{
 		name: "--provider",
@@ -42777,11 +42832,7 @@ const FLAGS = [
 		decode: ([raw]) => raw === "fixed" || raw === "jev" || raw === "llm" ? right(raw) : left(`gtd: --provider must be one of fixed, jev, llm — got "${raw ?? ""}"`),
 		scopeError: "gtd: --provider is only valid for `gtd judge run`",
 		valueHint: "<name>",
-		help: [
-			"(gtd judge run only) the answerer: fixed | jev | llm;",
-			"omitted: GTD_JUDGE_PROVIDER, then judge.json, then jev",
-			"when TYPESAFE_API_KEY is set, else llm"
-		]
+		help: "The answerer: fixed, jev or llm (default: $GTD_JUDGE_PROVIDER, then ~/.config/gtd/judge.json, then jev when $TYPESAFE_API_KEY is set, else llm)"
 	},
 	{
 		name: "--answers",
@@ -42791,11 +42842,7 @@ const FLAGS = [
 		decode: ([raw]) => raw === void 0 || raw === "" ? left("gtd: --answers must be a non-empty path") : right(raw),
 		scopeError: "gtd: --answers is only valid for `gtd judge run`",
 		valueHint: "<path>",
-		help: [
-			"(gtd judge run --provider fixed only) a JSON verdict array",
-			"[{ id, answer, p }]; else the GTD_JUDGE_ANSWERS env var",
-			"(inline JSON) is read"
-		]
+		help: "With --provider fixed: a JSON verdict file [{ id, answer, p }] (default: $GTD_JUDGE_ANSWERS, inline JSON)"
 	},
 	{
 		name: "--cost",
@@ -42805,7 +42852,7 @@ const FLAGS = [
 		decode: ([raw]) => nonNegativeNumber(raw ?? "", "--cost"),
 		scopeError: "gtd: --cost is only valid for `gtd land` — a start is not a metered agent turn",
 		valueHint: "<n>",
-		help: ["(gtd land only) record the invocation's token cost"]
+		help: "Record the token cost of the invocation that just finished on the commit"
 	},
 	{
 		name: "--model",
@@ -42815,11 +42862,11 @@ const FLAGS = [
 		decode: ([raw]) => raw === void 0 || raw.trim() === "" || /[\r\n]/.test(raw) ? left("gtd: --model must be a non-empty, single-line value") : right(raw),
 		scopeError: "gtd: --model is only valid for `gtd land` (with --cost) or `gtd judge run`",
 		valueHint: "<name>",
-		help: [
-			"(gtd land, with --cost) tag that cost's model",
-			"(gtd judge run, llm answerer) the claude model; omitted:",
-			"GTD_JUDGE_MODEL, then judge.json, then sonnet"
-		]
+		help: "",
+		helpFor: {
+			land: "With --cost: the model that cost was spent on",
+			judgeRun: "The claude model the llm answerer uses (default: $GTD_JUDGE_MODEL, then judge.json, then sonnet)"
+		}
 	},
 	{
 		name: "--workflow",
@@ -42829,7 +42876,7 @@ const FLAGS = [
 		decode: ([raw]) => right(raw ?? ""),
 		scopeError: "gtd: --workflow is only valid with no other command — use the bare `gtd --workflow <name>` form; landing and starting are different verbs",
 		valueHint: "<name>",
-		help: ["(with no command at all) start a brand new process on", "the named workflow — authenticated as human"]
+		help: "Start a new process on the named workflow"
 	},
 	{
 		name: "--var",
@@ -42860,14 +42907,11 @@ const FLAGS = [
 		},
 		scopeError: "gtd: --var requires --workflow (or `gtd history judges`)",
 		valueHint: "<name>=<value>",
-		help: [
-			"(with --workflow; repeatable) pin a process setting for the",
-			"new process; the name must already be declared by the",
-			"workflow's defaults (environment settings are not",
-			"pinnable). (gtd history judges) re-decide past verdicts",
-			"under this threshold: judgeIdenticalMinP or",
-			"qualityTriageMinP"
-		]
+		help: "",
+		helpFor: {
+			start: "Pin one of the workflow's declared settings for the new process (repeatable)",
+			historyJudges: "Re-decide every past verdict under this threshold: judgeIdenticalMinP or qualityTriageMinP (repeatable)"
+		}
 	},
 	{
 		name: "--jsonl",
@@ -42877,7 +42921,7 @@ const FLAGS = [
 		decode: () => right(true),
 		scopeError: "gtd: --jsonl is only valid for `gtd history judges`",
 		valueHint: "",
-		help: ["(gtd history judges only) print one JSON line per verdict", "instead of the report"],
+		help: "Print one JSON line per verdict instead of the report",
 		conflicts: ["--json", "--var"]
 	},
 	{
@@ -42888,12 +42932,7 @@ const FLAGS = [
 		decode: () => right(true),
 		scopeError: "gtd: --open-questions is only valid for `gtd check`",
 		valueHint: "",
-		help: [
-			"(gtd check only) ignore <mode>'s structural findings and",
-			"instead run the qa open-questions predicate over <file>,",
-			"printing each unanswered question one per line and exiting",
-			"non-zero when any remain"
-		]
+		help: "Instead of <mode>'s findings, list the unanswered questions in <file>; exits 1 when any remain"
 	},
 	{
 		name: "--open-threads",
@@ -42903,15 +42942,7 @@ const FLAGS = [
 		decode: () => right(true),
 		scopeError: "gtd: --open-threads is only valid for `gtd check`",
 		valueHint: "",
-		help: [
-			"(gtd check only) ignore <mode>'s structural findings and",
-			"instead list every open thread (a footnote whose last",
-			"entry is the agent's) over <file>, one per line with its",
-			"first H entry, exiting non-zero when any are open. With no",
-			"<mode>/<file>, lists code-comment threads in the files the",
-			"current process changed (read from its diff base, unlike",
-			"the rest of `gtd check`)"
-		]
+		help: "Instead of <mode>'s findings, list the open threads in <file>; exits 1 when any are open. Alone, lists the open code-comment threads in the files the current process changed"
 	},
 	{
 		name: "--verbose",
@@ -42921,11 +42952,7 @@ const FLAGS = [
 		decode: () => right(true),
 		scopeError: "gtd: --verbose is valid for every command — this error is unreachable",
 		valueHint: "",
-		help: [
-			"enable stderr narration for this invocation: which rest",
-			"resolved and how config resolved across layers. Aliased",
-			"to -v"
-		]
+		help: "Narrate on stderr what gtd resolved and where its config came from"
 	}
 ];
 /**
@@ -42944,203 +42971,39 @@ const flagByToken = (token) => {
 	return FLAGS.find((f) => f.name === bareName);
 };
 const COMMAND_ROWS = [
-	{
-		token: "land",
-		kind: "land",
-		arity: "none",
-		details: [
-			"Land whatever the tree now shows at the currently resolved",
-			"rest — a human capture, an agent/check turn, or an empty",
-			"attempt (a fruitless prompt turn). Pass",
-			"--cost=<n> (optionally --model=<name>) to record the",
-			"just-finished invocation's token cost and model on the",
-			"turn commit (summed into it.processCost/",
-			"processCostByModel). Plain (the default) prints one",
-			"human-readable sentence naming the commit subject (or a",
-			"no-op note) plus a pointer to `gtd land --json=script | sh`",
-			"to get the landing script — never the script itself.",
-			"--json emits script (the actual POSIX sh",
-			"a driver runs) alongside settled, idle, state (the",
-			"post-land target), subject, cost and model. Exits 0 on",
-			"success, 1 on any refusal — see the Exit codes section",
-			"below"
-		]
-	},
-	{
-		token: "abandon",
-		kind: "abandon",
-		arity: "none",
-		details: [
-			"End the process currently underway without completing it:",
-			"rewind HEAD to the commit the process started from,",
-			"keeping everything it produced as uncommitted changes. A",
-			"no-op when no process is underway"
-		]
-	},
-	{
-		token: "restore",
-		kind: "restore",
-		arity: "none",
-		details: [
-			"Hard-reset HEAD back to the tip retained by the last",
-			"abandon (refs/worktree/gtd/history), bringing back an",
-			"abandoned process's turns. Refuses on a dirty working",
-			"tree, when there is no retained history, or when HEAD has",
-			"advanced past the retained tip with commits that would be",
-			"lost"
-		]
-	},
 	{
 		token: "next",
 		kind: "next",
 		arity: "none",
-		details: [
-			"Print the resolved rest's beat (no mutation, safe to",
-			"poll), in one of three encodings. Plain (the default): a",
-			"status summary, a blank line, then the step verbatim — at a",
-			"script/capture rest an instruction line ('Run this",
-			"script:' / 'The edit is already made — run `gtd land` to",
-			"land it.') precedes the status summary; at a prompt rest",
-			"it's the bare step (plus the self-validation instruction",
-			"when applicable) with no header at all, since those bytes",
-			"are the agent's own input. --json emits the one structured",
-			"surface gtd has: kind (capture|message|script|prompt|",
-			"stalled) selects what a driver does, content is what it",
-			"runs or shows, idle marks the workflow's initial state with",
-			"a clean tree, plus the prompt session, model, validate",
-			"script, log path, changes, next and the resting state's own",
-			"fields. --json=<path> (a dotted key path into that same",
-			"document, e.g. kind, content, session.id) prints just that",
-			"value instead of the whole document — see --json's own help",
-			"above. Exits 0 — see the Exit codes section below"
-		]
-	},
-	{
-		token: "validate",
-		kind: "validate",
-		arity: "none",
-		details: [
-			"Print the script that formats (when declared) then",
-			"validates the resolved rest's steering file, using its",
-			"mode's commands (its file:/mode:), instead of running it —",
-			"a driver runs the script and reads the findings from its",
-			"own exit code/output. Always exits 0; prints \"nothing to",
-			"validate\" when the resolved rest declares nothing to run.",
-			"On a non-zero validate exit the emitted script prints a",
-			"ready-to-send fix prompt (instruction + findings) and",
-			"exits with the validator's own code"
-		]
-	},
-	{
-		token: "lsp",
-		kind: "lsp",
-		arity: "none",
-		details: ["Start the LSP server for .gtd/ steering files (stdio)"]
-	},
-	{
-		token: "ui",
-		kind: "ui",
-		arity: "none",
-		details: [
-			"Expose gtd's web/phone client for THIS worktree — the",
-			"invoking directory, never a configured list of roots — and",
-			"refuses outside a repository like every other state command.",
-			"By default, publishes through `tailscale serve` (reachable",
-			"from anywhere on the tailnet, including over a DERP relay)",
-			"with tailscaled terminating TLS, walking 8443, then 10000,",
-			"then 443 until one publishes; falls back to binding a local",
-			"HTTPS server directly, never refusing, when none of the",
-			"three works. --host <addr> opts out of serve and binds that",
-			"address directly instead; --port <n> overrides the serve",
-			"port (default: the first free of 8443, 10000, 443), or the",
-			"bind port when --host is given (default: a free port);",
-			"--self-signed also opts out of serve, generating a",
-			"throwaway TLS certificate instead of the configured",
-			"ui.cert/ui.key; --dev runs against local development sources",
-			"instead of the packaged build"
-		]
-	},
-	{
-		token: "check",
-		kind: "check",
-		arity: { names: ["mode", "file"] },
-		details: [
-			"Read <file> and run the built-in steering format named",
-			"<mode> (see `gtd validate`'s modes: qa, review, findings)",
-			"over its contents, printing each finding one per line and",
-			"exiting non-zero when there are any. Resolves no workflow",
-			"state and reads no config — standalone, runnable from any",
-			"directory with <mode>/<file> given explicitly. This is what a",
-			"workflow's emitted validation script invokes as a leaf step.",
-			"--open-questions runs the qa unanswered-questions predicate",
-			"instead (see --help); --open-threads lists open threads.",
-			"`gtd check --open-threads` alone lists open code-comment",
-			"threads (`// H: ...`) in the files the process changed;",
-			"it prints nothing when no process is underway."
-		]
-	},
-	{
-		token: "uncheck",
-		kind: "uncheck",
-		arity: { name: "file" },
-		details: [
-			"Read <file> and reset every review-mode `- [x]`/`- [X]`",
-			"file-pointer box back to `- [ ]`, writing the result back",
-			"only when the bytes actually changed. Resolves no workflow",
-			"state and reads no config — standalone, runnable from any",
-			"directory with <file> given explicitly. This is what the",
-			"landing script runs ahead of the commit at the human review",
-			"gate, so no tick ever reaches a commit. Takes no <mode> —",
-			"it means review-mode file pointers and nothing else, never",
-			"qa-mode's answered-question boxes. A missing file writes",
-			"nothing and exits 0"
-		]
-	},
-	{
-		token: "install",
-		kind: "install",
-		arity: "none",
-		details: [
-			"Print a complete, self-contained briefing that teaches an",
-			"agent (or a human) to build a gtd driver in any shell or",
-			"runtime — the self-serve version of",
-			"https://github.com/pmelab/gtd/blob/main/docs/driver.md's",
-			"'Writing your own driver', and how to get a workflow: gtd",
-			"ships none. It writes nothing."
-		]
+		group: "Core loop",
+		summary: "Print what should happen next",
+		details: `Print what should happen next in the process, changing nothing — safe to poll.
+
+Plain output is for a person: a status header (the step, who acts, the pending changes, where landing them would go), then the step's content. At a prompt the header goes to stderr, so stdout is exactly the agent's input.
+
+--json prints one JSON document for a driver: its kind (capture, message, script, prompt or stalled) says what to do, its content what to run or show. --json=<path> prints one field of it; an unknown path is a usage error (exit 2).`
 	},
 	{
-		token: "summary",
-		kind: "summary",
+		token: "land",
+		kind: "land",
 		arity: "none",
-		details: [
-			"Print the prompt for an agent to write the process HEAD",
-			"closes or sits inside its own closing message — the entry",
-			"commit, each human-authored commit (a review round, an",
-			"answered question gate), the diff range to inspect, and",
-			"it.processCost/processCostByModel. Writes nothing: no git,",
-			"no state transition, no file, no session identity — the",
-			"driver pipes the output to a cold agent and does what it",
-			"wants with the result (a squash, an amend, a PR body).",
-			"Refuses (exit 1) when the workflow declares no summary:",
-			"template, or when the resolved run has no commits to name —",
-			"it is runnable any time before the next thing lands on the",
-			"branch"
-		]
+		group: "Core loop",
+		summary: "Record what the tree now shows",
+		details: `Record what the working tree now shows at the current step: a person's edit, an agent's or a check's turn, or an empty attempt when an agent changed nothing.
+
+gtd writes nothing itself. Plain output names the commit it would make; --json=script prints the script that makes it:
+
+  s=$(gtd land --json=script) && sh -c "$s"
+
+--json prints the whole document: the script, the step the process lands at, the commit subject, and the recorded cost and model. A refusal exits 1.`
 	},
 	{
-		token: "base",
-		kind: "base",
+		token: "validate",
+		kind: "validate",
 		arity: "none",
-		details: [
-			"Print the review anchor hash — the diff base an external",
-			"tool (a diff, a PR tool, another agent) should point at —",
-			"bare, newline-terminated, and nothing else. Writes nothing:",
-			"no git, no state transition, no session identity. Before",
-			"the first review round it's the process's diff base;",
-			"afterward it's the most-recent review round's boundary.",
-			"Refuses (exit 1) when no process is underway."
-		]
+		group: "Core loop",
+		summary: "Print the script that checks the steering file",
+		details: `Print the script that formats, then validates, the current step's steering file with its mode's commands. gtd runs nothing: the script's exit code is the verdict, and on a failure it prints a ready-to-send fix prompt. Prints "nothing to validate" when the step declares no file to check.`
 	},
 	{
 		token: "door",
@@ -43149,73 +43012,55 @@ const COMMAND_ROWS = [
 			name: "name",
 			variadic: "args"
 		},
-		details: [
-			"Start a process through a named shortcut, mapping the",
-			"positional args to that workflow's process settings — the",
-			"same start `gtd --workflow` makes, printed the same way.",
-			"Each workflow the config exports brings its own doors (gtd's",
-			"`fix`, `review [base]`, `rollout <flag>` and",
-			"`cleanup <flag>`), plus the config's `doors` export. An",
-			"unknown door, or too few or too many args, is a usage error",
-			"(exit 2) naming the doors or the door's synopsis"
-		]
+		group: "Start and stop",
+		summary: "Start a process through a named shortcut",
+		details: `Start a process through a door: a named shortcut to a workflow that maps its positional args to the workflow's settings. It prints the same start script \`gtd --workflow\` does. Each workflow the config exports brings its own doors, plus the config's \`doors\` export.
+
+With no <name>, an unknown one, or the wrong number of args, it lists the doors and exits 2.`
 	},
 	{
 		token: "doors",
 		kind: "doors",
 		arity: "none",
-		details: [
-			"List every door, sorted: one `name [args] → workflow` line",
-			"each. --json prints one JSON array of { name, workflow,",
-			"args: [{ name, optional }] } instead; --json=<path> reads one",
-			"value off it. Writes nothing"
-		]
+		group: "Start and stop",
+		summary: "List the doors",
+		details: `List every door, sorted: one \`name [args] → workflow\` line each. --json prints a JSON array of { name, workflow, args: [{ name, optional }] }. Writes nothing.`
 	},
 	{
-		token: "judge",
-		kind: "judge",
+		token: "abandon",
+		kind: "abandon",
 		arity: "none",
-		details: [
-			"Print the resolved rest's pending judgment — the prepared",
-			"state, its typed questions, and their criteria — the same",
-			"judge field `gtd next --json` already carries. Read-only:",
-			"resolves no session, writes nothing. Refuses (exit 1) when",
-			"the resolved rest declares no judge:"
-		]
+		group: "Start and stop",
+		summary: "Stop the process, keeping its changes",
+		details: `Stop the process underway without finishing it. The printed script moves HEAD back to the commit the process started from and keeps everything it produced as uncommitted changes; \`gtd restore\` undoes it. With no process underway the script does nothing.
+
+  s=$(gtd abandon) && sh -c "$s"`
 	},
 	{
-		token: "judge answer",
-		kind: "judgeAnswer",
+		token: "restore",
+		kind: "restore",
 		arity: "none",
-		details: [
-			"Read a verdict off stdin — one { id, answer, p } entry per",
-			"question the pending judgment declared — and decode it",
-			"against an Effect Schema built from those same question",
-			"ids. Refuses (exit 1) when the resolved rest declares no",
-			"judge:. Exits 2 (a usage error, like an unknown --json",
-			"selector) when stdin isn't valid JSON or the verdict",
-			"doesn't decode against the pending question ids."
-		]
+		group: "Start and stop",
+		summary: "Bring back the last abandoned process",
+		details: `Bring back the process the last \`gtd abandon\` stopped: the printed script resets HEAD to that process's last commit. Refuses on a dirty working tree, when nothing was abandoned, or when commits made since would be lost.`
 	},
 	{
-		token: "judge run",
-		kind: "judgeRun",
+		token: "summary",
+		kind: "summary",
 		arity: "none",
-		details: [
-			"Answer a judgment: read the `gtd judge --json` document off",
-			"stdin, write a verdict [{ id, answer, p }] on stdout — what",
-			"`gtd judge answer` decodes. --provider fixed answers from",
-			"--answers <path> or GTD_JUDGE_ANSWERS; questions the file",
-			"does not cover are left out. --provider jev asks TypeSafe",
-			"(TYPESAFE_API_KEY). --provider llm asks the `claude` CLI",
-			"on PATH (Claude Code only), model sonnet unless --model.",
-			"No --provider: GTD_JUDGE_PROVIDER, then ~/.config/gtd/",
-			"judge.json, else jev when TYPESAFE_API_KEY is set and no",
-			"model is given, else llm; --model likewise falls back to",
-			"GTD_JUDGE_MODEL, then the file's model. Needs no",
-			"repository. jev and llm exit 1 when they cannot answer",
-			"every question, with nothing on stdout"
-		]
+		group: "Inspect",
+		summary: "Print the prompt for the closing message",
+		details: `Print the prompt for an agent to write the closing message of the process HEAD closes or sits inside: its first commit, each commit a person made, the diff range to read, and its cost. Writes nothing — what to do with the answer (a squash message, a PR body) is the driver's call.
+
+Refuses when the workflow declares no summary template, or when the process has no commits.`
+	},
+	{
+		token: "base",
+		kind: "base",
+		arity: "none",
+		group: "Inspect",
+		summary: "Print the commit a review diff starts from",
+		details: `Print the commit a review diff should start from, bare: the process's diff base before the first review round, the latest round's boundary after it. Writes nothing; refuses when no process is underway.`
 	},
 	{
 		token: "strays",
@@ -43224,45 +43069,27 @@ const COMMAND_ROWS = [
 			name: "range",
 			variadic: "glob"
 		},
-		details: [
-			"List the files <range> (<base>..<tip>, an empty side is HEAD)",
-			"touched in its committed net diff that match none of the",
-			"globs. Anchored at the repo root: * stays within one path",
-			"segment, ** crosses them, everything else is literal — quote",
-			"globs in the shell. stdout: a sorted JSON array, [] when",
-			"clean; stderr: a summary, plus one stray: line per path with",
-			"--verbose. --json=<n> picks one entry, nothing past the end;",
-			"a symlink is a path like any other, never followed; a",
-			"submodule counts as its path, whatever diff.ignoreSubmodules",
-			"or .gitmodules ignore say. Runs in any git repository, no",
-			"process needed. Exits 10 when",
-			"strays were found, 1 on an unknown revision, 2 on a bad range"
-		]
+		group: "Inspect",
+		summary: "List changed files outside the globs",
+		details: `List the files changed in <range> (<base>..<tip>, an empty side is HEAD) that match none of the globs. Globs are anchored at the repository root: * stays within one path segment, ** crosses them, everything else is literal — quote them in the shell.
+
+Prints a sorted JSON array ([] when clean) and a summary on stderr; --verbose adds one stray: line per path. Runs in any git repository, no process needed. Exits 10 when strays were found, 1 on an unknown revision, 2 on a bad range.`
 	},
 	{
 		token: "history list",
 		kind: "historyList",
 		arity: "none",
-		details: [
-			"List the finished processes kept behind refs/gtd/history/*,",
-			"newest first: entry, branch, tip, date and subject per line.",
-			"--json prints one array of { ref, entry, branch, tip, date,",
-			"subject }. Writes nothing and never replays; with no refs it",
-			"hints at `gtd history fetch | sh` and still exits 0"
-		]
+		group: "Inspect",
+		summary: "List finished processes",
+		details: `List the finished processes this clone keeps, newest first: entry, branch, tip, date and subject. --json prints an array of { ref, entry, branch, tip, date, subject }. Writes nothing; with none kept it suggests \`gtd history fetch\`.`
 	},
 	{
 		token: "history show",
 		kind: "historyShow",
 		arity: { name: "ref" },
-		details: [
-			"Replay one kept process under today's config and print its",
-			"steps, judge verdicts and approvals. <ref> is a full ref, an",
-			"entry hash (or unique prefix) or a branch name. Refuses",
-			"(exit 1) when a config file differs from its content at the",
-			"ref's tip. A version mismatch only warns on stderr. --json",
-			"prints the trail as one document; writes nothing"
-		]
+		group: "Inspect",
+		summary: "Replay one finished process",
+		details: `Replay one finished process under today's config and print its steps, judge verdicts and approvals. <ref> is a full ref, an entry hash or a unique prefix of one, or a branch name. Refuses when a config file changed since; a different gtd version only warns. --json prints the trail as one document. Writes nothing.`
 	},
 	{
 		token: "history metrics",
@@ -43271,18 +43098,9 @@ const COMMAND_ROWS = [
 			name: "ref",
 			many: true
 		},
-		details: [
-			"Report how the kept processes went: builds whose naive pass",
-			"landed or was rebuilt (the refactor-first rate), Gtd-Cost by",
-			"model and phase with the double work of a rebuild, quality-lap",
-			"findings per lens, and red checks that passed on their",
-			"re-check — per process and in total. Each <ref>",
-			"is read as by history show, but a branch name means every",
-			"process kept from it; none means every ref.",
-			"Reads commit subjects and trailers, never replays, so a",
-			"changed config is no refusal. --json prints { processes, total",
-			"} as one document; writes nothing"
-		]
+		group: "Inspect",
+		summary: "Report cost and rework of finished processes",
+		details: `Report how finished processes went: builds that landed first time or were rebuilt, cost by model and phase, review findings per lens, and red checks that passed when re-run — per process and in total. <ref> is read as by \`gtd history show\`, but a branch name means every process kept from it; no <ref> means all of them. Never replays, so a changed config is no reason to refuse. --json prints { processes, total }. Writes nothing.`
 	},
 	{
 		token: "history judges",
@@ -43291,18 +43109,9 @@ const COMMAND_ROWS = [
 			name: "ref",
 			many: true
 		},
-		details: [
-			"Calibrate the judges of the kept processes from their",
-			"recorded Gtd-Judge verdicts: per judge (retry, triage, clear)",
-			"and p bucket, how many verdicts later events overturned.",
-			"--var <name>=<value> re-decides every past verdict under",
-			"another threshold and prints what would have changed;",
-			"--jsonl prints one { process, judge, commit, step, question,",
-			"state, answer, p, outcome } line per verdict instead. <ref>",
-			"is read as by history metrics. Never replays and asks no",
-			"model. --json prints { processes, total, whatIf }; writes",
-			"nothing"
-		]
+		group: "Inspect",
+		summary: "Calibrate the judges of finished processes",
+		details: `Calibrate the judges of finished processes from their recorded verdicts: per judge and confidence bucket, how many verdicts later events overturned. <ref> is read as by \`gtd history metrics\`. Never replays and asks no model. --json prints { processes, total, whatIf }. Writes nothing.`
 	},
 	{
 		token: "history fetch",
@@ -43311,69 +43120,205 @@ const COMMAND_ROWS = [
 			name: "remote",
 			optional: true
 		},
-		details: [
-			"Print a script that fetches every refs/gtd/history/* from",
-			"<remote> (default origin) and reports how many arrived — run",
-			"it with `gtd history fetch | sh`. Never runs git itself"
-		]
+		group: "Inspect",
+		summary: "Print a script that fetches finished processes",
+		details: `Print a script that fetches every finished process kept on <remote> (default: origin) and reports how many arrived. gtd runs no git itself:
+
+  s=$(gtd history fetch) && sh -c "$s"`
+	},
+	{
+		token: "ui",
+		kind: "ui",
+		arity: "none",
+		group: "Inspect",
+		summary: "Serve the web and phone client",
+		details: `Serve gtd's web and phone client for this worktree. By default it publishes through \`tailscale serve\`, reachable from anywhere on the tailnet, on the first of ports 8443, 10000 and 443 that works; when none does it serves HTTPS locally instead of refusing.`
+	},
+	{
+		token: "install",
+		kind: "install",
+		arity: "none",
+		group: "Driver plumbing",
+		summary: "Print a briefing for writing a driver",
+		details: `Print a self-contained briefing that teaches an agent or a person to build a gtd driver in any shell or runtime, and where to get a workflow — gtd ships none. Writes nothing.`
+	},
+	{
+		token: "judge",
+		kind: "judge",
+		arity: "none",
+		group: "Driver plumbing",
+		summary: "Print the pending judgment",
+		details: `Print the current step's pending judgment: the prepared state, its questions and their criteria — the judge field \`gtd next --json\` carries. Writes nothing; refuses when the step declares no judge.`
+	},
+	{
+		token: "judge answer",
+		kind: "judgeAnswer",
+		arity: "none",
+		group: "Driver plumbing",
+		summary: "Land a verdict read from stdin",
+		details: `Read a verdict from stdin — one { id, answer, p } entry per pending question — and land it the way \`gtd land\` does: plain output names the commit, --json=script prints the script. Refuses when the step declares no judge; a verdict that is not JSON, or names a question that was not asked, is a usage error (exit 2).`
+	},
+	{
+		token: "judge run",
+		kind: "judgeRun",
+		arity: "none",
+		group: "Driver plumbing",
+		summary: "Answer a judgment with a model",
+		details: `Answer a judgment: read the \`gtd judge --json\` document from stdin and print the verdict [{ id, answer, p }] \`gtd judge answer\` reads. Needs no repository.
+
+The fixed answerer reads --answers and leaves out the questions it does not cover; jev asks TypeSafe ($TYPESAFE_API_KEY); llm asks the \`claude\` CLI on PATH. jev and llm exit 1, printing nothing, when they cannot answer every question.`
+	},
+	{
+		token: "check",
+		kind: "check",
+		arity: { names: ["mode", "file"] },
+		group: "Driver plumbing",
+		summary: "Check a steering file's format",
+		details: `Run the steering format <mode> (qa, review or findings) over <file> and print each finding on a line of its own; exits 1 when there are any. Reads no workflow and runs from any directory — emitted validation scripts call it.`
+	},
+	{
+		token: "uncheck",
+		kind: "uncheck",
+		arity: { name: "file" },
+		group: "Driver plumbing",
+		summary: "Untick a review file's boxes",
+		details: `Reset every ticked review box (- [x]) in <file> to - [ ], writing the file only when it changes; a missing file writes nothing. Reads no workflow and runs from any directory — the landing script at a review gate calls it, so no tick is ever committed.`
+	},
+	{
+		token: "lsp",
+		kind: "lsp",
+		arity: "none",
+		group: "Driver plumbing",
+		summary: "Start the steering-file language server",
+		details: `Start the language server for .gtd/ steering files on stdio.`
 	}
 ];
 const commandByToken = (token) => COMMAND_ROWS.find((r) => r.token === token);
-const COLUMN = 19;
-const renderBlock = (header, lines) => {
-	const [first, ...rest] = lines;
-	const headerCell = `  ${header}`;
-	return (headerCell.length < COLUMN ? `${headerCell.padEnd(COLUMN)}${first ?? ""}\n` : `${headerCell}\n${" ".repeat(COLUMN)}${first ?? ""}\n`) + rest.map((l) => `${" ".repeat(COLUMN)}${l}\n`).join("");
-};
-const START_SHORT_FORM = renderBlock("(no command) --workflow <name>", ["Starts a new process authenticated as human, e.g.", "'gtd --workflow <name>'"]);
-const VERSION_BLOCK = renderBlock("version", ["Print version and exit"]);
-const HELP_BLOCK = renderBlock("help", ["Print this help and exit"]);
+/** Every word that may follow `gtd`, for "did you mean". */
+const COMMAND_WORDS = [.../* @__PURE__ */ new Set([
+	...COMMAND_ROWS.map((r) => r.token.split(" ")[0]),
+	"help",
+	"version"
+])];
+const TOP_COLUMN = 28;
+const OPTION_COLUMN = 22;
+const synopsis = (row) => {
+	const { token, arity } = row;
+	if (arity === "none") return token;
+	if ("names" in arity) return `${token} <${arity.names[0]}> <${arity.names[1]}>`;
+	if ("variadic" in arity) return `${token} <${arity.name}> [${arity.variadic}...]`;
+	if ("optional" in arity) return `${token} [${arity.name}]`;
+	if ("many" in arity) return `${token} [${arity.name}...]`;
+	return `${token} <${arity.name}>`;
+};
 const SPACE_FORM_FLAGS = /* @__PURE__ */ new Set(["--workflow", "--var"]);
 const flagHeader = (row) => {
 	if (row.valueHint === "") return row.name;
+	if (row.arity === "optional") return `${row.name}[=${row.valueHint}]`;
 	return SPACE_FORM_FLAGS.has(row.name) ? `${row.name} ${row.valueHint}` : `${row.name}=${row.valueHint}`;
 };
+const START_ROW = {
+	term: "--workflow <name>",
+	summary: "Start a process on a workflow; --var <name>=<value> pins one of its settings"
+};
+const GLOBAL_OPTIONS = [
+	["-v, --verbose", "Narrate on stderr what gtd resolved"],
+	["-h, --help", "Print help; gtd <command> --help for one command"],
+	["-V, --version", "Print the version"]
+];
+const EXTRA_TOPICS = [[
+	"help [command]",
+	"Print help for gtd or one command",
+	"Print gtd's overview, or with <command> that command's own help."
+], [
+	"version",
+	"Print the version",
+	"Print gtd's version."
+]];
+const EXAMPLES = `  $ gtd --workflow <name>                       start a process
+  $ gtd next                                    see what happens next
+  $ s=$(gtd land --json=script) && sh -c "$s"   land the turn
+  $ gtd help land                               one command's details`;
+const lines = (block) => block.map((l) => `${l}\n`).join("");
+const GROUPS = [
+	"Core loop",
+	"Start and stop",
+	"Inspect",
+	"Driver plumbing"
+];
 const renderHelp = () => {
-	const commandBlocks = COMMAND_ROWS.map((row) => {
-		const header = row.arity === "none" ? row.token : "names" in row.arity ? `${row.token} <${row.arity.names[0]}> <${row.arity.names[1]}>` : "variadic" in row.arity ? `${row.token} <${row.arity.name}> [${row.arity.variadic}...]` : "optional" in row.arity ? `${row.token} [${row.arity.name}]` : "many" in row.arity ? `${row.token} [${row.arity.name}...]` : `${row.token} <${row.arity.name}>`;
-		return renderBlock(header, row.details);
-	});
-	return `Usage: gtd [command] [options]\n\nCommands:\n${[
-		commandBlocks[0],
-		START_SHORT_FORM,
-		...commandBlocks.slice(1),
-		VERSION_BLOCK,
-		HELP_BLOCK
-	].join("")}\nOptions:\n${FLAGS.map((row) => renderBlock(flagHeader(row), row.help)).join("")}${renderBlock("--version, -V", ["Print version and exit"]) + renderBlock("--help, -h", ["Print this help and exit"])}`;
+	const groups = GROUPS.map((group) => {
+		const rows = COMMAND_ROWS.filter((r) => r.group === group).flatMap((r) => definition(synopsis(r), r.summary, TOP_COLUMN));
+		const start = group === "Start and stop" ? definition(START_ROW.term, START_ROW.summary, TOP_COLUMN) : [];
+		const extra = group === "Driver plumbing" ? EXTRA_TOPICS.flatMap(([term, summary]) => definition(term, summary, TOP_COLUMN)) : [];
+		return `${group}:\n${lines([
+			...start,
+			...rows,
+			...extra
+		])}`;
+	});
+	return "Usage: gtd <command> [options]\n\n" + lines(wrap("gtd reads a repository's git state and prints what should happen next in its workflow. It never acts on it: a driver, or you, runs what it prints.")) + "\n" + groups.join("\n") + "\nOptions:\n" + lines(GLOBAL_OPTIONS.flatMap(([term, text]) => definition(term, text, TOP_COLUMN))) + `\nExamples:\n${EXAMPLES}\n\n` + lines(wrap("Run `gtd help <command>` for a command's details and options, and `gtd install` to learn how to drive gtd."));
+};
+/** Shown on stderr above a bare `gtd`'s usage error — the overview stays one `gtd help` away. */
+const SHORT_USAGE = `Usage: gtd <command> [options]
+
+  gtd --workflow <name>   start a process
+  gtd next                print what should happen next
+  gtd land                record what the tree now shows
+
+`;
+const renderCommandHelp = (row) => {
+	const options = FLAGS.filter((f) => f.name !== "--verbose" && f.scope(row.kind)).flatMap((f) => definition(flagHeader(f), f.helpFor?.[row.kind] ?? f.help, OPTION_COLUMN));
+	const global = definition("-v, --verbose", "Narrate on stderr what gtd resolved", OPTION_COLUMN);
+	return `Usage: gtd ${synopsis(row)}${options.length > 0 ? " [options]" : ""}\n\n` + lines(wrap(row.details)) + `\nOptions:\n${lines([...options, ...global])}`;
+};
+/** `gtd help <topic…>`'s text: one command's help, every `history` subcommand's for `history`, or undefined for an unknown topic. */
+const renderTopicHelp = (topic) => {
+	const two = commandByToken(topic.slice(0, 2).join(" "));
+	if (two !== void 0 && topic.length >= 2) return renderCommandHelp(two);
+	const [first = ""] = topic;
+	const one = commandByToken(first);
+	if (one !== void 0) return renderCommandHelp(one);
+	const extra = EXTRA_TOPICS.find(([term]) => term.split(" ")[0] === first);
+	if (extra !== void 0) return `Usage: gtd ${extra[0]}\n\n${lines(wrap(extra[2]))}`;
+	const family = COMMAND_ROWS.filter((r) => r.token.startsWith(`${first} `));
+	if (first !== "" && family.length > 0) return family.map(renderCommandHelp).join("\n");
+};
+/** A usage error's tail: the nearest candidate when `word` looks like a typo of one, and where the full list is. */
+const didYouMean = (word, candidates, prefix = "", pointer = "`gtd help` for every command") => {
+	const guess = closest(word, candidates);
+	return guess === void 0 ? ` — run ${pointer}` : ` — did you mean \`${prefix}${guess}\`? Run ${pointer}`;
+};
+const unknownOption = (tok, jsonSeen) => {
+	const candidates = tok.startsWith("--") ? FLAGS.map((f) => f.name) : [];
+	return {
+		kind: "error",
+		message: `gtd: unknown option '${tok}'${didYouMean(tok.split("=")[0], candidates, "", "`gtd help <command>` for its options")}`,
+		jsonSeen
+	};
 };
 const tokenize = (tail) => {
 	const positionals = [];
 	const byFlag = /* @__PURE__ */ new Map();
 	const present = /* @__PURE__ */ new Set();
 	let jsonSeen = false;
+	let afterBareJson;
 	for (let i = 0; i < tail.length; i++) {
 		const original = tail[i];
 		const tok = SINGLE_DASH_ALIASES.get(original) ?? original;
-		if (!tok.startsWith("--")) {
+		if (!tok.startsWith("-") || tok === "-") {
+			if (tail[i - 1] === "--json") afterBareJson ??= original;
 			positionals.push(original);
 			continue;
 		}
-		const row = flagByToken(tok);
-		if (row === void 0) return {
-			kind: "error",
-			message: `gtd: unknown option '${tok}' — see \`gtd --help\``,
-			jsonSeen
-		};
+		const row = tok.startsWith("--") ? flagByToken(tok) : void 0;
+		if (row === void 0) return unknownOption(tok, jsonSeen);
 		const eq = tok.indexOf("=");
 		const alreadyPresent = present.has(row.name);
 		present.add(row.name);
 		if (row.name === "--json") jsonSeen = true;
 		if (row.arity === 0) {
-			if (eq !== -1) return {
-				kind: "error",
-				message: `gtd: unknown option '${tok}' — see \`gtd --help\``,
-				jsonSeen
-			};
+			if (eq !== -1) return unknownOption(tok, jsonSeen);
 			if (!byFlag.has(row.name)) byFlag.set(row.name, []);
 			continue;
 		}
@@ -43424,7 +43369,8 @@ const tokenize = (tail) => {
 		positionals,
 		byFlag,
 		present,
-		jsonSeen
+		jsonSeen,
+		...afterBareJson !== void 0 ? { afterBareJson } : {}
 	};
 };
 const usagePlan = (message, json, stdout = "") => ({
@@ -43476,18 +43422,38 @@ const buildLandCommand = (bag) => ({
 	...bag["--cost"] !== void 0 ? { cost: bag["--cost"] } : {},
 	...bag["--model"] !== void 0 ? { model: bag["--model"] } : {}
 });
-const parseArgv = (argv) => {
-	if (argv.includes("--help") || argv.includes("-h")) return {
+const HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h"]);
+/** `--help`/`-h` anywhere: the named command's own help, else the overview — never a usage error, so a typo'd command still gets help. */
+const helpPlan = (argv) => {
+	const tokenized = tokenize(argv.slice(2).filter((tok) => !HELP_FLAGS.has(tok)));
+	const topic = tokenized.kind === "ok" ? tokenized.positionals : [];
+	return {
+		kind: "output",
+		stdout: renderTopicHelp(topic) ?? renderHelp()
+	};
+};
+/** `gtd help [topic…]`: an unknown topic is a usage error naming the nearest command. */
+const helpCommandPlan = (topic, json) => {
+	if (topic.length === 0) return {
 		kind: "output",
 		stdout: renderHelp()
 	};
+	const text = renderTopicHelp(topic);
+	if (text !== void 0) return {
+		kind: "output",
+		stdout: text
+	};
+	return usagePlan(`gtd: help: no command '${topic.join(" ")}'${didYouMean(topic[0], COMMAND_WORDS, "gtd help ")}`, json);
+};
+const parseArgv = (argv) => {
+	if (argv.some((tok) => HELP_FLAGS.has(tok))) return helpPlan(argv);
 	if (argv.includes("--version") || argv.includes("-V")) return {
 		kind: "output",
 		stdout: `${GTD_VERSION}\n`
 	};
 	const tokenized = tokenize(argv.slice(2));
 	if (tokenized.kind === "error") return usagePlan(tokenized.message, tokenized.jsonSeen);
-	const { positionals, byFlag, present, jsonSeen } = tokenized;
+	const { positionals, byFlag, present, jsonSeen, afterBareJson } = tokenized;
 	const first = positionals[0];
 	const workflowRaw = byFlag.get("--workflow")?.[0];
 	const workflowPresent = workflowRaw !== void 0;
@@ -43495,13 +43461,14 @@ const parseArgv = (argv) => {
 		kind: "output",
 		stdout: `${GTD_VERSION}\n`
 	};
-	if (first === "help") return {
-		kind: "output",
-		stdout: renderHelp()
-	};
+	if (first === "help") return helpCommandPlan(positionals.slice(1), jsonSeen);
 	const isHistory = first === "history";
 	const row = first === void 0 ? void 0 : commandByToken(isHistory ? `history ${positionals[1] ?? ""}` : first);
-	if (isHistory && row === void 0) return usagePlan("gtd history: expected a subcommand — list, show <ref>, metrics [ref...], judges [ref...] or fetch [remote]", jsonSeen);
+	if (isHistory && row === void 0) {
+		const subcommands = COMMAND_ROWS.filter((r) => r.token.startsWith("history ")).map((r) => r.token.split(" ")[1]);
+		const typo = closest(positionals[1] ?? "", subcommands);
+		return usagePlan(typo !== void 0 ? `gtd history: unknown subcommand '${positionals[1]}' — did you mean \`gtd history ${typo}\`?` : "gtd history: expected a subcommand — list, show <ref>, metrics [ref...], judges [ref...] or fetch [remote]", jsonSeen);
+	}
 	const judgeAnswer = row?.kind === "judge" && positionals[1] === "answer";
 	const selectsStart = workflowPresent && first === void 0;
 	const judgeRun = row?.kind === "judge" && positionals[1] === "run";
@@ -43509,15 +43476,18 @@ const parseArgv = (argv) => {
 	if (row === void 0 && !selectsStart) {
 		const violation = scopeViolation(void 0, present);
 		if (violation !== void 0) return usagePlan(violation, jsonSeen);
-		if (first === void 0) return usagePlan("gtd: missing command — gtd decides and prints, a driver executes; run `gtd install`, or copy one from https://github.com/pmelab/gtd/blob/main/docs/driver.md's \"A complete minimal driver\" section and run that, or see usage above (`gtd --help`)", jsonSeen, renderHelp());
-		return usagePlan(`unknown command '${first}'`, jsonSeen);
+		if (first === void 0) return usagePlan("gtd: missing command — run `gtd help` for every command, or `gtd install` to learn how to drive gtd", jsonSeen, SHORT_USAGE);
+		return usagePlan(`gtd: unknown command '${first}'${didYouMean(first, COMMAND_WORDS, "gtd ")}`, jsonSeen);
 	}
 	const restPositionals = first === void 0 ? positionals : positionals.slice(judgeAnswer || judgeRun || isHistory ? 2 : 1);
 	if (kind === "start" && first === void 0) {
 		if (restPositionals.length > 0) return usagePlan(`gtd: too many arguments — expected none, got: ${restPositionals.join(", ")}`, jsonSeen);
 	} else {
-		const arityMsg = kind === "check" && restPositionals.length === 0 && present.has("--open-threads") ? void 0 : arityError(isHistory ? row.token : first, restPositionals, row.arity);
-		if (arityMsg !== void 0) return usagePlan(arityMsg, jsonSeen);
+		const arityMsg = kind === "check" && restPositionals.length === 0 && present.has("--open-threads") || kind === "door" && restPositionals.length === 0 ? void 0 : arityError(isHistory ? row.token : first, restPositionals, row.arity);
+		if (arityMsg !== void 0) {
+			const hint = afterBareJson !== void 0 && restPositionals.includes(afterBareJson) ? ` — to print one field, write --json=${afterBareJson}` : "";
+			return usagePlan(arityMsg + hint, jsonSeen);
+		}
 	}
 	const violation = scopeViolation(kind, present);
 	if (violation !== void 0) return usagePlan(violation, jsonSeen);
@@ -43559,7 +43529,7 @@ const parseArgv = (argv) => {
 		kind: "command",
 		command: {
 			kind: "door",
-			name: restPositionals[0],
+			...restPositionals[0] !== void 0 ? { name: restPositionals[0] } : {},
 			args: restPositionals.slice(1)
 		},
 		json,