@jaggerxtrm/specialists 3.17.0 → 3.18.0

package/docs/cli-reference.md

@@ -0,0 +1,1645 @@
+---
+title: CLI Reference
+scope: cli
+category: reference
+version: 2.9.0
+updated: 2026-06-23
+synced_at: bf6baf7a
+description: Complete command reference for the Specialists CLI, generated from current source.
+source_of_truth_for:
+  - src/index.ts
+  - src/cli/run.ts
+  - src/cli/node.ts
+  - src/cli/feed.ts
+  - src/cli/result.ts
+  - src/cli/status.ts
+  - src/cli/chat.ts
+  - src/cli/chat/control.ts
+  - src/cli/chat/feed.ts
+  - src/cli/chat/status.ts
+  - src/cli/attach.ts
+  - src/cli/resume.ts
+  - src/cli/steer.ts
+  - src/cli/stop.ts
+  - src/cli/list.ts
+  - src/cli/models.ts
+  - src/cli/edit.ts
+  - src/cli/init.ts
+  - src/cli/doctor.ts
+  - src/cli/validate.ts
+  - src/cli/config.ts
+  - src/cli/view.ts
+  - src/cli/help.ts
+  - src/cli/ps.ts
+  - src/cli/merge.ts
+---
+
+<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+| [`specialists run`](#specialists-run) | `--epic <id>`, `--force-stale-base`: Epic membership, stale-base bypass; `--prompt`, `--bead`, `--worktree`, `--job`, `--context-depth` |
+| [`specialists node`](#specialists-node) | NodeSupervisor control surface: run/list/promote/members/memory/stop |
+| [`specialists epic`](#specialists-epic) | Epic lifecycle: list/status/resolve/merge (canonical publication path) |
+| [`specialists feed`](#specialists-feed) | `--job <id>`: Filter by job ID |
+| [`specialists log`](#specialists-log) | `-f`: Follow full runtime/control/error logs |
+| [`specialists result`](#specialists-result) | `--wait`: Poll until terminal state |
+| [`specialists status`](#specialists-status) | `--json`: Machine-readable status |
+| [`specialists chat`](#specialists-chat) | Interactive TUI launch/control surface |
+| [`specialists attach`](#specialists-attach) | Legacy tmux attach for jobs with `tmux_session` |
+| [`specialists resume`](#specialists-resume) | No flags |
+| [`specialists steer`](#specialists-steer) | No flags |
+| [`specialists stop`](#specialists-stop) | No flags |
+| [`specialists list`](#specialists-list) | `--category <name>`: Filter by category tag |
+| [`specialists models`](#specialists-models) | `--provider <name>`: Provider substring filter |
+| [`specialists view`](#specialists-view) | Pretty-print specialist config; `--section`, `--raw`, `--all` |
+| [`specialists edit`](#specialists-edit) | Dot-path editing, presets, array ops |
+| [`specialists config`](#specialists-config) | **DEPRECATED** — use `specialists edit` |
+| [`specialists init`](#specialists-init) | | Flag | Description | |
+| [`specialists doctor`](#specialists-doctor) | No flags |
+| [`specialists validate`](#specialists-validate) | `--json`: JSON validation output |
+| [`specialists memory`](#specialists-memory) | `sync\|refresh`, `--force`, `--json`: FTS memory cache management |
+| [`specialists ps`](#specialists-ps) | `--json`: Machine-readable output; `--all`: include terminal jobs; `--follow`/`-f`: live refresh; epic grouping |
+| [`specialists merge`](#specialists-merge) | Standalone chain merge (blocked for epic-owned chains) |
+<!-- END INDEX -->
+
+# CLI Reference
+
+`specialists` has a short alias: `sp`.
+
+---
+
+## `specialists run`
+
+### Synopsis
+
+```bash
+specialists run <name> [--prompt "..."] [--bead <id>] [--worktree] [--job <id>] \
+  [--epic <id>] [--force-stale-base] [--context-depth <n>] [--model <provider/model>] [--no-beads] \
+  [--keep-alive|--no-keep-alive] [--json | --raw]
+```
+
+### Flags
+
+- `--prompt <text>`: Ad-hoc prompt.
+- `--bead <id>`: Read prompt/context from bead.
+- `--worktree`: Explicitly provision (or reuse) an isolated bd-managed worktree for this run. Requires `--bead`.
+- `--job <id>`: Reuse the workspace from a prior job. Mutually exclusive with `--worktree`. When used without `--bead`, bead_id is automatically inferred from the target job's status.json if available.
+- `--epic <id>`: Explicitly declare epic membership for this job. When `--bead` is used, defaults to `bead.parent`; this flag overrides that default. Useful for prep jobs or chain-root jobs that should belong to a merge-gated epic.
+- `--force-stale-base`: Bypass the stale-base guard when provisioning a worktree. The guard blocks dispatch when epic sibling chains have unmerged substantive commits. Use this flag to force provisioning at the caller's risk (may cause merge conflicts later).
+- `--context-depth <n>`: Completed blocker depth for bead context (default `1`).
+- `--model <provider/model>`: Per-run model override.
+- `--no-beads`: Disable tracking bead creation (does **not** disable bead reading when `--bead` is used).
+- `--keep-alive`: Keep session for follow-up `resume` turns (explicit enable).
+- `--no-keep-alive`: Force one-shot run even if specialist YAML has `execution.interactive: true`.
+- `--json`: NDJSON event stream to stdout.
+- `--raw`: Legacy raw token delta stream.
+
+### Examples
+
+```bash
+specialists run debugger --bead unitAI-55d
+specialists run debugger --bead unitAI-55d --context-depth 2
+specialists run reviewer --prompt "Audit src/cli/run.ts"
+cat brief.md | specialists run planner
+specialists run reviewer --prompt "check logs" --json
+specialists run reviewer --prompt "check logs" --raw
+specialists run executor --worktree --bead hgpu.3
+specialists run executor --job a1b2c3 --bead hgpu.4
+specialists run executor --worktree --bead impl-2 --force-stale-base
+specialists run explorer --bead prep-task.1 --epic unitAI-100
+```
+
+### Stale-base guard
+
+When `--worktree` provisions a new worktree, the stale-base guard checks whether sibling chains in the same epic have unmerged substantive commits. If detected, dispatch is blocked:
+
+```
+Error: Epic 'unitAI-3f7b' has sibling chains with unmerged changes.
+  - impl-a: 2 substantive commits on 'feature/unitAI-impl-a-executor'
+  - impl-b: 3 substantive commits on 'feature/unitAI-impl-b-executor'
+Merge sibling chains first via 'sp epic merge unitAI-3f7b', or use --force-stale-base to bypass.
+```
+
+**Why this matters**: When parallel chains branch from the same base, Wave B's worktree lacks Wave A's merged changes. If Wave A merges first, Wave B's diff shows reversions. Rebase at merge-time resolves this, but starting from a stale base increases conflict risk.
+
+Use `--force-stale-base` to bypass when you knowingly accept merge complexity later.
+
+### Worktree guard
+
+Specialists with `permission_required = MEDIUM` or `HIGH` can edit files. For specialists with `requires_worktree=true` (default), `specialists run` now auto-provisions a worktree when `--bead` is provided and `--job` is not used.
+
+Additionally, when `--worktree` is used, the pi session enforces a **write-boundary**: edit/write/multiEdit/notebookEdit tool calls are restricted to paths within the worktree root. Read and bash tools are not intercepted. If a write tool attempts an out-of-bounds path, it falls back to a tmp-fs location (writes to a temp directory that is discarded). This prevents accidental modifications to files outside the isolated worktree.
+
+```
+Error: specialist '<name>' has permission_required=<MEDIUM|HIGH> and requires worktree isolation.
+Provide --bead <id> for automatic worktree provisioning, or use --job <id> to reuse an existing worktree.
+```
+
+Specialists with `permission_required = READ_ONLY` (or unset) are **not** affected — the guard only triggers on edit-capable permissions.
+
+### Exit codes
+
+- `0`: Run completed.
+- `1`: Invalid args, specialist/bead load failure, runtime failure.
+
+Notes:
+- `--prompt` and `--bead` are mutually exclusive.
+- `--worktree` and `--job` are mutually exclusive.
+- `--worktree` requires `--bead <id>` to derive a deterministic branch name.
+- `--epic` can be used standalone or with `--bead`. When used with `--bead`, it overrides the bead's parent epic.
+- `--force-stale-base` bypasses the stale-base guard for worktree provisioning.
+- `--force-job` bypasses the concurrency guard for `--job` reuse.
+- `--no-worktree` was removed.
+- Keep-alive default follows the merged specialist config `execution.interactive` (package / global user.json / repo override; default `false`).
+- Precedence: `--no-keep-alive` > `--keep-alive` > merged `execution.interactive`.
+- `--background` is removed and exits with error.
+- **Auto-bead resolution**: When `--job <id>` is used without `--bead`, bead_id is inferred from the target job's `status.json.bead_id`. Precedence: explicit `--bead` > inferred bead from job > none. A stderr notice indicates when inference occurs.
+
+---
+
+## `specialists node`
+
+### Synopsis
+
+```bash
+specialists node run <node-config-name-or-file> [--inline <json>] [--bead <id>] [--context-depth <n>] [--json]
+specialists node list [--json]
+specialists node promote <node-id> <finding-id> --to-bead <bead-id> [--json]
+specialists node members <node-id> [--json]
+specialists node memory <node-id> [--json]
+specialists node stop <node-id> [--json]
+```
+
+### Subcommands
+
+- `run`: Start a node run from discovered config name, config path, or inline JSON.
+- `list`: List discovered node configs from `config/nodes` then `.specialists/default/nodes` (repo wins on collision).
+- `promote`: Promote one node memory finding into bead notes.
+- `members`: Inspect member generation/status/worktree lineage.
+- `memory`: Inspect node memory entries and aggregate counts.
+- `stop`: SIGTERM coordinator process.
+
+Top-level replacements for flattened node operations:
+- `sp ps` / `sp ps --node <id>` for status/snapshots
+- `sp feed --node <id> [--json]` for node event streams
+- `sp steer <coordinator-job-id> <message>` for coordinator steering
+- `sp attach <coordinator-job-id>` for coordinator attach
+- `sp result <node-ref>:<member-key>` for member results
+
+Node refs accept any unique prefix (for example: `research`, `research-5eaf`, or full ID).
+
+### Flags
+
+Common:
+- `--json`: Machine-readable output.
+
+`run`:
+- `--inline <json>`: Inline node config JSON.
+- `--bead <id>`: Build bead_context from bead + completed blockers.
+- `--context-depth <n>`: Bead blocker depth override for node run context injection.
+
+`promote`:
+- `--to-bead <id>`: Target bead for promoted finding (required).
+
+### Examples
+
+```bash
+specialists node run research --bead unitAI-3f7b.7 --context-depth 2
+specialists node run ./config/nodes/research.node.json --json
+specialists node members research-abc12345 --json
+specialists node memory research-abc12345
+specialists node stop research-abc12345
+specialists node promote research-abc12345 finding-001 --to-bead unitAI-999
+sp ps --node research-abc12345
+sp feed --node research-abc12345 --json
+sp steer <coordinator-job-id> "focus on fix loop for failing gate"
+sp attach <coordinator-job-id>
+sp result research-abc12345:explorer-1
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Invalid args, missing ids, runtime/control failure, or unavailable coordinator control surface.
+
+### Notes
+
+- Coordinator is declarative; NodeSupervisor executes side effects.
+- `--context-depth` on `node run` controls bead dependency context injection for node bootstrap.
+- `node members` and `sp ps --node <id> --json` expose generation/worktree lineage fields used by operator tooling.
+
+---
+
+## `specialists feed`
+
+### Synopsis
+
+```bash
+specialists feed <job-id> [options]
+specialists feed -f [--forever] [options]
+```
+
+### Flags
+
+- `--job <id>`: Filter by job ID.
+- `--specialist <name>`: Filter by specialist.
+- `--since <iso|relative>`: Start time filter (`2026-03-30T10:00:00Z`, `5m`, `1h`, `30s`, `1d`).
+- `--limit <n>`: Max events in snapshot mode (default `100`).
+- `-f`, `--follow`: Live follow mode.
+- `--forever`: In global follow mode, keep following after all jobs complete.
+- `--json`: NDJSON output.
+
+### Examples
+
+```bash
+specialists feed a1b2c3
+specialists feed a1b2c3 --follow
+specialists feed -f
+specialists feed -f --forever
+specialists feed --specialist debugger --since 1h --limit 200
+specialists feed --job a1b2c3 --json
+```
+
+### Output
+
+When a specialist enters the `waiting` state, a **WAIT** banner is displayed:
+
+```
+WAIT  <specialist> (<job-id>) is waiting for input. Use: specialists resume <job-id> "..."
+```
+
+For streamed turn output, `TURN+` lines include an 80-character text preview. When context usage crosses warning thresholds, feed prints context warnings at `WARN` and `CRITICAL` levels.
+
+**Startup context lines** — on `run_start` events with `startup_snapshot`, feed emits a dimmed inline summary:
+
+```
+  ↳ startup job=a1b2c3 specialist=executor bead=unitAI-55d worktree=/repo/.worktrees/... branch=feature/... vars=[bead_context,reviewed_job_id] skills=3
+```
+
+On `meta` events with `memory_injection`, feed emits a memory token accounting line:
+
+```
+  ↳ memory static=1200 dynamic=3400 gitnexus=500 total=5100
+```
+
+`feed` reads from SQLite first and falls back to runtime files when SQLite data is unavailable. It is intentionally compact: use `sp log` when debugging stop/crash/resume/steer provenance.
+
+### Exit codes
+
+- `0`: Success (including no events found).
+- `1`: Unhandled runtime error.
+
+---
+
+## `specialists log`
+
+### Synopsis
+
+```bash
+specialists log [job-id] [options]
+specialists log -f [--specialist <name>] [--bead <id>]
+```
+
+### Flags
+
+- `--job <id>`: Filter to one job id.
+- `--specialist <name>`: Filter by specialist role.
+- `--bead <id>`: Filter by bead id.
+- `--node <id>`: Filter by node id.
+- `--repo <name>`: In parent/global mode, restrict output to one child repo.
+- `--since <iso|relative>`: Start time filter (`5m`, `1h`, ISO timestamp).
+- `--limit <n>`: Max rows in each snapshot (default `200`).
+- `-f`, `--follow`: Poll continuously for new rows.
+- `--json`: NDJSON rows with the full event payload.
+- `--all-events`, `--verbose`: Include agent-internal feed events (`tool`, `turn`, `message`, `text`, `thinking`, token rows).
+
+### Output
+
+`log` is the specialist-runtime/debug stream, not a duplicate of `sp feed`. From a repo root it reads that repo's `.specialists/db/observability.db`; from a parent directory with no local DB it discovers immediate child repos that have `.specialists/db/observability.db` and aggregates them as a global log. Use `--repo <name>` to narrow parent/global output. If exactly one child repo is found, it is used transparently.  By default it hides agent-internal turn/tool/text/thinking/token rows and shows only runtime-owned rows such as `run_start`, `run_complete`, `status_change`, `control_signal`, stale warnings, retries, compactions, extension/API errors, and auto-commit events. Human rows use restrained color (including color-coded `status=<state>`) and compact fields: timestamp, event label, job, specialist, bead, one collapsed `worktree=<repo>/<worktree>` field, status, pid, and event detail. Use `--all-events` when you explicitly need the raw feed-like internals.
+
+Examples:
+
+```bash
+specialists log a1b2c3
+specialists log --bead unitAI-123 --limit 500
+specialists log --specialist reviewer -f
+specialists log -f --json
+specialists log a1b2c3 --all-events
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Invalid args or missing observability DB.
+
+---
+
+## `specialists result`
+
+### Synopsis
+
+```bash
+specialists result <job-id> [--wait] [--timeout <seconds>]
+```
+
+### Flags
+
+- `--wait`: Poll until terminal state.
+- `--timeout <seconds>`: Wait timeout (positive integer).
+
+### Examples
+
+```bash
+specialists result a1b2c3
+specialists result a1b2c3 --wait
+specialists result a1b2c3 --wait --timeout 120
+specialists result a1b2c3 > output.md
+```
+
+### Output
+
+When a job is in the `waiting` state, an explicit message is shown:
+
+```
+--- Session is waiting for your input. Use: specialists resume <job-id> "..." ---
+```
+
+**Startup context block** — `result` derives a startup snapshot from `status.json.startup_context` merged with `run_start` timeline event and `meta` memory_injection. When present, a human-readable block is prepended before output:
+
+```
+--- startup context ---
+job_id: a1b2c3
+specialist_name: executor
+bead_id: unitAI-55d
+worktree_path: /repo/.worktrees/unitAI-55d/unitAI-55d-executor
+branch: feature/unitAI-55d-executor
+variables_keys: bead_context, reviewed_job_id
+skills.count: 3
+skills.activated: sync-docs, clean-code, using-xtrm
+memory.static_tokens: 1200
+memory.memory_tokens: 3400
+memory.gitnexus_tokens: 500
+memory.total_tokens: 5100
+---
+```
+
+In `--json` mode, `startup_context` appears both at top-level and inside `job`:
+
+```json
+{
+  "job": {
+    "id": "a1b2c3",
+    "startup_context": { ... }
+  },
+  "startup_context": { ... },
+  "output": "..."
+}
+```
+
+### Exit codes
+
+- `0`: Result printed.
+- `1`: Job missing, still running with no result file, failed job, timeout, or invalid args.
+
+`result` reads from SQLite first and falls back to runtime files when SQLite data is unavailable. Failed or cancelled jobs include a `sp log <job-id>` hint so the operator can inspect the full runtime/control trail.
+
+---
+
+## `specialists status`
+
+### Synopsis
+
+```bash
+specialists status [--json] [--job <id> | --job=<id>]
+```
+
+### Flags
+
+- `--json`: Machine-readable status.
+- `--job <id>` / `--job=<id>`: Show one job only.
+
+### Output
+
+Waiting jobs are shown in **magenta** with a resume hint:
+
+```
+action  specialists resume <job-id> "..."
+```
+
+In the job list, waiting status includes an inline action:
+
+```
+<id>  <specialist>  waiting  <elapsed>  resume: specialists resume <id> "..."
+```
+
+Status output also includes context telemetry fields:
+- `context_pct`: current context usage percentage.
+- `context_health`: health classification derived from context usage.
+- `is_dead`: computed liveness flag (PID gone OR tmux session gone). Never persisted — computed at read time to avoid stale state.
+
+`status` reads from SQLite first and falls back to runtime files when SQLite data is unavailable.
+
+### Examples
+
+```bash
+specialists status
+specialists status --json
+specialists status --job a1b2c3
+specialists status --job=a1b2c3 --json
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Invalid `--job` usage or unknown job.
+
+---
+
+## `specialists clean`
+
+### Synopsis
+
+```bash
+specialists clean [--all] [--keep <n>] [--processes] [--stale-after <hours>] [--dry-run]
+```
+
+### Flags
+
+- `--all`: Remove every completed job row, regardless of age.
+- `--keep <n>`: Keep N newest completed job rows, remove rest.
+- `--processes`: Cancel stale non-terminal jobs (`running`, `starting`, `waiting`) when PID is dead or `updated_at_ms` is older than `--stale-after`.
+- `--stale-after <hours>`: Staleness threshold for `--processes` mode. Default `24`.
+- `--dry-run`: Show plan only. No DB writes, no directory deletes.
+
+### Behavior
+
+- Default mode is DB-first. Completed jobs are read from `observability.db` via `specialist_jobs`.
+- Terminal cleanup still best-effort removes job directories when present.
+- Missing job directories no longer crash clean.
+- Legacy file-mode fallback stays available when `SPECIALISTS_JOB_FILE_OUTPUT=on` and SQLite has no rows.
+
+### Examples
+
+```bash
+specialists clean
+specialists clean --all
+specialists clean --keep 25
+specialists clean --processes
+specialists clean --processes --stale-after 48
+specialists clean --dry-run
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Invalid args or runtime failure.
+
+---
+
+## `specialists chat`
+
+### Synopsis
+
+```bash
+specialists chat <specialist> [prompt...] [--bead <id>] [--prompt <text>] [--context-depth <n>] [--model <provider/model>]
+```
+
+`sp chat` launches a specialist and opens an interactive TUI around that job. It is the single-screen equivalent of starting a run, following `sp feed -f`, checking status, and sending `sp steer` / `sp resume` messages.
+
+### What the TUI shows
+
+- **Feed area**: normalized timeline lines rendered with the same formatter as `sp feed -f`; startup preamble and raw `stderr:` rows are suppressed while the TUI owns the terminal.
+- **Deduped turn stream**: repeated streaming `THINK` / `TEXT` updates render once per turn phase instead of continuously repainting the same state. The dedupe resets on each new turn.
+- **Startup context**: run-start, payload, mandatory-rules, and memory/context side-lines are shown when timeline metadata is present.
+- **Final result**: `run_complete.output` is appended to the feed so the last assistant result is visible without leaving chat for `sp result`.
+- **Status row**: pinned to the chat job id and displays the actual specialist name, job id, bead id, state, token count, and model.
+- **Input prompt**: accepts freeform follow-up text and slash commands.
+
+### Input behavior
+
+Freeform input is state-aware:
+
+| Job state | Input action | FIFO payload | Equivalent CLI |
+|---|---|---|---|
+| `running` / `starting` | steer current turn | `{"type":"steer","message":"..."}` | `sp steer <job-id> "..."` |
+| `waiting` | resume next keep-alive turn | `{"type":"resume","task":"..."}` | `sp resume <job-id> "..."` |
+| terminal (`done`, `error`, `cancelled`) | rejected | none | inspect with `sp result` |
+
+Slash commands:
+
+| Command | Behavior |
+|---|---|
+| `/quit` | Detach from the TUI and leave the specialist job running/waiting. |
+| `Ctrl+C` | Same as `/quit`: restore the terminal and detach without stopping the job. |
+| `/stop` | Send the normal stop control action for the current job. |
+| `/finalize` | Finalize the current waiting chain/job using the normal finalize path. |
+| `/notes <text>` | Append a note to the current bead. |
+| `/show` | Print current job/bead context in the feed. |
+
+### Examples
+
+```bash
+sp chat explorer "map the release workflow"
+sp chat reviewer --bead unitAI-929wj
+sp chat debugger --prompt "why is sp chat not rendering?" --context-depth 2
+```
+
+### Relationship to `feed`, `result`, `steer`, and `resume`
+
+`sp chat` does not replace the batch/headless commands. Use it when a human wants to stay in a live interactive loop. Use the individual commands for scripts, CI, specialist orchestration, or non-TTY sessions:
+
+- `sp feed -f` — global multi-job observability.
+- `sp feed <job-id> --follow` — per-job feed without an input prompt.
+- `sp result <job-id>` — terminal or latest keep-alive output.
+- `sp steer <job-id> "..."` — explicit mid-turn steering.
+- `sp resume <job-id> "..."` — explicit next-turn prompt for a waiting keep-alive job.
+
+### Exit codes
+
+- `0`: TUI exited cleanly.
+- `1`: Invalid args, specialist/job startup failure, or terminal setup failure.
+
+---
+
+## `specialists attach`
+
+### Synopsis
+
+```bash
+specialists attach <job-id>
+```
+
+### Flags
+
+No flags.
+
+### Examples
+
+```bash
+specialists attach a1b2c3
+```
+
+### Exit codes
+
+- `0`: Successfully attached (returns when tmux session exits/detaches).
+- `1`: Missing args, job missing, terminal job state, missing tmux session, or tmux unavailable.
+
+Notes:
+- `attach` is the legacy tmux attachment path. It requires tmux and a live `tmux_session` recorded in the job `status.json`.
+- It does **not** provide the new chat TUI/feed/input surface. Use `sp chat <specialist> ...` when launching a new interactive TUI session. TUI attach to an existing job is planned separately in bead `unitAI-hx4ln`.
+- For multi-job interactive tmux selection, use `specialists list --live`.
+
+---
+
+## `specialists resume`
+
+### Synopsis
+
+```bash
+specialists resume <job-id> "<task>"
+```
+
+### Flags
+
+No flags.
+
+### Examples
+
+```bash
+specialists resume a1b2c3 "Now write the patch"
+specialists resume a1b2c3 "Focus only on auth"
+```
+
+### Exit codes
+
+- `0`: Resume message sent.
+- `1`: Missing args, missing job, non-waiting status, missing FIFO, or write failure.
+
+---
+
+## `specialists steer`
+
+### Synopsis
+
+```bash
+specialists steer <job-id> "<message>"
+```
+
+### Flags
+
+No flags.
+
+### Notes
+
+Works for **all running jobs** (not just keep-alive sessions). Accepts steering messages for jobs in `running`, `starting`, or `waiting` states.
+
+### Examples
+
+```bash
+specialists steer a1b2c3 "focus only on supervisor.ts"
+specialists steer a1b2c3 "skip tests and isolate root cause"
+```
+
+### Exit codes
+
+- `0`: Steer message sent.
+- `1`: Missing args, missing job, terminal job state, missing FIFO, or write failure.
+
+---
+
+## `specialists finalize`
+
+Manual fallback for keep-alive chains that reached reviewer PASS but whose auto-finalize did not fire (auto-finalize watches the reviewer's streaming output; PASS delivered via `sp resume` does not stream and won't trigger it).
+
+### Synopsis
+
+```bash
+specialists finalize <any-chain-job-id> [--json]
+```
+
+### Behavior
+
+Accepts any job id from the chain (executor, reviewer, debugger). Looks up the chain via `chain_id`, scans its members for a reviewer with `Verdict: PASS` (matches both plain and markdown-bold formats), then **cascades** — closes EVERY waiting keep-alive member of the chain via `supervisor.finalizeWaitingJob()` so chain readiness, status persistence, and FIFO close are atomic.
+
+Refuses if no reviewer in the chain has a PASS verdict, or if all chain members are already terminal.
+
+### Exit codes
+
+- `0`: Chain finalized (one or more members transitioned waiting → done).
+- `1`: Chain not eligible (no reviewer with PASS verdict, no waiting members, or job not found).
+
+---
+
+## `specialists stop`
+
+### Synopsis
+
+```bash
+specialists stop <job-id>
+```
+
+### Flags
+
+No flags.
+
+### Behavior
+
+Before sending SIGTERM, `sp stop` resolves the terminal status:
+
+- If the job has a `run_complete` event in `events.jsonl` → status becomes `done`
+- Otherwise → status becomes `cancelled`
+
+This prevents zombie "waiting" jobs after external kills. Status is written to `status.json` and `observability.db` **before** SIGTERM, ensuring the record reflects the actual outcome. `sp stop` also appends `control_signal` timeline events for stop request, signal delivery, tmux kill, and force-escalation paths.
+
+### Examples
+
+```bash
+specialists stop a1b2c3
+```
+
+### Exit codes
+
+- `0`: Signal sent, already terminal, or process already gone (`ESRCH`).
+- `1`: Missing args, missing job, missing PID, or unexpected kill error.
+
+### Notes
+
+- `cancelled` is a new terminal status distinct from `done`/`error` — indicates intentional stop without completion.
+- `run_complete` evidence is checked via SQLite first, then `events.jsonl` fallback.
+
+---
+
+## `specialists list`
+
+### Synopsis
+
+```bash
+specialists list [--category <name>] [--scope default|user] [--live] [--json]
+```
+
+### Flags
+
+- `--category <name>`: Filter by category tag.
+- `--scope <default|user>`: Filter by specialist scope.
+- `--live`: Show running/waiting tmux sessions and attach via interactive selector.
+- `--show-dead`: In `--live` mode, include jobs whose PID or tmux session is gone (filtered out by default). Useful for debugging dead sessions.
+- `--json`: JSON output.
+
+### Examples
+
+```bash
+specialists list
+specialists list --category analysis
+specialists list --scope user
+specialists list --live
+specialists list --json
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Invalid `--category`/`--scope` usage.
+
+---
+
+## `specialists models`
+
+### Synopsis
+
+```bash
+specialists models [--provider <name>] [--used]
+```
+
+### Flags
+
+- `--provider <name>`: Provider substring filter.
+- `--used`: Show only models currently referenced by specialists.
+
+### Examples
+
+```bash
+specialists models
+specialists models --provider anthropic
+specialists models --used
+specialists models --provider openai --used
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: `pi --list-models` unavailable/failed.
+
+---
+
+## `specialists view`
+
+### Synopsis
+
+```bash
+specialists view [<name>] [--section <section>] [--raw]
+specialists view --all
+```
+
+### Flags
+
+- `--section <section>`: Show one config section only. Supported values: `metadata`, `execution`, `prompt`, `skills`, `capabilities`, `communication`, `validation`, `stall` / `stall-detection`, `beads`.
+- `--raw`: Dump raw JSON to stdout (pipe-friendly).
+- `--all`: Show the full detailed catalog of all specialists without interactive selection.
+
+### Behavior
+
+| Invocation | Behavior |
+|---|---|
+| `sp view <name>` | Pretty-print all sections with ANSI color and readable multi-line prompts |
+| `sp view <name> --section <s>` | Print one section only |
+| `sp view <name> --raw` | Dump raw JSON (piping/scripting) |
+| `sp view --all` | Catalog with model, category, permission badge, keep-alive flag |
+| `sp view` (bare, TTY) | Catalog + interactive name prompt to drill into a specialist |
+| `sp view` (bare, non-TTY) | Catalog only, usage hint printed |
+
+### Examples
+
+```bash
+# Full pretty-print
+specialists view explorer
+
+# Single section
+specialists view executor --section prompt
+specialists view executor --section execution
+specialists view executor --section stall
+
+# Raw JSON for scripting
+specialists view debugger --raw
+specialists view debugger --raw | jq '.specialist.execution'
+
+# Full catalog
+specialists view --all
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Specialist not found, unknown `--section` value, unknown flag, or unexpected argument.
+
+---
+
+## `specialists edit`
+
+### Synopsis
+
+```bash
+# Dot-path syntax (full field coverage)
+specialists edit <name> <dot.path> <value> [options]
+specialists edit <name> --set <dot.path> <value> [options]
+specialists edit <name> --get <dot.path> [--scope <default|user>]
+
+# Global overrides (machine scope, no file-path argument)
+specialists edit --global <name>.<field.path> <value> [options]
+specialists edit --global --get <name>.<field.path>
+specialists edit --global --set <name>.<field.path> <value>
+specialists edit --global
+
+# Bulk operations
+specialists edit --all --set <dot.path> <value> [options]
+specialists edit --all --get <dot.path>
+specialists edit --all
+
+# Presets
+specialists edit <name> --preset <preset> [--dry-run]
+specialists edit --list-presets
+
+# Array operations
+specialists edit <name> --append <dot.path> <value>
+specialists edit <name> --remove <dot.path> <value>
+
+# File-based input (multiline fields)
+specialists edit <name> --file <path> <dot.path>
+```
+
+### Flags
+
+**Dot-path editing** (exactly one field per invocation):
+- Positional: `<dot.path> <value>` or `--set <dot.path> <value>`
+- `--get <dot.path>`: Read a field value
+- `--append <dot.path> <value>`: Append to array field
+- `--remove <dot.path> <value>`: Remove from array field
+- `--file <path>`: Read value from file (for `specialist.prompt.system` or `specialist.prompt.task_template`)
+
+**Presets**:
+- `--preset <name>`: Apply a preset bundle of field values
+- `--list-presets`: Show available presets
+
+**Options**:
+- `--global`: Target shared machine scope at `~/.config/specialists/user.json` (cannot combine with `--scope`)
+- `--scope <default|user>`: Target scope (default: auto-detect)
+- `--dry-run`: Preview changes without writing
+- `--all`: Apply to all specialists
+- `--fork-from <base-name>`: Create `.specialists/user/<name>.specialist.json` fork from resolved base specialist
+
+**Legacy field aliases** (compat only, translated to dot-paths):
+- `--model`, `--fallback-model`, `--description`, `--permission`, `--timeout`, `--tags`
+
+### Dot-Path Syntax
+
+All specialist JSON fields are addressable via dot-notation:
+
+```bash
+# Execution settings
+specialists edit executor --set specialist.execution.model openai-codex/gpt-5.4-mini
+specialists edit executor --set specialist.execution.timeout_ms 180000
+specialists edit executor --set specialist.execution.permission_required HIGH
+specialists edit executor --set specialist.execution.thinking_level medium
+
+# Metadata
+specialists edit executor --set specialist.metadata.description "High-performance code executor"
+specialists edit executor --append specialist.metadata.tags "[\"production\", \"critical\"]"
+
+# Prompt templates
+specialists edit executor --file system.txt specialist.prompt.system
+specialists edit executor --set specialist.prompt.task_template "Review and implement..."
+```
+
+**Array field operations**:
+
+```bash
+# Append tags
+specialists edit executor --append specialist.metadata.tags "security"
+
+# Remove tags
+specialists edit executor --remove specialist.metadata.tags "deprecated"
+
+# Set full array (JSON syntax)
+specialists edit executor --set specialist.metadata.tags '["analysis", "review"]'
+```
+
+### Presets
+
+Presets are predefined field bundles in `config/presets.json`. Built-in presets:
+
+| Preset | Description | Key fields |
+|--------|-------------|------------|
+| `cheap` | Low-cost, fast responses | See `sp edit --list-presets` / `config/presets.json` |
+| `medium` | Balanced cost/quality | See `sp edit --list-presets` / `config/presets.json` |
+| `power` | Maximum capability | See `sp edit --list-presets` / `config/presets.json` |
+
+```bash
+# List available presets
+specialists edit --list-presets
+
+# Apply preset to a specialist
+specialists edit executor --preset power --dry-run
+specialists edit executor --preset medium
+
+# Apply preset to all specialists
+specialists edit --all --preset cheap --dry-run
+```
+
+### Examples
+
+```bash
+# Get current value
+specialists edit executor --get specialist.execution.model
+
+# Set single field
+specialists edit executor specialist.execution.model openai-codex/gpt-5.5
+
+# Global override examples
+specialists edit --global executor.execution.model openai-codex/gpt-5.5
+specialists edit --global --get executor.execution.model
+specialists edit --global --set reviewer.execution.interactive false
+specialists edit --global --set reviewer.stall_detection.waiting_auto_close_ms 3600000
+
+# Legacy alias (compat)
+specialists edit executor --model openai-codex/gpt-5.5
+
+# Apply preset
+specialists edit reviewer --preset power
+
+# Bulk edit all specialists
+specialists edit --all --set specialist.execution.stall_timeout_ms 120000
+
+# Append to tags array
+specialists edit debugger --append specialist.metadata.tags "debugging"
+
+# Read system prompt from file
+specialists edit executor --file ./prompts/executor-system.txt specialist.prompt.system
+
+# Dry-run preview
+specialists edit executor --set specialist.execution.timeout_ms 300000 --dry-run
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Invalid args/values, specialist not found, write failure, preset not found.
+
+### Notes
+
+- Specialist configs are **JSON format** (`.specialist.json`).
+- Ownership model for edits:
+  - package source in `config/specialists/` is upstream fallback, not repo customization surface
+  - `~/.config/specialists/user.json` is machine-wide global override layer (managed by `sp init --global` / `sp edit --global`)
+  - `.specialists/default/` is optional pin / compatibility snapshot state; do not hand-edit; prune stale entries with `sp prune-stale-defaults`
+  - `.specialists/user/` is repo customization/fork layer
+- `--fork-from` supports both same-name override and new-name fork into `.specialists/user/`.
+- All dot-paths must start with `specialist.` (auto-prefixed if omitted).
+- `--all` without other flags opens all config JSON files in `$EDITOR`.
+- Array operations (`--append`, `--remove`) require valid JSON array element syntax.
+
+---
+
+## `specialists config` {#specialists-config}
+
+> **⚠ DEPRECATED** as of 2026-04-06. Use [`specialists edit`](#specialists-edit) instead.
+
+The `specialists config` command is a deprecated alias for `specialists edit`. It will be removed in a future version.
+
+### Migration
+
+| Old command | New command |
+|-------------|-------------|
+| `specialists config get <key> --all` | `specialists edit --all --get <key>` |
+| `specialists config set <key> <value> --all` | `specialists edit --all --set <key> <value>` |
+| `specialists config get <key> --name <n>` | `specialists edit <n> --get <key>` |
+| `specialists config set <key> <value> --name <n>` | `specialists edit <n> --set <key> <value>` |
+
+The new `edit` command supports full dot-path syntax, presets, array operations, and file-based input.
+
+### `specialists config show <name> --resolved` (still canonical)
+
+While `config get`/`config set` are deprecated aliases of `edit`, the `config show <name> --resolved` subcommand has **no equivalent on `edit`** and remains the only surface for inspecting how a specialist's `--tools` argument is computed at session start.
+
+Use `--from-source` inside worktrees when you need resolver behavior from local source instead of installed dist:
+
+```bash
+specialists config show <name> --resolved --from-source
+```
+
+`--from-source` shells out through `bunx tsx src/index.ts ...` and does not need a rebuild. If `bunx` or `tsx` is unavailable, command exits with a clear error.
+
+Output sections (in order):
+
+| Section | Meaning |
+|---------|---------|
+| Resolved JSON | The fully-merged specialist spec with defaults applied |
+| `layer attribution` | Which layer (`catalog`, `specialist_override`, `runtime_health`) contributed which tools |
+| `extension availability` | Live health probe per extension (`pi-gitnexus`, `pi-serena-tools`, native): `loaded_healthy` / `not_installed` / `disabled` / `loaded_unhealthy` / `unknown` |
+| `catalog compatibility` | `ok` if catalog schema version matches |
+| `denied natives` | Tools removed by the specialist's `permissions[<TIER>]` override block (or `(none)`) |
+| `deny mode` | `soft` (preference hint only) or `hard` (tool removed) |
+| `preference signals` | Populated when soft-deny is active |
+| `downgrade reasons` | Populated when hard-deny had to restore natives because an extension was unhealthy |
+| `--tools` | The literal comma-joined string passed to `pi --tools` |
+
+Example for `explorer` (READ_ONLY with hard-deny override on natives):
+
+```text
+layer attribution:
+  - catalog (tool catalogs): read,grep,find,ls
+  - specialist_override (specialist YAML): grep,find,ls
+extension availability:
+  - native: loaded_healthy [none] built-in
+  - gitnexus: loaded_healthy [none] loaded
+  - serena: loaded_healthy [none] loaded
+catalog compatibility:
+  - ok
+denied natives: grep,find,ls
+deny mode: hard
+preference signals: (none)
+downgrade reasons: (none)
+--tools: read,gitnexus_list_repos,gitnexus_query,gitnexus_context,gitnexus_impact,gitnexus_detect_changes,serena_list_tools,find_symbol,...
+```
+
+Use this command after editing a specialist's `permission_required` tier, its `permissions[<TIER>]` override block, or after installing/uninstalling `pi-gitnexus` or `pi-serena-tools` — to confirm the runtime tool set before dispatching a real specialist run.
+
+See [manifest.md](manifest.md) for the full resolution semantics.
+
+---
+
+## `specialists init`
+
+### Synopsis
+
+```bash
+specialists init [--global] [--sync-defaults] [--sync-skills] [--no-xtrm-check]
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--global` | Initialize/update global override layer at `~/.config/specialists/user.json` for cross-repo defaults, keep-alive defaults, waiting auto-close thresholds, and model fallback edits. |
+| `--sync-defaults` | Compatibility/operator path: copy canonical Category A assets into `.specialists/default/`. Not the default install model. |
+| `--sync-skills` | Re-sync skills only through the xtrm-managed skill surface. |
+| `--no-xtrm-check` | Skip `.xtrm/` / `xt` prerequisite checks for CI or tests. |
+
+### Examples
+
+```bash
+sp init                         # per-repo bootstrap
+sp init --global                # seed/update global user override layer for this machine
+sp init --sync-defaults         # deprecated compatibility snapshot only when deliberately needed
+sp init --sync-skills           # skill-only refresh path
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Unhandled runtime error.
+
+What it sets up (always):
+- `.specialists/default/`, `.specialists/user/`
+- `.specialists/jobs/`, `.specialists/ready/`, `.specialists/db/` runtime dirs
+  - `.specialists/jobs/` remains legacy/operator mirror in normal runtime
+- `.gitignore` runtime/db entries
+- `AGENTS.md` Specialists section
+- `.mcp.json` `mcpServers.specialists`
+- `.xtrm/hooks/specialists` + `.claude/hooks` symlinks + `.claude/settings.json` hook wiring
+- `.xtrm/skills/default`, `.xtrm/skills/active`, `.claude/skills` symlink, `.pi/skills` symlink
+
+With `--sync-defaults` only (deprecated compatibility path):
+- populate or refresh `.specialists/default/` snapshots for specialists, mandatory-rules, nodes
+- migrate legacy nested default layout (`default/specialists/*.specialist.json` -> `default/*.specialist.json`)
+
+Prefer `sp doctor --check-drift` and `sp prune-stale-defaults` for current package-canonical installs.
+
+---
+
+### Notes
+
+- Specialist configs are now **JSON format** (`.specialist.json`). YAML files (`.specialist.yaml`) are no longer created.
+- Existing YAML configs are migrated to JSON on first edit or validation.
+
+---
+
+## `specialists doctor`
+
+### Synopsis
+
+```bash
+specialists doctor [orphans] [--specialists] [--check-drift | --drift]
+```
+
+### Flags and subcommands
+
+| Flag / subcommand | Description |
+|---|---|
+| `orphans` | Read-only orphan scan for membership, jobs, epics, and worktree pointers. |
+| `--specialists` / `--check-specialists` | Health check specialist override layers (`sp init --global`, `sp edit --global`, model coverage, blocked-field attempts). |
+| `--check-drift`, `--drift` | Report stale `.specialists/default/` snapshots against package canonical assets. |
+
+### Examples
+
+```bash
+specialists doctor
+specialists doctor --specialists
+specialists doctor orphans
+specialists doctor --check-drift
+```
+
+### Exit codes
+
+- `0`: Always (current implementation reports failures in output, not process exit code).
+
+Checks include:
+- `pi`, `sp`, `bd`, `xt` availability
+- hooks presence/wiring
+- MCP registration
+- runtime directory health
+- zombie running-job detection
+
+---
+
+## `sp prune-stale-defaults`
+
+### Synopsis
+
+```bash
+sp prune-stale-defaults [--dry-run] [--root <path>]
+```
+
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | List stale default snapshots without deleting files. |
+| `--root <path>` | Repo root to scan; defaults to current repo. |
+
+Use this after `sp doctor --check-drift` to remove redundant `.specialists/default/` snapshots. Review `diverged` findings before pruning; user-owned overlays belong in `.specialists/user/`.
+
+---
+
+## xtrm-managed asset commands
+
+Specialists docs reference these xtrm-tools commands for Category B skills/hooks drift:
+
+```bash
+xt doctor --cwd <repo-or-root> --json
+xt doctor --cwd <repo-or-root> --check-drift
+xt update --repo <repo> --apply
+xt update --root <projects-root> --apply
+```
+
+Omit `--apply` for a dry run. `xt doctor` uses `--cwd`; `xt update` uses `--repo` for one repository or `--root` for many.
+
+---
+
+## `specialists ps`
+
+### Synopsis
+
+```bash
+specialists ps [--json] [--all] [--follow | -f]
+                [--running] [--bead <id>] [--since <duration>]
+                [--mine] [--include-terminal] [--node <id>] [<job-id>]
+```
+
+### Flags
+
+- `--json`: Machine-readable JSON output (see [JSON output](#ps-json-output) below).
+- `--all`: Include terminal (`done`/`error`/`cancelled`) jobs **and** terminal epics (merged/abandoned) in addition to active ones. Default shows only `starting`, `running`, `waiting` jobs and non-terminal epics.
+- `--follow` / `-f`: Live-refresh mode — updates in place every 1 second using cursor repositioning (no screen flash).
+- `--running`: Hide jobs not in an active state (`starting`/`running`/`waiting`). Combine with `--all` to broaden the source set, then narrow.
+- `--bead <id>`: Show only jobs whose `bead_id` matches the given id exactly.
+- `--since <duration>`: Show only jobs that started within the last duration. Accepts `<n>s`, `<n>m`, `<n>h`, `<n>d` (e.g. `30m`, `2h`, `1d`).
+- `--mine`: Show only jobs whose linked bead is currently assigned to the current user (resolved via `bd query "assignee=me" --json`). Falls back to no-op if `bd` is unreachable.
+- `--include-terminal`: Show epics in `merged` or `abandoned` state. Default hides them to keep the view focused on active work. Legacy alias `--include-merged` is preserved (covers both states now).
+- `--node <id>`: Show only jobs that belong to the given node id.
+- Positional `<job-id>`: Inspect a single job (full status detail) instead of the snapshot.
+
+Filter flags compose: `--running --bead unitAI-fyih8 --since 1h` returns only active jobs on that bead started in the last hour.
+
+### Description
+
+`specialists ps` gives a process-oriented snapshot of all active jobs grouped by worktree chain. It uses two complementary views:
+
+1. **Flat job list** — every visible job with id, specialist name, context %, elapsed time, bead id + title, and status color.
+2. **Worktree trees** — jobs are grouped under their `worktree_owner_job_id`. Within each tree, node-member jobs are collected under labelled `node:<id>` buckets. Reuse chains (`reused_from_job_id`) are rendered as nested sub-trees.
+
+Sorting: tree roots are ordered by urgency (`waiting > running > starting > done/error`), then by newest start time within each priority tier.
+
+### Output columns (human mode)
+
+```
+<job-id>  <specialist>  <ctx%>  <elapsed>  <bead-id [title]>  <status>
+```
+
+- **ctx%** — context window utilization (read from `context_pct` in `status.json`); `--` when not yet available.
+- **elapsed** — seconds/minutes since job started; `--` when not available.
+- **status** is color-coded: cyan=running, magenta=waiting, green=done, red=error, yellow=starting, gray=cancelled.
+
+Worktree tree section:
+
+```
+<owner-job-id> (branch) /path/to/worktree
+  - <job-id> <specialist> <ctx%> <elapsed> <bead> <status>
+    - <child-job-id> ...   ← reuse chain
+  node:<node-id>
+    - <job-id> ...
+```
+
+### JSON output {#ps-json-output}
+
+```bash
+specialists ps --json
+specialists ps --all --json
+```
+
+Output schema:
+
+```json
+{
+  "generated_at_ms": 1744123456789,
+  "include_terminal": false,
+  "counts": { "jobs": 3, "trees": 2 },
+  "flat": [
+    {
+      "id": "a1b2c3",
+      "specialist": "executor",
+      "status": "running",
+      "bead_id": "unitAI-55d",
+      "bead_title": "Fix the auth bug",
+      "node_id": null,
+      "worktree_owner_job_id": "a1b2c3",
+      "reused_from_job_id": null,
+      "worktree_path": "/repo/.worktrees/unitAI-55d/unitAI-55d-executor",
+      "branch": "feature/unitAI-55d-executor",
+      "started_at_ms": 1744123000000,
+      "elapsed_s": 456,
+      "context_pct": 34,
+      "context_health": "OK"
+    }
+  ],
+  "trees": [ ... ]
+}
+```
+
+### Examples
+
+```bash
+# Active jobs only (default)
+specialists ps
+
+# Include finished jobs
+specialists ps --all
+
+# Live dashboard — auto-refreshes every 1 second
+specialists ps --follow
+specialists ps -f
+
+# Machine-readable snapshot
+specialists ps --json
+specialists ps --all --json
+```
+
+### Data sources
+
+`ps` reads from SQLite first (via `ObservabilitySqliteClient.listStatuses()`). Scanning `status.json` files is legacy/operator fallback only.
+
+### Exit codes
+
+- `0`: Always (no jobs is a valid empty result).
+
+---
+
+## `specialists validate`
+
+### Synopsis
+
+```bash
+specialists validate <name> [--json]
+```
+
+### Flags
+
+- `--json`: JSON validation output.
+
+### Examples
+
+```bash
+specialists validate code-review
+specialists validate code-review --json
+```
+
+### Exit codes
+
+- `0`: Validation passed.
+- `1`: Not found, read error, schema validation failure, or invalid args.
+
+### Notes
+
+- `validate` resolves specialist by runtime precedence (`user` -> `default-mirror` -> `package-fallback`) and reports file path + source in output.
+
+---
+
+## `specialists memory`
+
+### Synopsis
+
+```bash
+specialists memory <sync|refresh> [--force] [--json]
+```
+
+### Subcommands
+
+| Command | Purpose |
+|---------|--------|
+| `sync` | Sync `bd memories` into local SQLite FTS cache when stale or mismatched |
+| `refresh` | Invalidate cache then full rebuild from `bd memories` |
+
+### Flags
+
+- `--force`: Force full rebuild even if cache appears fresh.
+- `--json`: JSON output.
+
+### Examples
+
+```bash
+specialists memory sync
+specialists memory sync --force
+specialists memory refresh
+specialists memory sync --json
+```
+
+### Exit codes
+
+- `0`: Success.
+- `1`: Invalid args or sync failure.
+
+### Notes
+
+- The FTS cache (`specialist_memories_cache` SQLite table) is used by `buildFilteredMemoryInjection()` for keyword-filtered memory retrieval at specialist spawn.
+- Cache auto-syncs on `specialists init` and via PostToolUse hook (`specialists-memory-cache-sync.mjs`).
+- Cache max age: 1 hour (`CACHE_MAX_AGE_MS = 3600000`).
+
+---
+
+## `specialists epic`
+
+### Synopsis
+
+```bash
+specialists epic list [--unresolved] [--json]
+specialists epic status <epic-id> [--json]
+specialists epic sync <epic-id> [--apply] [--json]
+specialists epic merge <epic-id> [--pr] [--rebuild] [--json]
+specialists epic abandon <epic-id> --reason "<text>" [--force] [--json]
+```
+
+### Subcommands
+
+| Command | Purpose |
+|---------|---------|
+| `list` | Enumerate epics with derived readiness state |
+| `status` | Show epic state, chains, blockers, and readiness summary |
+| `sync` | Recompute derived readiness; with `--apply`, repair drift (stale chain refs, dead jobs, redirect markers) |
+| `merge` | Publish all epic-owned chains (canonical path); auto-runs finalize preflight on PASS chains |
+| `abandon` | Mark epic as terminal-cancelled (cleanup escape hatch) |
+
+### Flags
+
+- `--unresolved`: (list) Show only non-terminal epics
+- `--apply`: (sync) Persist drift repairs; without it, sync is read-only
+- `--pr`: (merge) Create pull request instead of direct merge
+- `--rebuild`: (merge) Run `bun run build` after all merges complete
+- `--reason`: (abandon, required) Text recorded in epic transition audit
+- `--force`: (abandon) Override live-member guard
+- `--json`: Machine-readable JSON output
+
+### Epic Lifecycle (derived model)
+
+Epic state is **derived live from chain readiness**, not a persisted state machine. Only three persisted states exist as terminal markers: `merged`, `abandoned`, and an audit-only `open` for newly-created epics. Everything else is recomputed each time it's read.
+
+| Derived state | Meaning | Per-chain merge | Batch merge |
+|-------|---------|:----------:|:----------:|
+| `blocked` | Some chain pending or has no reviewer verdict | — | ✗ |
+| `failed` | At least one chain has a failed reviewer verdict | per-chain only on PASS chains | ✗ |
+| `merge_ready` | All chains pass and no active jobs | ✓ | ✓ |
+| `merged` | (persisted) Publication complete | — | terminal |
+| `abandoned` | (persisted) Cancelled without merge | — | terminal |
+
+**Per-chain `sp merge <chain>` is allowed for any PASS chain regardless of sibling state** — Loop A from the prior chain-lifecycle deadlock is gone. Use `sp epic merge` only when batching all chains together.
+
+**Reviewer PASS auto-finalizes the keep-alive executor** via `supervisor.finalizeWaitingJob()` when the verdict appears in the reviewer's streaming output. PASS delivered via `sp resume` (not streamed) does not trigger auto-finalize — use `sp finalize <any-chain-job-id>` to cascade-close the chain in that case.
+
+**Persisted `failed` is recoverable.** A transient `sp epic merge` failure (rebase conflict, dirty worktree) writes a soft `failed` marker, but the next `sp epic merge` attempt retries fresh once the operator clears the conflict source. Only `merged` and `abandoned` are truly terminal. `validateEpicMergeReadiness` only blocks on those two.
+
+`sp epic abandon` is the cleanup escape hatch for genuinely-unrecoverable epics. Live members require `--force`.
+
+### `sp epic list` Output
+
+```bash
+sp epic list
+# Output:
+# epic:unitAI-3f7b  state:merge_ready  chains:pass=3/3  blockers:[]
+# epic:unitAI-abc1  state:resolving   chains:pass=1/2  blockers:[chain:impl-b]
+# epic:unitAI-xyz  state:open        chains:n/a       blockers:[needs chains]
+
+sp epic list --unresolved
+# Shows only non-terminal epics (open, resolving, merge_ready)
+```
+
+### `sp epic status` Output
+
+```bash
+sp epic status unitAI-3f7b
+# Output:
+# epic_id: unitAI-3f7b
+# persisted_state: resolving
+# readiness_state: merge_ready
+# can_transition: true → merge_ready
+# prep: done=2/2 running=0 failed=0
+# chains:
+#   chain:impl-a  state:pass  reviewer_verdict:pass  has_active_jobs:false
+#   chain:impl-b  state:pass  reviewer_verdict:pass  has_active_jobs:false
+#   chain:impl-c  state:pass  reviewer_verdict:pass  has_active_jobs:false
+# blockers: []
+# summary: Epic unitAI-3f7b is merge-ready and all chains are terminal.
+```
+
+### `sp epic merge` Behavior
+
+1. Reads epic state from observability SQLite
+2. Verifies all chains are terminal (`done`/`error`)
+3. Verifies latest reviewer verdict is PASS for each chain
+4. Topologically sorts chains by bead dependencies
+5. For each chain: **rebase branch onto master** inside worktree (resolves parallel-chain divergence)
+6. For each chain: preview merge delta and check worthiness (blocks empty/noise-only)
+7. For each chain: `git merge <branch> --no-ff --no-edit`
+8. Runs `bunx tsc --noEmit` after each merge
+9. Creates PR if `--pr` is set
+10. Updates epic state to `merged` on success
+
+**Pre-merge rebase**: Before merging each chain, the branch is rebased onto master inside its worktree. This ensures parallel chains (branched from the same base) incorporate earlier waves' changes before publication. If rebase fails with conflicts:
+
+```
+Error: Rebase failed for 'feature/unitAI-impl-a-executor' onto 'master' in worktree '/repo/.worktrees/unitAI-impl-a'.
+Conflicting files:
+  - src/cli/run.ts
+  - src/specialist/supervisor.ts
+Resolve conflicts manually in that worktree, then re-run merge.
+```
+
+Abort is automatic — no partial rebase state remains.
+
+**Safety checks**:
+- Refuses merge if any chain job is non-terminal
+- Refuses merge if any chain lacks PASS verdict
+- Refuses merge if epic state is not `merge_ready` (use `--force-resolving` to auto-transition)
+- Refuses merge if branch has empty delta or noise-only delta (see [Merge-preview worthiness guard](#merge-preview-worthiness-guard))
+
+**File listing**: Uses `git diff HEAD^1 HEAD` for accurate changed-file reporting (not `git diff-tree`).
+
+### Examples
+
+```bash
+# Check epic readiness
+specialists epic status unitAI-3f7b
+
+# Publish all chains (canonical path)
+specialists epic merge unitAI-3f7b
+
+# PR mode instead of direct merge
+specialists epic merge unitAI-3f7b --pr
+
+# Rebuild after merge
+specialists epic merge unitAI-3f7b --rebuild
+```
+
+### Exit codes
+
+- `0`: Success (list/status/resolve/merge completed)
+- `1`: Invalid args, epic not found, chains non-terminal, missing PASS verdicts, merge conflict, or TypeScript gate failure
+
+### Notes
+
+- **This is the canonical publication path** for wave-bound chains.
+- `sp merge <chain-root>` is blocked for chains belonging to unresolved epics.
+- Epic state is persisted in observability SQLite (`epic_runs` table).
+- Chain readiness is computed from reviewer verdicts in job results.
+
+---
+
+## `specialists merge`
+
+### Synopsis
+
+```bash
+specialists merge <chain-root-bead-id> [--rebuild]
+```
+
+### Flags
+
+- `--rebuild`: Run `bun run build` after merge completes.
+
+### Arguments
+
+- `<chain-root-bead-id>`: A **chain-root bead** (single branch merge). **Must NOT belong to an unresolved epic.**
+
+### Behavior
+
+**Standalone chain merge**:
+1. Read bead via `bd show --json`
+2. Check epic membership via `resolveChainEpicMembership()`
+3. If chain belongs to unresolved epic, **refuse merge** with error message
+4. Preview merge delta and evaluate worthiness (refuse empty/noise-only)
+5. Find the newest terminal job with `worktree_path` and `branch` for that bead
+6. **Rebase branch onto master** inside the worktree (resolves parallel-chain divergence)
+7. Merge the branch with `--no-ff --no-edit`
+8. Run TypeScript gate (`bunx tsc --noEmit`)
+9. Print summary with changed files (using `git diff HEAD^1 HEAD`)
+
+**Epic guard**:
+
+If the chain belongs to an epic with status `open`, `resolving`, or `merge_ready`, the merge is blocked:
+
+```
+Error: Chain unitAI-impl belongs to unresolved epic unitAI-3f7b (status: resolving).
+Use 'sp epic merge unitAI-3f7b' to publish all chains together.
+```
+
+This guard ensures wave-bound chains are published atomically via `sp epic merge`.
+
+### Examples
+
+```bash
+# Standalone chain merge (epic guard must pass)
+specialists merge unitAI-55d
+
+# Rebuild after merge
+specialists merge unitAI-55d --rebuild
+```
+
+### Exit codes
+
+- `0`: Merge succeeded, TypeScript gate passed.
+- `1`: Invalid args, bead not found, no chain branch found, **chain belongs to unresolved epic**, **empty/noise-only merge delta**, non-terminal job, merge conflict, or TypeScript gate failure.
+
+### Notes
+
+- **Use `sp epic merge <epic-id>` for wave-bound chains.**
+- This command is only for standalone chains NOT belonging to an epic.
+- Uses `--no-ff` to preserve branch history.
+- Source: `src/cli/merge.ts`
+
+### Merge-preview worthiness guard
+
+Both `sp merge` and `sp epic merge` use a preview-based worthiness guard to prevent merging branches with no substantive changes.
+
+**How it works**:
+
+1. `previewBranchMergeDelta()` — performs a trial merge with `--no-commit`, inspects staged delta against HEAD
+2. Categorizes files into **substantive** and **noise** based on path prefixes
+3. `evaluateMergeWorthiness()` — decides if merge is worth doing
+
+**Noise paths** (ignored for worthiness):
+
+- `.xtrm/reports/`
+- `.wolf/`
+- `.specialists/jobs/` (legacy/operator mirror, not normal-runtime source of truth)
+
+**Blocking conditions**:
+
+| Reason | Meaning | Blocked? |
+|--------|---------|:--------:|
+| `empty-delta` | No files changed at all | ✓ Blocked |
+| `noise-only-delta` | Only noise paths changed | ✓ Blocked |
+| `ok` | At least one substantive file | ✓ Allowed |
+
+**Error output** (when blocked):
+
+```
+Error: Refusing merge for 'feature/unitAI-55d': empty merge delta.
+Diagnostics: beadId=unitAI-55d jobId=a1b2c3 branch=feature/unitAI-55d total=0 substantive=0 noise=0
+
+Error: Refusing merge for 'feature/unitAI-sync': noise-only merge delta.
+Diagnostics: beadId=unitAI-sync jobId=d4e5f6 branch=feature/unitAI-sync total=5 substantive=0 noise=5
+```
+
+**Why this matters**:
+
+- **Old behavior**: hardcoded `src/` check — blocked doc-only merges, config-only merges, skill-only merges
+- **New behavior**: noise-aware preview — allows docs, config, skills, any substantive content
+
+This enables doc-sync specialists and workflow-only changes to merge without false positives.
+
+## Releases (skill-driven)
+
+`sp release prepare/publish` remain as deprecated aliases. Releases now flow through
+`xt release`, which dispatches the `changelog-keeper` MEDIUM specialist via
+`sp script changelog-keeper`. The specialist:
+
+1. Reads relevant xt session reports under `.xtrm/reports/`.
+2. Drafts the new section directly into `CHANGELOG.md`.
+3. Bumps `package.json` `version`.
+4. Runs `npm run build` to refresh `dist/`.
+5. Commits with `release: vX.Y.Z`, tags, pushes `--follow-tags`.
+6. Optional `gh release create` if requested by the bead.
+
+Operator gate is a single `git diff --stat HEAD~1 HEAD` after the specialist
+finishes — must show only `CHANGELOG.md`, `package.json`, `dist/`. Anything
+else means scope was violated (revert and refile).
+
+Mandatory rule `changelog-keeper-scope` enforces the edit whitelist at the
+specialist level. See `config/skills/releasing/SKILL.md` for the bead
+template and recovery commands.