brainclaw 0.29.2 → 1.5.3

package/docs/cli.md

@@ -4,9 +4,9 @@ The CLI is Brainclaw's explicit operator, scripting, release, and fallback surfa
 
 For capable coding agents, prefer MCP for dynamic runtime state:
 
-- `bclaw_bootstrap` instead of manual bootstrap polling
-- `bclaw_get_context` instead of repeated raw CLI context calls
-- `bclaw_list_plans` / `bclaw_list_claims` / `bclaw_get_agent_board` for live coordination views
+- `bclaw_work(intent)` to start working — handles session, context, and claim creation in one call
+- `bclaw_context(kind)` for memory / execution / board reads instead of repeated raw CLI context calls
+- `bclaw_find(entity, filter?)` / `bclaw_get(entity, id)` for plans, claims, candidates, handoffs, and other entities (legacy `bclaw_list_*` / `bclaw_get_context` still work via a redirect warning)
 - `bclaw_claim`, `bclaw_write_note`, and `bclaw_session_end` for session continuity
 
 Use the CLI when a human operator is driving the workflow, when you are scripting setup or release operations, or when MCP is not the integration path.
@@ -56,7 +56,7 @@ brainclaw switch --clear             # clear, revert to cwd
 brainclaw --cwd /other/path status   # one-off override without switching
 ```
 
-**MCP usage:** The active project also affects MCP tools. When `bclaw_get_context()` is called without an explicit path, it resolves context from the active project's store. Agents can also use `BRAINCLAW_PROJECT=<name>` environment variable for the same effect.
+**MCP usage:** The active project also affects MCP tools. When `bclaw_context(kind="memory")` is called without an explicit path, it resolves context from the active project's store. Agents can also use the `BRAINCLAW_PROJECT=<name>` environment variable for the same effect.
 
 ---
 
@@ -224,6 +224,31 @@ When Brainclaw detects generated local agent files such as `.mcp.json` or `.clau
 
 In `multi-project` mode with `projects.strategy: folder`, `doctor` now checks the effective workspace project set, not just `config.projects.known`. That avoids false positives on workspaces that resolve child stores from the filesystem or global project registry.
 
+#### Repair candidates (pln#397)
+
+`doctor --json` also emits a `repair_candidates[]` array listing machine-readable remediation actions. Each entry has `{ action, target, description, safe, related_check }`. Safe candidates are pure-creation or idempotent; unsafe candidates relocate existing files and require explicit confirmation. Consume them with `brainclaw repair`.
+
+### `brainclaw repair`
+
+Apply the structured `repair_candidates[]` surfaced by `doctor`. By default only `safe: true` candidates run; unsafe candidates stay deferred with a clear reason.
+
+| Option | Description |
+|---|---|
+| `--dry-run` | Print the plan without executing anything |
+| `--include-unsafe` | Also apply candidates flagged unsafe (files are **relocated**, never deleted) |
+| `--json` | Output as JSON |
+
+```bash
+brainclaw repair --dry-run          # preview
+brainclaw repair                    # execute safe actions
+brainclaw repair --include-unsafe   # include quarantine etc.
+brainclaw repair --json             # structured output
+```
+
+Preservation guarantees: the repair module never calls `unlink`/`rm`/`rmdir`. Unsafe actions (e.g. malformed inbox messages) are relocated to labelled parking directories such as `coordination/inbox/.quarantine/` so operators can recover them manually. A preservation banner lists exactly what moves and where before execution.
+
+Today the flow covers missing entity subdirectories (`mkdir` action) and inbox hygiene (`move_inbox_message`, `quarantine_inbox_message`). More actions — orphaned agent references, mixed-version drift — land as additional repair candidates emitted by `doctor`.
+
 ### `brainclaw rebuild`
 
 Regenerate `project.md` from canonical state. No options.
@@ -513,12 +538,16 @@ brainclaw instruction "Summarize blockers explicitly" --layer agent --agent open
 
 Record an operational observation during a session.
 
+This is the CLI counterpart of the MCP tool `bclaw_write_note`.
+Use it for session observations, host-specific operator notes, and in-progress findings that are not yet durable decisions or traps.
+For operators who expect a resource-style verb, `brainclaw note create <text>` is accepted as an alias.
+
 | Option | Description |
 |---|---|
-| `--agent <name>` | Authoring agent |
+| `--agent <name>` | Authoring agent; defaults to the configured current agent |
 | `--project <name>` | Associated project |
 | `--plan <id>` | Associated plan ID |
