projectstore-claude 0.29.4 → 0.30.0

package/README.md

@@ -1,25 +1,26 @@
 # projectstore-claude
 
-The Claude Code installer for [projectstore](https://www.npmjs.com/package/projectstore): the core, pinned at exactly this version and bundled inside this tarball, with the harness fixed. One command, from a terminal **outside** a Claude Code session:
+> **To install ProjectStore, run `npx projectstore setup` from a terminal in your project.** This package is a release artifact; you do not need it.
+
+The Claude Code distribution shell of [projectstore](https://www.npmjs.com/package/projectstore): the core, pinned at exactly this version and bundled inside this tarball, with the harness fixed to Claude Code.
+
+From a terminal in your project:
 
 ```sh
-npx projectstore-claude install --project "$PWD"
+npx projectstore setup
 ```
 
-It registers the plugin for that checkout at the host's local scope. It prints its plan first — every write and every host command, verbatim — and at a terminal asks `◆ Apply N changes? [Y/n]` before anything runs; then each step as it runs, and what to do next. Without a terminal (a script, CI, an agent's tool) naming the shell is the confirmation; `--json` never asks. Restart Claude Code afterwards.
-
-- See before you write: `npx projectstore-claude plan --project "$PWD"` 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.
+Setup finds the coding agents the project uses, Claude Code among them, and installs ProjectStore for each, with a vault for the project's notes. It asks a few questions, prints one plan — every write and every host command, verbatim — and asks once before anything runs. For Claude Code it registers the plugin for that checkout at the host's local scope, through a small local marketplace under your Claude home. Restart Claude Code afterwards.
 
-- Upgrade, or pin: `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run.
-- Behind a registry mirror: if `npx` answers `could not determine executable to run`, the mirror's index knows only the reserved `0.0.1` placeholder — name the version, and if needed the public registry: `npx --registry https://registry.npmjs.org projectstore-claude@<version> install --project "$PWD"`.
-- Uninstall: `npx projectstore-claude uninstall --project "$PWD"` — forgets the registration for that checkout and nothing else; your vault is plain markdown and stays yours.
-- `doctor`, `status`, `search` and the other read verbs pass through unchanged: `npx projectstore-claude doctor --json`.
+Upgrade, or pin, from the same place; the version you name is the version you run:
 
-This shell is `projectstore <verb> --harness claude-code` and nothing more. `bin/projectstore-claude.mjs` locates the bundled core under `node_modules/projectstore/` and execs it; the core's low-level form — `npx projectstore install --harness claude-code --project "$PWD"` — is exactly what runs. A different `--harness` is refused (exit 2). The shell carries no plugin of its own: the plugin Claude Code loads is the bundled core, registered through a small local marketplace under your Claude home.
+```sh
+npx projectstore@<version> upgrade
+```
 
-Why from a terminal: the host CLI and a live session both rewrite the same settings files, so the core defers the registration inside a session and says so.
+This shell's bin is `projectstore <verb> --harness claude-code` and nothing more. `bin/projectstore-claude.mjs` locates the bundled core under `node_modules/projectstore/` and execs it; a different `--harness` is refused (exit 2). The shell carries no plugin of its own: the plugin Claude Code loads is the bundled core.
 
-- Docs: https://github.com/SmartAndPoint/ProjectStore#install--one-message
+- Docs: https://github.com/SmartAndPoint/ProjectStore#install
 - Source: https://github.com/SmartAndPoint/ProjectStore
 - Issues: https://github.com/SmartAndPoint/ProjectStore/issues
 

package/bin/projectstore-claude.mjs

@@ -57,7 +57,7 @@ function fixHarness(argv) {
     }
   }
   const other = given.find((g) => g !== HARNESS);
-  if (other !== undefined) return { error: `installs for ${HARNESS} only — \`--harness ${other}\` names another harness. Run that harness's shell, or the core: npx projectstore <verb> --harness ${other} …` };
+  if (other !== undefined) return { error: `installs for ${HARNESS} only — \`--harness ${other}\` names another harness. Run the core: npx projectstore <verb> --harness ${other} …` };
   if (given.length) return { argv }; // named already: pass through, never twice (the core's option repeats)
   const at = scan.findIndex((a) => !a.startsWith("-"));
   if (at === -1 || !HARNESS_VERBS.has(scan[at])) return { argv };

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.29.4",
+      "version": "0.30.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.29.4",
+  "version": "0.30.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

