brainclaw 0.28.0 → 1.5.3

package/docs/integrations/mcp.md

@@ -16,38 +16,321 @@ MCP matters because Brainclaw's value is mostly in dynamic state:
 
 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_get_execution_context` 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`.
+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_session_start` to open work and get the current board/context
-2. `bclaw_get_execution_context` early in the session when the agent needs local tooling signals or package update visibility
-3. `bclaw_get_context` when the target path or task changes
-4. `bclaw_list_plans` and `bclaw_list_claims` to inspect active work
-5. `bclaw_claim` before editing
-6. `bclaw_write_note` for runtime observations
-7. `bclaw_session_end` to close cleanly and hand work off
+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, dispatch, review, memory. Returned by default alongside facades.
+- **advanced** — Specialized governance, audit, registry, sequences, and power tools.
+
+By default, `tools/list` returns **facade + standard** tools (34 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 |
+| `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_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_list_sequences` | coordination | Coordination sequence listing |
+| `bclaw_create_sequence` | coordination | Create a coordination sequence |
+| `bclaw_update_sequence` | coordination | Update a sequence's status, metadata, or items |
+| `bclaw_get_thread` | coordination | Get all messages in a thread across inboxes |
+| `bclaw_delete_plan` | coordination | Delete a plan item by ID |
+| `bclaw_delete_sequence` | coordination | Delete a sequence 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 |
+
+Supported entities: plan, decision, constraint, trap, handoff,
+runtime_note, candidate, claim, action, assignment, agent_run
+(read-only for the latter four). Declarative transition matrix +
+updatable field list live in [src/core/entity-registry.ts](../../src/core/entity-registry.ts).
+
+##### `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_get_context` | Ranked prompt-ready context, supports `digest: true` |
-| `bclaw_bootstrap` | Derive brownfield bootstrap signals, return adaptive interview prompts, accept structured interview answers, and preview/apply a selective import proposal |
-| `bclaw_get_execution_context` | Inspect local execution context, installable update status, and agent tooling |
-| `bclaw_write_note` | Record a runtime note, supports `autoReflect: true` |
-| `bclaw_read_handoff` | Read active handoffs |
-| `bclaw_get_agent_board` | Coordination snapshot |
-| `bclaw_list_plans` | Structured plan listing with filters, pagination (`limit`/`offset`), `compact` mode, and `id` lookup |
-| `bclaw_list_claims` | Structured claim listing with CLI-equivalent filters |
-| `bclaw_list_agents` | Registered agent inventory, optionally with bounded reputation |
-| `bclaw_list_instructions` | Raw or resolved instruction listing |
-| `bclaw_list_candidates` | Pending or archived review queue listing |
-| `bclaw_search` | Full-text search across memory |
+| `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
 
@@ -89,7 +372,7 @@ Interview answers are keyed by question ID and may contain:
 
 ## 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_plan`), the request is enqueued and executed one at a time. This guarantees:
+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

package/docs/integrations/mistral-vibe.md

