@jaggerxtrm/specialists 3.16.0 → 3.18.0

package/README.md

@@ -1,82 +1,141 @@
 # Specialists
 
-**One MCP server. Many specialist agents. Bead-first orchestration.**
-
 [![npm version](https://img.shields.io/npm/v/@jaggerxtrm/specialists.svg)](https://www.npmjs.com/package/@jaggerxtrm/specialists)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 
-Specialists is a project-scoped runtime for running focused AI agents from the CLI, MCP, scripts, CI, or HTTP sidecars. A specialist definition declares its model, tools, permission tier, prompt, skills, output contract, timeout/stall policy, worktree behavior, and tracking behavior. The orchestrator keeps task identity in a **bead**; specialists run as fresh scoped sessions that report evidence, changes, and results back to that bead.
+**Specialists is an agent-mind runtime for getting real work done.**
+
+It is not just “run many agents”. The core idea is that a long single-agent chat becomes cognitively contaminated: old hypotheses, abandoned plans, tool residue, self-review bias, forgotten constraints, and context-window noise all accumulate in one mind. Quality drops because the same context tries to be explorer, implementer, tester, reviewer, security auditor, memory keeper, and release operator at once.
+
+Specialists gives an AI workflow a healthier shape:
+
+- the **orchestrator** stays the central executive — it owns the user intent, task identity, evidence, and publication decision;
+- the **bead** is the contract and durable working memory — problem, scope, success criteria, validation, dependencies, and handoffs live there;
+- **specialists** are fresh, scoped cognitive faculties — explorer, debugger, executor, test-engineer, reviewer, sync-docs, researcher, and domain roles each get only the context, tools, rules, and output contract they need;
+- **structured handoffs** flow back to the orchestrator — results are evidence to consume, not conversational vibes to remember;
+- **workspaces and gates** keep changes publishable — edit-capable roles work in branches/worktrees, reviewer/QA/security roles judge against the contract.
+
+The result is a shared project mind: continuity without hoarding every detail in one agent’s context.
 
 Specialists sits in the xt/xtrm stack:
 
-- **[pi coding agent](https://github.com/Jaggerxtrm/pi-coding-agent)** supplies the model/provider execution layer, JSONL/RPC subprocess boundary, tool events, and extension hooks.
-- **[xtrm-tools](https://github.com/Jaggerxtrm/xtrm-tools)** supplies the surrounding operator workflow: worktree sessions, `.xtrm/` skills/hooks, session reports, update tooling, and workflow enforcement.
-- **[beads](https://github.com/steveyegge/beads)** supplies issue IDs, dependency edges, claims, and durable task/result notes.
+- **[pi coding agent](https://github.com/earendil-works/pi-coding-agent)** executes model sessions and exposes tool events/RPC boundaries.
+- **[xtrm-tools](https://github.com/Jaggerxtrm/xtrm-tools)** provides operator workflow: worktree sessions, `.xtrm/` skills/hooks, reports, update tooling, and gates.
+- **[beads](https://github.com/steveyegge/beads)** provides issue IDs, claims, dependencies, task contracts, and durable notes.
 
-When a run starts from `--bead <id>`, the bead is the task prompt. Dependency context and relevant memory can be injected, the specialist output is appended back to the same bead, and edit-capable specialists work in isolated branches/worktrees that can be reviewed and merged through `sp merge` or `sp epic merge`.
+See [specialists.scheme.md](specialists.scheme.md) for the full rationale.
 
 ---
 
-## Vision
+## Why not one big agent chat?
+
+```mermaid
+flowchart LR
+  Long[One long agent session] --> Residue[Context residue]
+  Long --> Bias[Self-review bias]
+  Long --> Drift[Goal drift]
+  Long --> Noise[Tool/output noise]
+  Long --> Fatigue[Instruction fatigue]
+
+  Residue --> Bad[Lower-quality decisions]
+  Bias --> Bad
+  Drift --> Bad
+  Noise --> Bad
+  Fatigue --> Bad
+
+  Bad --> Symptoms[Symptoms]
+  Symptoms --> Vibes[Reviews become vibes]
+  Symptoms --> Mirrors[Tests mirror implementation]
+  Symptoms --> Scope[Scope silently widens]
+  Symptoms --> Forgotten[Constraints disappear]
+```
+
+The problem is not only token count. It is **cognitive contamination**. A single context window carries every role’s history, including false starts and stale assumptions. The agent starts defending its own implementation, testing what it built instead of what was requested, and treating completion claims as proof.
 
-Specialists turns one overloaded agent chat into a coordinated agent mind: a central orchestrator keeps task identity, evidence, and publication control, while fresh specialist sessions act as scoped capabilities with their own prompts, rules, tools, memory, and output contracts.
+Specialists replaces context hoarding with **contract-bound cognition**.
 
-The problem it solves is not just token count. Long single-agent sessions accumulate old hypotheses, partial plans, tool residue, self-review bias, and forgotten constraints. Specialists uses **contract-bound cognition** instead: write the task contract once, dispatch the right expert role with only the relevant context, require a structured handoff, and let the orchestrator decide the next step.
+---
 
-See [specialists.scheme.md](specialists.scheme.md) for the full diagrams and rationale. The core shape is:
+## The common-mind model
 
 ```mermaid
 flowchart TD
-  U[User / project need] --> O[Orchestrator]
-  O --> B[Bead issue contract]
-  B --> C{Contract ready?}
-  C -->|no| R[Repair scope, success, constraints]
-  R --> B
-  C -->|yes| D[Dispatch specialist]
-
-  D --> E[Explorer\nfresh read-only context]
-  D --> G[Debugger\nfresh root-cause context]
-  D --> X[Executor\nfresh implementation context]
-  D --> T[Test-runner\nfresh validation context]
-  D --> S[Code-sanity / Security\nadvisory context]
-  D --> V[Reviewer\ncontract compliance context]
+  U[User / project need] --> O[Orchestrator\ncentral executive]
+  O --> B[Bead contract\nproblem · scope · success · validation]
+  B --> Check{Contract ready?}
+  Check -->|repair needed| Refine[Refine scope / constraints / outputs]
+  Refine --> B
+  Check -->|ready| O
+
+  O --> Choose{Choose faculty}
+  Choose --> E[Explorer\nfresh read-only context]
+  Choose --> D[Debugger\nfresh root-cause context]
+  Choose --> X[Executor\nfresh implementation context]
+  Choose --> QA[Test-engineer / test-runner\nfresh validation context]
+  Choose --> R[Seconder / reviewer\nfresh judgment context]
+  Choose --> Docs[Sync-docs / service-skills\nfresh documentation context]
+  Choose --> Research[Researcher / domain specialist\nfresh external evidence]
 
   B --> E
-  B --> G
+  B --> D
   B --> X
-  B --> T
-  B --> S
-  B --> V
+  B --> QA
+  B --> R
+  B --> Docs
+  B --> Research
+
+  Rules[Mandatory rules\npermissions · tools · output schema] --> E
+  Rules --> D
+  Rules --> X
+  Rules --> QA
+  Rules --> R
+  Rules --> Docs
+  Rules --> Research
 
   E --> H[Structured handoff / evidence]
-  G --> H
+  D --> H
   X --> H
-  T --> H
-  S --> H
-  V --> H
+  QA --> H
+  R --> H
+  Docs --> H
+  Research --> H
+
   H --> O
-  O --> P[Merge, resume, re-review, or close]
+  O --> Decision{Next decision}
+  Decision -->|resume / steer| Choose
+  Decision -->|fix loop| B
+  Decision -->|publish| Merge[Merge / PR / release]
+  Decision -->|done| Close[Close bead + durable notes]
 ```
 
-## What you can run
+This is close to how a human mind works: a central executive does not consciously compute every perception, motor skill, language move, and memory lookup at once. It activates specialized faculties, receives summaries/evidence, and decides what to do next.
+
+Specialists gives an AI workflow the same structure. The orchestrator remains the “self”; specialists are bounded capabilities that can be activated without permanently polluting the central context.
+
+---
 
-| Need | Specialist / surface |
+## What Specialists lets you do
+
+| Need | Use |
 |---|---|
-| Map unfamiliar local code | `explorer` |
-| Diagnose a bug with unknown cause | `debugger` |
-| Implement a scoped change | `executor` |
-| Review an executor/debugger result | `reviewer --job <exec-job>` |
-| Run/classify tests | `test-runner` |
-| Current library/API/GitHub research | `researcher` |
-| Plan a multi-file feature into beads | `planner` |
-| Check code shape before review | `code-sanity` |
-| Audit security-sensitive diffs | `security-auditor` |
-| Sync exactly one doc | `sync-docs` |
-| Draft changelog gaps | `changelog-keeper` |
-| One-shot script/HTTP generation | `sp script` / `sp serve` |
-
-The live registry is authoritative:
+| Turn vague work into an executable task contract | bead + planner / orchestrator |
+| Map unfamiliar local code | `sp run explorer --bead <id>` |
+| Diagnose a bug with unknown cause | `sp run debugger --bead <id>` |
+| Implement a scoped change in an isolated workspace | `sp run executor --bead <id> --worktree` |
+| Add tests from the actual implementation diff | `test-engineer` |
+| Run and classify validation commands | `test-runner` |
+| Check scope/quality before final review | `seconder` |
+| Review implementation evidence against the bead contract | `sp run reviewer --bead <id> --job <exec-job>` |
+| Research current docs, repos, APIs, papers, or domain evidence | `researcher`, `quant-researcher`, `transcriber` |
+| Sync one stale doc safely | `sync-docs` |
+| Keep service-expert skill docs aligned with code drift | `service-skills-sync` |
+| Generate immediate JSON/text from a specialist | `sp script` or `sp serve` |
+| Watch all active specialist work across repos | `sp console` |
+| Inspect runtime evidence and telemetry | `sp feed`, `sp log`, `sp forensic`, `sp metrics` |
+| Configure package specialists for your machine | `sp init --global`, `sp edit --global`, `sp setup` |
+
+The live catalog is authoritative:
 
 ```bash
 sp list
@@ -85,9 +144,11 @@ sp list-rules
 sp help
 ```
 
+---
+
 ## Install and bootstrap
 
-Specialists is **Bun-only** and expects xtrm-tools to be installed explicitly. xtrm-tools is a runtime prerequisite, not an npm dependency of this package.
+Specialists is **Bun-first** and expects xtrm-tools to be installed explicitly. xtrm-tools is a runtime prerequisite, not an npm dependency of this package.
 
 ```bash
 # 1. Bun
@@ -101,91 +162,124 @@ xt init
 
 # 3. Specialists
 npm install -g @jaggerxtrm/specialists
-sp init
-sp doctor
+sp init --global       # machine-level user config and model defaults
+sp setup --discovery   # inspect available models/config gaps
+sp setup --plan cheap  # optional: propose model assignments
+sp init                # per-repo wiring: MCP, hooks, skills, db paths
+sp doctor --specialists
 sp list
 ```
 
 `sp` is an alias for `specialists`.
 
-`sp init` is an interactive, human-run bootstrap. It checks for `xt` and `.xtrm/`, wires project MCP registration, hooks, skill symlinks, `.specialists/` runtime directories, and the Specialists block in `AGENTS.md`. It does **not** require copying package-owned defaults into every repo.
-
-## Update and drift repair
+### Global model config
 
-Specialists uses two distribution tracks:
+Package specialist definitions ship with `execution.model = null`. This is intentional: the package defines roles, tools, contracts, and safety boundaries; your machine-level config defines provider/model choices.
 
-| Track | Owned by | What it covers | Check / update |
-|---|---|---|---|
-| **Category A** runtime assets | `@jaggerxtrm/specialists` package | specialist JSON, mandatory rules, catalog, nodes, hooks shipped with the package | `sp doctor --check-drift`, `sp prune-stale-defaults --dry-run`, `sp prune-stale-defaults` |
-| **Category B** filesystem assets | xtrm-tools | `.xtrm/skills`, `.claude/skills`, `.pi/skills`, hook snapshots read directly from disk | `xt doctor --cwd <repo> --json`, `xt update --repo <repo> --apply` |
+Use:
 
-`.specialists/user/` is your customization layer. `.specialists/default/` is now only for intentional pins or compatibility snapshots; stale default files are drift debt and `sp prune-stale-defaults` removes them by default. `sp init --sync-defaults` remains as a compatibility path, but it is deprecated because it creates repo-local snapshots that can drift from the package-canonical source.
+```bash
+sp init --global
+sp edit --global
+sp setup --fetch-benchmarks --json
+sp setup --plan <budget-preset>
+sp doctor --specialists
+```
 
-For an interactive, agent-guided update flow that runs both tracks, diagnoses drift, and asks before applying destructive changes, invoke the `/update-specialists` skill in Claude Code instead of running the raw commands manually.
+The loader merges configuration in this order:
 
-## Operator skills
+1. package canonical specialist JSON;
+2. `~/.config/specialists/user.json` global overrides;
+3. `.specialists/user/` repo-local overrides.
 
-These skills load into your Claude Code session on demand and guide the most common operator workflows:
+See [docs/installation.md](docs/installation.md), [docs/bootstrap.md](docs/bootstrap.md), and [docs/authoring.md](docs/authoring.md).
 
-| Skill | Invoke | When to use |
-|---|---|---|
-| `using-specialists-v3` | `/using-specialists-v3` | **Canonical orchestration guide.** Use for any substantial delegated work: implementation, debugging, review, planning, security audit, doc sync, multi-chain epics. Covers bead contracts, role selection, chain lifecycle, merge path, and escalation. |
-| `using-specialists-auto` | `/using-specialists-auto` | **Autonomous / offline mode.** Activates when you hand over a multi-item list and step away ("auto mode", "run the list"). Layers pacing discipline and escalation triggers on top of `using-specialists-v3`. |
-| `update-specialists` | `/update-specialists` | **Guided drift repair.** Runs both Category A and Category B diagnostics, presents a combined plan, and asks before applying anything. Prefer this over running raw `sp`/`xt` commands directly. |
+---
 
-## Core tracked workflow
+## First tracked run
 
 ```bash
-bd create "Investigate auth bug" -t bug -p 1 --json
+bd create "Investigate flaky checkout flow" -t bug -p 1 --json
 bd update <id> --claim --json
 
-sp run debugger --bead <id> --context-depth 3
-sp ps
+sp run explorer --bead <id> --context-depth 2
 sp feed <job-id> --follow
 sp result <job-id>
 
-# Human-in-the-loop alternative: launch with a live TUI
-sp chat debugger --bead <id>          # feed-style timeline + status + final result + input
-
-# After implementation and reviewer PASS
-sp merge <chain-root-bead>          # standalone chain
-sp epic status <epic-id>            # multi-chain publication check
-sp epic merge <epic-id>             # canonical epic publication
+sp run debugger --bead <id> --context-depth 3
+sp run executor --bead <id> --worktree
+sp run reviewer --bead <id> --job <executor-job>
 
-bd close <id> --reason "Done" --json
+bd close <id> --reason "Root cause found, fix reviewed" --json
 ```
 
-Ad-hoc work is still available, but tracked work should use beads:
+Ad-hoc one-offs are still supported, but tracked work should use beads:
 
 ```bash
 sp run explorer --prompt "Map the CLI architecture"
 ```
 
-## Background jobs and monitoring
+---
+
+## Operator console
+
+`sp console` is the multi-repo terminal dashboard for live specialist work.
 
-Normal runtime is DB-first: `.specialists/db/observability.db` stores jobs, events, and results. File mirrors under `.specialists/jobs/` are legacy/operator recovery surfaces.
+It provides:
 
-Useful commands:
+- an **ALL** view aggregating active jobs across configured repos;
+- per-repo tabs and persistent repo registry (`~/.config/specialists/console.json`);
+- job list, feed, result, bead, diff, config, and repo-config views;
+- cursor navigation and direct actions (`↵`, `r`, `i`, `b`, `d`, `g`, `R`, `x`, `0`, `tab`, `1-9`);
+- TUI-styled rows shared with `sp ps`.
 
 ```bash
-sp ps                         # actionable dashboard
-sp ps -f                      # TTY dashboard follow; pipes emit ANSI-free snapshots
-sp feed <job-id>              # full DB-backed event replay
-sp feed -f                    # follow all active jobs
-sp chat explorer --bead <id>    # launch interactive TUI; input auto-steers/resumes
-sp result <job-id> --wait
-sp steer <job-id> "focus only on X"
-sp resume <job-id> "continue with these findings"
-sp finalize <any-chain-job>   # cascade-close waiting keep-alive chain after PASS if needed
+sp console
+sp console --add-repo ~/dev/my-project
+sp console --remove-repo old-project
+```
+
+For shell-only workflows:
+
+```bash
+sp ps
+sp feed <job-id>
+sp feed -f
+sp result <job-id>
+sp log <job-id>
+sp steer <job-id> "focus only on the API boundary"
+sp resume <job-id> "continue with this additional evidence"
+sp stop <job-id>
 sp clean --reap-orphans --dry-run
-sp clean --ps                 # hide terminal dashboard history without deleting DB audit rows
 ```
 
-`sp chat` is for launching a new interactive specialist session. It renders the same normalized feed style as `sp feed -f`, shows startup/payload context and the final result, and maps typed input to `steer` while running or `resume` while waiting. `/quit` and Ctrl+C detach the TUI without stopping the job; use `/stop` when you intend to stop it. Current `sp attach <job-id>` remains the legacy tmux attach path; chat-style attach to an existing job is tracked separately.
+---
+
+## Publication and review
+
+Specialists separates **doing work** from **publishing work**.
+
+- `executor`, `debugger`, `test-engineer`, and `sync-docs` may create changes.
+- `seconder`, `test-runner`, and `reviewer` produce evidence/verdicts.
+- Reviewer PASS is the normal publish gate for implementation work.
+- `sp merge` and `sp epic merge` are publication tools, not authoring tools.
+
+```bash
+# Standalone reviewed chain
+sp merge <chain-root-bead>
+
+# Multi-chain epic
+sp epic status <epic-id>
+sp epic merge <epic-id>
+```
+
+Keep-alive specialists may stop in `waiting` after producing a result. Use `sp result <job-id>` to read the handoff, then `sp stop <job-id>` when no follow-up is needed.
+
+---
 
 ## Script and service specialists
 
-Use `sp run` for interactive agent orchestration. Use the script/service surfaces when you need a synchronous, READ_ONLY, one-shot generation path:
+Use `sp run` for interactive agent orchestration. Use `sp script` / `sp serve` when you need an immediate one-shot generation contract from a specialist.
 
 ```bash
 sp script <name> --vars key=value --json
@@ -195,49 +289,82 @@ curl -sS http://localhost:8000/v1/generate \
   -d '{"specialist":"hello","variables":{"name":"world"}}'
 ```
 
-`sp serve` is intended as a sidecar for script-class specialists. For container deployments, mount the whole `.specialists/` directory read-write, set `HOME=/pi-home`, and align container UID/GID with the host user. See [docs/specialists-service.md](docs/specialists-service.md), [docs/specialists-service-install.md](docs/specialists-service-install.md), and [docs/deploying-alongside.md](docs/deploying-alongside.md).
+Script/service mode is useful for CI, internal services, deterministic JSON generation, and sidecar deployments. Trusted local-script or write-capable execution must be explicitly enabled with the relevant flags; it is not implicit.
+
+See [docs/specialists-service.md](docs/specialists-service.md) and [docs/specialists-service-install.md](docs/specialists-service-install.md).
+
+---
+
+## Observability and telemetry
+
+Specialists is DB-first. Runtime state lives in `.specialists/db/observability.db`; file mirrors under `.specialists/jobs/` are legacy/operator recovery surfaces.
+
+Useful surfaces:
+
+```bash
+sp ps                         # dashboard row view
+sp feed <job-id>              # event stream replay
+sp log <job-id>               # control/status/error log
+sp forensic <job-id> --json   # persisted forensic envelopes
+sp metrics --prometheus       # low-cardinality metrics
+sp serve --port 8000          # exposes /metrics and job feed endpoints
+```
+
+Telemetry uses bounded labels and avoids high-cardinality IDs in Prometheus labels. Forensic events retain drill-down detail in SQLite/JSON output where IDs are appropriate.
+
+---
+
+## Built-in specialist families
+
+| Family | Examples | Purpose |
+|---|---|---|
+| Exploration/debugging | `explorer`, `debugger`, `overthinker` | map systems, find root causes, reason deeply |
+| Implementation/review | `executor`, `reviewer`, `seconder` | write changes, verify scope, check quality |
+| QA | `test-engineer`, `test-runner`, `obligations-scanner` | create tests, run exact commands, track TODO/FIXME obligations |
+| Research | `researcher`, `github-researcher`, `transcriber` | gather current docs, code examples, papers, video transcripts |
+| Documentation/release | `sync-docs`, `service-skills-sync`, `changelog-keeper`, `changelog-drafter` | keep docs and release notes current |
+| Operations | `xt-merge`, `memory-processor`, `node-coordinator` | merge queues, curate memory, coordinate node workers |
+| Domain specialists | `quant-researcher`, `quant-methodologist` | market-data and quantitative-method evidence/methodology |
+
+Run `sp list --compact` for the exact installed catalog and versions.
+
+---
 
 ## Documentation map
 
 | Need | Doc |
 |---|---|
-| Install, update, and distribution model | [docs/installation.md](docs/installation.md) |
-| Project bootstrap and `sp init` | [docs/bootstrap.md](docs/bootstrap.md) |
+| Install, update, global config | [docs/installation.md](docs/installation.md) |
+| Bootstrap a project | [docs/bootstrap.md](docs/bootstrap.md) |
 | Bead-first workflow | [docs/workflow.md](docs/workflow.md) |
 | CLI commands and flags | [docs/cli-reference.md](docs/cli-reference.md) |
-| Background jobs / `ps` / `feed` / `result` | [docs/background-jobs.md](docs/background-jobs.md) |
+| Feature-level behavior | [docs/features.md](docs/features.md) |
+| Background jobs / feed / result | [docs/background-jobs.md](docs/background-jobs.md) |
 | Specialist JSON authoring | [docs/authoring.md](docs/authoring.md) |
-| Built-in specialists | [docs/specialists-catalog.md](docs/specialists-catalog.md) |
-| Tool catalog and permission resolver | [docs/manifest.md](docs/manifest.md) |
-| MCP registration and tool surface | [docs/mcp-servers.md](docs/mcp-servers.md), [docs/mcp-tools.md](docs/mcp-tools.md) |
-| Hooks | [docs/hooks.md](docs/hooks.md) |
-| Skills and operator skill reference | [docs/skills.md](docs/skills.md) |
-| Orchestration skill (`using-specialists-v3`) | [docs/skills.md#using-specialists-v3](docs/skills.md#using-specialists-v3) |
-| Auto mode skill (`using-specialists-auto`) | [docs/skills.md#using-specialists-auto](docs/skills.md#using-specialists-auto) |
-| Update / drift repair skill (`update-specialists`) | [docs/skills.md#update-specialists](docs/skills.md#update-specialists) |
-| Worktrees and session close | [docs/worktrees.md](docs/worktrees.md), [docs/worktree.md](docs/worktree.md) |
-| Runtime architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
-| Pi subprocess isolation / RPC boundary | [docs/pi-session.md](docs/pi-session.md), [docs/pi-rpc-boundary.md](docs/pi-rpc-boundary.md) |
-| NodeSupervisor | [docs/nodes.md](docs/nodes.md) |
-| Service sidecar / HTTP contract | [docs/specialists-service.md](docs/specialists-service.md) |
-| Compose deployment recipe | [docs/deploying-alongside.md](docs/deploying-alongside.md) |
+| Built-in specialist catalog | [docs/specialists-catalog.md](docs/specialists-catalog.md) |
+| MCP server/tool surface | [docs/mcp-servers.md](docs/mcp-servers.md), [docs/mcp-tools.md](docs/mcp-tools.md) |
+| Pi subprocess isolation | [docs/pi-session.md](docs/pi-session.md), [docs/pi-rpc-boundary.md](docs/pi-rpc-boundary.md) |
+| Script/service sidecar | [docs/specialists-service.md](docs/specialists-service.md), [docs/specialists-service-install.md](docs/specialists-service-install.md) |
+| Worktrees and publication | [docs/worktrees.md](docs/worktrees.md), [docs/worktree.md](docs/worktree.md) |
+| Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
 | Release notes | [CHANGELOG.md](CHANGELOG.md) |
 
-## Project structure
+---
+
+## Project layout
 
 ```text
 config/
-├── specialists/       package-canonical specialist definitions (.specialist.json)
-├── mandatory-rules/   package-canonical rule sets injected into specialist prompts
-├── catalog/           package-canonical tool catalog
-├── nodes/             package-canonical node configs
+├── specialists/       package-canonical specialist definitions
+├── mandatory-rules/   package-canonical rule sets injected into prompts
+├── catalog/           tool catalog and permission metadata
+├── nodes/             node coordinator configs
 ├── hooks/             bundled hook scripts
-└── skills/            repo-local skills shipped by this package
+└── skills/            package-shipped skills
 
 .specialists/
-├── user/              repo-owned specialists and overrides (highest precedence)
+├── user/              repo-local specialists and overrides
 ├── default/           optional pins / compatibility snapshots; prune stale files
-├── mandatory-rules/   legacy/repo rule overlay compatibility
 ├── db/                runtime SQLite state (gitignored)
 ├── jobs/              legacy runtime mirror (gitignored)
 └── ready/             legacy ready markers (gitignored)
@@ -249,24 +376,33 @@ config/
 src/                   CLI, server, loader, runner, supervisor, MCP tool
 ```
 
+---
+
 ## Core rules
 
 - Use `--bead` for tracked work; use `--prompt` only for quick untracked work.
-- `--context-depth` controls completed dependency context injection; default is 3 for bead runs.
-- `--no-beads` disables tracking bead creation/updates, but it does not disable reading the input bead when `--bead` is provided.
-- Edit-capable specialists run in isolated worktrees. Review/fix passes should use `--job <exec-job>` to reuse the same workspace.
-- Reviewer PASS is the publish gate. Code-sanity/security/test-runner outputs are advisory evidence, not merge approval.
-- Specialists are project-scoped. User-scope specialist discovery is deprecated.
+- Put scope, success criteria, constraints, validation, and output expectations in the bead before dispatch.
+- Use `--context-depth` to inject completed dependency context; default is 3 for bead runs.
+- Use `--job <prior-job>` when a follow-up role must reuse the same worktree.
+- Prefer `sp console`, `sp ps`, `sp feed`, `sp log`, and `sp result` for operations; inspect raw files only for recovery.
+- Keep package defaults canonical. Put machine preferences in `~/.config/specialists/user.json` and repo exceptions in `.specialists/user/`.
+- Run `sp doctor --specialists` and `xt update --apply` when runtime or xtrm-managed assets drift.
 
-## Deprecated commands
+---
+
+## Deprecated / compatibility surfaces
 
-These commands are still recognized for migration guidance but are no longer onboarding paths:
+These commands or paths may still exist for migration, but they are not the preferred onboarding path:
 
 - `specialists setup`
 - `specialists install`
-- `sp release prepare` / `sp release publish` (deprecated aliases; release flow is skill-driven)
+- `sp init --sync-defaults` for routine setup
+- `.specialists/default/` as an always-synced mirror
+- `sp release prepare` / `sp release publish` aliases (release flow is skill-driven)
 
-Use `sp init`, `xt update`, and the release skill flow instead.
+Use `sp init`, `sp init --global`, `sp setup`, `xt update`, and the release skill flow instead.
+
+---
 
 ## Development
 

package/config/mandatory-rules/json-only-final-output.md

@@ -0,0 +1,13 @@
+---
+name: json-only-final-output
+kind: mandatory-rule
+---
+Final answer must be **JSON only**.
+
+Requirements:
+- No prose before or after the JSON object.
+- No Markdown fences.
+- No headings, bullets, or commentary.
+- Emit exactly one top-level JSON object.
+- Include required top-level keys promised by the specialist contract.
+- If work succeeded but some inner detail is uncertain, keep uncertainty inside JSON fields — never escape into prose.

package/config/mandatory-rules/research-tool-routing.md

@@ -7,6 +7,10 @@ Pick the right source before invoking research. Default to the project knowledge
 - `find-docs` / context7 — library, framework, SDK, CLI, or cloud-service docs (API syntax, config, migration).
 - `deepwiki` — public GitHub repo internals (architecture, conventions, code paths).
 - `github-search` (ghgrep) — real-world code patterns and API usage examples.
+- `ddgs` — general web search, no API key (`ddgs text -q "<query>" -m 8`). Discover authoritative URLs for vendor docs, blogs, papers, or proprietary products the above don't cover.
+- `agent-browser` — read/interact with any URL, including JS-rendered pages (`agent-browser open <url>` → `get text body`; close with `agent-browser close --all`).
 - `last30days` — recent web/social signals (Reddit, X, HN, YouTube). Early-warning only, never authoritative.
 
+General web (not a library/repo/social topic): use `ddgs` to discover URLs, then `agent-browser` to read them. Never point `agent-browser` at a search engine — headless Chrome gets CAPTCHA-blocked; search with `ddgs` instead. If `ddgs`/`agent-browser` aren't installed, report the gap (`uv tool install ddgs`; `npm i -g agent-browser && agent-browser install`) rather than answering from memory.
+
 Invoke skills on demand, not by default. Cite the source for every external claim.

package/config/mandatory-rules/service-skills-diff-scan-mandatory.md

@@ -0,0 +1,26 @@
+---
+name: service-skills-diff-scan-mandatory
+kind: mandatory-rule
+---
+**Phase 2.5 — Diff content scan is mandatory for every drifted service file.**
+
+Between Phase 2(c) (Serena cross-check) and Phase 2(d) (classify), run the actual diff body for each territory file that drifted:
+
+```bash
+git diff <last_sync_ref>..HEAD -- <file>
+```
+
+Grep the diff output for these patterns and feed every hit into Phase 2(d) classify:
+
+- `^[+-]\s*(raise|except)\b` — new/removed exception sites
+- `^[+-]\s*logger\.(error|critical|warning)` — new/removed error logs
+- `^[+-]\s*[A-Z][A-Z0-9_]+\s*=` — env var keys / config constants
+- `^[+-].*container_name:` — docker container renames
+- `^[+-].*@(app|router)\.(get|post|put|delete)` — endpoint additions/removals (FastAPI/Flask/Express)
+- `^[+-].*image:` — docker image refs (rename detection)
+
+**If `last_sync_ref` is unset** (`gitnexus_status: no_ref` or `git diff` returns empty due to missing ref): record `diff-scan-unavailable: no last_sync_ref` in the per-service report and DO NOT emit `audited-and-unchanged`. Treat as a triage-incomplete verdict requiring operator action.
+
+**Token budget:** for each drifted file, sample at most ~200 lines of diff (head + tail). If the diff exceeds that, run `gitnexus_impact` on the file's changed symbols and grep for the keyword set instead.
+
+This scan is complementary to the gitnexus symbol-graph check — it catches non-symbol drift (renamed env vars, new error strings, renamed containers, new endpoints) that the graph cannot see. It does NOT replace gitnexus triage; `audited-and-unchanged` still requires a cited gitnexus signal in addition to a clean diff scan.

package/config/mandatory-rules/service-skills-gitnexus-triage.md

@@ -0,0 +1,5 @@
+---
+name: service-skills-gitnexus-triage
+kind: mandatory-rule
+---
+Service-skills drift triage is gitnexus-backed, not string-based. A failed or absent `drift_detector` pre-script (tier=unknown / gitnexus_status=absent|no_ref|cli_error) is NOT license to skip semantic triage: repair gitnexus first (`npx gitnexus analyze`; have the operator run `xt update --apply` if machinery/last_sync_ref is missing), then re-triage. The `audited-and-unchanged` verdict is gitnexus-only — it must cite a gitnexus signal (detect_changes/impact/context) confirming the SKILL.md's Architecture/Data-Flow/Failure-Mode symbols still exist with documented signatures. If gitnexus genuinely cannot run, emit the weaker `synced (string-level only)` verdict, name what was not verified, and flag a follow-up gitnexus pass. Grep/string matching is a secondary cross-check, never the basis for an "unchanged" verdict.

package/config/mandatory-rules/test-runner-execution-scope.md

@@ -2,4 +2,4 @@
 name: test-runner-execution-scope
 kind: mandatory-rule
 ---
-Run only requested tests. Report failures with root cause and fix hints; do not expand scope.
+Run only requested tests. Exact command input wins over manifest fallback. If fallback is used, label it clearly as fallback. Report failures with root cause, owner classification, and next-recipient hints; do not expand scope.