projectstore-codex 0.0.1 → 0.28.2

package/.codex-plugin/plugin.json

@@ -0,0 +1,48 @@
+{
+  "name": "projectstore",
+  "version": "0.28.2",
+  "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",
+    "email": "ekonev@smartandpoint.com",
+    "url": "https://github.com/SmartAndPoint"
+  },
+  "homepage": "https://github.com/SmartAndPoint/ProjectStore#readme",
+  "repository": "git+https://github.com/SmartAndPoint/ProjectStore.git",
+  "license": "MIT",
+  "keywords": [
+    "project-management",
+    "adr",
+    "epics",
+    "stories",
+    "kanban",
+    "obsidian",
+    "markdown",
+    "knowledge-base",
+    "engineering-process",
+    "claude-code",
+    "codex",
+    "agentic",
+    "ai-agents"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "ProjectStore",
+    "shortDescription": "Versioned project memory for developer teams and agents.",
+    "longDescription": "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.",
+    "developerName": "SmartAndPoint",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Project memory",
+      "Architecture decisions",
+      "Planning",
+      "Peer review"
+    ],
+    "websiteURL": "https://github.com/SmartAndPoint/ProjectStore#readme",
+    "defaultPrompt": [
+      "Show the current ProjectStore status and work in progress.",
+      "Capture this technical decision as a ProjectStore ADR.",
+      "Plan the next ProjectStore story, then review the implementation."
+    ]
+  }
+}

package/README.md

@@ -1,19 +1,27 @@
 # projectstore-codex
 