-| `--visibility <scope>` | Visibility scope (e.g. `machine`) |
+| `--visibility <scope>` | Visibility scope: `shared`, `machine`, `private` |
 | `--host <name>` | Pin to a specific host |
 | `--tag <tag>` | Tag for categorization (repeatable) |
 | `--ttl <duration>` | Time-to-live (e.g. `7d`, `24h`) |
@@ -530,6 +559,17 @@ brainclaw runtime-note "Node not on PATH on this host" --visibility machine
 brainclaw runtime-note "Use auth gateway for new routes" --auto-reflect
 ```
 
+### `brainclaw note create <text>`
+
+Resource-style alias for `brainclaw runtime-note <text>`.
+
+Use the same options as `runtime-note` when an operator workflow or wrapper expects `create` semantics.
+
+```bash
+brainclaw note create "Observed host-specific CUDA mismatch on dgx-a"
+brainclaw note create "Need follow-up on launcher script" --plan pln_abc123
+```
+
 ---
 
 ## Memory Review
@@ -779,6 +819,73 @@ brainclaw search "rollout" --since 2026-01-01 --json
 
 For capable agents, prefer the MCP plan and claim tools for live runtime interactions. The CLI remains the operator and scripting form of the same coordination model.
 
+### `brainclaw codev [topic]`
+
+Experimental legacy command. Hidden from the default CLI surface and only registered when `BRAINCLAW_ENABLE_CODEV=1` is set.
+
+Multi-perspective ideation session using persona-based group discussion.
+
+| Option | Description |
+|---|---|
+| `--personas <tier>` | Persona tier: `tier1` (default), `tier2`, or `list` |
+| `--checkpoint` | Pause after clarification for human input (v2 mode only) |
+| `--spawn` | Spawn agent CLI instances for autonomous group discussion (v3 mode) |
+| `--agents <list>` | Comma-separated agent names for spawn (e.g. `claude-code,codex,antigravity`). Default: auto-detect available agents |
+| `--rounds <N>` | Number of discussion rounds in v3 mode (default: 3, minimum: 2) |
+| `--target-duration <seconds>` | Target response duration indicated to agents (default: 120) |
+| `--json` | Output as JSON |
+
+**v3 mode** (`--spawn`): Spawns agents that discuss iteratively in rounds:
+- Round 0 (position): Each agent states their initial position
+- Rounds 1-N (reaction): Agents react to each other's positions
+- Final round (convergence): Identify agreements and remaining tensions
+
+Agents are distributed round-robin across available CLI agents. Each round produces an ideation artifact stored in `.brainclaw/coordination/ideation/`.
+
+**v2 mode** (without `--spawn`): Generates a coordinator prompt for manual facilitation.
+
+Examples:
+```bash
+# Auto-detect agents, 3 rounds
+brainclaw codev "API redesign" --spawn
+
+# Specific agents, 5 rounds, faster target
+brainclaw codev "Migration strategy" --spawn --agents claude-code,codex --rounds 5 --target-duration 90
+
+# List available personas
+brainclaw codev --personas list
+```
+
+### `brainclaw codev-metrics <thread>`
+
+Experimental legacy command. Hidden from the default CLI surface and only registered when `BRAINCLAW_ENABLE_CODEV=1` is set.
+
+Show per-agent average and p95 response time metrics for a CoDev thread. Useful for diagnosing slow agents or comparing model performance across a multi-agent discussion.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+
+```bash
+brainclaw codev-metrics thr_abc123
+brainclaw codev-metrics thr_abc123 --json
+```
+
+### `brainclaw run [profile-name]`
+
+Run an agent profile, or list all available profiles if no name is given. Profiles are named invoke templates that describe how to launch a specific agent CLI for dispatch purposes.
+
+| Option | Description |
+|---|---|
+| `--dry` | Print the resolved command without executing |
+| `--agent <name>` | Override the invoke template with a known agent |
+
+```bash
+brainclaw run                    # list available profiles
+brainclaw run claude-code        # run the claude-code profile
+brainclaw run claude-code --dry  # preview the resolved command
+```
+
 ### `brainclaw plan create <text>`
 
 Create a shared work item.
@@ -802,6 +909,22 @@ brainclaw plan create "Refactor payments module" --project payments --estimate 9
 
 Legacy compatibility: `brainclaw plan "Coordinate auth rollout"`
 
+### `brainclaw plan show <id>`
+
+Display details of a specific plan item.
+
+Use `plan show` for the canonical syntax. `plan get` is accepted as a read alias for operator convenience.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+
+```bash
+brainclaw plan show pln_abc123
+brainclaw plan show pln_abc123 --json
+brainclaw plan get pln_abc123
+```
+
 ### `brainclaw add-step <planId> <text>`
 
 Add a step to an existing plan.
@@ -819,14 +942,19 @@ brainclaw add-step pln_001 "Deploy to staging" --assign devops-bot
 
 Mark a step in a plan as completed. No options.
 
+Use the plan item ID plus the step ID returned by `plan show` or `plan list --json`.
+`brainclaw plan update` updates plan items only; it does not operate on `stp_*` step IDs.
+
 ```bash