@@ -4,7 +4,7 @@
 
 [![release](https://img.shields.io/github/v/release/SmartAndPoint/ProjectStore?label=release)](https://github.com/SmartAndPoint/ProjectStore/releases) [![license](https://img.shields.io/github/license/SmartAndPoint/ProjectStore?label=license)](./LICENSE) [![Star on GitHub](https://img.shields.io/badge/%E2%AD%90-star_us-yellow?logo=github)](https://github.com/SmartAndPoint/ProjectStore/stargazers)
 
-A project workflow plugin for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex](https://developers.openai.com/codex/) (experimental). Both are released together at one version, and each installs with one command.
+A project workflow plugin for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex](https://developers.openai.com/codex/) (experimental). Both are released together at one version, and one command sets a project up for either or both: see [Install](#install).
 
 ---
 
@@ -75,24 +75,40 @@ In Claude Code a band above the prompt goes further (experimental): the session'
 
 Open the vault in [Obsidian](https://obsidian.md) and you get the graph view and the board for free. Don't use Obsidian? Everything renders on GitHub and in any editor.
 
-## Install — one message
+## Install
 
-Open Claude Code in your project and say:
+From a terminal in your project:
 
-> Install the projectstore plugin from https://github.com/SmartAndPoint/ProjectStore and set it up for this project.
+```
+npx projectstore setup
+```
 
-That's the whole setup. Claude adds the marketplace, installs the plugin, and walks you through binding a vault, scaffolding it and wiring the status line — every step previewed, nothing written without your Yes.
+Setup finds the coding agents the project uses — Claude Code, Codex or both — and installs ProjectStore for each, with a vault for the project's notes. At a terminal it asks a few questions: which folder is the project, which agents to install for, where the vault lives (an existing folder is bound; a missing or empty one becomes a new vault, with its own git repository and the layout's folders) and whether to show ProjectStore in the status line. Then it prints one plan — every file it writes and every host command, verbatim — and asks once before it writes anything. Restart the agent afterwards; Codex asks you to approve the ProjectStore hooks once.
 
-**On Codex**, run one command from a terminal in your project:
+`npx projectstore setup --dry-run` shows the questions and the plan and writes nothing. Without a terminal (a script, CI, an agent's tool) nothing is asked: `--harness <id>` names an agent and is the confirmation, and `--vault <path>` names the vault. `npx projectstore setup --help` lists the rest.
+
+If you prefer a global command:
 
 ```
-npx projectstore-codex install --project "$PWD"
+npm install -g projectstore
+projectstore setup
 ```
 
-Then restart Codex, approve the ProjectStore hooks when it asks, and run `$projectstore-bind ~/Documents/my-project-vault`. Codex support is newer and still labelled experimental: [`docs/harnesses.md`](./docs/harnesses.md#codex) says what has been verified and what has not. A project can be worked from both agents: they share the binding in `.projectstore/`, and each keeps its own overlay and session state beside it ([running both over one project](./docs/harnesses.md#running-both-over-one-project)).
+Behind a registry mirror (often a company's), `npx` runs the newest `projectstore` the mirror knows. That can be a release older than setup, which answers that `setup` is an unknown verb, or no release at all. Name the version, and if that is not enough, the public registry:
 
-<details>
-<summary>Prefer to type it yourself?</summary>
+```
+npm_config_registry=https://registry.npmjs.org npx projectstore@<version> setup
+```
+
+npm reads that variable wherever it runs, so the Codex plugin setup fetches comes from the same registry.
+
+### In a Claude Code session
+
+Open Claude Code in your project and say:
+
+> Install the projectstore plugin from https://github.com/SmartAndPoint/ProjectStore and set it up for this project.
+
+Claude adds the git marketplace, installs the plugin, and walks you through binding a vault, scaffolding it and wiring the status line — every step previewed, nothing written without your Yes. Or type it yourself:
 
 ```
 /plugin marketplace add SmartAndPoint/ProjectStore
@@ -103,49 +119,31 @@ Then restart Codex, approve the ProjectStore hooks when it asks, and run `$proje
 
 One switch worth flipping: Claude Code does **not** auto-update third-party plugins by default — `/plugin` → **Marketplaces** → **SmartAndPoint** → toggle **auto-update** on. If you skip it, `/projectstore:doctor` will remind you later with the exact setting.
 
-Contributors: `git clone` this repo, then `claude --plugin-dir ./ProjectStore`.
-
-**Or from npm, in one command** — from a terminal, not inside a Claude Code session:
+Contributors: `git clone` this repo, then run Claude Code from the clone's parent folder:
 
 ```
-npx projectstore-claude install --project "$PWD"
+claude --plugin-dir ./ProjectStore
 ```
 
-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.
+<details>
+<summary>What setup does for each agent, the low-level verbs, the CLI and MCP</summary>
 
-**Codex has its own shell with the same one-command shape:**
-`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. Before it
-changes anything it asks Codex for that read-back (`codex plugin list --json`),
-so a Codex too old to answer stops the registration before it changes anything
-and tells you to upgrade Codex. Restart Codex,
-approve the hooks, and run `$projectstore-bind <vault-path>`. For later
-releases, `npx projectstore-codex@<version> upgrade --project "$PWD"`. Because
-Codex's plugin registry is user-global, ordinary uninstall removes only the
-project's agents block; `uninstall --global` is the explicit machine-wide
-removal. If `npx` answers `could not determine executable to run`, your
-registry (often a company mirror) serves a stale index that knows only the
-reserved `0.0.1` placeholder: name the version, and if that is not enough, the
-public registry: `npx --registry https://registry.npmjs.org
-projectstore-codex@<version> install --project "$PWD"` (the same holds for
-`projectstore-claude`). Codex is **experimental** until a live session has exercised every
-surface it installs; [`docs/harnesses.md`](./docs/harnesses.md) says what has
-been measured and what has not. From a checkout, the same npx path runs against
-a built tarball:
+**Claude Code.** Setup registers the plugin from the npm package [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest. 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. The host CLI and a live session both rewrite the same settings files, so inside a Claude Code session the registration is deferred, and the plan says so: run setup from a terminal outside the session. When the checkout already loads ProjectStore from the git marketplace, setup asks whether to switch this project to the npm install or keep the git marketplace. A switch silences the git-marketplace copy for this checkout only (not globally), so the plugin does not load twice; `uninstall` turns it back on.
 
-```sh
-npm run shells:build -- --only projectstore-codex --dev --out dist
-npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").version').tgz" projectstore-codex install --project "$PWD"
+**Codex.** The Codex plugin ships in a package of its own; setup fetches it at setup's own version and plans Codex in the same plan as everything else. 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. Before it changes anything it asks Codex for that read-back (`codex plugin list --json`), so a Codex too old to answer stops the registration before it changes anything and tells you to upgrade Codex. Codex's plugin registry is user-global; the agents block in `AGENTS.md` stays project-local. Codex is **experimental** until a live session has exercised every surface it installs: [`docs/harnesses.md`](./docs/harnesses.md#codex) says what has been verified and what has not. A project can be worked from both agents: they share the binding in `.projectstore/`, and each keeps its own overlay and session state beside it ([running both over one project](./docs/harnesses.md#running-both-over-one-project)).
+
+**The low-level verbs.** Setup composes verbs that also run on their own. One agent's install, with no questions about the project or the vault:
+
+```
+npx projectstore install --harness claude-code   # shows the plan, asks at a terminal, then writes; without a terminal naming the harness is the confirmation — there is no --yes
 ```
 
-The package also carries a `bin`. Without a session — in CI, or in a shell — the same core answers token-free, with a `--json` envelope on every verb:
+`plan` prints the same plan and writes nothing; `--verbose` adds every row's reasoning; `npx projectstore <verb> --help` lists a verb's options with examples. bun works the same on the packed bin.
+
+Without a session — in CI, or in a shell — the same core answers token-free, with a `--json` envelope on every verb:
 
 ```
 npx projectstore doctor --json
-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
 ```
 
@@ -175,43 +173,76 @@ npx projectstore init ~/vaults/new-project --language ru
 npx projectstore scaffold --write
 ```
 
-`projectstore-claude`, `projectstore-codex` and `projectstore-opencode` are this package's per-harness shells — the core pinned and bundled, the harness fixed. The Claude Code and Codex shells are published at the core's version; Codex stays labelled experimental until a live run has exercised every surface it installs ([`docs/harnesses.md`](./docs/harnesses.md)). The opencode shell publishes after its plugin root is rendered. The other `projectstore-*` names are reserved placeholders pointing back here. One source package, one version, N tarballs.
+`projectstore-claude`, `projectstore-codex` and `projectstore-opencode` are release artifacts: per-harness packages that carry the core, pinned at the same version and bundled, with the harness fixed. Nobody needs to type their names. Setup fetches the Codex one, which carries the Codex plugin; the Claude Code one is published at the core's version too; the opencode one publishes after its plugin root is rendered. The other `projectstore-*` names are reserved placeholders pointing back here. One source package, one version, N tarballs. How a release builds and publishes them, and how to run a checkout's own build: [`packaging/README.md`](./packaging/README.md).
 </details>
 
 ## Upgrading
 
-`/plugin update` (or auto-update) and a restart, then one command per project
-bound before 0.28. What an existing project sees afterwards, and why:
+Installed with setup or from npm: from a terminal in your project, name the version you want to run (`latest` is the newest):
+
+```
+npx projectstore@<version> upgrade
+```
+
+It upgrades every agent the project uses — each one whose own directory (`.claude/`, `.codex/`) or `.projectstore/state/<id>/` is there — in one plan, and fetches the Codex plugin at the same version. `npx projectstore setup` converges a project the same way and asks its questions again. Installed from the git marketplace in a Claude Code session: `/plugin update` (or auto-update) and a restart.
+
+A bare upgrade selects agents by those directories, so on Codex name it, which upgrades Codex even in a project where no Codex session has run yet:
+
+```
+npx projectstore@<version> upgrade --harness codex
+```
+
+With the global command, update it first, then run it in the project:
+
+```
+npm install -g projectstore@latest
+projectstore upgrade
+```
+
+A project bound before 0.28 needs one more command. What an existing project sees afterwards, and why:
 
 - **The project's files move to `.projectstore/`.** `.claude/projectstore.json`
   and `.claude/.projectstore/` become `.projectstore/projectstore.json`,
   `.projectstore/harness/claude-code.json` and `.projectstore/state/`. Nothing
   breaks before you move them: every reader falls back to the old paths through
-  0.29, and the startup line names the command until the move is done. Close
-  every Claude Code session in the project, run that command from a terminal,
-  then restart. The command depends on how you installed:
-  - **From the git marketplace** (every 0.27.x install): the installed copy's
-    own `bin/projectstore.mjs`, with its path spelled out in the startup line —
-    `node "<plugin cache>/bin/projectstore.mjs" upgrade --harness claude-code --no-register --project "$PWD"`.
-    `--no-register` leaves your plugin registration as it is.
-  - **From npm**: `npx projectstore-claude@<version> upgrade --no-register --project "$PWD"`.
-
-  Both forms move only the project's files, so neither touches your plugin
-  registration. The same run re-stamps the status-line launcher at its new path
-  and re-registers the agents block, whose template is now v4. A plain
-  `npx projectstore-claude upgrade` on a git-marketplace install does more: it
+  0.30, and the startup line names the command until the move is done. Close
+  every Claude Code session in the project, run that command from a terminal in
+  the project, then restart. The command depends on how you installed. From the
+  git marketplace (every 0.27.x install), it is the installed copy's own
+  `bin/projectstore.mjs`, with its path spelled out in the startup line:
+
+  ```
+  node "<plugin cache>/bin/projectstore.mjs" upgrade --harness claude-code --no-register
+  ```
+
+  From npm:
+
+  ```
+  npx projectstore@<version> upgrade --harness claude-code --no-register
+  ```
+
+  `--no-register` leaves your plugin registration as it is: both forms move
+  only the project's files. The same run re-stamps the status-line launcher at
+  its new path and re-registers the agents block, whose template is now v4. An
+  upgrade without `--no-register` on a git-marketplace install does more: it
   also registers the plugin from npm for this checkout and turns the
   git-marketplace copy off here, so `/plugin update` stops reaching the
-  checkout. The 0.28.0-rc.1 and rc.2 startup lines named that shell form
-  (`npx projectstore-claude@<version> upgrade`, without `--no-register`), so on
-  those, update first and run what the new startup line names. If it already
-  happened,
-  `npx projectstore-claude@<version> uninstall --surface plugin --project "$PWD"`
-  (0.28.0 or later) turns the git-marketplace copy back on. That copy must be 0.28 or later — an
-  older one reads a moved project as unbound — so update it first if it is not.
-  Restart, then run
-  `/projectstore:doctor --fix` in the new session, which re-stamps the status
-  line against that copy.
+  checkout. The 0.28.0-rc.1 and rc.2 startup lines named that form, without
+  `--no-register`, so on those, update first and run what the new startup line
+  names. If it already happened, this turns the git-marketplace copy back on
+  (0.28.0 or later), from a terminal in the project:
+
+  ```
+  npx projectstore@<version> uninstall --harness claude-code --surface plugin
+  ```
+
+  That copy must be 0.28 or later — an older one reads a moved project as
+  unbound — so update it first if it is not. Restart, then in the new session,
+  to re-stamp the status line against that copy:
+
+  ```
+  /projectstore:doctor --fix
+  ```
 - **The status line keeps rendering.** A launcher written by an earlier version
   still works, but it carries no file stamp and its embedded fallback root is
   frozen at the old version; the move above re-stamps it. Nothing rewrites that
@@ -242,9 +273,9 @@ bound before 0.28. What an existing project sees afterwards, and why:
   move once more, and the move re-stamps the launcher. If a session already
   re-stamped the status line or re-registered the agents block before the move
   (rc.2's `/projectstore:doctor --fix` did both), 0.27.x reports a foreign
-  status line and a v4 block and leaves both alone — unless you run its
-  `/projectstore:agents register`, which rewrites the block; the status line
-  still renders, and the move settles both.
+  status line and a v4 block and leaves both alone — unless you run
+  `/projectstore:agents register` in it, which rewrites the block; the status
+  line still renders, and the move settles both.
 - **Rolling back** to 0.27.x after the move: 0.27.x looks for its binding under
   `.claude/`, finds none and offers `bind`. Do not accept. A re-bind writes
   `.claude/projectstore.json` again, and 0.28's `install` and `upgrade` refuse
@@ -252,11 +283,11 @@ bound before 0.28. What an existing project sees afterwards, and why:
   `.claude/projectstore.json`, then run the command the startup line names
   once more: a 0.27.x session writes its welcome marker back under `.claude/`.
 - **Installed from npm?** Then `/plugin update` has nothing to fetch: the
-  registration is refreshed by the package itself — from a terminal outside
-  the session, `npx projectstore-claude@<version> upgrade --project "$PWD"`
-  rewrites the local marketplace and runs the host's
-  `plugin update` for this checkout. `/projectstore:doctor` says when the
-  registration is behind the package, and names that command.
+  package itself refreshes the registration. The upgrade at the top of this
+  section, run from a terminal outside the session, rewrites the local
+  marketplace and runs the host's `plugin update` for this checkout.
+  `/projectstore:doctor` says when the registration is behind the package, and
+  names the command.
 
 ## When an agent starts a task, it can find its way
 
@@ -297,7 +328,25 @@ The deep dive — real session files, measured payloads, how every mechanism wor
 
 ## Uninstalling
 
-`/plugin uninstall projectstore@SmartAndPoint` for a Claude git-marketplace install; `npx projectstore-claude uninstall --project "$PWD"` for its npm registration. For Codex, `npx projectstore-codex uninstall --project "$PWD"` removes only project-owned wiring; add `--global` only to remove the user-global Codex plugin and marketplace. Your vault is yours — plain markdown, untouched. One leftover of a host-managed plugin path can be the agents block in `CLAUDE.md`/`AGENTS.md`; remove it with the harness's agents unregister skill, or delete everything between `<!-- projectstore:agents … -->` and `<!-- /projectstore:agents -->` by hand. A one-harness `uninstall` leaves a block that lives in `AGENTS.md`, because that file is read by other coding agents too. Claude Code's then removes the `CLAUDE.md` import when that file holds nothing else; Codex's keeps it, so Claude Code still sees the block. `uninstall --surface agents_block` removes the block as well. A bare core `npx projectstore uninstall --project "$PWD"`, with no `--harness`, covers every harness the project uses — each one whose own directory (`.claude/`, `.codex/`) or `.projectstore/state/<id>/` is there. Once every harness that can read the block's file is among them (for `AGENTS.md`, Claude Code and Codex), the block goes too, and the `CLAUDE.md` import with it unless your own text keeps both files.
+From a terminal in your project:
+
+```
+npx projectstore uninstall
+```
+
+With no `--harness` it covers every agent the project uses — each one whose own directory (`.claude/`, `.codex/`) or `.projectstore/state/<id>/` is there — and removes what install wrote, and only that. For Codex that is the project-owned wiring: its plugin and marketplace are user-global, and removing them for every project is explicit:
+
+```
+npx projectstore uninstall --harness codex --global
+```
+
+A Claude Code install from the git marketplace is removed in the session:
+
+```
+/plugin uninstall projectstore@SmartAndPoint
+```
+
+Your vault is yours — plain markdown, untouched. One leftover of a host-managed plugin path can be the agents block in `CLAUDE.md`/`AGENTS.md`; remove it with the harness's agents unregister skill, or delete everything between `<!-- projectstore:agents … -->` and `<!-- /projectstore:agents -->` by hand. A one-harness `uninstall`, with `--harness <id>`, leaves a block that lives in `AGENTS.md`, because that file is read by other coding agents too. Claude Code's then removes the `CLAUDE.md` import when that file holds nothing else; Codex's keeps it, so Claude Code still sees the block. `uninstall --surface agents_block` removes the block as well. Once every harness that can read the block's file is among those uninstalled (for `AGENTS.md`, Claude Code and Codex), the block goes too, and the `CLAUDE.md` import with it unless your own text keeps both files.
 
 ## Extending
 
@@ -322,7 +371,17 @@ One formatting-only commit is listed in `.git-blame-ignore-revs`. GitHub skips i
 git config blame.ignoreRevsFile .git-blame-ignore-revs
 ```
 
-A branch opened before that commit rebases in two steps, so that the lint fixes before it are kept: `git rebase <the commit before it>` (real conflicts, resolved as usual), then `git rebase --onto <it> <the commit before it>`, where every conflict is formatting only: take your side, run `npx prettier --write <file>`, `git add` it and continue.
+A branch opened before that commit rebases in two steps, so that the lint fixes before it are kept. First onto the commit before it, resolving real conflicts as usual:
+
+```sh
+git rebase <the commit before it>
+```
+
+Then onto the formatting commit itself, where every conflict is formatting only: take your side, format the file with `npx prettier --write <file>` and `git add` it, then continue.
+
+```sh
+git rebase --onto <it> <the commit before it>
+```
 
 ## License
 

package/node_modules/projectstore/docs/extending.md

@@ -49,12 +49,17 @@ vault-side layout or template override):
 4. **Checklist entry** — `scaffold/checklists.json`, consumed by
    `/projectstore:review` and the `projectstore-peer-reviewer` skill. English-only by design.
 
-5. **Command prompt** — `commands/<kind>.md`, a prompt (not code) that calls
-   `node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" <kind> "$ARGUMENTS"`, previews,
-   and gates every write behind AskUserQuestion. Copy `commands/research.md`
-   for a plain kind, `commands/adr.md` for one that renders the draft's
-   `collision`/`warnings` fields and updates an index, `commands/spec.md`
-   for one with status transitions.
+5. **Command prompt** — `commands/<kind>.md`, a prompt (not code). It renders
+   the draft with the line below, previews it, and gates every write behind
+   AskUserQuestion:
+
+   ```
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" <kind> "$ARGUMENTS"
+   ```
+
+   Copy `commands/research.md` for a plain kind, `commands/adr.md` for one
+   that renders the draft's `collision`/`warnings` fields and updates an
+   index, `commands/spec.md` for one with status transitions.
 
 6. **Folder strings** — `templates/<lang>/strings.json` → `folders.<kind>`,
    a `name` and a one-line `description`, in **every** bundled language's

package/node_modules/projectstore/docs/getting-started.md

@@ -1,5 +1,17 @@
 # Getting started with projectstore
 
+## Install
+
+From a terminal in your project:
+
+```
+npx projectstore setup
+```
+
+Setup finds the coding agents the project uses (Claude Code, Codex or both), asks a few questions — among them where the vault lives — then shows one plan and asks once before it writes. It binds the vault, or creates one when the folder is missing or empty. The README's [Install](../README.md#install) section has the details, the global form and the registry-mirror form.
+
+The next two sections are the other ways in: a checkout, and the git marketplace inside a Claude Code session. After either of them, the first-time setup below binds the vault.
+
 ## Install (local dev)
 
 Until projectstore is published to a public marketplace, install it from a local clone.
@@ -132,6 +144,14 @@ What the language does and does not change: section headings, table labels and p
 
 ## Updating to a new version
 
+Installed with setup or from npm: from a terminal in your project, name the version you want to run:
+
+```
+npx projectstore@<version> upgrade
+```
+
+Installed from the git marketplace, in a Claude Code session:
+
 ```
 /plugin marketplace update SmartAndPoint
 /reload-plugins
@@ -139,4 +159,4 @@ What the language does and does not change: section headings, table labels and p
 
 Or enable auto-update once (`/plugin` → **Marketplaces** → **SmartAndPoint** → toggle **auto-update**) and Claude Code will detect new releases at startup.
 
-**After any update, run `/projectstore:doctor`.** It compares your project's wiring against what the new version expects and names each fix with the command to run — stale agents block in `CLAUDE.md` (`/projectstore:agents register`), leftover agent copies that override nothing (`/projectstore:agents configure`), auto-update still off (the exact setting and file), a newer release than the one running. `doctor --fix` applies the install-side repairs interactively; `/projectstore:reconcile` rebuilds the board/indexes/code-map if content drifted. Silence at session start means healthy — the cheap checks run automatically and only speak up when something is wrong.
+**After any update, run `/projectstore:doctor` in a session.** It compares your project's wiring against what the new version expects and names each fix with the command to run: a stale agents block in `CLAUDE.md` gets `/projectstore:agents register` as its fix and leftover agent copies that override nothing get `/projectstore:agents configure` as theirs. It also names auto-update still off (the exact setting and file) and a newer release than the one running. `doctor --fix` applies the install-side repairs interactively; `/projectstore:reconcile` rebuilds the board/indexes/code-map if content drifted. Silence at session start means healthy — the cheap checks run automatically and only speak up when something is wrong.

package/node_modules/projectstore/docs/harnesses.md

@@ -75,24 +75,27 @@ not started from a terminal can miss a `node` that only `.zprofile` puts on
 `PATH`.
 
 The shell is published as `projectstore-codex` from 0.28.1, ahead of that live
-run, by the maintainer's decision:
+run, by the maintainer's decision. Nobody types its name: setup, install and
+upgrade fetch it at their own version and plan Codex from it. From a terminal
+in your project:
 
 ```sh
-npx projectstore-codex install --project "$PWD"
+npx projectstore setup
 ```
 
-For later releases, `npx projectstore-codex@<version> upgrade --project "$PWD"`.
-Installation is user-global because Codex stores marketplace registrations and
-plugin caches in `CODEX_HOME`; the agents block in `AGENTS.md` remains
-project-local. Ordinary uninstall leaves the global plugin in place; add
-`--global` only when you mean to remove it for every project. From this
-checkout, the same flow runs against a built tarball:
+To upgrade Codex alone, naming the version you want to run:
 
 ```sh
-npm run shells:build -- --only projectstore-codex --dev --out dist
-npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").version').tgz" projectstore-codex install --project "$PWD"
+npx projectstore@<version> upgrade --harness codex
 ```
 
+Installation is user-global because Codex stores marketplace registrations and
+plugin caches in `CODEX_HOME`; the agents block in `AGENTS.md` remains
+project-local. Ordinary uninstall leaves the global plugin in place; add
+`--global` only when you mean to remove it for every project. A checkout's own
+build runs through the same flow: [`packaging/README.md`](../packaging/README.md#running-a-checkouts-build)
+has the tarball loop.
+
 What is known, and how:
 
 - **Hooks load from Codex's default file, so the shell carries no root

package/node_modules/projectstore/docs/how-it-works.md

@@ -191,7 +191,7 @@ resistance. v0.13 makes that safe instead of forbidden:
   sees Bash-mediated writes, which bypass hook path extraction entirely.
 
 The division of labor: deterministic checks catch the mechanical 90% for free;
-the LLM critic (`/projectstore:review`) is saved for the judgment calls.
+the LLM critic that `/projectstore:review` runs is saved for the judgment calls.
 
 ## Naming a session after the work it settled on
 

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

@@ -11,26 +11,27 @@
     "date": "2026-09-04"
   },
   "install": {
-    "mechanism": "the package's own registration through its distribution shell, or the built-in plugin marketplace",
+    "mechanism": "the package's own registration (setup or install, from npm), or the built-in plugin marketplace",
     "shell": "projectstore-claude",
-    "shell_reason": "the distribution shell that installs this harness from npm (the layout ADR decision 6; the shells ADR): `npx projectstore-claude install --project <dir>` is the core's `install --harness claude-code`, with the core pinned at the same version and bundled inside the shell's tarball. Data, not `projectstore-<id>`: the id is claude-code and the reserved, published name is projectstore-claude. Every command a finding or a deferred reason names is built from this key (harness.mjs packageCommand).",
-    "why_not_scripted": "Two channels. `npx projectstore-claude install --project <dir>` registers the plugin for that project from the npm package itself — the shell bundles the core and fixes the harness; the core's low-level form is `npx projectstore install --harness claude-code --project <dir>` — through a local marketplace under the Claude home, driven by Claude Code's own `claude plugin` CLI. `/plugin install projectstore@SmartAndPoint` installs it from the git marketplace. `/plugin` lists and toggles either. Upgrading the npm registration is `npx projectstore-claude@<version> upgrade --project <dir>` — that is also the pin.",
+    "shell_reason": "the distribution shell of this harness on npm (the layout ADR decision 6; the shells ADR): `projectstore-claude install` is the core's `install --harness claude-code`, with the core pinned at the same version and bundled inside the shell's tarball. Data, not `projectstore-<id>`: the id is claude-code and the reserved, published name is projectstore-claude. Since the front-door ADR the shell is a release artifact: no command a person is told to type names it (packageCommand builds the core's form, `npx projectstore <verb> --harness claude-code`), and this key tells the core which harness a running shell fixes (harness.mjs bundlingShellHarnessId, speakingHarnessId).",
+    "why_not_scripted": "Two channels. The npm package registers the plugin for a project itself — run `npx projectstore setup` or the core's low-level `install --harness claude-code` from a terminal in the project — through a local marketplace under the Claude home, driven by Claude Code's own `claude plugin` CLI. `/plugin install projectstore@SmartAndPoint` installs it from the git marketplace. `/plugin` lists and toggles either. The npm registration is upgraded, and pinned, by `npx projectstore@<version> upgrade` from a terminal in the project.",
     "steps": [
-      "npx projectstore-claude install --project \"$PWD\"   (npm; registers the plugin for this project — the shell runs the core's install with the harness fixed)",
-      "/plugin marketplace add SmartAndPoint/ProjectStore && /plugin install projectstore@SmartAndPoint   (git marketplace, user-wide)",
+      "npm, for this checkout (the core registers the plugin), from a terminal in the project: npx projectstore install --harness claude-code",
+      "git marketplace, user-wide, in a Claude Code session: /plugin marketplace add SmartAndPoint/ProjectStore && /plugin install projectstore@SmartAndPoint",
       "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>.",
+      "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@<version> upgrade` from a terminal in the project.",
+      "Pin a git-marketplace release by adding the marketplace at a tag: /plugin marketplace add SmartAndPoint/ProjectStore#<tag>",
+      "The npm registration is pinned by the version its upgrade names: npx projectstore@<version> upgrade",
       "Two enabled copies of the plugin (git marketplace and npm) in one checkout would load twice; the npm registration silences the other one for that checkout only (settings.local.json), and says so in its preview.",
       "From a checkout instead: claude --plugin-dir ./ProjectStore",
       "The npm registration is per checkout (local scope) and per machine; a fresh clone or a new worktree runs the install command again. It must run from a terminal outside a Claude Code session: the host CLI and a live session both rewrite settings files."
     ],
-    "docs": "https://github.com/SmartAndPoint/ProjectStore#install--one-message"
+    "docs": "https://github.com/SmartAndPoint/ProjectStore#install"
   },
   "runtime": {
     "detect_env": [
@@ -498,14 +499,14 @@
     "reason": "What the first-run welcome and its one-line notice say about updates (generation spec, contract 18): `line` ends the notice, `welcome` is the welcome's update block. update_instructions is the long-form guidance; this is the part a session prints, kept here so no hook names a harness's update path."
   },
   "update_instructions": [
-    "**About future updates**: installed from the git marketplace, Claude Code does NOT auto-update third-party marketplaces by default (an npm registration updates with `npx projectstore-claude upgrade --project <dir>`). To get notified of new releases (v0.7+):",
+    "**About future updates**: installed from the git marketplace, Claude Code does NOT auto-update third-party marketplaces by default; an npm registration updates with `npx projectstore@<version> upgrade` from a terminal in the project. To get notified of new git-marketplace releases (v0.7+):",
     "1. Open `/plugin` → **Marketplaces** tab.",
     "2. Find **SmartAndPoint**.",
     "3. Toggle **auto-update** on.",
     "",
     "Without it, you would run `/plugin marketplace update SmartAndPoint` manually. See https://github.com/SmartAndPoint/ProjectStore#upgrading for details.",
     "",
-    "**Upgrading from 0.27.x to 0.28**: restart after the update, then move the project's files to `.projectstore/` with the one command the first session names, run from a terminal outside the session: for a git-marketplace install, the installed copy's own `bin/projectstore.mjs upgrade --harness claude-code --no-register --project <dir>`, which leaves the registration as it is; for the npm registration, `npx projectstore-claude@<version> upgrade --no-register --project <dir>`. The same run re-stamps the status-line launcher, and until then every reader falls back to the old paths. `status` and `search` answer from artifact facts; `doctor` gains surface, version-drift and mcp lines and exits 1 on findings; the plugin registers an MCP server the host may ask you to approve once. On 0.28.0-rc.1 or rc.2, update first: their startup line named the shell form without `--no-register` (`npx projectstore-claude@<version> upgrade`), which also switches a git-marketplace install to npm for the checkout (the README's Upgrading section has the way back). Before the move, a rollback to 0.27.x keeps working and the move is the way forward again; after the move, 0.27.x reads the project as unbound."
+    "**Upgrading from 0.27.x to 0.28**: restart after the update, then move the project's files to `.projectstore/` with the one command the first session names, run from a terminal in the project, outside the session. For a git-marketplace install it is the installed copy's own `bin/projectstore.mjs` with `upgrade --harness claude-code --no-register`, which leaves the registration as it is. For the npm registration it is `npx projectstore@<version> upgrade --harness claude-code --no-register` and nothing else. The same run re-stamps the status-line launcher, and until then every reader falls back to the old paths. `status` and `search` answer from artifact facts; `doctor` gains surface, version-drift and mcp lines and exits 1 on findings; the plugin registers an MCP server the host may ask you to approve once. On 0.28.0-rc.1 or rc.2, update first: their startup line named the form without `--no-register`, which also switches a git-marketplace install to npm for the checkout (the README's Upgrading section has the way back). Before the move, a rollback to 0.27.x keeps working and the move is the way forward again; after the move, 0.27.x reads the project as unbound."
   ],
   "agent_translation": {
     "carries_model": true,

package/node_modules/projectstore/harnesses/codex.json

@@ -311,32 +311,32 @@
   },
   "rewrites": [],
   "install": {
-    "mechanism": "the package's portable plugin root, registered through its distribution shell and Codex's own marketplace CLI",
+    "mechanism": "the package's portable plugin root, fetched in its distribution shell and registered through Codex's own marketplace CLI",
     "shell": "projectstore-codex",
     "shell_reason": "The built `projectstore-codex` shell carries the rendered Codex skills and hooks plus an exact bundled core, fixes --harness codex, stages a stable marketplace under CODEX_HOME, and asks Codex itself to install it. It is published from 0.28.1, by the maintainer's decision of 2026-10-04. Until then this key was absent, so generated guidance could not send users to the reserved 0.0.1 placeholder; the core alone is not Codex's plugin root and cannot register it.",
-    "why_not_scripted": "The shell does not edit Codex's registry or cache. It atomically stages the plugin source, previews the host commands, then runs `codex plugin marketplace add` and `codex plugin add`; a read-back verifies the installed version and payload digest. The global plugin survives ordinary project uninstall; `uninstall --global` is the explicit destructive form.",
+    "why_not_scripted": "The installer does not edit Codex's registry or cache. It atomically stages the plugin source from the shell it fetched, previews the host commands, then runs `codex plugin marketplace add` and `codex plugin add`; a read-back verifies the installed version and payload digest. The global plugin survives ordinary project uninstall; `uninstall --global` is the explicit destructive form.",
     "steps": [
-      "npx projectstore-codex install --project \"$PWD\"",
+      "from a terminal in the project (the core fetches the Codex shell at its own version): npx projectstore install --harness codex",
       "restart Codex and approve the ProjectStore hooks when prompted",
-      "run `$projectstore-bind <vault-path>` in Codex"
+      "in Codex, bind a vault: $projectstore-bind <vault-path>"
     ],
     "next": [
       "restart Codex from a terminal and approve the ProjectStore hooks when it asks"
     ],
     "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.",
+      "Upgrade with `npx projectstore@<version> upgrade --harness codex` from a terminal in the project; the version it names is also the plugin version.",
       "A second enabled ProjectStore plugin from another marketplace is a refusal, not silently disabled globally. Remove or disable that older registration explicitly, then retry.",
-      "Ordinary uninstall removes only project-owned surfaces. `npx projectstore-codex uninstall --global --project \"$PWD\"` also removes the user-global plugin registration after a preview."
+      "Ordinary uninstall removes only project-owned surfaces. `npx projectstore uninstall --harness codex --global` also removes the user-global plugin registration after a preview."
     ],
-    "docs": "https://github.com/SmartAndPoint/ProjectStore#install--one-message"
+    "docs": "https://github.com/SmartAndPoint/ProjectStore#install"
   },
   "update_hint": {
     "line": "Update from a terminal in this project:\n{upgrade}",
     "welcome": ["**About future updates**: from a terminal in this project, run:", "", "```", "{upgrade}", "```", "", "Then restart Codex and approve any hook it asks about. See https://github.com/SmartAndPoint/ProjectStore#upgrading for details."],
     "reason": "What the first-run welcome and its one-line notice say about updates (generation spec, contract 18): `line` ends the notice, `welcome` is the welcome's update block, and `{upgrade}` is filled with the core's upgrade for this harness at latest (`--harness codex`, no `--project`), so what is printed runs as printed. Each says where to run it and puts the command alone on its line (the story \"User-facing text says where to run and names no project path and no shell\", rules 4 and 5). update_instructions is the long-form guidance; this is the part a session prints, kept here so no hook names a harness's update path."
   },
-  "update_instructions": "Run `npx projectstore-codex@<version> upgrade --project <dir>`. The installer atomically replaces its stable source and `codex plugin add projectstore@projectstore-npx` materialises the new version; this was measured across two dev builds on codex-cli 0.153.4. Restart Codex afterwards so the new skills and hooks are loaded.",
+  "update_instructions": "From a terminal in the project, run `npx projectstore@<version> upgrade --harness codex` and restart Codex afterwards, so the new skills and hooks are loaded. The run fetches the shell at that version, atomically replaces its stable source, and `codex plugin add projectstore@projectstore-npx` materialises the new version; this was measured across two dev builds on codex-cli 0.153.4.",
   "agent_translation": {
     "carries_model": false,
     "carries_model_reason": "The surface projectstore ships — a plugin's agents/ entry — carries no model on Codex: surfaces.agents is supported:false because no route from a plugin's agents/ directory to collaborationspawn_agent has been found (measured). Codex DOES have a definition file that carries model and effort, recorded below, but it is project- or user-scoped and not plugin-shippable, so contract 12 holds as written: what we ship cannot carry a model. Was true here until 2026-09-08, which contradicted both contract 12 and this file's own agents row.",

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.29.4",
+  "version": "0.30.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/fetch-shell.mjs

@@ -18,7 +18,8 @@
 //   npmUserRegistry({ home, env })    → the user's own registry, read from home, or null
 //   fetchShell(job, { dir, registry }) → { ok, root, ms } or { ok: false, code, refusal }
 //   verifyFetched(root, { … })        → null, or the refusal naming file and values
-//   fetchRefusal(code, ctx)           → rule 4's texts
+//   fetchRefusal(code, ctx)           → rule 4's texts, the envelope's string
+//   fetchRefusalAdvice(code, ctx)     → the same, as PLAN draws it: { text, blocks }
 //   sweepFetchRuns(fetchDir)          → the leftovers of dead runs, removed
 //   fetchRunId()                      → <pid>-<epoch ms>
 //
@@ -29,8 +30,8 @@
 
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { registrationDeferred } from "./harness.mjs";
-import { removeTreeUnder, pidAlive, whichOnPath } from "./lib.mjs";
+import { registrationDeferred, packageCommand } from "./harness.mjs";
+import { removeTreeUnder, pidAlive, whichOnPath, fromTerminalIn } from "./lib.mjs";
 import {
   isPortablePluginRoot,
   payloadManifest,
@@ -213,12 +214,45 @@ export function npmError(stdout, stderr) {
 
 const seconds = (ms) => `${Number((ms / 1000).toFixed(ms % 1000 ? 1 : 0))} s`;
 
-// Rule 4's refusals, by npm's code or ours. `ctx`: pkg ("<shell>@<v>"),
-// shell, registry (null: npm's own), display (the harness's display name),
-// budget, summary (npm's), cause (a start failure's), path/from/variable (the
-// cache). Every way out is a terminal command or a variable; none names a
-// version but the one this run is at.
-export function fetchRefusal(code, ctx = {}) {
+// npm's own registry: the one README's registry-mirror advice names.
+export const PUBLIC_REGISTRY = "https://registry.npmjs.org";
+
+// A registry that has no such shell may be a mirror that has not synced it:
+// the run once more, from npm's public registry, in README's form — the
+// variable, not `npx --registry`, because `npm config get registry`, which
+// the fetch's resolver reads, honours it (the story "User-facing text says
+// where to run and names no project path and no shell", rule 7). It is the
+// run the person just saw: its verb and version, and its selection as given —
+// each named --harness, each --surface, and --no-register — never --project
+// (the front-door ADR, decision 5); the directory goes in the lead, and the
+// command stands alone after it (rule 4). `args` is the shape the converge
+// story's stop repeats a run with. Null when the run is unknown, or when the
+// registry is already the public one; a null registry is npm's own
+// resolution, which can be a mirror, so it gets the line.
+function mirrorBlock({ registry = null, verb = null, version = null, args = {}, project = null } = {}) {
+  if (!verb || !version || String(registry || "").replace(/\/+$/, "") === PUBLIC_REGISTRY) return null;
+  const { harnesses = [], surfaces = null, register = true } = args || {};
+  const narrowing = [
+    ...(surfaces || []).map((s) => `--surface ${s}`),
+    ...(register === false ? ["--no-register"] : []),
+  ];
+  const command = packageCommand(
+    harnesses.map((id) => ({ id })),
+    verb,
+    { version, args: narrowing.join(" ") },
+  );
+  const where = project ? fromTerminalIn(project) : "from a terminal in this project";
+  return {
+    lead: `A mirror that has not synced it? Run this again from npm's public registry, ${where}:`,
+    command: `npm_config_registry=${PUBLIC_REGISTRY} ${command}`,
+  };
+}
+
+// Rule 4's refusals, as PLAN draws them: `{ text, blocks }`, the prose, then
+// each lead and its command (presentation spec contract 6), so PLAN prints a
+// command whole, unwrapped, alone on its line. Only the missing shell has a
+// block today; every other refusal is its text alone.
+export function fetchRefusalAdvice(code, ctx = {}) {
   const {
     pkg = "the shell",
     shell = "the shell",
@@ -233,29 +267,61 @@ export function fetchRefusal(code, ctx = {}) {
   } = ctx;
   const where = registry || "the registry npm resolves";
   const without = `name --harness without ${display}`;
+  const said = (text, blocks = []) => ({ text, blocks });
   switch (code) {
     case "ETARGET":
-    case "E404":
-      return `${pkg} is not on ${where} (npm ${code}); ${display} is registered from that shell at this exact version, and no other version is tried. Just released? The shell is published after the core, so retry in a few minutes. From a checkout at an unpublished version, point PROJECTSTORE_DISTRIBUTION_ROOT at the output of \`npm run shells:build -- --dev\` (dist/build/${shell}). Or ${without}.`;
+    case "E404": {
+      const mirror = mirrorBlock(ctx);
+      return said(
+        `${pkg} is not on ${where} (npm ${code}); ${display} is registered from that shell at this exact version, and no other version is tried. Just released? The shell is published after the core, so retry in a few minutes. From a checkout at an unpublished version, point PROJECTSTORE_DISTRIBUTION_ROOT at the output of \`npm run shells:build -- --dev\` (dist/build/${shell}). Or ${without}.`,
+        mirror ? [mirror] : [],
+      );
+    }
     // Our budget, not npm's: npm's own ETIMEDOUT (a socket) is any other code.
     case "EBUDGET":
-      return `fetching ${pkg} from ${where} took longer than ${seconds(budget)} and was stopped. Retry, or ${without}.`;
+      return said(
+        `fetching ${pkg} from ${where} took longer than ${seconds(budget)} and was stopped. Retry, or ${without}.`,
+      );
     case "FETCH_TIMEOUT":
-      return `npm gave up on ${ctx.url || where} (network timeout) while fetching ${pkg}. Retry, or ${without}.`;
+      return said(`npm gave up on ${ctx.url || where} (network timeout) while fetching ${pkg}. Retry, or ${without}.`);
     case "E401":
     case "E403":
-      return `${where} refused the credentials for ${pkg} (npm ${code}). A project .npmrc's token does not reach this fetch — only its registry does — so the registry's token must be in user config: ~/.npmrc, or an NPM_CONFIG_… variable. Or point PROJECTSTORE_DISTRIBUTION_ROOT at a ${shell} root obtained another way.`;
+      return said(
+        `${where} refused the credentials for ${pkg} (npm ${code}). A project .npmrc's token does not reach this fetch — only its registry does — so the registry's token must be in user config: ~/.npmrc, or an NPM_CONFIG_… variable. Or point PROJECTSTORE_DISTRIBUTION_ROOT at a ${shell} root obtained another way.`,
+      );
     case "ESTART":
-      return `${cause}; ${display} is registered from its shell, which npm fetches. Put npm on PATH, or ${without}.`;
+      return said(
+        `${cause}; ${display} is registered from its shell, which npm fetches. Put npm on PATH, or ${without}.`,
+      );
     case "ENOCACHE":
-      return `the shell fetch has no cache directory: ${variable} is not an absolute path and the home directory is unknown. Set ${variable} to a writable directory, then run this again.`;
+      return said(
+        `the shell fetch has no cache directory: ${variable} is not an absolute path and the home directory is unknown. Set ${variable} to a writable directory, then run this again.`,
+      );
     case "ECACHE":
-      return `the cache directory ${path} cannot be written (${ctx.errno || "error"}); it comes from ${from}. Set ${variable} to a writable directory, then run this again.`;
+      return said(
+        `the cache directory ${path} cannot be written (${ctx.errno || "error"}); it comes from ${from}. Set ${variable} to a writable directory, then run this again.`,
+      );
     default:
-      return `npm could not fetch ${pkg} from ${where}: ${code || "an unknown error"}${summary ? ` — ${summary.split(/\r?\n/)[0]}` : ""}. ${display} is registered from its shell, which needs the network: retry once the registry is reachable, or ${without}.`;
+      return said(
+        `npm could not fetch ${pkg} from ${where}: ${code || "an unknown error"}${summary ? ` — ${summary.split(/\r?\n/)[0]}` : ""}. ${display} is registered from its shell, which needs the network: retry once the registry is reachable, or ${without}.`,
+      );
   }
 }
 
+// Rule 4's refusals, by npm's code or ours: the envelope's string, every part
+// on its own line — the prose, then each lead and its command — which an agent
+// relays as it is. `ctx`: pkg ("<shell>@<v>"), shell, registry (null: npm's
+// own), display (the harness's display name), budget, summary (npm's), cause
+// (a start failure's), path/from/variable (the cache), and the run — its verb,
+// version, project and `args` (the selection as given) — which the missing
+// shell's refusal repeats from the public registry. Every way out is a
+// terminal command or a variable; none names a version but the one this run
+// is at.
+export function fetchRefusal(code, ctx = {}) {
+  const { text, blocks } = fetchRefusalAdvice(code, ctx);
+  return [text, ...blocks.flatMap((b) => [b.lead, b.command])].join("\n");
+}
+
 // Rule 3: the fetched tree is what this run plans, before it is planned —
 // the shell's name and version, a plugin root by the analyser's own predicate,
 // its plugin manifest's name and version, and the bundled core at the same
@@ -294,26 +360,29 @@ export function verifyFetched(root, { shell, version, pluginName, coreName }) {
 // as *** (measured). A failure is a refusal before the plan, never a fallback.
 export async function fetchShell(
   { harness, s, version, coreName },
-  { dir, registry = null, env = process.env, spawn, budget = HOST_BUDGET_MS } = {},
+  { dir, registry = null, env = process.env, spawn, budget = HOST_BUDGET_MS, run = {} } = {},
 ) {
   const shell = harness.install.shell;
   const pkg = `${shell}@${version}`;
-  const ctx = { pkg, shell, registry, display: harness.display_name, budget };
+  // `run`: the verb, selection (`args`) and project of the run that fetches,
+  // for the missing shell's public-registry form; the version is this one.
+  const ctx = { pkg, shell, registry, display: harness.display_name, budget, ...run, version };
+  // A refusal in both forms: the envelope's string, and what PLAN draws.
+  const refused = (code, extra = {}) => ({
+    refusal: fetchRefusal(code, { ...ctx, ...extra }),
+    advice: fetchRefusalAdvice(code, { ...ctx, ...extra }),
+  });
   const call = npmCall(fetchArgv({ prefix: dir, registry, shell, version }), env);
   const t0 = Date.now();
   const r = await runHost(call.bin, call.argv, { env, cwd: dir, budget, spawn, shell: call.shell });
   const ms = Date.now() - t0;
   if (r.error) {
-    if (r.error.code === "ETIMEDOUT")
-      return { ok: false, ms, code: "ETIMEDOUT", refusal: fetchRefusal("EBUDGET", ctx) };
+    if (r.error.code === "ETIMEDOUT") return { ok: false, ms, code: "ETIMEDOUT", ...refused("EBUDGET") };
     return {
       ok: false,
       ms,
       code: r.error.code || "ESTART",
-      refusal: fetchRefusal("ESTART", {
-        ...ctx,
-        cause: startFailure(r.error, { bin: "npm", resolved: call.resolved, cwd: dir }),
-      }),
+      ...refused("ESTART", { cause: startFailure(r.error, { bin: "npm", resolved: call.resolved, cwd: dir }) }),
     };
   }
   if (r.status !== 0) {
@@ -321,14 +390,8 @@ export async function fetchShell(
     // npm reports a request it gave up on as FETCH_ERROR, "network timeout
     // at: <url>" (measured in review, 2026-10-08), not as ETIMEDOUT.
     const timeout = e.code === "FETCH_ERROR" && /network timeout at:\s*(\S+)/.exec(e.summary);
-    if (timeout)
-      return { ok: false, ms, code: e.code, refusal: fetchRefusal("FETCH_TIMEOUT", { ...ctx, url: timeout[1] }) };
-    return {
-      ok: false,
-      ms,
-      code: e.code || `exit ${r.status}`,
-      refusal: fetchRefusal(e.code, { ...ctx, summary: e.summary }),
-    };
+    if (timeout) return { ok: false, ms, code: e.code, ...refused("FETCH_TIMEOUT", { url: timeout[1] }) };
+    return { ok: false, ms, code: e.code || `exit ${r.status}`, ...refused(e.code, { summary: e.summary }) };
   }
   const root = join(dir, "node_modules", shell);
   const wrong = verifyFetched(root, { shell, version, pluginName: s.plugin_name, coreName });

package/node_modules/projectstore/scripts/install-harness.mjs

@@ -5050,10 +5050,11 @@ async function fetchShells(
     }
   }
   if (!jobs.length) return none;
-  const refuse = (message, cleanup = () => {}) => ({
-    ...none,
-    cleanup,
-    refused: {
+  // `advice`: the refusal as PLAN draws it, its commands in their own blocks
+  // (fetchRefusalAdvice) — kept off the envelope, as the channel "git"
+  // refusal's is, so `--json` keeps the one string.
+  const refuse = (message, cleanup = () => {}, advice = null) => {
+    const refused = {
       projectDir,
       mode: "install",
       named,
@@ -5066,8 +5067,10 @@ async function fetchShells(
       incomplete: false,
       root,
       plannedAgainst: {},
-    },
-  });
+    };
+    if (advice?.blocks?.length) Object.defineProperty(refused, "refusalAdvice", { value: advice, enumerable: false });
+    return { ...none, cleanup, refused };
+  };
   const cache = cachePaths({ env, home });
   if (!cache.root) return refuse(fetchRefusal("ENOCACHE", { variable: cache.variable }));
   sweepFetchRuns(cache.fetch);
@@ -5104,6 +5107,19 @@ async function fetchShells(
     const differs = Boolean(registry) && bare(registry) !== bare(mine);
     const payloadRoots = {},
       fetched = [];
+    // The run, for the missing shell's public-registry form: its verb, its
+    // project, and its selection as given, in the shape the stop repeats a
+    // run with — each named --harness (setup's answered set is named too),
+    // each --surface, --no-register.
+    const run = {
+      verb,
+      project: projectDir,
+      args: {
+        harnesses: named ? (opts.harnesses || []).filter(Boolean) : [],
+        surfaces: opts.surfaces || null,
+        register: opts.register !== false,
+      },
+    };
     for (const job of jobs) {
       const { harness } = job;
       const pkg = `${harness.install.shell}@${version}`;
@@ -5112,10 +5128,13 @@ async function fetchShells(
       const dir = jobs.length === 1 ? runDir : join(runDir, harness.id);
       if (dir !== runDir) mkdirSync(dir, { recursive: true });
       line = opts.onFetch ? opts.onFetch(`fetching ${pkg} for ${harness.display_name}`, ids) : null;
-      const r = await fetchShell({ ...job, version, coreName }, { dir, registry, env, spawn: opts.fetchSpawn, budget });
+      const r = await fetchShell(
+        { ...job, version, coreName },
+        { dir, registry, env, spawn: opts.fetchSpawn, budget, run },
+      );
       if (!r.ok) {
         if (line) line.end(false, `fetch failed ${pkg}`, r.code);
-        return refuse(r.refusal, cleanup);
+        return refuse(r.refusal, cleanup, r.advice);
       }
       if (line) line.end(true, `fetched ${pkg} for ${harness.display_name}`);
       line = null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore-claude",
-  "version": "0.29.4",
-  "description": "Installs projectstore for Claude Code from npm: the core pinned and bundled, the harness fixed — npx projectstore-claude install --project \"$PWD\".",
+  "version": "0.30.0",
+  "description": "projectstore for Claude Code: the core pinned and bundled, the harness fixed. A release artifact; the way in is npx projectstore setup",
   "keywords": [
     "projectstore",
     "installer",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.29.4"
+    "projectstore": "=0.30.0"
   },
   "bundleDependencies": [
     "projectstore"