projectstore-codex 0.0.1 → 0.28.1

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

@@ -0,0 +1,263 @@
+# How projectstore works under the hood
+
+The README gives the short version; this is the deep dive for the curious. Nothing
+here is required reading to use the plugin.
+
+## The write path: draft → approval → file
+
+Every create command follows the same shape:
+
+1. `scripts/draft.mjs` renders the artifact **in memory** (it never touches the
+   disk — no writes, no mkdir; declining leaves the vault byte-for-byte unchanged).
+2. The command shows you the target path + full content via `AskUserQuestion`.
+3. Only on **Yes** does the file land — and that same Yes covers the folder's
+   index. The index row is not appended: the command regenerates the folder's
+   managed table through the core (`reconcile --write --only indexes=<folder>`),
+   so the row arrives in canonical order, the file is replaced atomically, and
+   your own prose around the table is preserved. One consequence worth knowing:
+   the regeneration rewrites the whole table, so creating one artifact can also
+   repair a stale row for another.
+
+**Who holds the pen.** Content and the gate never delegate: the session's main
+agent composes the artifact (it holds the conversation the artifact captures)
+and answers to you at the approval gate. What *can* delegate is everything after
+"yes" — for the long ceremonies (a story close, a multi-target reconcile) the
+command hands execution to the `clerk` agent, which copies the approved content
+from a scratch file (never re-emitting it through a model — fidelity mechanical,
+proven per write by a byte-level diff), runs reconcile and doctor, and returns a one-line report instead
+of pages of tool output. The clerk composes nothing, decides nothing, and asks
+nothing; the advisors (critic, planner, reviewer, librarian, archaeologist)
+stay read-only.
+
+Frontmatter scalars are rendered through a JSON-escaping form (`{{title_json}}`),
+so titles containing `"` or `:` cannot corrupt the YAML. Slugs transliterate
+Cyrillic (`Кэширование запросов` → `keshirovanie-zaprosov`) and never come out
+empty.
+
+## Sessions: how parallel Claude instances coexist
+
+Each Claude Code session registers itself in the vault under its own
+`session_id`:
+
+```bash
+$ ls <vault>/.projectstore/sessions/
+d9149e0d-9169-43ef-b2c6-3e005a00e133.json   # session A — plugin dev
+f05e61c5-f809-46e1-aa3e-b7c3366bc723.json   # session B — feature work
+
+$ cat <vault>/.projectstore/sessions/f05e61c5….json
+{
+  "id":           "f05e61c5-f809-46e1-aa3e-b7c3366bc723",
+  "project_root": "/Users/me/projects/myapp",
+  "started_at":   "2026-05-19T13:35:36Z",
+  "recent_activity": [
+    { "path": "epics/WEB-101/epic.md", "tool": "Edit",  "at": "…" },
+    { "path": "epics/WEB-101/stories/001-oidc-flow.md", "tool": "Write", "at": "…" }
+  ]
+}
+```
+
+When another session starts, SessionStart sees fresh sibling files (mtime < 30
+min) and warns the new agent:
+
+> ⚠️ Multi-session warning — 1 other projectstore session active on this vault.
+> Run `/projectstore:search <topic>` before creating new artifacts.
+
+Create commands additionally re-check file existence right before writing, so two
+sessions can't silently overwrite each other's new artifact.
+
+**The status line is stricter still**: it renders from a *per-session* pointer
+(`<project>/.projectstore/state/sessions/<session_id>.json`, written by the
+PreToolUse hook with denormalized titles) and performs **zero cross-session and
+zero vault reads**. 2–6 parallel sessions each see exactly their own epic/story;
+a fresh session gets a localized "no epic or story in this session yet" line; a
+corrupt pointer shows an error marker, never a false "no work". The renderer also
+drops a `.last-render.json` breadcrumb so `doctor` can detect session-id
+divergence between the status line process and the hooks.
+
+## Surviving `/compact`
+
+Continuity across a compaction is delivered by **SessionStart**, not by
+PreCompact — and that is a correction, not a design flourish. PreCompact has no
+model-facing channel: it accepts a top-level `systemMessage` and nothing else,
+so for its whole life the hook assembled a rich packet, printed a red *"Hook
+JSON output validation failed"*, and reached nobody. Worse, the invalid field
+sank the whole object, so the one line PreCompact *does* support never landed
+either.
+
+So the two hooks now split the work by what each can actually do.
+
+PreCompact prints one line, for you:
+
+```
+PreCompact [...pre-compact.mjs] completed successfully: {
+  "systemMessage": "projectstore: compacting — vault myapp-vault,
+                    in flight: `epics/WEB-101/epic.md`,
+                    orientation and this session's recent files return
+                    at session start"
+}
+```
+
+That last clause is conditional on purpose. It appears only when the compaction
+is **manual** and `auto_inject` is on — the two things the hook can check at the
+moment it speaks. On an automatic compaction the plugin makes no claim that
+SessionStart fires at all, and under `auto_inject: false` the claim would be
+flatly false, so the line offers `/projectstore:status` instead. The
+recent-files half needs one more condition — a nonempty activity log — because
+an empty one renders no continuity section at all.
+
+SessionStart then fires with `source: "compact"` and renders a **Where this
+session left off** block above the derived-views section: up to five vault files
+the previous conversation touched, newest first, plus the newest structured
+write as the in-flight artifact. Both hooks resolve that artifact through one
+shared function, so the compaction line and the section that follows cannot name
+different files seconds apart.
+
+(Fine-grained "where exactly was my cursor" resume is the job of your task list
+and `git status`; the vault answers "where were we going".)
+
+## The status line composition trick
+
+`statusLine` in Claude Code is a single slot, not plugin-declarable, and read
+once when the session starts. So `/projectstore:statusline on` runs the
+install verb, which points the project's `.claude/settings.local.json` at a
+launcher it writes (provenance-stamped) at `.projectstore/state/claude-code/statusline.mjs`;
+the SessionStart hook keeps an existing entry current across updates and
+never creates one. Pointing
+it straight at the plugin would pin a versioned cache path
+(`…/projectstore/<version>/scripts/statusline.mjs`) and render the version
+installed at the *previous* session start — every update arrived a restart late.
+The launcher's path never changes, and it resolves the installed plugin from
+Claude Code's own registry on each render. The script then **composes** instead of
+clobbering: it re-runs whatever base statusLine command you already had (e.g.
+oh-my-claudecode's HUD, taken from the project's `.claude/settings.json` if it
+has one, else `~/.claude/settings.json`), prints its output
+verbatim, and adds one `[PS#version] 📚 …` line above it (`statusline.position`:
+`above`/`below`). With no base command it renders a standalone line.
+
+## Doctor and reconcile: the trust layer
+
+The vault's guarantees used to depend on everyone using the gated commands —
+but agents (and humans) hand-edit markdown, because it's the path of least
+resistance. v0.13 makes that safe instead of forbidden:
+
+- **`doctor`** is a deterministic, no-LLM check engine (`scripts/doctor.mjs`).
+  `--install` verifies the wiring (config, vault path, hooks firing, statusline,
+  agents block, leftover agent copies, gitignore, marketplace auto-update);
+  `--vault` verifies content consistency (status ↔ board ↔ indexes, acceptance
+  boxes, dead and ambiguous wiki/relative links — resolved by the same shared
+  resolver the link graph uses, so the two can never disagree about a body
+  link — `code_refs`,
+  code-map and graph staleness). A cheap
+  subset runs at session start and prints one line only when something is wrong.
+- **`reconcile`** rebuilds every generated view (kanban, folder indexes,
+  code-map, the link graph) from the vault — the repair partner. Idempotent: a clean vault
+  yields zero changes. Since v0.19 reconcile applies the write itself
+  (`--write`): each approved target is recomputed from the vault state at
+  write time and replaced atomically, so a stale preview is never what lands;
+  `--write` is also a sanctioned headless entry point (cron/CI repair job).
+- A throttled PreToolUse **nudge** fires when vault files are edited directly:
+  "run reconcile afterwards so the derived views stay in sync" (disable with
+  `"guard": "off"` in `projectstore.json`).
+- A once-per-session **entry reminder** fires on PostToolUse when a session has
+  written to three or more distinct *source* files and no story is `in-progress`:
+  "open it in the vault before going further". PostToolUse, not PreToolUse, so
+  declined edits are not counted as work that happened; `Stop` is the fallback
+  carrier for a session that delegates all its writing to subagents and then
+  answers without a tool call of its own. Subagent writes count toward the score
+  but never receive the reminder — a subagent cannot open a story. A session
+  launched with `--agent` carries an agent identity on every call and is
+  therefore never reminded either; for those sessions `doctor`'s
+  `work-without-story` is the only coverage. The same
+  `"guard": "off"` silences it, and silences both nudges together. Firings are
+  appended to `.projectstore/state/entry-log.jsonl` (machine-local, since
+  `.claude/` is gitignored) so `doctor` can report whether the prompt was ever
+  delivered — a mechanism that cannot say whether it worked is indistinguishable
+  from one that does not.
+- A **session-name offer** fires on PreToolUse once a session's vault work has
+  settled on an anchor — see below. Same `"guard": "off"` switch, same log, and
+  its records carry `kind: "name-offer"` so `doctor`'s reminder count does not
+  quietly absorb them.
+- `doctor` carries the after-the-fact half: **work-without-story** warns when the
+  project tree is dirty and no story is in progress. It is the only seam that
+  sees Bash-mediated writes, which bypass hook path extraction entirely.
+
+The division of labor: deterministic checks catch the mechanical 90% for free;
+the LLM critic (`/projectstore:review`) is saved for the judgment calls.
+
+## Naming a session after the work it settled on
+
+A Claude Code session has a name, and it is an **address**: live peers route to
+each other by it, which is why names are arbitrated for uniqueness across a
+machine. So a session named after its work is addressable by unit of work.
+
+No plugin can set that name. The authoritative value lives in the session
+process's memory behind no reachable API — writing the registry file or the
+transcript record reaches neither the tab nor the arbitration, and only
+desynchronises the three surfaces from each other. What a plugin can do is
+compose the right name and **offer** it:
+
+```
+projectstore: this session looks like "ps-agents-statusline-v2" — /rename ps-agents-statusline-v2
+```
+
+The whole design question is **when to speak**, because an offer is an
+interruption. Replaying nine recorded sessions, the obvious rule — offer on every
+epic/story change — fires **137 times, 37 in the worst session**. Work moves
+between a story, its epic and a sibling many times an hour; that motion is not a
+change of subject.
+
+What is stable is the **anchor**: the cluster a session's writes settle on. Seven
+of nine sessions had a dominant epic holding 62–100% of their epic writes. So:
+
+- every vault write maps to one anchor key — `epic:<ID>` for anything under an
+  epic, or the document itself for an ADR, spec or research note (two of the nine
+  sessions touched no epic at all, and an epic-only rule leaves those permanently
+  nameless);
+- an anchor **settles** at five writes and is offered;
+- a challenger takes over — and is offered — only at a **ten-write lead**;
+- the name is `<epic-id>-<its most-written story>`, or the document's slug;
+  kebab-case, 48 characters, cut on a word boundary.
+
+That is **12 offers across nine sessions, at most two in any one**, and six
+sessions naming themselves exactly once. Re-offering is deliberate: in three
+sessions the anchor moved, and the shape is a session that decides in a document
+and then builds in an epic — a name that does not follow that is a name for the
+first hour only.
+
+Only **write-family calls by the main agent** count. A review session that greps
+thirty files has not done work worth naming, and a subagent shares the session id
+but cannot accept a name. Neither gate is visible in the fixtures — every
+recorded session is an authoring session — so both are pinned by their own drives
+instead.
+
+If a live peer already holds the name it is offered as `-2`, then `-3`; a third
+collision means the name is not discriminating and nothing is said. And a name
+you chose yourself is never overwritten — but note that a session usually
+*arrives* with a harness-assigned name, so "not the name we offered" is not
+enough to infer choice: the plugin treats a name as yours only after it has made
+at least one offer of its own.
+
+**The known blind spot**: vault writes made through Bash never reach this seam,
+because the input is tool-call path extraction. The consequence that matters is
+not a missing name but a **wrong** one — if the bulk of a session's work went
+through scripts, the anchor is computed from the visible minority. And the gap is
+correlated with plugin-idiomatic behaviour: the more work goes through
+`/projectstore:*` and `reconcile`, the less nameable the session becomes.
+
+The rule is a pure fold in `lib.mjs` with no clock and no disk, so the fixture
+replay and the live hook run one implementation. Its tallies are files that grow
+by one byte — the count is the file size — because the shared session-state file
+is an unguarded read-modify-write, and a tally incremented on every vault write
+would eventually truncate the ADR-006 statusline pointer out from under an
+unrelated feature.
+
+## The epic ↔ code mapping
+
+Epics and stories carry a `code_refs` frontmatter list — the paths that feature
+actually owns in the codebase (`["src/auth/", "adapters/csv/"]`). The
+`/projectstore:codemap` command is the only writer (`codemap set`), the
+`planner` agent reads them to keep new epics consistent with how old ones
+landed, the `reviewer` proposes updates when a story completes, and
+`code-map.md` is the generated overview. Doctor checks refs status-aware:
+`planned` work may point at code that doesn't exist yet; `in-progress`/`done`
+refs must resolve.

