@magnusekdahl/parallix 1.0.0

package/docs/authority-reference.md

@@ -0,0 +1,298 @@
+# Parallix Authority Reference
+
+Consolidated parallix workflow authority for the parallix AI mission lifecycle. The executable authority is the `parallix/` code (in this repository, the root `index.js`/`px.js` and `lib/`); this file is its canonical markdown companion.
+
+> This document holds the internal operator and authority detail that previously lived in `README.md`. It was moved here during the task-1336 README rewrite so the landing page stays focused while none of the operational detail is lost. The public-facing overview is in [`README.md`](../README.md).
+
+Conflict resolution: `AGENTS.md` wins on hard rules and verification entrypoints; locked `MISSION.md` wins on mission-specific scope and stop rules; runtime code wins over this file.
+
+## 1. Workflow Modes
+
+Mission flow: `backlog → draft → ready → active → review → approved → done`. Blocking review findings loop `review → active → review` on the same branch and PR. One machine, one branch (`mission/<slug>`), one worktree (`../<project>-<slug>`), one implementer. Primary checkout stays on the primary branch (`main` or `master`, detected at runtime) for human integration only.
+
+`AGENTS.md` and the mode's agent-prompt are always in scope. `execute`, `review`, `act-on-review`, and `integrate` also always include locked `MISSION.md` and relevant source files. Expand beyond baseline only on a clear trigger (checkpoint transition, restricted-area entry, failed verification, blocked evidence, review feedback, or material mission-shape change); state what was loaded, why triggered, and why baseline was insufficient.
+
+## Entrypoints
+
+- `index.js` is the dispatcher; run it directly as `node index.js <command>`.
+- `px.js` is the `px` binary wrapper and shell-init helper.
+
+## Config Boundary
+
+- `config/` is tool-owned defaults and launcher policy.
+- The target repository's `config/` directory is repo state, not parallix code.
+- Operator-local overlays live in `.local.json` and `.example` files; they are machine-specific and must not be conflated with repo config.
+
+| Mode | Description | Mode-specific context |
+|---|---|---|
+| `portfolio` | Brainstorm and filter candidate missions | REALITY_PROBE.md, docs/index.md, docs/adr/index.md, Backlog state, active branches/worktrees, strategic framework |
+| `draft` | Build one mission spec in detail | REALITY_PROBE.md, selected mission candidate, relevant ADRs/mission history |
+| `execute` | Implement steps for a locked mission | current `git status` |
+| `review` | Code quality review | `git diff <primary-branch>..HEAD` |
+| `act-on-review` | Resolve live review findings on the current mission branch | live PR comments |
+| `area-review` | Review one repo area outside a mission execution flow | REALITY_PROBE.md, focused area source files |
+| `integrate` | Land a reviewed mission and complete cleanup | integration checkout state |
+
+## 2. Authority Stack
+
+| Layer | Owns | Must not do |
+|---|---|---|
+| `AGENTS.md` | Hard rules, restricted actions, verification entrypoints, autonomy boundaries | Re-specify mission-specific scope or phase procedures |
+| `docs/authority-reference.md` | Workflow modes, lifecycle, context packets, authority model, validation model | Override runtime code or mission-specific scope |
+| `missions/<slug>/MISSION.md` | Mission contract, scoped checkpoints, risks, gates, success criteria, stop rules | Override repo-wide hard rules |
+| `docs/agent-prompts/*.md` | Mode-specific procedures and entry/exit obligations | Re-teach the full workflow or become a second policy layer |
+| `parallix/` code | Executable workflow behavior | Depend on markdown duplication for correctness |
+
+## 3. Agent Selection
+
+Four families: `codex`, `claude`, `mistral`, `qwen`. Step eligibility is in `config/agents.json`. Launchers are resolved from `PATH` by bare executable name.
+
+`WORKFLOW_AGENT=<name>` overrides random selection only when that agent is eligible and unblocked. The effective blocklist is operator-owned at `<PARALLIX_HOME>/agents.local.json`; on first use parallix non-destructively migrates the legacy runtime-config, repo-root, and main-worktree files in that precedence order. Per-agent values: `true` (permanent block), `{ "until": "YYYY-MM-DD HH" }` (timed), `{ "blocked": false }` (unblock).
+
+Usage-limit failures: harness writes a timed block to the local blocklist and retries with the next eligible unblocked agent. All exhausted → fail clearly.
+
+## 4. Validation Model
+
+Validation is layered. One prompt declaring work complete is never sufficient.
+
+### 4.1 Primary gate runner
+
+The primary gate is **configured per repo**, not hardcoded. Declare it under
+`adapters.verification` in `workflow.config.json`:
+
+```json
+{
+  "adapters": {
+    "verification": { "command": "./scripts/verify-local.sh {{area}}", "defaultArea": "docs" }
+  }
+}
+```
+
+- **`command`** — the shell command the workflow runs as the primary gate. The `{{area}}` token
+  is substituted with the mission's detected area before the command runs. A command with no
+  `{{area}}` token runs verbatim for every area.
+- **`defaultArea`** — the area used when none can be detected from the mission (defaults to `docs`).
+- **No-op default:** when `adapters.verification` is absent, verification is a no-op pass — the
+  workflow does not invent a gate for repos that have not declared one.
+
+The area is detected from the gate-runner invocation written in `MISSION.md` (the `Gates` lines).
+Detection recognizes any verification script referenced as a `./` or `../`-prefixed path
+(e.g. `./scripts/ci.sh <area>`, `../tools/gate.sh <area>`), so it is not tied to the
+`./scripts/verify-local.sh` name. The relative-path prefix is required, so a bare filename in
+prose is not mistaken for a gate.
+
+Default is `./scripts/verify-local.sh {{area}}` .
+Repos **without** `verify-local.sh` declare their own command, for example:
+
+```json
+// Make target per area: make verify-docs, make verify-server, ...
+{ "adapters": { "verification": { "command": "make verify-{{area}}", "defaultArea": "docs" } } }
+```
+
+```json
+// npm script forwarding the area as an argument
+{ "adapters": { "verification": { "command": "npm run verify -- {{area}}", "defaultArea": "docs" } } }
+```
+
+The detected area maps from the changed surface as follows (this table reflects visualBoard's
+areas; the area names a repo uses are whatever its configured `command` accepts):
+
+| Changed surface | Gate |
+|---|---|
+| `docs/`, `*.md` only | `docs` |
+| `parallix/` or mixed parallix code | `workflow` or `all` |
+| `web-client/` | `web` |
+| `server/` | `server` |
+| `auth-server/` | `auth` |
+| `android/`, `wearos/` | `android` |
+| `kubernetes/` | `k8s` |
+| Multiple functional areas | `all` |
+
+### 4.2 Mission-specific gates
+
+Each locked mission may add gates (staging validation, manual QA, ADR creation, C2 review). These add to the baseline; they do not replace it.
+
+### 4.3 Review gate
+
+External review by a different agent is mandatory before integration. Valid review: surface exists; reviewer inspects `<primary-branch>..HEAD`; findings cite file references; zero-finding reviews for non-trivial missions include explicit searched-and-found-none evidence.
+
+### 4.4 Integration gate
+
+Complete when: mission reviewed, landing from the correct integration checkout, Backlog state updated, mission branch and worktree cleanup done.
+
+#### 4.4.1 Integration-time pipeline gates (ADR 0041)
+
+`px integrate` runs integration-time gates before the squash-merge lands. These gates are configured via a repo-side config file and invoked per changed top-level area.
+
+- **Config location:** `config/integration-pipelines.json`
+- **Schema:** `{"gates": {"<area>": {"command": "<shell-command>", "order": <number>, "run_last": <boolean>}}}`
+- **Supported areas:** `server`, `auth-server`, `web-client`, `web-e2e`
+- **Ordering:** Gates are executed in ascending `order` value; `run_last: true` ensures the gate runs after all others (regardless of order value)
+- **Change detection:** Gates are only invoked for areas with changed files in the mission branch vs the primary branch
+- **Opt-out:** `px integrate <slug> --no-integration-gates` skips all integration gates
+- **Dry-run:** `px integrate <slug> --dry-run` prints the resolved gate plan without executing
+
+Example config:
+```json
+{
+  "gates": {
+    "server": {"command": "./server/updateStaging.sh", "order": 1, "run_last": false},
+    "auth-server": {"command": "./auth-server/updateStaging.sh", "order": 2, "run_last": false},
+    "web-client": {"command": "SKIP_E2E=1 ./web-client/updateStaging.sh", "order": 3, "run_last": false},
+    "web-e2e": {"command": "./web-client/scripts/run-playwright-stage.sh", "order": 4, "run_last": true}
+  }
+}
+```
+
+If the config file is missing or empty, `px integrate` logs `integration-gates: no config present, skipping` and proceeds without error.
+
+## 5. Checkpoint Model
+
+Each completed checkpoint must produce: (1) checkpoint doc under the configured mission base dir for the repo (`missions/<slug>/` in this repo), (2) non-generic `Next action:`, (3) passing relevant gate, (4) commit on `mission/<slug>`. Checkpoint docs make resume and handoff deterministic.
+
+## 6. State Map and Command Aliases
+
+### Virtual vs. actual state names
+
+The workflow uses virtual state names (`backlog | ready | active | review | approved | done`). Each project's `config/state-map.json` maps virtual names to the actual backlog.md state names used by the board:
+
+```json
+{ "ready": "refined", "approved": "ready-for-integration" }
+```
+
+Rules:
+- When a virtual state has a non-null mapping, the corresponding backlog.md write happens with the actual name.
+- When a virtual state maps to `null` or is absent from the map, the workflow step advances but makes no backlog.md write (useful for sparse boards with fewer states).
+- States that match in both worlds (e.g. `active`, `review`, `done`) need not appear in the map.
+
+### Command aliases
+
+Command aliases are derived automatically from `state-map.json` — no second config file to maintain. The derivation rules are:
+
+- `ready` and its actual backlog.md name (if any) → `draft`
+- `approved` and its actual backlog.md name (if any) → `integrate`
+- `done` → `integrate` (always)
+
+With the default state-map above, the effective alias table is:
+
+| alias | canonical |
+|-------|-----------|
+| `approved` | `integrate` |
+| `done` | `integrate` |
+| `ready` | `draft` |
+| `ready-for-integration` | `integrate` |
+| `refined` | `draft` |
+
+When `px <alias>` is invoked, the CLI logs `[INFO] Resolving alias <alias> → <canonical>` and delegates to the canonical command.
+
+View the current alias table: `px aliases`
+
+## 7. Stats Preview
+
+Use `px stats` before integration when you want to validate the weekly tables from committed workflow data, or add `--from` and `--to` to inspect one larger inclusive date range.
+
+**Classification:** `<PARALLIX_HOME>/stats.csv` is **parallix-owned cross-repository agent telemetry** — one statistic about how agent families perform across every repo a single parallix runtime drives. It is operator-owned and independent of both the installed package and selected consuming repo, so one runtime working in several repositories accumulates one shared statistic rather than a split per-repo file. The five-column schema (`date,mission,classification,implementer,pr_fix_rounds`) carries no repository identity by design.
+
+## Persistent operator data
+
+`PARALLIX_HOME` overrides the whole persistent-data root. Without it, parallix
+uses `~/.local/state/parallix` on Linux,
+`~/Library/Application Support/parallix` on macOS, and
+`%LOCALAPPDATA%\parallix` on Windows. If the platform-specific base cannot be
+resolved, it falls back to `~/.parallix`.
+
+The root contains `stats.csv` and `agents.local.json`. Missing directories and
+files are created on first write; read-only paths tolerate absence. The first
+default access migrates the repo-root legacy `stats.csv` and the three legacy
+blocklist locations without deleting them. Statistics rows are
+deduplicated by all five columns. Blocklist precedence remains
+runtime-config, repo-root, main-worktree; conflicts are logged with both values
+and their sources. Malformed legacy blocklists are reported and skipped, while
+a malformed effective file is a hard failure and is never overwritten.
+
+Back up `PARALLIX_HOME` separately. It is not target-repository state and is not
+inside, restored by, or removed with the globally installed npm package.
+
+- Default preview: `px stats`
+- Freeze the reporting window for reproducible checks: `px stats --today 2026-05-18`
+- Preview one inclusive workflow-owned range: `px stats --from 2026-05-01 --to 2026-05-31`
+- Be explicit about the source file: `px stats --csv-file stats.csv --today 2026-05-18`
+- Write the output to a file for inspection or sharing: `px stats --from 2026-05-01 --to 2026-05-31 --output /tmp/workflow-stats.txt`
+- Break one mission down by phase: `px stats task-1285` (or `px stats --mission task-1285`)
+- Show command help and examples: `px stats --help`
+
+Behavior:
+- Workflow-owned stats datasets (`stats.csv` schema) print the current-week and previous-week mission tables plus the two agent-performance tables.
+- With `--from YYYY-MM-DD --to YYYY-MM-DD`, workflow-owned stats datasets instead print one mission table and one agent-performance table for rows whose `date` is within the inclusive range.
+- With a mission slug (`px stats task-1285`) or `--mission <slug>`, the command prints one mission broken down by phase — `draft`, `execute` (stored as the `active` stage), and `review` are always shown, plus any `follow-up`/extra recorded stages, with per-phase provider, model, implementer, token, tool-call, and duration columns and a totals row. The output is a pure function of the stored rows, so re-running it does not change the data.
+
+Telemetry capture contract (task-1285):
+- Stage rows are keyed by `(mission, stage)`; `draft.js`, `active.js`, and the review loop each record their phase via `recordStageStats`/`recordActiveStats`/`recordReviewStats`.
+- Structured sources: Codex (`codex-telemetry.js`, rollout JSONL) and Claude (`claude-telemetry.js`, stdout SSE) populate real token/usage fields.
+- `opencode` (local Qwen) exposes no structured usage source, so `opencode-telemetry.js` records honest zeros with provider/model falling back to the agent family — never fabricated numbers.
+- `vibe`/`mistral` telemetry is **blocked** in this environment; `mistral-telemetry.js` records honest zeros and the verification is tracked as follow-up task-1288.
+
+---
+
+## Public distribution (canonical packaging and install)
+
+This is the one authoritative public distribution story for parallix. It is the
+near-term supported model; the architectural decision behind it is recorded in
+ADR 0044 (`docs/adr/0044-workflow-distribution-model.md`).
+
+**Supported acquisition/install path.** parallix is a Node.js toolkit (package
+name `@magnusekdahl/parallix`) that coordinates AI-assisted software missions through
+the lifecycle `backlog → draft → active → review → approved → done`. The
+supported artifact is a **local npm tarball built from this repository** — not a
+public registry install and not a container image. The package name is scoped so
+the unscoped `px` / `parallix` npm names are not relied upon. The shortest
+supported path is:
+
+```sh
+npm pack
+```
+
+```sh
+npm install -g ./magnus-parallix-*.tgz
+```
+
+```sh
+npm install -g --prefix "$HOME/.local" ./magnus-parallix-*.tgz
+```
+
+Use the user-writable prefix when you do not have `sudo` access. If your shell
+does not already place `$HOME/.local/bin` on `PATH`, add it once.
+
+`CHANGELOG.md` is the versioning authority. Until the first public release,
+PATCH bumps are the release discipline: bump before each `px integrate`, then
+reinstall from the new tarball after the integrate succeeds. That policy is
+documented release practice, not automatic CLI behavior.
+
+**How the operator invokes `px`.** After the global install, `px <command>` is
+the installed runner; use `px shell-init` in your shell rc if you want mission
+transitions to `cd` your terminal into the next worktree. `px --version`
+identifies the executing `px.js` path so an accidental PATH collision with an
+unrelated `px` is visible.
+
+**What stays source-compatible for local development.** Running directly from a
+checkout is unchanged: `node index.js <command>` runs from source, requires no
+install step, and never changes the caller's shell directory. The tarball install and the source run are the same
+code; the tarball only adds a versioned, globally linked `px`.
+
+**What is not yet supported.** The following are explicitly out of the near-term
+model and are not claimed to work today: publishing to the public npm registry
+(or any other registry), Homebrew, Docker images, standalone single-file
+binaries, and CI/release automation or npm provenance (Sigstore). ECDSA registry
+signatures are automatic on the public npm registry and require no publisher action.
+Distribution stays a manual `npm pack` + global install until a follow-up decision
+changes that.
+
+The old enterprise walkthrough has been removed. The supported packaging and
+install path is the three shell lines above.
+
+## References
+
+- ADR 0044 — Workflow Distribution Model for parallix:
+  `docs/adr/0044-workflow-distribution-model.md` (candidate consumption modes,
+  Interface Boundary, Enterprise Safety Model).
+- Phase 1–4 extraction evidence: `docs/missions/2026/task-1231` … `task-1234`.

