projectstore-claude 0.29.2 → 0.29.4

package/README.md

@@ -6,7 +6,7 @@ The Claude Code installer for [projectstore](https://www.npmjs.com/package/proje
 npx projectstore-claude install --project "$PWD"
 ```
 
-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.
+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.
 

package/bin/projectstore-claude.mjs

@@ -24,7 +24,7 @@ const HARNESS = "claude-code";
 // scripts/cli.mjs; the packaging test pins it). Any other verb — doctor,
 // status, search, --version — passes through untouched: the core refuses an
 // option a verb does not declare, so a blanket insert would break `doctor`.
-const HARNESS_VERBS = new Set(["plan","install","uninstall","upgrade","agents"]);
+const HARNESS_VERBS = new Set(["setup","plan","install","uninstall","upgrade","agents"]);
 
 // The bundled core, by path — never by package resolution: a hoisted or global
 // copy at another version is exactly the pairing the pin exists to prevent,

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.2",
+      "version": "0.29.4",
       "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.2",
+  "version": "0.29.4",
   "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",
@@ -11,6 +11,7 @@
   "homepage": "https://github.com/SmartAndPoint/ProjectStore",
   "repository": "https://github.com/SmartAndPoint/ProjectStore",
   "license": "MIT",
+  "types": "./hooks/band-state.d.ts",
   "keywords": [
     "project-management",
     "adr",

package/node_modules/projectstore/README.md

@@ -1,6 +1,6 @@
 # ProjectStore
 
-> Not a memory plugin. ProjectStore is how your AI agent runs the *project* — decisions, specs, epics, stories and a kanban board as plain markdown in git — so the next agent, the next model, or you in six months know exactly **why** everything is the way it is.
+> Not agent memory, not a per-feature spec pipeline. Memory helps one agent recall; a feature spec plans one change. ProjectStore keeps the project's record — what was decided, what is in flight, what was checked — as reviewed markdown in git, readable by any agent and anyone with the repo.
 
 [![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)
 
@@ -14,6 +14,21 @@ Agents write code fast. They re-decide settled questions even faster: every fres
 
 The fix is not a smarter agent. It is a loop with verification in it.
 
+## Where it fits
+
+**Not agent memory. Not a spec pipeline. The project's record.** Three kinds of tools sit next to a coding agent. Each answers a different question.
+
+| Kind of tool | The question it answers | What it keeps | Examples |
+|---|---|---|---|
+| **Agent memory** | What does this agent recall? | Notes the model keeps from its sessions, for an agent, a user or a machine. | Mem0, Zep, Codex and Claude Code memory |
+| **Instruction files** | How should an agent behave here? | Standing rules for an agent, kept in the repository. | `CLAUDE.md`, `AGENTS.md`, rules, steering files |
+| **Spec-driven tools** | How do we build this change? | A spec, a plan and tasks for one feature. | Spec Kit, Kiro, OpenSpec, BMAD |
+| **ProjectStore** | What has the project decided, what is in flight, and was it checked? | Decisions, specs and work items with a status, a date and links, in git. A person approves each before ProjectStore writes it; a fresh-context critic reviews it by rule. | — |
+
+Keep your agent's memory for you and your machine, and the project in the vault.
+
+Decision logs, validators, session-start orientation and independent review each exist elsewhere. What ProjectStore adds is all of them over one linked record. Tool by tool, with sources: [`docs/alongside.md`](./docs/alongside.md).
+
 ## The loop
 
 The thing that makes agentic coding work — the loop Claude Code's own creator keeps pointing at — is *gather context, act, verify, repeat*. ProjectStore runs that loop one level up: over the project, not just the code.
@@ -27,10 +42,10 @@ The thing that makes agentic coding work — the loop Claude Code's own creator
 2. **A fresh-context critic attacks the artifact.** Expect *revise* — on this repo it has yet to pass anything on the first try, and that is the point.
 3. The fixed artifact lands in the **backlog**; the kanban regenerates itself.
 4. An agent picks up a story. A **planner** reads how earlier epics actually landed in the code and says where this change belongs.
-5. A **reviewer** matches the diff against the story's acceptance criteria — per criterion, with evidence — before anything gets called done.
+5. By rule, a **reviewer** matches the diff against the story's acceptance criteria — per criterion, with evidence — before anything gets called done.
 6. **Done.** Board, link graph and code map regenerate. The next session starts oriented instead of guessing.
 
-Mechanisms hold this together, not discipline: an agent that starts coding with no story open gets nudged, artifacts are not final before review, and a deterministic `doctor` checks the mechanical consistency with zero AI involved. Every *verify* step is a separate fresh-context agent with no stake in the draft it is judging.
+Mechanisms hold this together, not discipline: an agent that starts coding with no story open gets nudged; an artifact that needs review carries `review_status: pending` until a critic pass is applied, so "not yet reviewed" is a state the tools can read rather than something someone must remember; and a deterministic `doctor` checks the mechanical consistency with zero AI involved. Every *verify* step is a separate fresh-context agent with no stake in the draft it is judging.
 
 We build ProjectStore with ProjectStore. The feature that names your session went through exactly this loop — including a critic pass that killed the design's central claim, and a reviewer pass that caught a bug which would have shipped the feature silently dead for every real user.
 
@@ -56,6 +71,8 @@ Six months later, *"why Postgres?"* has an answer with a date and the alternativ
 
 ![projectstore status line: the 📚 epic › story line sitting above an existing oh-my-claudecode HUD](docs/images/statusline-hud.png)
 
+In Claude Code a band above the prompt goes further (experimental): the session's epic with its goal and how far it is, the story in hand, and the ProjectStore agent at work — `critic · opus 5.5 · reviews «…»` — on the model its own requests name. While it draws, the status line steps aside; `/projectstore:bar off` hides it, `/projectstore:bar status` says why it is not there.
+
 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
@@ -94,7 +111,7 @@ 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. 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.
+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 Codex
@@ -132,6 +149,8 @@ npx projectstore install --harness claude-code   # the low-level form the shell
 npx projectstore reconcile --write --only kanban
 ```
 
+At a terminal the bin's output is coloured; a pipe gets the same layout as plain text. `NO_COLOR=1` turns the colour off, and `PROJECTSTORE_ASCII=1` draws every glyph in ASCII — for a terminal that draws ambiguous-width characters wide (`TERM=dumb` does both).
+
 Reads too — the same facts the agents get over MCP:
 
 ```
@@ -148,11 +167,12 @@ The same eight reads are an MCP server. The plugin registers it through its own
 npx projectstore mcp --project "$PWD"
 ```
 
-Binding, too — naming the vault is the confirmation, and changing it needs `--rebind`:
+Binding, too — naming the vault is the confirmation, and changing it needs `--rebind`. `init` creates a whole vault in one step, with no `mkdir` first: the directory, its git repository, the layout's folders and their README indexes; `scaffold --write` adds the folders to a vault that was bound without them:
 
 ```
 npx projectstore bind ~/vaults/my-project
 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.
@@ -263,7 +283,7 @@ And they are the exit door. The vault is plain markdown in git — no server, no
 
 ## Fact sheet
 
-**20 commands** · **6 agents** — critic, planner, reviewer, librarian, archaeologist (the advisors: read-only, fresh-context) and clerk (the sole write-capable one — it executes approved writes, post-gate, and composes nothing) · **6 languages** — en, ru, es, de, fr, zh · zero runtime dependencies
+**21 commands** · **6 agents** — critic, planner, reviewer, librarian, archaeologist (the advisors: read-only, fresh-context) and clerk (the sole write-capable one — it executes approved writes, post-gate, and composes nothing) · **6 languages** — en, ru, es, de, fr, zh · zero runtime dependencies
 
 The deep dive — real session files, measured payloads, how every mechanism works and where its limits are: [docs/how-it-works.md](./docs/how-it-works.md).
 
@@ -277,7 +297,7 @@ 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. `uninstall` leaves a block that lives in `AGENTS.md`, because that file is read by other coding agents too, and removes the `CLAUDE.md` import when that file holds nothing else; `uninstall --surface agents_block` removes the block as well.
+`/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.
 
 ## Extending
 
@@ -287,6 +307,23 @@ See [`docs/extending.md`](./docs/extending.md) for adding layouts, templates, an
 
 Issues and discussions: https://github.com/SmartAndPoint/ProjectStore/issues. PRs welcome — adding a layout is a good first contribution (see `scaffold/layouts/engineering.json` for the format).
 
+The published package has no dependencies; the linter and the formatter are dev-only, pinned in `package-lock.json`. Every pull request runs the tests, ESLint and Prettier:
+
+```sh
+npm test              # Node 20+, no install needed
+npm ci                # once, for the lint tools (Node 20.19+, 22.13+ or 24+)
+npm run lint
+npm run format        # rewrites; npm run format:check only reports
+```
+
+One formatting-only commit is listed in `.git-blame-ignore-revs`. GitHub skips it in blame by itself; a local clone needs this once:
+
+```sh
+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.
+
 ## License
 
 MIT — see [`LICENSE`](./LICENSE).

package/node_modules/projectstore/commands/bar.md

@@ -0,0 +1,30 @@
+---
+description: The band above the prompt — this session's epic, its progress, its story and its ProjectStore agents. Switch it on or off, pin an epic for sessions with none, or ask why it is not drawing.
+argument-hint: "on | off | status | epic [<ID>]"
+---
+
+You are managing the band above the prompt through the core's `band` verb. The band is drawn by the plugin's hooks module; it shows this session's epic (from this session's own state), how far that epic is, its goal, this session's story and the ProjectStore agent at work. While it draws, the status line gives way to it, and it comes back within 30 s of the band stopping. Never edit `.projectstore/projectstore.json` yourself: the verb is the one writer of its `band` keys, and writes atomically.
+
+Read `$ARGUMENTS`: `on`, `off`, `status`, `epic <ID>`, or `epic` alone (releases the pin). Nothing, or anything else, is `status`.
+
+## status — read-only
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" band status --project "${CLAUDE_PROJECT_DIR}"
+```
+
+Relay its lines. Exit 3: the project is not bound — tell the user to run `/projectstore:bind <vault-path>` and stop. When it says the band is not drawing, the reason is one of: switched off; this session has no epic and none is pinned; the pinned epic no longer exists; the module is not drawing (the host has modules switched off, an older Claude Code, or a crashed module — the status line keeps its own line then); a harness without a band.
+
+## on, off, epic
+
+1. **Ask** via AskUserQuestion, naming the change — "Switch the band off?", "Switch the band on?", "Pin the band to `<ID>` for sessions with no epic of their own?", or "Release the pinned epic?" — **Yes** / **No**. On **No**, stop: nothing is written.
+
+2. **Write**, on **Yes**:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" band <on|off|epic> [<ID>] --json --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   The question above is the confirmation; `--json` never asks again. Report `result.band` and whether `result.wrote`. Exit 1 is a refusal — an unknown epic id (the message names the existing ones), or a binding that is not valid JSON: relay it. The band follows within a few seconds; no restart.
+
+A pin shows only in a session that has no epic of its own: a session working on an epic always shows that one.

package/node_modules/projectstore/commands/bind.md

@@ -3,7 +3,7 @@ description: Bind this project to an Obsidian vault (or any markdown directory)
 argument-hint: <vault-path> | --inherit [--layout engineering] [--lang en|ru|es|de|fr|zh]
 ---
 
-You are binding the current project to a markdown vault for projectstore. The config is written by the core's `bind` / `init` verbs (roadmap A8); this interview decides the values, previews them, and asks — it never writes `projectstore.json` itself, except on the inherit path (step 0a), which copies the parent's file verbatim, and the two later stamps in steps 11–12 (`autoupdate_asked`, `statusline`), which `Edit` the file the verb wrote. The interview's `--lang` is the verb's `--language`.
+You are binding the current project to a markdown vault for projectstore. The config is written by the core's `bind` / `init` verbs (roadmap A8); this interview decides the values, previews them, and asks — it never writes `projectstore.json` itself, except on the inherit path (step 0a), which copies the parent's file verbatim, and the one later stamp in step 11 (`statusline`), which `Edit`s the file the verb wrote. The interview's `--lang` is the verb's `--language`.
 
 Parse `$ARGUMENTS`:
 - First positional arg: vault path. Expand `~` if present.
@@ -20,7 +20,7 @@ Steps:
    - If absent otherwise: proceed to step 1 (fresh bind).
    - If present **and** `--inherit` was passed: print "Already bound to `<path>`." and stop. Do not fall through to the rebind comparison below — with `--inherit` there is no new path to compare, and the comparison would render an empty "proposed" side and offer to replace the binding. A no-op command must not reach a destructive option.
    - If present, let the verb compare — run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" bind "<vault-path>" [--layout <name>] [--language <code>] --json` **without** `--rebind` (pass the user's flags, so the proposed side of the diff is what a rebind would write) (the vault is normalised on both sides: `~`, relative, trailing slash, symlinks):
-     - `result.state` is `"same"` (exit 0, nothing written): print "Already bound to `<path>`. Re-run `/projectstore:scaffold` if you need to (re)create the layout, or `/projectstore:status` to inspect it." and stop. If `result.ignored` names `layout` or `language`, say the flag was ignored — a change of layout or language is not a rebind.
+     - `result.state` is `"same"` (exit 0, nothing written): print "Already bound to `<path>`." Then run step 7's `scaffold --json` check: when a row reads `create`, add "`/projectstore:scaffold` creates the layout's missing folders and READMEs"; otherwise suggest `/projectstore:status`. Stop. If `result.ignored` names `layout` or `language`, say the flag was ignored — a change of layout or language is not a rebind.
      - a refusal with code `UNREADABLE` (the config exists but is not valid JSON): relay it and stop — nothing is overwritten; the user fixes or removes the file first.
      - `result.state` is `"different"` (exit 1, a `REBIND` refusal, nothing written — **the refusal is the diff**, and `result.kept_keys` lists what a rebind keeps): show the user a one-block diff built from the existing config and the refusal:
        ```
@@ -48,12 +48,13 @@ Steps:
 
    It prints `{state, worktree, mainCheckout, vaultPath}` and writes nothing.
    - `state` is **not** `inheritable` → say why in one line (not a worktree, its parent is unbound too, or git could not answer) and fall through to step 1, which needs a vault path; if none was given, ask for one.
-   - `state` is `inheritable` → read the parent's `<mainCheckout>/.projectstore/projectstore.json` (or, in a checkout not yet migrated, the legacy `<mainCheckout>/.claude/projectstore.json`), show it **verbatim as a code block**, and ask via AskUserQuestion: "Adopt the binding of `<mainCheckout>` (vault `<vaultPath>`)?" — Yes / No.
-   - On **Yes**: Write that JSON verbatim to `<project>/.projectstore/projectstore.json`, **and write `<project>/.projectstore/.gitignore` beside it** with the two lines `projectstore.json` and `state/` under a comment saying they are machine-local (the verb writes them itself on every other path; this one bypasses the verb, and without them the worktree commits an absolute vault path into the index it shares with its parent). If that file already exists, add any missing line and leave the rest — it is line-merged. Then **jump straight to step 10** (the summary). Steps 1–9 and 11–12 are decisions the parent already made and the copied config already carries — layout, language, statusline, agent models, auto-update. Do not re-ask them, and do not scaffold: the vault exists and is shared.
+   - `state` is `inheritable` → read the parent's `<mainCheckout>/.projectstore/projectstore.json` (or, in a checkout not yet migrated, the legacy `<mainCheckout>/.claude/projectstore.json`), show it **verbatim as a code block** — but for the `channel_switch` and `channel_keep` keys, which are left out (below) — and ask via AskUserQuestion: "Adopt the binding of `<mainCheckout>` (vault `<vaultPath>`)?" — Yes / No.
+   - On **Yes**: Write that JSON verbatim, without `channel_switch` and `channel_keep`, to `<project>/.projectstore/projectstore.json`, **and write `<project>/.projectstore/.gitignore` beside it** with the two lines `projectstore.json` and `state/` under a comment saying they are machine-local (the verb writes them itself on every other path; this one bypasses the verb, and without them the worktree commits an absolute vault path into the index it shares with its parent). If that file already exists, add any missing line and leave the rest — it is line-merged. Then **jump straight to step 10** (the summary). Steps 1–9 and 11 are decisions the parent already made and the copied config already carries — layout, language, statusline, agent models. Do not re-ask them, and do not scaffold: the vault exists and is shared.
    - Copy the **binding only** (`projectstore.json`). Never copy `.projectstore/state/` — per-session state belonging to the other checkout — and never `harness/`: the overlays are committed and arrive from git.
+   - **Never copy `channel_switch` or `channel_keep`.** They record which channel the parent checkout chose — switched to the npm install, or kept on the git marketplace — a machine-local fact of that checkout's own registry rows, not of the binding it shares. Every other key is copied verbatim.
    - Do not add a provenance key to the config. The parent is resolvable from git at any time; a key would be a second source of truth for the same fact.
 
-1. **Validate the vault path** read-only first: `ls -d "<path>"` (the verb has no dry run — running it on a fresh project would write the config before step 4's approval). If it does not exist, ask the user (via AskUserQuestion) whether to create it; on Yes, step 5 runs `init` instead of `bind` (it creates the directory and binds; the layout's folders remain `/projectstore:scaffold`'s). Never `mkdir` it yourself.
+1. **Validate the vault path** read-only first: `ls -A "<path>"` (the verb has no dry run — running it on a fresh project would write the config before step 4's approval). If it does not exist, or exists and is empty, ask the user (via AskUserQuestion) whether to create the vault there; on Yes, step 5 runs `init` instead of `bind`. `init` creates the whole vault and binds: the directory (unless it is there and empty), its git repository with no commit, and the layout's folders and READMEs. Never `mkdir` it yourself. A directory that already holds files is bound with `bind`; `init` would bind it too, but never scaffolds or `git init`s inside it.
 2. **Detect existing layout**: list immediate subdirectories. If you see `adr/`, `epics/`, `concepts/`, `research/` — the vault already uses an engineering-like layout; suggest `engineering`. Otherwise use the user's choice or `engineering` default.
 3. **Build the config** as JSON:
 
@@ -80,15 +81,21 @@ Steps:
    node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" bind "<vault-path>" [--layout <name>] [--language <code>] [--rebind]
    ```
 
-   `init "<vault-path>" …` instead when step 1 chose to create the vault; `--rebind` only when step 0 ended on **Replace bind**. Naming the vault is the verb's confirmation (there is no `--yes`); the interview's AskUserQuestion in step 4 is the in-session gate. Print the verb's output. A non-zero exit is a refusal or a usage error — relay it and stop. Steps 11 and 12 below `Edit` the file this step wrote; keep them after it.
+   `init "<vault-path>" …` instead when step 1 chose to create the vault — it creates the whole vault, so step 7 has nothing to offer after it; `--rebind` only when step 0 ended on **Replace bind**. Naming the vault is the verb's confirmation (there is no `--yes`); the interview's AskUserQuestion in step 4 is the in-session gate. Print the verb's output. A non-zero exit is a refusal or a usage error — relay it and stop — except an `init` whose output reports `git init failed` or `Scaffold failed`: the binding is written, so relay the remedy line it prints and continue. Step 11 below `Edit`s the file this step wrote; keep it after it.
 
 6. **Check `.gitignore`**: read `<project>/.gitignore` if it exists. Our own files are self-ignored inside `.projectstore/` — the verb writes that `.gitignore` itself, carrying `projectstore.json` and `state/`, with `harness/` committed on purpose (the layout ADR); on the inherit path of step 0a, which bypasses the verb, you wrote both by hand. Unless `.claude/` is ignored wholesale, the one machine-specific entry left is the host's `.claude/settings.local.json`. If it is missing, offer (AskUserQuestion) to append it. If the user declines, skip silently.
 
-7. **Offer scaffold**: if the vault is empty or missing layout folders, ask: "Vault is empty/incomplete. Run `/projectstore:scaffold` to create the layout? [Yes / No]". If yes, invoke `/projectstore:scaffold` immediately (just describe; do not assume execution).
+7. **Offer scaffold** — after `bind` only; a vault `init` made is already scaffolded. Ask the core, which writes nothing here:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" scaffold --json --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Offer only when some `result.rows[]` entry has `action: "create"` — a layout folder or a README is missing. Ask via AskUserQuestion: "The vault is missing N of the layout's folders and READMEs (listed). Create them? Existing files are never rewritten." — **Yes** / **No**. On **Yes**, run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" scaffold --write --json --project "${CLAUDE_PROJECT_DIR}"` and report `result.created`. No `create` row: say nothing and continue.
 
 7.5. **Vault policy** (v0.14, ADR-007 — vault-side, survives clones): check `<vault>/.projectstore.json`.
    - If it already exists with a `spec_policy` key — respect it, print the current policy, do not re-ask.
-   - **New bind into an empty/fresh vault**: ask via AskUserQuestion — "Enable spec-first policy for this vault (every story must be covered by a spec; doctor enforces it)?" with options **Yes, `spec_policy: required` (Recommended)** / **Not yet, `optional`**. Second question: "Enable lifecycle gates (plan/close sections + evidence checks on stories)?" — **Yes, `lifecycle_gates: on` (Recommended)** / **Off for now**.
+   - **New bind into a vault with no artifacts** (a vault `init` just made counts: its folders and README indexes are not artifacts): ask via AskUserQuestion — "Enable spec-first policy for this vault (every story must be covered by a spec; doctor enforces it)?" with options **Yes, `spec_policy: required` (Recommended)** / **Not yet, `optional`**. Second question: "Enable lifecycle gates (plan/close sections + evidence checks on stories)?" — **Yes, `lifecycle_gates: on` (Recommended)** / **Off for now**.
    - **Bind to an existing vault with artifacts**: default to `spec_policy: optional`, `lifecycle_gates: off` and say doctor will suggest enabling once specs appear. Do not impose the gate on an existing backlog.
    - On any choice, write `<vault>/.projectstore.json` (vault ROOT — deliberately not inside `<vault>/.projectstore/`, whose .gitignore would keep the policy out of git):
 
@@ -108,18 +115,7 @@ Steps:
 
 10. **Print summary**: confirm the bind, list the layout's folders, suggest next commands (`/projectstore:status`, `/projectstore:adr "<first decision>"`, `/projectstore:epic <ID> "<title>"`).
 
-11. **Auto-update reminder** (v0.7+, only on first successful bind in this project): After Step 5 (config write), check whether the newly-written config has `autoupdate_asked: true`. If not, ask the user via AskUserQuestion:
-
-   > "Claude Code does not auto-update third-party marketplaces by default. Want to enable auto-update for the SmartAndPoint marketplace so you'll be notified about future projectstore releases?"
-
-   Options:
-   - **Yes, show me how** (Recommended) — respond with: "Open `/plugin` → **Marketplaces** tab → **SmartAndPoint** → toggle **auto-update** on. New releases (v0.7+) will be detected at Claude Code startup; you'll need to run `/reload-plugins` after the notification to activate them."
-   - **No, I'll handle it manually** — respond with: "OK. To pull the latest version at any time, run `/plugin marketplace update SmartAndPoint`, then `/reload-plugins`."
-   - **Already enabled** — respond with: "Great. New releases will be detected at the next Claude Code startup."
-
-   After the question is answered (regardless of choice), Edit `<project>/.projectstore/projectstore.json` to add `"autoupdate_asked": true` to the JSON object. This guarantees we ask only once per project.
-
-12. **Status line offer** (v0.13, ADR-006 — the final step, language is known by now): read `${CLAUDE_PLUGIN_ROOT}/templates/<lang>/strings.json` (fall back to `en`) and the plugin version, then show the fully rendered example:
+11. **Status line offer** (v0.13, ADR-006 — the final step, language is known by now): read `${CLAUDE_PLUGIN_ROOT}/templates/<lang>/strings.json` (fall back to `en`) and the plugin version, then show the fully rendered example:
 
     > `[PS#<version>] 📚 <statusline_example_epic> › <statusline_example_story> (in-progress)`
 

package/node_modules/projectstore/commands/doctor.md

@@ -66,20 +66,25 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
      The verbs refuse it in code; this clause is the belt.
    - `version-drift` → report only: name both versions and where each was
      read; the fix is the host's update path (`/plugin update` for a git-marketplace
-     copy; for the npm registration, the `projectstore-claude` shell's `upgrade`
-     from a terminal — the `plugin-registration` finding spells the command),
+     copy; for the npm registration, the package's `upgrade` from a terminal
+     in the project — the `plugin-registration` finding spells the command),
      not ours.
    - `layout-legacy` (warn; the startup line carries it as an offer) → the project
      still holds the pre-0.28 layout (`.claude/projectstore.json`,
-     `.claude/.projectstore/` — legacy, read through 0.29). The migration is one
+     `.claude/.projectstore/` — legacy, read through 0.30). The migration is one
      previewed `layout` item of `upgrade`, run **from a terminal outside this
      session** (it moves files this session reads and writes; the verb defers
      inside one). The finding names the form for the channel this plugin was
      installed through: the installed copy's own `bin/projectstore.mjs` for a