package/node_modules/projectstore/docs/images/loop-light.svg

@@ -0,0 +1,94 @@
+<svg width="960" height="470" viewBox="0 0 960 470" fill="none" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif">
+  <defs>
+    <marker id="lab" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#6B84AD"/>
+    </marker>
+    <marker id="lar" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#E11D48"/>
+    </marker>
+    <marker id="lag" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#059669"/>
+    </marker>
+  </defs>
+
+  <rect width="960" height="470" rx="18" fill="#FFFFFF"/>
+  <rect x="1" y="1" width="958" height="468" rx="17" stroke="#E2E8F0"/>
+
+  <text x="44" y="48" fill="#94A3B8" font-size="11" letter-spacing="3">DECIDE</text>
+  <text x="104" y="218" fill="#94A3B8" font-size="11" letter-spacing="3">BUILD</text>
+
+  <!-- ── lane 1: decide ─────────────────────────────────────────── -->
+  <rect x="44" y="70" width="104" height="64" rx="11" fill="#F1F5F9" stroke="#CBD5E1"/>
+  <text x="96" y="97" fill="#0F172A" font-size="15" font-weight="600" text-anchor="middle">Task</text>
+  <text x="96" y="117" fill="#64748B" font-size="11" text-anchor="middle">from you</text>
+
+  <path d="M152 102 L188 102" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+
+  <rect x="192" y="70" width="232" height="64" rx="11" fill="#F1F5F9" stroke="#CBD5E1"/>
+  <text x="308" y="97" fill="#0F172A" font-size="15" font-weight="600" text-anchor="middle">ADR · Spec · Epic · Story</text>
+  <text x="308" y="117" fill="#64748B" font-size="11" text-anchor="middle">the why, on disk</text>
+
+  <path d="M428 102 L462 102" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+
+  <rect x="492" y="44" width="64" height="18" rx="9" fill="#E11D48" fill-opacity="0.10"/>
+  <text x="524" y="57" fill="#E11D48" font-size="10" letter-spacing="1.5" text-anchor="middle">VERIFY</text>
+  <rect x="466" y="70" width="152" height="64" rx="11" fill="#FFF1F2" stroke="#E11D48"/>
+  <text x="542" y="97" fill="#BE123C" font-size="15" font-weight="600" text-anchor="middle">critic</text>
+  <text x="542" y="117" fill="#B25B70" font-size="11" text-anchor="middle">fresh context, adversarial</text>
+
+  <path d="M486 68 C 462 40, 442 40, 416 66" stroke="#E11D48" stroke-width="1.4" stroke-dasharray="4 4" marker-end="url(#lar)"/>
+  <text x="446" y="34" fill="#E11D48" font-size="11" text-anchor="middle">revise</text>
+
+  <path d="M622 102 L656 102" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+
+  <rect x="660" y="70" width="150" height="64" rx="11" fill="#F1F5F9" stroke="#CBD5E1"/>
+  <text x="735" y="97" fill="#0F172A" font-size="15" font-weight="600" text-anchor="middle">Backlog</text>
+  <text x="735" y="117" fill="#64748B" font-size="11" text-anchor="middle">kanban.md — ready</text>
+
+  <!-- hand-off to the build lane (lane 2 sits 60px right: a gantt cascade,
+       and the return arrow below gets a clear left margin) -->
+  <path d="M735 138 C 735 192, 210 168, 164 234" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+  <text x="470" y="163" fill="#64748B" font-size="12" text-anchor="middle">an agent picks it up</text>
+
+  <!-- ── lane 2: build ──────────────────────────────────────────── -->
+  <rect x="104" y="240" width="116" height="64" rx="11" fill="#F1F5F9" stroke="#CBD5E1"/>
+  <text x="162" y="267" fill="#0F172A" font-size="15" font-weight="600" text-anchor="middle">Story</text>
+  <text x="162" y="287" fill="#64748B" font-size="11" text-anchor="middle">in-progress</text>
+
+  <path d="M224 272 L258 272" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+
+  <rect x="262" y="240" width="136" height="64" rx="11" fill="#F5F3FF" stroke="#7C3AED"/>
+  <text x="330" y="267" fill="#6D28D9" font-size="15" font-weight="600" text-anchor="middle">planner</text>
+  <text x="330" y="287" fill="#8B7BB5" font-size="11" text-anchor="middle">where in the code</text>
+
+  <path d="M402 272 L436 272" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+
+  <rect x="440" y="240" width="140" height="64" rx="11" fill="#F1F5F9" stroke="#CBD5E1"/>
+  <text x="510" y="267" fill="#0F172A" font-size="15" font-weight="600" text-anchor="middle">Implement</text>
+  <text x="510" y="287" fill="#64748B" font-size="11" text-anchor="middle">code + tests</text>
+
+  <path d="M584 272 L618 272" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+
+  <rect x="668" y="214" width="64" height="18" rx="9" fill="#E11D48" fill-opacity="0.10"/>
+  <text x="700" y="227" fill="#E11D48" font-size="10" letter-spacing="1.5" text-anchor="middle">VERIFY</text>
+  <rect x="622" y="240" width="156" height="64" rx="11" fill="#FFF1F2" stroke="#E11D48"/>
+  <text x="700" y="267" fill="#BE123C" font-size="15" font-weight="600" text-anchor="middle">reviewer</text>
+  <text x="700" y="287" fill="#B25B70" font-size="11" text-anchor="middle">evidence per criterion</text>
+
+  <path d="M638 238 C 616 212, 600 212, 576 236" stroke="#E11D48" stroke-width="1.4" stroke-dasharray="4 4" marker-end="url(#lar)"/>
+  <text x="606" y="206" fill="#E11D48" font-size="11" text-anchor="middle">fix</text>
+
+  <path d="M782 272 L816 272" stroke="#059669" stroke-width="1.6" marker-end="url(#lag)"/>
+
+  <rect x="820" y="240" width="126" height="64" rx="11" fill="#ECFDF5" stroke="#059669"/>
+  <text x="883" y="267" fill="#047857" font-size="15" font-weight="600" text-anchor="middle">Done ✓</text>
+  <text x="883" y="287" fill="#5F9E86" font-size="11" text-anchor="middle">criteria met</text>
+
+  <!-- ── the feedback that closes the loop ──────────────────────── -->
+  <path d="M883 308 C 883 344, 856 364, 776 370" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+  <rect x="250" y="352" width="520" height="36" rx="18" fill="#F1F5F9" stroke="#E2E8F0"/>
+  <text x="510" y="375" fill="#475569" font-size="12.5" text-anchor="middle">kanban · graph · code-map regenerate — the next session starts oriented</text>
+  <path d="M246 370 C 90 370, 48 290, 76 142" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#lab)"/>
+
+  <text x="480" y="444" fill="#94A3B8" font-size="12.5" text-anchor="middle">gather context → act → verify — the agentic loop, run over the project itself, not just the code</text>
+</svg>

