projectstore-codex 0.28.1 → 0.29.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "author": {
     "name": "Evgenii Konev",

package/README.md

@@ -1,6 +1,6 @@
 # projectstore-codex
 
-The Codex installer for [ProjectStore](https://github.com/SmartAndPoint/ProjectStore). It ships a canonical portable `plugin.json`, rendered namespaced workflow skills, lifecycle hooks, and the ProjectStore core pinned at the exact same version and bundled inside the tarball.
+The Codex installer for [ProjectStore](https://github.com/SmartAndPoint/ProjectStore). It ships a Codex plugin manifest (`.codex-plugin/plugin.json`), rendered namespaced workflow skills, lifecycle hooks, and the ProjectStore core pinned at the exact same version and bundled inside the tarball.
 
 From a terminal in your project:
 
@@ -8,7 +8,7 @@ From a terminal in your project:
 npx projectstore-codex install --project "$PWD"
 ```
 
-The installer previews every mutation, stages a stable local marketplace under `CODEX_HOME`, asks Codex's own CLI to install the plugin, and verifies the materialised cache by version and payload digest. Restart Codex, approve the ProjectStore hooks when prompted, then run `$projectstore-bind <vault-path>`. Codex picks up hook changes late: a release that changes hooks may take effect only in the session after next.
+The installer prints its plan first — every mutation and every Codex command, verbatim — and at a terminal asks `Apply N changes? [Y/n]` (without one, naming the shell is the confirmation; `--json` never asks). It then stages a stable local marketplace under `CODEX_HOME`, asks Codex's own CLI to install the plugin, verifies the materialised cache by version and payload digest, and says what to do next. `npx projectstore-codex plan --project "$PWD"` prints the same plan and writes nothing; `--verbose` adds every row's reasoning; `<verb> --help` lists a verb's options with examples. Restart Codex, approve the ProjectStore hooks when prompted, then run `$projectstore-bind <vault-path>`. Codex picks up hook changes late: a release that changes hooks may take effect only in the session after next.
 
 Upgrade with `npx projectstore-codex@<version> upgrade --project "$PWD"`. Project uninstall leaves the user-global Codex plugin in place; `uninstall --global` is the explicit machine-wide removal.
 

package/bin/projectstore-codex.mjs

@@ -8,8 +8,10 @@
 // `--harness codex` inserted after a verb that takes it. Every other
 // argument passes through, so `projectstore-codex <verb> …` is exactly
 // `projectstore <verb> --harness codex …` — the same preview, the
-// same files, the same exit code. Naming the shell is the confirmation the
-// core's install gate asks for, exactly as naming --harness is.
+// same files, the same exit code. Naming the shell names the harness, exactly
+// as --harness does: without a terminal that is the confirmation the core's
+// install gate asks for; at a terminal the core shows the plan and asks (the
+// install spec, contract 9 as amended 2026-10-04).
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { constants as osConstants } from "node:os";
@@ -72,17 +74,20 @@ if (!core) {
     process.stderr.write(`${SHELL}: ${fixed.error}\n`);
     process.exitCode = 2;
   } else {
-    // stdio inherited: the core's install gate asks on a terminal and refuses
-    // without one, so the child must see the real stdin and stdout. No
-    // timeout — the child waits on a human at the preview. exitCode, not
-    // exit(): the core's own bin says why (a pending write on a pipe).
+    // stdio inherited: the core's install gate shows the plan and asks on a
+    // terminal, and refuses a bare run without one, so the child must see the
+    // real stdin and stdout. No timeout — the child waits on a human at the
+    // question. exitCode, not exit(): the core's own bin says why (a pending
+    // write on a pipe). PROJECTSTORE_SHELL lets the core's --help speak this
+    // shell's name; nothing the core plans or writes reads it.
     const r = spawnSync(process.execPath, [core, ...fixed.argv], {
       stdio: "inherit",
-      env: { ...process.env, PROJECTSTORE_DISTRIBUTION_ROOT: root },
+      env: { ...process.env, PROJECTSTORE_DISTRIBUTION_ROOT: root, PROJECTSTORE_SHELL: SHELL },
     });
     if (r.error) process.stderr.write(`${SHELL}: ${r.error.message}\n`);
-    // A signal is relayed the shell way (128 + its number): Ctrl-C at the
-    // preview is 130 here as it would be on the core itself.
+    // A signal is relayed the shell way (128 + its number): the core reads
+    // its answer in the terminal's line mode, so Ctrl-C at the question is a
+    // real SIGINT — 130 here as it would be on the core itself.
     process.exitCode = r.status ?? (r.signal ? 128 + (osConstants.signals[r.signal] || 0) : 2);
   }
 }

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "projectstore",
       "displayName": "projectstore",
       "description": "📚 Your agent runs the project through a verified loop: task → artifact (ADR · spec · epic · story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
-      "version": "0.28.1",
+      "version": "0.29.0",
       "author": {
         "name": "Evgenii Konev",
         "email": "ekonev@smartandpoint.com",

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore",
   "displayName": "projectstore",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "author": {
     "name": "Evgenii Konev @ SmartAndPoint",

package/node_modules/projectstore/README.md

@@ -94,11 +94,11 @@ Contributors: `git clone` this repo, then `claude --plugin-dir ./ProjectStore`.
 npx projectstore-claude install --project "$PWD"
 ```
 
-The same tree is published to npm as [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest — and `projectstore-claude` is its Claude Code shell: the core pinned at the same version and bundled inside, the harness fixed, so the one command has the same shape on every harness. It registers the plugin with Claude Code: it writes a small local marketplace of its own under your Claude home, then drives `claude plugin marketplace add` / `plugin install` **at local scope**, so the registration lands in this checkout's `.claude/settings.local.json` and nowhere else. Every host command is printed before it runs; naming the harness is the confirmation. Restart Claude Code afterwards. A git-marketplace copy already enabled for the checkout is silenced there (not globally) so the plugin does not load twice; `uninstall` turns it back on. Pin or upgrade with `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run. The core's low-level form, `npx projectstore <verb> --harness claude-code …`, is exactly what the shell runs. bun works the same on the packed bin.
+The same tree is published to npm as [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest — and `projectstore-claude` is its Claude Code shell: the core pinned at the same version and bundled inside, the harness fixed, so the one command has the same shape on every harness. It registers the plugin with Claude Code: it writes a small local marketplace of its own under your Claude home, then drives `claude plugin marketplace add` / `plugin install` **at local scope**, so the registration lands in this checkout's `.claude/settings.local.json` and nowhere else. It prints its plan first — every file it writes and every host command, verbatim — and at a terminal asks `Apply N changes? [Y/n]`; then it shows each step as it runs and what to do next. Without a terminal (a script, CI, an agent's tool) naming the harness is the confirmation. `plan` prints the same plan and writes nothing; `--verbose` adds every row's reasoning; `npx projectstore-claude <verb> --help` lists a verb's options with examples. Restart Claude Code afterwards. A git-marketplace copy already enabled for the checkout is silenced there (not globally) so the plugin does not load twice; `uninstall` turns it back on. Pin or upgrade with `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run. The core's low-level form, `npx projectstore <verb> --harness claude-code …`, is exactly what the shell runs. bun works the same on the packed bin.
 
 **Codex has its own shell with the same one-command shape:**
-`npx projectstore-codex install --project "$PWD"`. It carries a canonical
-portable manifest, namespaced workflow and role skills, lifecycle hooks, and
+`npx projectstore-codex install --project "$PWD"`. It carries a Codex
+plugin manifest, namespaced workflow and role skills, lifecycle hooks, and
 the exact bundled core. It stages a stable marketplace under `CODEX_HOME`,
 drives `codex plugin marketplace add` and `codex plugin add`, then reads the
 installation back and verifies its version and payload digest. Restart Codex,
@@ -120,7 +120,7 @@ The package also carries a `bin`. Without a session — in CI, or in a shell —
 
 ```
 npx projectstore doctor --json
-npx projectstore install --harness claude-code   # the low-level form the shell runs: previews, then writes the agents block and the status line; naming the harness is the confirmation, there is no --yes
+npx projectstore install --harness claude-code   # the low-level form the shell runs: shows the plan, asks at a terminal, then writes; without a terminal naming the harness is the confirmation — there is no --yes
 npx projectstore reconcile --write --only kanban
 ```
 

package/node_modules/projectstore/docs/harnesses.md

@@ -45,14 +45,15 @@ model names and those are harness-specific — is
 
 ## Codex
 
-Experimental, measured on `codex-cli 0.153.4`. The initial spike captured 759
+Experimental, measured on `codex-cli 0.153.4` and, for hook loading, 0.160.0.
+The initial spike captured 759
 hook firings. The 2026-09-30 gate then built the npm shell from a packed core,
 passed Codex's plugin validator, installed and upgraded it through an isolated
 `CODEX_HOME`, verified the materialised cache by version and digest, and loaded
 the `projectstore-status` skill in a fresh Codex session. The validator (the
 plugin-creator skill's `validate_plugin.py`) reads only
-`.codex-plugin/plugin.json`. The canonical root `plugin.json` was validated
-separately on 2026-10-04, against the schema it declares (Agent Plugins 1.0.0).
+`.codex-plugin/plugin.json`, which from 0.28.2 is the shell's only manifest
+(below).
 
 That run exercised one skill, not every installed surface, so `verified` stays
 `null`. The hooks are the reason it matters. On 2026-10-03 the first real
@@ -63,7 +64,8 @@ was all the user saw. The core had taken the shell's root for its own. That is
 fixed, and the suite now runs every rendered hook from the built shell. A live
 Codex session firing them from an installed release is still owed.
 
-How 0.153.4 starts a hook was read from its source, not measured: under the
+How 0.153.4 starts a hook was read from its source; on 0.160.0 it was seen
+once, with the hook's `$0` reading `/bin/zsh` and `node` found. Under the
 session's shell as `<shell> -c`, with the environment the Codex process had when
 it built the session's hooks. `$SHELL -lc` (or `/bin/sh -lc`) is the fallback
 when the hooks are built without exactly one ready local environment. So a hook
@@ -93,16 +95,27 @@ npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").ve
 
 What is known, and how:
 
-- **Hooks are rendered; their live firing from an installed release is not
-  yet observed.** The canonical portable `plugin.json` selects
-  `./hooks/hooks.json` through `extensions.com.openai`; the compatibility
-  `.codex-plugin/plugin.json` stays inside the current ingestion schema. Five
+- **Hooks load from Codex's default file, so the shell carries no root
+  `plugin.json`.** `.codex-plugin/plugin.json` is its only manifest and names
+  no hooks, so Codex falls back to `hooks/hooks.json`. 0.28.1, and every
+  build from a checkout since rc.3, also carried a root Agent Plugins
+  `plugin.json`, with the hooks under `extensions.com.openai`. Codex picks
+  that manifest first, and since openai/codex#37027 (merged 2026-08-05; in
+  `codex-cli` 0.153.4 and 0.160.0 alike) it loads no hooks from that format.
+  So no hook of ours loaded from those builds on any Codex measured here
+  (0.153.4, 0.160.0). On the maintainer's machine
+  on 2026-10-04, `/hooks` listed none of ours; with that file renamed away in
+  the installed cache, it listed all six, and the app server's `hooks/list`
+  gives 0 for 0.28.1's root and 6 for 0.28.2's. Five
   events: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`.
   Of the 759 captured firings, 757 came from the earlier inline form, across
   `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse` and `Stop`,
   and 2 from a file-site `hooks/hooks.json` with an absolute `node` path.
-  `PreCompact` has never been observed firing on Codex, and neither has the
-  `${PLUGIN_ROOT}` form selected through `extensions.com.openai`. The hook process
+  That live `codex-cli` 0.160.0 session ran on a hand-edited 0.28.1 cache, not
+  an installed release. Our SessionStart and PreCompact were observed in it. A
+  throwaway recorder saw PreToolUse, PostToolUse and Stop fire, but ours on
+  PostToolUse, matched to `apply_patch`, still awaits a write. SessionStart ran
+  on the session's first message, not when the window opened. The hook process
   receives `PLUGIN_ROOT` in its environment, naming the shell's root with the
   core beneath it in `node_modules/projectstore/`, and **no project-directory
   variable at all**. The project comes from the payload's `cwd`, which every

package/node_modules/projectstore/harnesses/claude-code.json

@@ -20,6 +20,9 @@
       "/plugin marketplace add SmartAndPoint/ProjectStore && /plugin install projectstore@SmartAndPoint   (git marketplace, user-wide)",
       "restart Claude Code"
     ],
+    "next": [
+      "restart Claude Code in this project"
+    ],
     "notes": [
       "Git marketplace only: auto-update is OFF by default for third-party plugins: /plugin -> Marketplaces -> SmartAndPoint -> toggle auto-update. The npm registration updates when you run `npx projectstore-claude upgrade --project <dir>`.",
       "Pin a git-marketplace release with: /plugin marketplace add SmartAndPoint/ProjectStore#<tag>; pin the npm registration with npx projectstore-claude@<version>.",

package/node_modules/projectstore/harnesses/codex.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Harness capability manifest — Codex. The committed adapters/codex tree renders the source commands, roles, passive skills and hooks into Codex vocabulary. Measurements began with 759 captured hook firings on 2026-09-07/08; the complete built shell, isolated marketplace install, upgrade, validator and fresh-session skill load passed on codex-cli 0.153.4 on 2026-09-30. The validator reads only .codex-plugin/plugin.json; the canonical root plugin.json was validated separately on 2026-10-04 against the schema it declares (Agent Plugins 1.0.0).",
+  "_comment": "Harness capability manifest — Codex. The committed adapters/codex tree renders the source commands, roles, passive skills and hooks into Codex vocabulary. Measurements began with 759 captured hook firings on 2026-09-07/08; the complete built shell, isolated marketplace install, upgrade, validator and fresh-session skill load passed on codex-cli 0.153.4 on 2026-09-30. The validator reads only .codex-plugin/plugin.json, which from 0.28.2 is the shell's one manifest: Codex picks a root Agent Plugins plugin.json first and has loaded no hooks from that format since openai/codex#37027 (merged 2026-08-05).",
   "id": "codex",
   "display_name": "Codex",
   "emit": true,
@@ -54,7 +54,7 @@
   },
   "hooks": {
     "config_file": "hooks/hooks.json",
-    "config_file_reason": "The canonical portable plugin.json selects ./hooks/hooks.json under extensions.com.openai; the compatibility manifest selects the same root-relative file. This keeps one rendered hook definition for both loaders. The legacy inline form fired 757 events across five event types; the file-selected portable form is gated by the compatibility matrix and fresh-session run.",
+    "config_file_reason": "Codex's default hooks file. A legacy .codex-plugin/plugin.json with no `hooks` key falls back to hooks/hooks.json (DEFAULT_HOOKS_CONFIG_FILE in codex-rs/core-plugins/src/loader.rs at rust-v0.160.0), so the manifest names no hooks at all. The shell ships no root Agent Plugins plugin.json. Codex picks that manifest first and then loads no hooks from it, a runtime boundary since openai/codex#37027 (loader.rs:955 at rust-v0.153.4, 952-962 at rust-v0.160.0). With one, the maintainer's codex-cli 0.160.0 listed none of ours in /hooks on 2026-10-04; with the file renamed away in the installed cache, it listed all six. The app-server's hooks/list agrees: 0 for 0.28.1's root, 6 for 0.28.2's. The spike's inline form fired 757 events across five event types.",
     "events": {
       "SessionStart": "SessionStart",
       "PreToolUse": "PreToolUse",
@@ -192,7 +192,7 @@
       "supported": true,
       "kind": "host",
       "scope": "user",
-      "scope_reason": "Selected by canonical plugin.json and the compatibility manifest, then loaded with the plugin; trust is granted per hook, machine-wide, and cannot be silenced per checkout."
+      "scope_reason": "Loaded with the plugin from its default hooks/hooks.json, which .codex-plugin/plugin.json leaves to Codex by naming no hooks; trust is granted per hook, machine-wide, and cannot be silenced per checkout."
     },
     "mcp": {
       "supported": false,
@@ -298,6 +298,10 @@
       "restart Codex and approve the ProjectStore hooks when prompted",
       "run `$projectstore-bind <vault-path>` in Codex"
     ],
+    "next": [
+      "restart Codex from a terminal and approve the ProjectStore hooks when it asks",
+      "in an unbound project, run `$projectstore-bind <vault-path>` in Codex"
+    ],
     "notes": [
       "The installation is user-global because Codex's marketplace, plugin row and cache live in CODEX_HOME; the AGENTS.md block is project-local.",
       "Upgrade with `npx projectstore-codex@<version> upgrade --project \"$PWD\"`; the named package version is also the plugin version.",

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",

package/node_modules/projectstore/scripts/build-adapters.mjs

@@ -80,10 +80,11 @@ const COMMAND_OVERRIDES = {
 
 ## register / unregister
 
-Preview the requested change and ask for explicit approval. On approval, run the
-core's \`install\` or \`uninstall\` verb with \`--harness codex --surface
-agents_block --project "$PWD"\`. Print its output verbatim. Never edit the
-managed block by hand.
+Preview the requested change with \`plan --harness codex --surface agents_block
+--project "$PWD"\` and ask for explicit approval. On approval, run the core's
+\`install\` or \`uninstall\` verb with \`--harness codex --surface agents_block
+--project "$PWD" --json\` — \`--json\` never waits on a terminal's question — and
+report the envelope's result. Never edit the managed block by hand.
 
 ## status
 
@@ -134,7 +135,9 @@ arguments and \`--json\`. Summarize every finding without re-deriving it.
 When \`--fix\` is absent, remain read-only. When it is present, separate fixes
 by owner: derived vault views use \`$projectstore-reconcile\`; Codex plugin or
 agents-block drift uses the core's \`upgrade --harness codex\` path. Preview
-each mutation and ask for explicit approval before running it. Unsupported
+each mutation with \`plan --harness codex\` and ask for explicit approval before
+running it; then run \`upgrade --harness codex --json\`, whose envelope is the
+result — \`--json\` never waits on a terminal's question. Unsupported
 surfaces remain unsupported; do not create host configuration by hand. Never
 claim a fix after a non-zero exit.`,
   },

package/node_modules/projectstore/scripts/cli.mjs

@@ -41,7 +41,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { createInterface } from "node:readline/promises";
+import * as term from "./term.mjs";
 import { projectRootDeclared, childEnv, harnessIds, harnessForOverlay, pinPluginRoot } from "./harness.mjs";
 import { readConfigAt, readOverlayAt, resolveAgentModel, writeOverlayAt, overlayId, layoutRoster } from "./lib.mjs";
 import { READ_OPERATIONS, LINEAGE_KINDS, LINEAGE_DEFAULT_DEPTH, SEARCH_DEFAULT_LIMIT, GRAPH_EDGE_CAP, DIRECTIONS } from "./query.mjs";
@@ -83,14 +83,15 @@ export function resolveProject({ project = null, env = process.env, cwd = proces
 const opt = (name, arg, summary, multiple = false) => Object.freeze({ name, arg, summary, multiple });
 const JSON_OPT = opt("json", false, "the envelope");
 const READ_JSON = [JSON_OPT];
-const HARNESS_OPT = opt("harness", "<id>", "the harness — and, non-interactively, the confirmation; 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 INSTALL_OPTS = [HARNESS_OPT, SURFACE_OPT, NO_REGISTER_OPT, JSON_OPT];
-const UNINSTALL_OPTS = [HARNESS_OPT, SURFACE_OPT, opt("global", false, "also remove the harness-global plugin registration"), JSON_OPT];
+const VERBOSE_OPT = opt("verbose", false, "every row's reasoning, each step's why and the host's own notes");
+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({
@@ -195,17 +196,141 @@ export const VERBS = Object.freeze([
 // story that adds a verb in slices.
 export const PLANNED_VERBS = Object.freeze([]);
 
-export function usage() {
-  const lines = ["usage: projectstore <verb> [options] [--project <dir>] [--json]", "", "verbs:"];
-  for (const v of VERBS) {
-    lines.push(`  ${v.verb.padEnd(11)} ${v.summary}`);
-    for (const o of v.options) lines.push(`    --${o.name}${o.arg ? " " + o.arg : ""}${o.multiple ? " (repeatable)" : ""}  ${o.summary}`);
+// 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.
+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"]],
+];
+
+// 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.
+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"],
+  plan: ["{cmd} plan{h}", "{cmd} plan{h} --json  # one envelope, for scripts and agents"],
+  status: ["{cmd} status", "{cmd} status --json"],
+  orientation: ["{cmd} orientation --json"],
+  search: ['{cmd} search "entry rule" --kind spec', "{cmd} search queue --status accepted --limit 5"],
+  show: ["{cmd} show adr/README.md", "{cmd} show epics/PS-CORE/epic.md --section acceptance"],
+  graph: ["{cmd} graph neighbors adr/README.md --direction out", "{cmd} graph lineage epics/PS-CORE/epic.md --depth 2"],
+  codemap: ["{cmd} codemap --for PS-CORE", "{cmd} codemap --for scripts/lib.mjs --reverse"],
+  doctor: ["{cmd} doctor", "{cmd} doctor --install --json"],
+  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"],
+  mcp: ['{cmd} mcp --project "$PWD"'],
+};
+
+// Positional arguments a summary does not already name.
+const ARGS = { search: "<phrase>", show: "<path>" };
+
+// "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) };
+  }
+  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" };
+}
+
+function optionLines(options) {
+  const rows = options.map((o) => [`--${o.name}${o.arg ? " " + o.arg : ""}`, `${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 EXIT_CODES = "Exit codes  0 ok · 1 findings or a refusal · 2 usage · 3 not bound";
+
+export function usage(env = process.env) {
+  const { cmd } = invocation(env);
+  const lines = [
+    "projectstore — project memory for coding agents: decisions, specs, epics and stories as plain markdown.",
+    "",
+    "Usage",
+    `  ${cmd} <verb> [options]`,
+    `  ${cmd} <verb> --help       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) {
+    if (!rows.length) continue;
+    lines.push("", title);
+    for (const v of rows) lines.push(`  ${v.verb.padEnd(12)} ${v.summary}`);
   }
-  if (PLANNED_VERBS.length) lines.push("", `  planned: ${PLANNED_VERBS.map((v) => `${v.verb} (${v.lands})`).join(", ")}`);
-  lines.push("", `  harnesses: ${harnessIds().join(", ")}`, "  --version  print the package version", "  exit codes: 0 ok, 1 findings or refusal, 2 usage, 3 not bound");
+  if (PLANNED_VERBS.length) lines.push("", `Planned: ${PLANNED_VERBS.map((v) => `${v.verb} (${v.lands})`).join(", ")}`);
+  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,
+  );
   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);
+  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);
+  return lines.join("\n");
+}
+
+// The nearest name within two edits — for a mistyped verb or option.
+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));
+    return m[a.length][b.length];
+  };
+  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; }
+  }
+  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 } = {}) {
@@ -217,7 +342,7 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
       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" },
+        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" },
@@ -228,7 +353,14 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
   } 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");
-    stderr.write(`${e.message}\n${usage()}\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;
   }
   const { values, positionals } = parsed;
@@ -236,7 +368,7 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
   // 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() + "\n" : ""));
+    stderr.write(message + "\n" + (help ? usage(env) + "\n" : ""));
     return code;
   };
   // In-process reads resolve layouts and registries from THIS package, as the
@@ -244,11 +376,17 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
   // session's variable points at.
   pinPluginRoot(PACKAGE_ROOT);
   if (values.version) return runVersion({ values, stdout });
-  if (values.help || !positionals.length) { (values.help ? stdout : stderr).write(usage() + "\n"); return values.help ? 0 : 2; }
+  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);
   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
@@ -257,7 +395,10 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
   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) return fail(verb, null, `${verb} does not take --${stray[0]}`, 2, { help: true });
+  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 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 /projectstore:bind <vault> in a session, or \`projectstore bind <vault>\` (\`projectstore init <vault>\` also creates the vault).`, 3);
@@ -285,8 +426,9 @@ function ownEnv(env, project) {
 async function confirmWrite(question, { stdin, stdout, ask }) {
   if (ask) return /^y(es)?$/i.test(String(await ask(question)).trim());
   if (!(stdin && stdin.isTTY && stdout && stdout.isTTY)) return null; // no terminal: refuse
-  const rl = createInterface({ input: stdin, output: stdout });
-  try { return /^y(es)?$/i.test(String(await rl.question(question)).trim()); } finally { rl.close(); }
+  // End of input is a no (term.mjs askLine), never a question left pending.
+  const answer = await term.askLine(question, stdin, stdout);
+  return answer !== null && /^y(es)?$/i.test(answer.trim());
 }
 
 // ─── verbs ─────────────────────────────────────────────────────────────
@@ -573,23 +715,28 @@ async function runReconcile({ values, project, env, stdin, stdout, stderr, ask }
 
 async function runInstallVerb({ row, values, project, env, 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 };
+  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) };
   if (row.verb === "plan") {
     const p = ih.plan(project, opts);
-    stdout.write(values.json ? JSON.stringify(envelope("plan", project, p.ok && !p.incomplete, { ...p, items: p.items.map(ih.publicItem) }), null, 2) + "\n" : ih.renderPreview(p));
+    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 }));
+    }
     return p.ok && !p.incomplete ? 0 : 1;
   }
-  const r = await ih.runVerb(row.verb, project, opts);
+  // Text mode hands runVerb the stream: the plan is printed before any
+  // question, then each step, then DONE (install spec contracts 9 and 18).
+  const r = await ih.runVerb(row.verb, project, values.json ? opts : { ...opts, out: stdout });
   // A registration the plan could not make (no host CLI) or a host command
   // 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 {
-    stdout.write(r.preview);
-    if (r.gate.confirmed) stdout.write(ih.appliedLine(r));
-    else if (r.gate.why === "non-tty") stdout.write(`a bare ${row.verb} in a non-TTY refuses; name a 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");
+  } 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");
   }
   return ok ? 0 : 1;
 }