@@ -0,0 +1,122 @@
+# Mistral Vibe Integration
+
+brainclaw integrates with **Mistral Vibe** through MCP tools, the universal `.agents/skills/brainclaw/SKILL.md`, and a `.live.md` companion file. Mistral Vibe is a Tier B agent — MCP + skills + CLI spawn, but no hooks (BeforePrompt is a feature request, not yet implemented) and no native rules file equivalent to `CLAUDE.md`.
+
+Mistral Vibe is open-source (Apache 2.0), Paris-based, and supports on-premise / EU-hosted deployment — making it a strategic option for teams that need GDPR compliance and freedom from US CLOUD Act exposure.
+
+## Auto-setup
+
+`brainclaw init` detects Mistral Vibe (via `~/.vibe/` directory or `VIBE_HOME` env var) and writes:
+
+- `.vibe/config.toml` — TOML MCP config registering brainclaw as a stdio server
+- `AGENTS.md` — shared instruction file (also read by Codex and OpenCode)
+- `.agents/skills/brainclaw/SKILL.md` — universal skill auto-discovered by Vibe
+- `.vibe/live.md` (opt-in via `--include-live`) — refreshed on session-end / handoff with current plans, claims, traps, candidates, handoffs
+
+Manual regeneration:
+
+```bash
+brainclaw export --format agents-md --write
+brainclaw export --format agents-md --write --include-live   # add the live companion
+```
+
+## MCP configuration
+
+Mistral Vibe reads MCP servers from `.vibe/config.toml` (project, prioritaire) or `~/.vibe/config.toml` (user fallback). Format is **TOML** — Mistral Vibe is the only Tier B agent in brainclaw's catalog using TOML rather than JSON/YAML.
+
+```toml
+[[mcp_servers]]
+name = "brainclaw"
+transport = "stdio"
+command = "npx"
+args = ["-y", "brainclaw@latest", "mcp"]
+```
+
+Other transports supported by Mistral Vibe : `http`, `sse` (Streamable-HTTP). brainclaw uses `stdio` by default, the simplest and most secure local path.
+
+The brainclaw writer is **idempotent** — if `.vibe/config.toml` already declares a `[[mcp_servers]]` block whose `name = "brainclaw"`, the writer leaves it alone (preserves any user customization of `command`, `args`, etc.). Other `[[mcp_servers]]` entries (e.g., Serena, custom MCP servers) are also preserved on regeneration.
+
+## Permissions
+
+Mistral Vibe supports per-tool permission control in `.vibe/config.toml`:
+
+```toml
+[tools.bash]
+permission = "always"     # auto-approve
+
+[mcp_servers.brainclaw]
+enabled_tools = ["bclaw_work", "bclaw_context", "bclaw_find", "bclaw_get"]
+```
+
+Patterns supported: exact names, glob (`bash*`), regex (`re:^bclaw_.*$`). brainclaw does not yet emit a curated `enabled_tools` list automatically — configure manually for headless workflows.
+
+For interactive sessions, toggle global auto-approve with `Shift+Tab` or pass `--auto-approve` on the CLI.
+
+## Instruction files
+
+- **`AGENTS.md`** — shared instruction file (read by Mistral Vibe, Codex, OpenCode). Static brainclaw protocol + active constraints. Generated by `brainclaw export --format agents-md --write`.
+- **`.agents/skills/brainclaw/SKILL.md`** — universal skill, auto-discovered by Mistral Vibe alongside `.vibe/skills/`. Provides slash-command access (`/brainclaw`).
+- **`.vibe/live.md`** (opt-in) — live companion regenerated on session-end and handoff with plans, claims, traps, candidates, handoffs. Critical for Tier B agents like Vibe that lack pre-prompt hooks: this is the parity backstop so the agent sees current coordination state without an MCP round-trip on every prompt.
+
+Mistral Vibe **does not have a native rules file** equivalent to `CLAUDE.md` — there is no documented mechanism to inject project-wide instructions outside `AGENTS.md` and skills. brainclaw works within that constraint.
+
+## Headless invocation
+
+Mistral Vibe is CLI-spawnable for parallel lanes and dispatched workflows. The canonical invoke template is:
+
+```bash
+vibe --prompt "{prompt}" --auto-approve --max-turns 5
+```
+
+- `--prompt` runs the task non-interactively from a single string.
+- `--auto-approve` disables interactive approval on file edits and bash exec.
+- `--max-turns N` caps the agent loop. brainclaw uses 5 by default; raise for larger tasks.
+- `--max-price <USD>` (optional) caps cost before interruption.
+
+For long prompts, `stdin_pipe` is supported (`echo "prompt" | vibe`) and is the fallback when `inline_arg` exceeds 8000 chars.
+
+Output is text-formatted on stdout. brainclaw parses completion via the brief-ack file (same handshake pattern as Codex and other CLI-spawned workers).
+
+## Capability profile
+
+| Field | Value |
+|-------|-------|
+| Tier | B |
+| MCP | yes (TOML config, project + user) |
+| Hooks | no (BeforePrompt is feature request #531, not implemented) |
+| Auto-approve | per-call (`--auto-approve` flag, or `Shift+Tab` interactive toggle) |
+| Skills | yes (`.vibe/skills/` + universal `.agents/skills/`) |
+| CLI spawnable | yes |
+| Max concurrent tasks | 2 (conservative, see caveats) |
+| Workflow model | task-based (one-shot `--prompt` exec) |
+| MCP config scope | both (project + user fallback) |
+| Prompt delivery | `inline_arg` (preferred, max 8000 chars), `stdin_pipe` (fallback) |
+| Native rules file | no (relies on `AGENTS.md` + skill universel) |
+| Live companion | `.vibe/live.md` (opt-in via `--include-live`) |
+
+## Sovereignty & compliance
+
+Mistral Vibe is a strategic option when EU/FR data sovereignty matters:
+
+- **Mistral AI is Paris-based** — fully subject to GDPR, **not** subject to the US CLOUD Act.
+- **Vibe CLI is open-source** (Apache 2.0) on [github.com/mistralai/mistral-vibe](https://github.com/mistralai/mistral-vibe) — auditable end-to-end.
+- **Open-weight models** (Mistral Medium 3.5, Codestral, Devstral) deployable on-premise via Hugging Face — full data control, no third-party API calls when self-hosted.
+- **EU-hosted Mistral cloud** available with a Data Processing Agreement (DPA).
+
+For teams that have ruled out US-hosted agents on compliance grounds (regulated sectors, public sector, defense), this is often the only viable Tier B option.
+
+## Caveats
+
+- **Windows + Git Bash unsupported.** Mistral Vibe spawns its child shells via PowerShell or `cmd.exe` on Windows and cannot reuse environment variables sourced inside Git Bash. Tracked upstream as [issue #135](https://github.com/mistralai/mistral-vibe/issues/135). Workaround: run `vibe` from PowerShell or WSL.
+- **No pre-prompt hooks.** Vibe has an experimental post-agent-turn hook system (v2.9.0+) but no `BeforePrompt` / `UserPromptSubmit` equivalent. Live coordination state must reach the agent via MCP calls or the `.vibe/live.md` companion regenerated on session-end / handoff — there is no real-time push mechanism.
+- **No `CLAUDE.md` equivalent.** Mistral Vibe does not auto-load a free-form rules file at session start; integration relies on `AGENTS.md` + skills.
+- **CLI freezes documented** on the current version (early v2.x). For production parallel dispatch, `max_concurrent_tasks` is capped at 2 conservatively.
+- **Rate-limit messages are vague** (upstream issue) — when running heavy parallel workloads, expect generic `rate limit exceeded` errors without specific guidance.
+- **Skill discovery overlap.** Vibe auto-discovers both `.vibe/skills/` and `.agents/skills/`. brainclaw writes only to `.agents/skills/brainclaw/SKILL.md` to avoid duplicate definitions; if a project already had a `.vibe/skills/brainclaw/` folder, remove it manually after this integration to avoid two competing definitions.
+
+## See also
+
+- [docs/integrations/overview.md](overview.md) — full agent matrix and integration tier model
+- [docs/integrations/mcp.md](mcp.md) — recommended dynamic runtime path
+- [Mistral Vibe official documentation](https://docs.mistral.ai/mistral-vibe/introduction)
+- [Mistral Vibe GitHub repository](https://github.com/mistralai/mistral-vibe) (Apache 2.0)

package/docs/integrations/opencode.md

@@ -0,0 +1,84 @@
+# OpenCode Integration
+
+brainclaw integrates with OpenCode through MCP tools and AGENTS.md, providing shared memory, plans, claims, and multi-agent coordination.
+
+## Auto-setup
+
+`brainclaw init` detects OpenCode and writes `AGENTS.md` automatically. Or manually:
+
+```bash
+brainclaw export --format agents-md --write
+```
+
+## MCP configuration
+
+OpenCode reads MCP servers from `opencode.json` at the project root, or `~/.config/opencode/opencode.json` globally:
+
+```json
+{
+  "mcp": {
+    "brainclaw": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
+    }
+  }
+}
+```
+
+## Permissions
+
+OpenCode uses a per-tool permission map with `allow`, `ask`, or `deny` values:
+
+```json
+{
+  "mcp": {
+    "brainclaw": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"],
+      "permissions": {
+        "bclaw_context": "allow",
+        "bclaw_work": "allow",
+        "bclaw_find": "allow",
+        "bclaw_get": "allow"
+      }
+    }
+  }
+}
+```
+
+brainclaw does not yet emit OpenCode permissions automatically.
+
+## Instruction files
+
+OpenCode reads `AGENTS.md` at the project root — the same file used by Codex. brainclaw writes this during `init` or `export`.
+
+## SKILL.md discovery
+
+OpenCode auto-discovers skills from `.opencode/skills/`, `.claude/skills/`, and `.agents/skills/`. A single `.agents/skills/brainclaw/SKILL.md` is picked up automatically.
+
+## Headless invocation
+
+```bash
+opencode run /path/to/project
+```
+
+OpenCode also supports `serve` (HTTP API) and `web` (browser UI) modes.
+
+## Invoke template
+
+```bash
+opencode /path/to/project
+```
+
+## Subagents
+
+OpenCode supports native subagents via `mode: subagent` and `@mention` syntax, with per-agent permissions. These are separate from brainclaw's coordination — brainclaw operates above them.
+
+## Caveats
+
+- **No hooks**: OpenCode has a plugin system (JS/TS) but it is not compatible with Claude Code hook format. No pre-prompt injection.
+- **No auto-approve writer**: brainclaw does not emit OpenCode `permissions` blocks yet — configure manually for headless.
+- **`external_directory` deny**: OpenCode may deny file access outside the project root by default. Ensure brainclaw's store path (`.brainclaw/`) is within the project.
+- **Windows**: Requires Node.js on PATH. Works on Windows, Linux, and macOS.

package/docs/integrations/overview.md

@@ -45,15 +45,15 @@ The agent gets dynamic context injected at every prompt. The instruction file ca
 
 ### Standard integration (MCP, no hooks)
 
-The agent can call brainclaw tools but doesn't get automatic context injection. The instruction file is more directive — it tells the agent it MUST call specific tools before working, and includes the most critical traps statically.
+The agent can call brainclaw tools but doesn't get automatic context injection. The instruction file is more directive — it tells the agent it MUST call specific tools before working, and includes the most critical traps statically. For agents without hooks, an opt-in `.live.md` companion (regenerated on session-end and handoff) carries plans, claims, traps, candidates, and handoffs as a parity backstop.
 
-**Today:** Cursor, Windsurf, Cline, Roo, Continue, OpenCode, Codex, Antigravity/Gemini CLI
+**Today:** Cursor, Windsurf, Cline, Roo, Continue, Kilocode, OpenCode, Codex, GitHub Copilot, Antigravity/Gemini CLI, Mistral Vibe
 
 ### Limited integration (no MCP)
 
-The agent cannot call brainclaw tools at all. The instruction file becomes the only source of project context, so it includes everything: constraints, traps, active plans, recent decisions.
+The agent cannot call brainclaw tools at all. The instruction file or SKILL.md becomes the only source of project context, so it includes everything: constraints, traps, active plans, recent decisions.
 
-**Today:** GitHub Copilot (uses skills as a partial workaround)
+**Today:** Autonomous agents only (OpenClaw, NanoClaw, NemoClaw, PicoClaw, ZeroClaw — wired via `skills/<agent>/SKILL.md`).
 
 ## Agent integration matrix
 
@@ -65,10 +65,12 @@ The agent cannot call brainclaw tools at all. The instruction file becomes the o
 | **Cline** | ✔ project | .clinerules/ | — | ✔ autoApprove | — |
 | **Roo** | ✔ project | .roo/rules/ | — | ✔ alwaysAllow | — |
 | **Continue** | ✔ both | .continue/rules/ | — | — | — |
+| **Kilocode** | ✔ both | .kilo/rules/ + AGENTS.md | — | ✔ alwaysAllow | — |
 | **OpenCode** | ✔ project | AGENTS.md | — | — | — |
 | **Codex** | ✔ global | AGENTS.md | — | — | — |
 | **Gemini CLI** | ✔ global | GEMINI.md | — | — | — |
-| **Copilot** | — | .github/copilot-instructions.md | — | — | ✔ brainclaw-context |
+| **GitHub Copilot** | ✔ global + project | .github/copilot-instructions.md | — | manual (per-call) | ✔ brainclaw-context |
+| **Mistral Vibe** | ✔ project + user (TOML) | AGENTS.md | — | `--auto-approve` flag | ✔ universal skill |
 | **OpenClaw** | — | — | — | — | ✔ brainclaw skill |
 
 **Legend:** ✔ = fully supported, ◐ = partial (static trigger, not dynamic injection), — = not available
@@ -85,11 +87,17 @@ That's why brainclaw activates **all available surfaces** by default during setu
 
 The developer can dial back individual surfaces if needed, but the default is full integration because that's what works.
 
-## Sequential collaboration, not parallel editing
+## Parallel and sequential collaboration
 
-brainclaw's store mutations are serialized (MCP single-writer queue + file-based lock), so memory writes are safe even under contention. However, running multiple agents in parallel on the same checkout can still cause Git conflicts and confusing file-level state.
+brainclaw's store mutations are serialized (MCP single-writer queue + file-based lock), so memory writes are safe even under contention.
 
-For now, brainclaw works best when one agent works at a time in a given checkout. The next agent can pick up where the previous one stopped, using shared plans, claims, handoffs, and memory. Git worktree isolation per agent is planned but not yet available.
+For **parallel work**, dispatch a sequence with `bclaw_dispatch(intent="execute")` — each lane gets its own auto-worktree under `~/.brainclaw/worktrees/<project-hash>/`, and the coordinator integrates with an octopus merge. For **review-fix loops**, `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions. These are the supported parallel paths today.
+
+For **sequential work** in the same project, let one agent claim at a time and rely on handoffs to keep continuity across sessions.
+
+What is **still risky**: running two agents in the *same* working tree without per-claim worktrees. That path can still produce Git conflicts and confusing file-level state — use the dispatch path (auto-worktree per claim) instead.
+
+See the README's "Current state" section for the full list of what works today and the residual sharp edges.
 
 ## Next reads
 
@@ -99,4 +107,11 @@ For now, brainclaw works best when one agent works at a time in a given checkout
 - [cursor.md](cursor.md)
 - [codex.md](codex.md)
 - [copilot.md](copilot.md)
+- [continue.md](continue.md)
+- [roo.md](roo.md)
+- [windsurf.md](windsurf.md)
+- [cline.md](cline.md)
+- [kilocode.md](kilocode.md)
+- [mistral-vibe.md](mistral-vibe.md)
+- [opencode.md](opencode.md)
 - [openclaw.md](openclaw.md)