package/node_modules/projectstore/docs/images/loop.svg

@@ -0,0 +1,93 @@
+<svg width="960" height="470" viewBox="0 0 960 470" fill="none" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif">
+  <defs>
+    <marker id="ab" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#5B7BB4"/>
+    </marker>
+    <marker id="ar" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#F43F5E"/>
+    </marker>
+    <marker id="ag" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#10B981"/>
+    </marker>
+  </defs>
+
+  <rect width="960" height="470" rx="18" fill="#0C1322"/>
+  <rect x="1" y="1" width="958" height="468" rx="17" stroke="#1E2A44"/>
+
+  <text x="44" y="48" fill="#64748B" font-size="11" letter-spacing="3">DECIDE</text>
+  <text x="104" y="218" fill="#64748B" font-size="11" letter-spacing="3">BUILD</text>
+
+  <!-- ── lane 1: decide ─────────────────────────────────────────── -->
+  <rect x="44" y="70" width="104" height="64" rx="11" fill="#131F36" stroke="#2C3E5F"/>
+  <text x="96" y="97" fill="#E2E8F0" font-size="15" font-weight="600" text-anchor="middle">Task</text>
+  <text x="96" y="117" fill="#7C8DB0" font-size="11" text-anchor="middle">from you</text>
+
+  <path d="M152 102 L188 102" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+
+  <rect x="192" y="70" width="232" height="64" rx="11" fill="#131F36" stroke="#2C3E5F"/>
+  <text x="308" y="97" fill="#E2E8F0" font-size="15" font-weight="600" text-anchor="middle">ADR · Spec · Epic · Story</text>
+  <text x="308" y="117" fill="#7C8DB0" font-size="11" text-anchor="middle">the why, on disk</text>
+
+  <path d="M428 102 L462 102" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+
+  <rect x="492" y="44" width="64" height="18" rx="9" fill="#F43F5E" fill-opacity="0.14"/>
+  <text x="524" y="57" fill="#FB7185" font-size="10" letter-spacing="1.5" text-anchor="middle">VERIFY</text>
+  <rect x="466" y="70" width="152" height="64" rx="11" fill="#2A1220" stroke="#F43F5E"/>
+  <text x="542" y="97" fill="#FDA4AF" font-size="15" font-weight="600" text-anchor="middle">critic</text>
+  <text x="542" y="117" fill="#B07A8C" font-size="11" text-anchor="middle">fresh context, adversarial</text>
+
+  <path d="M486 68 C 462 40, 442 40, 416 66" stroke="#F43F5E" stroke-width="1.4" stroke-dasharray="4 4" marker-end="url(#ar)"/>
+  <text x="446" y="34" fill="#FB7185" font-size="11" text-anchor="middle">revise</text>
+
+  <path d="M622 102 L656 102" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+
+  <rect x="660" y="70" width="150" height="64" rx="11" fill="#131F36" stroke="#2C3E5F"/>
+  <text x="735" y="97" fill="#E2E8F0" font-size="15" font-weight="600" text-anchor="middle">Backlog</text>
+  <text x="735" y="117" fill="#7C8DB0" font-size="11" text-anchor="middle">kanban.md — ready</text>
+
+  <!-- hand-off to the build lane -->
+  <path d="M735 138 C 735 192, 210 168, 164 234" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+  <text x="470" y="163" fill="#7C8DB0" font-size="12" text-anchor="middle">an agent picks it up</text>
+
+  <!-- ── lane 2: build ──────────────────────────────────────────── -->
+  <rect x="104" y="240" width="116" height="64" rx="11" fill="#131F36" stroke="#2C3E5F"/>
+  <text x="162" y="267" fill="#E2E8F0" font-size="15" font-weight="600" text-anchor="middle">Story</text>
+  <text x="162" y="287" fill="#7C8DB0" font-size="11" text-anchor="middle">in-progress</text>
+
+  <path d="M224 272 L258 272" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+
+  <rect x="262" y="240" width="136" height="64" rx="11" fill="#1D1733" stroke="#8B5CF6"/>
+  <text x="330" y="267" fill="#C4B5FD" font-size="15" font-weight="600" text-anchor="middle">planner</text>
+  <text x="330" y="287" fill="#9D8FC7" font-size="11" text-anchor="middle">where in the code</text>
+
+  <path d="M402 272 L436 272" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+
+  <rect x="440" y="240" width="140" height="64" rx="11" fill="#131F36" stroke="#2C3E5F"/>
+  <text x="510" y="267" fill="#E2E8F0" font-size="15" font-weight="600" text-anchor="middle">Implement</text>
+  <text x="510" y="287" fill="#7C8DB0" font-size="11" text-anchor="middle">code + tests</text>
+
+  <path d="M584 272 L618 272" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+
+  <rect x="668" y="214" width="64" height="18" rx="9" fill="#F43F5E" fill-opacity="0.14"/>
+  <text x="700" y="227" fill="#FB7185" font-size="10" letter-spacing="1.5" text-anchor="middle">VERIFY</text>
+  <rect x="622" y="240" width="156" height="64" rx="11" fill="#2A1220" stroke="#F43F5E"/>
+  <text x="700" y="267" fill="#FDA4AF" font-size="15" font-weight="600" text-anchor="middle">reviewer</text>
+  <text x="700" y="287" fill="#B07A8C" font-size="11" text-anchor="middle">evidence per criterion</text>
+
+  <path d="M638 238 C 616 212, 600 212, 576 236" stroke="#F43F5E" stroke-width="1.4" stroke-dasharray="4 4" marker-end="url(#ar)"/>
+  <text x="606" y="206" fill="#FB7185" font-size="11" text-anchor="middle">fix</text>
+
+  <path d="M782 272 L816 272" stroke="#10B981" stroke-width="1.6" marker-end="url(#ag)"/>
+
+  <rect x="820" y="240" width="126" height="64" rx="11" fill="#0C2A1E" stroke="#10B981"/>
+  <text x="883" y="267" fill="#6EE7B7" font-size="15" font-weight="600" text-anchor="middle">Done ✓</text>
+  <text x="883" y="287" fill="#79A893" font-size="11" text-anchor="middle">criteria met</text>
+
+  <!-- ── the feedback that closes the loop ──────────────────────── -->
+  <path d="M883 308 C 883 344, 856 364, 776 370" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+  <rect x="250" y="352" width="520" height="36" rx="18" fill="#101B31" stroke="#24344F"/>
+  <text x="510" y="375" fill="#9FB0CE" font-size="12.5" text-anchor="middle">kanban · graph · code-map regenerate — the next session starts oriented</text>
+  <path d="M246 370 C 100 370, 56 292, 84 142" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#ab)"/>
+
+  <text x="480" y="444" fill="#5F6E8C" font-size="12.5" text-anchor="middle">gather context → act → verify — the agentic loop, run over the project itself, not just the code</text>
+</svg>

