@pmelab/gtd 59.0.0 → 60.0.0

package/dist/chunks/{testkit-CMBAAyRK.mjs → testkit-BvecVjQ0.mjs}

@@ -1,6 +1,6 @@
-import { answered, applyScript, checkScript, configProblems, configure, installContext, isFactoryWorkflow, moveScript, numeric, protocolMismatch, removeScript, restoreScript, revertScript, showScript, t as flows_exports, writeScript } from "../flows.mjs";
-import { E as ACCESS_REFUSAL, _ as demandOf, a as landFields, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches } from "./wire-C12dahrH.mjs";
-import { F as formatFinding, N as headingSectionBodies, P as headingSections, a as unansweredQuestions, j as parseThreadsWithFindings, n as openThreads, r as steeringFormatFor, s as parseCodeThreads, t as BUILT_IN_MODE_NAMES } from "./steering-CCNvngSH.mjs";
+import { C as moveScript, D as revertScript, E as restoreScript, H as installContext, K as markedOptions, O as showScript, S as checkScript, T as removeScript, Y as protocolMismatch, i as configure, k as writeScript$1, n as configProblems, o as isFactoryWorkflow, p as numeric, s as answered, t as flows_exports, x as applyScript } from "./flows-DENt0uWV.mjs";
+import { O as ACCESS_REFUSAL, a as renderScriptJson, d as renderLandPlain, f as DEMAND_BRIEFING, g as statusOf, h as renderBeatJson, i as judgeJson, j as renderFormat, l as noopText, m as beatDocument, n as resolveSession, o as scriptFields, p as renderBeatPlain, r as selectPath, s as landFields, t as globMatches, u as renderLandJson, v as beatKindOf, y as demandOf } from "./wire-DZ8R1RU9.mjs";
+import { M as headingSectionBodies, N as formatFinding, a as sections, c as openThreads, i as sectionBodies, l as steeringFormatFor, o as threads, r as openQuestions, s as BUILT_IN_MODE_NAMES, t as parseCodeThreads, u as unansweredQuestions } from "./steering-DF_BMadH.mjs";
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
 import { PassThrough } from "node:stream";
@@ -24210,7 +24210,7 @@ if [ -z "\${1:-}" ]; then
   exit 2
 fi
 cd "$(git rev-parse --show-toplevel)"
-script="$(gtd door "$@")"
+script="$(gtd start "$@")"
 sh -c "$script"
 exec "$GTD_BUILD"`;
 const HEADER = () => `gtd ${GTD_VERSION} — driver protocol\n\ngtd decides and prints; the driver executes. gtd never runs git, never runs\nyour agent, never runs a check script, and never runs a steering mode's own\nformat:/validate: command either — that pair is text in the script gtd next\n--json's validate field (or gtd validate) prints, for the driver to run\nitself ahead of gtd land.\n`;
@@ -24389,7 +24389,7 @@ const DRIVER_OBLIGATIONS = `
     \`--json=judge\`, pipes that rendered \`{ schema, state, questions }\` document to a
     judge model, and pipes ITS verdict (one \`{ id, answer, p }\` per pending
     question, as JSON on stdin) to \`gtd judge answer\` — the FIFTH command
-    that changes anything, alongside \`gtd land\`/\`gtd --workflow\`/\`gtd
+    that changes anything, alongside \`gtd land\`/\`gtd start\`/\`gtd
     abandon\`/\`gtd restore\`. It follows the exact same required-half /
     optional-half script contract as \`gtd land\` in obligation 8 above:
     read \`--json=script\` (and, if you want them, \`--json=settled\`/
@@ -24586,9 +24586,9 @@ ${EDIT_COMMAND}
 
 ### \`gtd-door <name> [args...]\` — start a process through a door and drive it
 
-Runs \`gtd door <name> [args...]\`, captured by command substitution — never a
+Runs \`gtd start <name> [args...]\`, captured by command substitution — never a
 pipe: a pipeline reports only its LAST command's exit status, so
-\`gtd door ... | sh\` under \`set -e\` would sail past a refusal and \`exec\` a
+\`gtd start ... | sh\` under \`set -e\` would sail past a refusal and \`exec\` a
 loop over a process that was never started. It runs the captured script, then
 \`exec\`s the suite's RESOLVED \`gtd-build\` path — never the literal string
 \`gtd-build\`. This is one invocation that carries the process all the way to
@@ -24596,9 +24596,9 @@ its next human gate, not just a starter: \`gtd-door review\` on a RED baseline
 hands off to \`gtd-build\`, which halts at the blocked gate and prints it,
 rather than starting the review; \`gtd-door fix\` on a GREEN suite is a no-op
 straight back to \`idle\` — the exec'd \`gtd-build\` exits immediately on it.
-\`gtd doors\` lists the doors a repository offers (those of the workflows its
-config exports — gtd-workflows' \`default\` brings \`fix\` and
-\`review [base]\` — plus any the config declares). Refuses with
+A bare \`gtd start\` lists what a repository can start: its workflows, and
+the doors those workflows bring (gtd-workflows' \`default\` brings \`fix\`
+and \`review [base]\`) plus any the config declares. Refuses with
 \`usage: gtd-door <name> [args...]\` on stderr and exit \`2\` when the name is
 missing — nothing was even attempted. Default path: \`~/.local/bin/gtd-door\`.
 
@@ -24700,7 +24700,7 @@ const PREREQUISITES = `
 ## Prerequisites and portability
 
 - A POSIX \`sh\` (dash, ash, bash's own POSIX mode, etc.) — gtd's own emitted
-  scripts (\`gtd land --json=script\`, \`gtd --workflow <name>\`, \`gtd abandon\`,
+  scripts (\`gtd land --json=script\`, \`gtd start <name>\`, \`gtd abandon\`,
   \`gtd restore\`, \`gtd judge answer --json=script\`) are POSIX sh; captured,
   then piped into it (see obligation 8 above). Reading
   \`gtd next --json=<path>\`/\`gtd land --json=<path>\`'s own output needs
@@ -24825,7 +24825,7 @@ const parseStepId = (raw) => {
 		occurrence: Number(match[2])
 	};
 };
-const isVerdict = (value) => {
+const isVerdict$1 = (value) => {
 	if (typeof value !== "object" || value === null) return false;
 	const v = value;
 	return typeof v.id === "string" && [
@@ -24889,7 +24889,7 @@ const TRAILER_READERS = {
 	},
 	"Gtd-Judge": (value, into) => {
 		const parsed = parseJson(value);
-		if (isVerdict(parsed)) into.judge.push(parsed);
+		if (isVerdict$1(parsed)) into.judge.push(parsed);
 	},
 	"Gtd-Mark": (value, into) => {
 		const kv = MARK_RE.exec(value);
@@ -25107,6 +25107,11 @@ const approveConflict = (step) => {
 	if (keys.length === 0) return void 0;
 	return `gtd: step "${step.name}": approve cannot be combined with ${keys.join(", ")} in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing`;
 };
+const modeWithoutFile = (step) => {
+	const options = step.request.options;
+	if (options.mode === void 0 || options.file !== void 0) return void 0;
+	return `gtd: step "${step.name}": mode requires file in ${step.kind}() options — name the steering file the mode checks`;
+};
 const replay = async (input) => {
 	const commits = input.episode.commits.map((c) => ({
 		...c,
@@ -25268,7 +25273,7 @@ const replay = async (input) => {
 			kind: "divergence",
 			message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`
 		};