-brainclaw complete-step pln_001 step_001
+brainclaw complete-step pln_001 stp_001
 ```
 
 ### `brainclaw plan update <id>`
 
 Update plan status or ownership.
 
+This command expects a plan ID (`pln_*`), not a step ID. To complete a step, use `brainclaw complete-step <planId> <stepId>`.
+
 | Option | Description |
 |---|---|
 | `--status <status>` | Status: `todo`, `in_progress`, `blocked`, `done`, or `dropped` |
@@ -874,10 +1002,78 @@ Update an existing handoff.
 |---|---|
 | `--status <status>` | New status |
 | `--to <name>` | Change recipient |
+| `--narrative <text>` | Replace the handoff narrative |
+| `--reviewer <name>` | Set or override the assigned reviewer |
+| `--review-verdict <verdict>` | Capture a structured review verdict: `approve` or `request_changes` |
+| `--reviewed-by <name>` | Record who produced the verdict |
+| `--review-summary <text>` | Attach a short review summary |
+| `--blocking-issue <text>` | Add a blocking issue (repeatable) |
+| `--suggestion <text>` | Add a non-blocking suggestion (repeatable) |
 
 ```bash
-brainclaw update-handoff hnd_001 --status done
+brainclaw update-handoff hnd_001 --status closed
 brainclaw update-handoff hnd_001 --to alice
+brainclaw update-handoff hnd_001 --review-verdict request_changes --reviewed-by codex --blocking-issue "Null guard missing"
+```
+
+---
+
+## Dispatch
+
+The `dispatch` command group manages the local agent dispatcher: it analyzes the active sequence for lane readiness and assigns work to available agents.
+
+### `brainclaw dispatch analysis`
+
+Analyze the active sequence and show lane status: ready, active, blocked, and done lanes.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+
+```bash
+brainclaw dispatch analysis
+brainclaw dispatch analysis --json
+```
+
+### `brainclaw dispatch run`
+
+Run a dispatch cycle: assign ready lanes to available agents. Optionally preview assignments or spawn CLI agents autonomously.
+
+| Option | Description |
+|---|---|
+| `--agents <names>` | Comma-separated list of agents to dispatch to |
+| `--lanes <names>` | Comma-separated list of lanes to dispatch |
+| `--max <n>` | Maximum number of assignments |
+| `--dry` | Preview assignments without sending messages |
+| `--spawn` | Autonomously launch CLI agents with invoke templates |
+| `--agent <name>` | Dispatcher agent name |
+| `--json` | Output as JSON |
+
+```bash
+brainclaw dispatch run
+brainclaw dispatch run --dry
+brainclaw dispatch run --spawn --agents claude-code,codex
+brainclaw dispatch run --lanes docs,tests --max 2 --json
+```
+
+### `brainclaw dispatch review`
+
+Dispatch code reviews for completed handoffs. Finds handoffs ready for review and sends review assignments to available agents.
+
+| Option | Description |
+|---|---|
+| `--handoff <id>` | Specific handoff ID to review |
+| `--reviewer <name>` | Specific reviewer agent |
+| `--spawn` | Launch the reviewer CLI agent |
+| `--dry` | Preview without sending |
+| `--agent <name>` | Dispatcher agent name |
+| `--json` | Output as JSON |
+
+```bash
+brainclaw dispatch review
+brainclaw dispatch review --handoff hnd_001 --reviewer codex
+brainclaw dispatch review --dry
+brainclaw dispatch review --spawn --json
 ```
 
 ---
@@ -957,6 +1153,94 @@ brainclaw agent-board --suggest --capabilities
 
 ---
 
+## Inbox
+
+The `inbox` command group manages inter-agent messaging. Agents use inbox messages to assign work, request reviews, share information, and carry on structured conversations.
+
+### `brainclaw inbox list`
+
+List inbox messages. Defaults to pending messages only for the current agent.
+
+| Option | Description |
+|---|---|
+| `--agent <name>` | Agent name |
+| `--status <status>` | Filter by status: `pending`, `read`, `acknowledged`, `archived` |
+| `--type <type>` | Filter by type: `assign`, `review`, `rfc`, `info`, `reply` |
+| `--thread <id>` | Filter by thread ID |
+| `--all` | Show all messages, not just pending |
+| `--json` | Output as JSON |
+
+```bash
+brainclaw inbox list
+brainclaw inbox list --all
+brainclaw inbox list --status acknowledged --agent copilot
+brainclaw inbox list --type assign --json
+```
+
+### `brainclaw inbox ack <id>`
+
+Acknowledge a message to confirm receipt.
+
+| Option | Description |
+|---|---|
+| `--agent <name>` | Agent name |
+| `--json` | Output as JSON |
+
+```bash
+brainclaw inbox ack msg_abc123
+brainclaw inbox ack msg_abc123 --agent copilot
+```
+
+### `brainclaw inbox archive <id>`
+
+Archive a message to remove it from the active inbox.
+
+| Option | Description |
+|---|---|
+| `--agent <name>` | Agent name |
+| `--json` | Output as JSON |
+
+```bash
+brainclaw inbox archive msg_abc123
+brainclaw inbox archive msg_abc123 --json
+```
+
+### `brainclaw inbox send <to> <text>`
+
+Send a message to another agent.
+
+| Option | Description |
+|---|---|
+| `--type <type>` | Message type: `assign`, `review`, `rfc`, `info`, `reply` (default: `info`) |
+| `--ref <id>` | Reference to a plan, sequence, or other entity |
+| `--scope <path>` | File scope |
+| `--thread <id>` | Thread ID for conversations |
+| `--ack` | Require acknowledgment from the recipient |
+| `--agent <name>` | Sender agent name |
+| `--json` | Output as JSON |
+
+```bash
+brainclaw inbox send copilot "Please review the auth module changes"
+brainclaw inbox send codex "Ready for review" --type review --ref hnd_001
+brainclaw inbox send alice "Blocked on payments integration" --type rfc --ack
+brainclaw inbox send copilot "Reply on thread" --type reply --thread thr_001
+```
+
+### `brainclaw inbox thread <id>`
+
+Show all messages in a thread, in chronological order.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+
+```bash
+brainclaw inbox thread thr_001
+brainclaw inbox thread thr_001 --json
+```
+
+---
+
 ## Context and Agents
 
 ### `brainclaw context`
@@ -1107,12 +1391,15 @@ Mark the end of an agent work session.
 | `--summary <text>` | Summary of work done |
 | `--auto-reflect` | Automatically reflect runtime notes from the session |
 | `--auto-release` | Automatically release all claims held during the session |
-| `--reflect-handoff` | Reflect any open handoffs as candidates |
+| `--reflect-handoff` | Materialize an open handoff from git commits since session start |
+| `--dispatch-review` | When used with `--reflect-handoff`, auto-dispatch a code review if the handoff is reviewable |
+| `--reviewer <name>` | Explicit reviewer for the reflected handoff review |
 | `--json` | Output as JSON |
 
 ```bash
 brainclaw session-end --auto-release
 brainclaw session-end --session sess_42 --summary "Completed auth refactor" --auto-reflect --auto-release