package/node_modules/projectstore/docs/images/team-light.svg

@@ -0,0 +1,79 @@
+<svg width="960" height="430" viewBox="0 0 960 430" fill="none" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif">
+  <defs>
+    <marker id="ltb" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#6B84AD"/>
+    </marker>
+  </defs>
+
+  <rect width="960" height="430" rx="18" fill="#FFFFFF"/>
+  <rect x="1" y="1" width="958" height="428" rx="17" stroke="#E2E8F0"/>
+
+  <!-- ── the people ─────────────────────────────────────────────── -->
+  <g>
+    <rect x="44" y="56" width="232" height="76" rx="12" fill="#F8FAFC" stroke="#E2E8F0"/>
+    <circle cx="78" cy="94" r="15" fill="#E2E8F0" stroke="#CBD5E1"/>
+    <circle cx="78" cy="90" r="4.5" fill="#64748B"/>
+    <path d="M71 103 a7 5.5 0 0 1 14 0" fill="#64748B"/>
+    <text x="106" y="89" fill="#0F172A" font-size="15" font-weight="600">Dev A</text>
+    <text x="106" y="109" fill="#64748B" font-size="11.5">Claude Code + projectstore</text>
+  </g>
+  <g>
+    <rect x="44" y="166" width="232" height="76" rx="12" fill="#F8FAFC" stroke="#E2E8F0"/>
+    <circle cx="78" cy="204" r="15" fill="#E2E8F0" stroke="#CBD5E1"/>
+    <circle cx="78" cy="200" r="4.5" fill="#64748B"/>
+    <path d="M71 213 a7 5.5 0 0 1 14 0" fill="#64748B"/>
+    <text x="106" y="199" fill="#0F172A" font-size="15" font-weight="600">Dev B</text>
+    <text x="106" y="219" fill="#64748B" font-size="11.5">Claude Code + projectstore</text>
+  </g>
+  <g>
+    <rect x="44" y="276" width="232" height="76" rx="12" fill="#F8FAFC" stroke="#E2E8F0"/>
+    <circle cx="78" cy="314" r="15" fill="#E2E8F0" stroke="#CBD5E1"/>
+    <circle cx="78" cy="310" r="4.5" fill="#64748B"/>
+    <path d="M71 323 a7 5.5 0 0 1 14 0" fill="#64748B"/>
+    <text x="106" y="309" fill="#0F172A" font-size="15" font-weight="600">Dev C</text>
+    <text x="106" y="329" fill="#64748B" font-size="11.5">reviews on GitHub or Obsidian</text>
+  </g>
+
+  <!-- bind arrows -->
+  <path d="M280 94 C 320 94, 330 106, 356 116" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#ltb)"/>
+  <path d="M280 204 L356 206" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#ltb)"/>
+  <path d="M280 314 C 320 314, 330 302, 356 294" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#ltb)"/>
+  <text x="308" y="196" fill="#64748B" font-size="10.5" text-anchor="middle">bind</text>
+
+  <!-- ── the vault ──────────────────────────────────────────────── -->
+  <rect x="360" y="52" width="252" height="310" rx="14" fill="#EFF6FF" stroke="#3B82F6"/>
+  <text x="486" y="86" fill="#1D4ED8" font-size="16" font-weight="600" text-anchor="middle">The vault</text>
+  <text x="486" y="106" fill="#64748B" font-size="11" text-anchor="middle">its own git repo · plain markdown</text>
+  <path d="M384 122 L588 122" stroke="#DBEAFE"/>
+  <text x="384" y="150" fill="#334155" font-size="12.5">adr/ — decisions, with dates</text>
+  <text x="384" y="177" fill="#334155" font-size="12.5">specs/ — the normative how</text>
+  <text x="384" y="204" fill="#334155" font-size="12.5">epics/ · stories/ — the backlog</text>
+  <text x="384" y="231" fill="#334155" font-size="12.5">kanban.md — the board</text>
+  <text x="384" y="258" fill="#334155" font-size="12.5">graph.md — every link, typed</text>
+  <text x="384" y="285" fill="#334155" font-size="12.5">code-map.md — epic ↔ code</text>
+  <text x="384" y="330" fill="#94A3B8" font-size="11">every write previewed and</text>
+  <text x="384" y="346" fill="#94A3B8" font-size="11">approved — by whoever binds</text>
+
+  <!-- ── the remote ─────────────────────────────────────────────── -->
+  <path d="M616 128 L696 128" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#ltb)"/>
+  <text x="656" y="118" fill="#64748B" font-size="10.5" text-anchor="middle">push</text>
+  <path d="M696 172 L616 172" stroke="#6B84AD" stroke-width="1.6" marker-end="url(#ltb)"/>
+  <text x="656" y="192" fill="#64748B" font-size="10.5" text-anchor="middle">review &amp; pull</text>
+
+  <rect x="700" y="88" width="216" height="132" rx="12" fill="#F8FAFC" stroke="#CBD5E1"/>
+  <text x="808" y="118" fill="#0F172A" font-size="15" font-weight="600" text-anchor="middle">git remote</text>
+  <text x="808" y="144" fill="#64748B" font-size="11.5" text-anchor="middle">push / pull</text>
+  <text x="808" y="164" fill="#64748B" font-size="11.5" text-anchor="middle">ADRs &amp; specs reviewed</text>
+  <text x="808" y="182" fill="#64748B" font-size="11.5" text-anchor="middle">as merge requests</text>
+
+  <text x="806" y="252" fill="#94A3B8" font-size="11.5" text-anchor="middle">the why gets reviewed,</text>
+  <text x="806" y="269" fill="#94A3B8" font-size="11.5" text-anchor="middle">not just the code</text>
+
+  <!-- ── the guarantees ─────────────────────────────────────────── -->
+  <rect x="284" y="384" width="86" height="26" rx="13" fill="#F1F5F9" stroke="#E2E8F0"/>
+  <text x="327" y="401" fill="#64748B" font-size="11.5" text-anchor="middle">no server</text>
+  <rect x="382" y="384" width="122" height="26" rx="13" fill="#F1F5F9" stroke="#E2E8F0"/>
+  <text x="443" y="401" fill="#64748B" font-size="11.5" text-anchor="middle">plain markdown</text>
+  <rect x="516" y="384" width="160" height="26" rx="13" fill="#F1F5F9" stroke="#E2E8F0"/>
+  <text x="596" y="401" fill="#64748B" font-size="11.5" text-anchor="middle">any model can read it</text>
+</svg>

