projectstore-claude 0.29.2 → 0.29.4

package/node_modules/projectstore/scripts/cli.mjs

@@ -14,11 +14,24 @@
 // command files and the tests depend on it). Exit codes: 0 ok, 1 findings or
 // a refusal, 2 usage or an internal failure, 3 not bound.
 //
+// The parse is per verb. A scan finds the verb first, knowing only the
+// globals (--project <dir>, --json, --help/-h, --version/-v — the only options
+// that may come before it); then one strict parseArgs runs on that verb's row
+// plus the globals, so one name can be a flag on one verb and take a value on
+// another (`doctor --vault` beside the front-door ADR's `setup --vault
+// <path>`). A row's `usage` forms are both its help's Usage lines and the
+// bound on its arguments: an argument past the form is a usage error that
+// names it, never dropped. Every error raised before a verb runs names the
+// verb the scan found, in the envelope and on stderr.
+//
 // The gate (distribution ADR decision 6) binds every write verb this bin
 // exposes: the install family through install-harness.mjs's own preview and
 // confirmation, and `reconcile --write` through the same rule — naming what
 // is written (`--only <target>`) is the non-interactive confirmation, a bare
-// `--write` asks on a terminal and refuses without one. There is no --yes.
+// `--write` asks on a terminal and refuses without one. `scaffold --write`
+// differs on purpose: its write set is closed — create-only, what the layout
+// declares, in the vault the binding names — so it asks at a terminal and,
+// without one, `--write` is the confirmation. There is no --yes.
 //
 // The project is resolved once, here — --project, then the neutral
 // PROJECTSTORE_PROJECT_DIR, then a project-dir variable a harness declared,