+brainclaw session-end --auto-release --reflect-handoff --dispatch-review --reviewer codex
 ```
 
 ---
@@ -1229,6 +1516,32 @@ brainclaw check-constraints --staged
 brainclaw check-constraints --files src/payments/index.ts --json
 ```
 
+### `brainclaw check-policy`
+
+Pre-execution policy check. Verifies claims, constraints, traps, and governance instructions for a given scope. Returns blocks (hard stops) and warnings (context to consider).
+
+| Option | Description |
+|---|---|
+| `--scope <path>` | **(required)** File or directory scope to check |
+| `--agent <name>` | Agent name to check claims for |
+| `--agent-id <id>` | Agent ID to check claims for |
+| `--action <type>` | Intended action: edit, create, delete (informational) |
+| `--json` | Output as JSON |
+
+**Checks performed (deterministic, no AI):**
+- **Claim check** — Does the agent have an active claim on the scope? (BLOCK if not)
+- **Claim conflict** — Is the scope claimed by another agent? (BLOCK)
+- **Constraint check** — Do active constraints with matching `related_paths` apply? (WARN)
+- **Trap check** — Are there active traps with matching `related_paths`? (WARN)
+- **Governance context** — Active global/project instructions are displayed for reference.
+
+```bash
+brainclaw check-policy --scope src/core/auth.ts --agent claude-code
+brainclaw check-policy --scope src/commands --json
+```
+
+Exit code: 0 if allowed, 1 if blocked. Also available as MCP tool `bclaw_check_policy`.
+
 ---
 
 ## Sync and Distribution
@@ -1283,6 +1596,95 @@ brainclaw push --remote origin --message "chore: push memory state" --json
 
 ---
 