package/node_modules/projectstore/docs/images/team.svg

@@ -0,0 +1,79 @@
+<svg width="960" height="430" viewBox="0 0 960 430" fill="none" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif">
+  <defs>
+    <marker id="tb" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#5B7BB4"/>
+    </marker>
+  </defs>
+
+  <rect width="960" height="430" rx="18" fill="#0C1322"/>
+  <rect x="1" y="1" width="958" height="428" rx="17" stroke="#1E2A44"/>
+
+  <!-- ── the people ─────────────────────────────────────────────── -->
+  <g>
+    <rect x="44" y="56" width="232" height="76" rx="12" fill="#101B31" stroke="#24344F"/>
+    <circle cx="78" cy="94" r="15" fill="#1B2A45" stroke="#3D5378"/>
+    <circle cx="78" cy="90" r="4.5" fill="#93A6C8"/>
+    <path d="M71 103 a7 5.5 0 0 1 14 0" fill="#93A6C8"/>
+    <text x="106" y="89" fill="#E2E8F0" font-size="15" font-weight="600">Dev A</text>
+    <text x="106" y="109" fill="#7C8DB0" font-size="11.5">Claude Code + projectstore</text>
+  </g>
+  <g>
+    <rect x="44" y="166" width="232" height="76" rx="12" fill="#101B31" stroke="#24344F"/>
+    <circle cx="78" cy="204" r="15" fill="#1B2A45" stroke="#3D5378"/>
+    <circle cx="78" cy="200" r="4.5" fill="#93A6C8"/>
+    <path d="M71 213 a7 5.5 0 0 1 14 0" fill="#93A6C8"/>
+    <text x="106" y="199" fill="#E2E8F0" font-size="15" font-weight="600">Dev B</text>
+    <text x="106" y="219" fill="#7C8DB0" font-size="11.5">Claude Code + projectstore</text>
+  </g>
+  <g>
+    <rect x="44" y="276" width="232" height="76" rx="12" fill="#101B31" stroke="#24344F"/>
+    <circle cx="78" cy="314" r="15" fill="#1B2A45" stroke="#3D5378"/>
+    <circle cx="78" cy="310" r="4.5" fill="#93A6C8"/>
+    <path d="M71 323 a7 5.5 0 0 1 14 0" fill="#93A6C8"/>
+    <text x="106" y="309" fill="#E2E8F0" font-size="15" font-weight="600">Dev C</text>
+    <text x="106" y="329" fill="#7C8DB0" font-size="11.5">reviews on GitHub or Obsidian</text>
+  </g>
+
+  <!-- bind arrows -->
+  <path d="M280 94 C 320 94, 330 106, 356 116" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#tb)"/>
+  <path d="M280 204 L356 206" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#tb)"/>
+  <path d="M280 314 C 320 314, 330 302, 356 294" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#tb)"/>
+  <text x="308" y="196" fill="#7C8DB0" font-size="10.5" text-anchor="middle">bind</text>
+
+  <!-- ── the vault ──────────────────────────────────────────────── -->
+  <rect x="360" y="52" width="252" height="310" rx="14" fill="#0F2038" stroke="#3B82F6"/>
+  <text x="486" y="86" fill="#93C5FD" font-size="16" font-weight="600" text-anchor="middle">The vault</text>
+  <text x="486" y="106" fill="#7C8DB0" font-size="11" text-anchor="middle">its own git repo · plain markdown</text>
+  <path d="M384 122 L588 122" stroke="#1E3355"/>
+  <text x="384" y="150" fill="#A9B8D4" font-size="12.5">adr/ — decisions, with dates</text>
+  <text x="384" y="177" fill="#A9B8D4" font-size="12.5">specs/ — the normative how</text>
+  <text x="384" y="204" fill="#A9B8D4" font-size="12.5">epics/ · stories/ — the backlog</text>
+  <text x="384" y="231" fill="#A9B8D4" font-size="12.5">kanban.md — the board</text>
+  <text x="384" y="258" fill="#A9B8D4" font-size="12.5">graph.md — every link, typed</text>
+  <text x="384" y="285" fill="#A9B8D4" font-size="12.5">code-map.md — epic ↔ code</text>
+  <text x="384" y="330" fill="#64748B" font-size="11">every write previewed and</text>
+  <text x="384" y="346" fill="#64748B" font-size="11">approved — by whoever binds</text>
+
+  <!-- ── the remote ─────────────────────────────────────────────── -->
+  <path d="M616 128 L696 128" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#tb)"/>
+  <text x="656" y="118" fill="#7C8DB0" font-size="10.5" text-anchor="middle">push</text>
+  <path d="M696 172 L616 172" stroke="#5B7BB4" stroke-width="1.6" marker-end="url(#tb)"/>
+  <text x="656" y="192" fill="#7C8DB0" font-size="10.5" text-anchor="middle">review &amp; pull</text>
+
+  <rect x="700" y="88" width="216" height="132" rx="12" fill="#131F36" stroke="#2C3E5F"/>
+  <text x="808" y="118" fill="#E2E8F0" font-size="15" font-weight="600" text-anchor="middle">git remote</text>
+  <text x="808" y="144" fill="#7C8DB0" font-size="11.5" text-anchor="middle">push / pull</text>
+  <text x="808" y="164" fill="#7C8DB0" font-size="11.5" text-anchor="middle">ADRs &amp; specs reviewed</text>
+  <text x="808" y="182" fill="#7C8DB0" font-size="11.5" text-anchor="middle">as merge requests</text>
+
+  <text x="806" y="252" fill="#64748B" font-size="11.5" text-anchor="middle">the why gets reviewed,</text>
+  <text x="806" y="269" fill="#64748B" font-size="11.5" text-anchor="middle">not just the code</text>
+
+  <!-- ── the guarantees ─────────────────────────────────────────── -->
+  <rect x="284" y="384" width="86" height="26" rx="13" fill="#101B31" stroke="#24344F"/>
+  <text x="327" y="401" fill="#8FA1BF" font-size="11.5" text-anchor="middle">no server</text>
+  <rect x="382" y="384" width="122" height="26" rx="13" fill="#101B31" stroke="#24344F"/>
+  <text x="443" y="401" fill="#8FA1BF" font-size="11.5" text-anchor="middle">plain markdown</text>
+  <rect x="516" y="384" width="160" height="26" rx="13" fill="#101B31" stroke="#24344F"/>
+  <text x="596" y="401" fill="#8FA1BF" font-size="11.5" text-anchor="middle">any model can read it</text>
+</svg>