package/docs/forgejo-setup.md

@@ -0,0 +1,31 @@
+# Forgejo Setup
+
+Standalone workflow installs need three review-surface pieces before `active`, `review`, `handoff`, `rebase --push`, or `integrate` can talk to Forgejo:
+
+1. a reachable Forgejo base URL
+2. a review repository matching `adapters.review.repo`
+3. token files for the agent users that will push branches or post reviews
+
+## Happy Path
+
+1. Export the workflow into the repo.
+2. If you need a local Forgejo instance, run `parallix/tools/setup-forgejo-docker.sh` and start it with Docker Compose.
+3. Run `px setup`.
+4. Choose whether to keep the standard Backlog.md-style layout:
+   - task storage in `backlog/`
+   - missions in `missions/`
+   - `mission/*` branches on `main`
+   - worktrees in `../<repo>-<slug>`
+   - verification via `npm test`
+5. If you keep Forgejo bootstrap enabled, enter the Forgejo password for the login that can create the review repo.
+6. Enter passwords for the agent users you want available on this machine, or leave them blank to skip token creation for that user.
+
+`setup` writes `workflow.config.json`, writes token files into `.forgejo-local/tokens/`, grants the listed agent users write access to the configured review repo, creates or updates the git `review` remote, and runs `verify-env` so the install is validated before you start missions.
+
+## Notes
+
+- The configured review repo is created only if it does not already exist.
+- Existing review repos are updated to grant the listed agent users `write` access, so implementer identities can see and update their own PRs.
+- You can leave an agent password blank to skip that token on this machine.
+- Re-running `px setup` lets you change config and rotate the local token files.
+- `px setup-review` still exists as a narrower Forgejo-only repair path if you only need to refresh token or remote wiring.

