session-orchestrator 3.16.0

package/docs/owner-config-schema.md

@@ -0,0 +1,154 @@
+# Owner Persona Schema (`owner.yaml`)
+
+> Per-user configuration for the session-orchestrator plugin. Lives at
+> `~/.config/session-orchestrator/owner.yaml`. Never committed to a project repo.
+>
+> Issue [#174](../../../-/issues/174) — D1 of Sub-Epic [#161](../../../-/issues/161) (Owner Persona Layer).
+> Parent epic: [#157](../../../-/issues/157) (v3.1.0 Environment-Aware Sessions).
+
+## Path Resolution
+
+The loader (`scripts/lib/owner-config-loader.mjs`) resolves the canonical path as:
+
+```
+${XDG_CONFIG_HOME ?? <homedir>/.config}/session-orchestrator/owner.yaml
+```
+
+| Platform   | Default path                                            |
+|------------|---------------------------------------------------------|
+| macOS      | `~/.config/session-orchestrator/owner.yaml`             |
+| Linux      | `${XDG_CONFIG_HOME:-~/.config}/session-orchestrator/owner.yaml` |
+| Windows    | `%USERPROFILE%\.config\session-orchestrator\owner.yaml` |
+
+A missing file is **not an error** — it signals the user has not opted in.
+The loader returns `{ok: false, source: 'missing'}` in that case and consumers
+fall back to plugin defaults.
+
+## Schema (`schema-version: 1`)
+
+| Section / Field                          | Type                          | Required | Default       | Notes                                              |
+|------------------------------------------|-------------------------------|----------|---------------|----------------------------------------------------|
+| `schema-version`                         | integer                       | yes      | —             | Must equal `1`.                                    |
+| `owner.name`                             | string (1-100)                | yes      | —             | Display name.                                      |
+| `owner.email-hash`                       | hex (64 chars) or `null`      | no       | `null`        | SHA256 of email; cross-host identity correlation.  |
+| `owner.language`                         | ISO-639-1 (`de`, `en`, ...)   | yes      | —             | Drives soul.md default language.                   |
+| `tone.style`                             | `direct\|neutral\|friendly`   | no       | `neutral`     |                                                    |
+| `tone.tonality`                          | string (≤200) or `null`       | no       | `null`        | Free-form descriptor.                              |
+| `efficiency.output-level`                | `lite\|full\|ultra`           | no       | `full`        | Caveman-inspired token dial.                       |
+| `efficiency.preamble`                    | `minimal\|verbose`            | no       | `minimal`     | Pre-tool-call narration.                           |
+| `efficiency.comments-in-code`            | `minimal\|full`               | no       | `minimal`     | Inline code comments.                              |
+| `hardware-sharing.enabled`               | boolean                       | no       | `false`       | Consent gate for hardware-pattern export.          |
+| `hardware-sharing.hash-salt`             | hex (64 chars) or `null`      | no       | `null`        | Per-host random salt. Required when `enabled=true`.|
+| `defaults.preferred-test-command`        | string (≤200) or `null`       | no       | `null`        | Override CLAUDE.md `test-command`.                 |
+| `defaults.preferred-editor`              | string (≤50) or `null`        | no       | `null`        |                                                    |
+| `metadata.created_at`                    | ISO 8601 string or `null`     | no       | `null`        | Auto-set on first write.                           |
+| `metadata.updated_at`                    | ISO 8601 string or `null`     | no       | `null`        | Auto-bumped on every save.                         |
+
+### Privacy Contract
+
+- `hardware-sharing.enabled = true` **requires** `hardware-sharing.hash-salt`
+  to be a valid 64-char hex string. The validator rejects `enabled=true` with
+  `hash-salt=null` so consent is never recorded without the means to
+  anonymise per-host learnings.
+- `owner.email-hash` is the only field carrying potential cross-host identity;
+  it is hashed (never plaintext email) and remains optional.
+
+## Example
+
+See [`scripts/lib/owner-config.example.yaml`](../scripts/lib/owner-config.example.yaml)
+for an annotated, copyable example.
+
+## API Surface
+
+`scripts/lib/owner-config.mjs` (pure, no I/O):
+
+```js
+import { validate, coerce, defaults, merge } from './scripts/lib/owner-config.mjs';
+
+// Defensive, never throws. Use this in skill code paths.
+const result = validate(rawObj);
+//   → { ok: true, value: <normalized>, errors: [] }
+//   → { ok: false, value: null, errors: ["owner.name must be ..."] }
+
+// Strict mode: throws OwnerConfigError on failure. Use in tests / CLI.
+const value = coerce(rawObj);
+
+// Default-filled config. owner.name and owner.language remain blank
+// (the bootstrap interview in D2 fills them in).
+const def = defaults();
+
+// Deep-merge two configs. `override` wins on every defined leaf.
+const merged = merge(baseFromOwnerYaml, perSessionOverrides);
+```
+
+`scripts/lib/owner-config-loader.mjs` (filesystem I/O):
+
+```js
+import { loadOwnerConfig, resolveOwnerConfigPath } from './scripts/lib/owner-config-loader.mjs';
+
+const result = await loadOwnerConfig();
+// {
+//   ok: true|false,
+//   value: <normalized> | null,
+//   errors: string[],
+//   source: 'file' | 'missing' | 'parse-error' | 'validation-error',
+//   path: '<absolute path>',
+// }
+
+// Test override
+const result2 = await loadOwnerConfig({ path: '/tmp/test-owner.yaml' });
+```
+
+## Where this gets read
+
+D1 only ships the schema + validator + loader. The downstream tasks consume
+these primitives:
+
+- **[#175 D2](../../../-/issues/175) — bootstrap interview**: writes the file via
+  `coerce()` then a YAML serializer, stamping `metadata.created_at` /
+  `metadata.updated_at`.
+- **[#176 D3](../../../-/issues/176) — `soul.md` runtime-merge**: calls
+  `loadOwnerConfig()` from the session-start hook, then `merge()` with any
+  per-session overrides, then resolves `{{tone.style}}` /
+  `{{efficiency.output-level}}` / `{{owner.language}}` template slots.
+- **#177 D4 — projects-baseline propagation**: stamps a
+  reference to the canonical path into every consumer repo's CLAUDE.md
+  frontmatter (path reference only — never the content).
+- **[#168 C4](../../../-/issues/168) — hardware-sharing consent prompt**: writes
+  `hardware-sharing.enabled = true` + a freshly-generated `hash-salt` after
+  the user accepts the consent dialogue.
+
+## Validation Rules (rejection examples)
+
+```yaml
+# REJECTED — schema-version missing
+owner: { name: x, language: en }
+
+# REJECTED — schema-version mismatch (refuses to load future versions)
+schema-version: 2
+owner: { name: x, language: en }
+
+# REJECTED — name empty
+schema-version: 1
+owner: { name: "", language: en }
+
+# REJECTED — language not ISO-639-1
+schema-version: 1
+owner: { name: x, language: "english" }
+
+# REJECTED — enum violation
+schema-version: 1
+owner: { name: x, language: en }
+tone: { style: "snarky" }
+
+# REJECTED — privacy contract: enabled=true without hash-salt
+schema-version: 1
+owner: { name: x, language: en }
+hardware-sharing: { enabled: true }
+
+# ACCEPTED — minimal valid config
+schema-version: 1
+owner:
+  name: Bernhard
+  language: de
+```

package/docs/persona-panel.md

@@ -0,0 +1,433 @@
+# /persona-panel — Multi-Persona Content Review
+
+> Standalone skill + command for running N domain-expert, buyer-persona, or compliance personas
+> against a target artifact in parallel, with deterministic consolidation, hard-gate semantics,
+> and timestamped sidecar records for audit and trend-tracking.
+
+## When to use
+
+- Reviewing a research statement or technical document from multiple expert angles simultaneously
+  (e.g. a climate-research brief reviewed by a physicist and an AI expert)
+- Validating AI-generated accountant output from a domain-expert lens plus a compliance lens
+  before presenting it to a client
+- Running a Buyer-Panel Hard-Gate on a B2B product landing page: all N buyer personas must PASS
+  before the page goes live
+- Any "Multi-Pair-of-Eyes" review where you want structured, auditable output from N perspectives
+  without manually prompting each reviewer in turn
+
+The panel runs personas **in parallel** — wall-clock time is roughly the slowest single persona,
+not N times the slowest.
+
+---
+
+## Quick Start
+
+### 1. Create the catalog directory
+
+```bash
+mkdir -p .claude/personas
+```
+
+### 2. Copy a starter template
+
+Templates ship with the plugin at `templates/personas/`. Copy one as a starting point:
+
+```bash
+cp "$(claude plugin dir session-orchestrator)/templates/personas/klima-physicist.v1.md" \
+   .claude/personas/klima-physicist.md
+```
+
+Edit the file: update `name`, `role`, `evaluation_criteria`, and the `## Mission` body section
+to match your reviewer's perspective.
+
+### 3. Confirm the catalog loads
+
+```bash
+/persona-panel docs/research/my-draft.md --dry-run
+```
+
+`--dry-run` resolves the catalog and prints the planned dispatch list without making any Agent
+calls or writing any sidecar. Use it to verify setup before a real run.
+
+### 4. Run the panel
+
+```bash
+/persona-panel docs/research/my-draft.md
+```
+
+The command dispatches one agent per persona in parallel, consolidates verdicts using the
+default voting mode, and prints a Markdown table summary to stdout. A timestamped sidecar is
+written to `.orchestrator/persona-panel/`.
+
+---
+
+## Reference Examples
+
+### Example 1 — Research Statement Review (klima, 2-persona panel)
+
+**Scenario:** A climate-research brief (`wfk-2.1.5.md`) needs sign-off from a domain physicist
+and an AI/ML expert before it is submitted. Both must agree.
+
+**Catalog files:** `.claude/personas/klima-physicist.md`,
+`.claude/personas/klima-ai-expert.md`
+
+```bash
+/persona-panel docs/research/wfk-2.1.5.md \
+  --personas klima-physicist,klima-ai-expert \
+  --mode voting \
+  --threshold 2-of-2
+```
+
+The `2-of-2` threshold means both personas must return `pass`. A single `fail` or `warn` from
+either produces a final `fail` verdict.
+
+**Typical stdout output:**
+
+```
+Dispatching 2 persona agents in parallel. Target: .../docs/research/wfk-2.1.5.md. Mode: voting.
+
+## Persona Panel Report
+
+Target: docs/research/wfk-2.1.5.md
+Personas: 2 invoked | Mode: voting (threshold: 2-of-2)
+Final verdict: PASS
+
+| Persona          | Tier          | Verdict | Rationale (excerpt)                          |
+|------------------|---------------|---------|----------------------------------------------|
+| klima-physicist  | domain-expert | pass    | Physical assumptions consistent with AR6 ... |
+| klima-ai-expert  | domain-expert | pass    | Model claims grounded, no hallucinated ...   |
+
+Dissenting: none
+Sidecar: .orchestrator/persona-panel/2026-05-20T14-30-00Z-a1b2c3d4.json
+```
+
+**Sidecar excerpt:**
+
+```json
+{
+  "run_id": "a1b2c3d4",
+  "target": "/abs/path/docs/research/wfk-2.1.5.md",
+  "personas_invoked": [
+    { "name": "klima-physicist", "version": "2", "model": "claude-opus-4-7", ... },
+    { "name": "klima-ai-expert",  "version": "1", "model": "claude-opus-4-7", ... }
+  ],
+  "consolidation": {
+    "mode": "voting-quorum",
+    "final_verdict": "pass",
+    "pass_count": 2,
+    "fail_count": 0,
+    "dissenting_personas": []
+  }
+}
+```
+
+---
+
+### Example 2 — Buyer-Panel Hard-Gate (products/example-app)
+
+**Scenario:** A landing page component must pass review from all 6 buyer personas before the
+copy is considered launch-ready. One `fail` blocks the whole gate.
+
+**Catalog files:** `.claude/personas/` contains
+`buyer-p1-cto.md` through `buyer-p6-*.md`.
+
+```bash
+/persona-panel src/landing-page.tsx --mode hard-gate --threshold all
+```
+
+Because `--threshold all` is the default for `hard-gate`, this is equivalent to:
+
+```bash
+/persona-panel src/landing-page.tsx --mode hard-gate
+```
+
+**If 5 of 6 personas pass (one fails):**
+
+```
+Consolidation (hard-gate-threshold): 5 pass / 1 fail / 0 warn — Final: FAIL
+Dissenting: buyer-p3-kanzlei
+
+## Persona Panel Report
+
+Target: src/landing-page.tsx
+Personas: 6 invoked | Mode: hard-gate (threshold: all)
+Final verdict: FAIL
+
+| Persona                       | Tier          | Verdict | Rationale (excerpt)                    |
+|-------------------------------|---------------|---------|----------------------------------------|
+| buyer-p1-cto     | buyer-persona | pass    | Value proposition clear for CTO ...   |
+| buyer-p2-kanzlei | buyer-persona | pass    | Compliance language acceptable ...    |
+| buyer-p3-kanzlei | buyer-persona | fail    | DSGVO section too vague for ...       |
+| ...                           | ...           | pass    | ...                                   |
+
+Dissenting: buyer-p3-kanzlei
+Sidecar: .orchestrator/persona-panel/2026-05-20T16-00-00Z-b2c3d4e5.json
+```
+
+The command exits with code 1. CI pipelines and wave-executor hooks can gate on this exit code.
+
+**To re-run after revisions:**
+
+```bash
+# After fixing the DSGVO section:
+/persona-panel src/landing-page.tsx --mode hard-gate --threshold all
+```
+
+---
+
+### Example 3 — AI Accountant Output Compliance Review (accounting)
+
+**Scenario:** An AI accountant (Sophie) produces invoice analysis JSON. A tax-advisor persona
+and a DSGVO-compliance persona must both approve before the output is delivered to the client.
+
+**Catalog files:** `.claude/personas/accounting-tax-advisor.md`,
+`.claude/personas/accounting-compliance.md`
+
+```bash
+/persona-panel sophie-outputs/2026-05-19/invoice-12345.json \
+  --personas accounting-tax-advisor,accounting-compliance \
+  --mode voting \
+  --threshold 2-of-2
+```
+
+If the compliance persona returns `warn` (not `fail`), the tax-advisor returns `pass`, and the
+threshold is `2-of-2` (pass-only):
+
+```
+Consolidation (voting-quorum): 1 pass / 0 fail / 1 warn — Final: FAIL
+Dissenting: accounting-compliance (warn treated as non-pass under 2-of-2 threshold)
+```
+
+`warn` counts as a non-pass vote for quorum purposes. The sidecar records the full rationale
+and recommendations from the compliance persona so the issue can be addressed specifically.
+
+**Dry-run before dispatching (recommended for expensive Opus calls):**
+
+```bash
+/persona-panel sophie-outputs/2026-05-19/invoice-12345.json \
+  --personas accounting-tax-advisor,accounting-compliance \
+  --dry-run
+```
+
+---
+
+## Configuration
+
+### Catalog directory structure
+
+```
+.claude/personas/
+  klima-physicist.md
+  klima-ai-expert.md
+  accounting-tax-advisor.md
+  accounting-compliance.md
+  buyer-p1-cto.md
+  buyer-p2-kanzlei.md
+```
+
+Each file is a Markdown document with YAML frontmatter. All six frontmatter fields are required.
+
+### Persona file structure
+
+Full specification: `skills/persona-panel/persona-format.md`. Minimum shape:
+
+```yaml
+---
+name: my-reviewer
+schema_version: 1
+version: "1"
+role: "Domain expert in [field] — evaluates [aspect] of the target"
+model: claude-opus-4-7
+tier: domain-expert
+output_contract:
+  type: object
+  required: [verdict, rationale]
+  properties:
+    verdict:
+      type: string
+      enum: [pass, fail, warn]
+    rationale:
+      type: string
+      maxLength: 4096
+    recommendations:
+      type: array
+      items:
+        type: string
+evaluation_criteria:
+  - "Claim X is accurate and verifiable"
+  - "No contradictions with established standard Y"
+---
+
+## Mission
+
+You are [role]. Your goal is to review the target and determine whether it meets the standards
+defined in your evaluation criteria. Return a structured verdict.
+
+## Context Files
+
+None.
+
+## Evaluation Criteria
+
+[Expanded prose descriptions matching the frontmatter criteria.]
+
+## Output Template
+
+\```json
+{
+  "verdict": "pass|fail|warn",
+  "rationale": "Detailed rationale (max 4096 chars).",
+  "recommendations": []
+}
+\```
+```
+
+### Tier values
+
+| Tier | Typical use |
+|---|---|
+| `domain-expert` | Technical reviewers: physicist, AI expert, legal, medical |
+| `buyer-persona` | Buyer-panel hard-gates: CTO, procurement, compliance officer |
+| `compliance` | DSGVO, SEC, HIPAA, ISO reviewers |
+| `custom` | Any other structured reviewer |
+
+`domain-expert` and `compliance` tiers default to `claude-opus-4-7` for model selection
+(Opus finds real issues Sonnet misses — see vault learning `[[persona-opus-finds-real-failing-cibadge]]`).
+
+### output_contract security rules
+
+The `output_contract` field in each persona's YAML frontmatter is compiled by AJV at catalog
+load time. Three structural rules are enforced before compilation:
+
+- `$ref`, `$defs`, `allOf`, `anyOf` are **forbidden** — they enable attacker-controlled schema
+  complexity attacks (ReDoS via pathological schemas)
+- The schema MUST declare `verdict` in its `required` array
+- The AJV compile call is wrapped in a 2-second AbortSignal timeout
+
+A persona with a forbidden key in `output_contract` is rejected at Phase 1 (catalog load) with
+an informative error. Fix the frontmatter before running the panel.
+
+---
+
+## Consolidation Modes
+
+Three modes are available via `--mode`:
+
+| Mode | Flag | Deterministic | Extra LLM call |
+|---|---|---|---|
+| `voting` | `--mode voting` | Yes | No |
+| `hard-gate` | `--mode hard-gate` | Yes | No |
+| `summary` | `--mode summary` | No | Yes (coordinator aggregate) |
+
+**`voting` (default):** Counts PASS verdicts against `--threshold`. Suitable for panels where
+a majority or supermajority is sufficient.
+
+**`hard-gate`:** All N personas must return PASS. Any single FAIL (or WARN) produces FAIL.
+Exit code 1 on FAIL — suitable for CI gates and wave-executor integration.
+
+**`summary`:** Coordinator LLM aggregates heterogeneous outputs into a narrative. Emits a
+warning before dispatch: `summary mode adds one additional LLM call`. Use voting or hard-gate
+for cost-sensitive pipelines.
+
+### Threshold spec
+
+The `--threshold` flag accepts:
+
+- `M-of-N` — e.g. `2-of-3`, `5-of-6`. M and N are integers 1..20.
+- `all` — equivalent to `N-of-N`. Default for `hard-gate`.
+- `any` — first PASS is sufficient. Unusual; use with care.
+
+Default when omitted: `all`.
+
+---
+
+## Wave-Gate Integration (Issue #458)
+
+After issue #458 ships, `persona-panel` can be configured as an inter-wave gate inside
+`wave-executor`. A `persona-gate-wave` block in Session Config (in `CLAUDE.md` or `AGENTS.md`)
+will run the panel automatically after the Quality wave:
+
+```yaml
+persona-gate-wave:
+  enabled: true
+  after: quality
+  threshold: all
+  mode: strict
+```
+
+Cross-reference: `docs/session-config-reference.md` will gain a `persona-gate-wave` section
+when #458 is implemented. Until then, run `/persona-panel` manually between waves or at
+session-end.
+
+---
+
+## Security Notes
+
+**Per-repo catalog only.** The `.claude/personas/` directory is per-repo and never stored in
+the plugin. This is intentional: climate-research repos need physicists; SaaS repos need buyer
+personas; compliance repos need auditors. A plugin-central catalog would block that diversity.
+
+**Flat output_contract schemas.** The `output_contract` in each persona's YAML frontmatter must
+be a flat inline JSON Schema Draft 2020-12 object. The keywords `$ref`, `$defs`, `allOf`, and
+`anyOf` are forbidden. This guards against pathological schemas that could cause the AJV
+compiler to hang (schema-complexity DoS).
+
+**Sidecar path confinement.** Sidecar files are written exclusively to
+`.orchestrator/persona-panel/` inside the project root. The path is validated via
+`validatePathInsideProject` from `scripts/lib/path-utils.mjs` before any write. Sidecars
+cannot be written outside the repo boundary.
+
+**Model field validation.** Each persona's `model:` field is validated at catalog load time
+against `MODEL_ID_RE` and `ALLOWED_MODEL_ALIASES` from `scripts/lib/agent-frontmatter.mjs`. A
+persona declaring an unrecognized model string is rejected with an informative error.
+
+**Concurrency cap.** A maximum of 20 personas can run in a single panel invocation. If the
+active set exceeds 20, the run is truncated alphabetically and a warning is emitted.
+
+---
+
+## Trend Tracking (Future — Issue #459)
+
+Issue #459 will add a `--trend` sub-command that compares sidecar records across runs and flags
+verdict drift (a persona that was passing now fails, or vice versa). The `prompt_hash` field in
+each sidecar entry — a sha256 over the canonicalized persona inputs — enables detecting whether
+a change in persona content or model caused the drift, or whether the target artifact changed.
+
+Trend tracking is data-gated on at least 3 runs against the same target with the same persona
+set. It will not be useful before that threshold.
+
+---
+
+## Sidecar Location
+
+All runs write a JSON sidecar to:
+
+```
+.orchestrator/persona-panel/<isoTimestamp>-<runId>.json
+```
+
+Example: `.orchestrator/persona-panel/2026-05-20T14-30-00Z-a1b2c3d4.json`
+
+The sidecar schema is at `agents/schemas/persona-panel-sidecar.schema.json` (AJV Draft
+2020-12). The file is written atomically via `writeJsonAtomic()` from `scripts/lib/io.mjs`
+(tmp-then-rename, prevents partial writes). Schema validation runs against the sidecar object
+before write — an invalid sidecar causes exit 1, nothing is written.
+
+Add `.orchestrator/persona-panel/` to `.gitignore` to keep run records out of version control,
+or commit them if you want an auditable history.
+
+---
+
+## See Also
+
+- `commands/persona-panel.md` — command reference: argument syntax, flag validation, examples
+- `skills/persona-panel/SKILL.md` — full skill spec: 6 phases, catalog format, dispatch
+  mechanics, consolidation logic, sidecar schema
+- `skills/persona-panel/persona-format.md` — persona file format specification: frontmatter
+  fields, body sections, verdict contract, security rationale for criteria delimiters
+- `templates/personas/*.v1.md` — 6 catalog templates: `klima-physicist`, `klima-ai-expert`,
+  `accounting-tax-advisor`, `accounting-compliance`, `buyer-p1-cto`,
+  `buyer-p2-kanzlei`
+- `agents/schemas/persona-panel-sidecar.schema.json` — sidecar JSON Schema (Draft 2020-12)
+- Issue #457 (foundation), #458 (wave-hook integration), #459 (trend tracking), #460 (catalog
+  templates)

package/docs/pi-setup.md

@@ -0,0 +1,115 @@
+# Pi Setup Guide
+
+Guide for using Session Orchestrator with [Pi](https://pi.dev/docs/latest).
+
+## Prerequisites
+
+- Pi installed: `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`
+- Node.js 24 or later for this repository's hook/runtime scripts
+- A project repository with git initialized
+
+## Installation
+
+### Option 1: npm package (primary, once published)
+
+```bash
+pi install npm:session-orchestrator
+```
+
+This is the primary install path once the package has been published to npm and indexed by the [Pi packages gallery](https://pi.dev/packages) via its `pi-package` keyword — no local checkout required. Not yet available: the package has not been published to npm yet (see `docs/distribution/npm-publish-checklist.md` for the operator publish runbook). Until then, use one of the dev-fallback options below.
+
+### Option 2: Project-local registration (dev fallback)
+
+```bash
+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
+```
+
+This writes `/path/to/your/project/.pi/settings.json` with a `packages` entry pointing at the local checkout. Restart or reload Pi after registration.
+
+If you want Pi's native package installer to do the registration as well:
+
+```bash
+cd /path/to/your/project
+pi install ~/Projects/session-orchestrator -l
+```
+
+### Option 3: Global registration (dev fallback)
+
+```bash
+cd ~/Projects/session-orchestrator
+node scripts/pi-install.mjs --global --settings-only
+```
+
+Global mode writes `~/.pi/agent/settings.json`.
+
+## Configuration
+
+Pi reads `AGENTS.md` and `CLAUDE.md` natively. For Session Orchestrator on Pi, prefer `AGENTS.md` when creating a new project file; existing `CLAUDE.md` files continue to work via the shared alias rule.
+
+Add a `## Session Config` section:
+
+```markdown
+## Session Config
+
+agents-per-wave: 6
+waves: 5
+persistence: true
+enforcement: warn
+test-command: npm test
+typecheck-command: npm run typecheck
+lint-command: npm run lint
+```
+
+## What Loads
+
+The package manifest in `package.json` exposes:
+
+- `pi.extensions`: `./pi/extensions/session-orchestrator.ts`
+- `pi.skills`: `./skills`
+- `pi.prompts`: `./pi/prompts/*.md` generated from `commands/*.md`
+
+The extension uses `hooks/hooks-pi.json` and `scripts/lib/pi-hook-bridge.mjs` to translate Pi events into the existing hook stdin contract.
+
+## Hook Coverage
+
+| Pi event | Session Orchestrator equivalent | Status |
+|---|---|---|
+| `session_start` | `SessionStart` | enabled |
+| `session_shutdown` | `SessionEnd` | enabled |
+| `tool_call` | `PreToolUse` | enabled for `bash`, `edit`, `write` |
+| `tool_result` | `PostToolUse` | enabled |
+| `agent_end` | `Stop` | enabled |
+
+Not yet mapped in v1: `PostToolUseFailure`, `PostToolBatch`, `SubagentStart`, `SubagentStop`, and `CwdChanged`.
+
+## Usage
+
+After reload, use the same commands:
+
+- `/session [housekeeping|feature|deep]`
+- `/go`
+- `/close`
+- `/plan [new|feature|retro]`
+- `/discovery [scope]`
+- `/evolve [analyze|review|list]`
+
+## Differences From Claude Code And Codex
+
+| Aspect | Claude Code | Codex | Pi |
+|---|---|---|---|
+| Package format | Claude plugin manifest | Codex plugin manifest | `package.json.pi` package |
+| Config file | `CLAUDE.md` | `AGENTS.md` | `AGENTS.md` preferred; `CLAUDE.md` supported |
+| State directory | `.claude/` | `.codex/` | `.pi/` |
+| Tool guard event | `PreToolUse` | `PreToolUse` | `tool_call` bridge |
+| Agent dispatch | Native Agent tool | Codex subagents / typed roles | Sequential v1 |
+
+## Troubleshooting
+
+- **Prompts or skills not visible**: verify the project is trusted in Pi, then restart or reload.
+- **Package not loaded**: confirm `.pi/settings.json` or `~/.pi/agent/settings.json` contains the local checkout path under `packages`.
+- **Hooks not firing**: confirm `package.json` still has the `pi.extensions` entry and `hooks/hooks-pi.json` exists.
+- **Config ignored**: ensure the file has a `## Session Config` header in `AGENTS.md` or `CLAUDE.md`.
+- **Runtime error from hooks**: run `npm install` in the Session Orchestrator checkout so hook dependencies are present.