-     git-marketplace install or a checkout, the `projectstore-claude` shell for
-     the npm registration. Relay the finding's command verbatim and never
-     substitute the other form — the shell, run for a git-marketplace install,
-     would also move this checkout to the npm channel. When the finding carries
+     git-marketplace install or a checkout, the package's `upgrade` for the npm
+     registration. Relay the finding's command verbatim, with the directory its
+     words name, and never substitute the other form or drop its
+     `--no-register`. Both forms carry that flag, so neither changes the
+     channel: the named form runs the copy this project loads, so the move
+     re-stamps the launcher that copy renders, while the other form runs a
+     different copy. The package's `upgrade` without `--no-register` would
+     register the npm copy and turn a git-marketplace copy off for this
+     checkout. When the finding carries
      advice instead of a command — the installed copy predates the move, or
      predates `--no-register` — relay the advice and never compose a command
      yourself. Never move the files yourself. While this finding is in the report, its command is also the one

package/node_modules/projectstore/commands/scaffold.md

@@ -1,23 +1,31 @@
 ---
 description: Scaffold the bound vault with the layout's folder structure and README index files.
-argument-hint: [layout-name]
+argument-hint: ""
 ---
 
-You are creating the folder structure of the projectstore layout inside the bound vault.
+You are creating the bound vault's layout folders and their README indexes through the core's `scaffold` verb. The layout and the language are the binding's; the folder names, the descriptions and every README come from the plugin's templates in that language, so a vault scaffolded here is byte-identical to one `init` made. Never create a folder or write a README yourself, and take no layout argument: `bind --rebind` changes the layout.
 
 Steps:
 