@@ -42,13 +55,64 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import * as term from "./term.mjs";
-import { projectRootDeclared, childEnv, harnessIds, harnessForOverlay, pinPluginRoot } from "./harness.mjs";
-import { readConfigAt, readOverlayAt, resolveAgentModel, writeOverlayAt, overlayId, layoutRoster, commandForm, projectDirRefusal } from "./lib.mjs";
-import { READ_OPERATIONS, LINEAGE_KINDS, LINEAGE_DEFAULT_DEPTH, SEARCH_DEFAULT_LIMIT, GRAPH_EDGE_CAP, DIRECTIONS } from "./query.mjs";
-// binding.mjs is a write module imported statically where the install family
-// is lazy: it is a dependency-free leaf with no side effects, so the MCP
-// server's module graph gains nothing it could trip on.
-import { planBind, applyBind, renderBindPlan, bindResult, DEFAULT_LAYOUT, DEFAULT_LANGUAGE } from "./binding.mjs";
+import {
+  projectRootDeclared,
+  childEnv,
+  harnessIds,
+  harnessForOverlay,
+  pinPluginRoot,
+  invokedAs,
+  shellHarnessId,
+  CORE_NPX,
+  packageCommand,
+  loadHarnesses,
+  invocation,
+} from "./harness.mjs";
+import {
+  readConfigAt,
+  readOverlayAt,
+  resolveAgentModel,
+  writeOverlayAt,
+  overlayId,
+  layoutRoster,
+  commandForm,
+  projectDirRefusal,
+  fromTerminalIn,
+  doctorFallbackText,
+  refreshSessionPointer,
+} from "./lib.mjs";
+import {
+  READ_OPERATIONS,
+  LINEAGE_KINDS,
+  LINEAGE_DEFAULT_DEPTH,
+  SEARCH_DEFAULT_LIMIT,
+  GRAPH_EDGE_CAP,
+  DIRECTIONS,
+} from "./query.mjs";
+// binding.mjs and scaffold.mjs beneath it are write modules imported
+// statically where the install family is lazy: dependency-free, with no side
+// effects at import, so the MCP server's module graph gains nothing it could
+// trip on.
+import {
+  planBind,
+  applyBind,
+  renderBindPlan,
+  bindResult,
+  bindFailed,
+  normaliseVaultPath,
+  shellQuote,
+  DEFAULT_LAYOUT,
+  DEFAULT_LANGUAGE,
+} from "./binding.mjs";
+import { planScaffold, applyScaffold, scaffoldResult, renderScaffoldPlan } from "./scaffold.mjs";
+import {
+  planBand,
+  applyBand,
+  bandStatus,
+  renderBandStatus,
+  renderBandPlan,
+  SUBCOMMANDS as BAND_SUBCOMMANDS,
+} from "./band.mjs";
 
 export const SCHEMA_VERSION = 1;
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -56,7 +120,11 @@ export const PACKAGE_ROOT = dirname(HERE);
 const script = (name) => resolve(HERE, name);
 
 export function packageVersion() {
-  try { return String(JSON.parse(readFileSync(resolve(PACKAGE_ROOT, "package.json"), "utf8")).version || ""); } catch { return ""; }
+  try {
+    return String(JSON.parse(readFileSync(resolve(PACKAGE_ROOT, "package.json"), "utf8")).version || "");
+  } catch {
+    return "";
+  }
 }
 
 export function envelope(verb, project, ok, result) {
@@ -79,114 +147,441 @@ export function resolveProject({ project = null, env = process.env, cwd = proces
 // wraps: "script" (spawned), "module" (imported), "new" (code that exists
 // only for the CLI). output: "envelope" (--json wraps), "text". mcp: the MCP
 // tools that mirror the verb (MCP ADR decision 2), empty when none.
+// options: the row's parser — opt()'s arg is the type (false a flag, a
+// placeholder a value), multiple the repetition. usage: the forms the help
+// prints after the verb, verbatim, which also bound its arguments: a literal
+// sub-word (`neighbors`), a <placeholder> (`<phrase…>` takes the rest), or a
+// --name the form requires (its placeholder is the option's value, not an
+// argument). NO_FORMS: the verb takes no argument.
 
-const opt = (name, arg, summary, multiple = false) => Object.freeze({ name, arg, summary, multiple });
+export const opt = (name, arg, summary, multiple = false) => Object.freeze({ name, arg, summary, multiple });
 const JSON_OPT = opt("json", false, "the envelope");
+// The options every verb takes, and the only ones that may come before the
+// verb: the scan knows their arity before it knows the verb (--project takes
+// a value, the rest do not). Last in every parser map, so a row cannot
+// retype one. SHORT is their one-letter forms (`-hv`: version wins).
+const GLOBAL_OPTS = Object.freeze([
+  opt("project", "<dir>", "the project"),
+  JSON_OPT,
+  opt("help", false, "the help"),
+  opt("version", false, "the package version"),
+]);
+const SHORT = Object.freeze({ help: "h", version: "v" });
+const NO_FORMS = Object.freeze([]);
 const READ_JSON = [JSON_OPT];
-const HARNESS_OPT = opt("harness", "<id>", "the harness — and, without a terminal, the confirmation (a terminal is asked); there is no --yes", true);
+const HARNESS_OPT = opt(
+  "harness",
+  "<id>",
+  "the harness — and, without a terminal, the confirmation (a terminal is asked); there is no --yes",
+  true,
+);
 const SURFACE_OPT = opt("surface", "<key>", "one surface and those beneath it", true);
 // The layout move's remedy names this for any copy but the package's own
 // registration (the layout spec, contract 12 as amended 2026-10-03): it makes
 // "no host command" true by construction instead of by recognising the root.
-const NO_REGISTER_OPT = opt("no-register", false, "leave the plugin registration alone: change only this project's files");
+const NO_REGISTER_OPT = opt(
+  "no-register",
+  false,
+  "leave the plugin registration alone: change only this project's files",
+);
 const VERBOSE_OPT = opt("verbose", false, "every row's reasoning, each step's why and the host's own notes");
+// doctor's --verbose is the same flag in its own words: on a terminal, the
+// report the pipe gets — every note, every instance, each message whole.
+const DOCTOR_VERBOSE_OPT = opt(
+  VERBOSE_OPT.name,
+  VERBOSE_OPT.arg,
+  "on a terminal too: every note, every instance, whole messages",
+);
 const INSTALL_OPTS = [HARNESS_OPT, SURFACE_OPT, NO_REGISTER_OPT, VERBOSE_OPT, JSON_OPT];
-const UNINSTALL_OPTS = [HARNESS_OPT, SURFACE_OPT, opt("global", false, "also remove the harness-global plugin registration"), VERBOSE_OPT, JSON_OPT];
+const UNINSTALL_OPTS = [
+  HARNESS_OPT,
+  SURFACE_OPT,
+  opt("global", false, "also remove the harness-global plugin registration"),
+  VERBOSE_OPT,
+  JSON_OPT,
+];
+
+// setup's own options (the setup story, rule 1): seven, beside the globals.
+// `--vault <path>` takes a value here where doctor's `--vault` is a flag —
+// the per-verb parse's own case.
+const SETUP_OPTS = [
+  HARNESS_OPT,
+  opt(
+    "vault",
+    "<path>",
+    "the vault: an existing folder is bound, a missing or empty one is created (naming it confirms)",
+  ),
+  opt("layout", "<name>", `a new vault's layout (default ${DEFAULT_LAYOUT})`),
+  opt("language", "<code>", `a new vault's template language (default ${DEFAULT_LANGUAGE})`),
+  opt(
+    "channel",
+    "<npm|git>",
+    "with a git-marketplace copy enabled, without a terminal: npm switches to the npm install, git keeps the git marketplace",
+  ),
+  opt("dry-run", false, "the questions and the plan; nothing is written or fetched"),
+  VERBOSE_OPT,
+];
 
 export const VERBS = Object.freeze([
   Object.freeze({
-    verb: "doctor", summary: "Check the install wiring and the vault's consistency.",
-    module: "./doctor.mjs", wraps: "script", how: "spawn", output: "envelope", writes: false, requiresBinding: false, mcp: Object.freeze(["doctor"]),
-    options: [opt("install", false, "only the install section"), opt("vault", false, "only the vault section"), JSON_OPT],
+    verb: "setup",
+    summary: "Set up this project: every harness it uses, and a vault.",
+    usage: NO_FORMS,
+    module: "./setup.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: [...SETUP_OPTS, JSON_OPT],
+    run: runSetupVerb,
+  }),
+  Object.freeze({
+    verb: "doctor",
+    summary: "Check the install wiring and the vault's consistency.",
+    usage: NO_FORMS,
+    module: "./doctor.mjs",
+    wraps: "script",
+    how: "spawn",
+    output: "envelope",
+    writes: false,
+    requiresBinding: false,
+    mcp: Object.freeze(["doctor"]),
+    options: [
+      opt("install", false, "only the install section"),
+      opt("vault", false, "only the vault section"),
+      DOCTOR_VERBOSE_OPT,
+      JSON_OPT,
+    ],
     run: runDoctor,
   }),
   Object.freeze({
-    verb: "reconcile", summary: "Regenerate the derived views (kanban, code map, graph, indexes).",
-    module: "./reconcile.mjs", wraps: "module", how: "import", output: "envelope", writes: true, requiresBinding: true, mcp: Object.freeze([]),
-    options: [opt("write", false, "apply the regeneration (asks on a terminal; --only names what is written and confirms headless)"), opt("only", "<target>", "one derived view"), JSON_OPT],
+    verb: "reconcile",
+    summary: "Regenerate the derived views (kanban, code map, graph, indexes).",
+    usage: NO_FORMS,
+    module: "./reconcile.mjs",
+    wraps: "module",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: true,
+    mcp: Object.freeze([]),
+    options: [
+      opt(
+        "write",
+        false,
+        "apply the regeneration (asks on a terminal; --only names what is written and confirms headless)",
+      ),
+      opt("only", "<target>", "one derived view"),
+      JSON_OPT,
+    ],
     run: runReconcile,
   }),
   Object.freeze({
-    verb: "plan", summary: "Show what install would write for a harness, without writing.",
-    module: "./install-harness.mjs", wraps: "module", how: "import", output: "envelope", writes: false, requiresBinding: false, mcp: Object.freeze([]),
-    options: INSTALL_OPTS, run: runInstallVerb,
+    verb: "plan",
+    summary: "Show what install would write for a harness, without writing.",
+    usage: NO_FORMS,
+    module: "./install-harness.mjs",
+    wraps: "module",
+    how: "import",
+    output: "envelope",
+    writes: false,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: INSTALL_OPTS,
+    run: runInstallVerb,
   }),
   Object.freeze({
-    verb: "install", summary: "Install projectstore's surfaces for a harness, behind a preview.",
-    module: "./install-harness.mjs", wraps: "module", how: "import", output: "envelope", writes: true, requiresBinding: false, mcp: Object.freeze([]),
-    options: INSTALL_OPTS, run: runInstallVerb,
+    verb: "install",
+    summary: "Install projectstore's surfaces for a harness, behind a preview.",
+    usage: NO_FORMS,
+    module: "./install-harness.mjs",
+    wraps: "module",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: INSTALL_OPTS,
+    run: runInstallVerb,
   }),
   Object.freeze({
-    verb: "uninstall", summary: "Remove what install wrote, and only that.",
-    module: "./install-harness.mjs", wraps: "module", how: "import", output: "envelope", writes: true, requiresBinding: false, mcp: Object.freeze([]),
-    options: UNINSTALL_OPTS, run: runInstallVerb,
+    verb: "uninstall",
+    summary: "Remove what install wrote, and only that.",
+    usage: NO_FORMS,
+    module: "./install-harness.mjs",
+    wraps: "module",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: UNINSTALL_OPTS,
+    run: runInstallVerb,
   }),
   Object.freeze({
-    verb: "upgrade", summary: "Re-run install after a plugin update; re-stamps what this installation wrote and leaves the rest.",
-    module: "./install-harness.mjs", wraps: "module", how: "import", output: "envelope", writes: true, requiresBinding: false, mcp: Object.freeze([]),
-    options: INSTALL_OPTS, run: runInstallVerb,
+    verb: "upgrade",
+    summary: "After an update, refresh what install wrote and leave the rest.",
+    usage: NO_FORMS,
+    module: "./install-harness.mjs",
+    wraps: "module",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: INSTALL_OPTS,
+    run: runInstallVerb,
   }),
   Object.freeze({
-    verb: "status", summary: "The binding, what is in progress, and whether the derived views are fresh.",
-    module: "./query.mjs", wraps: "new", how: "import", output: "envelope", writes: false, requiresBinding: false, mcp: Object.freeze(["status"]),
-    options: READ_JSON, run: runRead("status"),
+    verb: "status",
+    summary: "What is bound, what is in progress, and whether views are fresh.",
+    usage: NO_FORMS,
+    module: "./query.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: false,
+    requiresBinding: false,
+    mcp: Object.freeze(["status"]),
+    options: READ_JSON,
+    run: runRead("status"),
   }),
   Object.freeze({
-    verb: "orientation", summary: "The SessionStart skeleton and the facts behind it.",
-    module: "./query.mjs", wraps: "module", how: "import", output: "envelope", writes: false, requiresBinding: true, mcp: Object.freeze(["orientation"]),
-    options: READ_JSON, run: runRead("orientation"),
+    verb: "orientation",
+    summary: "The SessionStart skeleton and the facts behind it.",
+    usage: NO_FORMS,
+    module: "./query.mjs",
+    wraps: "module",
+    how: "import",
+    output: "envelope",
+    writes: false,
+    requiresBinding: true,
+    mcp: Object.freeze(["orientation"]),
+    options: READ_JSON,
+    run: runRead("orientation"),
   }),
   Object.freeze({
-    verb: "search", summary: "Find a phrase in the vault's artifacts — deterministic, bounded, no shell.",
-    module: "./query.mjs", wraps: "new", how: "import", output: "envelope", writes: false, requiresBinding: true, mcp: Object.freeze(["search"]),
-    options: [opt("kind", "<type>", "only artifacts of this kind", true), opt("status", "<status>", "only artifacts in this status"), opt("limit", "<n>", `at most n matches (default ${SEARCH_DEFAULT_LIMIT}, hard cap 100)`), opt("include-derived", false, "search the derived views too"), opt("case-sensitive", false, "match case"), JSON_OPT],
+    verb: "search",
+    summary: "Find a phrase in the vault's artifacts, literal and bounded.",
+    usage: Object.freeze(["<phrase…>"]),
+    module: "./query.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: false,
+    requiresBinding: true,
+    mcp: Object.freeze(["search"]),
+    options: [
+      opt("kind", "<type>", "only artifacts of this kind", true),
+      opt("status", "<status>", "only artifacts in this status"),
+      opt("limit", "<n>", `at most n matches (default ${SEARCH_DEFAULT_LIMIT}, hard cap 100)`),
+      opt("include-derived", false, "search the derived views too"),
+      opt("case-sensitive", false, "match case"),
+      JSON_OPT,
+    ],
     run: runRead("search"),
   }),
   Object.freeze({
-    verb: "show", summary: "One artifact: its frontmatter, and its body or one section on request.",
-    module: "./query.mjs", wraps: "module", how: "import", output: "envelope", writes: false, requiresBinding: true, mcp: Object.freeze(["get_artifact"]),
-    options: [opt("body", false, "include the body"), opt("section", "<id>", "one section by its registry id (description, acceptance, …)"), JSON_OPT],
+    verb: "show",
+    summary: "One artifact's frontmatter; its body or a section on request.",
+    usage: Object.freeze(["<path>"]),
+    module: "./query.mjs",
+    wraps: "module",
+    how: "import",
+    output: "envelope",
+    writes: false,
+    requiresBinding: true,
+    mcp: Object.freeze(["get_artifact"]),
+    options: [
+      opt("body", false, "include the body"),
+      opt("section", "<id>", "one section by its registry id (description, acceptance, …)"),
+      JSON_OPT,
+    ],
     run: runRead("show"),
   }),
   Object.freeze({
-    verb: "graph", summary: "graph neighbors <path> | graph lineage <path> — the live link graph by vault path.",
-    module: "./query.mjs", wraps: "new", how: "import", output: "envelope", writes: false, requiresBinding: true, mcp: Object.freeze(["neighbors", "lineage"]),
-    options: [opt("kind", "<edge-kind>", "only edges of this kind (lineage: one of its four)", true), opt("direction", DIRECTIONS.join("|"), "neighbors: which edges"), opt("depth", "<n>", `lineage: how far (default ${LINEAGE_DEFAULT_DEPTH})`), opt("limit", "<n>", `neighbors: cap per direction (≤ ${GRAPH_EDGE_CAP})`), JSON_OPT],
+    verb: "graph",
+    summary: "The live link graph by vault path.",
+    usage: Object.freeze(["neighbors <path>", "lineage <path>"]),
+    module: "./query.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: false,
+    requiresBinding: true,
+    mcp: Object.freeze(["neighbors", "lineage"]),
+    options: [
+      opt("kind", "<edge-kind>", "only edges of this kind (lineage: one of its four)", true),
+      opt("direction", DIRECTIONS.join("|"), "neighbors: which edges"),
+      opt("depth", "<n>", `lineage: how far (default ${LINEAGE_DEFAULT_DEPTH})`),
+      opt("limit", "<n>", `neighbors: cap per direction (at most ${GRAPH_EDGE_CAP})`),
+      JSON_OPT,
+    ],
     run: runGraph,
   }),
   Object.freeze({
-    verb: "codemap", summary: "codemap --for <selector> — which code an epic or artifact maps to, or which artifacts map to a path.",
-    module: "./query.mjs", wraps: "new", how: "import", output: "envelope", writes: false, requiresBinding: true, mcp: Object.freeze(["code_refs"]),
-    options: [opt("for", "<selector>", "an epic id, an artifact, or a repo path"), opt("reverse", false, "read the selector as a path even if it names an artifact"), JSON_OPT],
+    verb: "codemap",
+    summary: "The code an epic or artifact maps to, or a path's artifacts.",
+    usage: Object.freeze(["--for <selector>"]),
+    module: "./query.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: false,
+    requiresBinding: true,
+    mcp: Object.freeze(["code_refs"]),
+    options: [
+      opt("for", "<selector>", "an epic id, an artifact, or a repo path"),
+      opt("reverse", false, "read the selector as a path even if it names an artifact"),
+      JSON_OPT,
+    ],
     run: runCodemap,
   }),
   Object.freeze({
-    verb: "agents", summary: "agents model <name> | agents show | agents configure — the harness overlay's agents block (ADR-008, read per invocation).",
-    module: "./lib.mjs", wraps: "new", how: "import", output: "envelope", writes: true, requiresBinding: false, mcp: Object.freeze([]),
-    options: [opt("harness", "<id>", "configure: the overlay to write — and, non-interactively, the confirmation; there is no --yes", true), opt("default", "<model>", "configure: agents.default.model (pins the clerk to sonnet unless --agent clerk=… says otherwise; an empty model clears it)"), opt("agent", "<name>=<model>", "configure: agents.per_agent.<name>.model (an empty model removes the key)", true), opt("reset", false, "configure: empty the agents block first; --default and --agent given with it apply on top"), JSON_OPT],
+    verb: "agents",
+    summary: "The harness overlay's agents block: the model each agent runs.",
+    usage: Object.freeze(["model <name>", "show", "configure"]),
+    module: "./lib.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: [
+      opt(
+        "harness",
+        "<id>",
+        "configure: the overlay to write — and, non-interactively, the confirmation; there is no --yes",
+        true,
+      ),
+      opt(
+        "default",
+        "<model>",
+        "configure: agents.default.model (pins the clerk to sonnet unless --agent clerk=… says otherwise; an empty model clears it)",
+      ),
+      opt("agent", "<name>=<model>", "configure: agents.per_agent.<name>.model (an empty model removes the key)", true),
+      opt("reset", false, "configure: empty the agents block first; --default and --agent given with it apply on top"),
+      JSON_OPT,
+    ],
     run: runAgents,
   }),
   Object.freeze({
-    verb: "bind", summary: "bind <vault> — bind this project to an existing vault (naming the vault is the confirmation).",
-    module: "./binding.mjs", wraps: "new", how: "import", output: "envelope", writes: true, requiresBinding: false, mcp: Object.freeze([]),
-    options: [opt("layout", "<name>", `the layout (default ${DEFAULT_LAYOUT})`), opt("language", "<code>", `the template language (default ${DEFAULT_LANGUAGE})`), opt("rebind", false, "point an already bound project at another vault; every other setting is kept"), JSON_OPT],
+    verb: "band",
+    summary: "The band above the prompt: switch it, pin an epic, ask why.",
+    usage: Object.freeze(["on", "off", "status", "epic <ID>"]),
+    module: "./band.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: true,
+    mcp: Object.freeze([]),
+    options: [JSON_OPT],
+    run: runBand,
+  }),
+  Object.freeze({
+    verb: "session",
+    summary: "Refresh this session's current story from its file.",
+    usage: Object.freeze(["refresh <path>"]),
+    module: "./lib.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: true,
+    mcp: Object.freeze([]),
+    options: [JSON_OPT],
+    run: runSession,
+  }),
+  Object.freeze({
+    verb: "bind",
+    summary: "Bind this project to an existing vault; naming it confirms.",
+    usage: Object.freeze(["<vault>"]),
+    module: "./binding.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: [
+      opt("layout", "<name>", `the layout (default ${DEFAULT_LAYOUT})`),
+      opt("language", "<code>", `the template language (default ${DEFAULT_LANGUAGE})`),
+      opt("rebind", false, "point an already bound project at another vault; every other setting is kept"),
+      JSON_OPT,
+    ],
     run: runBind(false),
   }),
   Object.freeze({
-    verb: "init", summary: `init <vault> — create the vault directory and bind to it; the layout's folders come from ${commandForm("scaffold")}.`,
-    module: "./binding.mjs", wraps: "new", how: "import", output: "envelope", writes: true, requiresBinding: false, mcp: Object.freeze([]),
-    options: [opt("layout", "<name>", `the layout (default ${DEFAULT_LAYOUT})`), opt("language", "<code>", `the template language (default ${DEFAULT_LANGUAGE})`), opt("rebind", false, "an already bound project: create the new vault and point the project at it; every other setting is kept"), JSON_OPT],
+    verb: "init",
+    summary: "Create a vault (folder, git repository, READMEs) and bind to it.",
+    usage: Object.freeze(["<vault>"]),
+    module: "./binding.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: [
+      opt("layout", "<name>", `the layout (default ${DEFAULT_LAYOUT})`),
+      opt("language", "<code>", `the template language (default ${DEFAULT_LANGUAGE})`),
+      opt(
+        "rebind",
+        false,
+        "an already bound project: create the new vault and point the project at it; every other setting is kept",
+      ),
+      JSON_OPT,
+    ],
     run: runBind(true),
   }),
   Object.freeze({
-    verb: "mcp", summary: "Serve the read tools over MCP (stdio) for the project named by --project or PROJECTSTORE_PROJECT_DIR; never the ambient cwd.",
-    module: "./mcp.mjs", wraps: "new", how: "import", output: "text", writes: false, requiresBinding: false, mcp: Object.freeze([]),
-    options: [], run: runMcp,
+    verb: "scaffold",
+    summary: "Create the vault's missing folders and READMEs; rewrite nothing.",
+    usage: NO_FORMS,
+    module: "./scaffold.mjs",
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: true,
+    requiresBinding: true,
+    mcp: Object.freeze([]),
+    options: [
+      opt("write", false, "create them (asks at a terminal; without one, --write is the confirmation)"),
+      JSON_OPT,
+    ],
+    run: runScaffold,
+  }),
+  Object.freeze({
+    verb: "mcp",
+    summary: "Serve the read tools over MCP (stdio) for the project you name.",
+    usage: NO_FORMS,
+    module: "./mcp.mjs",
+    wraps: "new",
+    how: "import",
+    output: "text",
+    writes: false,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: [],
+    run: runMcp,
   }),
   Object.freeze({
-    verb: "version", summary: "Print the package version (also --version).",
-    module: null, wraps: "new", how: "import", output: "envelope", writes: false, requiresBinding: false, mcp: Object.freeze([]),
-    options: [JSON_OPT], run: runVersion,
+    verb: "version",
+    summary: "Print the package version (also --version).",
+    usage: NO_FORMS,
+    module: null,
+    wraps: "new",
+    how: "import",
+    output: "envelope",
+    writes: false,
+    requiresBinding: false,
+    mcp: Object.freeze([]),
+    options: [JSON_OPT],
+    run: runVersion,
   }),
 ]);
 