package/docs/migration/extraction.md

@@ -0,0 +1,61 @@
+# parallix standalone extraction record (task-1302)
+
+This repository was extracted from the WrGroceries monorepo's embedded `parallix/`
+directory as the standalone-repo "extraction proof" required by ADR 0044.
+
+## Method — history-preserving
+
+The extraction used **`git subtree split -P parallix`** (history-preserving), not a
+flat copy. `git filter-repo` was not available on the workstation; `git subtree split`
+is built into git 2.53 and reproduces every commit that touched `parallix/` with the
+subtree promoted to the repository root. The standalone repo was then created with
+`git clone -b <split-branch> --single-branch`, the `origin` remote removed, and the
+default branch renamed to `main`.
+
+Result: the full commit history for the parallix tree survives (`git log` shows the
+`mission/task-1299`, `mission/task-1301`, `mission/task-1310`, etc. commits that
+shaped the tool), and the working tree is byte-identical to the monorepo's
+`parallix/` tree (verified with `diff -rq` across `lib/`, `test/`, `config/`,
+`prompts/`, `templates/`, `examples/`, and the root files).
+
+## Verbatim guarantee and the test-harness exception
+
+No parallix **source** (`lib/`, `index.js`, `px.js`, command interfaces) was rewritten.
+The only post-extraction edits are to **test-harness coupling** that assumed parallix
+lived as a subdirectory of a host monorepo. These were unavoidable to satisfy the
+mission's `npm test` zero-failures gate in a standalone checkout, and every one of
+them is backward-compatible — re-running the edited test files inside the monorepo
+still executes all tests with zero skips and zero failures.
+
+### 1. Monorepo-script tests → auto-skip when the script is absent
+
+`test/install.test.js` and the `scripts/verify-local.sh`-invoking tests in
+`test/integration-pipelines.test.js` exercise WrGroceries monorepo scripts
+(`scripts/install-workflow.sh`, `scripts/verify-local.sh`) that live **outside** the
+parallix tree and are intentionally **not** carried into the standalone repo
+(MISSION scope item 9 — those scripts stay in WrGroceries and are repointed to the
+global `px` runner). Each such test now carries a `{ skip: ... }` guard keyed on the
+script's presence: it runs unchanged in the monorepo and skips (with a documented
+reason) in the standalone repo. Tests affected: 13 in `install.test.js`, 8 in
+`integration-pipelines.test.js`.
+
+### 2. Monorepo `.gitignore` assertion → skip outside the monorepo host
+
+`test/agents.test.js` has one test asserting the monorepo `.gitignore` semantics for
+the embedded `workflow/config/` tree, computed against `../..` (the monorepo root). In
+the standalone repo `../..` is the parent code directory, not a git repo, so the
+assertion does not apply. It now skips when no `.git` exists at `../..`. (1 test.)
+
+### 3. Rebase tests → made hermetic to the Forgejo-review config
+
+The standalone repo declares `workflow.config.json` with `adapters.review.provider:
+"forgejo"` (required for self-hosting parity). That turns
+`isForgejoReviewEnabled(process.cwd())` ON at the repo root. The rebase tests in
+`test/rebase.test.js`, `test/rebase_diagnostics.test.js`, and
+`test/rebase_hardening.test.js` were written assuming Forgejo-off (in the monorepo
+they ran with `cwd = parallix/`, which had no local config), and they do not mock the
+Forgejo fetch path. They now inject `isForgejoReviewEnabledFn: () => false` — the same
+injection idiom two sibling tests in the file already use with `() => true` — so they
+are hermetic to ambient config. (11 rebase calls across 3 files.)
+
+Net: 22 tests skip in the standalone repo (host-coupled to the monorepo); 0 fail.