-1. **Read config**: `cat .projectstore/projectstore.json`. If missing, tell user to run `/projectstore:bind <path>` and stop.
-2. **Determine layout**: use `$ARGUMENTS` if provided, else `config.layout`.
-3. **Load layout spec**: `cat "${CLAUDE_PLUGIN_ROOT}/scaffold/layouts/<layout>.json"`. Parse it.
-4. **Show plan**: list every folder that will be created and which folders already exist. Mark new ones with `(create)`, existing with `(exists)`.
-5. **Ask approval** via AskUserQuestion: "Create the missing folders and READMEs? [Yes / Skip READMEs / No]".
-6. **Execute**:
-   - For each folder in `layout.folders`:
-     - Create directory via `mkdir -p <vault>/<folder.path>`.
-     - If `folder.readme === true` and `<vault>/<folder.path>/README.md` does not exist:
-       - Read template: `cat "${CLAUDE_PLUGIN_ROOT}/templates/<lang>/folder-readme.md.tmpl"`.
-       - Substitute `{{folder_name}}` and `{{folder_description}}` based on the folder kind.
-       - Write the README via Write tool.
-   - Also create a top-level `<vault>/README.md` if missing — a simple index pointing to each folder.
-7. **Print result**: tree of newly created files and a one-line "next step" suggestion.
+1. **Plan** — nothing is written:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" scaffold --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   It prints one row per folder, per folder README and for the vault's own `README.md`, each `create` or `exists`.
+   - Exit 3: the project is not bound — tell the user to run `/projectstore:bind <vault-path>` and stop.
+   - Exit 1: a refusal — the bound vault directory is missing, the binding's language lacks a template or a folder string, or a folder's path is a file. Relay the message and stop.
+   - No `create` row: say the vault already has every folder and README the layout declares, and stop.
+
+2. **Ask** via AskUserQuestion, showing the plan's `create` rows: "Create these folders and READMEs in the vault? Existing files are never rewritten." — **Yes** / **No**. On **No**, stop: nothing is written.
+
+3. **Write**, on **Yes**:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" scaffold --write --json --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   The question above is the confirmation; `--json` never asks again. Report `result.created`, and how many rows `result.exists` left as they were. A non-zero exit is an error: relay it.
+
+4. **Next**: the folder indexes fill as artifacts are created; `/projectstore:reconcile` regenerates the board and the other derived views when you want them.

