pi-crew 0.11.1 → 0.11.2

package/README.md

@@ -1,82 +1,49 @@
 # pi-crew
 
-> ## ⚠️ IMPORTANT — Read before using
->
-> **pi-crew is a sub-agent orchestration layer that was developed almost entirely
-> by AI, for the author's own workflow.** It is **not** a hardened, audited
-> product. Here's the honest framing:
->
-> - **AI-generated code, limited human review.** The vast majority of pi-crew
->   was written and iterated on by autonomous AI agents. While every change
->   goes through static review + runtime tests, I (the author) have not
->   line-by-line verified everything. There will be bugs, edge cases, and
->   behaviors I haven't anticipated.
-> - **It can spawn processes, run shell commands, and write files on your
->   behalf.** Dynamic workflows (`.dwf.ts`) and goal loops run with the same
->   privileges as your Pi session — treat any `.dwf.ts` like `node script.js`
->   you downloaded from the internet.
-> - **Built for *my* needs, not yours.** This scratches a personal itch. It
->   likely won't fit every workflow, team setup, or risk tolerance — and
->   that's fine.
->
-> **If that sounds too risky, don't use it** — no hard feelings.
->
-> **If you still want to use it**, the safest path is to **fork it, read the
->   parts you'll touch, and adapt it to your own setup.** If you find a bug,
->   a footgun, or a sharp edge, please open an issue or send a note — your
->   feedback is genuinely appreciated. Thanks. ✌️
->
-> See also: [SECURITY-ISSUES.md](docs/bugs/SECURITY-ISSUES.md),
-> [docs/dynamic-workflows.md](docs/dynamic-workflows.md#security-model-important)
-> (trust model), and the [Known limitations](#known-limitations) section below.
-
-**Coordinate AI agent teams inside [Pi](https://github.com/nicekate/pi-coding-agent).**
+**Multi-agent team orchestration for [Pi](https://github.com/nicekate/pi-coding-agent).**
 
-pi-crew is a Pi extension that orchestrates autonomous multi-agent workflows — research, implementation, review, testing, and more — with durable state, parallel execution, worktree isolation, and safe defaults.
+pi-crew is a Pi extension that adds one `team` tool for coordinating autonomous
+agent workflows — research, implementation, review, testing, and cleanup. Each
+task runs as a real child Pi process, with durable on-disk state, parallel
+execution, and opt-in git-worktree isolation. Runs can be monitored, steered,
+resumed, scheduled, and exported.
 
 ```text
-npm: pi-crew
-repo: https://github.com/baphuongna/pi-crew
+npm:   pi-crew
+repo:  https://github.com/baphuongna/pi-crew
 ```
 
-
+> ## ⚠️ IMPORTANT — Read before using
+>
+> **pi-crew was developed almost entirely by AI, for the author's own
+> workflow.** It is not a hardened, audited product:
+>
+> - **AI-generated code, limited human review.** Every change ships after
+>   static review + runtime tests, but nothing is independently audited.
+> - **It acts on your machine.** It spawns processes, runs shell commands, and
+>   writes files — including project-defined `.dwf.ts` scripts, which carry
+>   the same trust as any `node script.js` you downloaded.
+> - **Built for one workflow** (the author's). It may not fit yours — that's
+>   fine.
+>
+> If that's too risky, don't use it — no hard feelings. If you still want it:
+> **fork it, read the parts you'll touch, and adapt it to your setup.**
+> Details: [trust model](docs/trust-model.md) ·
+> [security issues](docs/bugs/SECURITY-ISSUES.md) ·
+> [Known limitations](#known-limitations).
 
 ## Features
 
-- **Workflow topology advisory** (v0.9.15) — before each run, pi-crew classifies the workflow's shape (`single` / `sequential` / `concurrent` / `complex-dag`) and prints an **advisory note** with measured cost evidence (e.g. "3-step sequential: measured 5.7× slower than 3 raw Agent calls — proceeding anyway"). Never blocks — the agent decides. Tool description and prompt-snippet carry the same guidance up-front, so agents know the trade-off before calling. New files: `src/workflows/topology-analyzer.ts`, `src/workflows/preflight-validator.ts`. See [Workflow topology advisory](#workflow-topology-advisory) below.
-- **One Pi tool** — `team` handles routing, planning, execution, review, and cleanup
-- **Autonomous delegation** — policy injection decides when/how to delegate based on task complexity
-- **needs_attention status** — tasks that complete without calling `submit_result` get `needs_attention` (terminal) instead of `completed`; allows retry/re-run without blocking downstream phases
-- **Real child Pi workers** — each task spawns a separate Pi process by default; scaffold/dry-run opt-out
-- **Adaptive planning** — implementation workflow lets a planner agent decide subagent fanout
-- **Parallel execution** — tasks in the same phase run concurrently with configurable concurrency
-- **Durable state** — manifest, tasks, events, artifacts all persisted to disk
-- **Async/background runs** — detached runs survive session switches with completion notifications
-- **Worktree isolation** — opt-in git worktrees per task for safe parallel edits
-- **Rich UI** — task list above the editor (pi-tasks style: numbered plan rows, dependency hints, `… and N more` overflow), dock at the very bottom (static icons, per-row model, footer usage), and an inline agent panel (open a worker's transcript with `↓` from the empty prompt — never a session switch). Live widget, dashboard, and progress tracking unchanged.
-- **Inline agent panel** (`src/ui/inline-panel/`) — status rows at the bottom, transcript in-document with pi's native components, `CustomEditor` overlay for steering (rides the existing `team steer` channel). Adapted from `pi-subtask` v0.7.4 (MIT) — attribution `NOTICE.md` §"Inline agent panel"; no code copied verbatim.
-- **Adaptive default team** (`workflows/default.workflow.md`) — the built-in default is now a single `assess` → adaptive-DAG step instead of a fixed `explore → plan → execute → verify` chain. The planner inspects the repo and emits a JSON plan; independent tasks run in parallel; the verifier closes the loop. Workflow files are runtime data — the change is live without a rebuild. Pin to `workflow='plan-execute'` if you need the old fixed DAG.
-- **Observability** — metrics registry, Prometheus/OTLP exporters, heartbeat watching, deadletter queue
-- **Resource management** — create/update/delete agents, teams, workflows with validation
-- **Import/export** — portable run bundles for sharing and archiving
-- **Adaptive plan fanout** — single `assess` step lets a planner pick the smallest effective crew
-- **Adaptive workflows** — `implementation`, `review`, `parallel-research`, `research` workflows ship in `workflows/`
-- **Hardened secrets** — linear-time detection covers PEM keys, Authorization headers, Bearer tokens, and `key=value` patterns
-- **Scheduled runs** — `schedule`/`scheduled` actions with cron, interval, and one-shot support; spawned runs tracked and auto-cancelled on job removal
-- **Plugin system** — framework-aware context injection (Next.js, Vite, Vitest) via plugin registry
-- **Health scoring** — penalty-based run health with time-series snapshots
-- **Autonomous goal loops** (P0/P1) — `team action='goal'` runs an autonomous multi-turn loop: a worker does a turn, a separate LLM judge evaluates the transcript+evidence against the goal, and on "not-achieved" the reason is fed into the next turn's prompt. Stops on achieved / maxTurns / budget / blocked. Claude-Code-style `/goal`. See `docs/goals.md`.
-- **Dynamic workflows** (P2/P3) — author orchestration as a `.dwf.ts` script (JS loops/branch/cross-review) instead of a static step list. The script runs in the background, calls subagents via `ctx.agent()`/`ctx.fanOut()`, holds intermediate results in JS variables, and only `ctx.setResult()` reaches the main context. `ctx.phase()` marks logical phases; **round-14** adds `ctx.log()` (durable `dwf.log` events), `ctx.budget` (per-workflow token budget that auto-rejects `ctx.agent()` when exhausted), and `ctx.args<T>()` (typed workflow arguments). TypeScript IntelliSense is available via `import type { WorkflowCtx } from "pi-crew/workflow"`. `workflow-create`/`-delete`/`-save` require `confirm:true` at the tool-call layer (the only gate — a malicious agent that passes `confirm:true` programmatically bypasses it; this is postinstall-equivalent trust, not a human-in-the-loop dialog). See `docs/dynamic-workflows.md`.
-- **Strict SKILL.md validation** (L3, v0.9.8) — skills with malformed frontmatter (missing/malformed `name`/`description`, type mismatches) now **fail-fast at discovery** with visible diagnostics, instead of silently producing broken behavior at runtime. HYBRID policy: HARD on required fields, SOFT (warn) on unknown props for forward-compat. Surfaced via `buildSkillValidationDiagnostics()`.
-- **Durable event replay** (L1, v0.9.8) — `RunEventBus.onWithReplay()` catches up a re-subscribing dashboard/overlay with events it missed during transient absence (toggle, reconnect), replaying from the durable JSONL log with seq-based dedup. No information loss even if the live subscriber was briefly gone.
-- **Lossless-by-default output handling** (L4, v0.9.8) — worker output thresholds sized from measured data (100% of real outputs fit without compaction); when compaction is unavoidable it keeps head+tail (preserves closing code fences/headings) instead of head-only truncation. No more `[pi-crew compacted N chars]` markers eating the end of a worker's result.
-- **Inter-pi broker** (v0.9.47, default-on) — a Unix-domain-socket message bus that lets concurrently-running Pi sessions pass messages, steering notes, and task-status events to each other. **On by default** on Linux + macOS; auto-disabled on native Windows (no unix socket). Three independent kill switches: `broker.enabled: false` (config), `PI_CREW_BROKER=0` (env, always wins), Windows auto-disable. See [docs/decisions/2026-07-22-broker-phase4-gated-on.md](docs/decisions/2026-07-22-broker-phase4-gated-on.md).
-- **Worker stateful scratchpad** (experimental, opt-in per role) — `executor` / `test-engineer` / `verifier` workers get a `scratchpad` tool: a persistent Bun-free JS evaluator whose namespace **compounds across calls within a task attempt** (variables set in one cell are visible in the next), so intermediate results live in memory instead of being re-derived from the transcript. Snapshots are flushed (redacted, atomic) per-attempt into the artifact store; the next attempt (retry / crash-recovery re-queue / re-run) **automatically revives the namespace** from the latest snapshot. Dormant by default (armed only when the spawner sets `PI_CREW_SCRATCHPAD=1`); zero behavior change for non-opt-in workers. Ported from the `@shift-labs/pi-rlm` pattern. See [src/runtime/scratchpad/README.md](src/runtime/scratchpad/README.md) (Phase 1-3 design, env keys, guards, threat model).
-- **`test:critical` + `real-test-pi-crew` skill** (v0.9.47) — a curated 14-file / 97-test subset (`npm run test:critical`, ~20s) for fast in-loop verification, plus a bundled skill distilling the full 8-tier end-to-end verification discipline (unit → 3-path kill-switch proof → typecheck/bundle → live TUI probing → smoke team run). Prevents the verifier-worker hang that full `npm test` (>4 min) caused against the 300s worker timeout.
-- **Provider extensions in subagents** (v0.9.57, local-path support v0.9.63) — pi-crew spawns child-pi workers with `--no-extensions` (security posture), which made extension-registered providers (e.g. `pi-commandcode-provider`, `pi-other-provider`) unresolvable inside subagents. pi-crew now **auto-discovers provider packages** from `~/.pi/agent/settings.json` `packages` — both `npm:` specs (v0.9.57) and **local-path specs** like `../../source/foo` (v0.9.63) — and loads them via `--extension` in every builtin/user subagent, so **all provider models work in subagents**. An explicit `runtime.agentExtensions: string[]` config is an optional extra allowlist on top of auto-discovery. **SEC-1 preserved:** project/project-pi agents never receive these (env-gate unchanged).
-- **Built-in performance observability** (v0.9.63) — every team run auto-attaches a detached resource sampler (per-PID CPU/RSS via ppid-tree attribution, 6 live warning categories) and auto-generates a markdown performance report on completion (22 anomaly categories, per-subagent timeline, token/cost/model attribution). Toggle per-team via frontmatter `observability: true|false`. Overhead ≈ 0 (sampler ~0.05% CPU / 56MB RSS; analyzer ~72ms post-run). See [Built-in performance observability](#built-in-performance-observability) below.
-
----
+- **One `team` tool, 55 actions** — run, monitor, steer, schedule, and manage agents/teams/workflows ([actions reference](docs/actions-reference.md)).
+- **Real child Pi workers** — each task spawns an isolated `pi` process; `runtime.mode: "scaffold"` gives a dry-run with prompts only.
+- **Built-in teams & adaptive planning** — 6 teams and 11 workflows ship in the box; the `default` and `implementation` workflows let a planner agent pick the smallest effective crew.
+- **Parallel execution + worktree isolation** — tasks in the same phase run concurrently; `workspaceMode: "worktree"` gives each task its own git worktree for safe parallel edits.
+- **Durable runs** — manifest, tasks, events, and artifacts persist under `.crew/`; resume, retry, or steer in-flight tasks; export/import run bundles. `.crew/knowledge.md` injects durable project learnings into every worker prompt.
+- **Async background runs** — `async: true` detaches a run so it survives session switches, with completion notification.
+- **Dynamic workflows** — author orchestration as a `.dwf.ts` script with real JS loops/branching, typed `ctx`, phases, and token budgets ([docs](docs/dynamic-workflows.md)).
+- **Autonomous goal loops** — `action: "goal"` runs worker → LLM judge → feedback turns until the goal is achieved or budget/turn limits hit ([docs](docs/goals.md)).
+- **Inter-pi broker** — concurrent Pi sessions exchange messages and steering over a unix socket; on by default (Linux/macOS), three kill switches.
+- **Observability & UI** — task list above the editor, agent dock, inline transcript panel, dashboard; per-run resource sampler + auto-generated performance report and cost breakdown.
 
 ## Install
 
@@ -84,1016 +51,174 @@ repo: https://github.com/baphuongna/pi-crew
 pi install npm:pi-crew
 ```
 
-Local development:
+> The `npm:` prefix is required — without it, `pi install` treats the argument
+> as a local path. Requires Node ≥ 22.
 
-```bash
-pi install ./pi-crew
-```
-
-Post-install config bootstrap:
+Local development (from a clone):
 
 ```bash
-pi-crew          # after npm install
-node ./pi-crew/install.mjs   # from local clone
+pi install .
 ```
 
-> **Split-scope install note (v0.8.11+):** pi installs extensions under
-> `~/.pi/agent/npm/node_modules/<ext>/`, separate from pi's own
-> node_modules tree (nvm / `%APPDATA%\npm` / Volta / fnm). Since v0.8.11
-> pi-crew resolves the `@earendil-works/pi-coding-agent` peer dep robustly
-> across these layouts — no symlink/NODE_PATH workaround needed. If you ever
-> do hit `Cannot find module '@earendil-works/pi-coding-agent'`, set
-> `PI_CREW_PEER_DEP_DIR=<path to the pi-coding-agent package dir>` as a
-> one-line workaround (or install pi-crew in pi's own scope:
-> `npm install -g @earendil-works/pi-crew`).
-
 ### Uninstall
 
-`pi uninstall npm:pi-crew` removes the package, but pi doesn't fire an
-extension uninstall hook, so several things pi-crew created are left behind.
-Reverse them explicitly with `team action=cleanup`. There are **two scopes**:
-
-> **v0.8.14+**: `team action=init` **no longer injects a guidance block into
-> AGENTS.md** (it was redundant — the `team` tool self-describes via its tool
-> registration, so the agent learns pi-crew's commands from there, not AGENTS.md).
-> The cleanup steps below still work for removing blocks injected by **older
-> versions** (<0.8.14).
-
-#### Project scope (reverse `team action=init`)
-
-```bash
-# 1. (Optional) Preview what would be removed, without writing:
-team action=cleanup dryRun=true
-
-# 2. Remove the AGENTS.md guidance block only (.crew/ preserved):
-team action=cleanup
-
-# 3. Remove BOTH the guidance block AND the .crew/ state directory (force):
-team action=cleanup force=true
-```
-
-The guidance block is wrapped in `<!-- PI-CREW:GUIDANCE:START -->` /
-`<!-- PI-CREW:GUIDANCE:END -->` markers, so cleanup removes **only** that
-block — your own AGENTS.md content is never touched. The `.crew/` directory
-is removed **only** with `force=true` (it's irreversible).
-
-#### User scope (remove user-level state `pi uninstall` leaves behind)
-
-```bash
-# 4. Preview + remove pi-crew user-scope junk:
-team action=cleanup scope=user dryRun=true   # preview
-team action=cleanup scope=user               # remove ~/.pi/agent/extensions/pi-crew/
-                                              #   + pi-crew smoke-test *.bak files
-
-# 5. (Optional) Also remove the global config (holds your settings):
-team action=cleanup scope=user force=true    # also removes ~/.pi/agent/pi-crew.json
-```
-
-This removes the pi-crew state dir (`~/.pi/agent/extensions/pi-crew/`, which
-holds run artifacts + state), the global config (with `force=true`), and the
-`*.md.bak-<timestamp>` smoke-test backup files pi-crew's own tests may leave in
-`~/.pi/agent/agents/`. **Your authored agent files (`*.md`) are never touched**
-— pi-crew can't tell which were user-created vs test-copied, so only the
-clearly-pi-crew `.bak-*` backups are removed.
-
-#### Final step
+`pi uninstall npm:pi-crew` removes the package, but pi has no uninstall hook —
+pi-crew-created state is left behind. Reverse it explicitly:
 
 ```bash
-# 6. Remove the package itself:
-pi uninstall npm:pi-crew
+team action=cleanup dryRun=true            # preview, no writes
+team action=cleanup force=true             # remove project guidance block + .crew/
+team action=cleanup scope=user force=true  # + user-level state and global config
+pi uninstall npm:pi-crew                   # finally, the package itself
 ```
 
-
----
-
-## Quick Start
-
-### 1. Initialize project
+## Quick start
 
 ```text
 /team-init
-```
-
-### 2. Run a team
-
-```text
 /team-run Investigate failing tests and propose a fix
 ```
 
-Or via tool call:
-
-```json
-{
-  "action": "run",
-  "team": "default",
-  "goal": "Investigate failing tests and propose a fix"
-}
-```
-
-### 3. Check status
-
-```text
-/team-status <runId>
-/team-dashboard
-```
-
-### 4. Get a recommendation
-
-When unsure which team/workflow fits:
+Or via tool calls (all examples verified against the action schema):
 
 ```json
-{
-  "action": "recommend",
-  "goal": "Refactor auth flow and add tests"
-}
-```
-
----
-
-## Builtin Teams
-
-| Team | Workflow | Purpose |
-|------|----------|----------|
-| `default` | adaptive: planner derives concrete tasks from the goal, parallel phases, verify | Balanced, general-purpose |
-| `fast-fix` | explore → execute → verify | Quick bug fixes |
-| `implementation` | Adaptive planner decides fanout | Multi-file implementation |
-| `review` | explore → code-review → security-review → verify | Code review + security audit |
-| `research` | explore → analyze → write | Research and documentation |
-| `parallel-research` | Parallel shards → synthesize → write | Multi-source research |
-
----
-
-## Workflow topology advisory
-
-Before every `team action='run'`, pi-crew classifies the workflow shape and prints an informational note. **It never blocks** — agents decide whether to proceed, refactor, or override.
-
-### How it works
-
-```text
-team action='run', workflow='fast-fix', goal='...'
-  ↓
-pi-crew analyzes topology: 3-step sequential
-  ↓
-⚠️  [team-tool.preflight] WARN: 3-step sequential chain: measured 5.7× slower
-    and 1.9× costlier than 3 raw Agent calls (Run #3 in .crew/state/runs/).
-    Proceeding anyway.
-  ↓
-Workflow runs to completion. Agent sees the note, decides for next time.
-```
-
-### Topology → advisory level
-
-| Topology | When | Level | What pi-crew prints |
-|---|---|---|---|
-| `single` | 1 step, no concurrency | `warn` | "raw Agent tool would be ~30× faster and ~5× cheaper. Proceeding anyway." |
-| `sequential` (2-3 steps) | Linear chain, no fan-out | `warn` | "measured 5.7× slower than raw Agent calls. Proceeding anyway." |
-| `sequential` (4+ steps) | Linear chain, longer | `warn` | "audit trail may justify pi-crew overhead. Proceeding anyway." |
-| `concurrent` | ≥3 truly parallel agents (parallelGroup) | `note` | "✅ Validated use case: N-way parallel fan-out. pi-crew's parallelism wins." |
-| `complex-dag` | 4+ steps with data dependencies | `note` | "✅ Validated use case: complex DAG with adaptive plan." |
-| `dynamic` | `.dwf.ts` script | `info` | "Runtime decides topology." |
-
-### When to prefer raw `Agent` over `team`
-
-Use the raw `Agent` tool when:
-- You have a single task or quick question (1-step)
-- You have 2–3 sequential independent steps (no DAG branching, no concurrency)
-
-Use `team` when:
-- You have ≥3 agents running TRULY CONCURRENTLY (`parallelGroup`)
-- You have a COMPLEX DAG (4+ steps with data dependencies, branching)
-- You need an audit trail, team coordination, or worktree isolation that justifies pi-crew's overhead
-
-### How agents learn the rule
-
-The guidance is available in three places agents see:
-
-1. **`team` tool description** — the LLM reads this when considering whether to call the tool. Includes an explicit "ℹ️ ADVISORY NOTE (preflight, never blocks)" section.
-2. **`team` prompt snippet** — rendered in agent context when the tool is relevant. Single-line summary of the rule.
-3. **`.crew/knowledge.md` CONVENTIONS section** — always injected into every worker session's context. Contains the full 4-question self-check.
-
-### How to silence the advisory
-
-The advisory is **informational only** — there is no `force:true` flag needed (the run proceeds regardless).
-
-### Implementation
-
-- `src/workflows/topology-analyzer.ts` — pure classifier (parses workflow YAML, builds DAG, detects parallelGroups)
-- `src/workflows/preflight-validator.ts` — returns `{level: info|note|warn, message, suggestion}` (never throws)
-- Integration: `src/extension/team-tool/run.ts` (extension layer, prints advisory) + `src/runtime/team-runner.ts` (defense-in-depth, also logs)
-
-### Tests
-
-- `test/unit/topology-analyzer.test.ts` — 13 cases (each topology + edge cases)
-- `test/unit/preflight-validator.test.ts` — 11 cases (each level + advisory contract)
-
-
-- `test/functional/pi-crew-live.test.ts` + `test/functional/pi-crew-live-broad.test.ts` — 16 live integration tests run against the **real pi binary + real LLM provider** (verified after v0.9.42 audit, ~26 commits). Use these when you want to confirm end-to-end behavior, not just unit-level invariants.
-
-## Recent changes
-
-### v0.10.2: UI rewrite + adaptive default team (2026-08-24)
-
-40 commits after `v0.10.1` (≈3,500 LOC, 54 files). Headline: the UI surface
-goes from "two modal overlays + status widget" to a proper in-document
-panel — task list above the editor, dock at the very bottom, and an inline
-agent transcript that opens with `↓` from the empty prompt. The default
-team also moves from a fixed 4-step chain to a single adaptive `assess` →
-parallel-execute → verify DAG.
-
-- **Task list above the editor** — pi-tasks style numbered plan rows
-  (`#1`, `#2`, …) instead of `01_explore` ids; completed rows dim and
-  strike through; running row shows spinner + elapsed time + token
-  counts; queued rows name dependencies (`› blocked by #2`). Header
-  is Claude-Code style (`● 4 tasks (1 done, 1 in progress, 2 open)`).
-  Role/agent/model identity moved to the dock — the list is the *plan*,
-  not a worker report. 10-row cap with `… and N more` overflow.
-- **Inline agent panel** (`src/ui/inline-panel/`, ~1,761 LOC, 10 files) —
-  `↓` from the empty prompt opens the dock; Enter drops into the worker's
-  full transcript rendered in-document with pi's native components;
-  steering rides the existing `team steer` channel (no stdin pipe).
-  Worker view is a *byte-copy* of the worker's own session log, polled
-  for live refresh, and Enter on the dock row always opens a real Pi
-  session (the worker-143 kill on switches and the `AbortError`
-  post-exit crash are both fixed). Full-screen overlay preserved for
-  end-of-run review.
-- **Dock survives until the run is done** — rows no longer disappear at
-  "completed"; 3-row scroll window keeps the in-progress task visible;
-  per-row model display.
-- **Adaptive default team** (`workflows/default.workflow.md`, runtime
-  data — no rebuild needed) — old fixed `explore → plan → execute →
-  verify` replaced by a single `assess` step (planner role) that emits
-  an `ADAPTIVE_PLAN_JSON` block. Independent tasks go into the SAME
-  phase so they run in parallel; verifier still closes the loop.
-  **Pin to `workflow='plan-execute'` if you need the old fixed DAG.**
-- **Model-routing passthrough muted** + Biome 2.5.3 lint/format sync.
-- Real-test re-run on the released v0.10.1 bundle: test:critical 102/102,
-  typecheck clean, 9a 10/10, 9b 5/5, chain 306.8s observation.
-  See `CHANGELOG.md` §Unreleased for full notes and `NOTICE.md` for
-  pi-subtask / pi-tasks attributions.
-
-### v0.9.65: team-tool schema empty-string guard + effectiveness empty-result guard (2026-08-10)
-
-- **`budgetTotal` empty-string unset marker accepted**: `budgetTotal` was the only numeric `TeamToolParams` field missing the `Literal("")` union branch its siblings had. Calling models that emit every schema key with defaults were rejected by pi-ai's pre-handler validation → `Validation failed for tool "team"` on every action. The `MISCONFIGURATION GUARD` (rejects 1-999) is preserved. Caught by the Tier 9 feature battery — Tiers 1-8 stayed green while the team tool was broken for emitting models.
-- **Effectiveness empty-result guard**: a completed task with an empty result artifact (`sizeBytes === 0`) is now treated as no-observed-work — closing the monitoring gap where a 429-absorbed / model-not-found worker produced zero real content but the run still completed with `consistency=1`. Empty-result tasks flow through the existing `noObservedWork` escalation. Regression tests: `test/unit/runtime/core/effectiveness-guard.test.ts` (8 tests).
-- Full 9-tier real-test re-run (2026-08-10): Tiers 1-8 + 9a (10/10) + 9b (5/5) pass; previous failure modes did not reproduce. See [CHANGELOG.md](CHANGELOG.md) §0.9.65 and `docs/real-test/reports/real-test-2026-08-10-full-9-tier-f4-effectiveness-guard.md`.
-
-### v0.9.63: built-in performance observability + local-path provider-extension discovery
-
-- **Built-in performance observability (always-on, toggle per team)**: every team run now auto-attaches a detached resource sampler (`scripts/resource-sampler.mjs` — per-PID CPU/RSS via ppid-tree attribution, 6 live warning categories: high_cpu / rss_jump / rss_high / rss_leak / proc_died / proc_zombie) and auto-generates a markdown performance report (`scripts/analyze-run.mjs` → `docs/perf-report-<runId>.md` — 22 anomaly categories, per-subagent launch/respawn/active/drain timeline, token/cost/model attribution). Runtime wiring in `src/runtime/team-runner.ts`: `startPerfSampler` (detached + `unref`'d; death never affects the run) + `schedulePerfAnalyze` (+3s after `after_run_complete`, `unref`'d `setTimeout`). Toggle: team frontmatter `observability: true|false` (default `true`). **Overhead ≈ 0** (A/B verified: sampler ~0.05% CPU / 56MB RSS, analyzer ~72ms post-run, ~32KB artifacts/run). New scripts: `scripts/resource-sampler.mjs`, `scripts/analyze-run.mjs`. Tests: `test/unit/scripts/{analyze-run,resource-sampler}-audit.test.ts`.
-- **Local-path provider extensions now discovered for child workers**: `discoverProviderExtensions` previously resolved only `npm:` specs from `~/.pi/agent/settings.json` `packages`, skipping local-path specs on the assumption they were the pi-crew extension itself. That broke local provider extensions (e.g. `pi-other-provider` installed via `pi install <local-path>`) — every model from such a provider hit `Error: Model "…" not found` in child workers and burned ~10s/task of fallback churn. Fix: resolve `./`, `../`, and absolute specs relative to the settings.json dir (same sanctioned trust level as `npm:`), and skip pi-crew itself via `packageRoot()`. **SEC-1 preserved** (project/project-pi AGENT extensions stay gated). Tests in `test/unit/runtime/model/provider-extensions.test.ts`.
-- See [CHANGELOG.md](CHANGELOG.md) §0.9.63 and `docs/real-test/reports/real-test-2026-08-08-provider-ext-local-path.md`.
-
-### v0.9.57: team-tool schema repair + provider-extension auto-discovery + post-reorg repo-layout consolidation
-
-- **Team tool repaired (was broken live while tests stayed green)**: calling models emit empty-string/boolean defaults for every schema key, which pi-ai's pre-handler `validateToolArguments` rejected (`Validation failed for tool team`) and `Type.Unsafe` schema fields without `[TypeBox.Kind]` made `Value.Check` throw (`Unknown type`). Schema now accepts unset markers natively; `SkillOverride`/`FreeformConfig` switched to TypeBox-native constructors; `normalizeTeamParams` drops empties in the handler. Chain-runner also fixed (quote-aware step splitting). Caught by a new **Tier 9 feature battery** in the [`real-test-pi-crew`](skills/real-test-pi-crew/SKILL.md) skill (live team-tool action coverage).
-- **Source reorg finalised (~90 commits)**: `src/` is now cluster-organised — `src/runtime/` (15 subdirs + ~77 flat files) and `src/state/` (3 subdirs + 12 root files), with the other top-level dirs (`extension/`, `ui/`, `config/`, `utils/`, `agents/`, …) cluster-honed too. See [Repository layout](#repository-layout) and the cluster maps [`src/runtime/README.md`](src/runtime/README.md) / [`src/state/README.md`](src/state/README.md).
-- **Tests mirrored into subdirs**: 566 flat `.test.ts` files now live in 35 leaf subdirectories mirroring `src/` (`test/unit/runtime/`, `test/unit/state/`, `test/unit/extension/`, …). 151 cross-cutting tests (`round*`, `v0*`, `package-*`, errors, i18n, bundle-*) stay at `test/unit/` root by design. See [`test/unit/README.md`](test/unit/README.md).
-- **Recursive-glob test-runner fix**: `scripts/test-runner.mjs` now expands `**` globs itself — Node v22's `--test` only expands single-level `*`, so subdir tests (e.g. `test/unit/security/`) were **invisible** to `npm test` before.
-- **Docs consolidated**: 47 flat docs at `docs/` root → 20 living docs kept at root, 27 historical moved to `docs/archive/` (flat); 11 stray root `.md` files moved to `docs/archive/` + `docs/bugs/`. New [`docs/README.md`](docs/README.md) indexes the living docs + subdirs.
-- **Provider extensions in subagents** (see [Features](#features)): auto-discovery of provider packages from `~/.pi/agent/settings.json` `packages` (npm: specs) + explicit `runtime.agentExtensions` allowlist. Implementation: `src/runtime/model/provider-extensions.ts` + merge in `src/agents/discover-agents.ts`. SEC-1 preserved (project/project-pi agents never receive these).
-- See [CHANGELOG.md](CHANGELOG.md) for the full reorg + feature log.
-
-### v0.9.47 (2026-07-22): Inter-pi broker Phase 4 (default-on) + verifier-hang fix + verification skill
-
-- **Broker default-on**: `broker.enabled` flipped `false` → `true` on Linux + macOS. The inter-pi broker lets concurrent Pi sessions exchange messages, steering notes, and task-status events over a Unix-domain socket. Three kill switches remain: config `broker.enabled: false`, env `PI_CREW_BROKER=0` (always wins), Windows auto-disable.
-- **Verifier-hang fix**: `npm run test:critical` — a curated 14-file / 97-test subset (~20s) replaces full `npm test` (>4 min) in verifier prompts. The full suite was exceeding the 300s `RESPONSE_TIMEOUT_MS`, killing workers with exit 143. Both plan-templates and all 4 workflow verifier prompts now specify the fast command.
-- **`real-test-pi-crew` skill** (659 lines): distills the 8-tier verification discipline used to ship this release (critical tests → 3-path kill-switch proof → typecheck/bundle → bundle md5 sync → live TUI probing via tmux/pty → smoke team run). Bundled `scripts/pty_probe.py`.
-- **Postinstall skill-collision fix**: v0.9.47's `copySkills()` (which mirrored skills to `~/.pi/agent/skills/`) caused 31 "collision" warnings — Pi already discovers skills natively from the npm package. v0.9.48 removes `copySkills()` and adds a safe byte-identical cleanup (`cleanupStaleSkillCopies()`) that clears the stale copies on upgrade. User-customized skills are preserved.
-- See [CHANGELOG.md](CHANGELOG.md) §0.9.47 and [docs/decisions/2026-07-22-broker-phase4-gated-on.md](docs/decisions/2026-07-22-broker-phase4-gated-on.md).
-
-### v0.9.45 – v0.9.46 (2026-07-20): security + perf remediation, UI stability
-
-- **Custom agent roles default to read-only (FIND-12, breaking):**
-  `permissionForRole()` returns `"read_only"` for unknown roles (was
-  permissive `"workspace_write"`). Write-capable roles are now an explicit
-  allowlist (`WRITE_ROLES`). See `CHANGELOG.md` for the migration.
-- **Mailbox / snapshot-cache / scan perf:** delivery cache + async append
-  (FIND-01/02), `listActive` TTL + mtime-sort strict limit (FIND-03/04),
-  byte-bounded event-log tail-read (FIND-05).
-- **Heartbeat race (FIND-06):** in-flight guard + drain + terminal-safety +
-  late-save repair in the coalesced task group.
-- **UI flicker eliminated:** the render path no longer hard-deletes snapshot
-  entries, so the crew widget / powerbar / live sidebar stay stable (no more
-  "(loading…)" flashing every ~160ms).
-- **Emoji width-overflow crash fixed for good:** `visibleWidth` delegates to
-  pi-tui's own measure, so agent-output emoji can never exceed terminal width.
-- **Background-subagent notifications coalesce:** N near-simultaneous
-  completions now produce ONE consolidated wake-up instead of N drips.
-
-### v0.9.42 – v0.9.44: 4-wave audit + flaky-CI fixes
-
-A 4-wave audit + fix pass was completed (see `docs/archive/UPGRADE_REVIEW.md` for the full 647-line report and `CHANGELOG.md` for the diff):
-
-- **−481 KB** bundle size (externalized `acorn` + fixed `@sinclair/typebox` name).
-- **−31.1%** in `child-pi.ts` (1842 → 1270 lines via 6 decomposition steps).
-- **~30 bug fixes** across security, correctness, budget enforcement, worker cap, observability, and worktree isolation.
-- **Lock re-entrance guard** via `AsyncLocalStorage` (H-1) — fixes a root-cause mutual-exclusion violation.
-- **Task-level metrics now functional** (OBS-NEW-1/2) — `crew.task.{count,duration_ms,tokens_total}` were always zero; now emit on every run completion.
-- **Live-test-only bugs found** (mock tests had passed): token usage not captured (nested `obj.message.usage`), child-pi spawning wrong binary (`argv1` trust heuristic), worktree mode blocked by own `.gitignore`.
-
-## Builtin Agents
-
-```
-analyst  ·  critic  ·  executor  ·  explorer  ·  planner  ·  reviewer
-security-reviewer  ·  test-engineer  ·  verifier  ·  writer
-```
-
----
-
-## Runtime Modes
-
-pi-crew supports multiple runtime modes for task execution:
-
-| Mode | Description |
-|------|-------------|
-| `auto` (default) | Uses `child-process` unless overridden by config |
-| `child-process` | Spawns real `pi` child processes — each task runs in isolation |
-| `scaffold` | Dry-run mode — renders prompts and persists artifacts without executing |
-| `live-session` (experimental) | In-process session execution within the parent Pi |
-
-```json
-// Use scaffold mode (no real workers, just prompts)
-{ "action": "run", "team": "default", "goal": "...", "runtime": { "mode": "scaffold" } }
-
-// Disable workers globally
-{ "executeWorkers": false }
-```
-
-## Built-in performance observability
-
-Every team run auto-attaches a **detached resource sampler** and auto-generates a **performance report** on completion — measuring real resource usage and surfacing anomalies from the run's actual events/transcripts, not a synthetic benchmark.
-
-### Artifacts produced (per run, under `.crew/artifacts/<runId>/`)
-
-| File | Contents |
-|------|----------|
-| `resources.jsonl` | Per-PID CPU/RSS samples every 2s (root runner + all child workers via ppid-tree attribution, including respawns). PID-reuse guarded by `/proc` starttime; first-sample CPU excluded from averages. |
-| `perf-obs.log` | Sampler diagnostics: spawn marker, live warnings, terminal-stop confirmation. |
-| `docs/perf-report-<runId>.md` | Markdown report: 22 anomaly categories, per-subagent timeline (launch/respawn/startup/active-work/drain/finalize), token/cost/model attribution. |
-
-### Live warnings (written to `perf-obs.log` during the run)
-
-`high_cpu` (≥300% one core) · `rss_jump` (+200MB/interval) · `rss_high` (≥1GB) · `rss_leak` (window-30 monotonic +100MB) · `proc_died` · `proc_zombie`. Rate-limited (10s/pid/category).
-
-### Toggle
-
-```yaml
-# teams/my-team.team.md
----
-name: my-team
-observability: false   # default: true — set false to skip sampler + report
----
-```
-
-`observability: true` is the default for parsed team files; direct-object `TeamConfig` fixtures (unit tests) stay unset so they never spawn the sampler. `schedulePerfAnalyze` runs the analyzer `+3s` after `after_run_complete` via an `unref`'d `setTimeout` — it never blocks run completion. The sampler auto-stops when the run manifest reaches a terminal status.
-
-### Overhead
-
-Measured A/B (same team/goal, observability on vs off): **no detectable wall-time difference** (delta inside the 429-storm noise). Sampler: ~0.05% of one core, 56MB RSS fixed, detached + `unref`'d. Analyzer: ~72ms one-shot after run. ~32KB artifacts/run. See `docs/real-test/reports/real-test-2026-08-07-perf-obs-overhead.md`.
-
-## Async Runs
-
-Async runs are **detached** from the session — they survive session switches and reloads. Pi-crew notifies when complete.
-
-```json
-{ "action": "run", "team": "default", "goal": "...", "async": true }
-```
-
-```text
-/team-run --async Investigate failing tests
+{ "action": "run", "team": "default", "goal": "Investigate failing tests and propose a fix" }
+{ "action": "status", "runId": "team_..." }
+{ "action": "recommend", "goal": "Refactor auth flow and add tests" }
+{ "action": "run", "team": "implementation", "goal": "Refactor auth", "async": true, "workspaceMode": "worktree" }
 ```
 
-Background runs use `node --import jiti-register.mjs` for TypeScript support. See [docs/runtime-flow.md](docs/runtime-flow.md) for details.
-
-## Worktree Isolation
+`action: "recommend"` picks a team/workflow when you're unsure which fits.
+Slash commands (`/team-status`, `/team-dashboard`, `/team-config`, …) cover ops
+and debugging — [full list](docs/commands-reference.md).
 
-Worktree mode creates an **isolated git worktree per task** — safe for parallel edits to the same branch.
+## Built-in teams
 
-```json
-{
-  "action": "run",
-  "team": "implementation",
-  "goal": "Refactor auth",
-  "workspaceMode": "worktree"
-}
-```
-
-```text
-/team-run --worktree Refactor auth
-```
+| Team | Workflow shape | Use for |
+|------|----------------|---------|
+| `default` | adaptive: assess → parallel tasks → verify | general-purpose work |
+| `fast-fix` | explore → execute → verify | small bug fixes |
+| `implementation` | adaptive planner decides fanout | multi-file features/refactors |
+| `review` | explore → code-review → security-review → verify | code + security review |
+| `research` | explore → analyze → write | investigation and documentation |
+| `parallel-research` | parallel shards → synthesize → write | multi-source audits |
 
-Requirements:
-- Git repository (cwd must be inside a git repo)
-- Clean working tree (no uncommitted changes in the leader worktree)
-  - Can be disabled via config: `requireCleanWorktreeLeader: false`
-- Worktrees auto-cleanup on run completion/cancel
-
-If preconditions are not met, a friendly error message is returned instead of crashing.
-
----
+18 built-in agents ship in [`agents/`](agents/) (explorer, planner, executor,
+critic, reviewer, verifier, test-engineer, writer, analyst, oracle, librarian,
+…). Resources are discovered in three layers — builtin package < user
+(`~/.pi/agent/`) < project (`.crew/`) — and project resources cannot shadow
+builtin ones. Formats: [docs/resource-formats.md](docs/resource-formats.md).
 
 ## Configuration
 
-### Config Paths
+Config files (first found wins per scope):
 
 | Scope | Path |
 |-------|------|
-| User (primary) | `~/.pi/agent/pi-crew.json` |
-| User (legacy, still read for migration) | `~/.pi/agent/extensions/pi-crew/config.json` |
-| Project (crewRoot) | `.crew/config.json` (or `.pi/teams/config.json` legacy) |
-| Project (alt) | `.pi/pi-crew.json` |
-
-### Quick Config
-
-```text
-/team-config                           # view all settings
-/team-config runtime.mode=scaffold    # set a key (--project for project scope)
-/team-config --unset=runtime.mode     # reset a key to default
-/team-config --project runtime.mode   # project-scoped view
-/team-settings path                   # show config file path
-```
-
-### Key Settings
-
-A comprehensive reference of every config key. 🔒 marks keys that are
-**sensitive** — project config (`.crew/config.json`) cannot set them; they are
-silently ignored with a warning unless set in **user config**
-(`~/.pi/agent/pi-crew.json`). Cross-referenced against `src/config/types.ts`
-(`PiTeamsConfig`), `src/config/defaults.ts`, and the project-override sanitizer
-in `src/config/config.ts`.
-
-For machine-readable validation, see [schema.json](schema.json).
-
-#### Top-level
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `asyncByDefault` 🔒 | `boolean` | `false` | Detach every `run` by default (survives session switches). |
-| `executeWorkers` 🔒 | `boolean` | `true` | Spawn worker agents. `false` = dry-run planning only. |
-| `notifierIntervalMs` | `number` | `5000` | How often the completion notifier polls. |
-| `requireCleanWorktreeLeader` 🔒 | `boolean` | _(unset)_ | Require a clean git repo before starting a worktree-mode run. |
-| `ignoreMethod` | `"gitignore" \| "exclude"` | _(unset)_ | How run artifacts are ignored by git. |
-
-#### `autonomous.*` — Delegation & magic keywords
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `autonomous.profile` 🔒 | `manual \| suggested \| assisted \| aggressive` | `suggested` | How much the agent self-delegates to crew runs. |
-| `autonomous.enabled` 🔒 | `boolean` | `true` | Master switch for autonomous delegation. |
-| `autonomous.injectPolicy` 🔒 | `boolean` | `true` | Inject the delegation policy into prompts. |
-| `autonomous.preferAsyncForLongTasks` 🔒 | `boolean` | `false` | Auto-detach runs expected to be long. |
-| `autonomous.allowWorktreeSuggestion` 🔒 | `boolean` | `true` | Suggest worktree isolation for mutating goals. |
-| `autonomous.magicKeywords` | `Record<string, string[]>` | _(unset)_ | Trigger words mapped to team/workflow hints. |
-
-#### `limits.*` — Scheduling ceilings
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `limits.maxConcurrentWorkers` | `number` | workflow-dependent¹ | Hard cap on parallel workers. Ceiling 1024. |
-| `limits.allowUnboundedConcurrency` | `boolean` | `false` | Permit unbounded fan-out (dangerous). |
-| `limits.maxTaskDepth` | `number` | `100` | Max nesting depth of the task graph. |
-| `limits.maxChildrenPerTask` | `number` | `1000` | Max children a single task may spawn. |
-| `limits.maxRunMinutes` | `number` | `1440` | Wall-clock cap for a run (24 h). |
-| `limits.maxRetriesPerTask` | `number` | `100` | Max automatic retries per task. |
-| `limits.maxTasksPerRun` | `number` | `10000` | Max tasks allowed in a single run. |
-| `limits.heartbeatStaleMs` | `number` | `86400000` | Heartbeat staleness threshold (24 h). |
-| `limits.serializeOnPathOverlap` | `boolean` | `false` | Skip ready tasks whose `step.output` overlaps an in-flight task. |
-
-¹ Per workflow: `parallelResearch` 4, `research` 3, `implementation` 4, `review` 3, `default` 3 (fallback 2).
-
-#### `runtime.*` — Worker execution
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `runtime.mode` 🔒 | `auto \| scaffold \| child-process \| live-session` | `auto` | How workers are spawned. |
-| `runtime.preferLiveSession` 🔒 | `boolean` | _(unset)_ | Prefer in-process live-session workers. |
-| `runtime.allowChildProcessFallback` 🔒 | `boolean` | _(unset)_ | Fall back to child-process if live-session unavailable. |
-| `runtime.maxTurns` | `number` | `10000` | Max agent turns per task. |
-| `runtime.graceTurns` | `number` | `5` | Extra turns allowed after a stop signal. |
-| `runtime.taskTimeoutMs` | `number` | `0` | Per-task wall-clock timeout (0 = none). |
-| `runtime.inheritContext` 🔒 | `boolean` | `true` | Inherit parent context into workers. |
-| `runtime.promptMode` | `replace \| append` | `replace` | How the task prompt is applied. |
-| `runtime.groupJoin` | `off \| group \| smart` | `smart` | How grouped task results are joined. |
-| `runtime.groupJoinAckTimeoutMs` | `number` | `86400000` | Timeout for group-join acknowledgements. |
-| `runtime.requirePlanApproval` 🔒² | `boolean` | `false` | Pause for plan approval before mutating tasks. |
-| `runtime.completionMutationGuard` | `off \| warn \| fail` | `warn` | Guard against tasks mutating outside plan approval. |
-| `runtime.effectivenessGuard` | `off \| warn \| block \| fail` | `off` | Pre-flight topology validator enforcement mode. |
-| `runtime.isolationPolicy` 🔒 | `{ isolatedRoles?, defaultRuntime? }` | _(unset)_ | Per-role runtime selection for crash isolation. |
-| `runtime.excludeContextBash` | `boolean` | `false` | Exclude certain bash results from worker context. |
-| `runtime.agentExtensions` | `string[]` | _(unset)_ | Extra extension paths (file paths or npm entry points) loaded in **every** child-pi worker on top of auto-discovered provider packages (see [Features](#features)). Optional allowlist — auto-discovery already loads provider packages from `~/.pi/agent/settings.json` `packages`. Project/project-pi agents never receive these (SEC-1). |
-
-² `requirePlanApproval` is sensitive only when set to `false` in project config
-(the sanitizer blocks *disabling* the gate from untrusted project config).
-
-#### `control.*` — Needs-attention gating
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `control.enabled` | `boolean` | _(unset)_ | Enable the needs-attention controller. |
-| `control.needsAttentionAfterMs` | `number` | _(unset)_ | Threshold before flagging a run as needing attention. |
-
-#### `worktree.*` — Git worktree isolation
-
-> Worktree **mode** is chosen at run time via `workspaceMode: "worktree"`, not
-> in config. These keys configure how a worktree is set up.
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `worktree.setupHook` 🔒 | `string` | _(unset)_ | Shell command run after worktree creation. |
-| `worktree.setupHookTimeoutMs` | `number` | _(unset)_ | Timeout for the setup hook. |
-| `worktree.linkNodeModules` | `boolean` | `false` | Symlink `node_modules` into the worktree. |
-| `worktree.seedPaths` | `string[]` | _(unset)_ | Extra paths to copy/symlink into the worktree. |
-
-#### `goalWrap.*` — Goal-completion workflows
-
-A per-workflow map (`Record<workflowName, GoalWrapWorkflowConfig>`) that applies
-the `goal` action's completion-guarantee loop to builtin workflows.
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `goalWrap.<name>.enabled` | `boolean` | _(unset)_ | Enable goal-wrap for this workflow. |
-| `goalWrap.<name>.maxTurns` | `number` (1–50) | _(unset)_ | Max iterations of the goal loop. |
-| `goalWrap.<name>.evaluatorModel` | `string` | _(unset)_ | Model used by the LLM judge. |
-| `goalWrap.<name>.verification.commands` | `string[]` | _(unset)_ | Commands run to verify completion. |
-| `goalWrap.<name>.budgetTotal` | `number` | _(unset)_ | Token budget for the goal loop. |
-| `goalWrap.<name>.budgetUnlimited` | `boolean` | _(unset)_ | Skip the token budget. |
-
-#### `agents.*` — Agent overrides
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `agents.disableBuiltins` 🔒 | `boolean` | `false` | Hide built-in agents. |
-| `agents.overrides` 🔒 | `Record<name, AgentOverride>` | _(unset)_ | Per-agent `model`, `fallbackModels`, `thinking`, `tools`, `skills`, `disabled`. |
-
-#### `tools.*` — Tool behaviour
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `tools.enableClaudeStyleAliases` | `boolean` | _(unset)_ | Accept Claude-style tool aliases. |
-| `tools.enableSteer` 🔒 | `boolean` | _(unset)_ | Enable the `steer` action. |
-| `tools.terminateOnForeground` 🔒 | `boolean` | _(unset)_ | Terminate background runs when foreground starts. |
-
-#### `telemetry.*`
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `telemetry.enabled` | `boolean` | `false` | Collect anonymous usage telemetry. |
-
-#### `policy.*` — Capability gating
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `policy.requireIntentForDestructiveActions` | `boolean` | _(unset)_ | Require explicit intent for deletes/forgets. |
-| `policy.disabledCapabilities` | `string[]` | _(unset)_ | Disable named capabilities. |
-
-#### `notifications.*`
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `notifications.enabled` | `boolean` | `false` | Enable run-completion notifications. |
-| `notifications.severityFilter` | `Severity[]` | `[warning, error, critical]` | Which severities to surface. |
-| `notifications.dedupWindowMs` | `number` | `30000` | De-duplicate notifications within this window. |
-| `notifications.batchWindowMs` | `number` | `0` | Batch notifications for this long before emitting. |
-| `notifications.quietHours` | `string` | _(unset)_ | Quiet-hours schedule (e.g. `"22:00-08:00"`). |
-| `notifications.sinkRetentionDays` | `number` | `7` | How long notification sinks retain data. |
-
-#### `observability.*`
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `observability.enabled` | `boolean` | _(unset)_ | Enable the periodic observability poller. |
-| `observability.pollIntervalMs` | `number` | _(unset)_ | Polling interval. |
-| `observability.metricRetentionDays` | `number` | _(unset)_ | How long metrics are retained. |
-
-#### `reliability.*` — Retry, recovery & validation
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `reliability.autoRetry` | `boolean` | `false` | Auto-retry failed tasks. |
-| `reliability.retryPolicy.maxAttempts` | `number` | _(unset)_ | Max retry attempts. |
-| `reliability.retryPolicy.backoffMs` | `number` | _(unset)_ | Base backoff between retries. |
-| `reliability.retryPolicy.jitterRatio` | `number` | _(unset)_ | Jitter fraction (0–1). |
-| `reliability.retryPolicy.exponentialFactor` | `number` | _(unset)_ | Exponential backoff multiplier. |
-| `reliability.retryPolicy.retryableErrors` | `string[]` | _(unset)_ | Error substrings considered retryable. |
-| `reliability.retryPolicy.maxTotalSpawns` | `number` | `0` | Flat per-task spawn budget (0 = auto). |
-| `reliability.autoRecover` | `boolean` | `false` | Auto-recover stuck/orphaned runs. |
-| `reliability.deadletterThreshold` | `number` | _(unset)_ | Attempts before a task is dead-lettered. |
-| `reliability.autoRepairIntervalMs` | `number` | `60000` | Periodic stale-run repair interval (0 = off). |
-| `reliability.cleanupOrphanedTempDirs` | `boolean` | `true` | Remove orphaned `/tmp/pi-crew-*` dirs. |
-| `reliability.forcePreflight` | `boolean` | `false` | Bypass the topology validator (audit-logged). |
-| `reliability.ambientStatusInjection` | `boolean` | `true` | Inject ambient crew-status note on every LLM call. |
-| `reliability.perWriteValidation` | `boolean` | `true` | Validate `write`/`edit` results (JSON v1). |
-| `reliability.scopeModels` | `boolean` | `false` | Enforce subagent models stay within the allowlist. |
-
-#### `otlp.*` — OpenTelemetry export
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `otlp.enabled` | `boolean` | _(unset)_ | Enable OTLP trace/metric export. |
-| `otlp.endpoint` 🔒 | `string` | _(unset)_ | OTLP collector endpoint. |
-| `otlp.headers` 🔒 | `Record<string, string>` | _(unset)_ | Auth headers sent to the collector. |
-| `otlp.intervalMs` | `number` | _(unset)_ | Export flush interval. |
-
-#### `ui.*` — Dashboard & widget
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `ui.widgetPlacement` | `aboveEditor \| belowEditor \| bottom` | `bottom` | Where the status widget renders. `bottom` docks inside the crew-vibes footer (very bottom of the screen), falling back to `belowEditor` when no footer sink exists. |
-| `ui.inlinePanel` | `boolean` | `true` | Keyboard-navigable agent rows under the prompt (`↓` from an empty prompt). Yields to any extension that owns the editor component. |
-| `ui.refreshMs` | `number` | `1000` | Internal UI refresh cadence default (not a user-settable `ui.*` schema key — kept here for completeness). |
-| `ui.widgetDefaultFrameMs` | `number` | `1000` | Internal widget frame-budget default (not a user-settable `ui.*` schema key — kept here for completeness). |
-| `ui.widgetMaxLines` | `number` | `8` | Max lines shown by the widget. |
-| `ui.powerbar` | `boolean` | `true` | Show the power bar. |
-| `ui.dashboardPlacement` | `center \| right` | `center` | Dashboard screen position. |
-| `ui.dashboardWidth` | `number` | `72` | Dashboard column width. |
-| `ui.dashboardLiveRefreshMs` | `number` | `1000` | Dashboard live-refresh interval. |
-| `ui.autoOpenDashboard` | `boolean` | `false` | Auto-open the dashboard. |
-| `ui.autoOpenDashboardForForegroundRuns` | `boolean` | `false` | Auto-open only for foreground runs. |
-| `ui.autoCloseDashboardMs` | `number` | _(unset)_ | Auto-close the dashboard after this long. |
-| `ui.showModel` | `boolean` | `true` | Show model names in the UI. |
-| `ui.showTokens` | `boolean` | `true` | Show token counts. |
-| `ui.showTools` | `boolean` | `true` | Show tool activity. |
-| `ui.transcriptTailBytes` | `number` | `1048576` | Bytes of transcript tail kept. |
-| `ui.mascotStyle` | `cat \| armin` | `cat` | Mascot character. |
-| `ui.mascotEffect` | `random \| none \| …` | `random` | Mascot animation effect. |
-
-#### `broker.*` — Inter-Pi broker
-
-> Default is **ON** since v0.9.47 (Linux + macOS). Disable via
-> `broker.enabled: false`, env `PI_CREW_BROKER=0`, or auto-off on Windows.
-
-| Key path | Type | Default | Description |
-|----------|------|---------|-------------|
-| `broker.enabled` | `boolean` | `true` | Master switch for the local socket broker. |
-| `broker.pathHashLen` | `number` (4–32) | `8` | SHA-256 prefix length in the socket filename. |
-| `broker.maxFrameBytes` | `number` (1024–1048576) | `262144` | Max NDJSON frame size (256 KiB). |
-| `broker.outboundQueueCap` | `number` (32–4096) | `256` | Per-connection outbound queue cap. |
-
-> ⚠️ **Trust boundary**: 🔒 keys are blocked from project config — set them in
-> **user config** only. The project config sanitizer silently drops them with a
-> warning so untrusted repos cannot escalate privileges or redirect telemetry.
-
-📖 Interactive config UI: [docs/commands-reference.md#team-settings--config-management](docs/commands-reference.md) · machine-readable: [schema.json](schema.json)
-
----
-
-## Reliability & Trust
-
-### Compaction resilience
-
-pi-crew survives Pi's context compaction. When the context is compacted (auto or manual), in-flight crew runs are detected and a **resume directive** is injected into the post-compaction context, so tasks continue instead of stalling. You'll see a notification like:
-
-```
-Context compacted. 1 pi-crew run(s) still in-flight — use team status to continue.
-```
-
-**Durable event replay** (v0.9.8, L1): even if a dashboard/overlay is briefly gone during compaction or a reconnect, `RunEventBus.onWithReplay()` catches it up with the events it missed, replaying from the durable JSONL log with seq-based dedup — no information loss. (The dashboard wires this up per-run; the primitive is available for any subscriber.)
-
-**Lossless-by-default worker output** (v0.9.8, L4): output-handling thresholds are sized from measured real data (100% of real worker outputs fit without any compaction). When compaction *is* unavoidable, it keeps head+tail instead of head-only truncation, so closing code fences and headings survive — no more `[pi-crew compacted N chars]` markers eating the end of a result.
-
-### Plan-level human-in-the-loop (HITL)
-
-Set `runtime.requirePlanApproval = true` to gate **any workflow** at the plan→execute boundary. After the read-only (planning) phases complete, the run pauses for explicit approval before mutating tasks run:
-
-```
-team api op=approve-plan runId=<runId>   # approve → execute
-  team api op=cancel-plan runId=<runId>    # cancel
-```
-
-This is plan-level (not per-step) — per-step gates would kill the parallelism that's pi-crew's point.
-
-### Cross-run memory (`.crew/knowledge.md`)
-
-Create `.crew/knowledge.md` in your project root with durable learnings (code style, test commands, common pitfalls, past refactors). It's auto-read (up to 16KB) and injected into **every** agent's system prompt — the main session and each crew worker. pi-crew gets better the longer you use it.
-
-```markdown
-# Project Knowledge
-- Tests: run with `npm test` (not jest directly)
-- Style: tabs, not spaces
-- Auth refactor (2026-06): split auth.ts into session.ts + api.ts
-```
-
-### Cost visibility
-
-Every `team summary <runId>` includes a per-role cost report:
-
-```
-═══ Cost Report ═══
-Tokens: 134k (in 112k, out 5.7k, cache-write 16k)
-Cost: $0.7700 across 18 turn(s)
-By role:
-  executor (2 tasks): $0.6100 — 79%, 98k tok, 13 turns
-  reviewer (1 task): $0.1100 — 14%, 23k tok, 3 turns
-```
-
-### Single-agent mode (cliff hedge)
-
-Any workflow can run single-agent instead of multi-agent — composing all phases into one sequential prompt:
-
-```
-team plan team=default workflow=default goal="..." singleAgent=true
-```
-
-This is pi-crew's cliff-resilient mode: the workflow definitions, phase structure, and artifact contracts survive even if a single large-context model outperforms multi-agent teams.
-
----
-
-## Tool Actions
+| User | `~/.pi/agent/pi-crew.json` |
+| User (legacy, still read) | `~/.pi/agent/extensions/pi-crew/config.json` |
+| Project | `.crew/config.json` (legacy layout: `.pi/teams/config.json`; alt: `.pi/pi-crew.json`) |
+
+Most-used keys (full set: [docs/usage.md](docs/usage.md) · [schema.json](schema.json)):
+
+| Key | What it does |
+|-----|--------------|
+| `runtime.mode` 🔒 | `auto \| scaffold \| child-process \| live-session` — how workers execute |
+| `executeWorkers` 🔒 | `false` = dry-run planning only, no child processes |
+| `asyncByDefault` 🔒 | detach every run by default (survives session switches) |
+| `limits.maxConcurrentWorkers` | hard cap on parallel workers |
+| `runtime.maxTurns` | per-task turn ceiling |
+| `runtime.requirePlanApproval` | pause at the plan→execute boundary for approval |
+| `worktree.linkNodeModules` | symlink `node_modules` into task worktrees |
+| `agents.overrides` 🔒 | per-agent `model` / `skills` / `tools` override |
+| `reliability.autoRetry` | auto-retry failed tasks |
+| `broker.enabled` | inter-session message bus; default `true` (`PI_CREW_BROKER=0` always wins; auto-off on native Windows) |
+| `notifications.webhook` 🔒 | opt-in outbound webhook on run completion — one POST per terminal run, quiet-hours-aware, SSRF-guarded (see below) |
+
+🔒 = sensitive: settable in **user config only** — project config silently
+drops these keys with a warning, so untrusted repos can't escalate privileges.
+Environment variables (`PI_CREW_BROKER`, `PI_CREW_USE_BUNDLE`, …) are listed in
+[src/config/env-vars.ts](src/config/env-vars.ts).
+
+### Webhook notifications (US-030)
+
+Disabled by default — **no URL configured means zero network calls**. When a
+run reaches a terminal status (`completed` / `failed` / `cancelled`), and it
+is outside `notifications.quietHours`, pi-crew POSTs one JSON document to
+your URL (5 s timeout, exactly one retry on 5xx/network error, failures never
+affect the run):
 
 ```json
-// Execute workflow (foreground or async)
-{ "action": "run", "team": "default", "goal": "..." }
-{ "action": "run", "team": "default", "goal": "...", "async": true }
-
-// Monitor & control
-{ "action": "status", "runId": "team_..." }
-{ "action": "summary", "runId": "team_..." }
-{ "action": "events", "runId": "team_..." }
-{ "action": "artifacts", "runId": "team_..." }
-{ "action": "cancel", "runId": "team_..." }
-{ "action": "resume", "runId": "team_..." }
-{ "action": "retry", "runId": "team_..." }
-{ "action": "steer", "runId": "team_...", "taskId": "01_explore", "message": "Focus on src/ only" }
-{ "action": "respond", "runId": "team_...", "message": "Answer" }
-{ "action": "wait", "runId": "team_..." }
-
-// Discovery
-{ "action": "list" }
-{ "action": "get", "resource": "team", "team": "default" }
-{ "action": "get", "resource": "agent", "agent": "explorer" }
-{ "action": "get", "resource": "workflow", "workflow": "review" }
-{ "action": "recommend", "goal": "Refactor auth flow" }
-{ "action": "search", "goal": "heartbeat detection" }
-
-// Resource management
-{ "action": "create", "resource": "agent", "config": { "name": "api-reviewer", ... } }
-{ "action": "update", "resource": "team", "name": "backend", "config": { ... } }
-{ "action": "delete", "resource": "workflow", "name": "quick-review" }
-{ "action": "validate" }
-
-// Run maintenance
-{ "action": "cleanup", "runId": "team_..." }
-{ "action": "forget", "runId": "team_...", "confirm": true }
-{ "action": "prune", "olderThanDays": 7, "confirm": true }
-{ "action": "export", "runId": "team_..." }
-{ "action": "import", "path": "/path/to/bundle.tar.gz" }
-
-// Environment & configuration
-{ "action": "doctor", "config": { "smokeChildPi": true } }
-{ "action": "config" }
-{ "action": "init", "config": { "copyBuiltins": true } }
-{ "action": "autonomy", "profile": "assisted" }
-
-// Advanced
-{ "action": "api", "runId": "team_...", "config": { "operation": "read-manifest" } }
-{ "action": "plan", "team": "default", "goal": "..." }
-{ "action": "orchestrate", "planPath": "plan.md", "team": "implementation", "goal": "..." }
-{ "action": "parallel", "config": { "tasks": [{"goal": "...", "agent": "explorer"}] } }
-{ "action": "worktrees", "runId": "team_..." }
-{ "action": "graph", "runId": "team_..." }
-{ "action": "explain", "runId": "team_..." }
-{ "action": "health" }
-{ "action": "doctor" }
-{ "action": "cache" }
-{ "action": "invalidate", "runId": "team_..." }
-
-// Scheduled runs
-{ "action": "schedule", "team": "fast-fix", "goal": "Run tests", "cron": "0 9 * * MON" }
-{ "action": "schedule", "team": "default", "goal": "...", "interval": 3600000 }
-{ "action": "schedule", "team": "research", "goal": "...", "once": "+10m" }
-{ "action": "scheduled" }
-
-// Diagnostics & settings
-{ "action": "config" }
-{ "action": "settings" }
-{ "action": "autonomy" }
-{ "action": "anchor" }
-{ "action": "onboard" }
-{ "action": "auto-summarize" }
-```
-
-📖 Full actions reference (54 schema actions across 5 domain dispatchers: run/status/control/manage/automate): [docs/actions-reference.md](docs/actions-reference.md)
-
----
-
-## Slash Commands
-
-```text
-/team-run [--team=X] [--async] [--worktree] <goal>
-/team-status <runId>
-/team-dashboard
-/team-doctor
-/team-init [--copy-builtins]
-/team-config [key=value]
-/team-autonomy [status|on|off|suggested|assisted]
-```
-
-📖 Full commands reference: [docs/commands-reference.md](docs/commands-reference.md)
-
----
-
-## Resource Discovery
-
-Agents, teams, and workflows are discovered from three layers:
-
-```
-builtin (package)  <  user (~/.pi/agent/)  <  project (.crew/ or .pi/teams/)
-```
-
-Project resources can add new names but **cannot shadow** builtin/user resources.
-
-### Resource Paths
-
-| Type | Builtin | User | Project |
-|------|---------|------|---------|
-| Agent | `agents/*.md` | `~/.pi/agent/agents/*.md` | `.crew/agents/*.md` |
-| Team | `teams/*.team.md` | `~/.pi/agent/teams/*.team.md` | `.crew/teams/*.team.md` |
-| Workflow | `workflows/*.workflow.md` | `~/.pi/agent/workflows/*.workflow.md` | `.crew/workflows/*.workflow.md` |
-
-### Custom Resources with Routing Metadata
-
-```yaml
----
-name: api-reviewer
-description: Reviews API changes
-triggers: api, endpoint, contract
-useWhen: backend API changes, OpenAPI changes
-avoidWhen: docs-only edits
-cost: cheap
-category: backend
----
-Your system prompt here.
-```
-
-📖 Full resource formats: [docs/resource-formats.md](docs/resource-formats.md)
-
----
-
-## State Layout
-
-```
-<crewRoot>/                          # .crew/ (new) or .pi/teams/ (legacy)
-├── state/runs/{runId}/
-│   ├── manifest.json                # run metadata
-│   ├── tasks.json                   # task graph + status
-│   ├── events.jsonl                 # append-only events
-│   └── agents/{taskId}/status.json  # per-agent state
-├── artifacts/{runId}/
-│   ├── goal.md
-│   ├── prompts/{taskId}.md
-│   ├── results/{taskId}.txt
-│   ├── logs/{taskId}.log
-│   └── summary.md
-├── worktrees/{runId}/{taskId}/
-└── imports/{runId}/run-export.json
-```
-
----
-
-## Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `PI_CREW_BROKER=0` | **Disable the inter-pi broker entirely** (always wins over config). Use to opt out of cross-session messaging. |
-| `PI_CREW_BROKER=1` | Explicitly enable the broker (redundant under the v0.9.47 default-on; useful for overriding a config `broker.enabled: false`). |
-| `PI_CREW_USE_BUNDLE=1` | Force-load via bundled `dist/index.mjs` (~19% faster cold-start than strip-types). Default: bundle (since v0.9.17). Set `PI_CREW_USE_BUNDLE=0` to force strip-types fallback. Requires `npm run build:bundle` to have produced `dist/`. |
-| `PI_CREW_EXECUTE_WORKERS=0` | Disable child workers (scaffold mode) |
-| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy disable flag |
-| `PI_TEAMS_MOCK_CHILD_PI=success` | Mock child worker for testing |
-| `PI_TEAMS_PI_BIN=<path>` | Explicit Pi CLI path |
-| `PI_TEAMS_HOME=<path>` | Override home for tests |
-
----
-
-## Development
-
-### Auto-rebuild bundle on edit
-
-For active development on the bundle, run the watcher in a separate terminal:
-
-```bash
-npm run watch:bundle
-```
-
-This watches `src/` + `index.bundle.ts` and rebuilds `dist/index.mjs` after a 300ms debounce. Zero added dependencies (uses native `node:fs.watch` with per-directory watchers).
-
-```bash
-npm run watch:bundle             # watch + auto-rebuild
-npm run watch:bundle --debounce 500  # custom debounce
-node scripts/watch-bundle.mjs --once  # build once and exit (CI prep)
-```
-
-The watcher is the dev-loop companion to `check:bundle-staleness` (CI gate) — together they eliminate the "edit src/foo.ts, forget to rebuild, run stale bundle" failure mode.
-
-```bash
-cd pi-crew
-npm install          # dependencies
-npm test             # unit + integration tests (~6,500 tests)
-npm run test:critical # fast subset: 97 broker/UI tests in ~20s
-npm run typecheck    # tsc --noEmit
-npm run ci           # full CI-equivalent check
-npm pack --dry-run   # package verification
-```
-
-Stats: **476 source files** (112K lines) · **762 test files** (717 unit + 34 integration + 5 smoke + 3 functional + 2 platform + 1 manual) · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
-
----
-
-## Repository layout
-
-After the v0.9.x reorg (~90 commits) the repo is cluster-organised so related
-files live together — source, tests, and docs mirror each other.
-
-```
-src/                         # ~476 TS files
-├── runtime/                 # team-run execution machinery — 15 subdirs + ~77 flat files
-├── state/                   # persistent state layer — 3 subdirs + 12 root files
-├── extension/               # Pi extension surface (register, team-tool, ui glue)
-├── ui/                      # TUI, dashboard, overlays
-├── config/ · utils/ · agents/ · workflows/ · …   # supporting clusters
-test/
-└── unit/                    # mirrors src/ — 35 leaf subdirs + 151 cross-cutting tests at root
-    ├── runtime/ · state/ · extension/ · ui/ · config/ · …
-docs/                        # living docs at root; history in docs/archive/
+"notifications": {
+  "quietHours": "22:00-07:00",
+  "webhook": {
+    "url": "https://hooks.example.com/pi-crew",
+    "enabled": true,
+    "secret": "shared-secret",
+    "allowLocalhost": false
+  }
+}
 ```
 
-- **`src/`** — each top-level dir has a cluster map; the two largest are
-  [`src/runtime/README.md`](src/runtime/README.md) (15 subdirs: child-pi,
-  broker, live-session, recovery, scheduling, verification, model, output,
-  heartbeat, process, goal-workflow, compaction, task-runner, custom-tools,
-  errors) and [`src/state/README.md`](src/state/README.md) (event-log,
-  stores, coordination).
-- **`test/unit/`** — mirrors `src/` 1:1; cross-cutting tests (`round*`,
-  `v0*`, `package-*`, errors, i18n, bundle-*) stay at the root by design.
-  See [`test/unit/README.md`](test/unit/README.md).
-- **`docs/`** — 20 living docs at the root; 27 historical docs moved to
-  `docs/archive/`. See [`docs/README.md`](docs/README.md).
+Payload (PII-safe — no transcripts or events, goal is first-line only):
+`{ "event": "run.terminal", "runId": …, "status": …, "team": …, "goal": …,
+"durationMs": …, "cost": …, "tokens": …, "at": "<ISO>" }`. With `secret`
+set, every request carries `x-pi-crew-signature: sha256=<hmac-sha256(raw body,
+secret)>`. Non-http(s) URLs and loopback/link-local targets (`localhost`,
+`127.0.0.0/8`, `[::1]`, `fe80::/10`, `169.254.0.0/16`) are refused unless you
+set `allowLocalhost: true` explicitly. The whole `webhook` block is 🔒 — user
+config only, so an untrusted repo cannot point your runs at an attacker URL.
 
----
-
-## Documentation
+## Where things live
 
 | Doc | Contents |
 |-----|----------|
-| [docs/actions-reference.md](docs/actions-reference.md) | Full tool actions + examples |
-| [docs/commands-reference.md](docs/commands-reference.md) | Slash commands + `/team-api` |
-| [docs/resource-formats.md](docs/resource-formats.md) | Agent/team/workflow file formats |
-| [docs/usage.md](docs/usage.md) | Usage patterns + config examples |
-| [docs/troubleshooting.md](docs/troubleshooting.md) | Common errors, recovery, and error-code reference (E001–E012) |
-| [docs/architecture.md](docs/architecture.md) | Internal architecture + run flow |
-| [docs/runtime-flow.md](docs/runtime-flow.md) | Runtime execution details |
-| [docs/goals.md](docs/goals.md) | **v0.9.0** Autonomous goal loops (`team action='goal'`) |
-| [docs/dynamic-workflows.md](docs/dynamic-workflows.md) | **v0.9.0** `.dwf.ts` script runtime + trust model |
-| [docs/live-mailbox-runtime.md](docs/live-mailbox-runtime.md) | Mailbox + live-session runtime |
-| [docs/publishing.md](docs/publishing.md) | Release & publish process |
-| [docs/README.md](docs/README.md) | Index of all docs/ (living + subdirs) |
-| [src/runtime/README.md](src/runtime/README.md) | Runtime source cluster map (15 subdirs) |
-| [src/state/README.md](src/state/README.md) | State source cluster map (3 subdirs) |
-| [test/unit/README.md](test/unit/README.md) | Unit-test cluster map (mirrors src/) |
-| [docs/archive/next-upgrade-roadmap.md](docs/archive/next-upgrade-roadmap.md) | Future upgrade roadmap |
-| [schema.json](schema.json) | Config JSON schema |
-
-Research docs (not in package): [`docs/pi-crew-research/`](https://github.com/baphuongna/pi-crew/tree/main/docs) — audits, deep research, distillation notes.
-
----
+| [docs/README.md](docs/README.md) | index of all docs (living + archive) |
+| [docs/usage.md](docs/usage.md) | usage patterns + config examples |
+| [docs/actions-reference.md](docs/actions-reference.md) | all 55 `team` actions with examples |
+| [docs/commands-reference.md](docs/commands-reference.md) | slash commands + `/team-api` |
+| [docs/architecture.md](docs/architecture.md) | internal architecture + run flow |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | common errors, recovery, error codes |
+| [docs/trust-model.md](docs/trust-model.md) | trust boundaries + accepted risks |
+| [docs/dynamic-workflows.md](docs/dynamic-workflows.md) | `.dwf.ts` runtime + its security model |
+| [docs/resource-formats.md](docs/resource-formats.md) | agent/team/workflow file formats |
+| [docs/publishing.md](docs/publishing.md) | release & publish process |
+
+Also: [schema.json](schema.json) (machine-readable config) ·
+[CHANGELOG.md](CHANGELOG.md) (version history) · [`skills/`](skills/) (bundled
+skills) · [NOTICE.md](NOTICE.md) (attributions).
 
 ## Known limitations
 
-This is AI-developed software built for a personal workflow. These are the
-sharp edges I'm aware of — there are almost certainly others I'm not.
+- **`.dwf.ts` scripts are not sandboxed.** They run in plain module scope with
+  full `require`/`process` access (postinstall-equivalent trust). Only run
+  scripts you have reviewed. See
+  [the security model](docs/dynamic-workflows.md#security-model-important).
+- **Workers run with your privileges; verification is best-effort.** Guards
+  (read-only defaults for unknown roles, path allowlists, sensitive-key
+  sanitizing) raise the bar, but they are not a boundary against a malicious
+  worker in the same process. See [docs/trust-model.md](docs/trust-model.md).
+- **AI-developed, single maintainer.** Every change ships after static review
+  + runtime tests, but there is no independent human audit. Found a bug or a
+  sharp edge? [Open an issue](https://github.com/baphuongna/pi-crew/issues).
 
-- **Multi-step goal-wrap crashes non-deterministically.** Goal-wrapping
-  multi-step builtin workflows (`fast-fix`, `default`) can hit a V8/libuv
-  event-loop race that kills the background process with no signal, no core,
-  and no V8 diagnostic report (8 investigation attempts: gdb, strace, perf,
-  `--report-on-fatalerror`, sync-fs workarounds, worker-thread atomic writer —
-  see [CHANGELOG.md](CHANGELOG.md) § v0.9.0 "Phase 1.5 #3").
-  **Mitigation:** multi-step workflows silently auto-downgrade to a normal
-  team-run (no goal-wrap layer); single-step workflows (`implementation`)
-  goal-wrap end-to-end.
-- **`.dwf.ts` scripts are NOT sandboxed in v1.** The `WorkflowCtx` is
-  `Object.freeze()`d, but the script runs in plain module scope with full
-  `require`/`import`/`process` access (postinstall-equivalent trust).
-  `isolated-vm` (real V8 isolate) is planned for a future release. Only place
-  `.dwf.ts` files you have reviewed. See
-  [docs/dynamic-workflows.md#security-model-important](docs/dynamic-workflows.md#security-model-important).
-- **Editor/agent file caching.** After editing a loaded pi-crew source file,
-  restart the Pi session for changes to take effect (jiti in-memory cache).
-  Editing a `.dwf.ts` in place while a run is mid-flight can serve a stale
-  module body; rename the file or restart Pi to force a fresh load.
-- **Verification integrity is best-effort against adversarial workers.** The
-  bookend snapshot (P1a) and git-worktree sandbox (Phase 1.5 #2, opt-in)
-  raise the bar, but a worker in the same process can still tamper with files
-  outside the snapshot window. Full isolation requires the planned sandbox.
-- **Single maintainer + AI review.** Every change ships after 2+ consecutive
-  clean static-review rounds + runtime tests, but there's no independent human
-  audit. Fork and read before trusting anything that touches your data.
+## Development
 
-If you hit any of these — or a new one — please
-[open an issue](https://github.com/baphuongna/pi-crew/issues).
+```bash
+npm install
+npm test                # unit + integration suites
+npm run test:critical   # fast broker/UI subset (~20s)
+npm run typecheck       # tsc --noEmit + strip-types import check
+npm run lint            # biome (linters only)
+npm run format:check    # biome format
+npm run ci              # full gate: checks, typecheck, lint, bundle, tests, pack
+npm run build:bundle    # rebuild dist/index.mjs
+```
 
----
+Running Pi sessions load the pre-built `dist/index.mjs` bundle — rebuild
+(`npm run build:bundle`, or `npm run watch:bundle` while editing) and start a
+new Pi session to pick up source changes.
 
-## Acknowledgements
+## License
 
-`pi-crew` builds on ideas and selected MIT-licensed implementation patterns from `pi-subagents` and `oh-my-claudecode`, with conceptual inspiration from `oh-my-openagent`.
+MIT — see [LICENSE](LICENSE).