-**This is a reserved name, not a product.** Install [`projectstore`](https://www.npmjs.com/package/projectstore) instead:
+The Codex installer for [ProjectStore](https://github.com/SmartAndPoint/ProjectStore). It ships a Codex plugin manifest (`.codex-plugin/plugin.json`), rendered namespaced workflow skills, lifecycle hooks, and the ProjectStore core pinned at the exact same version and bundled inside the tarball.
+
+From a terminal in your project:
 
 ```sh
-npm install projectstore
+npx projectstore-codex install --project "$PWD"
 ```
 
-Codex installs the very same `projectstore` package through a marketplace entry. This name is reserved so it cannot be taken and made to look official.
+The installer previews every mutation, stages a stable local marketplace under `CODEX_HOME`, asks Codex's own CLI to install the plugin, and verifies the materialised cache by version and payload digest. Restart Codex, approve the ProjectStore hooks when prompted, then run `$projectstore-bind <vault-path>`. Codex picks up hook changes late: a release that changes hooks may take effect only in the session after next.
+
+Upgrade with `npx projectstore-codex@<version> upgrade --project "$PWD"`. Project uninstall leaves the user-global Codex plugin in place; `uninstall --global` is the explicit machine-wide removal.
+
+Codex support is **experimental**: see [`docs/harnesses.md`](https://github.com/SmartAndPoint/ProjectStore/blob/main/docs/harnesses.md) for what has been measured and what has not. Hooks start `node` from the Codex process's own `PATH`, so start Codex from a terminal where `node` resolves.
 
-ProjectStore ships as **one package carrying every harness's manifest** —
-Claude Code, Codex, opencode and an MCP server all install the same tree. That
-decision is recorded in the project's architecture decision records.
+To exercise the same npx path from a checkout, against a built tarball:
+
+```sh
+npm run shells:build -- --only projectstore-codex --dev --out dist
+npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").version').tgz" projectstore-codex install --project "$PWD"
+```
 
 - Source: https://github.com/SmartAndPoint/ProjectStore
 - Issues: https://github.com/SmartAndPoint/ProjectStore/issues
-- Author: Evgenii Konev (SmartAndPoint)
 
 MIT licensed.

package/bin/projectstore-codex.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// projectstore-codex — the Codex distribution shell of projectstore.
+// RENDERED by packaging/shells.mjs from its template: edit the template, then
+// `node packaging/shells.mjs --write`. A hand edit here fails --check.
+//
+// A shell is a bin and a pin, never logic (the layout spec, contract 10): this
+// file locates the core the tarball bundles and execs it with
+// `--harness codex` inserted after a verb that takes it. Every other
+// argument passes through, so `projectstore-codex <verb> …` is exactly
+// `projectstore <verb> --harness codex …` — the same preview, the
+// same files, the same exit code. Naming the shell is the confirmation the
+// core's install gate asks for, exactly as naming --harness is.
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SHELL = "projectstore-codex";
+const HARNESS = "codex";
+// The verbs of the core's table that declare --harness (rendered from
+// 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"]);
+
+// 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,
+// and the core's file layout is not an API (the shells ADR, decision 5).
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const CANDIDATES = [
+  resolve(root, "node_modules", "projectstore", "bin", "projectstore.mjs"), // bundled — the release shape
+  resolve(root, "core", "bin", "projectstore.mjs"), // vendored — the shells ADR's fallback
+];
+
+// Inserts --harness after the verb (the first positional) when that verb takes
+// it; refuses another harness; never duplicates one already given. Scans up to
+// a bare "--". A verb that is not the first positional (`--project x install`)
+// is left alone: the core then asks for --harness itself, a usage error, never
+// a wrong write.
+function fixHarness(argv) {
+  const stop = argv.indexOf("--");
+  const scan = stop === -1 ? argv : argv.slice(0, stop);
+  const given = [];
+  const dangling = { error: `\`--harness\` is given without a value — this shell fixes it to ${HARNESS}; drop the flag` };
+  for (let i = 0; i < scan.length; i++) {
+    if (scan[i] === "--harness") {
+      const v = scan[i + 1];
+      if (v === undefined || v.startsWith("-")) return dangling;
+      given.push(v); i++;
+    } else if (scan[i].startsWith("--harness=")) {
+      const v = scan[i].slice("--harness=".length);
+      if (!v) return dangling;
+      given.push(v);
+    }
+  }
+  const other = given.find((g) => g !== HARNESS);
+  if (other !== undefined) return { error: `installs for ${HARNESS} only — \`--harness ${other}\` names another harness. Run that harness's shell, or the core: npx projectstore <verb> --harness ${other} …` };
+  if (given.length) return { argv }; // named already: pass through, never twice (the core's option repeats)
+  const at = scan.findIndex((a) => !a.startsWith("-"));
+  if (at === -1 || !HARNESS_VERBS.has(scan[at])) return { argv };
+  return { argv: [...argv.slice(0, at + 1), "--harness", HARNESS, ...argv.slice(at + 1)] };
+}
+
+const core = CANDIDATES.find((p) => existsSync(p));
+if (!core) {
+  process.stderr.write(`${SHELL}: the bundled core is missing — looked at:\n${CANDIDATES.map((c) => "  " + c).join("\n")}\n`);
+  process.exitCode = 2;
+} else {
+  const fixed = fixHarness(process.argv.slice(2));
+  if (fixed.error) {
+    process.stderr.write(`${SHELL}: ${fixed.error}\n`);
+    process.exitCode = 2;
+  } else {
+    // stdio inherited: the core's install gate asks on a terminal and refuses
+    // without one, so the child must see the real stdin and stdout. No
+    // timeout — the child waits on a human at the preview. exitCode, not
+    // exit(): the core's own bin says why (a pending write on a pipe).
+    const r = spawnSync(process.execPath, [core, ...fixed.argv], {
+      stdio: "inherit",
+      env: { ...process.env, PROJECTSTORE_DISTRIBUTION_ROOT: root },
+    });
+    if (r.error) process.stderr.write(`${SHELL}: ${r.error.message}\n`);
+    // A signal is relayed the shell way (128 + its number): Ctrl-C at the
+    // preview is 130 here as it would be on the core itself.
+    process.exitCode = r.status ?? (r.signal ? 128 + (osConstants.signals[r.signal] || 0) : 2);
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/node_modules/projectstore/hooks/session-start.mjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/node_modules/projectstore/hooks/session-rules.mjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/node_modules/projectstore/scripts/touch-session.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/node_modules/projectstore/scripts/touch-session.mjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/node_modules/projectstore/hooks/session-stop.mjs\""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/node_modules/projectstore/hooks/pre-compact.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "SmartAndPoint",
+  "description": "Claude Code plugins by SmartAndPoint.",
+  "owner": {
+    "name": "Evgenii Konev",
+    "email": "ekonev@smartandpoint.com",
+    "url": "https://github.com/SmartAndPoint"
+  },
+  "plugins": [
+    {
+      "name": "projectstore",
+      "displayName": "projectstore",
+      "description": "📚 Your agent runs the project through a verified loop: task → artifact (ADR · spec · epic · story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
+      "version": "0.28.2",
+      "author": {
+        "name": "Evgenii Konev",
+        "email": "ekonev@smartandpoint.com",
+        "url": "https://github.com/SmartAndPoint"
+      },
+      "category": "productivity",
+      "homepage": "https://github.com/SmartAndPoint/ProjectStore",
+      "tags": [
+        "obsidian",
+        "markdown",
+        "adr",
+        "epics",
+        "stories",
+        "kanban",
+        "knowledge-base",
+        "engineering-process",
+        "llm-wiki"
+      ],
+      "source": {
+        "source": "github",
+        "repo": "SmartAndPoint/ProjectStore"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "name": "projectstore",
+  "displayName": "projectstore",
+  "version": "0.28.2",
+  "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",
+    "email": "ekonev@smartandpoint.com",
+    "url": "https://github.com/SmartAndPoint"
+  },
+  "homepage": "https://github.com/SmartAndPoint/ProjectStore",
+  "repository": "https://github.com/SmartAndPoint/ProjectStore",
+  "license": "MIT",
+  "keywords": [
+    "project-management",
+    "adr",
+    "epics",
+    "kanban",
+    "obsidian",
+    "markdown",
+    "engineering-process"
+  ]
+}

package/node_modules/projectstore/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "projectstore": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs",
+        "mcp",
+        "--project",
+        "${CLAUDE_PROJECT_DIR}"
+      ]
+    }
+  }
+}

package/node_modules/projectstore/AGENTS.md

@@ -0,0 +1,26 @@
+<!-- projectstore:agents v4 (managed by projectstore — edit outside markers) -->
+## projectstore agents
+
+- **A feature-sized request opens a vault artifact before it opens an editor.**
+  Analysis → placement (which epic, which story) → an ADR and/or spec when the
+  "how" is non-trivial → `projectstore:critic` → only then implementation →
+  `projectstore:reviewer`. "Feature-sized" is not a judgement about how the
+  request was phrased — it is about what the work touches: if you are about to
+  write across several source files, open the story first.
+- **Report instruction conflicts; do not arbitrate them.** If a session-level or
+  harness-level instruction contradicts this block, say so and ask which wins.
+  Resolving it silently is how the contradiction becomes invisible to the person
+  who could have settled it.
+- When spawning any agent below, resolve its model from
+  `.projectstore/harness/<harness>.json` → `agents.per_agent.<name>.model ?? agents.default.model`,
+  where `<name>` is the **bare** agent name (`critic` for `projectstore:critic`),
+  and pass it as the spawn's model parameter. No key — pass nothing.
+- After authoring or revising any vault artifact (ADR/research/epic/story) or
+  design proposal: run the `projectstore:critic` agent on it before treating it final.
+- Before implementing an epic/story: consult `projectstore:planner` — it plans
+  against how prior epics map to the codebase (`code_refs`).
+- After writing code, before commit / story-done: run `projectstore:reviewer` —
+  it verifies the diff actually closes the story's acceptance criteria.
+- When discussing vault contents, reference artifacts by their frontmatter
+  `title:` (with their parent epic), never by session-invented shorthand.
+<!-- /projectstore:agents -->

package/node_modules/projectstore/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SmartAndPoint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/projectstore/README.md

@@ -0,0 +1,284 @@
+# 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.
+
+[![release](https://img.shields.io/github/v/release/SmartAndPoint/ProjectStore?label=release)](https://github.com/SmartAndPoint/ProjectStore/releases) [![license](https://img.shields.io/github/license/SmartAndPoint/ProjectStore?label=license)](./LICENSE) [![Star on GitHub](https://img.shields.io/badge/%E2%AD%90-star_us-yellow?logo=github)](https://github.com/SmartAndPoint/ProjectStore/stargazers)
+
+A project workflow plugin for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex](https://developers.openai.com/codex/) (experimental). Both are released together at one version, and each installs with one command.
+
+---
+
+## Two months of agents, and nobody knows why
+
+Agents write code fast. They re-decide settled questions even faster: every fresh session arrives empty, makes its own architectural call, and commits under its own assumptions. Two months later you have noodle code — every strand reviews fine on its own, and each was written under a different theory of the project. Ask *"why is this a queue and not a cron job?"* and nobody can answer. The agent that decided is long gone.
+
+The fix is not a smarter agent. It is a loop with verification in it.
+
+## 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.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/loop.svg">
+  <img alt="The ProjectStore loop: task → artifact → critic (verify) → backlog → planner → implement → reviewer (verify) → done → views regenerate" src="docs/images/loop-light.svg">
+</picture>
+
+1. **You hand the agent a task.** It opens an artifact before it opens an editor: an ADR if something needs deciding, an epic and stories for the work, a spec when the "how" is non-trivial.
+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.
+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.
+
+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.
+
+## What lands on disk
+
+Say *"let's go with Postgres, not Mongo — we need transactions"*, approve the draft, and a real file lands:
+
+```markdown
+---
+title: "Use Postgres for primary storage"
+status: accepted
+date: 2026-07-03
+---
+## Context
+We need ACID transactions for order processing...
+## Decision
+Postgres 16 as the primary store...
+## Alternatives Considered
+### MongoDB — rejected because...
+```
+
+Six months later, *"why Postgres?"* has an answer with a date and the alternatives you rejected. Stories work the same way — status in frontmatter, board generated from it — and your status line always shows what *this* session is working on:
+
+![projectstore status line: the 📚 epic › story line sitting above an existing oh-my-claudecode HUD](docs/images/statusline-hud.png)
+
+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
+
+Open Claude Code in your project and say:
+
+> Install the projectstore plugin from https://github.com/SmartAndPoint/ProjectStore and set it up for this project.
+
+That's the whole setup. Claude adds the marketplace, installs the plugin, and walks you through binding a vault, scaffolding it and wiring the status line — every step previewed, nothing written without your Yes.
+
+**On Codex**, run one command from a terminal in your project:
+
+```
+npx projectstore-codex install --project "$PWD"
+```
+
+Then restart Codex, approve the ProjectStore hooks when it asks, and run `$projectstore-bind ~/Documents/my-project-vault`. Codex support is newer and still labelled experimental: [`docs/harnesses.md`](./docs/harnesses.md#codex) says what has been verified and what has not. A project can be worked from both agents: they share the binding in `.projectstore/`, and each keeps its own overlay and session state beside it ([running both over one project](./docs/harnesses.md#running-both-over-one-project)).
+
+<details>
+<summary>Prefer to type it yourself?</summary>
+
+```
+/plugin marketplace add SmartAndPoint/ProjectStore
+/plugin install projectstore@SmartAndPoint
+/reload-plugins
+/projectstore:bind ~/Documents/my-project-vault
+```
+
+One switch worth flipping: Claude Code does **not** auto-update third-party plugins by default — `/plugin` → **Marketplaces** → **SmartAndPoint** → toggle **auto-update** on. If you skip it, `/projectstore:doctor` will remind you later with the exact setting.
+
+Contributors: `git clone` this repo, then `claude --plugin-dir ./ProjectStore`.
+
+**Or from npm, in one command** — from a terminal, not inside a Claude Code session:
+
+```
+npx projectstore-claude install --project "$PWD"
+```
+
+The same tree is published to npm as [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest — and `projectstore-claude` is its Claude Code shell: the core pinned at the same version and bundled inside, the harness fixed, so the one command has the same shape on every harness. It registers the plugin with Claude Code: it writes a small local marketplace of its own under your Claude home, then drives `claude plugin marketplace add` / `plugin install` **at local scope**, so the registration lands in this checkout's `.claude/settings.local.json` and nowhere else. Every host command is printed before it runs; naming the harness is the confirmation. Restart Claude Code afterwards. A git-marketplace copy already enabled for the checkout is silenced there (not globally) so the plugin does not load twice; `uninstall` turns it back on. Pin or upgrade with `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run. The core's low-level form, `npx projectstore <verb> --harness claude-code …`, is exactly what the shell runs. bun works the same on the packed bin.
+
+**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,
+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
+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:
+
+```sh
+npm run shells:build -- --only projectstore-codex --dev --out dist
+npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").version').tgz" projectstore-codex install --project "$PWD"
+```
+
+The package also carries a `bin`. Without a session — in CI, or in a shell — the same core answers token-free, with a `--json` envelope on every verb:
+
+```
+npx projectstore doctor --json
+npx projectstore install --harness claude-code   # the low-level form the shell runs: previews, then writes the agents block and the status line; naming the harness is the confirmation, there is no --yes
+npx projectstore reconcile --write --only kanban
+```
+
+Reads too — the same facts the agents get over MCP:
+
+```
+npx projectstore status --json
+npx projectstore search "entry rule" --kind spec
+npx projectstore show adr/README.md --section index
+npx projectstore graph neighbors epics/PS-CORE/epic.md
+npx projectstore codemap --for scripts/lib.mjs
+```
+
+The same eight reads are an MCP server. The plugin registers it through its own `.mcp.json`, so a Claude Code session has `status`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `orientation` and `doctor` as tools with no shell; every tool result is the CLI's `--json` for the same arguments. Elsewhere:
+
+```
+npx projectstore mcp --project "$PWD"
+```
+
+Binding, too — naming the vault is the confirmation, and changing it needs `--rebind`:
+
+```
+npx projectstore bind ~/vaults/my-project
+npx projectstore init ~/vaults/new-project --language ru
+```
+
+`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.
+</details>
+
+## Upgrading
+
+`/plugin update` (or auto-update) and a restart, then one command per project
+bound before 0.28. What an existing project sees afterwards, and why:
+
+- **The project's files move to `.projectstore/`.** `.claude/projectstore.json`
+  and `.claude/.projectstore/` become `.projectstore/projectstore.json`,
+  `.projectstore/harness/claude-code.json` and `.projectstore/state/`. Nothing
+  breaks before you move them: every reader falls back to the old paths through
+  0.29, and the startup line names the command until the move is done. Close
+  every Claude Code session in the project, run that command from a terminal,
+  then restart. The command depends on how you installed:
+  - **From the git marketplace** (every 0.27.x install): the installed copy's
+    own `bin/projectstore.mjs`, with its path spelled out in the startup line —
+    `node "<plugin cache>/bin/projectstore.mjs" upgrade --harness claude-code --no-register --project "$PWD"`.
+    `--no-register` leaves your plugin registration as it is.
+  - **From npm**: `npx projectstore-claude@<version> upgrade --no-register --project "$PWD"`.
+
+  Both forms move only the project's files, so neither touches your plugin
+  registration. The same run re-stamps the status-line launcher at its new path
+  and re-registers the agents block, whose template is now v4. A plain
+  `npx projectstore-claude upgrade` on a git-marketplace install does more: it
+  also registers the plugin from npm for this checkout and turns the
+  git-marketplace copy off here, so `/plugin update` stops reaching the
+  checkout. The 0.28.0-rc.1 and rc.2 startup lines named that shell form
+  (`npx projectstore-claude@<version> upgrade`, without `--no-register`), so on
+  those, update first and run what the new startup line names. If it already
+  happened,
+  `npx projectstore-claude@<version> uninstall --surface plugin --project "$PWD"`
+  (0.28.0 or later) turns the git-marketplace copy back on. That copy must be 0.28 or later — an
+  older one reads a moved project as unbound — so update it first if it is not.
+  Restart, then run
+  `/projectstore:doctor --fix` in the new session, which re-stamps the status
+  line against that copy.
+- **The status line keeps rendering.** A launcher written by an earlier version
+  still works, but it carries no file stamp and its embedded fallback root is
+  frozen at the old version; the move above re-stamps it. Nothing rewrites that
+  file behind your back any more: first wiring and refresh are `install`'s,
+  behind a preview.
+- **`/projectstore:status` and `/projectstore:search` answer differently:**
+  facts from artifact frontmatter and the derived views' freshness instead
+  of an `mtime` walk; a literal, bounded, grouped search instead of a shell
+  `grep`. Every other command prints what it printed before.
+- **`/projectstore:doctor` has new lines** — the state of each installed
+  surface, a version-drift check across plugin versions, and one permanent
+  info line saying the MCP read tools are registered. Its exit code now
+  carries the verdict (1 = findings), so a red Bash result is findings, not
+  a crash.
+- **The plugin registers an MCP server** (eight read-only tools over the
+  vault). Claude Code may ask you to approve it once.
+- **The agents block stays where Claude Code reads it.** In a project with an
+  `AGENTS.md`, the block goes there and `CLAUDE.md` carries a one-line
+  `@AGENTS.md` import; otherwise the block goes into `CLAUDE.md`. A project with
+  an `AGENTS.md` and no `CLAUDE.md` now gains that one-line `CLAUDE.md`.
+- **The passive skills are published under the `projectstore-` prefix**
+  (`projectstore-decision-detector`, `projectstore-peer-reviewer`,
+  `projectstore-story-completion`, `projectstore-vault-communication`). Nothing
+  in a project names them; only a skill listing shows the new names.
+- **Rolling back** to 0.27.x before the move: everything keeps working, since
+  0.27.x still reads the old layout. It rewrites the status-line launcher in its
+  own form, as it always did; coming forward again, the startup line names the
+  move once more, and the move re-stamps the launcher. If a session already
+  re-stamped the status line or re-registered the agents block before the move
+  (rc.2's `/projectstore:doctor --fix` did both), 0.27.x reports a foreign
+  status line and a v4 block and leaves both alone — unless you run its
+  `/projectstore:agents register`, which rewrites the block; the status line
+  still renders, and the move settles both.
+- **Rolling back** to 0.27.x after the move: 0.27.x looks for its binding under
+  `.claude/`, finds none and offers `bind`. Do not accept. A re-bind writes
+  `.claude/projectstore.json` again, and 0.28's `install` and `upgrade` refuse
+  while two bindings exist. To come forward again, delete
+  `.claude/projectstore.json`, then run the command the startup line names
+  once more: a 0.27.x session writes its welcome marker back under `.claude/`.
+- **Installed from npm?** Then `/plugin update` has nothing to fetch: the
+  registration is refreshed by the package itself — from a terminal outside
+  the session, `npx projectstore-claude@<version> upgrade --project "$PWD"`
+  rewrites the local marketplace and runs the host's
+  `plugin update` for this checkout. `/projectstore:doctor` says when the
+  registration is behind the package, and names that command.
+
+## When an agent starts a task, it can find its way
+
+Two generated views exist for exactly that moment. `graph.md` holds every artifact's links, typed, in both directions — one grep returns a document's whole neighborhood. `code-map.md` answers where the code for each epic actually lives, so new code lands where the old code already is. And before any architectural choice, the agent is pointed at the ADR index first — which is how settled questions stay settled.
+
+## Teams: many humans, many agents
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/team.svg">
+  <img alt="Team setup: several developers, each with their own agent, bind to one vault in its own git repo; ADRs and specs are reviewed as merge requests" src="docs/images/team-light.svg">
+</picture>
+
+Put the vault in its own repository. Every teammate installs ProjectStore, binds to the same vault, and contributes through the same approval gates. ADRs and specs get reviewed like code — as merge requests, except what's under review is the *reasoning*. A teammate without an agent reviews on GitHub or in Obsidian: it is all just markdown.
+
+Parallel sessions coordinate too: each registers itself, sessions warn each other on the same vault, every status line shows only its own work — and once a session's writing settles on an epic or a document, it gets offered a name to be addressed by. Measured before shipping: roughly one offer per session; the naive "rename on every change" fired 37 times in the worst recorded session, which is why it doesn't do that.
+
+## What it costs — measured, not promised
+
+Running the loop is not free, and we will not pretend otherwise. On this very repository — the worst case we know, since here the tool builds itself and every change goes through the full loop — vault work measures **22.5% of total spend**. On a typical project, budget **10–15% of your weekly limit**.
+
+What you get for it: a project manager and a systems analyst who never forget to file, made of the same agent you already pay for. The artifacts are not notes-to-self — they are the working backlog, the review record and the decision log of the project.
+
+And they are the exit door. The vault is plain markdown in git — no server, no proprietary format, nothing to export. Move to Codex, Gemini or DeepSeek tomorrow and the project continues: the orientation a new agent needs is already on disk, so you spend no tokens re-teaching a model what the project is and why.
+
+## 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
+
+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).
+
+## Philosophy
+
+1. **Markdown + git is the source of truth.** No proprietary format. The plugin can disappear; your project's decisions remain.
+2. **Obsidian is a view, not a dependency.** Files render on GitHub, in any editor, in `cat`.
+3. **The agent is a methodologist, not a database.** Skills nudge, commands gate, humans approve.
+4. **Layouts are opinionated.** v1 ships `engineering`; community adds `data-analytics`, `product`, `chatbot`, `library`.
+5. **One brain per project, not per person.** The vault travels with the repo. Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) is its personal-research counterpart.
+
+## 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.
+
+## Extending
+
+See [`docs/extending.md`](./docs/extending.md) for adding layouts, templates, and skills, and [`docs/harnesses.md`](./docs/harnesses.md) for which coding agents projectstore runs on — what "experimental" means there, and what adding one takes.
+
+## Contributing
+
+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).
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).