package/node_modules/projectstore/commands/status.md

@@ -22,6 +22,6 @@ Steps:
 
 5. **Active sessions** from `result.sessions`: `active` is the count within the last 30 minutes; `entries[]` (capped at 5) carry `id`, `project_root`, `started_at`, `last_active` — print them as a compact table. From inside a slash command you cannot tell which entry is the current session (Claude's `session_id` reaches hooks, not commands); the user can match by `project_root` and timestamps. If `active` is greater than 1: warn "⚠️ Coordinate via /projectstore:search before creating new artifacts to avoid topic collisions (identity is the slug — ADR-010; the draft's `collision` field catches clashes at creation time)."
 
-6. Suggest the next command from what you saw: `stories.total` is 0 → "Vault looks empty — try `/projectstore:scaffold`"; any view stale or missing → "Stale views — try `/projectstore:reconcile`"; something in progress → name it and suggest `/projectstore:story` to continue.
+6. Suggest the next command from what you saw: `stories.total` is 0 → "No stories yet — `/projectstore:epic <ID> "<title>"` opens the first epic" (a vault `init` made has its folders; `/projectstore:scaffold` is for one bound without them, and its plan says which are missing); any view stale or missing → "Stale views — try `/projectstore:reconcile`"; something in progress → name it and suggest `/projectstore:story` to continue.
 
 What this command no longer does, and why: the former `ls`/`find -mtime -7` walk of recently touched files is gone — its failure mode is a false "nothing changed" (an iCloud download or a git checkout resets mtimes), the opposite of the views' `stale` flag, whose false positive only costs a reconcile. The in-progress list and the views' freshness answer the same question from artifact facts. The former layout-folder check (`ls` the vault, mark missing folders) is `doctor --vault`'s job and `orientation`'s skeleton shows the folders that exist; it is not repeated here.