+## Federation
+
+The `federation` command group manages cloud signal exchange with `app.brainclaw.dev`. Federation requires `BRAINCLAW_CLOUD_API_KEY` to be set. It is a planned premium tier for cross-machine and cross-organization coordination.
+
+### `brainclaw federation push <message>`
+
+Push a test signal to the cloud. The signal is sent from the current project and agent to a target project or broadcast address.
+
+| Option | Description |
+|---|---|
+| `--type <type>` | Signal type (default: `runtime_note`). Accepted values: `signal`, `handoff`, `candidate`, `runtime_note`, `board_snapshot` |
+| `--to-project <project>` | Target project name (default: `broadcast`) |
+| `--to-agent <agent>` | Target agent name |
+
+```bash
+brainclaw federation push "Auth rollout complete" --to-project lodestar
+brainclaw federation push "Blocked on payments" --type runtime_note --to-agent copilot
+```
+
+### `brainclaw federation pull`
+
+Pull signals from the cloud inbox for the current agent.
+
+| Option | Description |
+|---|---|
+| `--agent <name>` | Agent name to pull for (default: auto-detected) |
+| `--since <date>` | Only pull signals after this ISO date |
+| `--limit <n>` | Maximum number of signals to pull (default: 20) |
+
+```bash
+brainclaw federation pull
+brainclaw federation pull --since 2026-04-01
+brainclaw federation pull --agent copilot --limit 50
+```
+
+### `brainclaw federation status`
+
+Check cloud federation configuration: shows the configured cloud URL, whether the API key is set, and pings the cloud health endpoint if configured.
+
+```bash
+brainclaw federation status
+```
+
+---
+
+## Cross-project links
+
+The `link` command group manages local cross-project federation peers — entries stored under `cross_project_links` in `.brainclaw/config.yaml`. These are the targets used by `bclaw_write_note --crossProject`, `bclaw_create(entity='handoff', targetProject=…)`, and the runtime cross-project signal writers in `src/core/cross-project.ts`.
+
+The same entity surface is available through the canonical grammar: `bclaw_create / find / get / update / remove(entity='cross_project_link')`.
+
+### `brainclaw link add <path>`
+
+Register a sibling project as a federation peer. The path is validated to point at an existing brainclaw-initialised directory; the link `name` is auto-derived from the linked project's `project_name` (or its basename) unless `--name` is passed.
+
+| Option | Description |
+|---|---|
+| `--name <slug>` | Override the auto-derived name |
+| `--role <role>` | `publisher` (push signals out) or `subscriber` (default, read-only) |
+| `--channels <list>` | Comma-separated allow-list: `candidate,handoff,runtime_note` |
+| `--force` | Replace an existing link of the same name/path |
+| `--json` | Emit the resulting link entry as JSON |
+
+```bash
+brainclaw link add ../brainclaw-cloud
+brainclaw link add ../brainclaw-site --role publisher --channels candidate,handoff
+brainclaw link add ../brainclaw-cloud --role publisher --force
+```
+
+### `brainclaw link list`
+
+Show every configured cross-project link with its resolved absolute path, role, and availability marker (`✓` if the target directory exists and is brainclaw-initialised).
+
+```bash
+brainclaw link list
+brainclaw link list --json
+```
+
+### `brainclaw link remove <name|path>`
+
+Drop a link from the config. Matches by name, exact `path`, resolved absolute path, or basename of the resolved path — the same matcher used by `resolveCrossProjectTarget`.
+
+```bash
+brainclaw link remove brainclaw-cloud
+brainclaw link remove ../brainclaw-site
+```
+
+---
+
 ## Monitoring and Maintenance
 
 ### `brainclaw watch`
