session-orchestrator 5.0.0 → 5.1.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
     "email": "office@gotzendorfer.at"
   },
   "metadata": {
-    "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
-    "version": "5.0.0"
+    "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
+    "version": "5.1.0"
   },
   "plugins": [
     {
       "name": "session-orchestrator",
       "source": "./",
-      "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
+      "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
       "author": {
         "name": "Bernhard Goetzendorfer",
         "email": "office@gotzendorfer.at"

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "5.0.0",
-  "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
+  "version": "5.1.0",
+  "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer",
     "email": "office@gotzendorfer.at",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "session-orchestrator",
-  "version": "5.0.0+codex.20260913085049",
-  "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
+  "version": "5.1.0+codex.20260913171452",
+  "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "keywords": [
     "session",
     "orchestration",

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "session-orchestrator",
-  "version": "5.0.0",
-  "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
+  "version": "5.1.0",
+  "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer"
   },

package/.orchestrator/policy/blocked-commands.json

@@ -116,6 +116,16 @@
       "modes": ["truncate"],
       "rationale": "Truncating redirect (>, &>, N>) onto protected artefacts silently destroys them — #983. Append (>>) stays allowed.",
       "sources": ["#983"]
+    },
+    {
+      "id": "redirect-harness-memory",
+      "type": "redirect-truncate",
+      "pattern": ">",
+      "severity": "block",
+      "target-denylist": ["~/.claude/projects/*/memory/**","~/.codex/projects/*/memory/**","~/.cursor/projects/*/memory/**"],
+      "modes": ["truncate","append"],
+      "rationale": "The harness auto-memory directory is injected as TRUSTED project context into every later session, yet lives outside git diff, CI review, check-owner-leakage (git ls-files only) and gitleaks. #1352 closed the Edit/Write lane for dispatched agents; this closes the shell-redirect lane, append included. NAMED CEILING (BV-004), every case measured 2026-09-13: (a) redirect-shaped by construction — `tee -a` and an in-process write (node -e fs.appendFileSync) are NOT covered; (b) `eval '… > target'` and `dd of=target` reach the file too, because the payload is never traversed for redirect targets — the pre-existing `redirect-truncate-protected` rule behaves identically, so this is a gap of the traversal, not of this rule; (c) a cwd-relative target after a directory change (`cd ~ && … > .claude/projects/*/memory/…`) is out of reach — the hook does not know the chain's cwd and a relative target is judged repo-root-relative, which is not lexically solvable; (d) `$HOME` / `${HOME}` / `$(…)` / backticks in the target fall into the pre-existing `unresolved` class (#641), where the hook warns and allows rather than guessing — for a home directory that is the most natural spelling. Revisit if the policy grows a non-redirect target class or the payload traversal learns redirects. Home-anchored entries are matched against the expanded ABSOLUTE path (#1362) because relativizeAgainstRoot discards every out-of-repo target by design.",
+      "sources": ["#1352","#1362"]
     }
   ]
 }

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.0] - 2026-09-13
+
+### Added
+
+- `docs/install.md` — the requirements matrix, per-harness install commands, upgrade path (incl. how the session-start banner detects a behind-copy) and the full uninstall/what-stays-behind list, moved out of the README so the landing page can be read in one screen.
+- Playwright local-install preflight in `scripts/lib/playwright-driver/runner.mjs` (#1359). The host-global `playwright` package is gone (browser-kit pins the toolchain per repo), so `npx playwright test` in a target repo without a local install no longer resolves — it starts an unpinned registry download in the middle of what is supposed to be a test run. The runner now resolves `@playwright/test` or `playwright` from the target's own `node_modules` (walking up, so a monorepo hoist counts) and exits 2 with an actionable message instead. It runs AFTER the `--dry-run` exit, and that ordering is pinned by a test.
+- Policy rule `redirect-harness-memory` + home-anchored denylist matching in `scripts/lib/command-blocker.mjs` (#1352, #1362). The harness auto-memory directory is injected as TRUSTED project context into every later session yet lives outside `git diff`, CI review, `check-owner-leakage` (tracked files only) and gitleaks. #1352 closed the Edit/Write lane for dispatched agents; this closes the shell-redirect lane, append included. Denylist entries starting with `~/` are matched against the expanded ABSOLUTE target, because `relativizeAgainstRoot` discards every out-of-repo target by design — measured: no glob spelling could reach the directory before. Relative ENTRIES keep byte-identical behaviour (pinned), while a relative TARGET is resolved against the repo root first — without that, `> ../../.claude/projects/<enc>/memory/MEMORY.md` reached the very file the tilde spelling blocks. NAMED CEILING (BV-004), all four measured as allow: `tee -a` and in-process writes; redirects inside `eval`/`dd of=` payloads; `cd ~ && … > .claude/…` (cwd-relative, not lexically solvable); and `$HOME`/`${HOME}`/`$(…)` targets, which stay in the pre-existing `unresolved` warn-and-allow class (#641).
+- Signal S5 `hand-keyed-learning-subject` in `scripts/lib/validate/check-unwired-features.mjs` (#1363). `sizingSubject()` (#1247) had ZERO mechanical consumers — prose told an LLM to derive the `effective-sizing` subject through it, and nothing enforced that, so a hand-concatenated subject silently re-merged a 7-wave `ultradeep` session onto the 5-wave `deep` row. The check imports the helper (which is what gives it a consumer at all) and re-derives the subject of every written `effective-sizing` learning. Only canonically-shaped subjects are judged: measured on this repo's live ledger, 1 of 6 is canonically keyed, so judging free-form prose would put the class at 83% on day one — the broken instrument `.claude/rules/host-resources.md` § HR-101 forbids.
+- `orchestrator.scope.coordinator_carveout_allowed` (#1361). The coordinator carve-out returned `emitAllow()`, which is `process.exit(0)` with no log path — whether the branch ever fired was structurally unanswerable (HR-105). The event carries the `classifyCaller` `discriminator`, so the fail-open case is countable.
+
+### Changed
+
+- `isPinnedActionComment()` in `scripts/release.mjs` — the version drift sweep no longer reads a SHA-pinned third-party action's trailing version comment as our own stale surface. `.github/workflows/test.yml` pins `actions/setup-node@a0853c2…  # v5.0.0`, and the sweep for the previous tag 5.0.0 matched it, blocking `--publish` on a file no release ever writes. The collision is coincidence and recurs for any action whose pin equals our next version, so the carve-out is a PREDICATE, not an allowlist row (the unenumerable-table failure `.claude/rules/measurement-discipline.md` records). Two conditions, both required: the line pins with `uses:` before the comment marker, and every occurrence of the literal sits after it — a version in the pin itself is still swept. Both directions proven by mutation: removing the predicate turns 1 test red, loosening it to "any YAML comment" turns 2 red.
+- README reduced from 314 to 151 lines, 3684 to 1694 words and 22 to 10 sections, measured against ten comparable repositories whose medians are 80 lines / 330 words / 5 sections. The animated illustration, the four film links and the AI-illustration disclaimer paragraph left the landing page (the assets stay in `site/video/` and on session-orchestrator.com); a Mermaid flow diagram of `/session` → `/go` → quality gate → `/close` with the fails-loop took that slot. The diagram is deliberately short-labelled: GitHub renders Mermaid in a sandboxed iframe and anchors its pan/zoom buttons to that iframe's right edge, so the 997 B and 905 B natural widths filled the 838 px container and ran under the controls — only the 690 px variant clears them. Prose rewritten in the `skills/eli5` register (no analogies, every greppable token kept). Nothing was deleted: the relocated sections live in `docs/install.md`, `docs/components.md` (destructive-command guard + import probe), `docs/telemetry.md` ("Your data stays in your repo"), `docs/USER-GUIDE.md` § 21 (hook PATH, `bootstrap.lock`) and `CONTRIBUTING.md` (`npx husky`, `rules/` vs `.claude/rules/`).
+- The plugin description is one sentence across `package.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (both slots), `.codex-plugin/plugin.json` and `.cursor-plugin/plugin.json`, adopting the plain wording already used in the GitHub About field instead of the previous jargon line. npm shows it from the published tarball, so it only becomes visible with this release.
+- `CODE_OF_CONDUCT.md` moved to `.github/CODE_OF_CONDUCT.md` — a location GitHub supports natively, so the repository's "Code of conduct" tab is unchanged. It had zero inbound references. The other three community-health files stay at the repo root deliberately: `SECURITY.md` is named by path in `.orchestrator/policy/blocked-commands.json` (moving it would silently void that protection), in `package.json` `files[]` and in `CODEOWNERS`; `CONTRIBUTING.md` is in the `HISTORY_ALLOWLIST` of `scripts/release.mjs`; and `CODEOWNERS` is scaffolded to consumer repos at root by four `skills/bootstrap/` files.
+- `hooks/enforce-scope.mjs` grants the #245 coordinator carve-out to the COORDINATOR only (#1361). The carve-out returned `emitAllow()` before Gate 7 without consulting `classifyCaller`, so any dispatched wave agent could write `.claude/STATE.md` — PSA-005/PSA-007 territory — and, worse, overwrite the LIVE `wave-scope.json`, rewriting its own scope manifest and disarming every later gate of the same wave. The RCR-007 allow-census ran first: across 1069 subagent transcripts carrying 4385 real `Write`/`Edit`/`MultiEdit` calls, **0** targeted a carve-out path, so the fix takes nothing away from a legitimate writer. Ambiguity stays fail-OPEN, same posture and same discriminator as Gate 5c.
+- `docs/session-config-template.md` catalogues four further runtime-read keys in the opt-in block (#1364): `heavy-repo`, `worktree-cleanup`, `persona-gate-wave` and the nested `test` block. Three more (`cross-repo`, `gitlab-portfolio`, `worktree-exclude`) are deliberately NOT catalogued yet — `claude-md-drift-check` Check 10b turns any opt-in template key missing from `docs/session-config-reference.md` into an `errors[]` entry, measured at 3 errors, so the reference has to be written first. `skill-evolution` and `dispatcher-autonomy` stay parity-exempt by design (#646 / #679).
+
 ## [5.0.0] - 2026-09-13
 
 Migration from 4.x: [v5 migration guide](docs/migration-v5.md). The major version reflects the changed `readCurrentStatus()` return contract and the now-enabled default close-time discovery scan.

package/README.md

@@ -1,68 +1,49 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-5.0.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.1.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
-[![Tests](https://img.shields.io/badge/tests-vitest-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
 **Give your agents a working rhythm.**
 
-Plan the work. Run it in checked waves. Pick up where you left off. Session Orchestrator is a free, MIT-licensed workflow plugin for **Claude Code, Codex CLI, Cursor IDE, or [Pi](docs/pi-setup.md)**. It reads your repository and issues, coordinates scoped work, and records what passed and what remains.
+You type three commands:
 
-[![Session Orchestrator: Plan, Go, Close, with an illustration of an agent workshop under human direction](site/og.png)](https://session-orchestrator.com)
-
-![One work item passes an automatic check; the one that fails is sent back](site/video/gate-readme.webp)
+- **`/session`** reads your repository, your open issues and the last session, proposes what to work on, and waits for your correction.
+- **`/go`** runs the agreed work in waves of parallel agents and runs your test, typecheck and lint commands between each wave. Work that fails a check goes back to be fixed before the next wave starts.
+- **`/close`** checks every planned item against what actually happened, commits, and files the rest as issues for next time.
 
-[34-second film](site/video/session-orchestrator-film.mp4) · [watch it embedded on the site](https://session-orchestrator.com/#loop) · [22-second camera preview](site/video/session-orchestrator-4.3-preview.mp4) · [How the film is made](marketing/vidlab/README.md)
+Session Orchestrator is a free, MIT-licensed workflow plugin for **Claude Code, Codex CLI, Cursor IDE, or [Pi](docs/pi-setup.md)**. It runs on your machine and writes plain text into your repository. No account, no server, nothing to sign up for.
 
-The film shows the workflow: read first, then build in parallel lanes, check every step, send back what fails, and step in where it matters. Illustrations are generated with AI. The 22-second preview illustrates the workflow; it is not a recording of a product session.
+[![Session Orchestrator: Plan, Go, Close, with an illustration of an agent workshop under human direction](site/og.png)](https://session-orchestrator.com)
 
-[Website](https://session-orchestrator.com) · [User guide](docs/USER-GUIDE.md) · [Platform support](#platform-support) · [Changelog](CHANGELOG.md)
+```mermaid
+flowchart LR
+    S["/session"] --> G["/go"]
+    G --> Q{"quality gate"}
+    Q -- "fails" --> G
+    Q -- "passes" --> C["/close"]
+```
 
-The same workflows are available on all four harnesses; Codex exposes commands as selectable skills. **Guard enforcement depends on the harness.** Claude Code runs the guard hooks directly; Cursor and Pi use bridges with documented limits. On Codex, destructive-command and file-scope rules are instructions only. With an active compatible scope hook, `strict` blocks supported out-of-scope edits, `warn` reports them without denial, and `off` disables the check (see [Platform support](#platform-support)).
+Longer explanation, with examples and screenshots: **[session-orchestrator.com](https://session-orchestrator.com)** ([auf Deutsch](https://session-orchestrator.com/de)).
 
-## Requirements
-
-| | |
-|---|---|
-| **Node.js** | **24 or later** (`node --version`) ; `package.json` `engines.node` is `>=24.0.0`. The plugin is ES modules and needs a real Node runtime. [Install Node.js](https://nodejs.org/). |
-| **A coding agent** | Claude Code, Codex CLI, Cursor IDE, or Pi. This is a workflow layer *on top of* one of them, not a replacement. |
-| **Harness version** | Codex CLI **0.144.4 or later** ([docs/codex-setup.md](docs/codex-setup.md)). No minimum is pinned for Claude Code, Cursor, or Pi; if `/plugin` (or the Cursor/Pi installer) runs, the plugin loads. |
-| **OS** | macOS and Linux are tested in CI. Windows is untested and best-effort; shell hooks and the optional Bash/`jq` MCP server need WSL or Git Bash. |
-| **Git** | A git repository. Session-orchestrator reads git state at every session start and commits at close. |
+[User guide](docs/USER-GUIDE.md) · [Install & upgrade](docs/install.md) · [Changelog](CHANGELOG.md)
 
 ## Install
 
+You need **Node.js 24 or later**, a git repository, and one of the four agents below. Full requirements, upgrade path and uninstall: [docs/install.md](docs/install.md).
+
 | Platform | Install |
 |---|---|
-| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry` (run both inside Claude Code). |
-| **Codex CLI** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs` |
-| **Cursor IDE** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/cursor-install.mjs /path/to/your/project` |
-| **Pi** | `pi install npm:session-orchestrator` ; dev fallback: `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only` |
-
-For Claude Code, also install the package's Node dependencies **once** and restart Claude Code. First locate the installed plugin:
-
-```bash
-claude plugin list --json
-```
-
-Find the enabled `session-orchestrator@kanevry` entry, then replace the placeholder below with its `installPath` value:
-
-```bash
-cd "/absolute/installPath/from/the/list" && npm install
-```
-
-If that entry is missing or disabled, resolve it through `/plugin` first. Use the path reported for that entry; another cached version or a nested dependency is not the installed plugin.
-
-Setup guides: [Codex](docs/codex-setup.md) · [Cursor IDE](docs/cursor-setup.md) · [Pi](docs/pi-setup.md). Per-IDE notes on `CLAUDE.md` vs `AGENTS.md`: [instruction-file-resolution](skills/_shared/instruction-file-resolution.md).
+| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry`, then [install its Node dependencies once](docs/install.md#claude-code-install-the-node-dependencies-once). |
+| **Codex CLI** | `git clone` the repo, `npm install`, then `node scripts/codex-install.mjs` ([guide](docs/codex-setup.md)). |
+| **Cursor IDE** | `git clone` the repo, `npm install`, then `node scripts/cursor-install.mjs /path/to/your/project` ([guide](docs/cursor-setup.md)). |
+| **Pi** | `pi install npm:session-orchestrator` ([guide](docs/pi-setup.md)). |
 
 ## Quick Start
 
-In Codex, select the corresponding **Session Orchestrator** skill in the picker or use `$session-orchestrator:<command>`; the slash commands below name the shared workflows. For example, bootstrap with `$session-orchestrator:bootstrap`. See [Codex usage](docs/codex-setup.md#usage).
-
-**1. Bootstrap the repo once.** Run `/bootstrap` in your project. It scaffolds the minimum structure and writes `.orchestrator/bootstrap.lock`, which session-start requires before `/session` will run.
+**1. Run `/bootstrap` once in your project.** It creates the minimum structure and writes `.orchestrator/bootstrap.lock`. `/session` refuses to start until that file exists.
 
-**2. Declare a Session Config.** Add a `## Session Config` section to your project's `CLAUDE.md` (Claude Code, Cursor IDE) or `AGENTS.md` (Codex CLI, Pi). See [instruction-file-resolution](skills/_shared/instruction-file-resolution.md) for which file each platform reads. The smallest valid config is seven fields:
+**2. Add a Session Config** to your project's instruction file — `CLAUDE.md` on Claude Code and Cursor, `AGENTS.md` on Codex CLI and Pi ([which file each platform reads](skills/_shared/instruction-file-resolution.md)). These seven fields are enough:
 
 ```yaml
 ## Session Config
@@ -76,146 +57,53 @@ persistence: true
 enforcement: warn
 ```
 
-Everything else is opt-in. Full template: [`docs/session-config-template.md`](docs/session-config-template.md). Canonical types and defaults: [`docs/session-config-reference.md`](docs/session-config-reference.md).
+The first three are the commands `/go` runs between waves and `/close` runs at the end — use whatever your project actually uses. Everything else is opt-in: [full template](docs/session-config-template.md) · [every key, its type and default](docs/session-config-reference.md).
 
-**3. What the first `/session` writes into your repo.** Nothing outside these paths, all plain text, all local:
+**3. Run the loop.**
 
 ```text
-.orchestrator/bootstrap.lock        # written by /bootstrap, the gate for every later run
-.orchestrator/current-session.json  # which session owns this working copy right now
-.orchestrator/session.lock          # heartbeat lock; stops two sessions colliding in one checkout
-.orchestrator/host.json             # host-local identity for peer-session detection
-.orchestrator/metrics/*.jsonl       # append-only session, learning, event and subagent records
-.orchestrator/steering/             # stable product/tech/structure context injected each session
-.claude/STATE.md                    # wave progress and deviations (harness-specific directory)
-```
-
-## A session in three commands
-
-```text
-/session feature    # research + Q&A: inspect git, issues, history, then agree on scope
-/go                 # execute in typed waves sized by session type (feature: 3, deep: 5); quality gate between each
-/close              # verify every item, commit cleanly, file carryover issues for the rest
-```
-
-In Codex, invoke the same loop through the generated command skills:
-
-```text
-$session-orchestrator:session feature
-$session-orchestrator:go
-$session-orchestrator:close
-```
-
-These entries preserve each command's full workflow and prechecks. Codex's native `/goal` is a separate feature. `/plan` and `/evolve` extend the loop, but you can start with just these three.
-
-## Upgrade
-
-```text
-/plugin update session-orchestrator@kanevry     # Claude Code
-```
-
-Restart the harness afterwards, and re-run `npm install` in the plugin directory when the release adds dependencies. On Cursor and the Pi clone fallback, upgrade with `git pull` in your clone followed by the same install script you originally ran. Manage npm-installed Pi packages through Pi's package manager. For Codex, follow the [refresh instructions](docs/codex-setup.md#refresh-and-explicit-cache-invalidation) for your marketplace source, then reload the skill picker or restart Codex.
-
-Session-start tells you when the running copy is behind: `scripts/lib/plugin-update-banner.mjs` compares the version of the code **that is actually loaded** against the published npm version and warns in the session-start banner (minor or major; patch-only updates stay silent). It fails silent: offline, a non-2xx response, or a malformed answer produces *no statement*, never a false "up to date".
-
-Upgrading across a major version: **[docs/migration-v5.md](docs/migration-v5.md)** covers the current release: the agent-status reader API changes and close-time discovery is enabled by default. If upgrading from before v4, also follow **[docs/migration-v4.md](docs/migration-v4.md)** for the removed skills, commands and scripts and their replacements. [docs/migration-v3.md](docs/migration-v3.md) documents the older v2 → v3 path and the shape both guides follow (what changes · prerequisites · per-platform steps · what stays · known issues · rollback).
-
-## Uninstall
-
-Remove the plugin through your harness's own plugin manager: `/plugin` in Claude Code (marketplace entry `session-orchestrator@kanevry`), `codex plugin remove` on Codex CLI ([docs/codex-setup.md](docs/codex-setup.md)), or Pi's package manager for an npm-installed Pi package. On Cursor and the Pi clone fallback, delete the files the installer wrote into your project.
-
-**What stays behind in your repo.** None of it is removed by uninstalling, and all of it is plain text you can delete by hand:
-
-- `.orchestrator/`: `bootstrap.lock`, `metrics/` (your session and learning JSONL records), `policy/`, `steering/`, `runtime/`, `peers/`, `session.lock`
-- `STATE.md` under your harness's state directory (`.claude/STATE.md` on Claude Code; see [Platform support](#platform-support))
-- The `## Session Config` block you added to `CLAUDE.md` / `AGENTS.md`
-- `.claude/rules/*.md` if you vendored the rule library via `/bootstrap --sync-rules`
-
-Deleting `.orchestrator/metrics/` deletes your session history. Telemetry requires explicit consent (see [Data & telemetry](#safety--data--telemetry)). The session-start update check (`scripts/lib/plugin-update-banner.mjs`) makes an anonymous `GET` to the npm registry to compare your installed version against the latest release. Successful results are cached for 24 hours per repo; failed checks can retry at the next session start. Set `SO_DISABLE_UPDATE_CHECK=1` (or `DO_NOT_TRACK=1`) to turn it off.
-
-## Lifecycle and waves
-
-**Plan, Go, Close** describes the working rhythm. Bootstrap once per project, then start a session, execute its agreed scope, and close with evidence.
-
-| Step | What happens | What carries forward |
-|---|---|---|
-| **Plan** | Read the code, issues and prior session. Agree the objective and assign file scopes. | One shared plan and separate responsibilities. |
-| **Go** | Run independent tasks, combine the changes, check the result and fix findings. | Changes with verification evidence. |
-| **Close** | Check the plan against the work, commit the result and record unfinished tasks. | A handover for the next session. |
-
-Housekeeping uses **one** wave. Deep uses **five**; the **ultradeep** profile uses **seven**. Claude Code and Codex can run independent work in parallel. Cursor and Pi execute tasks sequentially. A failing check sends the findings back for correction.
-
-<details>
-<summary>Deep-session stages and the ultradeep profile</summary>
-
-```mermaid
-flowchart LR
-    D[Discovery] --> I[Implementation]
-    I --> P[Integration and polish]
-    P --> Q[Quality checks]
-    Q --> F[Finalization]
+/session feature    # read the repo, propose scope, wait for your correction
+/go                 # execute in waves, check between each
+/close              # verify, commit, file the rest as issues
 ```
 
-The deep session uses Discovery, Impl-Core, Impl-Polish, Quality and Finalization. Checks run between waves, with a full configured quality gate before completion. The diagram shows the successful path, not a guarantee that the first attempt passes.
-
-Ultradeep is a profile over `session-type: deep`, not a fourth session-type value. It runs Research, Code-Discovery, Impl-Core, Impl-Polish, a read-only Review-Panel, Quality and Release, with a coordinator Synthesis-Gate after the first two waves. Downstream tooling still sees `deep`.
-
-`/plan` is optional when you need a PRD or retrospective before a session. `/evolve` deliberately extracts patterns across sessions.
-
-</details>
+On Codex the same three are `$session-orchestrator:session feature`, `$session-orchestrator:go`, `$session-orchestrator:close` ([Codex usage](docs/codex-setup.md#usage)). `/plan` and `/evolve` extend the loop; you can start with just these three.
 
 ## How it works
 
-The workflow starts with the state of the project. The plan records what to change, who handles each part and what counts as verified.
-
 When you type `/session feature`:
 
-1. **Read the project.** Git state, open issues, recent commits, documentation, resource health and prior-session records inform a Session Overview with a recommendation.
-2. **Agree the scope.** Review the proposed work and correct the plan before implementation.
-3. **Assign the work.** The session type determines the wave structure. Each wave has a purpose, declared paths and a result to verify.
-4. **`/go` executes.** Independent agents can work in parallel on Claude Code and Codex; Cursor and Pi execute sequentially. Reviews and checks bring the work back together.
-5. **`/close` verifies and records it.** Check planned items, run the full quality gate, commit the result and record unfinished work as carryover. The coordinator stages files individually.
-
-Two complementary commands round out the loop: **`/plan`** runs *before* a session when you need a PRD or retrospective; **`/evolve`** runs occasionally to surface patterns across sessions and feed them back at the next start.
-
-The system is markdown-driven config plus a thin Node runtime. Skills, commands, and agents are Markdown with YAML frontmatter; `scripts/lib/*.mjs` and `hooks/*.mjs` handle dispatch, validation, and telemetry. Everything is plain text: if something goes wrong, you can read every file and see what happened.
-
-## What you get
+1. **It reads the project.** Git state, open issues, recent commits, documentation, host resources and the records of previous sessions become a Session Overview with one recommendation.
+2. **You correct the scope.** Nothing is implemented until you agree to the plan.
+3. **The work is split into waves.** The session type decides how many: housekeeping 1, feature 3, deep 5, the ultradeep profile 7. Each wave gets a purpose, a list of file paths it may write to, and a result that can be checked.
+4. **`/go` runs it.** Agents whose file scopes do not overlap run at the same time on Claude Code and Codex; Cursor and Pi run them one after another. After each wave the quality gate runs, and anything it reports goes back for correction before the next wave starts.
+5. **`/close` checks and records.** It compares the plan against what happened, runs the full quality gate, commits file by file, and opens issues for whatever was not finished.
 
-Counts measured on 2026-09-07 with the command in brackets:
+**What it writes into your repository**, and nothing else — all of it plain text, all of it local:
 
-- **44 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, UX grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, and audits (`ls -d skills/*/ | grep -v _shared | wc -l`)
-- **26 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/ux-grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …) (`ls commands/*.md | wc -l`)
-- **14 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …) (`ls agents/*.md | wc -l`)
-- **27 hook files across 10 event types** for scope checks, destructive-command policy, templates-first gates and telemetry. Claude Code runs the guard hooks directly; Cursor and Pi bridge supported calls. Codex does not enforce the destructive-command or file-scope guard ([Platform support](#platform-support)) (`ls hooks/*.mjs | wc -l`)
-- **26 rule files** and **18 ADRs** carrying the reasoning behind the mechanisms (`ls .claude/rules/*.md | wc -l`, `ls docs/adr/*.md | wc -l`)
-- **664 vitest test files** covered by the full quality gate and CI; 13,789 static `it()`/`test()` definitions at that measurement, and the runtime total is higher because of parameterised blocks ([methodology](docs/telemetry/telemetry-claims.md)) (`find tests -name '*.test.mjs' | wc -l`); Full Gate 2026-09-09: 16847 passed / 11 skipped / 664 files
-
-**Portable across harnesses by construction.** `scripts/generate-agents-skills.mjs` generates root `AGENTS.md` byte-identical from `CLAUDE.md` and the `.agents/skills/<name>/SKILL.md` mirrors, with spec-legal frontmatter and pointers to canonical instructions. `scripts/generate-codex-skills.mjs` generates the Codex command entrypoints. Plugin validation checks both surfaces. Separate manifests under `.claude-plugin/`, `.codex-plugin/` and `.cursor-plugin/` register each harness's components; see [Codex manifest compatibility](docs/codex-setup.md#manifest-compatibility).
-
-Full component inventory: [`docs/components.md`](docs/components.md). Version history and per-release detail: [CHANGELOG.md](CHANGELOG.md).
-
-## Why this design
-
-- **Typed waves, not one big batch.** Discovery first, so implementers start with shared context. Impl-Core before Impl-Polish, so architecture lands before integrations. Quality runs a *simplification pass* on AI-generated code **before** tests are written; otherwise tests pin the AI patterns into place.
-- **Inter-wave reviews, not just end-of-session.** Catching regressions between waves stops a bad pattern from propagating into later work; the confidence floor filters speculative criticism so only high-signal findings reach you.
-- **State persists across crashes.** `STATE.md` records wave progress and deviations; the next `/session` offers to resume from the last completed wave.
-- **Hook enforcement has a defined platform boundary.** On Claude Code, the active destructive-command hook applies the policy’s blocking and warning rules. With an active compatible scope hook, supported writes outside declared paths warn in `warn` mode and block in `strict` mode; `off` disables scope checking. Cursor and Pi bridge supported events. Both guards are instructions only on Codex ([Platform support](#platform-support)).
-- **Parallel *operator* sessions are treated as a hazard.** Two humans, or two of your own sessions, in the same working copy share one git index, one filesystem, one `STATE.md`. A heartbeat session lock, peer-scope manifests, and the PSA rule set in [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) exist for exactly that axis.
-- **Cross-session learning is opt-in and inspectable.** Every session writes a record; after 5+ sessions `/evolve analyze` extracts confidence-scored patterns you can read and prune. Nothing is hidden.
-- **VCS dual support, no lock-in.** Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.
-
-A comparison with other orchestrators, distinguishing measured results from unmeasured claims: [`docs/components.md` § Comparisons](docs/components.md#comparisons).
+```text
+.orchestrator/bootstrap.lock        # written by /bootstrap, the gate for every later run
+.orchestrator/current-session.json  # which session owns this working copy right now
+.orchestrator/session.lock          # heartbeat lock; stops two sessions colliding in one checkout
+.orchestrator/host.json             # host-local identity for peer-session detection
+.orchestrator/metrics/*.jsonl       # append-only session, learning, event and subagent records
+.orchestrator/steering/             # stable product/tech/structure context injected each session
+.claude/STATE.md                    # wave progress and deviations (harness-specific directory)
+```
 
-## Recent highlights (v5.0.0)
+The plugin is **44 skills, 26 slash commands, 14 typed subagents and 27 hook files across 10 event types**. Skills, commands and agents are Markdown with YAML frontmatter; the code that dispatches, validates and records runs in `scripts/lib/*.mjs` and `hooks/*.mjs`. There is no build step and no compiled artifact — when a session does something you did not expect, you can open the file that decided it. Full inventory: [`docs/components.md`](docs/components.md).
 
-Highlights of the v5.0.0 line:
+## Why it is built this way
 
-- **Agent status carries provenance.** `readCurrentStatus()` returns entries with their source, timestamp and degradation details. Integrations that need the former bare map can use `readCurrentStatusEntries()`. Read the [v5 migration guide](docs/migration-v5.md) before upgrading a deep-import consumer.
-- **Bounded operations use an explicit run contract.** Session-start can coordinate launch preparation, research and community work with a deadline, scoped accounts, one publisher and verified outcomes. It uses the active harness and does not install a background scheduler.
-- **Discovery runs at close by default.** Repos without `discovery-on-close` now receive the close-time scan; set it to `false` to retain the previous behavior. Failed issue creation refunds only a proven budget charge, and agent-status recovery reports stale data instead of silently trusting it.
+- **The wave order is deliberate.** Discovery runs first so every implementer starts from the same picture of the code. Impl-Core runs before Impl-Polish so the structure exists before anything integrates against it. The Quality wave simplifies generated code *before* tests are written — write the tests first and they assert whatever the model produced, so changing it later means rewriting the tests too.
+- **Checks run between waves, not only at the end.** A mistake caught after wave 2 costs one wave. The same mistake found at `/close` has already been copied into every wave after it. Findings below the configured confidence threshold are not shown to you.
+- **A crash does not lose the session.** `STATE.md` records which wave finished and what deviated from the plan. The next `/session` offers to continue from the last completed wave.
+- **Two sessions in one working copy is treated as a real risk.** Two people, or two of your own sessions, in the same checkout share one git index, one filesystem and one `STATE.md`, and neither can see the other's uncommitted work. A heartbeat session lock, per-agent file-scope manifests, and the PSA rules in [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) exist for exactly that case.
+- **Guards run where the harness supports them, and the table below says where it does not.** A destructive-command policy — 10 rules block, 4 warn — and file-scope enforcement run as real hooks on Claude Code, as bridges on Cursor and Pi, and as instructions only on Codex. Details: [`docs/components.md`](docs/components.md#other-surfaces).
+- **What it learns is opt-in and readable.** Every session appends a record. After 5 or more sessions, `/evolve analyze` proposes patterns with a confidence score; you read them and delete the ones you disagree with. Nothing is applied without you.
+- **GitLab and GitHub, both fully.** It detects which one your remote points at and drives issues and merge/pull requests for either.
 
-If upgrading from before 4.0, also read [the v4 migration guide](docs/migration-v4.md). Full changes and verification: [CHANGELOG.md](CHANGELOG.md).
+How this compares to other orchestrators, with measured results kept separate from unmeasured claims: [`docs/components.md` § Comparisons](docs/components.md#comparisons).
 
 ## Platform support
 
@@ -229,86 +117,35 @@ If upgrading from before 4.0, also read [the v4 migration guide](docs/migration-
 | AskUserQuestion | Native tool | Numbered-list fallback | Numbered-list fallback | Numbered-list fallback |
 | Quality gates | Full | Full | Full | Full |
 
-All platforms share the same skills, commands, and scripts; hooks use platform-specific adapters and event subsets. Codex leaves `PreToolUse` handlers empty because these guards do not yet match its tool names and edit payloads. Both the destructive-command and file-scope guards are instructions only there; see [`docs/codex-setup.md`](docs/codex-setup.md#why-our-pretooluse-guards-stay-unwired--the-reason-corrected). Platform detection lives in `scripts/lib/platform.mjs`. Cursor and Pi have known event-coverage limits; see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
-
-## Safety & data & telemetry
-
-**Your data stays in your repo.** Session Orchestrator runs locally, requires no account, and writes its records as append-only JSONL under `.orchestrator/metrics/` in *your* repository: sessions, learnings, events, subagent records. Those files are yours: readable, greppable, deletable. Optional anonymous usage telemetry is **off until you explicitly consent** and is separate from the local records ([docs/telemetry.md](docs/telemetry.md) says exactly what it would collect and how to turn it off). Reported metrics describe *this* repository under its own conditions and will not transfer unchanged to yours ([details](docs/telemetry/telemetry-claims.md)).
-
-**Destructive-command guard.** On Claude Code, the active `hooks/pre-bash-destructive-guard.mjs` applies `.orchestrator/policy/blocked-commands.json` in the main session and in subagent waves. The policy has 10 blocking rules (`git reset --hard`, `rm -rf`, `git push --force`, and more) and 4 warning rules. Cursor and Pi use event bridges with documented limits; Codex does not enforce this guard. Scope `enforcement: warn` or `off` does not change the separate destructive-command policy. See [Platform support](#platform-support). Where the hook is active, bypass it per session only for intentional maintenance:
-
-```yaml
-allow-destructive-ops: true
-```
-
-The rule source of truth is [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) (PSA-003), vendored to consumer repos via `/bootstrap`.
-
-**Import probe.** `hooks/post-edit-import-probe.mjs` (PostToolUse on `Edit`/`Write`/`MultiEdit`) guards the other direction: a hook-reachable helper saved in a broken intermediate state makes *every* Bash/Edit/Write call fail with an internal hook error, host-wide, for every session sharing the working copy. Right after such a file is saved the probe runs ESLint `no-undef` on it (plus a child-process `import()` for `scripts/lib/**`) and reports the blast radius; it never blocks and always exits 0. It only fires for files listed in the committed allowlist [`hooks/_lib/hook-import-set.json`](hooks/_lib/hook-import-set.json), regenerated by `node scripts/generate-hook-import-set.mjs`. Kill switch: `SO_DISABLED_HOOKS=post-edit-import-probe`.
-
-## Troubleshooting
-
-**Codex plugin or hooks not loading.** Start with `codex plugin list --available --json`. Confirm `session-orchestrator@kanevry` is installed, enabled, unique, and at the tracked manifest version; then start a fresh task and review `/hooks`. Remove only the two allowlisted legacy IDs through `codex plugin remove`, and resolve marketplace conflicts through the public marketplace remove/add lifecycle before reinstalling. Any other pre-public plugin/config/cache/hook-state residue is unsupported: do not modify private Codex files; file an issue with `codex --version` plus the public plugin and marketplace list output. Full decision tree: [`docs/codex-setup.md`](docs/codex-setup.md#troubleshooting).
+All four platforms share the same skills, commands and scripts; only the hooks differ, because each harness fires different events. Codex leaves its `PreToolUse` handlers empty because these guards do not yet match its tool names and edit payloads ([why](docs/codex-setup.md#why-our-pretooluse-guards-stay-unwired--the-reason-corrected)). Cursor and Pi have known event-coverage limits — see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
 
-**Node is missing from the hook PATH.** The harness executes hook commands via `/bin/sh -c` with its own PATH. That shell does not source `~/.zshrc`/`~/.bashrc`, so Node installed via Homebrew, nvm, volta, or asdf can be invisible to hooks even though `node` works in your terminal. All hook commands route through [`hooks/run-node.sh`](hooks/run-node.sh), which resolves Node via `$SO_NODE_BIN` → PATH → well-known install dirs → nvm and degrades gracefully: hooks are skipped with **one** warning per 6 hours instead of a shell error on every tool call. Fixes, in order of preference: launch the harness from a shell where `node` resolves; export `SO_NODE_BIN=/abs/path/to/node`; or install Node 24+ to a standard location.
+## Recent highlights (v5.1.0)
 
-**`/session` refuses to start.** It needs `.orchestrator/bootstrap.lock`. Run `/bootstrap` first, or `/bootstrap --retroactive` if the repo already has a `## Session Config` block.
+Highlights of the v5.1.0 line:
 
-## Development
+- **This landing page got shorter.** 314 lines down to 151, 22 sections down to 10, measured against ten comparable repositories. Requirements, upgrade and uninstall moved to [docs/install.md](docs/install.md); the guards and the import probe to [docs/components.md](docs/components.md); what stays on your machine to [docs/telemetry.md](docs/telemetry.md). Nothing was deleted.
+- **The shell-redirect lane into the harness memory directory is closed.** The policy rule `redirect-harness-memory` plus home-anchored denylist matching in `scripts/lib/command-blocker.mjs` cover `> ~/.claude/.../memory/…` and its relative spellings — that directory is injected as trusted context into every later session but sits outside `git diff`, CI review and the leakage scanner.
+- **The scope carve-out is the coordinator's alone.** `hooks/enforce-scope.mjs` no longer lets a dispatched wave agent write `.claude/STATE.md` or overwrite the live `wave-scope.json`. A census over 1069 subagent transcripts and 4385 real write calls found zero legitimate uses, so the narrowing takes nothing away.
 
-```bash
-git clone https://github.com/Kanevry/session-orchestrator.git && cd session-orchestrator
-npm install
-npm test          # vitest
-npm run lint      # ESLint v10 + Prettier
-npm run typecheck # node --check on every .mjs file
-```
-
-`.npmrc` ships with `ignore-scripts=true` (supply-chain defence), so Husky git hooks don't auto-wire on install. Run `npx husky` once after cloning. `git commit` then runs gitleaks → owner-privacy scan → lint-staged → commitlint. CI re-runs everything, plus more.
-
-Two directories share the name *rules* and play opposite roles: [`rules/`](rules/README.md) is the **deliverable rule library** shipped *out* to consumer repos via `/bootstrap --sync-rules`, while [`.claude/rules/`](https://github.com/Kanevry/session-orchestrator/tree/main/.claude/rules/) is this repo's own rule set with always-on and path-scoped entries.
-
-Contributor docs: [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) · [CONTRIBUTING.md](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md) · [sub-agent authoring spec](docs/agent-authoring.md).
-
-## Why I built it
-
-I kept a Notion page with 20–30 prompts for different projects. Before each session I copied the relevant row and explained how I wanted to work again. That routine gradually became Plan, Go, Close. I use it on my Mac M4 and the M5 at the office; Session Orchestrator is the tool that grew out of it.
 
-## Support & scope
-
-Session Orchestrator is provided **as-is**, a community project with no SLA, no commercial support contract, and no guaranteed response time. Maintenance is best-effort.
-
-[Buy me a coffee, if this helped.](https://paypal.me/Kanevry)
-
-- Questions, ideas, show-and-tell → [GitHub Discussions](https://github.com/Kanevry/session-orchestrator/discussions)
-- Bugs and feature requests → [Issues](https://github.com/Kanevry/session-orchestrator/issues)
-
-What it is **not**:
-
-- **Not an official product of any agent vendor.** An independent, community-maintained project, not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Cursor, or any agent it integrates with. (It is distributed through the Claude Code plugin marketplace, but is not an Anthropic product.)
-- **Not a replacement** for Claude Code / Codex CLI / Cursor / Pi. It is a workflow layer that runs *on top of* your existing agent; you still need one of those installed.
-- **Not a multi-user product.** Single-operator by design; the parallel-session machinery protects one operator's concurrent sessions, not a shared team workspace.
+Full changes and verification: [CHANGELOG.md](CHANGELOG.md).
 
 ## Documentation
 
-- [docs/ Router](docs/README.md): living reference vs. public decision history vs. active work documents
-- [User Guide](docs/USER-GUIDE.md): installation, config reference, workflow walkthrough, FAQ
-- [Components & Reference](docs/components.md): full skill/command/agent/hook inventory, repository anatomy, comparisons
-- [Plugin Architecture (v3)](docs/plugin-architecture-v3.md): contributor guide, layering, hook anatomy, testing
-- [Migration to v4](docs/migration-v4.md): upgrade path, removed surfaces and replacements
-- [Telemetry](docs/telemetry.md) · [Telemetry claims](docs/telemetry/telemetry-claims.md): what is collected, how metrics are measured, why they may not transfer
-- [Example Configs](https://github.com/Kanevry/session-orchestrator/tree/main/docs/examples/): Session Config examples for Next.js, Express, Swift
-- [CHANGELOG.md](CHANGELOG.md): version history
-
-We follow [Conventional Commits](https://www.conventionalcommits.org/). See [CONTRIBUTING.md](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md).
+- [User guide](docs/USER-GUIDE.md) — config reference, a walkthrough of one session, troubleshooting, FAQ
+- [Install, upgrade, uninstall](docs/install.md) — requirements, per-harness setup, migration paths
+- [Components & reference](docs/components.md) — every skill, command, agent and hook; the guards; comparisons
+- [Telemetry](docs/telemetry.md) — what stays on your machine, what the optional anonymous telemetry would send, and every switch that turns it off
+- [Contributing](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md) · [Plugin architecture](docs/plugin-architecture-v3.md) · [docs/ router](docs/README.md)
 
-## Learn the method behind it
+## Scope and support
 
-This plugin is a methodology turned into code. The reasoning behind it is taught hands-on at **[agenticbuilders.at](https://agenticbuilders.at)**: [Multi-Agent Orchestration](https://agenticbuilders.at/orchestrierung) and [Loop Engineering](https://agenticbuilders.at/loop-engineering). The courses cover why execution runs in waves, why each wave ends at a verification gate, and how to make an autonomous loop that finishes. The plugin is free and MIT; the courses are for going deeper, not a requirement for using it.
+Provided **as-is**: a community project, best-effort maintenance, no SLA. Questions and ideas go to [Discussions](https://github.com/Kanevry/session-orchestrator/discussions), bugs to [Issues](https://github.com/Kanevry/session-orchestrator/issues).
 
-## Links
+It is **not** an official product of any agent vendor — independent and community-maintained, not affiliated with, endorsed by or sponsored by Anthropic, OpenAI, Cursor or any agent it integrates with, and distributed through the Claude Code plugin marketplace without being an Anthropic product. It does **not replace** your agent; it runs on top of one, and you still need it installed. It is built for **one operator**: the parallel-session machinery protects your own concurrent sessions, not a shared team workspace.
 
-[Homepage](https://session-orchestrator.com) (also at [/de](https://session-orchestrator.com/de) in German, with the workflow, installation paths and platform limits) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy) · [npm](https://www.npmjs.com/package/session-orchestrator)
+The reasoning behind the method is taught at [agenticbuilders.at](https://agenticbuilders.at). The plugin is free and MIT; the courses go deeper and are not required to use it.
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE) · [Privacy policy](https://gotzendorfer.at/en/session-orchestrator/privacy) · [npm](https://www.npmjs.com/package/session-orchestrator)

package/docs/USER-GUIDE.md

@@ -1406,6 +1406,30 @@ For Claude Code, run these commands inside a Claude Code session, not in your sh
 /plugin install session-orchestrator@kanevry
 ```
 
+### Node is missing from the hook PATH
+
+The harness executes hook commands via `/bin/sh -c` with its own PATH. That
+shell does not source `~/.zshrc`/`~/.bashrc`, so Node installed via Homebrew,
+nvm, volta, or asdf can be invisible to hooks even though `node` works in your
+terminal.
+
+All hook commands route through
+[`hooks/run-node.sh`](https://github.com/Kanevry/session-orchestrator/blob/main/hooks/run-node.sh),
+which resolves Node via `$SO_NODE_BIN` → PATH → well-known install dirs → nvm
+and degrades gracefully: hooks are skipped with **one** warning per 6 hours
+instead of a shell error on every tool call.
+
+Fixes, in order of preference:
+
+1. Launch the harness from a shell where `node` resolves.
+2. Export `SO_NODE_BIN=/abs/path/to/node`.
+3. Install Node 24+ to a standard location.
+
+### `/session` refuses to start
+
+It needs `.orchestrator/bootstrap.lock`. Run `/bootstrap` first, or
+`/bootstrap --retroactive` if the repo already has a `## Session Config` block.
+
 ### "tsgo: command not found"
 
 The default typecheck command is `npm run typecheck`. If your project's `typecheck` script invokes `tsgo`, install it or change `typecheck-command` to the runner your project actually uses:

package/docs/components.md

@@ -52,6 +52,8 @@ Codex uses the curated six-event project subset `SessionStart`, `PreToolUse`, `P
 
 - **Output Styles (3):** `session-report`, `wave-summary`, `finding-report`.
 - **Policy & rules:** `.orchestrator/policy/blocked-commands.json` (destructive-command rules); `.claude/rules/parallel-sessions.md` (PSA-001..PSA-004).
+- **Destructive-command guard.** On Claude Code, the active `hooks/pre-bash-destructive-guard.mjs` applies `.orchestrator/policy/blocked-commands.json` in the main session and in subagent waves. The policy has 10 blocking rules (`git reset --hard`, `rm -rf`, `git push --force`, and more) and 4 warning rules. Cursor and Pi use event bridges with documented limits; Codex does not enforce this guard. Scope `enforcement: warn` or `off` does not change the separate destructive-command policy — see [Platform support](../README.md#platform-support). Where the hook is active, bypass it per session only for intentional maintenance by setting `allow-destructive-ops: true` in Session Config. The rule source of truth is [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) (PSA-003), vendored to consumer repos via `/bootstrap`.
+- **Import probe.** `hooks/post-edit-import-probe.mjs` (PostToolUse on `Edit`/`Write`/`MultiEdit`) guards the other direction: a hook-reachable helper saved in a broken intermediate state makes *every* Bash/Edit/Write call fail with an internal hook error, host-wide, for every session sharing the working copy. Right after such a file is saved the probe runs ESLint `no-undef` on it (plus a child-process `import()` for `scripts/lib/**`) and reports the blast radius; it never blocks and always exits 0. It only fires for files listed in the committed allowlist [`hooks/_lib/hook-import-set.json`](../hooks/_lib/hook-import-set.json), regenerated by `node scripts/generate-hook-import-set.mjs`. Kill switch: `SO_DISABLED_HOOKS=post-edit-import-probe`.
 - **Codex:** `.codex-plugin/plugin.json` (tracked `+codex.<UTC timestamp>` version), generated command and skill entrypoints under `.codex-plugin/skills/`, compatibility config, agent role definitions, and the public marketplace/add/list lifecycle implemented by `scripts/codex-install.mjs`. `scripts/generate-codex-skills.mjs` produces the name union with commands taking precedence; [Codex usage](codex-setup.md#usage) explains selection. Every installer run refreshes via `plugin add`; hook trust remains an operator decision in a fresh task through `/hooks`.
 - **Cursor:** `.cursor-plugin/plugin.json` registers canonical skills and `.mcp.json` using Cursor's native manifest format. Additional native component discovery is explicitly disabled; `scripts/cursor-install.mjs` supplies the existing command and hook adapters. The former standard root manifest was moved to prevent [Codex manifest interception](codex-setup.md#manifest-compatibility).
 - **Pi:** `package.json` `pi` manifest, `pi/extensions/session-orchestrator.ts` bridge, `hooks/hooks-pi.json`, `scripts/pi-install.mjs`.