package/node_modules/projectstore/commands/statusline.md

@@ -3,9 +3,9 @@ description: Enable/disable the projectstore status line (current epic & story i
 argument-hint: "on | off | status"
 ---
 
-You are toggling the projectstore status line for THIS project. When enabled, `install-harness.mjs` points the project's `.claude/settings.local.json` at a launcher it writes at `.projectstore/state/claude-code/statusline.mjs`. That path carries no version, so it never goes stale: the launcher resolves the *currently installed* plugin on every render, and an update is reflected on the spot instead of one restart later. (A dev checkout or `--plugin-dir` root is wired straight to its `scripts/statusline.mjs` — those paths have no version to drift.) The line renders `[PS#<version>] 📚 <epic> › <story> (<status>)` **composed above** any existing HUD (e.g. oh-my-claudecode), never replacing it.
+You are toggling the projectstore status line for THIS project. When enabled, `install-harness.mjs` points the project's `.claude/settings.local.json` at a launcher it writes at `.projectstore/state/claude-code/statusline.mjs`. That path carries no version, so it never goes stale: the launcher resolves the *currently installed* plugin on every render, and an update is reflected on the spot instead of one restart later. (A dev checkout or `--plugin-dir` root is wired straight to its `scripts/statusline.mjs` — those paths have no version to drift.) The line renders `[PS#<version>] 📚 <epic> › <story> (<status>)` **composed above** any existing HUD (e.g. oh-my-claudecode), never replacing it. While this session's band above the prompt is drawing (`/projectstore:bar`), the line gives way to it — your base HUD stays — and it comes back within 30 s of the band stopping.
 
-Resolution is **per-session with zero cross-session and zero vault reads** (ADR-006): the 📚 segment comes from this session's pointer (`.projectstore/state/sessions/<session_id>.json`, maintained by the PreToolUse hook); a fresh session shows an explicit localized cold-start line ("No epic or story in this session yet" / «Эпик и стори ещё не в работе в этой сессии») — never a silent blank; a corrupt pointer shows an error-marked string. Strings localize via `templates/<lang>/strings.json` (en fallback). The version badge is controlled by `statusline.show_version` (default true).
+Resolution is **per-session with zero cross-session and zero vault reads** (ADR-006): the 📚 segment comes from this session's pointer (`.projectstore/state/sessions/<session_id>.json`, maintained by the tool hooks — a write's patch after the write — by `story close`, and at session start; a done, closed or parked story leaves the segment); a fresh session shows an explicit localized cold-start line ("No epic or story in this session yet" / «Эпик и стори ещё не в работе в этой сессии») — never a silent blank; a corrupt pointer shows an error-marked string. Strings localize via `templates/<lang>/strings.json` (en fallback). The version badge is controlled by `statusline.show_version` (default true).
 
 This command flips the flag in `.projectstore/projectstore.json` and then runs the install verb, which writes `settings.local.json` and the launcher behind a preview. The SessionStart hook only refreshes an entry that is already ours and removes it when the flag is off — it never creates one.
 

