brainclaw 1.9.0 → 1.9.1

package/docs/integrations/mcp.md

@@ -1,95 +1,95 @@
-# MCP Integration
-
-MCP is the primary Brainclaw integration path for capable coding agents.
-
-Use it whenever the agent can retrieve or mutate shared state directly instead of relying only on static files.
-
-## Why MCP Is The Nominal Path
-
-MCP matters because Brainclaw's value is mostly in dynamic state:
-
-- fresh context for the exact path being edited
-- current board state
-- active plans and claims
-- runtime observations
-- handoffs and review queues
-
-Static files still help, but they age immediately. MCP is the stronger path for live coordination.
-
-That now also includes Brainclaw's own install channel state: `bclaw_context({ kind: "execution" })` surfaces whether a newer npm or local-pack build is available, so the agent can notice upgrades without relying on a human to run `brainclaw version --check`.
-
-## Recommended Agent Pattern
-
-The default dynamic workflow is:
-
-1. `bclaw_work` to start the session and load the relevant context in one call (returns compact payload by default — pass `compact: false` for the full context result)
-2. `bclaw_context({ kind: "execution" })` early when the agent needs local tooling signals or package update visibility
-3. `bclaw_context({ kind: "memory" })`, `bclaw_context({ kind: "board" })`, or `bclaw_context({ kind: "delta" })` when the target path changes or full memory is needed beyond the compact summary
-4. `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` for entity reads and writes
-5. `bclaw_coordinate`, `bclaw_dispatch`, or `bclaw_loop` for assign, consult, review, reroute, summarize, dispatch, or multi-turn loop flows
-6. `bclaw_read_inbox` when resuming delegated work
-7. `bclaw_write_note`, `bclaw_quick_capture`, or `bclaw_create({ entity: "candidate", ... })` when the result should become runtime or durable shared memory
-
-This keeps session continuity inside Brainclaw instead of pushing the agent back to manual CLI usage.
-
-When a human operator needs the CLI equivalent of `bclaw_write_note`, use `brainclaw runtime-note <text>`.
-
-## Available Tools
-
-All 59 published MCP tools are discoverable via `tools/list`. Each tool carries an `annotations` object with `tier` and `category` metadata so clients can filter or group tools without server-side hiding.
-
-### Tool tiers
-
-Every tool has one of three tiers in its `annotations.tier` field:
-
-- **facade** — High-level entry points for agents that don't need granular access. Start here.
+# MCP Integration
+
+MCP is the primary Brainclaw integration path for capable coding agents.
+
+Use it whenever the agent can retrieve or mutate shared state directly instead of relying only on static files.
+
+## Why MCP Is The Nominal Path
+
+MCP matters because Brainclaw's value is mostly in dynamic state:
+
+- fresh context for the exact path being edited
+- current board state
+- active plans and claims
+- runtime observations
+- handoffs and review queues
+
+Static files still help, but they age immediately. MCP is the stronger path for live coordination.
+
+That now also includes Brainclaw's own install channel state: `bclaw_context({ kind: "execution" })` surfaces whether a newer npm or local-pack build is available, so the agent can notice upgrades without relying on a human to run `brainclaw version --check`.
+
+## Recommended Agent Pattern
+
+The default dynamic workflow is:
+
+1. `bclaw_work` to start the session and load the relevant context in one call (returns compact payload by default — pass `compact: false` for the full context result)
+2. `bclaw_context({ kind: "execution" })` early when the agent needs local tooling signals or package update visibility
+3. `bclaw_context({ kind: "memory" })`, `bclaw_context({ kind: "board" })`, or `bclaw_context({ kind: "delta" })` when the target path changes or full memory is needed beyond the compact summary
+4. `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` for entity reads and writes
+5. `bclaw_coordinate`, `bclaw_dispatch`, or `bclaw_loop` for assign, consult, review, reroute, summarize, dispatch, or multi-turn loop flows
+6. `bclaw_read_inbox` when resuming delegated work
+7. `bclaw_write_note`, `bclaw_quick_capture`, or `bclaw_create({ entity: "candidate", ... })` when the result should become runtime or durable shared memory
+
+This keeps session continuity inside Brainclaw instead of pushing the agent back to manual CLI usage.
+
+When a human operator needs the CLI equivalent of `bclaw_write_note`, use `brainclaw runtime-note <text>`.
+
+## Available Tools
+
+All 59 published MCP tools are discoverable via `tools/list`. Each tool carries an `annotations` object with `tier` and `category` metadata so clients can filter or group tools without server-side hiding.
+
+### Tool tiers
+
+Every tool has one of three tiers in its `annotations.tier` field:
+
+- **facade** — High-level entry points for agents that don't need granular access. Start here.
 - **standard** — Day-to-day coordination tools: plans, claims, messaging, sequences, dispatch, review, memory. Returned by default alongside facades.
 - **advanced** — Specialized governance, audit, registry, and power tools.
 
 By default, `tools/list` returns **facade + standard** tools (38 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
-
-Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
-
-See [docs/concepts/mcp-governance.md](../concepts/mcp-governance.md) for
-the stability contract of each tier (what counts as a breaking change,
-deprecation window, schema versioning rules). Changelog entries for
-every version live in [docs/mcp-schema-changelog.md](../mcp-schema-changelog.md).
-
-### Tool categories
-
-Each tool also has an `annotations.category` field: `session`, `context`, `memory`, `coordination`, `loops`, `governance`, or `discovery`.
-
-### Facade tools
-
-| Tool | Category | Purpose |
-|---|---|---|
-| `bclaw_work` | session | Start session + load context + optionally claim a scope in one call (compact payload by default) |
-| `bclaw_context` | context | Unified context read for memory, execution, board, board summary, and deltas |
-| `bclaw_coordinate` | coordination | Assign, consult, review, ideate, reroute, or summarize across agents |
-| `bclaw_dispatch` | coordination | Analyze, execute, or review dispatch work through one intent-based entry point |
-| `bclaw_loop` | loops | Drive multi-turn review, ideation, implementation, research, or debug loops |
-| `bclaw_setup` | session | Agent-driven onboarding wizard |
-
-### Standard tools
-
-| Tool | Category | Purpose |
-|---|---|---|
-| `bclaw_bootstrap` | context | Brownfield bootstrap signals, interview prompts, selective import |
-| `bclaw_release_notes` | context | Agent-first release notes with breaking risk assessment |
-| `bclaw_search` | memory | Full-text search across memory items |
-| `bclaw_assignment_events` | coordination | List correlated runtime events for assignments and runs |
-| `bclaw_switch` | session | Switch active project in a multi-project workspace |
-| `bclaw_read_inbox` | coordination | Read messages from an agent inbox |
-| `bclaw_send_message` | coordination | Send assignments, review requests, RFCs, notifications, or threaded replies |
-| `bclaw_ack_message` | coordination | Acknowledge a processed inbox message |
-| `bclaw_write_note` | memory | Record a runtime note |
-| `bclaw_quick_capture` | memory | Capture text and classify it locally as a decision, trap, or runtime note |
-| `bclaw_claim` | coordination | Claim a work scope (advisory lock, auto-worktree) |
-| `bclaw_release_claim` | coordination | Release a claim, optionally updating linked plan status |
-| `bclaw_session_start` | session | Start a session explicitly (granular workflow) |
-| `bclaw_session_end` | session | End session, optionally auto-reflect notes or handoffs |
-| `bclaw_add_step` | coordination | Add a sub-step to a plan item |
-| `bclaw_complete_step` | coordination | Mark a plan sub-step as done |
+
+Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
+
+See [docs/concepts/mcp-governance.md](../concepts/mcp-governance.md) for
+the stability contract of each tier (what counts as a breaking change,
+deprecation window, schema versioning rules). Changelog entries for
+every version live in [docs/mcp-schema-changelog.md](../mcp-schema-changelog.md).
+
+### Tool categories
+
+Each tool also has an `annotations.category` field: `session`, `context`, `memory`, `coordination`, `loops`, `governance`, or `discovery`.
+
+### Facade tools
+
+| Tool | Category | Purpose |
+|---|---|---|
+| `bclaw_work` | session | Start session + load context + optionally claim a scope in one call (compact payload by default) |
+| `bclaw_context` | context | Unified context read for memory, execution, board, board summary, and deltas |
+| `bclaw_coordinate` | coordination | Assign, consult, review, ideate, reroute, or summarize across agents |
+| `bclaw_dispatch` | coordination | Analyze, execute, or review dispatch work through one intent-based entry point |
+| `bclaw_loop` | loops | Drive multi-turn review, ideation, implementation, research, or debug loops |
+| `bclaw_setup` | session | Agent-driven onboarding wizard |
+
+### Standard tools
+
+| Tool | Category | Purpose |
+|---|---|---|
+| `bclaw_bootstrap` | context | Brownfield bootstrap signals, interview prompts, selective import |
+| `bclaw_release_notes` | context | Agent-first release notes with breaking risk assessment |
+| `bclaw_search` | memory | Full-text search across memory items |
+| `bclaw_assignment_events` | coordination | List correlated runtime events for assignments and runs |
+| `bclaw_switch` | session | Switch active project in a multi-project workspace |
+| `bclaw_read_inbox` | coordination | Read messages from an agent inbox |
+| `bclaw_send_message` | coordination | Send assignments, review requests, RFCs, notifications, or threaded replies |
+| `bclaw_ack_message` | coordination | Acknowledge a processed inbox message |
+| `bclaw_write_note` | memory | Record a runtime note |
+| `bclaw_quick_capture` | memory | Capture text and classify it locally as a decision, trap, or runtime note |
+| `bclaw_claim` | coordination | Claim a work scope (advisory lock, auto-worktree) |
+| `bclaw_release_claim` | coordination | Release a claim, optionally updating linked plan status |
+| `bclaw_session_start` | session | Start a session explicitly (granular workflow) |
+| `bclaw_session_end` | session | End session, optionally auto-reflect notes or handoffs |
+| `bclaw_add_step` | coordination | Add a sub-step to a plan item |
+| `bclaw_complete_step` | coordination | Mark a plan sub-step as done |
 | `bclaw_update_step` | coordination | Update a plan sub-step's status, text, or assignee |
 | `bclaw_delete_step` | coordination | Remove a sub-step from a plan |
 | `bclaw_list_sequences` | coordination | Coordination sequence listing |
@@ -97,65 +97,65 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_update_sequence` | coordination | Update a sequence's status, metadata, or items |
 | `bclaw_delete_sequence` | coordination | Delete a sequence by ID |
 | `bclaw_correct_handoff` | coordination | Write an immutable correction handoff that supersedes an earlier one |
-| `bclaw_assignment_update` | coordination | Report assignment lifecycle status |
-| `bclaw_assignment_action` | coordination | Resolve or reject a pending ActionRequired item |
-| `bclaw_harvest_candidates` | coordination | Harvest sandboxed worktree candidate files into the main project store |
-| `bclaw_find` | memory | List canonical entities with filters |
-| `bclaw_get` | memory | Fetch a canonical entity by id or short label |
-| `bclaw_create` | memory | Create a canonical entity |
-| `bclaw_update` | memory | Partially update mutable fields on a canonical entity |
-| `bclaw_remove` | memory | Archive or purge a canonical entity |
-| `bclaw_transition` | memory | Move an entity through its validated state machine |
-
-### Advanced tools
-
-| Tool | Category | Purpose |
-|---|---|---|
-| `bclaw_audit` | governance | Audit log or governance posture report |
-| `bclaw_check_policy` | governance | Pre-execution policy check for a scope |
-| `bclaw_check_security` | governance | Supply chain security scores via Socket.dev |
-| `bclaw_conflict_check` | governance | Check for overlapping claims between agents |
-| `bclaw_doctor` | governance | Health checks on the memory store |
-| `bclaw_history` | governance | Full mutation history of a memory item |
-| `bclaw_estimation_report` | governance | Estimation accuracy report for completed plans |
-| `bclaw_list_agents` | discovery | Registered agent inventory with reputation |
-| `bclaw_list_instructions` | discovery | Raw or resolved instruction listing |
-| `bclaw_get_capabilities` | discovery | List registered project capabilities |
-| `bclaw_list_tools` | discovery | List registered project tools |
-| `bclaw_search_tools` | discovery | Search tools by name or description |
-| `bclaw_get_discovery` | discovery | Scan workspace for MCP configs, skills, hooks |
-| `bclaw_who` | discovery | List active agent sessions on workspace |
-| `bclaw_add_capability` | discovery | Register a project capability |
-| `bclaw_add_tool` | discovery | Register a project tool |
+| `bclaw_assignment_update` | coordination | Report assignment lifecycle status |
+| `bclaw_assignment_action` | coordination | Resolve or reject a pending ActionRequired item |
+| `bclaw_harvest_candidates` | coordination | Harvest sandboxed worktree candidate files into the main project store |
+| `bclaw_find` | memory | List canonical entities with filters |
+| `bclaw_get` | memory | Fetch a canonical entity by id or short label |
+| `bclaw_create` | memory | Create a canonical entity |
+| `bclaw_update` | memory | Partially update mutable fields on a canonical entity |
+| `bclaw_remove` | memory | Archive or purge a canonical entity |
+| `bclaw_transition` | memory | Move an entity through its validated state machine |
+
+### Advanced tools
+
+| Tool | Category | Purpose |
+|---|---|---|
+| `bclaw_audit` | governance | Audit log or governance posture report |
+| `bclaw_check_policy` | governance | Pre-execution policy check for a scope |
+| `bclaw_check_security` | governance | Supply chain security scores via Socket.dev |
+| `bclaw_conflict_check` | governance | Check for overlapping claims between agents |
+| `bclaw_doctor` | governance | Health checks on the memory store |
+| `bclaw_history` | governance | Full mutation history of a memory item |
+| `bclaw_estimation_report` | governance | Estimation accuracy report for completed plans |
+| `bclaw_list_agents` | discovery | Registered agent inventory with reputation |
+| `bclaw_list_instructions` | discovery | Raw or resolved instruction listing |
+| `bclaw_get_capabilities` | discovery | List registered project capabilities |
+| `bclaw_list_tools` | discovery | List registered project tools |
+| `bclaw_search_tools` | discovery | Search tools by name or description |
+| `bclaw_get_discovery` | discovery | Scan workspace for MCP configs, skills, hooks |
+| `bclaw_who` | discovery | List active agent sessions on workspace |
+| `bclaw_add_capability` | discovery | Register a project capability |
+| `bclaw_add_tool` | discovery | Register a project tool |
 | `bclaw_get_thread` | coordination | Get all messages in a thread across inboxes |
 | `bclaw_delete_plan` | coordination | Delete a plan item by ID |
 | `bclaw_delete_memory` | memory | Delete a memory item by ID |
-| `bclaw_update_memory` | memory | Update a memory item's text or metadata |
-| `bclaw_compact` | memory | LLM-driven semantic memory compaction (two-phase) |
-
-### Canonical grammar (standard tier, v1.0+)
-
-Phase 3 shipped a unified grammar that replaces the per-entity tools
-listed above. All canonical verbs are in the default `standard` tier
-as of v1.0. The legacy per-entity tools have been removed from the
-catalog (still callable as a migration escape hatch — see the redirect
-warnings they emit).
-
-See [docs/concepts/mcp-governance.md](../concepts/mcp-governance.md)
-for the stability contract and [docs/mcp-schema-changelog.md](../mcp-schema-changelog.md)
-for the full 1.0.0 changelog.
-
-#### Six CRUD verbs
-
-| Verb | Purpose | Replaces |
-|---|---|---|
-| `bclaw_find(entity, filter?)` | List query (default: hides `legacy` + `auto_reflect<0.6`) | `bclaw_list_plans/candidates/claims/actions/assignments/runs` |
-| `bclaw_get(entity, id)` | Fetch one by id or short_label | `bclaw_read_handoff` |
-| `bclaw_create(entity, data)` | Create with auto-stamped provenance | `bclaw_create_plan/candidate` |
-| `bclaw_update(entity, id, patch)` | Partial merge (updatable fields only) | `bclaw_update_plan`, `bclaw_update_memory` |
-| `bclaw_remove(entity, id, purge?)` | Archive (default) or hard-delete | `bclaw_delete_memory`, `bclaw_delete_plan` |
-| `bclaw_transition(entity, id, to, reason?)` | State machine transition with side-effect tags | `bclaw_accept`, `bclaw_reject`, status-update flows |
-
+| `bclaw_update_memory` | memory | Update a memory item's text or metadata |
+| `bclaw_compact` | memory | LLM-driven semantic memory compaction (two-phase) |
+
+### Canonical grammar (standard tier, v1.0+)
+
+Phase 3 shipped a unified grammar that replaces the per-entity tools
+listed above. All canonical verbs are in the default `standard` tier
+as of v1.0. The legacy per-entity tools have been removed from the
+catalog (still callable as a migration escape hatch — see the redirect
+warnings they emit).
+
+See [docs/concepts/mcp-governance.md](../concepts/mcp-governance.md)
+for the stability contract and [docs/mcp-schema-changelog.md](../mcp-schema-changelog.md)
+for the full 1.0.0 changelog.
+
+#### Six CRUD verbs
+
+| Verb | Purpose | Replaces |
+|---|---|---|
+| `bclaw_find(entity, filter?)` | List query (default: hides `legacy` + `auto_reflect<0.6`) | `bclaw_list_plans/candidates/claims/actions/assignments/runs` |
+| `bclaw_get(entity, id)` | Fetch one by id or short_label | `bclaw_read_handoff` |
+| `bclaw_create(entity, data)` | Create with auto-stamped provenance | `bclaw_create_plan/candidate` |
+| `bclaw_update(entity, id, patch)` | Partial merge (updatable fields only) | `bclaw_update_plan`, `bclaw_update_memory` |
+| `bclaw_remove(entity, id, purge?)` | Archive (default) or hard-delete | `bclaw_delete_memory`, `bclaw_delete_plan` |
+| `bclaw_transition(entity, id, to, reason?)` | State machine transition with side-effect tags | `bclaw_accept`, `bclaw_reject`, status-update flows |
+
 Supported entities: plan, decision, constraint, trap, handoff,
 runtime_note, candidate, sequence, claim, action, assignment, agent_run
 (with assignment lifecycle now writable through `bclaw_transition` and
@@ -199,236 +199,236 @@ For assignments specifically:
 - `bclaw_transition(entity="assignment", id=..., to="cancelled", reason=...)` is the canonical supervisor/admin cancel path.
 - `bclaw_remove(entity="assignment", id=...)` archives by cancelling the assignment.
 - `bclaw_remove(entity="assignment", id=..., purge=true)` hard-deletes the assignment record.
-
-##### `bclaw_find` filter keys
-
-The `filter` object accepts the following keys. **Unknown keys are
-rejected with `validation_error`** (pln#460) — a typo like
-`{staus:'todo'}` fails fast instead of silently returning unfiltered
-results.
-
-| Key | Type | Applies to | Effect |
-|---|---|---|---|
-| `status` | string | all entities with a `status` field | Exact match on the entity's lifecycle status |
-| `tag` | string | entities with `tags[]` | Returns items where `tags` contains the value |
-| `author` | string | entities with an `author` field | Exact match |
-| `plan_id` | string | handoff, candidate, runtime_note, claim, action, assignment, agent_run | Filter to items linked to a given plan |
-| `source` | string (`auto` / `agent` / `human`) | candidate | Provenance source filter |
-| `auto_generated` | boolean | candidate | `true` keeps only auto-generated candidates, `false` excludes them (matches `source === 'auto'` OR legacy `origin` starting with `session-end`) |
-| `limit` | number (default 50) | all | Max items returned (paging) |
-| `offset` | number (default 0) | all | Paging offset |
-| `includeLegacy` | boolean (default false) | all | Include records with `provenance.kind='legacy'` |
-| `minAutoReflectConfidence` | number 0-1 (default 0.6) | all | Threshold below which `auto_reflect` records are hidden |
-
-Notes:
-- `candidate` has an active bucket of `pending` only; accepted / rejected
-  candidates are archived on transition and don't appear in `bclaw_find`.
-- Combining filters intersects them (AND, not OR).
-- Filters that don't apply to a given entity (e.g. `plan_id` on `plan`)
-  are currently no-ops — they don't error, but they don't match either.
-
-#### Cross-project access (pln#359)
-
-The canonical grammar (`bclaw_find` / `bclaw_get` / `bclaw_create` /
-`bclaw_update` / `bclaw_remove` / `bclaw_transition`), the read
-dispatcher `bclaw_context`, and the coordination facade `bclaw_coordinate`
-accept an optional `project` parameter that routes the operation to a
-**linked project** instead of the current one. The CLI exposes the same
-parameter as a global `--project <name>` flag.
-
-Two link kinds are accepted:
-- `cross_project_links` (sibling/peer projects in `config.yaml`, managed
-  via `brainclaw link add/list/remove`).
-- Workspace store-chain children (monorepo-style nested projects).
-
-Arbitrary directory paths are rejected — adoption requires an explicit
-link, which gives the user a single point of control over what an agent
-can reach.
-
-**Read / write on canonical entities (phase 1a):**
-
-```jsonc
-// Read a trap from a sibling project linked as 'brainclaw-site'
-bclaw_get({ entity: 'trap', id: 'trp_795bbfb5', project: 'brainclaw-site' })
-
-// Update a plan in the linked site repo
-bclaw_update({ entity: 'plan', id: 'pln_abc', patch: { priority: 'high' }, project: 'brainclaw-site' })
-
-// Capture context from a child project in a monorepo
-bclaw_context({ kind: 'memory', project: 'web-app' })
-```
-
-Identity (`author` / `agent`) is resolved from the **source** project's
-agent registry — an agent does not need to be registered in the target
-to write into it. Audit log entries land in the **target** project.
-Unknown project arguments throw `validation_error` with a hint listing
-the configured links — no silent fallback.
-
-**Coordinate / dispatch into a linked project (phase 1b-α):**
-
-```jsonc
-// Dispatch the brainclaw-site claude-code agent without leaving brainclaw
-bclaw_coordinate({
-  intent: 'assign',
-  task: 'Refactor the homepage hero variant',
-  scope: 'src/pages/index.astro',
-  targetAgents: ['claude-code'],
-  project: 'brainclaw-site',
-  agent: 'claude-code',  // self-attribution from the source side
-})
-```
-
-Cross-project dispatch is **inbox-only**: the target agent picks up the
-brief async via its own `bclaw_work`. Auto-spawn from the source process
-is force-disabled when `project` is set, because spawn cwd / worktree
-semantics are tied to the target's git repo. A warning surfaces in
-`FacadeResponse.warnings` so the caller knows auto-spawn was downgraded.
-The same logic applies to `intent=consult|review|reroute|ideate`.
-
-**CLI parity (phase 1c):**
-
-```bash
-# Read the linked project's plans without leaving the current dir
-brainclaw --project=brainclaw-site list-plans
-
-# Write a decision into the linked project
-brainclaw --project=brainclaw-site decision "Switch hero variant to v3"
-
-# Scoped variants: --project works on every subcommand. Mutually exclusive
-# with --cwd; use one or the other.
-```
-
-#### Unified intent dispatchers
-
-| Tool | Consolidates | Example |
-|---|---|---|
-| `bclaw_context(kind, since?)` | `bclaw_get_context` / `bclaw_get_execution_context` / `bclaw_get_agent_board` / `bclaw_get_agent_board_summary` + new `kind='delta'` (P6.4) | `bclaw_context({ kind: 'delta', since: 'sess_abc' })` |
-| `bclaw_dispatch(intent, …)` | `bclaw_dispatch_analysis` / `bclaw_dispatch` / `bclaw_dispatch_review` | `bclaw_dispatch({ intent: 'review', openLoop: true })` |
-
-#### Handoff correction (tombstone)
-
-| Tool | Purpose |
-|---|---|
-| `bclaw_correct_handoff(originalId, text?, narrative?, tags?, reason?)` | Write a new handoff that supersedes an earlier, incorrect one. Original becomes immutable with `superseded_by` back at the correction; correction carries `supersedes`. Federation-safe (both records stay on disk). |
-
-Use `bclaw_correct_handoff` instead of `bclaw_update_handoff` — the
-latter was removed from the catalog at v1.0 (direct calls still succeed
-as a migration escape hatch but emit a redirect warning).
-
-#### Example gallery
-
-```jsonc
-// List all recent high-priority plans (legacy provenance hidden by default)
-bclaw_find({ entity: 'plan', filter: { status: 'in_progress', limit: 10 } })
-
-// Include legacy records + lower auto_reflect confidence threshold
-bclaw_find({ entity: 'decision', filter: { includeLegacy: true, minAutoReflectConfidence: 0.3 } })
-
-// Fetch a specific handoff by short_label
-bclaw_get({ entity: 'handoff', id: 'hnd#42' })
-
-// Create a decision (provenance auto-stamped as kind:user)
-bclaw_create({ entity: 'decision', data: { text: 'switch to postgres', author: 'jberdah' } })
-
-// Transition a candidate (validated against transition matrix)
-bclaw_transition({ entity: 'candidate', id: 'cnd_abc', to: 'accepted' })
-
-// Get memory delta since a previous session
-bclaw_context({ kind: 'delta', since: 'sess_07c...' })
-
-// Compact board summary (replaces bclaw_get_agent_board_summary)
-bclaw_context({ kind: 'board_summary' })
-
-// Review dispatch with structured loop
-bclaw_dispatch({ intent: 'review', openLoop: true, reviewMode: 'symmetric' })
-
-// Open a memory-confrontation ideation loop (single-agent: champion drives manually)
-bclaw_coordinate({ intent: 'ideate', task: 'Should we extract the dispatcher into a separate package?' })
-
-// Multi-agent ideation: critic gets a context-filtered, BM25-ranked brief auto-dispatched
-bclaw_coordinate({
-  intent: 'ideate',
-  task: 'Should we adopt approach A or approach B?',
-  targetAgents: ['codex'],
-})
-
-// Correct a handoff instead of mutating it
-bclaw_correct_handoff({ originalId: 'hnd_xyz', reason: 'wrong contract', text: '...' })
-```
-
-For the full ideation_loop design (phases, context_filter, iteration
-block, advance_gate, brief assembly, single vs multi-agent UX), see
-[docs/concepts/ideation-loop.md](../concepts/ideation-loop.md). For
-the underlying loop engine, see
-[docs/concepts/loop-engine.md](../concepts/loop-engine.md).
-
-#### Deprecation status
-
-The v1.0-removed legacy tools named in the changelog emit a
-deprecation warning server-side on each direct call. The warning names
-the canonical replacement. Warnings fired during the 0.8.x window. As
-of v1.0 those tools are removed from every `tools/list` catalog,
-including `{ catalog: "all" }`, but direct calls still succeed as a
-migration escape hatch and keep emitting redirect warnings.
-
-## When To Use MCP Versus Other Surfaces
-
-| Need | Best surface |
-|---|---|
-| Fresh path-scoped context | MCP |
-| Current plans, claims, board state | MCP |
-| Runtime writes with session continuity | MCP |
-| Local behavioral reminders inside the agent UI | native agent files |
-| Human inspection or scripting | CLI |
-| Simple readable fallback | `.brainclaw/project.md` (derived view, may be stale) |
-
-## Starting The Server
-
-```bash
-brainclaw mcp
-```
-
-In practice, most agents pick this up through generated MCP config such as `.mcp.json`, `~/.cursor/mcp.json`, or other agent-specific config files written by `brainclaw setup`, `brainclaw init`, or `brainclaw export`.
-
-By default, installable update checks use the public npm channel `brainclaw@latest`. Projects that need a different channel can override `brainclaw_update_source`, for example with `type: npm` and `dist_tag: prelaunch`, or with `type: local-pack` for local tarball workflows.
-
-## Bootstrap Through MCP
-
-For agent-first onboarding, `bclaw_bootstrap` is the nominal path:
-
-1. call `bclaw_bootstrap` to get the current `import_plan` and adaptive interview questions
-2. collect answers in the agent surface
-3. call `bclaw_bootstrap` again with `interviewAnswers` to preview confirmed `decision`, `constraint`, `instruction`, or `trap` suggestions
-4. call `bclaw_bootstrap` with `apply: true` to create canonical memory
-5. call `bclaw_bootstrap` with `uninstall: true` to revert the last bootstrap-managed import
-
-Interview answers are keyed by question ID and may contain:
-
-- `response_text`
-- `response_items`
-- `response_boolean`
-- optional explicit `suggestions` when the agent wants to confirm exact canonical memory items
-
-## Mutation Safety
-
-The MCP server serializes all mutations through a single-writer queue (`McpTaskRunner`). When an agent calls a write tool (e.g. `bclaw_claim`, `bclaw_write_note`, `bclaw_create({ entity: "plan", ... })`), the request is enqueued and executed one at a time. This guarantees:
-
-- no concurrent writes from the same MCP connection
-- no partial state from interleaved mutations
-- deterministic ordering of operations
-
-A secondary file-based lock (`mutate()`) provides cross-process safety in case CLI commands run alongside MCP. But for agents, MCP is the safe path by design — no extra precautions needed.
-
-## Important Rule
-
-If the agent has MCP available, do not treat the CLI as the primary runtime interface. All agent mutations MUST go through MCP tools.
-
-The CLI remains valuable for:
-
-- setup and initialization
-- bootstrap by a human operator
-- scripting and automation
-- release and packaging
-- debugging and fallback access
-
-But for capable agents, MCP is the first-class path for both reads and writes.
+
+##### `bclaw_find` filter keys
+
+The `filter` object accepts the following keys. **Unknown keys are
+rejected with `validation_error`** (pln#460) — a typo like
+`{staus:'todo'}` fails fast instead of silently returning unfiltered
+results.
+
+| Key | Type | Applies to | Effect |
+|---|---|---|---|
+| `status` | string | all entities with a `status` field | Exact match on the entity's lifecycle status |
+| `tag` | string | entities with `tags[]` | Returns items where `tags` contains the value |
+| `author` | string | entities with an `author` field | Exact match |
+| `plan_id` | string | handoff, candidate, runtime_note, claim, action, assignment, agent_run | Filter to items linked to a given plan |
+| `source` | string (`auto` / `agent` / `human`) | candidate | Provenance source filter |
+| `auto_generated` | boolean | candidate | `true` keeps only auto-generated candidates, `false` excludes them (matches `source === 'auto'` OR legacy `origin` starting with `session-end`) |
+| `limit` | number (default 50) | all | Max items returned (paging) |
+| `offset` | number (default 0) | all | Paging offset |
+| `includeLegacy` | boolean (default false) | all | Include records with `provenance.kind='legacy'` |
+| `minAutoReflectConfidence` | number 0-1 (default 0.6) | all | Threshold below which `auto_reflect` records are hidden |
+
+Notes:
+- `candidate` has an active bucket of `pending` only; accepted / rejected
+  candidates are archived on transition and don't appear in `bclaw_find`.
+- Combining filters intersects them (AND, not OR).
+- Filters that don't apply to a given entity (e.g. `plan_id` on `plan`)
+  are currently no-ops — they don't error, but they don't match either.
+
+#### Cross-project access (pln#359)
+
+The canonical grammar (`bclaw_find` / `bclaw_get` / `bclaw_create` /
+`bclaw_update` / `bclaw_remove` / `bclaw_transition`), the read
+dispatcher `bclaw_context`, and the coordination facade `bclaw_coordinate`
+accept an optional `project` parameter that routes the operation to a
+**linked project** instead of the current one. The CLI exposes the same
+parameter as a global `--project <name>` flag.
+
+Two link kinds are accepted:
+- `cross_project_links` (sibling/peer projects in `config.yaml`, managed
+  via `brainclaw link add/list/remove`).
+- Workspace store-chain children (monorepo-style nested projects).
+
+Arbitrary directory paths are rejected — adoption requires an explicit
+link, which gives the user a single point of control over what an agent
+can reach.
+
+**Read / write on canonical entities (phase 1a):**
+
+```jsonc
+// Read a trap from a sibling project linked as 'brainclaw-site'
+bclaw_get({ entity: 'trap', id: 'trp_795bbfb5', project: 'brainclaw-site' })
+
+// Update a plan in the linked site repo
+bclaw_update({ entity: 'plan', id: 'pln_abc', patch: { priority: 'high' }, project: 'brainclaw-site' })
+
+// Capture context from a child project in a monorepo
+bclaw_context({ kind: 'memory', project: 'web-app' })
+```
+
+Identity (`author` / `agent`) is resolved from the **source** project's
+agent registry — an agent does not need to be registered in the target
+to write into it. Audit log entries land in the **target** project.
+Unknown project arguments throw `validation_error` with a hint listing
+the configured links — no silent fallback.
+
+**Coordinate / dispatch into a linked project (phase 1b-α):**
+
+```jsonc
+// Dispatch the brainclaw-site claude-code agent without leaving brainclaw
+bclaw_coordinate({
+  intent: 'assign',
+  task: 'Refactor the homepage hero variant',
+  scope: 'src/pages/index.astro',
+  targetAgents: ['claude-code'],
+  project: 'brainclaw-site',
+  agent: 'claude-code',  // self-attribution from the source side
+})
+```
+
+Cross-project dispatch is **inbox-only**: the target agent picks up the
+brief async via its own `bclaw_work`. Auto-spawn from the source process
+is force-disabled when `project` is set, because spawn cwd / worktree
+semantics are tied to the target's git repo. A warning surfaces in
+`FacadeResponse.warnings` so the caller knows auto-spawn was downgraded.
+The same logic applies to `intent=consult|review|reroute|ideate`.
+
+**CLI parity (phase 1c):**
+
+```bash
+# Read the linked project's plans without leaving the current dir
+brainclaw --project=brainclaw-site list-plans
+
+# Write a decision into the linked project
+brainclaw --project=brainclaw-site decision "Switch hero variant to v3"
+
+# Scoped variants: --project works on every subcommand. Mutually exclusive
+# with --cwd; use one or the other.
+```
+
+#### Unified intent dispatchers
+
+| Tool | Consolidates | Example |
+|---|---|---|
+| `bclaw_context(kind, since?)` | `bclaw_get_context` / `bclaw_get_execution_context` / `bclaw_get_agent_board` / `bclaw_get_agent_board_summary` + new `kind='delta'` (P6.4) | `bclaw_context({ kind: 'delta', since: 'sess_abc' })` |
+| `bclaw_dispatch(intent, …)` | `bclaw_dispatch_analysis` / `bclaw_dispatch` / `bclaw_dispatch_review` | `bclaw_dispatch({ intent: 'review', openLoop: true })` |
+
+#### Handoff correction (tombstone)
+
+| Tool | Purpose |
+|---|---|
+| `bclaw_correct_handoff(originalId, text?, narrative?, tags?, reason?)` | Write a new handoff that supersedes an earlier, incorrect one. Original becomes immutable with `superseded_by` back at the correction; correction carries `supersedes`. Federation-safe (both records stay on disk). |
+
+Use `bclaw_correct_handoff` instead of `bclaw_update_handoff` — the
+latter was removed from the catalog at v1.0 (direct calls still succeed
+as a migration escape hatch but emit a redirect warning).
+
+#### Example gallery
+
+```jsonc
+// List all recent high-priority plans (legacy provenance hidden by default)
+bclaw_find({ entity: 'plan', filter: { status: 'in_progress', limit: 10 } })
+
+// Include legacy records + lower auto_reflect confidence threshold
+bclaw_find({ entity: 'decision', filter: { includeLegacy: true, minAutoReflectConfidence: 0.3 } })
+
+// Fetch a specific handoff by short_label
+bclaw_get({ entity: 'handoff', id: 'hnd#42' })
+
+// Create a decision (provenance auto-stamped as kind:user)
+bclaw_create({ entity: 'decision', data: { text: 'switch to postgres', author: 'jberdah' } })
+
+// Transition a candidate (validated against transition matrix)
+bclaw_transition({ entity: 'candidate', id: 'cnd_abc', to: 'accepted' })
+
+// Get memory delta since a previous session
+bclaw_context({ kind: 'delta', since: 'sess_07c...' })
+
+// Compact board summary (replaces bclaw_get_agent_board_summary)
+bclaw_context({ kind: 'board_summary' })
+
+// Review dispatch with structured loop
+bclaw_dispatch({ intent: 'review', openLoop: true, reviewMode: 'symmetric' })
+
+// Open a memory-confrontation ideation loop (single-agent: champion drives manually)
+bclaw_coordinate({ intent: 'ideate', task: 'Should we extract the dispatcher into a separate package?' })
+
+// Multi-agent ideation: critic gets a context-filtered, BM25-ranked brief auto-dispatched
+bclaw_coordinate({
+  intent: 'ideate',
+  task: 'Should we adopt approach A or approach B?',
+  targetAgents: ['codex'],
+})
+
+// Correct a handoff instead of mutating it
+bclaw_correct_handoff({ originalId: 'hnd_xyz', reason: 'wrong contract', text: '...' })
+```
+
+For the full ideation_loop design (phases, context_filter, iteration
+block, advance_gate, brief assembly, single vs multi-agent UX), see
+[docs/concepts/ideation-loop.md](../concepts/ideation-loop.md). For
+the underlying loop engine, see
+[docs/concepts/loop-engine.md](../concepts/loop-engine.md).
+
+#### Deprecation status
+
+The v1.0-removed legacy tools named in the changelog emit a
+deprecation warning server-side on each direct call. The warning names
+the canonical replacement. Warnings fired during the 0.8.x window. As
+of v1.0 those tools are removed from every `tools/list` catalog,
+including `{ catalog: "all" }`, but direct calls still succeed as a
+migration escape hatch and keep emitting redirect warnings.
+
+## When To Use MCP Versus Other Surfaces
+
+| Need | Best surface |
+|---|---|
+| Fresh path-scoped context | MCP |
+| Current plans, claims, board state | MCP |
+| Runtime writes with session continuity | MCP |
+| Local behavioral reminders inside the agent UI | native agent files |
+| Human inspection or scripting | CLI |
+| Simple readable fallback | `.brainclaw/project.md` (derived view, may be stale) |
+
+## Starting The Server
+
+```bash
+brainclaw mcp
+```
+
+In practice, most agents pick this up through generated MCP config such as `.mcp.json`, `~/.cursor/mcp.json`, or other agent-specific config files written by `brainclaw setup`, `brainclaw init`, or `brainclaw export`.
+
+By default, installable update checks use the public npm channel `brainclaw@latest`. Projects that need a different channel can override `brainclaw_update_source`, for example with `type: npm` and `dist_tag: prelaunch`, or with `type: local-pack` for local tarball workflows.
+
+## Bootstrap Through MCP
+
+For agent-first onboarding, `bclaw_bootstrap` is the nominal path:
+
+1. call `bclaw_bootstrap` to get the current `import_plan` and adaptive interview questions
+2. collect answers in the agent surface
+3. call `bclaw_bootstrap` again with `interviewAnswers` to preview confirmed `decision`, `constraint`, `instruction`, or `trap` suggestions
+4. call `bclaw_bootstrap` with `apply: true` to create canonical memory
+5. call `bclaw_bootstrap` with `uninstall: true` to revert the last bootstrap-managed import
+
+Interview answers are keyed by question ID and may contain:
+
+- `response_text`
+- `response_items`
+- `response_boolean`
+- optional explicit `suggestions` when the agent wants to confirm exact canonical memory items
+
+## Mutation Safety
+
+The MCP server serializes all mutations through a single-writer queue (`McpTaskRunner`). When an agent calls a write tool (e.g. `bclaw_claim`, `bclaw_write_note`, `bclaw_create({ entity: "plan", ... })`), the request is enqueued and executed one at a time. This guarantees:
+
+- no concurrent writes from the same MCP connection
+- no partial state from interleaved mutations
+- deterministic ordering of operations
+
+A secondary file-based lock (`mutate()`) provides cross-process safety in case CLI commands run alongside MCP. But for agents, MCP is the safe path by design — no extra precautions needed.
+
+## Important Rule
+
+If the agent has MCP available, do not treat the CLI as the primary runtime interface. All agent mutations MUST go through MCP tools.
+
+The CLI remains valuable for:
+
+- setup and initialization
+- bootstrap by a human operator
+- scripting and automation
+- release and packaging
+- debugging and fallback access
+
+But for capable agents, MCP is the first-class path for both reads and writes.