@@ -1326,6 +1728,44 @@ Remove expired memory items.
 brainclaw prune --expired
 ```
 
+### `brainclaw compact`
+
+LLM-driven semantic memory compaction. Archives old items that are superseded or low-signal and provides a summary template for review. Use `--assess` to see what would be compacted before committing.
+
+| Option | Description |
+|---|---|
+| `--assess` | Show pressure assessment and compaction template without archiving |
+| `--dry-run` | Preview eligible items without archiving |
+| `--max-items <n>` | Maximum items to compact (default: 20) |
+| `--min-age <days>` | Minimum age in days for eligibility (default: 7) |
+
+```bash
+brainclaw compact --assess
+brainclaw compact --dry-run
+brainclaw compact --max-items 10 --min-age 14
+```
+
+### `brainclaw refresh`
+
+Refresh live companion files with current state (plans, claims, traps, sequences). These files are gitignored and safe to run frequently. Use this after a bulk memory operation or when an agent's companion view may be stale.
+
+```bash
+brainclaw refresh
+```
+
+### `brainclaw patch-configs`
+
+Patch all MCP config files to use the current brainclaw binary path. Run this after reinstalling or moving the brainclaw binary to ensure all agent MCP integrations point to the correct executable.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+
+```bash
+brainclaw patch-configs
+brainclaw patch-configs --json
+```
+
 ### `brainclaw rollback`
 
 Roll back a memory item to a previous state.
@@ -1344,7 +1784,7 @@ brainclaw rollback --audit-id aud_042 --json
 
 ### `brainclaw audit`
 
-Show the audit log of memory changes.
+Show the audit log of memory changes, or generate a governance posture report.
 
 | Option | Description |
 |---|---|
@@ -1352,11 +1792,25 @@ Show the audit log of memory changes.
 | `--actor <name>` | Filter by actor |
 | `--action <type>` | Filter by action type |
 | `--limit <n>` | Maximum number of entries |
+| `--governance` | Generate an aggregated governance posture report instead of chronological log |
+| `--scope <path>` | Filter governance report by scope (used with `--governance`) |
 | `--json` | Output as JSON |
 
+**Chronological mode (default):** Shows individual audit entries with timestamp, actor, action, and scope.
+
+**Governance mode (`--governance`):** Produces an aggregated posture report:
+- Active global instructions ("constitution vivante")
+- Constraints by category ("red lines")
+- Claims by agent, expired claims needing release
+- Open traps by severity
+- Mutations without claim (last 24h)
+- Actionable recommendations
+
 ```bash
 brainclaw audit --since 2026-03-01 --actor copilot
 brainclaw audit --action accept --limit 20 --json