package/docs/migration/task-classification.md

@@ -0,0 +1,36 @@
+# Task Classification
+
+| Task | Decision | Reason |
+| --- | --- | --- |
+| `TASK-1059` | move | workflow/parallix subject from title and mission context |
+| `TASK-1088` | move | workflow follow-up or workflow-operations subject from title |
+| `TASK-1115` | move | workflow/parallix subject from title and mission context |
+| `TASK-1133` | move | workflow/parallix subject from title and mission context |
+| `TASK-1243` | move | workflow follow-up or workflow-operations subject from title |
+| `TASK-1267` | move | workflow follow-up or workflow-operations subject from title |
+| `TASK-1268` | move | workflow follow-up or workflow-operations subject from title |
+| `TASK-1269` | move | workflow follow-up or workflow-operations subject from title |
+| `TASK-1270` | move | workflow/parallix subject from title and mission context |
+| `TASK-1273` | move | workflow/parallix subject from title and mission context |
+| `TASK-1275` | move | workflow/parallix subject from title and mission context |
+| `TASK-1277` | stay | model-capacity tuning note for GPT family selection; not the parallix workflow tool itself |
+| `TASK-1281` | move | workflow/parallix subject from title and mission context |
+| `TASK-1287` | stay | qwen-9B benchmark note; a model-evaluation task, not a parallix workflow change |
+| `TASK-1288` | move | workflow/parallix subject from title and mission context |
+| `TASK-1290` | move | workflow/parallix subject from title and mission context |
+| `TASK-1294` | move | workflow/parallix subject from title and mission context |
+| `TASK-1297` | move | workflow/parallix subject from title and mission context |
+| `TASK-1298` | move | workflow/parallix subject from title and mission context |
+| `TASK-1300` | move | workflow/parallix subject from title and mission context |
+| `TASK-1302` | move | workflow/parallix subject from title and mission context |
+| `TASK-1303` | move | workflow/parallix subject from title and mission context |
+| `TASK-1304` | move | workflow/parallix subject from title and mission context |
+| `TASK-1305` | move | workflow/parallix subject from title and mission context |
+| `TASK-1306` | move | workflow/parallix subject from title and mission context |
+| `TASK-1307` | move | workflow/parallix subject from title and mission context |
+| `TASK-1308` | move | workflow/parallix subject from title and mission context |
+| `TASK-1309` | move | workflow/parallix subject from title and mission context |
+| `TASK-1311` | move | workflow/parallix subject from title and mission context |
+| `TASK-1312` | move | workflow/parallix subject from title and mission context |
+| `TASK-1313` | move | workflow/parallix subject from title and mission context |
+| `TASK-1314` | move | workflow/parallix subject from title and mission context |