package/node_modules/projectstore/commands/story.md

@@ -92,11 +92,11 @@ the two cannot collide).
      <baseline-path>`), the derived targets (`kanban`, plus `indexes=<epic
      folder>` when status changed), and the doctor pre-state line. On a clean
      report (`verbatim: true`, `stopped_at: null`, doctor no worse than the
-     pre-state) skip steps 6-6b — the clerk's report is the write evidence. On a
+     pre-state) skip steps 6-6b and run step 6c — the clerk's report is the write evidence. On a
      stopped report: fix what diverged, then re-delegate (the resume rule: after
      the copy, the ceremony restarts at reconcile, not at the race gate) or
      finish the remaining steps yourself (the copy is idempotent).
-   - No clerk available → perform steps 6-6b yourself. There is no fallback
+   - No clerk available → perform steps 6-6c yourself. There is no fallback
      agent: a general-purpose writer is an unpinned procedure.
 
 6. **On Yes** (undelegated path): Write the full file. On a `plan`, finish by
@@ -111,3 +111,16 @@ the two cannot collide).
    — a close is not done while doctor got worse. Then suggest the reviewer's
    proposed `code_refs` via `/projectstore:codemap set` (the reviewer computes it
    from `scripts/diff-refs.mjs --since <started_at>`).
+
+6c. **(close only, both paths) Refresh this session's story**, here in the
+   main thread, after the clerk's clean report or after 6b:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" session refresh "<story-path>" --json --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   `<story-path>` is the absolute `path` the compute script returned in
+   step 2. The copy went through Bash, which no hook sees, so without this the
+   session's band and status line keep naming the closed story. The core finds
+   the session itself; with none it writes nothing and exits 0. A non-zero
+   exit is reported and never undoes the close.