projectstore-codex 0.0.1 → 0.28.1

package/node_modules/projectstore/commands/story.md

@@ -0,0 +1,113 @@
+---
+description: Create a new story inside an existing epic, or run its lifecycle gates (plan / close).
+argument-hint: <epic-id> <title> [--spec SPEC-ID] | plan <story> | close <story>
+---
+
+You are managing a story: creating one, or running its lifecycle gates.
+
+**Dispatch rule** (positional-1 contract, PS-SPEC story-007): if the first
+argument is `plan` or `close` AND the second argument resolves to an existing
+story file (path, or `<epic-id>/<story-id>` searched under
+`<vault>/epics/*/stories/`), run the **Lifecycle gate flow** below. Otherwise
+this is a **create** (first argument = epic id — uppercase by convention, so
+the two cannot collide).
+
+# Create flow
+
+1. **Check config**: stop if `.projectstore/projectstore.json` missing.
+
+2. **Validate args**: epic-id (positional 1) + title (rest). If only one word, ask for the title. An optional `--spec SPEC-ID` names the covering spec — put it into the rendered draft's `specs:` list (inline flow: `specs: ["SPEC-001"]`). Under `spec_policy: required` (vault's `.projectstore.json`), remind that every story needs a covering spec before implementation starts.
+
+3. **Render draft**:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" story "$ARGUMENTS"
+   ```
+
+   The script fails if the epic folder does not exist. Surface the error and suggest `/projectstore:epic <id> "<title>"` first.
+
+4. **Preview**: path + first ~25 lines.
+
+5. **Approval** via AskUserQuestion: Yes / Edit / No.
+
+   When prompting "Edit", note that the story template has a `Decomposition` checklist — if the user wants to seed it with concrete tasks from the current conversation, regenerate with those tasks pre-filled in place of the empty checkboxes.
+
+6. **Post-approval race re-check** (Layer 1): re-run `draft.mjs story "$ARGUMENTS"` and re-read its `collision` field — an exact-name `test -e` cannot see normalized cross-era collisions (`story-006-foo.md` vs `story-foo.md`). If `collision` is non-null, surface it as a topic collision (`"<identity>" already exists as <with>`), and ask: extend the existing story, pick a different slug (`-2` is a deliberate distinct identity), or cancel. Render `warnings` entries as `⚠️` lines in the preview too.
+
+7. **On Yes** (path free): Write file.
+
+8. **Suggest next**: "Now decompose the work in the `Decomposition` section, or run `/projectstore:kanban` to refresh the board. Before implementation: `/projectstore:story plan <story>`."
+
+# Lifecycle gate flow (plan / close)
+
+1. **Resolve the story file** (second argument). Ambiguous → list candidates and ask.
+
+2. **Run the compute script** (pure — writes nothing):
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/story-section.mjs" <plan|close> "<story-path>"
+   ```
+
+   It returns `{ path, changed, notes, content }`: section inserted when
+   absent, status transition, lifecycle timestamps (`started_at` /
+   `plan_updated_at` / `closed_at` — stamped unconditionally; the
+   `lifecycle_gates` key gates checks, never data).
+
+3. **Fill the section content** in the returned `content` before preview:
+   - `plan` — write the Implementation Plan. When the story's `specs:` names a
+     covering spec, the plan is a THIN ROUTE through that spec's behavioral
+     contracts: which contracts, in what order, which files. Consult the
+     planner agent's output if one ran. Do not restate the spec.
+   - `close` — write the Final Summary (what changed / why / tests executed /
+     risks & follow-ups), and update the Acceptance Criteria checkboxes with
+     evidence suffixes: `- [x] <criterion> — evidence: <test | command | file:line>`.
+     Check a box ONLY with real evidence (reviewer output, test run, command).
+
+4. **Preview** path + notes + the changed sections. **Approval** via
+   AskUserQuestion: Yes / Edit / No.
+
+5. **Immediately before writing**, re-run the script and verify its `content`
+   (before your section edits) still matches what you previewed against — a
+   human may have edited the file in Obsidian meanwhile. On divergence:
+   re-preview, re-ask.
+
+5a. **Delegate the ceremony — enumerated case: story close** (ADR "Artifact
+   content is authored by the context-holder, the write ceremony by a clerk").
+   After the approval in step 4 and the re-check in step 5, on a `close`:
+   - Write TWO files to the session scratchpad: the **scratch** (the full final
+     content you previewed — sections filled) and the **baseline** (the script's
+     raw `content` from step 2, BEFORE your section edits). They are different
+     files with different jobs: the scratch is what gets copied to the target;
+     the baseline is what `--check` compares against. Handing `--check` the
+     scratch makes it report drift on every run.
+   - **Model (ADR-008)**: resolve it with `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" agents model clerk --json --project "${CLAUDE_PROJECT_DIR}"` and pass `result.model` as the spawn's model parameter (`null` → pass nothing).
+     Missing key, `inherit`, or unreadable config → pass nothing and let the
+     agent's own frontmatter decide; never guess a model.
+   - Capture doctor's summary line (`node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" doctor
+     --vault`, last line) — the clerk needs it as the **pre-state**: it must not
+     stop on findings that were already there and are not its own.
+   - Spawn `projectstore:clerk` **as a foreground task** (you need its report to
+     continue) with: the scratch path, the target path, the exact re-check
+     invocation (`story-section.mjs close "<story-path>" --check
+     <baseline-path>`), the derived targets (`kanban`, plus `indexes=<epic
+     folder>` when status changed), and the doctor pre-state line. On a clean
+     report (`verbatim: true`, `stopped_at: null`, doctor no worse than the
+     pre-state) skip steps 6-6b — the clerk's report is the write evidence. On a
+     stopped report: fix what diverged, then re-delegate (the resume rule: after
+     the copy, the ceremony restarts at reconcile, not at the race gate) or
+     finish the remaining steps yourself (the copy is idempotent).
+   - No clerk available → perform steps 6-6b yourself. There is no fallback
+     agent: a general-purpose writer is an unpinned procedure.
+
+6. **On Yes** (undelegated path): Write the full file. On a `plan`, finish by
+   suggesting `/projectstore:kanban` (the status changed) — 6a/6b below are the
+   close's ceremony, not the plan's.
+
+6a. **(close only) Reconcile** the touched derived targets through the core:
+   `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --write --only kanban` (add
+   `indexes=<epic folder>` when the status changed).
+
+6b. **(close only) Verify**: `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" doctor --vault` (exit 1 = findings, not failure)
+   — a close is not done while doctor got worse. Then suggest the reviewer's
+   proposed `code_refs` via `/projectstore:codemap set` (the reviewer computes it
+   from `scripts/diff-refs.mjs --since <started_at>`).

package/node_modules/projectstore/docs/extending.md

@@ -0,0 +1,172 @@
+# Extending projectstore
+
+## Adding a new artifact kind — the honest checklist
+
+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
+vault-side layout or template override):
+
+1. **Layout folder entry** — `scaffold/layouts/<name>.json` → `folders`:
+
+   ```jsonc
+   { "path": "specs", "kind": "spec", "readme": true, "numbered": true, "prefix": "SPEC-", "pad": 3 }
+   ```
+
+   Since v0.18 every kind creates **slug-only filenames** (`<slug>.md`;
+   stories keep the `story-` marker: `story-<slug>.md`) — identity lives in
+   the slug, sequence numbers are no longer allocated (ADR-010), which makes
+   concurrent creation collision-free by construction. `numbered` + `prefix`
+   + `pad` stay declared for **grandfathered** vaults: the prefix drives
+   legacy-number stripping in identity matching and the index label badge
+   (`SPEC-002` rows keep their labels; slug rows are labelled by slug).
+   `date_prefix: true` gives `YYYY-MM-DD-slug.md`. The epic folder
+   additionally accepts `story_prefix` (default `story-`) for its stories'
+   kind marker; `story_pad` remains recognized but only describes legacy
+   files.
+
+2. **Layout command entry** — the same file's `commands` array. A command
+   needs a template only if it maps to a declared folder kind (`story` maps
+   through the `epic` folder; `kanban` through the `kanban` block). Folders
+   without a command (e.g. `diagrams`) need no template.
+
+3. **Template** — `templates/en/<kind>.md.tmpl` (and `templates/ru/…`).
+   Variables filled by `scripts/draft.mjs`: `{{date}}`, `{{author}}`,
+   `{{tags}}`, `{{title}}`, `{{slug}}`, `{{id}}` (the exact machine id: the
+   slug itself; `story-<slug>` for stories), `{{epic_id}}` (stories). Use
+   `{{x_json}}` for any frontmatter scalar — it renders as a valid YAML
+   double-quoted string. Frontmatter should carry `id:` and an inline-flow
+   `external_refs: {}` (the designed home for Jira/YouTrack-style keys —
+   ADR-010); `number:` is optional display metadata, never identity. The
+   template's own frontmatter `status:` is what the index row shows at
+   creation (derived, never hardcoded), and its `date:` (or `created:`) is
+   the index row's date. Carry one of them: with neither, the date cell
+   renders empty — consistently, in both the preview and the written row —
+   but an empty date sorts first, so the kind's rows pile up at the top of
+   its index and stay there.
+
+4. **Checklist entry** — `scaffold/checklists.json`, consumed by
+   `/projectstore:review` and the `projectstore-peer-reviewer` skill. English-only by design.
+
+5. **Command prompt** — `commands/<kind>.md`, a prompt (not code) that calls
+   `node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" <kind> "$ARGUMENTS"`, previews,
+   and gates every write behind AskUserQuestion. Copy `commands/research.md`
+   for a plain kind, `commands/adr.md` for one that renders the draft's
+   `collision`/`warnings` fields and updates an index, `commands/spec.md`
+   for one with status transitions.
+
+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
+`scaffold/headings.json` — matchers accept every registered language, so a
+ru-headed file lints in an en-bound vault.
+
+## Adding a new layout
+
+A layout is a JSON file at `scaffold/layouts/<name>.json` declaring folders,
+kinds, commands, agents and (optionally) a kanban block — see
+`engineering.json` for the full shape. Every command that maps to a folder
+kind needs its template per the checklist above.
+
+## Adding a new command
+
+Create `commands/<name>.md` with frontmatter:
+
+```yaml
+---
+description: One-line summary shown in `/help`.
+argument-hint: <expected args>
+---
+```
+
+Body is a **prompt** for Claude — instructions, not code. To do real work, call
+the plugin's scripts via Bash. Always gate writes through `AskUserQuestion`
+after showing a preview. Scripts are pure compute (they never write); the
+command writes after approval — keep that split.
+
+## Adding a new skill
+
+Skills passively watch the conversation and suggest commands. Create
+`skills/<name>/SKILL.md`:
+
+```yaml
+---
+description: When [trigger condition], suggest [the relevant /projectstore:* command]. Never write to disk directly.
+---
+```
+
+The `description` field is what Claude uses to decide activation. Be specific
+about triggers, and include an Anti-patterns section.
+
+## Adding a new language
+
+Bundled: `en`, `ru`, `es`, `de`, `fr`, `zh`. To add another:
+
+Mirror `templates/en/` to `templates/<lang>/` and translate the bodies.
+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.
+
+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
+`index-header` warn while reconcile drops the same index silently; an
+unregistered `acceptance` heading is silent everywhere; an unregistered
+`implementation_plan` is misdiagnosed as "this done story has no Implementation
+Plan"; and `heading(id, lang)` falls back to English, so the lifecycle gates
+write English headings into an otherwise translated story.
+
+Constraints the deterministic scripts impose on the translation:
+
+- **Every heading must match *some* registered form.** `insertSection` guards on
+  `headingLineRe`, which accepts every registered form of every language — so a
+  heading in another locale's form is filled, not duplicated. Only a spelling
+  registered nowhere makes the gate append a second section beside it.
+- **Use the FIRST form of your language** — that is what `story-section` writes
+  when it has to insert, so agreeing with it keeps written and rendered
+  documents identical. This is a convention; the gate does not enforce it.
+- **No form may match two ids.** Keep the `acceptance` ("Acceptance Criteria")
+  and `spec_acceptance` ("Acceptance") headings distinct in your language;
+  matching is whole-line, so a prefix relationship is fine but equality is not.
+- **The folder-README index header must use the registered column names —
+  exactly those four, and no more** — and the separator row under it must stay
+  a plain `|---|---|---|---|`. Matching is end-anchored: adding a fifth column
+  of your own does not extend the managed table, it stops being one. That is
+  deliberate — an unanchored match let the regeneration rewrite your extra
+  column away. An unrecognized header is now loud in both directions: doctor
+  warns, and a creation into that folder fails its index step on stderr
+  (the artifact still lands — see the failure prose in the create commands).
+- **Inline grammars carry a keyword and a colon**: the evidence suffix on a
+  checked criterion and the `stories:` attribution on a spec acceptance item.
+  Both accept the CJK-width colon (`evidenceSuffixRe` / `storiesAttributionRe`
+  in `lib.mjs`); if your language punctuates differently, widen them there
+  rather than working around it in the template.
+
+Where two spellings are realistic (Russian `ё`/`е`, a French typographic vs
+ASCII apostrophe), register both: the first is written, all are accepted. No
+test can decide "realistic" — have someone who reads the language check it.
+
+Domain terms follow the language's practitioners, not the dictionary. `epic`
+and `story` are localized where the field localizes them (`ru` "Эпик", `es`
+"Épica") and left in English where teams say the English word (`de`, `fr`,
+`zh`). Nothing reads these table labels, so the only cost of getting it wrong
+is that the document reads like a translation.
+
+The bundled set is currently spelled out by hand in four places (the test's
+`LOCALES`, the registry's `_description`, this page, `commands/bind.md`) with
+nothing checking that they agree — see the PS-I18N epic's backlog.
+
+## Vault-side policy
+
+`<vault>/.projectstore.json` (vault root — committed with the vault, survives
+clones) carries `spec_policy: required|optional`, `lifecycle_gates: on|off`,
+and `spec_policy_since` (ISO-8601). See ADR-007 in the project vault and
+`commands/doctor.md` for which checks each key activates.
+
+## Contributing back
+
+PRs welcome at https://github.com/SmartAndPoint/ProjectStore. Prefer one
+focused PR per layout / template / skill. Include a sample output in your PR
+description.

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

@@ -0,0 +1,133 @@
+# Getting started with projectstore
+
+## Install (local dev)
+
+Until projectstore is published to a public marketplace, install it from a local clone.
+
+```bash
+git clone https://github.com/SmartAndPoint/ProjectStore.git ~/Projects/SmartAndPoint/ProjectStore
+```
+
+In Claude Code, register the local plugin directory:
+
+```
+claude --plugin-dir ~/Projects/SmartAndPoint/ProjectStore
+```
+
+Inside a Claude Code session, reload the plugin without restart:
+
+```
+/reload-plugins
+```
+
+Verify the plugin appears:
+
+```
+/plugin list
+```
+
+You should see `projectstore` (displayName) with prefix `projectstore`.
+
+## Install (via marketplace)
+
+```
+/plugin marketplace add SmartAndPoint/ProjectStore
+/plugin install projectstore@SmartAndPoint
+```
+
+## First-time setup
+
+1. **Pick a vault directory** — any folder where you want your project artifacts to live. Obsidian opens it natively. Git tracks it cleanly.
+
+   ```bash
+   mkdir -p ~/Documents/projects/my-project-vault
+   ```
+
+2. **Bind your current project to that vault**:
+
+   ```
+   /projectstore:bind ~/Documents/projects/my-project-vault
+   ```
+
+   This creates `.projectstore/projectstore.json` in your project root (machine-local, gitignored) — and then walks you through a short interview: gitignore entries → scaffold offer → agent registration in `CLAUDE.md` (recommended: Yes) → model preset for the review agents (the default `opus` is fine) → status line offer (you'll see a preview of the exact line). Every step shows what it wants to write and waits for your approval.
+
+   **Working in a git worktree?** That config is gitignored, so a worktree of a bound checkout starts unbound and `/projectstore:*` will not run there. Session start says so and names the fix:
+
+   ```
+   /projectstore:bind --inherit
+   ```
+
+   It copies the binding of the checkout the worktree was forked from — same vault, shared and unchanged, no session state carried over — and skips the interview, since the parent already answered it.
+
+3. **Scaffold the layout** if the vault is empty (bind offers this automatically):
+
+   ```
+   /projectstore:scaffold engineering
+   ```
+
+   Creates `adr/`, `specs/`, `epics/`, `research/`, `concepts/`, `meetings/`, `ops/`, `diagrams/` and a top-level `README.md`.
+
+## Daily flow
+
+```
+/projectstore:status                                      # what's bound, what's in progress, view freshness
+/projectstore:adr "Use Postgres for primary storage"      # capture a decision
+/projectstore:epic AUTH-001 "Authentication system"       # plan a major piece of work
+/projectstore:story AUTH-001 "OIDC discovery"             # decompose into stories
+/projectstore:kanban                                      # regenerate the board
+/projectstore:search "data detective"                     # search the vault
+/projectstore:doctor                                      # install + vault diagnostics (no LLM)
+/projectstore:reconcile                                   # re-derive board/indexes/code-map from frontmatter
+/projectstore:codemap                                     # epic ↔ code mapping view
+/projectstore:graph                                       # vault link graph: nodes + typed edges
+/projectstore:agents status                               # routing block + model config state
+```
+
+## How approval works
+
+Every command that writes or edits a file goes through `AskUserQuestion`:
+
+1. The command renders a draft (via a plugin script, no disk write).
+2. You see the target path + content preview.
+3. You pick `Yes` / `Edit before saving` / `No`.
+4. Only on `Yes` does the file land.
+5. That same `Yes` covers the folder's index README — the row is not appended,
+   the folder's managed index table is regenerated through the core, so it
+   arrives in canonical order and your prose around the table is preserved.
+   One consequence the prompt tells you about: the regeneration rewrites the
+   whole table, so a creation can also repair a stale row for another artifact.
+
+Skills (`projectstore-decision-detector`, `projectstore-story-completion`) are passive — they suggest commands; they never write directly.
+
+## Disabling skills
+
+Edit `.projectstore/projectstore.json`:
+
+```jsonc
+{
+  "active_skills": false
+}
+```
+
+## Multi-language templates
+
+Default is English (`en`). Also bundled: Russian (`ru`), Spanish (`es`), German (`de`), French (`fr`), Simplified Chinese (`zh`):
+
+```
+/projectstore:bind <path> --lang de
+```
+
+Or edit `language: "de"` in `.projectstore/projectstore.json` (templates must exist at `templates/de/`). The language also localizes the status line strings (e.g. the "no epic or story in this session yet" line).
+
+What the language does and does not change: section headings, table labels and prose are translated; frontmatter keys and their values (`status: planned`, `priority: p2`) stay English, because they are machine-read. Section headings are registered in `scaffold/headings.json`, so doctor, reconcile and the story lifecycle gates recognize every bundled language — a Russian-headed file lints in a French-bound vault, and mixed-language vaults reconcile.
+
+## Updating to a new version
+
+```
+/plugin marketplace update SmartAndPoint
+/reload-plugins
+```
+
+Or enable auto-update once (`/plugin` → **Marketplaces** → **SmartAndPoint** → toggle **auto-update**) and Claude Code will detect new releases at startup.
+
+**After any update, run `/projectstore:doctor`.** It compares your project's wiring against what the new version expects and names each fix with the command to run — stale agents block in `CLAUDE.md` (`/projectstore:agents register`), leftover agent copies that override nothing (`/projectstore:agents configure`), auto-update still off (the exact setting and file), a newer release than the one running. `doctor --fix` applies the install-side repairs interactively; `/projectstore:reconcile` rebuilds the board/indexes/code-map if content drifted. Silence at session start means healthy — the cheap checks run automatically and only speak up when something is wrong.

package/node_modules/projectstore/docs/harnesses.md

@@ -0,0 +1,163 @@
+# Harnesses
+
+projectstore's engine is one package. What differs between coding agents —
+where a hook is declared, whether a subagent can be shipped, which environment
+variable names the project — lives in `harnesses/<id>.json`, one **capability
+manifest** per harness, and nowhere else. No script branches on a harness name;
+the portability suite greps for it.
+
+This page says which harnesses exist, how far each one is trusted, and what
+"experimental" means when you read it below.
+
+## Status
+
+| Harness | id | Status | Verified | Surfaces installed |
+|---|---|---|---|---|
+| Claude Code | `claude-code` | **supported** | 2026-08-30 | hooks, commands, agents, skills, MCP, status line, agents block |
+| Codex | `codex` | **experimental** | — | portable plugin, hooks, rendered workflow skills, agents block |
+
+**supported** means the manifest carries a `verified` block: a session id and a
+date on which this harness's surfaces were installed and exercised end to end,
+and the measurements in the manifest came from that run.
+
+**experimental** means `verified` is `null`. Every field that was not measured
+is absent or `null` rather than guessed. It is enough to run on; it is not enough
+to promise. An experimental harness is never the source layout. A generated
+adapter may exist while it is experimental. Its distribution shell may
+publish before the live run that sets `verified`, but only by the maintainer's
+decision (Codex's does, from 0.28.1); the label stays experimental until that
+run.
+
+The label is not prose. It is derived from the manifest, and
+`tests/portability.test.mjs` fails if this table and `verified` disagree.
+
+## Claude Code
+
+The **source layout**: the repository's own `hooks/`, `commands/`, `agents/`,
+`skills/` and `.mcp.json` are Claude Code's, written by hand and read directly.
+Every other harness is generated from them. Exactly one manifest may say
+`source_layout: true`, which is what keeps "the original" a single place.
+
+Config lives in `<project>/.projectstore/`, harness-neutral, shared by every
+harness in the project. The per-harness half — the agents block, which carries
+model names and those are harness-specific — is
+`<project>/.projectstore/harness/claude-code.json`.
+
+## Codex
+
+Experimental, measured on `codex-cli 0.153.4`. The initial spike captured 759
+hook firings. The 2026-09-30 gate then built the npm shell from a packed core,
+passed Codex's plugin validator, installed and upgraded it through an isolated
+`CODEX_HOME`, verified the materialised cache by version and digest, and loaded
+the `projectstore-status` skill in a fresh Codex session. The validator (the
+plugin-creator skill's `validate_plugin.py`) reads only
+`.codex-plugin/plugin.json`. The canonical root `plugin.json` was validated
+separately on 2026-10-04, against the schema it declares (Agent Plugins 1.0.0).
+
+That run exercised one skill, not every installed surface, so `verified` stays
+`null`. The hooks are the reason it matters. On 2026-10-03 the first real
+install's cached hooks could not load the vault in any session. They were run
+by hand through `zsh -lc`; the failure did not depend on the shell form. In the
+first session the failure sat in the model's context under the welcome, which
+was all the user saw. The core had taken the shell's root for its own. That is
+fixed, and the suite now runs every rendered hook from the built shell. A live
+Codex session firing them from an installed release is still owed.
+
+How 0.153.4 starts a hook was read from its source, not measured: under the
+session's shell as `<shell> -c`, with the environment the Codex process had when
+it built the session's hooks. `$SHELL -lc` (or `/bin/sh -lc`) is the fallback
+when the hooks are built without exactly one ready local environment. So a hook
+finds `node` on the Codex process's own `PATH`, plus whatever `.zshenv` adds:
+zsh reads `.zshenv` for a `-c` command, not `.zprofile` or `.zshrc`, so a Codex
+not started from a terminal can miss a `node` that only `.zprofile` puts on
+`PATH`.
+
+The shell is published as `projectstore-codex` from 0.28.1, ahead of that live
+run, by the maintainer's decision:
+
+```sh
+npx projectstore-codex install --project "$PWD"
+```
+
+For later releases, `npx projectstore-codex@<version> upgrade --project "$PWD"`.
+Installation is user-global because Codex stores marketplace registrations and
+plugin caches in `CODEX_HOME`; the agents block in `AGENTS.md` remains
+project-local. Ordinary uninstall leaves the global plugin in place; add
+`--global` only when you mean to remove it for every project. From this
+checkout, the same flow runs against a built tarball:
+
+```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"
+```
+
+What is known, and how:
+
+- **Hooks are rendered; their live firing from an installed release is not
+  yet observed.** The canonical portable `plugin.json` selects
+  `./hooks/hooks.json` through `extensions.com.openai`; the compatibility
+  `.codex-plugin/plugin.json` stays inside the current ingestion schema. Five
+  events: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`.
+  Of the 759 captured firings, 757 came from the earlier inline form, across
+  `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse` and `Stop`,
+  and 2 from a file-site `hooks/hooks.json` with an absolute `node` path.
+  `PreCompact` has never been observed firing on Codex, and neither has the
+  `${PLUGIN_ROOT}` form selected through `extensions.com.openai`. The hook process
+  receives `PLUGIN_ROOT` in its environment, naming the shell's root with the
+  core beneath it in `node_modules/projectstore/`, and **no project-directory
+  variable at all**. The project comes from the payload's `cwd`, which every
+  projectstore hook adopts before it resolves anything.
+- **Trust is granted per hook, machine-wide**, and it lags: a release that
+  changes hooks may not take effect until the session after next.
+- **Source commands are not shipped.** Codex has no registrable root slash command, and
+  shipping `commands/` is actively harmful — it rewrites them into skills itself
+  and leaves `${CLAUDE_PLUGIN_ROOT}` in the body, producing entry points that
+  exit 1. They are rendered as skills instead.
+- **Roles are rendered as orchestration skills.** Codex spawns subagents through
+  its collaboration tool, not by loading a plugin's `agents/` directory. The
+  six ProjectStore roles therefore ship as namespaced skills that resolve their
+  configured model through the core and ask Codex to spawn the role. No effort
+  is forced: it inherits unless the user has configured a model policy.
+- **Multi-file edits reach the activity log and entry rule when their paths
+  are absolute.** Codex's `apply_patch` carries paths inside
+  `tool_input.command`; the shared extractor reads every `Add`, `Update`,
+  `Delete` and `Move to` path from that measured envelope field. A relative
+  path is not yet resolved against the payload's `cwd`, so it is not recorded.
+  The field name remains manifest data, not a Codex branch.
+- **MCP does not ship.** Our `.mcp.json` is in Claude Code's dialect.
+
+Codex also sets Claude Code's `CLAUDE_PLUGIN_ROOT` for compatibility. A variable
+two harnesses both set identifies neither, so both manifests demote it: it stops
+being evidence for *either* harness rather than being evidence for the first file
+in alphabetical order.
+
+## Running both over one project
+
+Nothing is shared that could collide. The binding
+(`<project>/.projectstore/projectstore.json`) is harness-neutral and one file;
+the agents block is per harness; the session state is keyed by harness id. Two
+harnesses in one project write two overlays and neither disturbs the other.
+
+Within one machine, run them in separate **git worktrees** over the same
+checkout, as parallel Claude Code sessions already do. The vault itself is a git
+repository with its own remote — that is how it syncs between people and their
+agents.
+
+## Adding a harness
+
+A harness is a manifest plus measurements, not code:
+
+1. Write `harnesses/<id>.json`. Copy the field list from an existing one; leave
+   `verified: null` and omit or null every value you have not observed. A field
+   that is `null` with a reason is a decision on the record; an absent field is
+   one someone forgot.
+2. Measure. Install it, run a real task, capture the hook payloads. The values
+   that matter first: which environment variables the hook process receives,
+   where hooks are declared, which tool writes files and where that tool puts the
+   path.
+3. Declare any variable the harness sets that belongs to another harness under
+   `runtime.shared_env`, or detection will answer with someone else's id.
+4. Add a row to the table above. It stays **experimental** until the manifest
+   carries a `verified` block — the test enforces the pairing in both directions.
+
+See [`docs/extending.md`](./extending.md) for the surfaces themselves.