projectstore-claude 0.29.2 → 0.29.3

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,16 @@ 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 { projectRootDeclared, childEnv, harnessIds, harnessForOverlay, pinPluginRoot, invokedAs, loadHarnesses, invocation } from "./harness.mjs";
+import { readConfigAt, readOverlayAt, resolveAgentModel, writeOverlayAt, overlayId, layoutRoster, commandForm, projectDirRefusal, doctorFallbackText } 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";
+// 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));
@@ -79,9 +95,22 @@ 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 SURFACE_OPT = opt("surface", "<key>", "one surface and those beneath it", true);
@@ -90,101 +119,116 @@ const SURFACE_OPT = opt("surface", "<key>", "one surface and those beneath it",
 // "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 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];
 
 export const VERBS = Object.freeze([
   Object.freeze({
-    verb: "doctor", summary: "Check the install wiring and the vault's consistency.",
+    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"), JSON_OPT],
+    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).",
+    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.",
+    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.",
+    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.",
+    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.",
+    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.",
+    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.",
+    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.",
+    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.",
+    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.",
+    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 (≤ ${GRAPH_EDGE_CAP})`), JSON_OPT],
+    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.",
+    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).",
+    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).",
+    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: "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")}.`,
+    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.",
+    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).",
+    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 +240,39 @@ 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. Once
+// setup exists, START becomes setup and uninstall, and install and bind move
+// to ADVANCED.
 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", ["install", "bind", "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.
+// core needs and a shell fixes. A `{core}` example is the core's alone: under
+// a shell `{h}` is empty, so it would repeat the line above it and say what
+// the shell's own run does not. `{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 = {
   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"],
+  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 +284,149 @@ 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"],
+  scaffold: ["{cmd} scaffold  # what would be created; nothing is written", "{cmd} scaffold --write"],
   agents: ["{cmd} agents show", "{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"],
   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,
+// which status's and bind's next commands print too.
 
-// "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 };
+  return null;
 }
 
-function invocation(env = process.env) {
-  const shell = env.PROJECTSTORE_SHELL || null;
-  return { shell, cmd: shell ? `npx ${shell}` : "npx projectstore" };
-}
-
-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)));
+    }
   }
+  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")} `), width, "  "));
   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.
+  const h = shell ? "" : " --harness <id>";
+  const has = (verb) => verbs.some((v) => v.verb === verb);
+  const examples = [["install", `${cmd} install${h}`], ["status", `${cmd} status`], ["doctor", `${cmd} 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("install, upgrade and uninstall show their 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, [`${cmd} 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 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]));
   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);
+  // 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 = [];
+  for (const [x, note] of ex.map((e) => e.split("{cmd}").join(cmd).split("{h}").join(h).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");
 }
 
@@ -333,75 +448,218 @@ export function nearest(word, names) {
 
 // ─── 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;
+  }
+  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;
   }
-  const { values, positionals } = parsed;
+  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);
+  if (row.requiresBinding && !cfg) return fail(`${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, { project });
   try {
     return await row.run({ row, values, positionals: positionals.slice(1), cfg, project, env, cwd, stdin, stdout, stderr, ask });
   } catch (e) {
@@ -435,10 +693,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;
 }
 
@@ -490,26 +750,78 @@ 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 });
     // 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;
+  if (!vault) {
+    const why = `the binding names no usable vault path${norm && norm.error ? ` (${norm.error})` : ""} — rebind with \`projectstore bind <vault> --rebind\``;
+    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. \`projectstore init ${shellQuote(vault)}\` creates it under this binding: the directory, its git repository and the layout's folders.`;
+    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 }), 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
@@ -615,6 +927,36 @@ async function runAgents(ctx) {
   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`);
+}
+
 async function runGraph(ctx) {
   const { row, values, positionals, cfg } = ctx;
   const sub = positionals[0];
@@ -660,12 +1002,14 @@ function spawnDoctor(project, env, flags) {
   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]);
@@ -681,12 +1025,29 @@ async function runDoctor({ values, project, env, stdout, stderr }) {
   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;
@@ -716,15 +1077,17 @@ async function runReconcile({ values, project, env, stdin, stdout, stderr, ask }
   return failed ? 1 : 0;
 }
 
-async function runInstallVerb({ row, values, project, env, stdin, stdout, ask }) {
+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);
+    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 +1098,14 @@ 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, surfaces: opts.surfaces, caps: term.caps(stdout, env) }));
   }
   return ok ? 0 : 1;
 }