projectstore-claude 0.29.1 → 0.29.3

package/README.md

@@ -6,11 +6,12 @@ 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.
 
 - 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`.
 

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.1",
+      "version": "0.29.3",
       "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.1",
+  "version": "0.29.3",
   "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,19 +111,27 @@ 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
 plugin manifest, namespaced workflow and role skills, lifecycle hooks, and
 the exact bundled core. It stages a stable marketplace under `CODEX_HOME`,
 drives `codex plugin marketplace add` and `codex plugin add`, then reads the
-installation back and verifies its version and payload digest. Restart Codex,
+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. Codex is **experimental** until a live session has exercised every
+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:
@@ -124,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:
 
 ```
@@ -140,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.
@@ -255,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).
 
@@ -269,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
 

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

@@ -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 a `channel_switch` key, which is 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`, 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.
    - 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`.** It records that the parent checkout was switched to the npm install — a machine-local fact of that checkout, 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. Steps 11 and 12 below `Edit` the file this step wrote; keep them 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):
 

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,7 +3,7 @@ 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).
 

package/node_modules/projectstore/docs/alongside.md

@@ -0,0 +1,167 @@
+# ProjectStore beside agent memory and spec-driven tools
+
+People who meet ProjectStore compare it with what they already run next to a coding agent: a
+memory plugin, an instruction file, a spec-driven tool. This page says what each of those keeps,
+what ProjectStore keeps instead, and which parts of ProjectStore exist elsewhere. The README and
+the site name three kinds of tools; the first table here has four kinds, because agent memory kept
+in the repository gets its own column.
+
+The claims about other tools come from their own documentation, repositories and release notes,
+**read on 2026-10-09**. Tools move fast; if a cell below is wrong or out of date,
+[open an issue](https://github.com/SmartAndPoint/ProjectStore/issues/new?title=docs%2Falongside.md%3A+a+wrong+cell)
+and name the cell and your source.
+
+## The question each kind of tool answers
+
+| | Agent memory | Instruction files | Agent notes in the repository | Spec-driven tools | ProjectStore |
+|---|---|---|---|---|---|
+| **Examples** | Mem0, Zep, claude-mem, Codex memories, Claude Code auto memory | `CLAUDE.md`, `AGENTS.md`, rules, Kiro steering | Cline Memory Bank, Serena memories, Basic Memory, Letta | Spec Kit, Kiro specs, OpenSpec, BMAD | |
+| **One entry is** | a fact or an observation | a rule | a note the agent keeps | a change: spec, plan, tasks | a decision, a spec or a work item, with a status, a date and links |
+| **Written by** | the model, automatically | a person, or the agent on request | the agent, sometimes reviewed in pull requests | the agent; phase approval in Kiro and Tessl, a clear yes in OpenSpec's Explore, write previews in one BMAD skill | the agent drafts; a person approves the full text; a fresh-context critic reviews it by rule |
+| **Lives in** | a hosted or local index (vector, graph, SQLite), or machine-local files | the code repository | the code repository, or a memory repository | the code repository; OpenSpec Stores (beta) in a planning repository | a folder kept in git, usually its own repository |
+| **Read by** | the model, by retrieval | the model, at session start or when a file pattern or request matches | the model, on demand | the model and the team, during the feature | Claude Code sessions from the start (Codex: experimental); any agent through the CLI and MCP; people in pull requests and Obsidian |
+| **Scope** | an agent, a user or a machine | the project | the project | a feature, plus a constitution or steering | the project, across features and harnesses |
+| **Changes by** | expiry, invalidation, pruning | rewriting | rewriting, git history | per feature: discarded, or merged into living specs | supersede with reasons; status changes with evidence; `doctor` and `reconcile` |
+| **Answers** | "What does this agent recall?" | "How should an agent behave here?" | "What has this agent learned about the project?" | "How do we build this change?" | "What has the project decided, what is in flight, and was it checked?" |
+
+## Why ProjectStore is not agent memory
+
+1. **Nothing is written because it was said.** A memory system writes when the model notices
+   something. A vault artifact is written through a ProjectStore command, after a person approved
+   its path and full text. The skill that watches the conversation only suggests a command.
+2. **Nothing is read by similarity.** Agents navigate: folder indexes, the link graph grepped by
+   path, the kanban, then the artifact. `search` is a literal substring search. What an agent read
+   is a file a person can open.
+
+   The price: an agent must know a word, a title or a path. Nothing finds a note that says the
+   same thing in other words.
+3. **Nothing belongs to an agent, a user or a machine.** The vault travels through git to whoever
+   has the repository. Claude Code and Codex read it through ProjectStore's commands; any other
+   agent can read it through the CLI or the MCP read surface. Codex memories and Claude Code auto
+   memory are per machine; Mem0's are per user or agent.
+4. **It can be wrong in a way that is reviewed.** A memory that turned false is expired, pruned or
+   invalidated. A decision that turned false is superseded by a newer ADR that says why, and the
+   chain stays.
+5. **What survives `/compact` is paths into the record, not knowledge from the session.** In
+   Claude Code, the SessionStart hook runs after compaction too. It hands back a navigation
+   skeleton of the vault plus the vault paths the session touched: the session's own activity log,
+   machine-local and git-ignored, resolved against the vault. Nothing the conversation said is
+   stored. Codex runs the same hook in its experimental shell, but what it reports after
+   compaction has not been measured.
+
+**The overlap.** ProjectStore keeps a little session state on the machine — a per-session pointer
+and the last 50 activity entries — for orientation, never committed. It is not knowledge, and
+deleting it changes nothing in the vault.
+
+**Where the data goes.** A memory tool stores what it derives from conversations, and some ship it
+off the machine (Mem0's platform, claude-mem's optional cloud sync). The vault holds only text a
+person approved. What reaches the model provider still depends on your harness and its
+permissions.
+
+## Memory and the vault, side by side
+
+They are not rivals. Use both, each for its own thing:
+
+- **Memory for the person and the machine:** how you like to work, your environment's quirks,
+  corrections you gave the agent.
+- **The vault for the project:** what was decided and why, what is in flight, what was checked.
+
+The vendors say the same about their own memory. Codex: "Keep required team guidance in AGENTS.md
+or checked-in documentation. Treat memories as a helpful recall layer, not as the only source for
+rules that must always apply." Claude Code's auto memory skips what your `CLAUDE.md` already says.
+
+The rule needs upkeep, because memory fills up on its own. When a memory states a project decision
+or an idea the team should see, move it into the vault as an artifact, and let the memory keep only
+a pointer to it.
+
+## The ingredients, tool by tool
+
+Every ingredient of ProjectStore's loop exists somewhere else. This matrix shows where. "Core"
+means without extensions; "?" means the documentation we read says nothing either way.
+
+| Tool | Decision record with status and supersede | Person approves the full text before a write | Fresh-context review of planning artifacts | Fresh-context review of the diff against acceptance criteria | Orientation from the record at session start | Consistency checks with no model | Read surface for any agent |
+|---|---|---|---|---|---|---|---|
+| Spec Kit 1.1, core | no | no (a convention between phases) | no (in-context `/speckit.analyze` and `/speckit.checklist` only) | no | no | ? | commands for about forty agents |
+| Spec Kit with community extensions | `adrkit`: MADR records with `status`, `adr accept`, superseded retrieval (pinned below 1.1.0) | no, before a write. `plan-review-gate` requires spec and plan merged by PR before tasks; `spec-validate` adds approval state as "a hard gate before /speckit.implement" | `red-team`, `critique`, `multi-model-review` | `maqa`, a QA workflow (fresh context unstated) | the official `agent-context` extension keeps a static block in `CLAUDE.md`/`AGENTS.md`; `memory`, `dubsar` (resume) | ? (`speckit-utils` "validate project health", `sync`; model use unverified) | same |
+| Kiro | no | yes, per phase (Quick Spec skips the gates) | ? | ? | steering, always included | ? | Kiro only |
+| OpenSpec 1.14 | a section per change; the archive keeps history | Explore only: waits for "a clear yes" | ? | ? | marker blocks in `CLAUDE.md`/`AGENTS.md`; no session hook | **yes**: `openspec validate` | many tools |
+| BMAD 6.12.1 | spine `AD-n`: IDs can be retired, never reused; append-only rationale; no supersede chain documented | the project-context skill shows every write first | **yes**: reviewer gates on PRD, spine, UX | fresh subagent lenses (edge cases, verification gaps); the edge-case lens reads the spec's acceptance as claims, not per criterion | its `AGENTS.md` block (project-context skill); no SessionStart hook found | **yes**: `sprint_plan.py validate` | installer for several agents |
+| Beads 1.3.1 | no: issues, not decisions (`bd supersede` marks an issue superseded by a newer one) | no | no | no | **yes**: `bd prime` through SessionStart hooks (Claude Code, Gemini CLI, Codex) | **yes**: `bd doctor`, `bd lint` (missing sections), `bd orphans` (referenced in commits, still open) | CLI with JSON; Dolt in git, JSONL export |
+| Letta, Serena | no | no | no | no | Letta loads memory-root files into the system prompt every turn | no | Serena: any MCP client |
+| Mem0, claude-mem | no | no | no | no | claude-mem injects memory at session start | no | many harnesses |
+| ProjectStore 0.29.2 | **yes**: ADR status, `superseded_by` | **yes**, through its commands | a standing rule for every kind (critic) | a standing rule (reviewer), per criterion with evidence | **yes** in Claude Code; Codex experimental | **yes**: `doctor`, `reconcile`, regenerated views | CLI and MCP; Claude Code and Codex shells |
+
+**What it shows.** No single column is ProjectStore's alone:
+- `adrkit` keeps decision status and supersession;
+- OpenSpec, BMAD and Beads validate artifacts without a model;
+- Beads injects ready work at session start;
+- BMAD reviews plans and diffs in fresh contexts.
+
+What none of the tools above documents is all of them over one record: decisions, specs and work
+items in one linked graph with a lifecycle, where the same `doctor` checks the links between them
+and down to code, the same views regenerate from them, one critic rule covers every kind, and each
+session's starting map is computed from that record.
+
+**The nearest composition is Spec Kit with extensions.** Read cell by cell, it covers three of the
+four ingredients listed above — decision status (`adrkit`), fresh-context review (`red-team`,
+`critique`, `multi-model-review`), session-start orientation (`agent-context`, `memory`, `dubsar`) —
+and has a "?" on the fourth, checks with no model. But it spreads across three stores — `adrkit`'s
+ADRs, `specs/`, and an issue tracker through `maqa` — and documents no links between them and no
+check that reads across them. `adrkit`'s catalog entry also pins Spec Kit below 1.1.0, the current
+core.
+
+**Review is a rule, not a lock**, in ProjectStore and in BMAD alike. Both are only as good as their
+being followed. In ProjectStore, ADRs, specs, epics and research notes carry `review_status:
+pending` until a critic pass is applied, so "not yet reviewed" is a state the tools can read;
+stories are checked instead by the reviewer, against their diff. Nothing stops a person from
+accepting an ADR before the critic pass.
+
+**When this table is re-read:** when BMAD ships its next release, when OpenSpec Stores leave beta,
+or when a Spec Kit extension joins decision records to review — each of those could change a cell.
+
+**Sources, read on 2026-10-09:**
+- Spec Kit: [repository](https://github.com/github/spec-kit) — releases 1.0.0 (2026-08-21) and
+  1.1.0 (2026-10-02), `docs/concepts/spec-persistence.md`, `docs/reference/integrations.md`,
+  `extensions/catalog.community.json`; [adrkit](https://github.com/mbeacom/adrkit).
+- Kiro: [specs](https://kiro.dev/docs/specs/), [best practices](https://kiro.dev/docs/specs/best-practices/),
+  [steering](https://kiro.dev/docs/steering/).
+- OpenSpec: [repository](https://github.com/Fission-AI/OpenSpec) — releases, `docs/concepts.md`,
+  `docs/cli.md`, `docs/installation.md`, `docs/stores-beta/user-guide.md`.
+- BMAD-METHOD: [repository](https://github.com/bmad-code-org/BMAD-METHOD) — release 6.12.1
+  (2026-10-04), `src/bmm-skills/plan/bmad-architecture/references/reviewer-gate.md`,
+  `src/bmm-skills/plan/bmad-sprint-planning/references/validate.md`.
+- Beads: [repository](https://github.com/gastownhall/beads) — release 1.3.1 (2026-09-30),
+  `docs/cli-reference/`.
+- Letta: [context repositories](https://www.letta.com/blog/context-repositories),
+  [MemFS](https://docs.letta.com/concepts/memfs). Serena:
+  [memories](https://oraios.github.io/serena/02-usage/045_memories.html).
+- Zep / Graphiti: [concepts](https://help.getzep.com/concepts),
+  [Graphiti](https://github.com/getzep/graphiti). Cline: [Memory Bank](https://docs.cline.bot/best-practices/memory-bank).
+  Basic Memory: [repository](https://github.com/basicmachines-co/basic-memory). Tessl:
+  [overview](https://docs.tessl.io/overview/readme.md),
+  [spec-driven development tile](https://github.com/tesslio/spec-driven-development-tile).
+- Mem0: [how it works](https://docs.mem0.ai/core-concepts/how-it-works),
+  [memory expiration](https://docs.mem0.ai/platform/features/memory-expiration),
+  [OpenMemory's removal](https://github.com/mem0ai/mem0/pull/6530). claude-mem:
+  [repository](https://github.com/thedotmack/claude-mem).
+- Claude Code: [memory](https://code.claude.com/docs/en/memory). Codex:
+  [memories](https://learn.chatgpt.com/docs/customization/memories),
+  [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).
+- ProjectStore: this repository.
+
+## What the checks cost
+
+The critic and reviewer runs are model calls, and they are not free. On this repository, where
+every change goes through the full loop, vault work measures 22.5% of total spend; on a typical
+project, budget 10–15% of a weekly limit. The number is the price of the critic and reviewer
+runs, not of storing files. See
+[What it costs — measured, not promised](../README.md#what-it-costs--measured-not-promised).
+
+## Spec-driven tools
+
+Running ProjectStore beside a spec-driven tool such as Spec Kit, Kiro or OpenSpec is a design that
+has not been tried. The idea is that the spec-driven tool would own one feature's spec, plan and
+tasks, while ProjectStore keeps the decisions, the backlog and the checks around them. Whether the
+two tools' agent instructions, entry points and acceptance criteria stay out of each other's way is
+an open question, and so is how ProjectStore's spec-first policy should be set beside them. A trial
+and a decision on that policy are proposed; until they land, this page recommends no setting.

package/node_modules/projectstore/docs/extending.md

@@ -4,8 +4,8 @@
 
 Since v0.14 the kind machinery is layout-driven: `draft.mjs` builds ANY kind
 declared in the layout, and doctor's template check follows the layout instead
-of a hardcoded list. A new kind needs **five touch points** — note that **all
-five live inside the plugin installation**, not in your vault (there is no
+of a hardcoded list. A new kind needs **six touch points** — note that **all
+six live inside the plugin installation**, not in your vault (there is no
 vault-side layout or template override):
 
 1. **Layout folder entry** — `scaffold/layouts/<name>.json` → `folders`:
@@ -56,6 +56,16 @@ vault-side layout or template override):
    `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
+   file. `scaffold` (and `init`) render the folder's README and its row in
+   the vault's top-level README from them, and refuse a layout whose folder
+   kind has no string in the bound language, naming the kind and the
+   language; doctor warns about the same gap. Every folder kind needs one,
+   with or without a command (`diagram` too). Keep the description to 160
+   characters with no `|`: the SessionStart skeleton shows it as the
+   folder's Purpose cell. Machine tokens such as `stories/` stay as they are.
+
 If the kind introduces **new section headings or inline keywords** that
 deterministic checks must recognize (doctor, reconcile, story-section),
 register a form per bundled language (en, ru, es, de, fr, zh) in
@@ -108,7 +118,11 @@ Frontmatter keys **and their values** stay English (`status: planned` is
 machine-read; only prose and table labels get translated). Then register the
 language's heading/keyword/index-column forms in `scaffold/headings.json`, and
 add the locale to `LOCALES` in `tests/locales.test.mjs` so the suite actually
-runs over it. `templates/<lang>/strings.json` localizes the statusline only.
+runs over it. `templates/<lang>/strings.json` localizes the statusline and the
+folder names and descriptions `scaffold` writes into the READMEs
+(`folders.<kind>`, one per kind the layout declares — touch point 6 above),
+and `vault-readme.md.tmpl` is the vault's top-level README. There is no English
+fallback for either: a language that lacks one is refused by `scaffold`.
 
 Skipping the registry does not produce one clean error — it degrades *unevenly*,
 which is why the spec exists: an unregistered index header raises a doctor