+brainclaw audit --governance
+brainclaw audit --governance --json
 ```
 
 ### `brainclaw history <id>`
@@ -1382,39 +1836,43 @@ brainclaw mcp
 
 #### Available MCP tools
 
-**Read tools** (no trust requirement):
-
-| Tool | Description |
-|---|---|
-| `bclaw_get_context` | Full workspace context (constraints, decisions, traps, plans, handoffs) |
-| `bclaw_bootstrap` | Derive brownfield bootstrap signals from repo docs and git history |
-| `bclaw_get_execution_context` | Inspect local execution environment and agent tooling signals |
-| `bclaw_read_handoff` | Read an open handoff ticket with git diff and state snapshot |
-| `bclaw_get_agent_board` | Live plan + claim board with active sessions |
-| `bclaw_search` | Full-text BM25 search across all memory items |
-| `bclaw_estimation_report` | Estimation accuracy report for completed plans |
-| `bclaw_list_plans` | List plan items with filters, pagination (`limit`/`offset`), `compact` mode, and direct `id` lookup |
-| `bclaw_list_claims` | List claims with the same filters as `brainclaw claim list` |
-| `bclaw_list_agents` | List registered agents, optionally with bounded reputation summaries |
-| `bclaw_list_instructions` | List raw or resolved shared instructions |
-| `bclaw_list_candidates` | List pending or archived review candidates |
-
-**Write tools** (contributor trust or above):
-
-| Tool | Description |
-|---|---|
-| `bclaw_write_note` | Add a runtime note (supports TTL and auto-reflect) |
-| `bclaw_create_candidate` | Create a memory candidate (decision, constraint, trap, handoff) |
-| `bclaw_accept` | Accept a pending candidate into canonical memory |
-| `bclaw_reject` | Reject a pending candidate |
-| `bclaw_claim` | Claim a work scope (advisory lock) |
-| `bclaw_release_claim` | Release a claim, optionally updating the linked plan status |
-| `bclaw_session_start` | Start an agent session and register identity |
-| `bclaw_session_end` | End session, optionally auto-reflect notes as candidates |
-| `bclaw_create_plan` | Create a new plan item |
-| `bclaw_update_plan` | Update plan status, actual effort, priority, or assignee |
-| `bclaw_add_step` | Add a sub-step to a plan item |
-| `bclaw_complete_step` | Mark a plan sub-step as done |
+The default catalog is intentionally small and centred on the canonical grammar. The full live tool list is the source of truth — see [`docs/integrations/mcp.md`](integrations/mcp.md) and [`docs/concepts/mcp-governance.md`](concepts/mcp-governance.md) for the complete catalog, tier rules, and stability contract.
+
+**Entry facades** — start here:
+
+| Tool | Purpose |
+|---|---|
+| `bclaw_work(intent)` | Start a session, load context, and (for `intent="execute"`) claim a scope in one call. Returns a compact payload by default (pass `compact: false` for the full context). |
+| `bclaw_context(kind)` | Unified context read: `kind` is one of `memory`, `execution`, `board`, `board_summary`, or `delta`. |
+
+**Canonical grammar** — your main tool for working with memory entities (plan, decision, constraint, trap, handoff, runtime_note, candidate, claim, action, assignment, agent_run):
+
+| Tool | Purpose |
+|---|---|
+| `bclaw_find(entity, filter?)` | List entities of a given type with optional filters and pagination. |
+| `bclaw_get(entity, id)` | Read a single entity by id. |
+| `bclaw_create(entity, data)` | Create a new entity (plan, decision, constraint, trap, handoff, candidate, runtime_note, …). |
+| `bclaw_update(entity, id, patch)` | Edit an entity in place. |
+| `bclaw_remove(entity, id, purge?)` | Soft-delete (or purge) an entity. |
+| `bclaw_transition(entity, id, to)` | Change an entity's status (e.g. plan `todo` → `in_progress` → `done`, candidate `pending` → `accepted`). |
+
+**Multi-agent coordination** (escalation path when delegating to other agents):
+
+| Tool | Purpose |
+|---|---|
+| `bclaw_coordinate(intent)` | Assign, consult, review, reroute, or summarize across agents. Pass `open_loop: true` on `intent="review"` to also dispatch the reviewer turn. |
+| `bclaw_dispatch(intent)` | Parallelize execute across a sequence's lanes (analysis / execute / review). |
+| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
+
+**Session, claims, plans, handoffs**:
+
+`bclaw_session_start`, `bclaw_session_end`, `bclaw_claim`, `bclaw_release_claim`, `bclaw_add_step`, `bclaw_complete_step`, `bclaw_update_step`, `bclaw_delete_step`, `bclaw_read_inbox`, `bclaw_ack_message`, `bclaw_send_message`, `bclaw_correct_handoff`.
+
+**Notes, search, setup, navigation**:
+
+`bclaw_write_note`, `bclaw_quick_capture`, `bclaw_search`, `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`, `bclaw_doctor`.
+
+**Legacy per-entity tools** (`bclaw_list_plans` / `bclaw_list_claims` / `bclaw_list_candidates` / `bclaw_list_sequences`, `bclaw_get_context` / `bclaw_get_execution_context` / `bclaw_get_agent_board`, `bclaw_create_plan` / `bclaw_create_candidate`, `bclaw_update_plan` / `bclaw_update_handoff` / `bclaw_update_memory`, `bclaw_read_handoff` / `bclaw_delete_memory`, `bclaw_accept` / `bclaw_reject`, `bclaw_dispatch_analysis` / `bclaw_dispatch_review`, and others) were removed from the discoverable catalog at v1.0. Direct calls still succeed as a migration escape hatch but emit a redirect warning pointing at the canonical grammar. The full removal list and replacement map lives in [`docs/mcp-schema-changelog.md`](mcp-schema-changelog.md) under the v1.0 "Removed" section. Raw MCP clients can request the full advanced catalog with `tools/list` params `{ catalog: "all" }`.
 
 ---
 
@@ -1442,4 +1900,193 @@ brainclaw version --publish-local --release-notes "Add estimation-report command
 - if `brainclaw_update_source` is configured, use it
 - otherwise, fall back to the public npm channel `brainclaw@latest`
 
+If the release changes CLI, MCP, or context-schema behavior, run the release checklist in [release-maintenance.md](release-maintenance.md) before `--publish-local`.
+
+### `brainclaw release-notes`
+
+Generate agent-first release notes from git history.
+
+| Option | Description |
+|---|---|
+| `--from <ref>` | Base git ref (default: latest tag) |
+| `--json` | Output as JSON |
+
+---
+
+## Additional Operational Commands
+
+### `brainclaw uninstall`
+
+Remove brainclaw from a project and/or machine. Cleans up generated agent files, hooks, and MCP configurations.
+
+| Option | Description |
+|---|---|
+| `--global` | Also uninstall the global npm package |
+| `--keep-memory` | Remove agent files but preserve `.brainclaw/` memory |
+| `--json` | Output as JSON |
+
+### `brainclaw discover`
+
+Scan the workspace for MCP configs, instruction files, skills, hooks, and agent integrations. Produces a structured discovery profile saved to `.brainclaw/discovery/`.
+
+| Option | Description |
+|---|---|
+| `--refresh` | Force a fresh scan even if a cached profile exists |
+| `--no-save` | Do not persist the discovery profile |
+| `--json` | Output as JSON |
+
+### `brainclaw migrate`
+
+Migrate memory items between stores (e.g. promote machine-scoped items to user store).
+
+| Option | Description |
+|---|---|
+| `--dry-run` | Show what would be migrated without making changes |
+| `--json` | Output as JSON |
+
+### `brainclaw runtime-status`
+
+Show runtime notes.
+
+| Option | Description |
+|---|---|
+| `--agent <agent>` | Filter by agent |
+| `--plan <id>` | Filter by linked plan item |
+| `--visibility <visibility>` | Visibility filter: `shared`, `machine`, `private`, `all` |
+| `--host <host>` | Include machine-local notes for a specific host |
+| `--all-hosts` | Include machine-local notes from all hosts |
+| `--json` | Output as JSON |
+
+### `brainclaw check-security`
+
+Check supply chain security scores for packages via Socket.dev.
+
+| Option | Description |
+|---|---|
+| `--packages <names>` | Comma-separated package names such as `axios,express` or `axios@1.14.1` |
+| `--ecosystem <type>` | Package ecosystem: `npm` or `pypi` |
+| `--json` | Output as JSON |
+
+### `brainclaw setup-security`
+
+Enable the supply chain security gate by generating wrapper scripts and configuring preinstall checks.
+
+| Option | Description |
+|---|---|
+| `--mode <mode>` | Security mode: `advisory` or `enforced` |
+
+### `brainclaw worktree`
+
+Manage Git worktrees for stronger agent isolation.
+
+Subcommands:
+
+- `brainclaw worktree create <branch>` — create a linked worktree for a branch
+- `brainclaw worktree list` — list known worktrees for the current project
+- `brainclaw worktree remove <path>` — remove a linked worktree
+- `brainclaw worktree prune` — prune stale Git worktree administrative files
+- `brainclaw worktree clean` — remove merged worktrees and orphan directories
+- `brainclaw worktree merge <branch>` — merge a worktree branch with auto-restoration
+
+`create` options:
+
+| Option | Description |
+|---|---|
+| `--session-id <id>` | Associate the worktree with a brainclaw session |
+| `--agent <name>` | Associate the worktree with an agent name |
+
+`remove` options:
+
+| Option | Description |
+|---|---|
+| `--force` | Force removal even with uncommitted changes |
+
+`clean` options:
+
+| Option | Description |
+|---|---|
+| `--force` | Force removal even with uncommitted changes |
+| `--dry-run` | Show what would be removed without actually removing |
+
+`merge` options:
+
+| Option | Description |
+|---|---|
+| `-m, --message <message>` | Merge commit message |
+| `--dry-run` | Show what would be merged without committing |
+
+```bash
+brainclaw worktree clean --dry-run
+brainclaw worktree clean --force
+brainclaw worktree merge feat/my-feature
+brainclaw worktree merge feat/my-feature --dry-run
+```
+
+### `brainclaw memory-log`
+
+Show recent memory change history from the internal git repo.
+
+| Option | Description |
+|---|---|
+| `-n, --limit <count>` | Number of entries to show |
+
+### `brainclaw memory-rollback <ref>`
+
+Restore only the current project's live Brainclaw memory to a previous git snapshot. This command is reserved to registered human identities and preserves durable audit logs, archives, compaction outputs, and backups instead of performing a full destructive reset. Use `memory-log` to find valid refs.
+
+| Option | Description |
+|---|---|
+| `--actor <name>` | Explicit registered human identity to authorize the rollback |
+
+If no human identity is registered yet:
+
+```bash
+brainclaw register-agent <name> --kind human --set-current
+```
+
+### `brainclaw agent-inventory`
+
+Detect all installed AI coding agents and their capabilities on this machine.
+
+| Option | Description |
+|---|---|
+| `--refresh` | Force regeneration even if an inventory already exists |
+| `--json` | Output as JSON |
+
+### `brainclaw projects`
+
+List all brainclaw-initialized projects on this machine from the global registry.
+
+| Option | Description |
+|---|---|
+| `--scan <roots>` | Comma-separated directories to scan for projects |
+| `--register` | Register the current project in the global registry |
+| `--json` | Output as JSON |
+
+### `brainclaw check-events`
+
+Show unseen events from the event bus (`events.jsonl`) for the current agent.
+
+| Option | Description |
+|---|---|
+| `--agent <name>` | Agent to check events for |
+| `--json` | Output as JSON |
+
+### `brainclaw who`
+
+List active agent sessions on this workspace. Shows agent, user, project, claims count, and last activity.
+
+| Option | Description |
+|---|---|
+| `--all` | Include stale sessions |
+| `--gc` | Remove stale sessions |
+
+### `brainclaw usage`
+
+Show brainclaw context volume stats — tokens injected per agent and per MCP tool call.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+
 This keeps end-user installs aware of published npm releases without requiring a local tarball channel. To keep beta testers on a different channel, set `brainclaw_update_source` to `type: npm` with a different `dist_tag`, such as `prelaunch`.