@@ -196,24 +591,60 @@ export const VERBS = Object.freeze([
 // story that adds a verb in slices.
 export const PLANNED_VERBS = Object.freeze([]);
 
-// The verbs as a person meets them: setting a project up, reading the vault,
-// keeping it consistent, serving it. A verb not listed lands in "Other", so a
-// new row is never hidden by this table.
+// The verbs as a person meets them (presentation spec contract 10): starting,
+// reading the vault, keeping it consistent. Every verb not listed here is
+// ADVANCED, one line of names in table order — so a new row is never hidden
+// by this table, and init and scaffold, which the contract names in no group,
+// are there too. A group lists only the verbs this run's table has. With
+// setup, START is setup and uninstall, and install and bind are ADVANCED's
+// (contract 10; the setup story, rule 1).
 const HELP_GROUPS = [
-  ["Set up", ["install", "upgrade", "uninstall", "plan", "bind", "init", "agents"]],
-  ["Read", ["status", "search", "show", "graph", "codemap", "orientation"]],
-  ["Check and repair", ["doctor", "reconcile"]],
-  ["Serve", ["mcp", "version"]],
+  ["START", ["setup", "uninstall"]],
+  ["VAULT", ["status", "search", "show", "graph", "codemap"]],
+  ["CHECK AND REPAIR", ["doctor", "reconcile", "upgrade"]],
 ];
+// The column a group's summaries start at: two spaces, the verb in twelve,
+// one space. A summary fits 80 columns from there, so each is at most 65
+// characters, in ASCII (tests/presentation.test.mjs, criterion 5, holds every
+// row to it).
+const VERB_COLUMN = 12;
+export const SUMMARY_MAX = 80 - (2 + VERB_COLUMN + 1);
 
-// Examples per verb. `{cmd}` is how this run was invoked (a shell's own name
-// when PROJECTSTORE_SHELL says so, else the core — a shell passes the read
-// verbs through, so its name serves them too), `{h}` the harness argument the
-// core needs and a shell fixes.
+// Examples per verb. They are what to run next, so they are the core's form
+// through a shell too (the story "User-facing text says where to run and
+// names no project path and no shell", rule 6): `{cmd}` is the core through
+// npx, and `{h}` the harness argument — ` --harness <id>` from the core, and
+// through a shell ` --harness <the shell's own harness>` (shellHarnessId),
+// never a session's identity. `{fixed}` is that argument through a shell
+// only: the shell inserts --harness for every verb that declares it
+// (packaging/shells.mjs, HARNESS_VERBS), so an example the core runs bare —
+// setup, which asks; agents show, which reads the session's overlay — names
+// the shell's harness through it and stays bare from the core. A `{core}`
+// example is the core's alone: a shell's help leaves it out, since it says
+// what the shell's own harness does not (every harness, the way back from a
+// switch). `{switch.surface}`,
+// `{switch.host}` and `{switch.doctor}` name the harness whose project can
+// switch channels — the one with a host plugin registration — from its
+// manifest: its surface key, its display name and its doctor form
+// (switchHarness, below); an example naming them is left out when no
+// manifest has one.
 const EXAMPLES = {
+  setup: [
+    "{cmd} setup{fixed}",
+    "{cmd} setup{fixed} --dry-run  # the questions and the plan; nothing is written or fetched",
+    "{cmd} setup{h} --vault ~/vaults/my-project  # without a terminal: --harness confirms, --vault names the vault",
+  ],
   install: ["{cmd} install{h}", "{cmd} plan{h}  # the same plan; nothing is written"],
-  upgrade: ["{cmd}@<version> upgrade{h}  # the version you name is the version that runs", "{cmd} upgrade{h} --verbose"],
-  uninstall: ["{cmd} uninstall{h}", "{cmd} uninstall{h} --surface statusline"],
+  upgrade: [
+    "{cmd}@<version> upgrade{h}  # the version you name is the version that runs",
+    "{cmd} upgrade{h} --verbose",
+  ],
+  uninstall: [
+    "{core}{cmd} uninstall  # every harness this project uses",
+    "{cmd} uninstall{h}",
+    "{cmd} uninstall{h} --surface statusline",
+    "{core}{cmd} uninstall{h} --surface {switch.surface}  # back to the git marketplace after a switch, then restart {switch.host} and run {switch.doctor} in it",
+  ],
   plan: ["{cmd} plan{h}", "{cmd} plan{h} --json  # one envelope, for scripts and agents"],
   status: ["{cmd} status", "{cmd} status --json"],
   orientation: ["{cmd} orientation --json"],
@@ -225,93 +656,219 @@ const EXAMPLES = {
   reconcile: ["{cmd} reconcile  # what would change; nothing is written", "{cmd} reconcile --write"],
   bind: ["{cmd} bind ~/vaults/my-project", "{cmd} bind ~/vaults/other --rebind"],
   init: ["{cmd} init ~/vaults/new-project --language ru"],
-  agents: ["{cmd} agents show", "{cmd} agents configure{h} --default opus --agent clerk=sonnet"],
+  scaffold: ["{cmd} scaffold  # what would be created; nothing is written", "{cmd} scaffold --write"],
+  agents: ["{cmd} agents show{fixed}", "{cmd} agents configure{h} --default opus --agent clerk=sonnet"],
+  band: [
+    "{cmd} band status",
+    "{cmd} band off",
+    "{cmd} band epic PS-CORE  # a session with no epic of its own shows this one",
+  ],
+  session: ["{cmd} session refresh epics/PS-CORE/stories/story-x.md --json  # after a write no hook saw"],
   mcp: ['{cmd} mcp --project "$PWD"'],
 };
 
-// Positional arguments a summary does not already name.
-const ARGS = { search: "<phrase>", show: "<path>" };
+// How this run was invoked is invokedAs (harness.mjs), the one spelling of
+// the binary that ran: the help's first line, its Usage lines, the
+// fixed-harness line and the usage errors. What a person runs next is the
+// core's (CORE_NPX, packageCommand), as status's and bind's Next lines are.
 
-// "bind <vault> — bind this project…" names its own form; "graph neighbors
-// <path> | graph lineage <path> — …" names two.
-function forms(row) {
-  const m = /^(.+?) — (.+)$/.exec(row.summary);
-  if (m && m[1].startsWith(row.verb + " ")) {
-    const list = m[1].split(" | ").map((f) => f.replace(new RegExp(`^${row.verb} `), ""));
-    return { forms: list, about: m[2][0].toUpperCase() + m[2].slice(1) };
+// The harness whose project can switch channels (the converge story's rule
+// 4): the one whose manifest declares a host plugin registration. Its surface
+// key, display name and doctor form, from the manifest — `invocation()` in
+// harness.mjs, never a literal; null when no manifest has one.
+function switchHarness() {
+  for (const m of loadHarnesses().values()) {
+    const row = Object.entries(m.surfaces || {}).find(
+      ([k, s]) => !k.startsWith("_") && s?.format === "host-plugin-registration",
+    );
+    if (row)
+      return {
+        "switch.surface": row[0],
+        "switch.host": m.display_name,
+        "switch.doctor": invocation(m, "doctor", { args: "--fix" }),
+      };
   }
-  return { forms: [ARGS[row.verb] || ""], about: row.summary };
-}
-
-function invocation(env = process.env) {
-  const shell = env.PROJECTSTORE_SHELL || null;
-  return { shell, cmd: shell ? `npx ${shell}` : "npx projectstore" };
+  return null;
 }
 
-function optionLines(options) {
-  const rows = options.map((o) => [`--${o.name}${o.arg ? " " + o.arg : ""}`, `${o.summary}${o.multiple ? " (repeatable)" : ""}`]);
+// An aligned options block: each option's form in a column at most 28 wide,
+// its description beside it — or, past that column, on the next line under
+// it. On a live terminal a description wraps with its column as the hanging
+// indent; anywhere else it stays one line, whole, for a reader that greps.
+function optionLines(options, c = term.PLAIN) {
+  const rows = options.map((o) => [
+    term.glyphText(c, `--${o.name}${o.arg ? " " + o.arg : ""}`),
+    term.glyphText(c, `${o.summary}${o.multiple ? " (repeatable)" : ""}`),
+  ]);
   const w = Math.min(28, Math.max(0, ...rows.map(([l]) => l.length)));
-  return rows.map(([l, r]) => (l.length > w ? `  ${l}\n  ${" ".repeat(w)}  ${r}` : `  ${l.padEnd(w)}  ${r}`));
+  const pad = " ".repeat(2 + w + 2);
+  const text = (r) => term.wrap(r, c.live ? c.width : 0, pad);
+  return rows.map(([l, r]) => (l.length > w ? `  ${l}\n${pad}${text(r)}` : `  ${l.padEnd(w)}  ${text(r)}`));
 }
 
-const EXIT_CODES = "Exit codes  0 ok · 1 findings or a refusal · 2 usage · 3 not bound";
+const EXIT_CODES = "0 ok, 1 findings or a refusal, 2 usage, 3 not bound, 130 cancelled";
+// The facts that close a help screen (`Harnesses`, `Exit codes`): the key in
+// the explanation role, its value at one column for both.
+const FACT_KEY = "Exit codes".length;
+const fact = (c, key, value) =>
+  `${term.painter(c)("explanation", key)}${" ".repeat(FACT_KEY - key.length + 2)}${value}`;
+
+// What the bin is, in the help's badge: one line with the name and version,
+// short enough that a prerelease version (0.30.0-rc.12) still fits 80 columns.
+const PURPOSE = "project memory for coding agents, in markdown";
+
+// What a verb's help says beneath its Usage when the summary has no room for
+// it: here, how mcp is told its project.
+const NOTES = {
+  mcp: "It serves the project --project names, else PROJECTSTORE_PROJECT_DIR or the host session's project; never the directory it was started in.",
+};
+
+// The global options, as every verb takes them.
+const EVERY_VERB = Object.freeze([
+  opt("project", "<dir>", "the project (default: the session's, else this directory)"),
+  opt("json", false, "the result as one JSON envelope, for scripts and agents"),
+  opt("version", false, "the package version"),
+]);
 
-export function usage(env = process.env) {
-  const { cmd } = invocation(env);
+// Top-level help (presentation spec contract 10): the badge — name, version,
+// purpose; Usage; the named groups, each verb in the action role and its
+// summary on one line; ADVANCED, one line of the remaining verbs; the options
+// every verb takes; examples, each command alone on its line (contract 6);
+// the tips, whose plan command stands alone too; the harnesses and the exit
+// codes. `verbs` is the table this run answers for — VERBS, or a test's own.
+// `caps` is the writing stream's (term.mjs): painted at a terminal, plain on a
+// pipe, and every line of it fits 80 columns either way.
+export function usage(env = process.env, verbs = VERBS, { caps: c = term.PLAIN, version = packageVersion() } = {}) {
+  const { shell, cmd } = invokedAs(env);
+  const paint = term.painter(c);
+  const width = c.live ? c.width : 0;
+  const prose = (text) => "  " + term.wrap(term.glyphText(c, text), width, "    ");
   const lines = [
-    "projectstore — project memory for coding agents: decisions, specs, epics and stories as plain markdown.",
+    term.badge(c, "projectstore", [version, PURPOSE]),
     "",
-    "Usage",
-    `  ${cmd} <verb> [options]`,
-    `  ${cmd} <verb> --help       one verb's options and examples`,
+    term.heading(c, "Usage"),
+    ...term.rows(c, [
+      { target: `${cmd} <verb> [options]`, note: "run it inside your code project" },
+      { target: `${cmd} <verb> --help`, note: "one verb's options and examples" },
+    ]),
   ];
-  const seen = new Set();
-  const groups = HELP_GROUPS.map(([title, names]) => [title, names.map((n) => VERBS.find((v) => v.verb === n)).filter(Boolean)]);
-  for (const [, rows] of groups) for (const r of rows) seen.add(r.verb);
-  const other = VERBS.filter((v) => !seen.has(v.verb));
-  if (other.length) groups.push(["Other", other]);
-  for (const [title, rows] of groups) {
+  const listed = new Set(HELP_GROUPS.flatMap(([, names]) => names));
+  for (const [title, names] of HELP_GROUPS) {
+    const rows = names.map((n) => verbs.find((v) => v.verb === n)).filter(Boolean);
     if (!rows.length) continue;
-    lines.push("", title);
-    for (const v of rows) lines.push(`  ${v.verb.padEnd(12)} ${v.summary}`);
+    lines.push("", term.heading(c, title));
+    for (const v of rows) {
+      const lead = `  ${paint("action", v.verb)}${" ".repeat(Math.max(0, VERB_COLUMN - v.verb.length))} `;
+      lines.push(lead + term.wrap(term.glyphText(c, v.summary), width, " ".repeat(term.plain(lead).length)));
+    }
   }
+  // ADVANCED is one line of verbs, broken at 80 columns in every mode: with
+  // install and bind among them (contract 10, once setup exists) it no longer
+  // fits one row, and a pipe gets the same lines a terminal does.
+  const advanced = verbs.filter((v) => !listed.has(v.verb));
+  if (advanced.length)
+    lines.push(
+      "",
+      term.heading(c, "ADVANCED"),
+      "  " + term.wrap(advanced.map((v) => paint("action", v.verb)).join(` ${term.icon(c, "dot")} `), 80, "  "),
+    );
   if (PLANNED_VERBS.length) lines.push("", `Planned: ${PLANNED_VERBS.map((v) => `${v.verb} (${v.lands})`).join(", ")}`);
+  // A command is offered only for a verb this table has. The examples and the
+  // tips' plan are what to run next: the core's form, through a shell with
+  // the shell's own harness (rule 6 of the story "User-facing text says
+  // where to run…"); setup names it only through a shell, as EXAMPLES'
+  // `{fixed}` does.
+  const h = ` --harness ${(shell && shellHarnessId(env)) || "<id>"}`;
+  const has = (verb) => verbs.some((v) => v.verb === verb);
+  const examples = [
+    ["setup", `${CORE_NPX} setup${shell ? h : ""}`],
+    ["status", `${CORE_NPX} status`],
+    ["doctor", `${CORE_NPX} doctor`],
+  ]
+    .filter(([v]) => has(v))
+    .map(([, x]) => x);
+  lines.push("", term.heading(c, "Options"), ...optionLines(EVERY_VERB, c));
+  if (examples.length) lines.push("", term.heading(c, "Examples"), ...term.commandBlock(c, examples));
   lines.push(
     "",
-    "Every verb",
-    "  --project <dir>  the project (default: the host session's project, else the current directory)",
-    "  --json           one envelope { schema_version, verb, project, ok, result } — for scripts and agents",
-    "  --version        the package version",
-    "",
-    "Tips",
-    "  install, upgrade and uninstall show their plan first; `plan` prints the same plan and writes nothing.",
-    "  At a terminal they ask before writing. Without one, --harness is the confirmation — there is no --yes.",
-    "  Unattended in a terminal (a script, a Makefile): pass --json, set CI=1, or give stdin no terminal (`</dev/null`).",
-    "  --verbose on those verbs adds every row's reasoning and the host's own notes.",
-    "",
-    `Harnesses   ${harnessIds().join(", ")}`,
-    EXIT_CODES,
+    term.heading(c, "Tips"),
+    prose("setup, install, upgrade and uninstall show a plan, then ask at a terminal."),
+    prose(
+      `Without a terminal, ${shell ? "the verb is its own" : "--harness is the"} confirmation ${term.icon(c, "dash")} there is no --yes.`,
+    ),
+    prose("Unattended in a terminal: pass --json, set CI=1, or give stdin </dev/null."),
+    prose("--verbose on those verbs adds every row's reasoning and the host's notes."),
   );
+  if (has("plan"))
+    lines.push(
+      prose("plan prints the same plan and writes nothing:"),
+      ...term.commandBlock(c, [`${CORE_NPX} plan${h}`]),
+    );
+  lines.push("", fact(c, "Harnesses", harnessIds().join(", ")), fact(c, "Exit codes", EXIT_CODES));
   return lines.join("\n");
 }
 
-// One verb: what it does, how to call it, every option, examples.
-export function verbHelp(row, env = process.env) {
-  const { shell, cmd } = invocation(env);
+// One verb: what it does, how to call it, every option, examples. The Usage
+// lines are the row's own forms, the same declaration that bounds its
+// arguments — never parsed out of the summary, so help and the parser cannot
+// disagree about what a verb takes. Its first line is the summary the
+// top-level help lists, after the command; `caps` as usage()'s.
+export function verbHelp(row, env = process.env, { caps: c = term.PLAIN } = {}) {
+  const { shell, cmd } = invokedAs(env);
+  const paint = term.painter(c);
   const fixed = Boolean(shell) && row.options.some((o) => o.name === "harness");
   const opts = row.options.filter((o) => !(fixed && o.name === "harness"));
-  const { forms: list, about } = forms(row);
-  const lines = [`${cmd} ${row.verb} — ${about}`, "", "Usage"];
-  for (const f of list) lines.push(`  ${cmd} ${row.verb}${f ? " " + f : ""}${opts.length ? " [options]" : ""}`);
-  if (opts.length) lines.push("", "Options", ...optionLines(opts));
-  if (fixed) lines.push("", `${shell} names the harness itself: without a terminal, the verb is its own confirmation.`);
-  else if (row.options.some((o) => o.name === "harness")) lines.push("", `Harnesses   ${harnessIds().join(", ")}`);
-  const ex = EXAMPLES[row.verb] || [];
-  const h = fixed ? "" : " --harness <id>";
-  const rendered = ex.map((e) => e.split("{cmd}").join(cmd).split("{h}").join(h).split("  # "));
-  const col = Math.max(0, ...rendered.filter((r) => r.length > 1).map(([c]) => c.length));
-  if (ex.length) lines.push("", "Examples", ...rendered.map(([c, note]) => `  ${note ? `${c.padEnd(col)}   # ${note}` : c}`));
-  lines.push("", EXIT_CODES);
+  const prose = (text) => "  " + term.wrap(term.glyphText(c, text), c.live ? c.width : 0, "    ");
+  const head = `${paint("emphasis", `${cmd} ${row.verb}`)} ${term.icon(c, "dash")} ${term.glyphText(c, row.summary)}`;
+  const lines = [term.wrap(head, c.live ? c.width : 0, "  "), "", term.heading(c, "Usage")];
+  for (const f of row.usage.length ? row.usage : [""])
+    lines.push(`  ${cmd} ${row.verb}${f ? " " + term.glyphText(c, f) : ""}${opts.length ? " [options]" : ""}`);
+  if (NOTES[row.verb]) lines.push("", prose(NOTES[row.verb]));
+  if (opts.length) lines.push("", term.heading(c, "Options"), ...optionLines(opts, c));
+  if (fixed)
+    lines.push(
+      "",
+      term.wrap(
+        `${shell} names the harness itself: without a terminal, the verb is its own confirmation.`,
+        c.live ? c.width : 0,
+        "  ",
+      ),
+    );
+  else if (row.options.some((o) => o.name === "harness")) lines.push("", fact(c, "Harnesses", harnessIds().join(", ")));
+  const sw = switchHarness();
+  const ex = (EXAMPLES[row.verb] || [])
+    .filter((e) => !(fixed && e.startsWith("{core}")) && (sw || !e.includes("{switch.")))
+    .map((e) => e.replace(/^\{core\}/, "").replace(/\{(switch\.\w+)\}/g, (_, k) => sw[k]));
+  // What to run next is the core's form: through a shell, its own harness.
+  const h = ` --harness ${(fixed && shellHarnessId(env)) || "<id>"}`;
+  // Each example command stands alone on its line, after a blank one
+  // (contract 6): nothing after it, so a paste takes exactly the command — a
+  // trailing `# note` broke a paste into a shell that reads no comments. A
+  // note leads its command, a blank line between them, as every other
+  // introduced command does (DONE's tip, doctor's fix, bind's Next);
+  // commands with no note share one block.
+  const blocks = [];
+  const render = (e) =>
+    e
+      .split("{cmd}")
+      .join(CORE_NPX)
+      .split("{h}")
+      .join(h)
+      .split("{fixed}")
+      .join(fixed ? h : "");
+  for (const [x, note] of ex.map((e) => render(e).split("  # "))) {
+    const last = blocks.at(-1);
+    if (!note && last && !last.note) last.cmds.push(x);
+    else blocks.push({ note: note ? `${note[0].toUpperCase()}${note.slice(1)}:` : null, cmds: [x] });
+  }
+  if (blocks.length) lines.push("", term.heading(c, "Examples"));
+  for (const b of blocks)
+    lines.push(
+      "",
+      ...(b.note ? [prose(paint("explanation", b.note)), ""] : []),
+      ...b.cmds.map((x) => `  ${paint("action", x)}`),
+    );
+  lines.push("", fact(c, "Exit codes", EXIT_CODES));
   return lines.join("\n");
 }
 
@@ -320,90 +877,322 @@ export function nearest(word, names) {
   const d = (a, b) => {
     const m = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
     for (let j = 1; j <= b.length; j++) m[0][j] = j;
-    for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    for (let i = 1; i <= a.length; i++)
+      for (let j = 1; j <= b.length; j++)
+        m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
     return m[a.length][b.length];
   };
-  let best = null, score = 3;
+  let best = null,
+    score = 3;
   for (const n of names) {
     const k = n.startsWith(word) && word.length >= 3 ? 0 : d(word, n);
-    if (k < score) { best = n; score = k; }
+    if (k < score) {
+      best = n;
+      score = k;
+    }
   }
   return best;
 }
 
 // ─── run ───────────────────────────────────────────────────────────────
 
-export async function run(argv, { env = process.env, cwd = process.cwd(), stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, ask = null } = {}) {
-  let parsed;
-  try {
-    parsed = parseArgs({
-      args: argv,
-      allowPositionals: true,
-      strict: true,
-      options: {
-        project: { type: "string" }, json: { type: "boolean" }, help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
-        harness: { type: "string", multiple: true }, surface: { type: "string", multiple: true }, global: { type: "boolean" }, "no-register": { type: "boolean" }, verbose: { type: "boolean" },
-        write: { type: "boolean" }, only: { type: "string" }, install: { type: "boolean" }, vault: { type: "boolean" },
-        kind: { type: "string", multiple: true }, status: { type: "string" }, limit: { type: "string" }, "include-derived": { type: "boolean" }, "case-sensitive": { type: "boolean" },
-        body: { type: "boolean" }, section: { type: "string" }, direction: { type: "string" }, depth: { type: "string" }, for: { type: "string" }, reverse: { type: "boolean" },
-        layout: { type: "string" }, language: { type: "string" }, rebind: { type: "boolean" },
-        default: { type: "string" }, agent: { type: "string", multiple: true }, reset: { type: "boolean" },
-      },
-    });
-  } catch (e) {
-    // --json cannot be known before parsing; a raw scan is enough here.
-    if (argv.includes("--json")) stdout.write(JSON.stringify(envelope(argv.find((a) => !a.startsWith("-")) || null, null, false, { error: e.message }), null, 2) + "\n");
-    // Node's own wording for an unknown option explains "--" positionals; a
-    // person who typed --verbos wants the option they meant.
-    const unknown = e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ? /'(-{1,2}[^']+)'/.exec(e.message)?.[1] : null;
-    const row = VERBS.find((v) => v.verb === argv.find((a) => !a.startsWith("-")));
-    const names = [...(row ? row.options.map((o) => o.name) : VERBS.flatMap((v) => v.options.map((o) => o.name))), "project", "json", "help", "version"];
-    const hint = unknown ? nearest(unknown.replace(/^-+/, ""), [...new Set(names)]) : null;
-    const message = unknown ? `${row ? row.verb + " does not take" : "unknown option"} ${unknown}${hint ? ` — did you mean --${hint}?` : ""}` : e.message;
-    stderr.write(`${message}\nRun ${row ? `\`${row.verb} --help\`` : "--help"} for the options.\n`);
-    return 2;
+// Rule 1 of the per-verb parse: the verb is found before anything is parsed.
+// Before it only the globals' arity is known; after it, its row's too. Left
+// to right, to the first "--": a "--" before the verb makes the next token
+// the verb (`projectstore -- doctor`), and one after it leaves the rest to
+// the verb, so the MCP server's `-- <query>` is never read as a global. Only
+// the exact tokens set a flag: `--json=v` is a global with a bad value, which
+// the parse words (rule 6), not a verb's option. A bare --project takes the
+// next token whatever it is, as parseArgs does, and so does a bare option of
+// the verb's that takes a value: `reconcile --only --help` and the MCP
+// server's `--kind -h` hand the parse a value it refuses, never the help.
+// Any other option before the verb is misplaced (rule 3). A bare word right
+// after one is presumed to be its value when it is not a verb and some verb
+// gives that option a value — for the message only (`--harness codex plan`
+// reads back as `plan --harness codex`); nothing is parsed on that guess.
+function scanArgv(argv, verbs) {
+  const scan = { verb: null, at: -1, json: false, help: false, version: false, misplaced: [] };
+  const takesValue = (row, name) => row.options.some((o) => o.name === name && o.arg);
+  let row = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      if (scan.at === -1 && i + 1 < argv.length) {
+        scan.verb = argv[i + 1];
+        scan.at = i + 1;
+      }
+      break;
+    }
+    if (a.length > 1 && a.startsWith("-")) {
+      if (/^-[hv]+$/.test(a)) {
+        if (a.includes("h")) scan.help = true;
+        if (a.includes("v")) scan.version = true;
+        continue;
+      }
+      if (a === "--json") scan.json = true;
+      if (a === "--help") scan.help = true;
+      if (a === "--version") scan.version = true;
+      const name = a.startsWith("--") ? a.slice(2).split("=")[0] : null;
+      const inline = a.includes("=");
+      if (!inline && (name === "project" || (row && takesValue(row, name)))) i++;
+      else if (scan.at === -1 && !GLOBAL_OPTS.some((o) => o.name === name))
+        scan.misplaced.push({ name, raw: a, at: i, inline, value: undefined });
+      continue;
+    }
+    if (scan.at !== -1) continue;
+    const prev = scan.misplaced[scan.misplaced.length - 1];
+    if (
+      !verbs.some((v) => v.verb === a) &&
+      prev &&
+      prev.at === i - 1 &&
+      !prev.inline &&
+      verbs.some((v) => takesValue(v, prev.name))
+    ) {
+      prev.value = a;
+      continue;
+    }
+    scan.verb = a;
+    scan.at = i;
+    row = verbs.find((v) => v.verb === a) || null;
   }
-  const { values, positionals } = parsed;
+  return scan;
+}
+
+// A row's options and the globals, in parser order: the later declaration
+// wins, so a row cannot retype a global. No row (no verb) is the globals alone.
+const optionsOf = (row) => [...(row ? row.options : []), ...GLOBAL_OPTS];
+
+// Rule 2: the row is the parser — arg is the type, multiple the repetition.
+function parserOptions(row) {
+  const options = {};
+  for (const o of optionsOf(row))
+    options[o.name] = {
+      type: o.arg ? "string" : "boolean",
+      ...(o.multiple ? { multiple: true } : {}),
+      ...(SHORT[o.name] ? { short: SHORT[o.name] } : {}),
+    };
+  return options;
+}
+
+// "install does not take --verbos — did you mean --verbose?" With a row the
+// candidates are its options and the globals; without one (no verb, or a
+// word that is none), every option the table declares, as 0.29.2 offered.
+function unknownOption(row, raw, verbs) {
+  const names = (row ? optionsOf(row) : [...verbs.flatMap((v) => v.options), ...GLOBAL_OPTS]).map((o) => o.name);
+  const hint = nearest(raw.replace(/^-+/, ""), [...new Set(names)]);
+  return `${row ? `${row.verb} does not take` : "unknown option"} ${raw}${hint ? ` — did you mean --${hint}?` : ""}`;
+}
+
+// Rule 6: Node's own wording explains "--" positionals; a person who typed
+// --verbos wants the option they meant, and one who left --only bare wants
+// its form. A bad value comes in three shapes — an inline value on a flag
+// (`--json=v`), none at all (`--only` last), one that looks like an option
+// (`--only --json`) — and each quotes the long name, with ` <value>` or a
+// `-h, ` short form around it: the declaration words the answer. Node's text
+// is the fallback when no name can be read.
+function parseFailure(e, row, verbs) {
+  const raw = e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ? /'(-{1,2}[^']+)'/.exec(e.message)?.[1] : null;
+  if (raw) return unknownOption(row, raw, verbs);
+  const name =
+    e.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE"
+      ? /'(?:-[^-], )?(--[^' ]+)(?: <value>)?'/.exec(e.message)?.[1]
+      : null;
+  const o = name ? optionsOf(row).findLast((x) => `--${x.name}` === name) : null;
+  if (!o) return e.message;
+  return o.arg ? `\`--${o.name}\` needs a value: \`--${o.name} ${o.arg}\`` : `\`--${o.name}\` takes no value`;
+}
+
+// Rule 4: a usage form, word by word — a --name the form requires (the word
+// after it is the option's value when it takes one, not an argument), a
+// <placeholder> (`<phrase…>` takes the rest), or a literal sub-word. The
+// bound is how many arguments the form holds.
+function formOf(row, form) {
+  const f = { form, literals: [], required: [], placeholders: 0, variadic: false };
+  const words = form.split(" ");
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    if (w.startsWith("--")) {
+      f.required.push(w.slice(2));
+      if (row.options.find((o) => o.name === w.slice(2))?.arg) i++;
+    } else if (w.startsWith("<")) {
+      f.placeholders++;
+      if (w.endsWith("…>")) f.variadic = true;
+    } else f.literals.push(w);
+  }
+  f.bound = f.variadic ? Infinity : f.literals.length + f.placeholders;
+  return f;
+}
+
+// The form the arguments take: the first whose literal words lead them and
+// whose required options were given. null when none does, and the verb's own
+// message then says what it takes ("agents takes model <name>, show, or
+// configure") — which is how `codemap PS-CORE` keeps its --for hint while
+// `codemap --for X extra` names `extra`. A row with no forms binds nothing.
+function matchForm(row, args, values) {
+  if (!row.usage.length) return { form: "", bound: 0 };
+  for (const form of row.usage) {
+    const f = formOf(row, form);
+    if (f.literals.every((w, i) => args[i] === w) && f.required.every((n) => values[n] !== undefined)) return f;
+  }
+  return null;
+}
+
+// `verbs` is the table this run answers for: VERBS, or a test's own — the
+// scan, the help, the verb lookup and every hint read it, never VERBS behind it.
+export async function run(
+  argv,
+  {
+    verbs = VERBS,
+    env = process.env,
+    cwd = process.cwd(),
+    stdin = process.stdin,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    ask = null,
+  } = {},
+) {
+  const scan = scanArgv(argv, verbs);
+  const row = verbs.find((v) => v.verb === scan.verb) || null;
   // A failure before a verb runs still answers in the envelope under --json:
-  // a consumer (the MCP server, a script) always has something to parse.
-  const fail = (verb, project, message, code, { help = false } = {}) => {
-    if (values.json) stdout.write(JSON.stringify(envelope(verb, project, false, { error: message, exit: code }), null, 2) + "\n");
-    stderr.write(message + "\n" + (help ? usage(env) + "\n" : ""));
+  // a consumer (the MCP server, a script) always has something to parse. The
+  // verb is the scan's, whichever step failed (rule 7) — never the first
+  // bare word, which may be --project's value.
+  const fail = (message, code, { project = null, help = false } = {}) => {
+    if (scan.json)
+      stdout.write(JSON.stringify(envelope(scan.verb, project, false, { error: message, exit: code }), null, 2) + "\n");
+    stderr.write(message + "\n" + (help ? usage(env, verbs, { caps: term.caps(stderr, env) }) + "\n" : ""));
     return code;
   };
+  // A usage error says where the options are: the verb's help, else the top
+  // (a word that is not a verb has no help to point at).
+  const refuse = (message) => fail(`${message}\nRun ${row ? `\`${row.verb} --help\`` : "--help"} for the options.`, 2);
   // In-process reads resolve layouts and registries from THIS package, as the
   // children already do through ownEnv — not from whichever copy the host
   // session's variable points at.
   pinPluginRoot(PACKAGE_ROOT);
-  if (values.version) return runVersion({ values, stdout });
-  if (values.help && positionals.length) {
-    const row = VERBS.find((v) => v.verb === positionals[0]);
-    if (row) { stdout.write(verbHelp(row, env) + "\n"); return 0; }
-  }
-  if (values.help || !positionals.length) { (values.help ? stdout : stderr).write(usage(env) + "\n"); return values.help ? 0 : 2; }
-  const verb = positionals[0];
-  const row = VERBS.find((v) => v.verb === verb);
+  // Rule 8: help and version answer first, whatever else the line holds, so
+  // `doctor extra --help` and `--harness codex plan --help` print the help.
+  if (scan.version) return runVersion({ values: { json: scan.json }, stdout });
+  // Help is painted at a terminal and plain on a pipe: the caps are stdout's.
+  if (scan.help) {
+    const caps = term.caps(stdout, env);
+    stdout.write((row ? verbHelp(row, env, { caps }) : usage(env, verbs, { caps })) + "\n");
+    return 0;
+  }
+  // With no verb to scope it, an option no verb declares is unknown before
+  // anything else is said, as in 0.29.2: `--bogus frobnicate` names --bogus,
+  // and `--verbos instal` offers --verbose.
+  const stray = row ? null : scan.misplaced.find((m) => !verbs.some((v) => v.options.some((o) => o.name === m.name)));
+  if (stray) return refuse(unknownOption(null, stray.raw.split("=")[0], verbs));
+  if (scan.verb === null) {
+    // No verb. A verb's option (`--harness codex`, `--verbose`) is the usage,
+    // as before — not "unknown verb: codex"; otherwise the globals alone are
+    // parsed, so a bad value of one (`--project` last) is named.
+    if (!scan.misplaced.length) {
+      try {
+        parseArgs({ args: argv, options: parserOptions(null), strict: true, allowPositionals: true });
+      } catch (e) {
+        return refuse(parseFailure(e, null, verbs));
+      }
+    }
+    stderr.write(usage(env, verbs, { caps: term.caps(stderr, env) }) + "\n");
+    return 2;
+  }
+  const verb = scan.verb;
   if (!row) {
     const planned = PLANNED_VERBS.find((v) => v.verb === verb);
-    const guess = planned ? null : nearest(verb, VERBS.map((v) => v.verb));
-    if (guess) return fail(verb, null, `unknown verb: ${verb} — did you mean ${guess}?\nRun --help for every verb.`, 2);
-    return fail(verb, null, (planned ? `${verb} lands with roadmap ${planned.lands}; not in this release.` : `unknown verb: ${verb}`), 2, { help: true });
-  }
-  // The options map is global (parseArgs), the rows are not: an option a row
-  // does not declare is a usage error, so help cannot lie about what a verb
-  // takes.
-  const GLOBAL = new Set(["project", "json", "help", "version"]);
-  const declared = new Set(row.options.map((o) => o.name));
-  const stray = Object.keys(values).filter((k) => !GLOBAL.has(k) && !declared.has(k));
-  if (stray.length) {
-    const guess = nearest(stray[0], row.options.map((o) => o.name));
-    return fail(verb, null, `${verb} does not take --${stray[0]}${guess ? ` — did you mean --${guess}?` : ""}\nRun \`${verb} --help\` for the options.`, 2);
+    const guess = planned
+      ? null
+      : nearest(
+          verb,
+          verbs.map((v) => v.verb),
+        );
+    if (guess) return fail(`unknown verb: ${verb} — did you mean ${guess}?\nRun --help for every verb.`, 2);
+    return fail(
+      planned ? `${verb} lands with roadmap ${planned.lands}; not in this release.` : `unknown verb: ${verb}`,
+      2,
+      { help: true },
+    );
+  }
+  // Rule 3: only the globals come before the verb (git's model). A verb's
+  // own option there is shown in its place; one the verb does not declare is
+  // unknown, scoped to the verb. Accepting it would need its arity before the
+  // verb is known, which is what per-verb types make ambiguous.
+  if (scan.misplaced.length) {
+    const m = scan.misplaced[0];
+    const o = m.name === null ? null : row.options.find((x) => x.name === m.name);
+    if (!o) return refuse(unknownOption(row, m.raw.split("=")[0], verbs));
+    // Through a shell the harness is fixed (verbHelp's test: the row declares
+    // it): the order shown drops it, since the shell inserts it after the verb.
+    // The rest of the line follows, so the command shown is the one to run.
+    const { shell, cmd } = invokedAs(env);
+    const moved = shell && o.name === "harness" ? [] : [m.raw, ...(o.arg && m.value !== undefined ? [m.value] : [])];
+    return refuse(
+      `\`--${o.name}\` belongs after the verb: \`${[cmd, verb, ...moved, ...argv.slice(scan.at + 1)].join(" ")}\``,
+    );
+  }
+  // Rule 2: one strict parse with this row's options plus the globals, on the
+  // full argv so a token's index is the user's (rule 4's hints read them).
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: parserOptions(row), strict: true, allowPositionals: true, tokens: true });
+  } catch (e) {
+    return refuse(parseFailure(e, row, verbs));
+  }
+  const { values, positionals, tokens } = parsed;
+  // Rule 4: an argument past the matched form is named, never dropped. The
+  // hint says how it became one: the flag before it takes no value, or a
+  // "--" made everything after it an argument.
+  const args = tokens.filter((t) => t.kind === "positional" && t.index !== scan.at);
+  const form = matchForm(
+    row,
+    args.map((t) => t.value),
+    values,
+  );
+  if (form && args.length > form.bound) {
+    const extra = args[form.bound];
+    const prev = tokens.find((t) => t.index === extra.index - 1);
+    const end = tokens.find((t) => t.kind === "option-terminator");
+    const why =
+      prev && prev.kind === "option" && prev.value === undefined
+        ? ` — \`--${prev.name}\` takes no value`
+        : end && extra.index > end.index
+          ? " — everything after `--` is an argument"
+          : "";
+    return refuse(
+      `${form.bound ? `\`${verb} ${form.form}\` takes no further argument` : `${verb} takes no argument`} \`${extra.value}\`${why}`,
+    );
   }
   const project = resolveProject({ project: values.project, env, cwd });
   const cfg = readConfigAt(project);
-  if (row.requiresBinding && !cfg) return fail(verb, project, `${project} is not bound to a vault — run ${commandForm("bind", { args: "<vault>", env })} in a session, or \`projectstore bind <vault>\` (\`projectstore init <vault>\` also creates the vault).`, 3);
+  // Each form alone on its line after the lead, the terminal's in the core's
+  // form, the directory in the lead (the story "User-facing text says where to
+  // run and names no project path and no shell", rules 1, 4 and 6).
+  if (row.requiresBinding && !cfg)
+    return fail(
+      [
+        `${project} is not bound to a vault. Bind it in a session, or ${fromTerminalIn(project)}, where init creates the vault too:`,
+        commandForm("bind", { args: "<vault>", env }),
+        packageCommand([], "bind", { args: "<vault>" }),
+        packageCommand([], "init", { args: "<vault>" }),
+      ].join("\n"),
+      3,
+      { project },
+    );
   try {
-    return await row.run({ row, values, positionals: positionals.slice(1), cfg, project, env, cwd, stdin, stdout, stderr, ask });
+    return await row.run({
+      row,
+      values,
+      positionals: positionals.slice(1),
+      cfg,
+      project,
+      env,
+      cwd,
+      stdin,
+      stdout,
+      stderr,
+      ask,
+    });
   } catch (e) {
     // An internal failure is not "findings" (1) — it is 2, with an envelope
     // when one was asked for.
@@ -435,10 +1224,12 @@ async function confirmWrite(question, { stdin, stdout, ask }) {
 
 // The read verbs: one call into query.mjs, the result in the envelope or
 // rendered. A usage error from the operation (a bad path, a missing query)
-// is exit 2 with the message, never a stack trace.
-function emitRead({ verb, values, project, stdout }, op, result, ok = true) {
+// is exit 2 with the message, never a stack trace. A renderer gets the
+// stream's caps — painted at a terminal, plain on a pipe — and the env its
+// command forms are named for; one that takes neither ignores them.
+function emitRead({ verb, values, project, stdout, env }, op, result, ok = true) {
   if (values.json) stdout.write(JSON.stringify(envelope(verb, project, ok, result), null, 2) + "\n");
-  else stdout.write(op.render(result));
+  else stdout.write(op.render(result, { caps: term.caps(stdout, env), env }));
   return ok ? 0 : 1;
 }
 
@@ -456,8 +1247,16 @@ function runRead(name) {
       let result;
       if (name === "status") result = op.fn(cfg, { project });
       else if (name === "orientation") result = await op.fn(cfg);
-      else if (name === "search") result = op.fn(cfg, positionals.join(" "), { kinds: values.kind || null, status: values.status ?? null, limit: values.limit, includeDerived: Boolean(values["include-derived"]), caseSensitive: Boolean(values["case-sensitive"]) });
-      else if (name === "show") result = op.fn(cfg, positionals[0], { body: Boolean(values.body), section: values.section ?? null });
+      else if (name === "search")
+        result = op.fn(cfg, positionals.join(" "), {
+          kinds: values.kind || null,
+          status: values.status ?? null,
+          limit: values.limit,
+          includeDerived: Boolean(values["include-derived"]),
+          caseSensitive: Boolean(values["case-sensitive"]),
+        });
+      else if (name === "show")
+        result = op.fn(cfg, positionals[0], { body: Boolean(values.body), section: values.section ?? null });
       return emitRead({ verb: row.verb, ...ctx }, op, result);
     } catch (e) {
       if (e && e.code === "USAGE") return usageFail(e, { verb: row.verb, ...ctx });
@@ -490,26 +1289,108 @@ function gitAuthor(project, env) {
 
 // bind / init: the vault named on the command line is the confirmation (the
 // distribution ADR's decision 6 read for a binding — there is no --yes and
-// nothing to ask); a change of vault needs --rebind. Exit 1 on a refusal with
-// the reason, 2 on usage, 0 when already bound to the same vault.
+// nothing to ask, at a terminal either: init's command line names what it
+// writes); a change of vault needs --rebind. Exit 1 on a refusal with the
+// reason, or when init's git or scaffold step failed after the binding was
+// written; 2 on usage; 0 when already bound to the same vault.
 function runBind(init) {
   return async (ctx) => {
     const { row, values, positionals, project, env, stdout, stderr } = ctx;
     const vault = positionals[0];
-    if (!vault) return usageFail(Object.assign(new Error(`${row.verb} takes the vault path`), { code: "USAGE" }), { verb: row.verb, ...ctx });
+    if (!vault)
+      return usageFail(Object.assign(new Error(`${row.verb} takes the vault path`), { code: "USAGE" }), {
+        verb: row.verb,
+        ...ctx,
+      });
     // The author is the caller's to find: the plan reads nothing ambient.
-    const plan = planBind(project, { vault, layout: values.layout ?? null, language: values.language ?? null, rebind: Boolean(values.rebind), init, author: gitAuthor(project, env), env });
+    const plan = planBind(project, {
+      vault,
+      layout: values.layout ?? null,
+      language: values.language ?? null,
+      rebind: Boolean(values.rebind),
+      init,
+      author: gitAuthor(project, env),
+      env,
+      root: PACKAGE_ROOT,
+    });
     const usage = plan.refusals.find((r) => r.code === "USAGE");
     if (usage) return usageFail(Object.assign(new Error(usage.message), { code: "USAGE" }), { verb: row.verb, ...ctx });
     let done = null;
-    if (plan.ok && plan.writes) done = applyBind(plan);
+    if (plan.ok && (plan.writes || plan.buildsVault)) done = applyBind(plan, { env });
+    const ok = plan.ok && !bindFailed(done);
     const result = bindResult(plan, done);
-    if (values.json) stdout.write(JSON.stringify(envelope(row.verb, project, plan.ok, result), null, 2) + "\n");
-    else (plan.ok ? stdout : stderr).write(renderBindPlan(plan, done));
-    return plan.ok ? 0 : 1;
+    if (values.json) stdout.write(JSON.stringify(envelope(row.verb, project, ok, result), null, 2) + "\n");
+    else {
+      const stream = plan.ok ? stdout : stderr;
+      stream.write(renderBindPlan(plan, done, { env, caps: term.caps(stream, env) }));
+    }
+    return ok ? 0 : 1;
   };
 }
 
+// scaffold: the bound vault's skeleton, from the binding's layout and
+// language (`bind --rebind` changes them; the verb takes no layout). Bare, the
+// plan, and nothing is written. --write creates the `create` rows: at an
+// interactive terminal (install spec contract 9's definition) after the plan
+// and `Apply N changes? [Y/n]`; without one, --write is the confirmation —
+// the write set is closed, so `scaffold --write --json` writes at a terminal
+// too, which is how the session command and the Codex skill confirm. A plan
+// with nothing to create asks nothing and exits 0. A vault directory that
+// is gone is refused: recreating it here would hide that it vanished, and
+// `init` is the verb that makes a vault.
+async function runScaffold(ctx) {
+  const { row, values, cfg, project, env, stdin, stdout, stderr, ask } = ctx;
+  const emit = (ok, result, text, code) => {
+    if (values.json) stdout.write(JSON.stringify(envelope(row.verb, project, ok, result), null, 2) + "\n");
+    else (ok ? stdout : stderr).write(text);
+    return code;
+  };
+  // readConfigAt hands back the stored path raw: `~`, relative, a trailing slash.
+  const norm = normaliseVaultPath(cfg.vault_path, project);
+  const vault = typeof norm === "string" ? norm : null;
+  // Each refusal ends with its command alone on its line, in the core's form,
+  // the directory in the lead (the story "User-facing text says where to
+  // run…", rules 1, 4 and 6). In a session, bind asks before a rebind.
+  if (!vault) {
+    const why = [
+      `the binding names no usable vault path${norm && norm.error ? ` (${norm.error})` : ""}. Rebind it in a session, or ${fromTerminalIn(project)}:`,
+      commandForm("bind", { args: "<vault>", env }),
+      packageCommand([], "bind", { args: "<vault> --rebind" }),
+    ].join("\n");
+    return emit(false, { error: why }, why + "\n", 1);
+  }
+  if (!existsSync(vault)) {
+    const why = [
+      `${vault} does not exist: the binding names a vault directory that is not there. init creates it under this binding — the directory, its git repository and the layout's folders — ${fromTerminalIn(project)}:`,
+      packageCommand([], "init", { args: shellQuote(vault) }),
+    ].join("\n");
+    return emit(false, { error: why, vault_path: vault }, why + "\n", 1);
+  }
+  const plan = planScaffold(vault, {
+    layout: cfg.layout || DEFAULT_LAYOUT,
+    language: cfg.language || DEFAULT_LANGUAGE,
+    root: PACKAGE_ROOT,
+  });
+  if (!plan.ok) return emit(false, scaffoldResult(plan), renderScaffoldPlan(plan, null, { env }), 1);
+  if (!values.write || plan.creates === 0)
+    return emit(true, scaffoldResult(plan), renderScaffoldPlan(plan, null, { env, project }), 0);
+  // An injected `ask` is a terminal, as for install. Otherwise the installer's
+  // definition of one (TTYs, CI, a host session's markers) is the one
+  // contract 9 names — imported lazily, as runInstallVerb imports it.
+  const interactive =
+    !values.json &&
+    (ask ? true : (await import("./install-harness.mjs")).isInteractive({ stdin, stdout, env, json: false }));
+  if (interactive) {
+    stdout.write(renderScaffoldPlan(plan, null, { env, asking: true }));
+    if (!(await term.askApply(plan.creates, { stdin, stdout, ask, caps: term.caps(stdout, env) }))) {
+      stdout.write("Nothing written.\n");
+      return 1;
+    }
+  }
+  const done = applyScaffold(plan);
+  return emit(true, scaffoldResult(plan, done), renderScaffoldPlan(plan, done, { env }), 0);
+}
+
 // agents model <name> — the model a plugin surface passes for that agent, from
 // the active harness's overlay (ADR-008's two terms); agents show — the overlay
 // as read, with the keys the allowlist rejected; agents configure — the one
@@ -522,21 +1403,32 @@ async function runAgents(ctx) {
   if (!["model", "show", "configure"].includes(sub)) return usage("agents takes model <name>, show, or configure");
   // The flag IS the confirmation, so it names exactly one overlay: two are a
   // question, not an answer.
-  if (values.harness && values.harness.length > 1) return usage("--harness names exactly one overlay (it is the confirmation); given twice");
+  if (values.harness && values.harness.length > 1)
+    return usage("--harness names exactly one overlay (it is the confirmation); given twice");
   const named = values.harness && values.harness[0];
-  if (named && !harnessIds().includes(named)) return usage(`unknown harness: ${named} — known: ${harnessIds().join(", ")}`);
+  if (named && !harnessIds().includes(named))
+    return usage(`unknown harness: ${named} — known: ${harnessIds().join(", ")}`);
   const harness = named || overlayId(env);
   const forConfigure = ["default", "agent", "reset"].filter((o) => values[o] !== undefined);
   if (sub !== "configure" && forConfigure.length) return usage(`--${forConfigure[0]} is an option of agents configure`);
   // A refusal goes to stderr, as bind's does; --json keeps its envelope on stdout.
-  const emit = (verb, ok, result, text) => { if (values.json) stdout.write(JSON.stringify(envelope(verb, project, ok, result), null, 2) + "\n"); else (ok ? stdout : stderr).write(text); return ok ? 0 : 1; };
+  const emit = (verb, ok, result, text) => {
+    if (values.json) stdout.write(JSON.stringify(envelope(verb, project, ok, result), null, 2) + "\n");
+    else (ok ? stdout : stderr).write(text);
+    return ok ? 0 : 1;
+  };
   const cfg = readConfigAt(project);
   const roster = layoutRoster(cfg);
   if (sub === "model") {
     const name = positionals[1];
     if (!name) return usage("agents model takes the agent's bare name (critic, planner, …)");
     const r = resolveAgentModel(project, name, { harness });
-    return emit("agents model", true, r, `${name}: ${r.model ? `${r.model} (${r.source}, ${r.overlay})` : "no model configured — the agent's frontmatter decides"}\n`);
+    return emit(
+      "agents model",
+      true,
+      r,
+      `${name}: ${r.model ? `${r.model} (${r.source}, ${r.overlay})` : "no model configured — the agent's frontmatter decides"}\n`,
+    );
   }
   const before = readOverlayAt(project, harness);
   const inBinding = Boolean(cfg && cfg.agents && typeof cfg.agents === "object");
@@ -544,34 +1436,72 @@ async function runAgents(ctx) {
     // Resolved per roster agent (per configured name when no layout loads), so
     // a reader reports what would run without restating the two-term rule.
     const names = [...new Set([...(roster || []), ...Object.keys(before.agents.per_agent)])].sort();
-    const resolved = Object.fromEntries(names.map((n) => { const r = resolveAgentModel(project, n, { harness }); return [n, { model: r.model, source: r.source }]; }));
+    const resolved = Object.fromEntries(
+      names.map((n) => {
+        const r = resolveAgentModel(project, n, { harness });
+        return [n, { model: r.model, source: r.source }];
+      }),
+    );
     const unknown = roster ? Object.keys(before.agents.per_agent).filter((n) => !roster.includes(n)) : [];
-    const lines = [`overlay: ${before.path || "(none: no harness detected and none named)"}${before.path && !before.present ? " (absent)" : ""}`];
+    const lines = [
+      `overlay: ${before.path || "(none: no harness detected and none named)"}${before.path && !before.present ? " (absent)" : ""}`,
+    ];
     if (before.unparseable) lines.push("  not valid JSON");
     if (before.agents.default) lines.push(`  default: ${before.agents.default}`);
-    for (const n of names) lines.push(`  ${n}: ${resolved[n].model ? `${resolved[n].model} (${resolved[n].source})` : "— (the agent's frontmatter)"}${unknown.includes(n) ? " — not in the roster: nothing runs under this name" : ""}`);
+    for (const n of names)
+      lines.push(
+        `  ${n}: ${resolved[n].model ? `${resolved[n].model} (${resolved[n].source})` : "— (the agent's frontmatter)"}${unknown.includes(n) ? " — not in the roster: nothing runs under this name" : ""}`,
+      );
     if (before.rejected.length) lines.push(`  ignored (not an overlay key): ${before.rejected.join(", ")}`);
     if (inBinding) lines.push("  the binding still carries an agents block — a pre-0.28 leftover; run upgrade");
-    return emit("agents show", true, { harness, path: before.path, present: before.present, unparseable: before.unparseable, agents: before.agents, resolved, roster, unknown, rejected: before.rejected, agents_in_binding: inBinding }, lines.join("\n") + "\n");
+    return emit(
+      "agents show",
+      true,
+      {
+        harness,
+        path: before.path,
+        present: before.present,
+        unparseable: before.unparseable,
+        agents: before.agents,
+        resolved,
+        roster,
+        unknown,
+        rejected: before.rejected,
+        agents_in_binding: inBinding,
+      },
+      lines.join("\n") + "\n",
+    );
   }
   // configure — in a project that exists (the install spec, contract 19;
   // the layout spec, contract 4): refused before the preview and the gate.
   const missingProject = projectDirRefusal(project);
   if (missingProject) return emit("agents configure", false, { error: missingProject }, `${missingProject}\n`);
   if (!harness) return usage("no harness detected and none named: agents configure names --harness <id>");
-  if (before.unparseable) return emit("agents configure", false, { error: `${before.path} is not valid JSON; fix or remove it first`, harness, path: before.path }, `${before.path} is not valid JSON; fix or remove it first\n`);
-  if (!values.reset && values.default === undefined && !(values.agent || []).length) return usage("agents configure takes --default <model>, --agent <name>=<model> (repeatable) or --reset");
+  if (before.unparseable)
+    return emit(
+      "agents configure",
+      false,
+      { error: `${before.path} is not valid JSON; fix or remove it first`, harness, path: before.path },
+      `${before.path} is not valid JSON; fix or remove it first\n`,
+    );
+  if (!values.reset && values.default === undefined && !(values.agent || []).length)
+    return usage("agents configure takes --default <model>, --agent <name>=<model> (repeatable) or --reset");
   // --reset empties the block first; --default and --agent then apply on top of
   // the emptied block — "reset, then set" is one call, and nothing given is
   // silently dropped.
   const base = values.reset ? { default: null, per_agent: {} } : before.agents;
-  const next = { default: values.default !== undefined ? (values.default || null) : base.default, per_agent: { ...base.per_agent } };
+  const next = {
+    default: values.default !== undefined ? values.default || null : base.default,
+    per_agent: { ...base.per_agent },
+  };
   for (const spec of values.agent || []) {
     const m = /^([a-z][a-z0-9-]*)=(.*)$/.exec(spec);
     if (!m) return usage(`--agent takes <name>=<model>, got ${spec}`);
     // A name outside the roster would be written, listed, and never run.
-    if (roster && !roster.includes(m[1])) return usage(`no agent named ${m[1]} in the ${cfg.layout} roster — known: ${roster.join(", ")}`);
-    if (m[2]) next.per_agent[m[1]] = m[2]; else delete next.per_agent[m[1]];
+    if (roster && !roster.includes(m[1]))
+      return usage(`no agent named ${m[1]} in the ${cfg.layout} roster — known: ${roster.join(", ")}`);
+    if (m[2]) next.per_agent[m[1]] = m[2];
+    else delete next.per_agent[m[1]];
   }
   // The clerk transcribes; a strong default must not lift it (commands/agents.md,
   // ADR-008). WHICH model it is pinned to is the harness's vocabulary, so the
@@ -590,45 +1520,189 @@ async function runAgents(ctx) {
   const clerkAsked = (values.agent || []).some((s) => s.startsWith("clerk="));
   if (next.default && !next.per_agent.clerk && !clerkAsked) {
     const cheap = harnessForOverlay(harness)?.agent_translation?.cheap_model || null;
-    if (cheap) { next.per_agent.clerk = cheap; pinnedClerk = true; }
-    else clerkPinUnavailable = true;
+    if (cheap) {
+      next.per_agent.clerk = cheap;
+      pinnedClerk = true;
+    } else clerkPinUnavailable = true;
   }
   // Keys inside the agents block that the allowlist rejected (an `effort`, a
   // stray shape) are rewritten out by the write and announced here; keys
   // outside the block are kept, and stay doctor's to name.
   const dropped = before.rejected.filter((k) => k.startsWith("agents."));
-  const same = !dropped.length && JSON.stringify({ d: before.agents.default, p: before.agents.per_agent }) === JSON.stringify({ d: next.default, p: next.per_agent });
-  const preview = [`agents configure — ${harness} — ${before.path}`, `  default: ${before.agents.default || "—"} → ${next.default || "—"}`];
+  const same =
+    !dropped.length &&
+    JSON.stringify({ d: before.agents.default, p: before.agents.per_agent }) ===
+      JSON.stringify({ d: next.default, p: next.per_agent });
+  const preview = [
+    `agents configure — ${harness} — ${before.path}`,
+    `  default: ${before.agents.default || "—"} → ${next.default || "—"}`,
+  ];
   const names = new Set([...Object.keys(before.agents.per_agent), ...Object.keys(next.per_agent)]);
-  for (const n of [...names].sort()) preview.push(`  ${n}: ${before.agents.per_agent[n] || "—"} → ${next.per_agent[n] || "—"}${pinnedClerk && n === "clerk" ? " (pinned: the clerk stays cheap under a strong default)" : ""}`);
+  for (const n of [...names].sort())
+    preview.push(
+      `  ${n}: ${before.agents.per_agent[n] || "—"} → ${next.per_agent[n] || "—"}${pinnedClerk && n === "clerk" ? " (pinned: the clerk stays cheap under a strong default)" : ""}`,
+    );
   // Silence here would read as "the clerk is fine", and it is not: it takes the
   // strong default, which is the one thing ADR-008 says must not happen to it.
-  if (clerkPinUnavailable) preview.push(`  clerk: takes the default — ${harness} declares no cheap model to pin it to, so name one with --agent clerk=<model>`);
-  if (dropped.length) preview.push(`  drops from the agents block (an overlay carries only models): ${dropped.join(", ")}`);
-  if (same) return emit("agents configure", true, { harness, path: before.path, wrote: false, agents: next, pinnedClerk, clerkPinUnavailable, dropped }, preview.join("\n") + "\n  Nothing to change.\n");
+  if (clerkPinUnavailable)
+    preview.push(
+      `  clerk: takes the default — ${harness} declares no cheap model to pin it to, so name one with --agent clerk=<model>`,
+    );
+  if (dropped.length)
+    preview.push(`  drops from the agents block (an overlay carries only models): ${dropped.join(", ")}`);
+  if (same)
+    return emit(
+      "agents configure",
+      true,
+      { harness, path: before.path, wrote: false, agents: next, pinnedClerk, clerkPinUnavailable, dropped },
+      preview.join("\n") + "\n  Nothing to change.\n",
+    );
   // The gate: a named harness confirms; otherwise ask, and refuse without a terminal.
   let confirmed = Boolean(named);
-  if (!confirmed) { const a = await confirmWrite(preview.join("\n") + `\nWrite ${before.path}? [y/N] `, { stdin, stdout, ask }); if (a === null) return usage("a non-interactive agents configure names --harness <id> to confirm; there is no --yes"); confirmed = a; }
-  if (!confirmed) return emit("agents configure", false, { harness, path: before.path, wrote: false, declined: true, agents: next, dropped }, preview.join("\n") + "\n  nothing written.\n");
+  if (!confirmed) {
+    const a = await confirmWrite(preview.join("\n") + `\nWrite ${before.path}? [y/N] `, { stdin, stdout, ask });
+    if (a === null)
+      return usage("a non-interactive agents configure names --harness <id> to confirm; there is no --yes");
+    confirmed = a;
+  }
+  if (!confirmed)
+    return emit(
+      "agents configure",
+      false,
+      { harness, path: before.path, wrote: false, declined: true, agents: next, dropped },
+      preview.join("\n") + "\n  nothing written.\n",
+    );
   const path = writeOverlayAt(project, harness, next);
   const after = readOverlayAt(project, harness);
-  return emit("agents configure", true, { harness, path, wrote: true, agents: after.agents, pinnedClerk, clerkPinUnavailable, dropped, rejected: after.rejected, agents_in_binding: inBinding }, preview.join("\n") + `\n  wrote ${path}.${inBinding ? " The binding still carries an agents block (pre-0.28); run upgrade to move it." : ""}\n`);
+  return emit(
+    "agents configure",
+    true,
+    {
+      harness,
+      path,
+      wrote: true,
+      agents: after.agents,
+      pinnedClerk,
+      clerkPinUnavailable,
+      dropped,
+      rejected: after.rejected,
+      agents_in_binding: inBinding,
+    },
+    preview.join("\n") +
+      `\n  wrote ${path}.${inBinding ? " The binding still carries an agents block (pre-0.28); run upgrade to move it." : ""}\n`,
+  );
+}
+
+// The band's switch (the band spec, contract 13): one atomic binding write per
+// change, previewed; a terminal is asked, --json is the confirmation (the
+// command that runs it has asked already), and without either it refuses.
+// `status` writes nothing.
+async function runBand(ctx) {
+  const { row, values, positionals, cfg, project, env, stdout, stderr, stdin, ask } = ctx;
+  const sub = positionals[0];
+  const arg = positionals[1];
+  const usage = (m) => usageFail(Object.assign(new Error(m), { code: "USAGE" }), { verb: row.verb, ...ctx });
+  if (!BAND_SUBCOMMANDS.includes(sub))
+    return usage(`band takes ${BAND_SUBCOMMANDS.join(", ")} (epic takes an epic id, or none to release the pin)`);
+  const emit = (verb, ok, result, text) => {
+    if (values.json) stdout.write(JSON.stringify(envelope(verb, project, ok, result), null, 2) + "\n");
+    else (ok ? stdout : stderr).write(text);
+    return ok ? 0 : 1;
+  };
+  if (sub === "status") {
+    const s = bandStatus(project, cfg, { env, root: PACKAGE_ROOT });
+    return emit("band status", true, s, renderBandStatus(s));
+  }
+  const plan = planBand(project, sub, arg, { env, root: PACKAGE_ROOT });
+  if (plan.refusal)
+    return emit(
+      `band ${sub}`,
+      false,
+      { error: plan.refusal.message, code: plan.refusal.code, path: plan.path },
+      `${plan.refusal.message}\n`,
+    );
+  const preview = renderBandPlan(plan, sub, arg);
+  if (!plan.changed)
+    return emit(
+      `band ${sub}`,
+      true,
+      { path: plan.path, wrote: false, band: plan.after },
+      preview + "  Nothing to change.\n",
+    );
+  let confirmed = Boolean(values.json);
+  if (!confirmed) {
+    const a = await confirmWrite(preview + `Write ${plan.path}? [y/N] `, { stdin, stdout, ask });
+    if (a === null) return usage("a non-interactive band write passes --json; there is no --yes");
+    confirmed = a;
+  }
+  if (!confirmed)
+    return emit(
+      `band ${sub}`,
+      false,
+      { path: plan.path, wrote: false, declined: true, band: plan.after },
+      preview + "  nothing written.\n",
+    );
+  const done = applyBand(plan);
+  return emit(
+    `band ${sub}`,
+    true,
+    { path: plan.path, wrote: done.wrote, band: plan.after },
+    preview + `  wrote ${plan.path}. The band follows within a few seconds; no restart.\n`,
+  );
+}
+
+// `session refresh <path>`: this session's pointer from a story file, after a
+// write no hook saw (the close ceremony's copy). Machine-local state, like the
+// hooks' own writes — no confirmation. No session: nothing written, exit 0.
+async function runSession(ctx) {
+  const { row, values, positionals, cfg, project, env, stdout, stderr } = ctx;
+  if (positionals[0] !== "refresh" || !positionals[1] || positionals.length > 2)
+    return usageFail(
+      Object.assign(new Error("session takes refresh <path> (a story file in the vault)"), { code: "USAGE" }),
+      {
+        verb: row.verb,
+        ...ctx,
+      },
+    );
+  const r = refreshSessionPointer(project, cfg, positionals[1], { env });
+  const ok = !r.refusal;
+  const result = ok ? r : { error: r.refusal.message, code: r.refusal.code };
+  if (values.json) stdout.write(JSON.stringify(envelope("session refresh", project, ok, result), null, 2) + "\n");
+  else if (!ok) stderr.write(`${r.refusal.message}\n`);
+  else if (!r.refreshed) stdout.write("No session id from the host: nothing written.\n");
+  else {
+    const p = r.pointer;
+    stdout.write(
+      `This session's story: ${p.story_title || p.active_story}${p.story_status ? ` (${p.story_status})` : ""}.\n`,
+    );
+  }
+  return ok ? 0 : 1;
 }
 
 async function runGraph(ctx) {
   const { row, values, positionals, cfg } = ctx;
   const sub = positionals[0];
   const path = positionals[1];
-  if (!["neighbors", "lineage"].includes(sub)) return usageFail(Object.assign(new Error("graph takes neighbors <path> or lineage <path>"), { code: "USAGE" }), { verb: row.verb, ...ctx });
+  if (!["neighbors", "lineage"].includes(sub))
+    return usageFail(Object.assign(new Error("graph takes neighbors <path> or lineage <path>"), { code: "USAGE" }), {
+      verb: row.verb,
+      ...ctx,
+    });
   const op = READ_OPERATIONS[sub];
   try {
     // The row declares the union; each mode takes its own — an option the
     // mode would ignore is a usage error, not a silent no-op.
     const notFor = sub === "neighbors" ? ["depth"] : ["direction", "limit"];
-    for (const o of notFor) if (values[o] !== undefined) throw Object.assign(new Error(`--${o} is not an option of graph ${sub}`), { code: "USAGE" });
-    const result = sub === "neighbors"
-      ? op.fn(cfg, path, { kinds: values.kind || null, direction: values.direction, limit: values.limit })
-      : op.fn(cfg, path, { depth: values.depth, kinds: values.kind && values.kind.length ? values.kind : LINEAGE_KINDS });
+    for (const o of notFor)
+      if (values[o] !== undefined)
+        throw Object.assign(new Error(`--${o} is not an option of graph ${sub}`), { code: "USAGE" });
+    const result =
+      sub === "neighbors"
+        ? op.fn(cfg, path, { kinds: values.kind || null, direction: values.direction, limit: values.limit })
+        : op.fn(cfg, path, {
+            depth: values.depth,
+            kinds: values.kind && values.kind.length ? values.kind : LINEAGE_KINDS,
+          });
     return emitRead({ verb: `graph ${sub}`, ...ctx }, op, result);
   } catch (e) {
     if (e && e.code === "USAGE") return usageFail(e, { verb: row.verb, ...ctx });
@@ -640,7 +1714,10 @@ async function runCodemap(ctx) {
   const { row, values, cfg } = ctx;
   const op = READ_OPERATIONS.codeRefs;
   try {
-    if (!values.for) throw Object.assign(new Error("codemap takes --for <selector>; regeneration is reconcile --only codemap"), { code: "USAGE" });
+    if (!values.for)
+      throw Object.assign(new Error("codemap takes --for <selector>; regeneration is reconcile --only codemap"), {
+        code: "USAGE",
+      });
     return emitRead({ verb: row.verb, ...ctx }, op, op.fn(cfg, values.for, { reverse: Boolean(values.reverse) }));
   } catch (e) {
     if (e && e.code === "USAGE") return usageFail(e, { verb: row.verb, ...ctx });
@@ -650,22 +1727,32 @@ async function runCodemap(ctx) {
 
 function runVersion({ values, stdout }) {
   const version = packageVersion();
-  stdout.write(values.json ? JSON.stringify(envelope("version", null, true, { version }), null, 2) + "\n" : version + "\n");
+  stdout.write(
+    values.json ? JSON.stringify(envelope("version", null, true, { version }), null, 2) + "\n" : version + "\n",
+  );
   return 0;
 }
 
 function spawnDoctor(project, env, flags) {
   // A project that does not exist is still a project doctor can report on
   // ("not bound") — so the cwd is only set when it can be.
-  return spawnSync(process.execPath, [script("doctor.mjs"), ...flags], { encoding: "utf8", cwd: existsSync(project) ? project : undefined, env: ownEnv(env, project), timeout: 60000, maxBuffer: 1 << 24 });
+  return spawnSync(process.execPath, [script("doctor.mjs"), ...flags], {
+    encoding: "utf8",
+    cwd: existsSync(project) ? project : undefined,
+    env: ownEnv(env, project),
+    timeout: 60000,
+    maxBuffer: 1 << 24,
+  });
 }
 
-// Spawned, never imported (MCP ADR decision 2): doctor's report and main are
-// not exported, and importing them would be a second doctor. doctor.mjs sets
-// no exit code of its own and prints either JSON or text, so text mode is
-// two spawns — one for the findings that decide the exit code, one for the
-// report the user reads. Deliberate; do not "optimise" the second away
-// without giving doctor an exit code first.
+// Spawned, never imported (MCP ADR decision 2): doctor's main writes to
+// stdout and is not exported, and importing its checks would be a second
+// doctor. One spawn, always --json: its findings decide the exit code
+// (doctor.mjs sets none of its own), and the text a person reads is drawn
+// from those same findings here, in this process, by doctor-report.mjs — a
+// renderer that imports no check (the presentation spec, contract 11). So a
+// terminal gets colour, which a piped child could not tell it had, and the
+// report and the exit code can never come from two different runs.
 async function runDoctor({ values, project, env, stdout, stderr }) {
   const sections = [values.install && "--install", values.vault && "--vault"].filter(Boolean);
   const r = spawnDoctor(project, env, ["--json", ...sections]);
@@ -677,29 +1764,76 @@ async function runDoctor({ values, project, env, stdout, stderr }) {
   if (r.error) return fail(r.error.message);
   if (r.status !== 0 && !r.stdout) return fail((r.stderr || "").trim() || `exit ${r.status}`);
   let findings;
-  try { findings = JSON.parse(r.stdout); } catch { return fail("unparseable output"); }
+  try {
+    findings = JSON.parse(r.stdout);
+  } catch {
+    return fail("unparseable output");
+  }
   const ok = !findings.some((f) => f.level === "issue");
   if (values.json) stdout.write(JSON.stringify(envelope("doctor", project, ok, findings), null, 2) + "\n");
   else {
-    const t = spawnDoctor(project, env, sections);
-    stdout.write(typeof t.stdout === "string" && t.stdout ? t.stdout : `${(t.stderr || "").trim() || "doctor printed nothing"}\n`);
+    // The sections as doctor.mjs derives them: no flag is both.
+    const groups = sections.length
+      ? [values.install && "install", values.vault && "vault"].filter(Boolean)
+      : ["install", "vault"];
+    stdout.write(
+      await doctorText(findings, groups, {
+        caps: term.caps(stdout, env),
+        verbose: Boolean(values.verbose),
+        project,
+        env: ownEnv(env, project),
+        stderr,
+      }),
+    );
   }
   return ok ? 0 : 1;
 }
 
+// doctor's text from its findings. `env` is the child's environment
+// (ownEnv), so every command form the report names is the one doctor itself
+// would name. A renderer that cannot load, or throws, must not cost the
+// reader the findings: they are printed one per line, `level check message
+// — file`, and the Summary line still ends them (lib.mjs). `load` stands in
+// for the import in a test.
+export async function doctorText(
+  findings,
+  groups,
+  { caps, verbose = false, project = null, env = process.env, stderr = null } = {},
+  { load = () => import("./doctor-report.mjs") } = {},
+) {
+  try {
+    const { report } = await load();
+    return report(findings, groups, { caps, verbose, version: packageVersion(), project, env });
+  } catch (e) {
+    if (stderr)
+      stderr.write(
+        `doctor: the report could not be drawn (${e && e.message ? e.message : e}); its findings follow, one per line.\n`,
+      );
+    return doctorFallbackText(findings, { env });
+  }
+}
+
 async function runReconcile({ values, project, env, stdin, stdout, stderr, ask }) {
   const write = Boolean(values.write);
   const only = values.only ?? null;
   // The gate: --only names what is written and confirms headless; a bare
   // --write asks on a terminal and refuses without one.
   if (write && !only) {
-    const yes = await confirmWrite(`Regenerate every derived view of ${project}'s vault? [y/N] `, { stdin, stdout, ask });
+    const yes = await confirmWrite(`Regenerate every derived view of ${project}'s vault? [y/N] `, {
+      stdin,
+      stdout,
+      ask,
+    });
     if (yes === null) {
       stderr.write("a bare reconcile --write in a non-TTY refuses; name what is written to confirm: --only <target>\n");
-      if (values.json) stdout.write(JSON.stringify(envelope("reconcile", project, false, { refused: "non-tty" }), null, 2) + "\n");
+      if (values.json)
+        stdout.write(JSON.stringify(envelope("reconcile", project, false, { refused: "non-tty" }), null, 2) + "\n");
       return 1;
     }
-    if (!yes) { stdout.write("nothing written.\n"); return 0; }
+    if (!yes) {
+      stdout.write("nothing written.\n");
+      return 0;
+    }
   }
   const { runReconcile: core } = await import("./reconcile.mjs");
   let out;
@@ -708,7 +1842,8 @@ async function runReconcile({ values, project, env, stdin, stdout, stderr, ask }
   } catch (e) {
     const msg = e && e.message ? e.message : String(e);
     stderr.write(msg + "\n");
-    if (values.json) stdout.write(JSON.stringify(envelope("reconcile", project, false, { error: msg }), null, 2) + "\n");
+    if (values.json)
+      stdout.write(JSON.stringify(envelope("reconcile", project, false, { error: msg }), null, 2) + "\n");
     return e && e.code === "UNBOUND" ? 3 : 2;
   }
   const failed = write && out.summary && out.summary.failed > 0;
@@ -716,15 +1851,57 @@ async function runReconcile({ values, project, env, stdin, stdout, stderr, ask }
   return failed ? 1 : 0;
 }
 
-async function runInstallVerb({ row, values, project, env, stdin, stdout, ask }) {
+// setup (the setup story): its own module, imported lazily as the install
+// family is, run with this package as its root and in the environment every
+// installer run gets (ownEnv, for the project setup settles on). The envelope
+// is written here, as every verb's is: its result is the write verbs' keys
+// plus `setup`. A usage error is exit 2 with its envelope.
+async function runSetupVerb(ctx) {
+  const { runSetup } = await import("./setup.mjs");
+  const { values, env, stdout } = ctx;
+  const r = await runSetup({
+    ...ctx,
+    root: PACKAGE_ROOT,
+    ownEnv: (p) => ownEnv(env, p),
+    author: (p) => gitAuthor(p, env),
+  });
+  if (r.error) return usageFail(Object.assign(new Error(r.error), { code: "USAGE" }), { verb: "setup", ...ctx });
+  if (values.json && r.result)
+    stdout.write(JSON.stringify(envelope("setup", r.project, r.ok, r.result), null, 2) + "\n");
+  return r.code;
+}
+
+async function runInstallVerb({ row, values, project, env, cwd, stdin, stdout, ask }) {
   const ih = await import("./install-harness.mjs");
-  const opts = { harnesses: values.harness || [], surfaces: values.surface && values.surface.length ? values.surface : null, globalRemoval: Boolean(values.global), register: !values["no-register"], root: PACKAGE_ROOT, env: ownEnv(env, project), stdin, stdout, ask, json: Boolean(values.json), verbose: Boolean(values.verbose) };
+  const opts = {
+    harnesses: values.harness || [],
+    surfaces: values.surface && values.surface.length ? values.surface : null,
+    globalRemoval: Boolean(values.global),
+    register: !values["no-register"],
+    root: PACKAGE_ROOT,
+    env: ownEnv(env, project),
+    cwd,
+    stdin,
+    stdout,
+    ask,
+    json: Boolean(values.json),
+    verbose: Boolean(values.verbose),
+  };
+  // plan goes through the installer's own planOptions, as its main() does, so
+  // the two entry points read the same root version for a dry-run row.
   if (row.verb === "plan") {
-    const p = ih.plan(project, opts);
-    if (values.json) stdout.write(JSON.stringify(envelope("plan", project, p.ok && !p.incomplete, { ...p, items: p.items.map(ih.publicItem) }), null, 2) + "\n");
+    const p = ih.plan(project, ih.planOptions(opts));
+    if (values.json)
+      stdout.write(
+        JSON.stringify(
+          envelope("plan", project, p.ok && !p.incomplete, { ...p, items: p.items.map(ih.publicItem) }),
+          null,
+          2,
+        ) + "\n",
+      );
     else {
       const c = term.caps(stdout, env);
-      stdout.write(ih.renderPreview(p, { verbose: opts.verbose, verb: "plan", paint: term.painter(c), icon: (n) => term.icon(c, n), width: c.live ? c.width : 0 }));
+      stdout.write(ih.renderPreview(p, { verbose: opts.verbose, verb: "plan", caps: c }));
     }
     return p.ok && !p.incomplete ? 0 : 1;
   }
@@ -735,11 +1912,30 @@ async function runInstallVerb({ row, values, project, env, stdin, stdout, ask })
   // that failed is exit 1 with the rest applied (install spec contract 4′).
   const ok = r.plan.ok && !r.plan.incomplete && !r.failed && (r.gate.confirmed || r.gate.why === "nothing-to-do");
   if (values.json) {
-    stdout.write(JSON.stringify(envelope(row.verb, project, ok, { gate: r.gate, applied: r.applied, failed: r.failed, incomplete: r.plan.incomplete, plannedAgainst: r.plan.plannedAgainst, items: r.plan.items.map(ih.publicItem), refusals: r.plan.refusals, reports: r.plan.reports }), null, 2) + "\n");
-  } else if (r.gate.why === "non-tty") {
-    stdout.write(`Nothing written: without a terminal, a bare ${row.verb} refuses. Name the harness to confirm: --harness ${r.plan.detected.map((d) => d.id).join(" | ") || harnessIds().join(" | ")}\n`);
-  } else if (r.gate.why === "declined") {
-    stdout.write("Nothing written.\n");
+    // `fetched` is additive: the shells a run fetched before its plan, [] for
+    // a run that fetched none (uninstall always).
+    stdout.write(
+      JSON.stringify(
+        envelope(row.verb, project, ok, {
+          gate: r.gate,
+          applied: r.applied,
+          failed: r.failed,
+          incomplete: r.plan.incomplete,
+          plannedAgainst: r.plan.plannedAgainst,
+          items: r.plan.items.map(ih.publicItem),
+          refusals: r.plan.refusals,
+          reports: r.plan.reports,
+          fetched: r.fetched || [],
+        }),
+        null,
+        2,
+      ) + "\n",
+    );
+  } else {
+    // The installer's own words for a gate that wrote nothing — a bare run
+    // without a terminal, a declined question, a channel switch without a
+    // terminal — shared with its main(), so the two entries say the same.
+    stdout.write(ih.gateText(r, { verb: row.verb, harnesses: opts.harnesses, caps: term.caps(stdout, env) }));
   }
   return ok ? 0 : 1;
 }