-		const error = unknownOptions(step) ?? approveConflict(step) ?? checkIdentity(step);
+		const error = unknownOptions(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step);
 		return error === void 0 ? void 0 : {
 			kind: "failed",
 			message: error
@@ -25403,24 +25408,10 @@ const replay = async (input) => {
 		changes: () => changesBetween(previousPosition.tree, position.tree),
 		changesSince,
 		matches: globMatches,
-		sections: (text) => headingSections(text),
-		sectionBodies: (text) => headingSectionBodies(text),
-		openQuestions: (text) => {
-			const qa = steeringFormatFor("qa");
-			return qa === void 0 ? [] : unansweredQuestions(qa, text).map((q) => ({
-				question: q.question,
-				line: q.headingLine + 1
-			}));
-		},
-		threads: (text) => {
-			const { threads, findings } = parseThreadsWithFindings(text);
-			return threads.map((t) => ({
-				name: t.name,
-				line: t.line + 1,
-				waitingOn: t.waitingOn,
-				faults: findings.filter((f) => f.message.startsWith(`Footnote thread "[^${t.name}]": `)).map((f) => f.message)
-			}));
-		},
+		sections,
+		sectionBodies,
+		openQuestions,
+		threads,
 		codeThreads: () => changesBetween(treeAt(input.start) ?? input.startTree ?? input.episode.base.tree, position.tree).filter((c) => c.status !== "deleted").flatMap((c) => {
 			const { threads, findings } = parseCodeThreads(c.path, position.tree.read(c.path) ?? "");
 			return threads.map((t) => ({
@@ -25743,7 +25734,7 @@ const dedupeDiagnostics = (diagnostics) => {
 };
 //#endregion
 //#region src/workflow/load.ts
-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$3(configError(diagnostics)) : _void;
 const MIGRATION_DOC = "https://github.com/pmelab/gtd/blob/main/docs/configuration.md#migrating-from-gtdrc";
 /**
@@ -25759,11 +25750,11 @@ const refuseLegacyRc = gen(function* () {
 	const found = files.filter((f) => f.owned).map((f) => f.path);
 	if (found.length === 0) return;
 	return yield* fail$3(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",
-		"    env     → an option of the workflow factory in gtd.config.ts, or its `envDefaults` export",
+		"    vars    → an option of the workflow factory in gtd.config.ts, or `workflow(flow, { defaults })`",
+		"    env     → an option of the workflow factory in gtd.config.ts, or `workflow(flow, { envDefaults })`",
 		"    judge   → ~/.config/gtd/judge.json, or GTD_JUDGE_PROVIDER / GTD_JUDGE_MODEL",
 		"    modes, ui, skills, access → the `config` export of gtd.config.ts (`defineConfig`)",
 		"    $schema → nothing; drop it",
@@ -25783,7 +25774,7 @@ const load = gen(function* () {
 		const missing = {
 			severity: "error",
 			path: [],
-			message: `no workflows configured: no ${WORKFLOW_MODULE} here or above — gtd ships no workflow; \`gtd install\` says where to get one`,
+			message: `no workflows configured: no ${WORKFLOW_MODULE} here or above — gtd ships no workflow; \`gtd guide\` says where to get one`,
 			origin: host.root
 		};
 		return yield* fail$3(configError([missing]));
@@ -25795,23 +25786,22 @@ 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]));
 	yield* failOnErrors(diagnostics);
 	if (loaded.default === void 0) return yield* die("unreachable: a default fails to build only with an error reported");
 	const initial = yield* firstStep(loaded.default, headTree(yield* Workspace));
-	const steering = loaded.file.steering;
 	const define = (entry) => ({
 		flow: entry.flow,
-		summary: entry.file.summary,
-		base: (w, v) => entry.file.base?.(w, v) ?? entry.base?.(w, v),
-		steering,
+		summary: entry.summary,
+		base: (w, v) => entry.base?.(w, v),
+		steering: entry.steering,
 		modes: compiled.modes,
-		skills: entry.file.skills,
+		skills: entry.skills,
 		configuredSkills: compiled.skills,
-		access: entry.file.access,
+		access: entry.access,
 		configuredAccess: compiled.access,
 		skillsOrigin: entry.file.origin,
 		initial
@@ -25933,48 +25923,69 @@ const requiredOnUse = (modules, files) => {
 		get: (loaded, id) => typeof id !== "string" || id in loaded ? loaded[id] : loaded[id] = require(files.get(id))
 	});
 };
-const stringRecord = (exports, name) => {
-	const value = exports[name] ?? {};
-	if (typeof value !== "object" || value === null || Object.values(value).some((entry) => typeof entry !== "string")) throw new Error(`the "${name}" export is not a record of strings`);
-	return value;
+/** `what` names the value in an error: `workflow "x"'s "steering"`. */
+const stringRecord = (value, what) => {
+	const record = value ?? {};
+	if (typeof record !== "object" || record === null || Object.values(record).some((entry) => typeof entry !== "string")) throw new Error(`${what} is not a record of strings`);
+	return record;
 };
 const isStringArray = (v) => Array.isArray(v) && v.every((entry) => typeof entry === "string");
-const checkSkillsRecord = (value) => {
-	if (typeof value !== "object" || value === null || Object.values(value).some((entry) => !isStringArray(entry))) throw new Error(`the "skills" export is not a record of skill-name arrays`);
+const checkSkillsRecord = (value, what) => {
+	if (typeof value !== "object" || value === null || Object.values(value).some((entry) => !isStringArray(entry))) throw new Error(`${what} is not a record of skill-name arrays`);
 	return value;
 };
-/** Read a module's optional `skills` export — a scope full name -> skill list record, or a function of the vars returning one. */
-const skillsExport = (exports) => {
-	const value = exports["skills"] ?? {};
-	if (typeof value === "function") return (vars) => checkSkillsRecord(value(vars));
-	const record = checkSkillsRecord(value);
+/** A workflow's `skills` option — a scope full name -> skill list record, or a function of the vars returning one. */
+const skillsFrom = (value, what) => {
+	if (typeof value === "function") return (vars) => checkSkillsRecord(value(vars), what);
+	const record = checkSkillsRecord(value ?? {}, what);
 	return () => record;
 };
-/** Read a module's optional `access` export — a scope full name -> `{ read?, write? }` record, or a function of the vars returning one. */
-const accessExport = (exports) => {
-	const value = exports["access"] ?? {};
+const checkAccessRecord = (value, what) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${what} is not a record of scope access (scope -> { read?, write? }) or a function returning one`);
+	for (const [scope, access] of Object.entries(value)) {
+		const fault = accessShapeFault(access);
+		if (fault !== void 0) throw new Error(`${what}: scope "${scope}": ${fault}`);
+	}
+	return value;
+};
+/**
+* A workflow's `access` option — a scope full name -> `{ read?, write? }`
+* record, checked now, or a function of the vars returning one, checked when
+* the process's settings are known.
+*/
+const accessFrom = (value, what) => {
 	if (typeof value === "function") return (vars) => value(vars);
-	return () => value;
+	const record = checkAccessRecord(value ?? {}, what);
+	return () => record;
 };
-const optionalFunction = (exports, name) => {
-	const value = exports[name];
+const optionalFunction = (value, what) => {
 	if (value === void 0) return void 0;
-	if (typeof value !== "function") throw new Error(`the "${name}" export is not a function`);
+	if (typeof value !== "function") throw new Error(`${what} is not a function`);
 	return value;
 };
-const RESERVED_EXPORTS = /* @__PURE__ */ new Set([
-	"default",
-	"summary",
-	"base",
+const RETIRED_EXPORTS = /* @__PURE__ */ new Set([
 	"defaults",
 	"envDefaults",
 	"steering",
 	"skills",
 	"access",
 	"doors",
-	"config"
+	"summary",
+	"base"
+]);
+/** Names that are never a workflow. */
+const RESERVED_EXPORTS = /* @__PURE__ */ new Set([
+	"default",
+	"config",
+	...RETIRED_EXPORTS
 ]);
-/** The rules every declared setting meets, whether a file's export or a factory's build. */
+const retiredExports = (exports, origin) => Object.keys(exports).filter((name) => RETIRED_EXPORTS.has(name)).sort().map((name) => ({
+	severity: "error",
+	path: [name],
+	origin,
+	message: `the "${name}" export is no longer read — pass it to the workflow it configures: \`workflow(flow, { ${name} })\`, or the build a workflow factory returns`
+}));
+/** The rules every declared setting meets. */
 const checkSettings = (defaults, envDefaults, declares) => {
 	for (const [kind, record] of [["defaults", defaults], ["envDefaults", envDefaults]]) for (const [name, setting] of Object.entries(record)) {
 		if (!isSettingName(name)) throw new Error(`${declares(kind)} ${JSON.stringify(name)}, not a valid setting name — ${SETTING_NAME_RULE}`);
@@ -25983,23 +25994,6 @@ const checkSettings = (defaults, envDefaults, declares) => {
 	const both = Object.keys(defaults).filter((name) => Object.hasOwn(envDefaults, name));
 	if (both.length > 0) throw new Error(`${both.map((name) => `"${name}"`).join(", ")} declared in both "defaults" and "envDefaults" — a setting is a process setting or an environment setting, not both`);
 };
-/** A module's per-file exports: `defaults`, `envDefaults`, `steering`, `skills`, `access`, `summary`, `base`. */
-const fileFrom = (exports, origin, dependencyFiles) => {
-	const defaults = stringRecord(exports, "defaults");
-	const envDefaults = stringRecord(exports, "envDefaults");
-	checkSettings(defaults, envDefaults, (kind) => `the "${kind}" export declares`);
-	return {
-		defaults,
-		envDefaults,
-		steering: stringRecord(exports, "steering"),
-		skills: skillsExport(exports),
-		access: accessExport(exports),
-		summary: optionalFunction(exports, "summary"),
-		base: optionalFunction(exports, "base"),
-		origin,
-		dependencyFiles
-	};
-};
 const DOOR_NAME_RULE = /^[a-z][a-z0-9-]*$/;
 /** Why one door's `args` are malformed, or `undefined` when they are well-formed. */
 const argsProblem = (args) => {
@@ -26023,22 +26017,11 @@ const doorProblem = (name, door) => {
 	const varsOk = vars === void 0 || typeof vars === "function";
 	return argsProblem(args) ?? (varsOk ? void 0 : `has "vars" that is not a function`);
 };
-/** A module's `doors` export, shape-checked; the workflow names are checked later, against the catalogue. */
-const doorsFrom = (exports) => {
-	const value = exports["doors"];
-	if (value === void 0) return /* @__PURE__ */ new Map();
-	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`the "doors" export is not a record of doors`);
-	for (const [name, door] of Object.entries(value)) {
-		const problem = doorProblem(name, door);
-		if (problem !== void 0) throw new Error(`door "${name}" ${problem}`);
-	}
-	return new Map(Object.entries(value));
-};
 /**
-* Each exported workflow's own doors, onto the name it is exported under. The
-* `doors` export adds to them and declares a name several workflows clash on.
+* Each exported workflow's own doors, onto the name it is exported under. A
+* door several workflows build and none is exported under is a clash: no door.
 */
-const derivedDoors = (catalogue, declared) => {
+const derivedDoors = (catalogue) => {
 	const builders = /* @__PURE__ */ new Map();
 	for (const [workflow, loaded] of catalogue) for (const [name, spec] of Object.entries(loaded.doors ?? {})) {
 		const door = {
@@ -26054,34 +26037,31 @@ const derivedDoors = (catalogue, declared) => {
 	for (const [name, built] of builders) {
 		const owner = ownerOf(name, built);
 		if (owner !== void 0) doors.set(name, owner);
-		else if (!declared.has(name)) clashes.set(name, built.map((door) => door.workflow));
+		else clashes.set(name, built.map((door) => door.workflow));
 	}
 	return {
-		doors: new Map([...doors, ...declared]),
+		doors,
 		clashes
 	};
 };
 /** The export named after the door owns it, else the sole builder; a clash of several builds no door. */
 const ownerOf = (name, built) => built.find((door) => door.workflow === name) ?? (built.length === 1 ? built[0] : void 0);
-/** Sort the doors and check each names a startable workflow. */
-const checkDoors = (declared, catalogue) => {
-	const doors = new Map([...declared].sort(([a], [b]) => a.localeCompare(b)));
-	for (const [name, door] of doors) if (!catalogue.has(door.workflow)) throw new Error(`door "${name}" names workflow "${door.workflow}", which is not startable — known: ${[...catalogue.keys()].sort().join(", ")}`);
-	return doors;
-};
 const namespaceOf = (exported) => typeof exported === "object" && exported !== null ? exported : {};
 /**
-* Evaluate `gtd.config.ts`. Every exported function or factory workflow but
-* the reserved names is a workflow named by its export. `cache` is jiti's OWN
-* per-call module cache (unrelated to the instance's `moduleCache: false`) —
-* passing an empty object in has the side effect of collecting every real file
-* jiti resolved evaluating this module, module AND every relative import it
-* pulled in, transitively.
+* Evaluate `gtd.config.ts`. Every export but the reserved names that went
+* through `workflow()` or is a factory workflow is a workflow named by its
+* export. `cache` is jiti's OWN per-call module cache (unrelated to the
+* instance's `moduleCache: false`) — passing an empty object in has the side
+* effect of collecting every real file jiti resolved evaluating this module,
+* module AND every relative import it pulled in, transitively.
 */
 const loadWorkflows = (module, shipped) => {
 	const { exports: evaluated, files } = module.read === void 0 ? evaluateFromDisk(module, shipped) : evaluateRead(module, module.read, shipped);
 	const exports = namespaceOf(evaluated);
-	const file = fileFrom(exports, module.filepath, files);
+	const file = {
+		origin: module.filepath,
+		dependencyFiles: files
+	};
 	const exported = Object.entries(exports).filter(([name, value]) => !RESERVED_EXPORTS.has(name) && isWorkflow(value));
 	const value = defaultExport(exports);
 	const defaultName = exported.find(([, other]) => other === value)?.[0] ?? "default";
@@ -26096,27 +26076,40 @@ const loadWorkflows = (module, shipped) => {
 	const derived = rejections.length > 0 ? {
 		doors: /* @__PURE__ */ new Map(),
 		clashes: /* @__PURE__ */ new Map()
-	} : derivedDoors(catalogue, doorsFrom(exports));
+	} : derivedDoors(catalogue);
+	const doors = new Map([...derived.doors].sort(([a], [b]) => a.localeCompare(b)));
 	return {
 		file,
 		catalogue,
-		doors: checkDoors(derived.doors, catalogue),
+		doors,
 		default: defaultWorkflow && {
 			...defaultWorkflow,
 			name: defaultName
 		},
 		config: compileConfig(exports["config"], module.filepath),
-		diagnostics: [...nameRejections(rejections), ...[...derived.clashes].map(([name, builders]) => {
-			const names = [...builders].sort().map((b) => JSON.stringify(b));
-			return {
-				severity: "warning",
-				message: `door "${name}" is built by workflows ${names.slice(0, -1).join(", ")} and ${names.at(-1)} and none is exported under that name — declare it in the "doors" export`,
-				path: ["doors", name],
-				origin: file.origin
-			};
-		})]
+		diagnostics: [
+			...retiredExports(exports, file.origin),
+			...nameRejections(rejections),
+			...shadowingDoors(doors, catalogue, file.origin),
+			...[...derived.clashes].map(([name, builders]) => {
+				const names = [...builders].sort().map((b) => JSON.stringify(b));
+				return {
+					severity: "warning",
+					message: `door "${name}" is built by workflows ${names.slice(0, -1).join(", ")} and ${names.at(-1)} and none is exported under that name — rename the export that should own it to "${name}"`,
+					path: ["doors", name],
+					origin: file.origin
+				};
+			})
+		]
 	};
 };
+/** `gtd start <name>` takes the door, so a door named like a workflow it does not start hides that workflow. */
+const shadowingDoors = (doors, catalogue, origin) => [...doors].filter(([name, door]) => catalogue.has(name) && door.workflow !== name).map(([name, door]) => ({
+	severity: "warning",
+	message: `door "${name}" starts workflow ${JSON.stringify(door.workflow)} and hides the workflow of the same name from \`gtd start ${name}\` — rename one of them`,
+	path: ["doors", name],
+	origin
+}));
 const evaluateFromDisk = (module, shipped) => {
 	const cache = {};
 	return {
@@ -26160,49 +26153,58 @@ const evaluateRead = (module, read, shipped) => {
 		files
 	};
 };
-const isWorkflow = (value) => typeof value === "function" || isFactoryWorkflow(value);
+const isWorkflow = (value) => markedOptions(value) !== void 0 || isFactoryWorkflow(value);
 const defaultExport = (exports) => {
 	const value = exports.default;
-	if (value === void 0) throw new Error("no default export — export the workflow an ordinary start runs (`gtd install` scaffolds one)");
-	if (!isWorkflow(value)) throw new Error("the default export is not a function");
+	if (value === void 0) throw new Error("no default export — export the workflow an ordinary start runs; `gtd guide` says where to get one, or write your own");
+	if (typeof value !== "function" && !isFactoryWorkflow(value)) throw new Error("the default export is not a function");
 	return value;
 };
-/** One exported workflow: a plain flow as-is, a factory validated and built. */
+/** One exported workflow: a factory validated and built, a `workflow()` call's options checked alike. */
 const buildWorkflow = (name, value, file, rejections) => {
 	const result = configure(value);
-	if (result === void 0) return {
-		flow: value,
-		file,
-		defaults: file.defaults,
-		envDefaults: file.envDefaults
-	};
+	if (result === void 0) return checkedBuild(name, file, {
+		...markedOptions(value),
+		flow: value
+	});
 	if (!result.ok) {
 		for (const issue of result.issues) rejections.push(optionDiagnostic(name, issue, file));
 		return;
 	}
-	return {
-		flow: result.build.flow,
-		file,
-		...builtSettings(name, file, result.build),
-		doors: result.build.doors,
-		base: result.build.base
-	};
+	return checkedBuild(name, file, result.build);
 };
-/** A factory's settings over its file's, held to the rules a file's own exports are. */
-const builtSettings = (name, file, build) => {
-	checkSettings(build.defaults ?? {}, build.envDefaults ?? {}, (kind) => `workflow "${name}" builds ${kind}`);
-	const defaults = {
-		...file.defaults,
-		...build.defaults
-	};
-	const envDefaults = {
-		...file.envDefaults,
-		...build.envDefaults
-	};
-	checkSettings(defaults, envDefaults, (kind) => `workflow "${name}" builds ${kind}`);
+const BUILD_KEYS = /* @__PURE__ */ new Set([
+	"flow",
+	"defaults",
+	"envDefaults",
+	"doors",
+	"base",
+	"skills",
+	"access",
+	"steering",
+	"summary"
+]);
+/** A build — a factory's, or a `workflow()` call's options with its flow — held to one set of rules. */
+const checkedBuild = (name, file, build) => {
+	const what = (key) => `workflow "${name}"'s "${key}"`;
+	const unknown = Object.keys(build).filter((key) => !BUILD_KEYS.has(key));
+	if (unknown.length > 0) throw new Error(`workflow "${name}" has unknown option(s) ${unknown.map((key) => JSON.stringify(key)).join(", ")} — known: ${[...BUILD_KEYS].filter((key) => key !== "flow").join(", ")}`);
+	if (typeof build.flow !== "function") throw new Error(`${what("flow")} is not a function`);
+	const defaults = stringRecord(build.defaults, what("defaults"));
+	const envDefaults = stringRecord(build.envDefaults, what("envDefaults"));
+	checkSettings(defaults, envDefaults, (kind) => `workflow "${name}" declares ${kind}`);
+	if (build.doors !== void 0 && (typeof build.doors !== "object" || build.doors === null || Array.isArray(build.doors))) throw new Error(`${what("doors")} is not a record of doors`);
 	return {
+		flow: build.flow,
+		file,
 		defaults,
-		envDefaults
+		envDefaults,
+		summary: optionalFunction(build.summary, what("summary")),
+		steering: stringRecord(build.steering, what("steering")),
+		skills: skillsFrom(build.skills, what("skills")),
+		access: accessFrom(build.access, what("access")),
+		doors: build.doors,
+		base: optionalFunction(build.base, what("base"))
 	};
 };
 /** A rejected factory option, reported at `gtd.config.ts`. */
@@ -26300,7 +26302,7 @@ const replayToFirstStep = (loaded, vars, env, tree) => flatMap$2(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$3(new GtdError(`gtd config:\n  - ${loaded.file.origin}: ${problem}`));
+	return fail$3(new GtdError(`gtd: config:\n  - ${loaded.file.origin}: ${problem}`));
 });
 /**
 * The default entry's first step — where a finished process waits — found the
@@ -26316,20 +26318,20 @@ 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$3(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$3(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$3(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$3(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$3(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 });
 };
 //#endregion
 //#region src/workflow/skills.ts
-const fail = (origin, message) => new GtdError(`gtd config:\n  - ${origin}: ${message}`);
+const fail = (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`);
@@ -26518,10 +26520,10 @@ const checkOverrides = (commandLabel, varOverrides, declaredNames, envNames) =>
 	const environmentOnly = Object.keys(varOverrides).filter((n) => !declaredNames.includes(n) && envNames.includes(n));
 	if (environmentOnly.length > 0) return yield* fail$3(new GtdUsageError(`${commandLabel}: --var pins process settings only; ${environmentOnly.join(", ")} ${environmentOnly.length === 1 ? "is an environment setting" : "are environment settings"} — set it as a workflow option in gtd.config.ts or with a GTD_<NAME> environment variable`));
 	const undeclared = Object.keys(varOverrides).filter((n) => !declaredNames.includes(n));
-	if (undeclared.length > 0) return refusal(`${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(", ")} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`);
+	if (undeclared.length > 0) return yield* fail$3(new GtdUsageError(`${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(", ")} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`));
 });
 /**
-* `gtd --workflow <name>`: start a brand NEW process on a workflow, writing an
+* `gtd start <name>`: start a brand NEW process on a workflow, writing an
 * opening commit that names the workflow's first step and carries a
 * `Gtd-Workflow:` trailer, every process setting as a `Gtd-Var:` trailer, plus
 * a `Gtd-Review-Base:` trailer when the workflow fixes the process's diff base,
@@ -26534,8 +26536,7 @@ const planStart = (current, actor, start) => gen(function* () {
 	if (!current.idle) return refusal(`${commandLabel}: a process is already underway (resting at "${current.state}") — finish it, or run \`gtd abandon\`, before starting another`);
 	if ("refusal" in first) return refusal(`${commandLabel}: ${first.refusal}`);
 	const { firstStep } = first;
-	const overrideRefusal = yield* checkOverrides(commandLabel, varOverrides, Object.keys(workflow.vars), Object.keys(workflow.env));
-	if (overrideRefusal !== void 0) return overrideRefusal;
+	yield* checkOverrides(commandLabel, varOverrides, Object.keys(workflow.vars), Object.keys(workflow.env));
 	const baseOf = workflow.def.base;
 	const flags = yield* StartFlags;
 	const hostEnv = (yield* Host).env;
@@ -26609,7 +26610,7 @@ const ACTORS = /* @__PURE__ */ new Set([
 /**
 * Where the episode HEAD belongs to begins, read off subjects alone. Walking
 * back from HEAD: a bare `gtd(human): <step>` commit with no `Gtd-Step` is what
-* `gtd --workflow` writes — no landing ever produces one — and opens an
+* `gtd start` writes — no landing ever produces one — and opens an
 * episode as its first commit (its `Gtd-Workflow` trailer names the workflow;
 * a legacy `--entry` opening has none); a commit that is not a gtd step commit, or one
 * entering the flow's first step (a finished episode), bounds the episode
@@ -27113,7 +27114,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$3(/* @__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$3(/* @__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
@@ -27143,7 +27144,7 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 });
 const currentRest = restAt(void 0);
 /**
-* Whether `gtd --workflow <name>` can start a process here: the workflow must
+* Whether `gtd start <name>` can start a process here: the workflow must
 * reach a step from the tree the opening commit would capture. That step is
 * what the opening commit's subject names.
 */
@@ -27665,7 +27666,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";
 /**
@@ -27960,6 +27961,21 @@ const writeJson = (json, out, document) => gen(function* () {
 	else yield* writeSelection(out, document, json.path);
 	return true;
 });
+/** Exactly one trailing newline: a script embedded in a `--json` document is never re-normalized at its tail. */
+const normalizeScriptNewline = (script) => script.length === 0 ? script : `${script.replace(/\n+$/, "")}\n`;
+/**
+* A script-printing command's output: the script itself (or `plain`, when
+* there is none to run), `{ schema, script }` under `--json`, or one field.
+*/
+const writeScript = (json, out, script, plain = script) => gen(function* () {
+	if (json.kind === "off") {
+		out.write(plain);
+		return;
+	}
+	const fields = scriptFields(normalizeScriptNewline(script));
+	if (json.kind === "document") out.write(renderScriptJson(fields));
+	else yield* writeSelection(out, fields, json.path);
+});
 //#endregion
 //#region src/cli/Strays.ts
 const resolveSide = (git, side) => git.resolveRef(`${side}^{commit}`).pipe(mapError$1(() => new GtdError(`gtd strays: unknown revision '${side}'`)));
@@ -28054,9 +28070,7 @@ const runHistoryShowCommand = (ref, json, out) => gen(function* () {
 	out.write(`${lines.join("\n")}\n`);
 });
 /** Prints the script and never runs git: gtd's promise that it only decides and prints. */
-const runHistoryFetchCommand = (remote, out) => sync$1(() => {
-	out.write(`${combinedScript(fetchHistoryRefs(remote), "")}\n`);
-});
+const runHistoryFetchCommand = (remote, json, out) => writeScript(json, out, `${combinedScript(fetchHistoryRefs(remote), "")}\n`);
 //#endregion
 //#region src/cli/Metrics.ts
 const QUALITY$1 = ".gtd/QUALITY.md";
@@ -28639,7 +28653,7 @@ const runLspCommand = () => flatMap$2(ToolCommands, (tools) => tools.lsp(selfGtd
 * gtd ships no workflow, so where no `gtd.config.ts` governs it says where to
 * get one; it writes nothing.
 */
-const runInstallCommand = (out) => gen(function* () {
+const runGuideCommand = (out) => gen(function* () {
 	const briefing = renderBriefing();
 	out.write(briefing.endsWith("\n") ? briefing : briefing + "\n");
 	const host = yield* Host;
@@ -28647,20 +28661,12 @@ const runInstallCommand = (out) => gen(function* () {
 	if (topLevel._tag === "Left") return;
 	if ((yield* host.realPath(topLevel.right)) !== (yield* host.realPath(host.root))) return;
 	if ((yield* (yield* ConfigDiscovery).workflowModule(host.root, host.home)) !== void 0) return;
-	yield* (yield* Narrator).warn(`gtd install: no ${WORKFLOW_MODULE} governs here, and gtd ships no workflow — get one from ${WORKFLOWS_REPO} or write your own (step 2 of the briefing above)`);
+	yield* (yield* Narrator).warn(`gtd guide: no ${WORKFLOW_MODULE} governs here, and gtd ships no workflow — get one from ${WORKFLOWS_REPO} or write your own (step 2 of the briefing above)`);
 });
 /**
-* Exactly one trailing newline — duplicated from `Cli.ts`'s own
-* `normalizeTrailingNewline` rather than imported, to avoid a circular value
-* dependency (`Cli.ts` already depends on this module). `LandResult.script`
-* must carry its own trailing newline because it's embedded verbatim inside
-* the `--json` document, never re-normalized at its tail.
-*/
-const normalizeScriptNewline = (script) => script.length === 0 ? script : `${script.replace(/\n+$/, "")}\n`;
-/**
 * `combinedScript`, narrowed to accept only an already-guarded
 * `RunnableScript` for `required` — the one boundary `ScriptSurface`'s brand
-* exists to protect: `gtd land`/`gtd --workflow`'s emitted script. Every OTHER
+* exists to protect: `gtd land`/`gtd start`'s emitted script. Every OTHER
 * `combinedScript` call (`abandon`/`restore`/steering validate, below) builds
 * from `emitScripts` directly and keeps the unbranded signature — those
 * paths land no guard-gated git write for a brand to protect.
@@ -28754,12 +28760,24 @@ const readStdin = () => tryPromise({
 	},
 	catch: (e) => e instanceof Error ? e : new Error(String(e))
 });
+/** A stdin that is no judgment is the caller's mistake, a usage error like `gtd judge answer`'s. */
+const judgmentShape = (input) => {
+	let doc;
+	try {
+		doc = JSON.parse(input);
+	} catch {
+		return fail$3(new GtdUsageError("gtd judge run: stdin is not valid JSON"));
+	}
+	const questions = doc?.questions;
+	return Array.isArray(questions) ? _void : fail$3(new GtdUsageError("gtd judge run: stdin has no \"questions\" array"));
+};
 /** Stdout is written once, after the answerer resolves — a rejection leaves it empty. */
 const runJudgeRunCommand = (command, out) => gen(function* () {
 	const host = yield* Host;
 	const tools = yield* ToolCommands;
 	yield* refuseLegacyRc;
 	const input = yield* readStdin();
+	yield* judgmentShape(input);
 	const verdict = yield* tryPromise({
 		try: () => tools.judge({
 			provider: command.provider,
@@ -28832,16 +28850,19 @@ const runLandCommand = (opts, json, out) => gen(function* () {
 * `base` renders to something that is not an ancestor of (and differs from)
 * HEAD.
 */
-const runStartCommand = (actor, workflow, varOverrides, out, commandLabel) => gen(function* () {
+const startWorkflow = (workflow, varOverrides, json, out, commandLabel) => gen(function* () {
 	const config = yield* (yield* ConfigService).load;
 	const resolved = config.workflowNamed(workflow);
-	if (resolved === void 0) return yield* fail$3(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$3(new GtdUsageError(`${commandLabel}: unknown workflow "${workflow}" — ${startable}`));
+	}
 	const rest = yield* restAt(void 0, varOverrides);
 	const started = yield* startRefusal(rest, resolved, varOverrides);
 	const plan = yield* planStart({
 		state: rest.state,
 		idle: noProcessUnderway(rest)
-	}, actor, {
+	}, "human", {
 		workflow: resolved,
 		first: started,
 		commandLabel,
@@ -28849,51 +28870,79 @@ const runStartCommand = (actor, workflow, varOverrides, out, commandLabel) => ge
 		config: rest.config
 	});
 	if (plan.kind === "refusal") return yield* fail$3(new Error(plan.message));
-	out.write(landingScript(ScriptSurface.render(plan.steps)));
+	yield* writeScript(json, out, listingCommitted(landingScript(ScriptSurface.render(plan.steps)), rest.changes));
 });
-const doorSynopsis = (name, door) => [name, ...(door.args ?? []).map((arg) => arg.optional === true ? `[${arg.name}]` : `<${arg.name}>`)].join(" ");
 /**
-* `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
-* arity is a usage error naming what would have worked.
+* 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 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$3(new GtdUsageError(`gtd door: unknown door "${name}" — doors: ${known.map(([n, d]) => doorSynopsis(n, d)).join(", ")}`));
-	}
+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(" ");
+/** A door's start: its args mapped to process settings, `extra` (`--var`) pinned on top. */
+const startThroughDoor = (name, door, args, extra, json, out) => gen(function* () {
+	const label = `gtd start ${name}`;
 	const declared = door.args ?? [];
 	const required = declared.filter((arg) => arg.optional !== true).length;
-	if (args.length < required || args.length > declared.length) return yield* fail$3(new GtdUsageError(`gtd door ${name}: ${args.length < required ? "missing" : "too many"} arguments — usage: gtd door ${doorSynopsis(name, door)}`));
+	if (args.length < required || args.length > declared.length) return yield* fail$3(new GtdUsageError(`${label}: ${args.length < required ? "missing" : "too many"} arguments — usage: gtd start ${doorSynopsis(name, door)}`));
 	const named = {};
 	declared.forEach((arg, i) => {
 		named[arg.name] = args[i];
 	});
 	const vars = yield* try_({
 		try: () => door.vars?.(named) ?? {},
-		catch: (e) => /* @__PURE__ */ new Error(`gtd door ${name}: ${e instanceof Error ? e.message : String(e)}`)
+		catch: (e) => /* @__PURE__ */ new Error(`${label}: ${e instanceof Error ? e.message : String(e)}`)
 	});
-	yield* runStartCommand("human", door.workflow, { ...vars }, out, `gtd door ${name}`);
+	yield* startWorkflow(door.workflow, {
+		...vars,
+		...extra
+	}, json, out, label);
 });
-/** `gtd doors`: every door and its args, sorted by name — plain lines, or one JSON array. */
-const runDoorsCommand = (json, out) => gen(function* () {
-	const doors = [...(yield* (yield* ConfigService).load).doors];
-	if (json.kind === "off") {
-		out.write(doors.map(([n, d]) => `${doorSynopsis(n, d)} → ${d.workflow}\n`).join(""));
-		return;
-	}
-	const document = doors.map(([n, d]) => ({
-		name: n,
-		workflow: d.workflow,
-		args: (d.args ?? []).map((arg) => ({
+/**
+* `gtd start <name> [args…]`: a door when `<name>` is one — so a door shadows
+* the workflow it shares a name with — else a workflow, which takes no args.
+* No name lists both.
+*/
+const runStartCommand = (command, json, out) => gen(function* () {
+	const { name, args, vars } = command;
+	if (name === void 0) return yield* runStartListCommand(json, out);
+	const label = `gtd start ${name}`;
+	const config = yield* (yield* ConfigService).load;
+	const door = config.doors.get(name);
+	if (door !== void 0) return yield* startThroughDoor(name, door, args, vars, json, out);
+	if (config.workflowNamed(name) === void 0) return yield* fail$3(new GtdUsageError(`${label}: no workflow or door is named "${name}" — run \`gtd start\` to list them`));
+	if (args.length > 0) return yield* fail$3(new GtdUsageError(`${label}: too many arguments — a workflow takes none, only --var <name>=<value>; got: ${args.join(", ")}`));
+	yield* startWorkflow(name, { ...vars }, json, out, label);
+});
+/**
+* Bare `gtd start`: every workflow startable by name, then every door — plain
+* lines, or one JSON array. A workflow a door shadows is left out: its name
+* opens the door.
+*/
+const runStartListCommand = (json, out) => gen(function* () {
+	const config = yield* (yield* ConfigService).load;
+	const workflows = [...config.workflowNames].filter((name) => !config.doors.has(name)).sort();
+	const doors = [...config.doors];
+	const document = [...workflows.map((name) => ({
+		kind: "workflow",
+		name
+	})), ...doors.map(([name, door]) => ({
+		kind: "door",
+		name,
+		workflow: door.workflow,
+		args: (door.args ?? []).map((arg) => ({
 			name: arg.name,
 			optional: arg.optional === true
 		}))
-	}));
-	if (json.kind === "document") out.write(`${JSON.stringify(document)}\n`);
-	else yield* writeSelection(out, document, json.path);
+	}))];
+	if (yield* writeJson(json, out, document)) return;
+	if (document.length === 0) yield* (yield* Narrator).warn("gtd start: this config exports no workflow besides its default, which an ordinary start runs, and no door");
+	out.write([...workflows.map((name) => `workflow ${name}\n`), ...doors.map(([n, d]) => `door ${doorSynopsis(n, d)} → ${d.workflow}\n`)].join(""));
 });
 /**
 * Ends the process underway without completing it. Nothing is discarded: a
@@ -28908,7 +28957,7 @@ const runDoorsCommand = (json, out) => gen(function* () {
 * Idempotent at the initial state. The one refusal is a process whose first
 * commit is the repository's root commit: nothing earlier to rewind to.
 */
-const runAbandonCommand = (out) => gen(function* () {
+const runAbandonCommand = (json, out) => gen(function* () {
 	const git = yield* GitService;
 	const initial = (yield* (yield* ConfigService).load).workflow.initial;
 	const run = yield* currentRun;
@@ -28917,8 +28966,7 @@ const runAbandonCommand = (out) => gen(function* () {
 			kind: "outcome",
 			command: abandonNoopOutcome(initial)
 		}]).required;
-		out.write(combinedScript(required, ""));
-		return;
+		return yield* writeScript(json, out, combinedScript(required, ""));
 	}
 	const restState = run.trace[run.trace.length - 1].state;
 	if (run.startParentHash === EMPTY_TREE) return yield* fail$3(/* @__PURE__ */ new Error(`gtd abandon: the process underway (resting at "${restState}") starts at the repository's first commit — there is no earlier commit to rewind to`));
@@ -28936,7 +28984,7 @@ const runAbandonCommand = (out) => gen(function* () {
 			command: abandonedOutcome(restState, run.startParentHash, initial)
 		}
 	]).required;
-	out.write(combinedScript(required, ""));
+	yield* writeScript(json, out, combinedScript(required, ""));
 });
 /**
 * `gtd restore`: hard-reset HEAD back to the tip `gtd abandon` retained.
@@ -28945,7 +28993,7 @@ const runAbandonCommand = (out) => gen(function* () {
 * refuses on a dirty working tree, no retained history, or HEAD having
 * advanced past the retained tip with commits that would be lost.
 */
-const runRestoreCommand = (out) => gen(function* () {
+const runRestoreCommand = (json, out) => gen(function* () {
 	const git = yield* GitService;
 	if ((yield* currentRest).changes.length > 0) return yield* fail$3(/* @__PURE__ */ new Error("gtd restore: refuses on a dirty working tree — commit, stash, or discard your changes first."));
 	const retained = yield* readRetainedHistory(git);
@@ -28969,7 +29017,7 @@ const runRestoreCommand = (out) => gen(function* () {
 			command: restoredOutcome(tip, after.state)
 		}
 	]).required;
-	out.write(combinedScript(required, ""));
+	yield* writeScript(json, out, combinedScript(required, ""));
 });
 /**
 * The mode's own validate command for `file`: a declared `validate:` command
@@ -29028,26 +29076,35 @@ 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));
 	}
 });
 /** Emits the format-then-validate script for the driver to run; reads no file and executes nothing itself. The verdict lives in that script's future exit code, which prints the complete fix prompt rather than bare findings. */
-const runValidateCommand = (out) => gen(function* () {
+const runValidateCommand = (json, out) => gen(function* () {
 	const rest = yield* currentRest;
-	const resolved = yield* resolveValidateScript(rest);
-	out.write(resolved !== void 0 && resolved.script.length > 0 ? `${resolved.script}\n` : `nothing to validate at "${rest.state}"\n`);
+	const script = (yield* resolveValidateScript(rest))?.script ?? "";
+	yield* writeScript(json, out, script, script.length > 0 ? `${script}\n` : `nothing to validate at "${rest.state}"\n`);
 });
 /**
 * Runs `<mode>`'s parser over `<file>`, exiting non-zero on any finding.
 * Resolves no workflow state and reads no config — this is what a seeded
 * `validate:` command invokes as a leaf step, and it formats nothing.
 *
-* An absent file exits 0, like `gtd validate`. Findings ride the failing
-* Effect's message, so the shared refusal path reports them on stderr.
+* An unknown mode is a usage error; an absent file is a refusal (the emitted
+* validate script guards on the file's presence before it calls this).
+* Findings ride the failing Effect's message, so the shared refusal path
+* reports them on stderr.
 */
 const runCheckCommand = (mode, file, openQuestions, openThreadsFlag) => gen(function* () {
 	const format = steeringFormatFor(mode);
-	if (format === void 0) return yield* fail$3(/* @__PURE__ */ new Error(`gtd check: unknown mode "${mode}" — known modes: ${BUILT_IN_MODE_NAMES.join(", ")}`));
+	if (format === void 0) return yield* fail$3(new GtdUsageError(`gtd check: unknown mode "${mode}" — known modes: ${BUILT_IN_MODE_NAMES.join(", ")}`));
 	if (openThreadsFlag) {
 		if (openQuestions) return yield* fail$3(/* @__PURE__ */ new Error("gtd check: --open-threads and --open-questions are mutually exclusive"));
 		if (format.openThreads === void 0) {
@@ -29060,11 +29117,15 @@ const runCheckCommand = (mode, file, openQuestions, openThreadsFlag) => gen(func
 		if (mode !== "qa") return yield* fail$3(/* @__PURE__ */ new Error(`gtd check: --open-questions only applies to mode "qa" — got "${mode}"`));
 		return yield* runOpenQuestionsCheckCommand(format, file);
 	}
-	const content = (yield* Workspace).atPath(file);
-	const errors = content !== void 0 ? format.validate(content).map((finding) => formatFinding(file, finding)) : [];
+	const content = yield* existingFile(file);
+	const errors = format.validate(content).map((finding) => formatFinding(file, finding));
 	if (errors.length === 0) return;
 	return yield* fail$3(/* @__PURE__ */ new Error(`gtd check: ${file} is not valid under mode "${mode}" (${errors.length} finding(s)):\n` + errors.join("\n")));
 });
+const existingFile = (file) => flatMap$2(Workspace, (workspace) => {
+	const content = workspace.atPath(file);
+	return content === void 0 ? fail$3(/* @__PURE__ */ new Error(`gtd check: no such file: ${file}`)) : succeed$3(content);
+});
 /**
 * The bare `gtd check --open-threads`: code-comment threads in the files the
 * current process changed. The one `check` form that reads process state; no
@@ -29082,23 +29143,18 @@ const runCodeThreadsCheckCommand = () => gen(function* () {
 	if (lines.length === 0) return;
 	return yield* fail$3(new Error(lines.join("\n")));
 });
-/** Prints one `file:line: [^name]: <first H entry>` line per open thread; a missing file fails, like `--open-questions`. */
+/** Prints one `file:line: [^name]: <first H entry>` line per open thread. */
 const runOpenThreadsCheckCommand = (format, file) => gen(function* () {
-	const content = (yield* Workspace).atPath(file);
-	if (content === void 0) return yield* fail$3(/* @__PURE__ */ new Error(`gtd check: ${file} does not exist`));
-	const errors = openThreads(format, content).map((t) => `${file}:${t.line + 1}: [^${t.name}]: ${t.firstMe}`);
+	const errors = openThreads(format, yield* existingFile(file)).map((t) => `${file}:${t.line + 1}: [^${t.name}]: ${t.firstMe}`);
 	if (errors.length === 0) return;
 	return yield* fail$3(/* @__PURE__ */ new Error(`gtd check: ${errors.length} open thread(s) in ${file}:\n` + errors.join("\n")));
 });
 /**
 * Runs the SAME `unansweredQuestions` predicate a flow's `openQuestions()`
-* reads, so the gate script and the flow's own check stay in sync. A missing
-* file is a non-zero exit here, unlike the structural path above.
+* reads, so the gate script and the flow's own check stay in sync.
 */
 const runOpenQuestionsCheckCommand = (format, file) => gen(function* () {
-	const content = (yield* Workspace).atPath(file);
-	if (content === void 0) return yield* fail$3(/* @__PURE__ */ new Error(`gtd check: ${file} does not exist`));
-	const errors = unansweredQuestions(format, content).map((q) => `${file}:${q.headingLine + 1}: ${q.question}`);
+	const errors = unansweredQuestions(format, yield* existingFile(file)).map((q) => `${file}:${q.headingLine + 1}: ${q.question}`);
 	if (errors.length === 0) return;
 	return yield* fail$3(/* @__PURE__ */ new Error(`gtd check: ${errors.length} open question(s) unanswered in ${file}:\n` + errors.join("\n")));
 });
@@ -29183,12 +29239,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$3(/* @__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$3(/* @__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$3(/* @__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$3(/* @__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
@@ -29200,7 +29257,7 @@ const assertRepositoryHasCommits = (git) => gen(function* () {
 const needsOf = (kind) => {
 	switch (kind) {
 		case "lsp":
-		case "install":
+		case "guide":
 		case "judgeRun":
 		case "strays": return "none";
 		case "check":
@@ -29226,18 +29283,16 @@ const dispatchVoidCommand = (command, json, out) => {
 			...command.cost !== void 0 ? { cost: command.cost } : {},
 			...command.model !== void 0 ? { model: command.model } : {}
 		}, json, out);
-		case "start": return runStartCommand(command.actor, command.workflow, command.vars, out, command.label);
-		case "door": return runDoorCommand(command.name, command.args, out);
-		case "doors": return runDoorsCommand(json, out);
-		case "abandon": return runAbandonCommand(out);
-		case "restore": return runRestoreCommand(out);
+		case "start": return runStartCommand(command, json, out);
+		case "abandon": return runAbandonCommand(json, out);
+		case "restore": return runRestoreCommand(json, out);
 		case "next": return runNextCommand(json, out);
-		case "validate": return runValidateCommand(out);
+		case "validate": return runValidateCommand(json, out);
 		case "check":
 			if (command.mode === void 0 || command.file === void 0) return runCodeThreadsCheckCommand();
 			return runCheckCommand(command.mode, command.file, command.openQuestions ?? false, command.openThreads ?? false);
 		case "uncheck": return runUncheckCommand(command.file);
-		case "install": return runInstallCommand(out);
+		case "guide": return runGuideCommand(out);
 		case "summary": return runSummaryCommand(out);
 		case "base": return runBaseCommand(out);
 		case "judge": return runJudgeCommand(json, out);
@@ -29247,7 +29302,7 @@ const dispatchVoidCommand = (command, json, out) => {
 		case "historyShow": return runHistoryShowCommand(command.ref, json, out);
 		case "historyMetrics": return runHistoryMetricsCommand(command.refs, json, out);
 		case "historyJudges": return runHistoryJudgesCommand(command.refs, command.vars, command.jsonl, json, out);
-		case "historyFetch": return runHistoryFetchCommand(command.remote, out);
+		case "historyFetch": return runHistoryFetchCommand(command.remote, json, out);
 	}
 };
 /**
@@ -29275,18 +29330,99 @@ const runCommand$1 = (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
+/** `<name>=<value>` occurrences of `flag` → one record, each name a setting name given at most once. */
+const decodeAssignments = (flag, raws) => {
+	const vars = {};
+	for (const raw of raws) {
+		const eq = raw.indexOf("=");
+		if (eq <= 0) return left(`gtd: ${flag} must be <name>=<value> with a non-empty name — got "${raw}"`);
+		const name = raw.slice(0, eq);
+		const value = raw.slice(eq + 1);
+		if (!isSettingName(name)) return left(`gtd: ${flag} ${JSON.stringify(name)} is not a valid setting name — ${SETTING_NAME_RULE}`);
+		if (/[\r\n]/.test(value)) return left(`gtd: ${flag} ${name} must be a single-line value`);
+		if (Object.hasOwn(vars, name)) return left(`gtd: ${flag} ${name} specified more than once`);
+		if (!name.startsWith("flag_")) {
+			vars[name] = value;
+			continue;
+		}
+		const pinned = flagSettingValue(value);
+		if (pinned === void 0) return left(`gtd: ${flag} ${name} must be 1, 0, true or false`);
+		vars[name] = pinned;
+	}
+	return right(vars);
+};
 const nonNegativeNumber = (raw, flag) => {
 	const n = Number(raw);
 	if (raw.trim() === "" || !Number.isFinite(n) || n < 0) return left(`gtd: ${flag} must be a non-negative number — got "${raw}"`);
 	return right(n);
 };
+/** The commands whose only output is a script: `--json` prints `{ schema, script }`. */
+const SCRIPT_KINDS = /* @__PURE__ */ new Set([
+	"start",
+	"abandon",
+	"restore",
+	"validate",
+	"historyFetch"
+]);
+const SCRIPT_JSON_HELP = "Print { schema, script }, or with --json=script the script alone";
 const JSON_KINDS = /* @__PURE__ */ new Set([
+	...SCRIPT_KINDS,
 	"next",
 	"land",
 	"judge",
 	"judgeAnswer",
-	"doors",
 	"historyList",
 	"historyShow",
 	"historyMetrics",
@@ -29300,22 +29436,14 @@ const FLAGS = [
 		repeatable: false,
 		scope: (kind) => JSON_KINDS.has(kind),
 		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",
+		scopeError: "gtd: --json is only valid for `gtd next`/`gtd land`, the commands that print a script, and the listings whose help names it (e.g. `gtd strays`) — every other command prints plain text; see `gtd guide` 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",
+			...Object.fromEntries([...SCRIPT_KINDS].map((kind) => [kind, SCRIPT_JSON_HELP])),
+			start: `${SCRIPT_JSON_HELP}. Bare, print the list as a JSON array of { kind, name } (a door adds workflow and args)`
+		}
 	},
 	{
 		name: "--port",
@@ -29328,11 +29456,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",
@@ -29342,11 +29466,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",
@@ -29356,7 +29476,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",
@@ -29366,7 +29486,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",
@@ -29376,11 +29496,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",
@@ -29390,11 +29506,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",
@@ -29404,7 +29516,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",
@@ -29412,61 +29524,33 @@ const FLAGS = [
 		repeatable: false,
 		scope: (kind) => kind === "land" || kind === "judgeRun",
 		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`",
+		scopeError: "gtd: --model is only valid for `gtd land` (with --cost: the model to record the cost against) or `gtd judge run` (the model that answers)",
 		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 — recorded on the commit, nothing runs on it",
+			judgeRun: "The claude model the llm answerer uses (default: $GTD_JUDGE_MODEL, then judge.json, then sonnet)"
+		}
 	},
 	{
-		name: "--workflow",
+		name: "--threshold",
 		arity: 1,
-		repeatable: false,
-		scope: (kind) => kind === "start",
-		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"]
+		repeatable: true,
+		scope: (kind) => kind === "historyJudges",
+		decode: (raws) => decodeAssignments("--threshold", raws),
+		scopeError: "gtd: --threshold is only valid for `gtd history judges`",
+		valueHint: "<name>=<value>",
+		help: "Re-decide every past verdict under this threshold: judgeIdenticalMinP or qualityTriageMinP (repeatable)"
 	},
 	{
 		name: "--var",
 		arity: 1,
 		repeatable: true,
-		scope: (kind) => kind === "start" || kind === "historyJudges",
-		decode: (raws) => {
-			const vars = {};
-			const seen = /* @__PURE__ */ new Set();
-			for (const raw of raws) {
-				const eq = raw.indexOf("=");
-				if (eq <= 0) return left(`gtd: --var must be <name>=<value> with a non-empty name — got "${raw}"`);
-				const name = raw.slice(0, eq);
-				const value = raw.slice(eq + 1);
-				if (!isSettingName(name)) return left(`gtd: --var ${JSON.stringify(name)} is not a valid setting name — ${SETTING_NAME_RULE}`);
-				if (/[\r\n]/.test(value)) return left(`gtd: --var ${name} must be a single-line value`);
-				if (seen.has(name)) return left(`gtd: --var ${name} specified more than once`);
-				seen.add(name);
-				if (name.startsWith("flag_")) {
-					const pinned = flagSettingValue(value);
-					if (pinned === void 0) return left(`gtd: --var ${name} must be 1, 0, true or false`);
-					vars[name] = pinned;
-					continue;
-				}
-				vars[name] = value;
-			}
-			return right(vars);
-		},
-		scopeError: "gtd: --var requires --workflow (or `gtd history judges`)",
+		scope: (kind) => kind === "start",
+		decode: (raws) => decodeAssignments("--var", raws),
+		scopeError: "gtd: --var is only valid for `gtd start <name>`",
 		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: "Pin one of the workflow's declared settings for the new process (repeatable); through a door, on top of the settings its args set"
 	},
 	{
 		name: "--jsonl",
@@ -29476,8 +29560,8 @@ 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"],
-		conflicts: ["--json", "--var"]
+		help: "Print one JSON line per verdict instead of the report",
+		conflicts: ["--json", "--threshold"]
 	},
 	{
 		name: "--open-questions",
@@ -29487,12 +29571,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",
@@ -29502,15 +29581,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",
@@ -29520,11 +29591,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"
 	}
 ];
 /**
@@ -29544,277 +29611,92 @@ const flagByToken = (token) => {
 };
 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",
+		token: "next",
+		kind: "next",
 		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"
-		]
+		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: "next",
-		kind: "next",
+		token: "land",
+		kind: "land",
 		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"
-		]
+		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: "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"
-		]
+		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; --json=script then prints an empty script.`
 	},
 	{
-		token: "lsp",
-		kind: "lsp",
-		arity: "none",
-		details: ["Start the LSP server for .gtd/ steering files (stdio)"]
+		token: "start",
+		kind: "start",
+		arity: {
+			name: "name",
+			variadic: "args",
+			bare: true
+		},
+		group: "Start and stop",
+		summary: "Start a workflow or door; bare, list them",
+		details: `Start a new process: print the script that makes its first commit, which also commits whatever the working tree holds.
+
+<name> is a door — a named shortcut whose positional args set the workflow's settings — or else a workflow the config exports, which takes no args. A door shadows a workflow of the same name. --var pins a setting either way.
+
+  s=$(gtd start <name> --json=script) && sh -c "$s"
+
+With no <name>, list every workflow and door it can start. An unknown <name>, the wrong number of args, or a --var the workflow does not declare is a usage error (exit 2); a process already underway is a refusal (exit 1).`
 	},
 	{
-		token: "ui",
-		kind: "ui",
+		token: "abandon",
+		kind: "abandon",
 		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"
-		]
+		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 --json=script) && sh -c "$s"`
 	},
 	{
-		token: "install",
-		kind: "install",
+		token: "restore",
+		kind: "restore",
 		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: "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: "summary",
 		kind: "summary",
 		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: "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",
-		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."
-		]
-	},
-	{
-		token: "door",
-		kind: "door",
-		arity: {
-			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"
-		]
-	},
-	{
-		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"
-		]
-	},
-	{
-		token: "judge",
-		kind: "judge",
-		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:"
-		]
-	},
-	{
-		token: "judge answer",
-		kind: "judgeAnswer",
-		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."
-		]
-	},
-	{
-		token: "judge run",
-		kind: "judgeRun",
-		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 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",
@@ -29823,45 +29705,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",
@@ -29870,18 +29734,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",
@@ -29890,18 +29745,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",
@@ -29910,69 +29756,201 @@ 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 --json=script) && 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: "guide",
+		kind: "guide",
+		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. A stdin that is not a judgment document is a usage error (exit 2).`
+	},
+	{
+		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, or when <file> does not exist. An unknown <mode> is a usage error (exit 2). 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"]);
-const SPACE_FORM_FLAGS = /* @__PURE__ */ new Set(["--workflow", "--var"]);
+/** 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 ("bare" in arity) return `${token} [${arity.name}] [${arity.variadic}...]`;
+	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(["--var", "--threshold"]);
 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 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"],
+	["--", "End the options: every word after it is an argument"]
+];
+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 start                                   list what can start
+  $ gtd start <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);
+	const groups = GROUPS.map((group) => {
+		const rows = COMMAND_ROWS.filter((r) => r.group === group).flatMap((r) => definition(synopsis(r), r.summary, TOP_COLUMN));
+		const extra = group === "Driver plumbing" ? EXTRA_TOPICS.flatMap(([term, summary]) => definition(term, summary, TOP_COLUMN)) : [];
+		return `${group}:\n${lines([...rows, ...extra])}`;
 	});
-	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"])}`;
+	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 guide` 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 start <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;
+	const end = tail.indexOf("--");
 	for (let i = 0; i < tail.length; i++) {
 		const original = tail[i];
+		if (i === end) continue;
 		const tok = SINGLE_DASH_ALIASES.get(original) ?? original;
-		if (!tok.startsWith("--")) {
+		if (end !== -1 && i > end || !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;
 		}
@@ -30023,7 +30001,8 @@ const tokenize = (tail) => {
 		positionals,
 		byFlag,
 		present,
-		jsonSeen
+		jsonSeen,
+		...afterBareJson !== void 0 ? { afterBareJson } : {}
 	};
 };
 const usagePlan = (message, json, stdout = "") => ({
@@ -30046,7 +30025,7 @@ const tooMany = (cmd, rest, expected, max) => rest.length > max ? `gtd ${cmd}: t
 const arityError = (cmd, rest, arity) => {
 	if (arity === "none") return tooMany(cmd, rest, "none", 0);
 	if ("names" in arity) return pairArityError(cmd, rest, arity.names);
-	if ("many" in arity) return void 0;
+	if ("many" in arity || "bare" in arity) return void 0;
 	if ("optional" in arity) return tooMany(cmd, rest, `at most one ${arity.name}`, 1);
 	if (rest.length === 0) return `gtd ${cmd}: missing ${arity.name} argument`;
 	return "variadic" in arity ? void 0 : tooMany(cmd, rest, `one ${arity.name}`, 1);
@@ -30069,54 +30048,85 @@ const decodeFlags = (byFlag) => {
 	}
 	return right(bag);
 };
+/** `gtd history judges`' thresholds: each a known judge threshold with a numeric value. */
+const judgeThresholds = (thresholds) => {
+	const unknown = Object.keys(thresholds).find((name) => !Object.hasOwn(THRESHOLDS, name));
+	if (unknown !== void 0) return left(`gtd history judges: --threshold ${unknown} is no judge threshold — use ${Object.keys(THRESHOLDS).join(" or ")}`);
+	const nan = Object.entries(thresholds).find(([, value]) => value.trim() === "" || !Number.isFinite(Number(value)));
+	if (nan !== void 0) return left(`gtd history judges: --threshold ${nan[0]} must be a number — got "${nan[1]}"`);
+	return right(thresholds);
+};
 /** Assembles a `land` `Command` from its already-scope-checked flag bag — split out of `parseArgv` so its two independent, omit-when-absent optional fields don't inflate that function's own branching. */
 const buildLandCommand = (bag) => ({
 	kind: "land",
 	...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"]);
+/** The options part of argv: everything before a `--`, which ends the options. */
+const optionsOf = (argv) => {
+	const end = argv.indexOf("--", 2);
+	return end === -1 ? argv : argv.slice(0, end);
+};
+/** `--help`/`-h` anywhere before `--`: 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(optionsOf(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()
 	};
-	if (argv.includes("--version") || argv.includes("-V")) return {
+	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) => {
+	const options = optionsOf(argv);
+	if (options.some((tok) => HELP_FLAGS.has(tok))) return helpPlan(argv);
+	if (options.includes("--version") || options.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;
 	if (first === "version") return {
 		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";
-	const kind = selectsStart ? "start" : judgeAnswer ? "judgeAnswer" : judgeRun ? "judgeRun" : row?.kind;
-	if (row === void 0 && !selectsStart) {
+	if (row === void 0 || first === void 0) {
 		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 guide` 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 kind = judgeAnswer ? "judgeAnswer" : judgeRun ? "judgeRun" : row.kind;
+	const restPositionals = positionals.slice(judgeAnswer || judgeRun || isHistory ? 2 : 1);
+	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) {
+		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);
@@ -30140,30 +30150,20 @@ const parseArgv = (argv) => {
 		};
 	}
 	if (kind === "start") {
-		const label = `gtd --workflow ${workflowRaw}`;
+		const [name, ...args] = restPositionals;
+		if (name === void 0 && bag["--var"] !== void 0) return usagePlan("gtd start: --var needs a <name> — run `gtd start` to list the workflows and doors", jsonSeen);
 		return {
 			kind: "command",
 			command: {
 				kind: "start",
-				actor: "human",
-				workflow: workflowRaw,
-				vars: bag["--var"] ?? {},
-				label
+				...name !== void 0 ? { name } : {},
+				args,
+				vars: bag["--var"] ?? {}
 			},
 			json,
 			verbose
 		};
 	}
-	if (kind === "door") return {
-		kind: "command",
-		command: {
-			kind: "door",
-			name: restPositionals[0],
-			args: restPositionals.slice(1)
-		},
-		json,
-		verbose
-	};
 	if (kind === "ui") return {
 		kind: "command",
 		command: {
@@ -30229,17 +30229,14 @@ const parseArgv = (argv) => {
 		verbose
 	};
 	if (kind === "historyJudges") {
-		const vars = bag["--var"] ?? {};
-		const unknown = Object.keys(vars).find((name) => !Object.hasOwn(THRESHOLDS, name));
-		if (unknown !== void 0) return usagePlan(`gtd history judges: --var ${unknown} is no judge threshold — use ${Object.keys(THRESHOLDS).join(" or ")}`, jsonSeen);
-		const nan = Object.entries(vars).find(([, value]) => value.trim() === "" || !Number.isFinite(Number(value)));
-		if (nan !== void 0) return usagePlan(`gtd history judges: --var ${nan[0]} must be a number — got "${nan[1]}"`, jsonSeen);
+		const thresholds = judgeThresholds(bag["--threshold"] ?? {});
+		if (isLeft(thresholds)) return usagePlan(thresholds.left, jsonSeen);
 		return {
 			kind: "command",
 			command: {
 				kind: "historyJudges",
 				refs: restPositionals,
-				vars,
+				vars: thresholds.right,
 				jsonl: bag["--jsonl"] ?? false
 			},
 			json,
@@ -31128,7 +31125,7 @@ const recognizeWrite = (repo, script) => {
 	const [, content, to] = words$1(lines[3]);
 	const remove = words$1(lines.find((l) => l.startsWith("rm -rf -- ")) ?? "");
 	if (path === void 0 || content === void 0 || to !== path) return void 0;
-	if (writeScript(path, content, remove) !== script) return void 0;
+	if (writeScript$1(path, content, remove) !== script) return void 0;
 	repo.writeFile(path, content);
 	removeAll(repo, remove);
 	return ok();
@@ -31765,7 +31762,10 @@ const recognizeGtdCheck = (repo, block) => {
 		error: `gtd check: unknown mode "${mode}" — known modes: ${BUILT_IN_MODE_NAMES.join(", ")}`
 	};
 	const content = repo.readFile(file);
-	if (content === void 0) return { kind: "noop" };
+	if (content === void 0) return {
+		kind: "failed",
+		error: `gtd check: no such file: ${file}`
+	};
 	const findings = format.validate(content).map((finding) => formatFinding(file, finding));
 	if (findings.length === 0) return { kind: "noop" };
 	return {
@@ -31788,12 +31788,10 @@ const recognizeGtdUncheck = (repo, block) => {
 	return { kind: "noop" };
 };
 /**
-* `Emit.ts`'s `combinedScript` leading comment — `gtd land`/`gtd --workflow`'s
-* whole plain-text artifact opens with this line ahead of the required
-* script, so recognizing it as a no-op (like the retry-helper function
-* definition) keeps the `@inmem` tier green.
+* A block of nothing but comments is a no-op in `sh` too — `combinedScript`'s
+* leading `DID_NOT_RUN_COMMENT`, and the list of paths a start commits.
 */
-const recognizeDidNotRunComment = (block) => block === "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn" ? { kind: "noop" } : void 0;
+const recognizeCommentBlock = (block) => block.split("\n").every((line) => line.startsWith("#")) ? { kind: "noop" } : void 0;
 /** `combinedScript`'s optional half. Reports `noop` whatever the inner result, mirroring bash's `( … ) || <warning>`. Exception: under `git: false` any unrecognized inner block fails the outer script (git or not), so the in-memory twin knowingly diverges from `sh` rather than run git unseen. */
 const PRESENTATION_FAILURE_TEXT = `${extractQuotedTokens(PRESENTATION_FAILURE_WARNING)[0].replace(/\\n$/, "")}\n`;
 const PRESENTATION_SUBSHELL_PREFIX = `${PRESENTATION_ONLY_COMMENT}\n(\n`;
@@ -31907,7 +31905,7 @@ const recognizeWriteLines = (repo, block) => {
 /** Every recognizer `applyEmittedScript` tries, first match wins — `recognizeScriptedCommand` stays last since it's the exact-hit fallback for anything the rest don't claim. */
 const recognizersFor = (repo, commands, git) => [
 	(block) => recognizeSetFlags(block),
-	(block) => recognizeDidNotRunComment(block),
+	(block) => recognizeCommentBlock(block),
 	(block) => recognizePrecondition(repo, block),
 	(block) => recognizeFileExistsGuard(repo, block),
 	(block) => recognizeBinaryGuard(commands, block),
@@ -31985,6 +31983,52 @@ const unrecognized = (block, output = "") => ({
 });
 Narrator.layer(() => {}, false);
 //#endregion
+//#region src/testkit/imports.ts
+const IDENTIFIER$1 = /^[A-Za-z_$][\w$]*$/;
+const STATEMENT = /^[ \t]*(import|export)([ \t]+type)?[ \t]+([\w$* \t,]*(?:\{[^}]*\})?[\w$* \t,]*?)\s*\bfrom\s*(["'])([^"'\n]+)\4[ \t]*;?|^[ \t]*import\s*(["'])([^"'\n]+)\6[ \t]*;?/gm;
+const bindings = (list) => list.split(",").map((entry) => entry.trim()).filter((entry) => entry !== "" && !entry.startsWith("type ")).map((entry) => {
+	const [name, as] = entry.split(/\s+as\s+/);
+	return {
+		name,
+		as: as ?? name
+	};
+});
+const exportLine = (as, value) => as === "default" ? `export default ${value}` : `export const ${as} = ${value}`;
+const exportLines = (module, m, read, head, braces) => {
+	if (braces !== void 0) return bindings(braces).map((b) => exportLine(b.as, read(b.name)));
+	if (/^\*\s+as\s+/.test(head)) return [exportLine(head.replace(/^\*\s+as\s+/, ""), m)];
+	return Object.keys(module).filter((name) => name !== "default" && IDENTIFIER$1.test(name)).map((name) => exportLine(name, read(name)));
+};
+const importLines = (m, read, head, braces) => [...head.split(",").map((part) => part.trim()).filter((part) => part !== "").map((part) => part.startsWith("*") ? `const ${part.replace(/^\*\s+as\s+/, "")} = ${m}` : `const ${part} = ${read("default")}`), ...braces === void 0 ? [] : bindings(braces).map((b) => `const ${b.as} = ${read(b.name)}`)];
+/**
+* `source` with each import or re-export of a specifier in `modules` reading
+* that module off `lookup(specifier)`, an expression evaluated when the
+* config runs. A string config is evaluated in memory, where no resolver
+* knows the specifier, so the binding is made by hand.
+*/
+const importsFrom = (source, modules, lookup) => {
+	let n = 0;
+	const rewrite = (kind, clause, specifier, module) => {
+		const m = `__testkit_module_${++n}`;
+		const read = (name) => {
+			if (!(name in module)) throw new Error(`testkit: module "${specifier}" has no export "${name}"`);
+			return `${m}[${JSON.stringify(name)}]`;
+		};
+		const text = clause.trim();
+		const braces = /\{([^}]*)\}/.exec(text)?.[1];
+		const head = text.replace(/\{[^}]*\}/, "").replace(/,\s*$/, "").trim();
+		const lines = kind === "export" ? exportLines(module, m, read, head, braces) : importLines(m, read, head, braces);
+		return [`const ${m} = ${lookup(specifier)}`, ...lines].join("\n");
+	};
+	return source.replace(STATEMENT, (statement, kind, typeOnly, clause, _q, from, _bq, bare) => {
+		const specifier = from ?? bare;
+		const module = modules[specifier];
+		if (module === void 0) return statement;
+		if (typeOnly !== void 0 || bare !== void 0) return "";
+		return rewrite(kind, clause, specifier, module);
+	});
+};
+//#endregion
 //#region src/testkit/TestRepo.ts
 const REGISTRY = Symbol.for("@pmelab/gtd/testkit:modules");
 const registry = () => {
@@ -31993,9 +32037,10 @@ const registry = () => {
 };
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 let registered = 0;
+const lookup = (key) => `globalThis[Symbol.for(${JSON.stringify(REGISTRY.description)})].get(${JSON.stringify(key)})`;
 /** A config whose exports are module `id`'s, read off the registry when the engine loads it. */
 const moduleSource = (id, module) => {
-	const lines = [`const m = globalThis[Symbol.for(${JSON.stringify(REGISTRY.description)})].get(${JSON.stringify(id)})`];
+	const lines = [`const m = ${lookup(id)}`];
 	for (const name of Object.keys(module)) if (name === "default") lines.push(`export default m.default`);
 	else if (IDENTIFIER.test(name)) lines.push(`export const ${name} = m[${JSON.stringify(name)}]`);
 	else throw new Error(`testkit: export name "${name}" is not an identifier`);
@@ -32003,6 +32048,48 @@ const moduleSource = (id, module) => {
 };
 /** An actor that runs the step's own script, for steps whose script `runScript` understands. */
 const runsItsScript = (beat, repo) => repo.runScript(beat.content);
+/**
+* A judge's verdict, keyed by question id: `verdict({ ready: true })`, or with
+* a confidence, `verdict({ ready: { answer: true, p: 0.6 } })`. `p` defaults to 0.9.
+*/
+const verdict = (answers) => ({ answers: Object.entries(answers).map(([id, entry]) => typeof entry === "object" ? {
+	id,
+	answer: entry.answer,
+	p: entry.p ?? .9
+} : {
+	id,
+	answer: entry,
+	p: .9
+}) });
+/** `actor`, at a visit whose beat content contains `text`; any other visit changes nothing. */
+const whenPrompted = (text, actor) => (beat, repo) => beat.content.includes(text) ? actor(beat, repo) : void 0;
+/** Each actor in order, at every visit; the first verdict any of them returns is the result. */
+const inTurn = (actors) => async (beat, repo) => {
+	let result;
+	for (const actor of actors) {
+		const returned = await actor(beat, repo);
+		if (result === void 0 && returned !== void 0) result = returned;
+	}
+	return result;
+};
+/** At a judge step, `answer` when the pending questions (as `gtd judge` prints them) contain `text`. */
+const verdictWhen = (text, answer) => async (_, repo) => {
+	const { stdout } = await repo.gtd("judge");
+	return stdout.includes(text) ? answer : void 0;
+};
+const isVerdict = (value) => typeof value === "object" && value !== null && Array.isArray(value.answers);
+const TRAILER = /^([A-Za-z0-9][A-Za-z0-9-]*): ?(.*)$/;
+const trailersOf = (message) => {
+	const paragraphs = message.trimEnd().split(/\n\s*\n/);
+	const last = paragraphs.length > 1 ? paragraphs.at(-1).split("\n") : [];
+	const trailers = {};
+	if (last.length === 0 || !last.every((line) => TRAILER.test(line))) return trailers;
+	for (const line of last) {
+		const [, key, value] = TRAILER.exec(line);
+		(trailers[key] ??= []).push(value);
+	}
+	return trailers;
+};
 const words = (text) => [...text.matchAll(/'((?:[^']|'\\'')*)'/g)].map((m) => m[1].replaceAll("'\\''", "'"));
 const fileOf = (repo, path, what) => {
 	const content = repo.readFile(path);
@@ -32047,17 +32134,61 @@ const runLines = (repo, commands, script) => {
 	if (!applied.ok) throw cannotRun(applied.error ?? "");
 };
 const failed = (what, result) => /* @__PURE__ */ new Error(`${what} exited ${result.exitCode}\n${result.stderr}${result.stdout}`);
+const ANSWER = {
+	noul: "true",
+	choice: "\"<option>\"",
+	score: "0.5"
+};
+/** The verdict a judge beat's questions take, as a template to copy. */
+const expectedVerdict = (doc) => {
+	let questions = [];
+	try {
+		questions = JSON.parse(doc.judge ?? "").questions;
+	} catch {}
+	return ["expected a JSON array, one entry per question — answer a boolean for a noul, a string for a choice, a number for a score; p between 0 and 1:", `[${questions.map(({ id, primitive }) => `{ "id": ${JSON.stringify(id)}, "answer": ${ANSWER[primitive] ?? "\"<answer>\""}, "p": 0.9 }`).join(", ")}]`].join("\n");
+};
+const quoted = (names) => names.map((name) => `"${name}"`).join(", ");
+/** Who acts at `doc`: its scripted actor, or a check's own script under `checks: "run"`. A stall has none. */
+const actorAt = (doc, actors, checks) => {
+	if (doc.kind === "stalled") return {
+		scripted: false,
+		actor: void 0
+	};
+	if (Object.hasOwn(actors, doc.state)) return {
+		scripted: true,
+		actor: actors[doc.state]
+	};
+	return {
+		scripted: false,
+		actor: checks === "run" && doc.actor === "check" ? runsItsScript : void 0
+	};
+};
+/** A strict drive's rest: refused at an unscripted check step, or with an actor no drive reached. */
+const strictRest = (doc, actors, reached) => {
+	if (doc.kind !== "stalled" && doc.actor === "check") throw new Error(`strict drive: check step "${doc.state}" has no actor — script it, or drive with checks: "run"`);
+	const never = reached === void 0 ? [] : Object.keys(actors).filter((step) => !reached.has(step));
+	if (never.length > 0) throw new Error(`strict drive: the process rests at "${doc.state}", and never reached the actors for ${quoted(never)} — script a step only for the drive that reaches it`);
+	return doc;
+};
+const refuseVerdict = (doc, returned) => {
+	if (doc.actor !== "judge" && returned !== void 0) throw new Error(`strict drive: the actor for ${doc.actor} step "${doc.state}" returned a verdict; only a judge step takes one`);
+};
+const refuseNothingLanded = (doc, nothing) => {
+	if (doc.actor === "human" && nothing) throw new Error(`strict drive: the actor for human step "${doc.state}" changed nothing, so nothing landed and the drive would repeat the step`);
+};
 const testRepo = (options) => {
 	const repo = new InMemRepo();
 	const env = { ...options.env };
 	const { workflow } = options;
 	const id = `module-${++registered}`;
-	repo.writeFile("gtd.config.ts", typeof workflow === "string" ? workflow : moduleSource(id, workflow));
+	const modules = Object.entries(options.modules ?? {});
+	const moduleKey = (specifier) => `${id}:${specifier}`;
+	repo.writeFile("gtd.config.ts", typeof workflow !== "string" ? moduleSource(id, workflow) : modules.length === 0 ? workflow : importsFrom(workflow, options.modules, (specifier) => lookup(moduleKey(specifier))));
 	for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content);
 	repo.seedCommit("chore: initial commit");
 	const canned = [...options.commands ?? []];
-	const commands = { get: (command) => {
-		const hit = canned.find(({ run }) => typeof run === "string" ? run === command : run.test(command));
+	const table = (first = []) => ({ get: (command) => {
+		const hit = [...first, ...canned].find(({ run }) => typeof run === "string" ? run === command : run.test(command));
 		if (hit === void 0) return void 0;
 		const { exit = 0, output = "", effect } = hit;
 		return {
@@ -32066,10 +32197,16 @@ const testRepo = (options) => {
 			output,
 			effect: () => effect?.(self)
 		};
-	} };
+	} });
+	const commands = table();
+	const seenEnv = () => options.ambientFlags === false ? {
+		...Object.fromEntries(Object.keys(process.env).filter((name) => name.startsWith("GTD_FLAG_")).map((name) => [name, void 0])),
+		...env
+	} : env;
 	const gtd = async (...args) => {
-		const { io, result } = makeCapturingCliIo(repo, env);
+		const { io, result } = makeCapturingCliIo(repo, seenEnv());
 		if (typeof workflow !== "string") registry().set(id, workflow);
+		for (const [specifier, module] of modules) registry().set(moduleKey(specifier), module);
 		try {
 			await runPromise(runCli([
 				"node",
@@ -32078,6 +32215,7 @@ const testRepo = (options) => {
 			], io));
 		} finally {
 			registry().delete(id);
+			for (const [specifier] of modules) registry().delete(moduleKey(specifier));
 		}
 		return result();
 	};
@@ -32101,10 +32239,10 @@ const testRepo = (options) => {
 		if (!applied.ok) throw new Error(`${what}: its script failed — ${applied.error ?? ""}`);
 	};
 	/** Runs a write command, then the script its `--json=script` twin prints. */
-	const runWrite = async (args, stdin) => {
+	const runWrite = async (args, stdin, refused = (error) => error) => {
 		const call = (...extra) => stdin === void 0 ? gtd(...args, ...extra) : withStdin(stdin, () => gtd(...args, ...extra));
 		const reported = await call();
-		if (reported.exitCode !== 0) throw failed(`gtd ${args.join(" ")}`, reported);
+		if (reported.exitCode !== 0) throw refused(failed(`gtd ${args.join(" ")}`, reported));
 		const script = await call("--json=script");
 		apply(`gtd ${args.join(" ")}`, script.stdout);
 		return reported;
@@ -32121,19 +32259,42 @@ const testRepo = (options) => {
 		return JSON.parse(result.stdout);
 	};
 	/** Lands what an actor did: a judge's verdict answered, anything else validated and landed. */
-	const act = async (doc, verdict) => {
+	const act = async (doc, returned) => {
 		if (doc.actor !== "judge") {
 			if (doc.validate !== void 0) apply(`validating ${doc.file ?? doc.state}`, doc.validate);
 			await runWrite(["land"]);
 			return;
 		}
-		if (typeof verdict !== "string") throw new Error(`the actor for judge step "${doc.state}" returned no verdict`);
-		await runWrite(["judge", "answer"], verdict);
+		const actor = `the actor for judge step "${doc.state}"`;
+		if (returned === void 0) throw new Error(`${actor} returned no verdict\n${expectedVerdict(doc)}`);
+		const sent = isVerdict(returned) ? JSON.stringify(returned.answers) : returned;
+		if (typeof sent !== "string") throw new Error(`${actor} returned ${Array.isArray(sent) ? "an array" : typeof sent === "object" ? "an object" : `a ${typeof sent}`}, not a JSON string — JSON.stringify it\n${expectedVerdict(doc)}`);
+		await runWrite(["judge", "answer"], sent, (error) => /* @__PURE__ */ new Error(`${actor} sent a verdict gtd refused:\n${sent}\n${expectedVerdict(doc)}\n${error.message}`));
+	};
+	const reached = /* @__PURE__ */ new Set();
+	/** One beat of a drive: the beat it rests at, or `undefined` to read the next. */
+	const beat = async (doc, actors, { strict = true, checks, unreachedActors = "fail" }) => {
+		if (doc.kind === "capture") {
+			await runWrite(["land"]);
+			return;
+		}
+		const { scripted, actor } = actorAt(doc, actors, checks);
+		if (actor === void 0) return strict ? strictRest(doc, actors, unreachedActors === "fail" ? reached : void 0) : doc;
+		if (scripted) reached.add(doc.state);
+		const returned = await actor(doc, self);
+		if (strict) refuseVerdict(doc, returned);
+		const before = repo.commitHistory().length;
+		await act(doc, returned);
+		if (strict) refuseNothingLanded(doc, repo.commitHistory().length === before);
 	};
 	const self = {
 		command: (command) => {
 			canned.push(command);
 		},
+		setEnv: (name, value) => {
+			if (value === void 0) delete env[name];
+			else env[name] = value;
+		},
 		branch: (name, ref = "HEAD") => repo.createBranch(name, ref),
 		checkout: (name) => repo.checkoutBranch(name),
 		ref: (name, ref = "HEAD") => {
@@ -32148,43 +32309,47 @@ const testRepo = (options) => {
 		remove: (path) => repo.deleteFile(path),
 		commit: (message) => repo.seedCommit(message),
 		show: (ref, path) => repo.fileAtRef(ref, path) ?? void 0,
-		runScript: (script) => {
-			const flow = applyFlowScript(repo, commands, script);
-			if (flow === void 0) runLines(repo, commands, script);
+		runScript: (script, { commands: first = [] } = {}) => {
+			const scriptCommands = first.length === 0 ? commands : table(first);
+			const flow = applyFlowScript(repo, scriptCommands, script);
+			if (flow === void 0) runLines(repo, scriptCommands, script);
 			else if (!flow.ok) throw new Error(`testkit: ${flow.error ?? ""}`);
 		},
 		gtd,
-		start: (workflow, ...args) => begin([
-			"--workflow",
-			workflow,
+		start: (name, ...args) => begin([
+			"start",
+			name,
 			...args
 		]),
 		door: (name, ...args) => begin([
-			"door",
+			"start",
 			name,
 			...args
 		]),
 		land: () => runWrite(["land"]),
 		next,
-		drive: async (actors = {}, { maxBeats = 50 } = {}) => {
-			for (let beat = 0; beat < maxBeats; beat++) {
+		drive: async (actors = {}, options = {}) => {
+			const { maxBeats = 50 } = options;
+			const passed = [];
+			for (let n = 0; n < maxBeats; n++) {
 				const doc = await next();
-				if (doc.kind === "stalled") return doc;
-				if (doc.kind === "capture") {
-					await runWrite(["land"]);
-					continue;
-				}
-				const actor = actors[doc.state];
-				if (actor === void 0) return doc;
-				await act(doc, await actor(doc, self));
+				passed.push(doc.state);
+				const rest = await beat(doc, actors, options);
+				if (rest !== void 0) return rest;
 			}
-			throw new Error(`the process did not rest within ${maxBeats} beats`);
+			throw new Error(`the process did not rest within ${maxBeats} beats; it passed through:\n${passed.join(" → ")}`);
 		},
 		subjects: () => repo.commitHistory().map(({ message }) => message.split("\n")[0] ?? ""),
 		messages: () => repo.commitHistory().map(({ message }) => message),
-		hashes: () => repo.commitHistory().map(({ hash }) => hash)
+		hashes: () => repo.commitHistory().map(({ hash }) => hash),
+		commits: () => repo.commitHistory().map(({ hash, message }) => ({
+			hash,
+			subject: message.split("\n")[0] ?? "",
+			message,
+			trailers: trailersOf(message)
+		}))
 	};
 	return self;
 };
 //#endregion
-export { testRepo as n, InMemRepo as r, runsItsScript as t };
+export { verdictWhen as a, verdict as i, runsItsScript as n, whenPrompted as o, testRepo as r, inTurn as t };