package/docs/operator-setup.md

@@ -0,0 +1,76 @@
+# Operator Setup — Graphify Skill Installation
+
+## Prerequisites
+
+The `graphify` CLI is a pinned pip package. Bootstrap it on your workstation:
+
+```sh
+pip3 install --user graphifyy==0.8.30
+```
+
+This installs the `graphify` entry-point script to `~/.local/bin/graphify` (on Linux/macOS). Verify:
+
+```sh
+~/.local/bin/graphify --version
+# → graphify 0.8.30
+```
+
+The CLI resolves in this order: `$GRAPHIFY_BIN` → `graphify` on `$PATH` → `~/.local/bin/graphify`.
+
+## One-Time Platform Install
+
+Run the installer once per agent family. It copies a platform-specific skill (and, for Claude, a `CLAUDE.md` directive) into the agent's config directory. **Do not use `--project` scope** — it writes artifacts into the current working directory.
+
+| Family | Command | Target Directory |
+|--------|---------|-----------------|
+| claude | `graphify install --platform claude` | `~/.claude/skills/graphify/` + `CLAUDE.md` directive |
+| codex | `graphify install --platform codex` | `~/.agents/skills/graphify/` |
+| qwen/opencode | `graphify install --platform opencode` | `~/.config/opencode/skills/graphify/` |
+
+Each command produces a `SKILL.md` file in the target directory. After running all three, verify:
+
+```sh
+test -f ~/.claude/skills/graphify/SKILL.md && echo OK   # claude
+test -f ~/.agents/skills/graphify/SKILL.md && echo OK    # codex
+test -f ~/.config/opencode/skills/graphify/SKILL.md && echo OK  # opencode
+```
+
+The install is idempotent — re-running any command overwrites the target with the latest skill file.
+
+### Environment variable overrides
+
+- **Claude**: Honors `$CLAUDE_CONFIG_DIR` to change the base config path.
+- **Opencode**: No env-var overrides; always writes to `~/.config/opencode/skills/graphify/`.
+
+## Codex Isolated HOME — Copy-Seed
+
+Codex runs with a worktree-local HOME (`<worktree>/.workflow/codex-home`). The global `~/.agents/skills/graphify/` is invisible to codex unless copied into that isolated HOME.
+
+The parallix harness handles this automatically. In `ensureCodexHome` (`lib/agents/codex.js`), a plain `fs.cpSync` copies the global skill into the worktree-local HOME **before** the `HOME` environment variable is overridden for the codex child process. This mirrors the existing `auth.json` copy pattern:
+
+```
+Source (operator's real HOME):
+  ~/.agents/skills/graphify/SKILL.md
+
+Target (worktree-local codex HOME):
+  <worktree>/.workflow/codex-home/.agents/skills/graphify/SKILL.md
+```
+
+The copy is:
+- **Idempotent**: re-running `ensureCodexHome` leaves the target unchanged.
+- **Clean skip**: if no global skill is installed (`fs.existsSync` returns false), the copy step is silently skipped — config is still written, but no skill directory is created.
+- **Not a per-launch install**: this is a filesystem copy of an already-installed skill. No subprocess is spawned.
+
+## Mistral Exclusion
+
+Graphify ships no `mistral` or `vibe` platform. The `graphify install --platform mistral` command does not exist and will fail. The parallix harness skips mistral without error during any Graphify-related operations.
+
+## Summary Checklist
+
+After setup, an operator should be able to:
+
+1. Run `graphify install --platform claude` → skill at `~/.claude/skills/graphify/`
+2. Run `graphify install --platform codex` → skill at `~/.agents/skills/graphify/`
+3. Run `graphify install --platform opencode` → skill at `~/.config/opencode/skills/graphify/`
+4. Launch any mission — codex will receive the skill via the copy-seed in `ensureCodexHome`
+5. mistral agents will not receive a Graphify skill (by design)