brainclaw 1.8.0 → 1.9.1

package/docs/integrations/mistral-vibe.md

@@ -1,122 +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)
+# 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/openclaw.md

@@ -1,98 +1,99 @@
-# OpenClaw Integration
-
-## Why brainclaw for OpenClaw users
-
-OpenClaw's built-in memory (`MEMORY.md` + daily logs) is great for personal notes and preferences, but it doesn't distinguish between different types of project knowledge. After many conversations, constraints get buried, decisions lose their reasoning, and the agent drifts from its original instructions.
-
-brainclaw adds a structured memory layer on top:
-
-| Problem | OpenClaw alone | With brainclaw |
-|---|---|---|
-| "Don't deploy on Friday" gets forgotten | Buried in MEMORY.md after 50 conversations | Stored as a constraint, always visible |
-| Agent repeats a known mistake | No trap system | Traps scored by relevance to current scope |
-| Two agents work on same file | No coordination | Claims prevent collisions |
-| Decision reasoning is lost | Mixed with daily notes | Preserved as typed decisions, searchable |
-
-## How it works
-
-brainclaw integrates as an OpenClaw **skill**. The skill instructs the agent to:
-
-1. Load brainclaw project context before any coding work
-2. Record constraints, traps, and decisions in brainclaw (not MEMORY.md)
-3. Keep MEMORY.md for personal preferences and daily observations
-4. Coordinate with other agents through plans and claims
-
-## Installation
-
-### Prerequisites
-
-```bash
-npm install -g brainclaw
-```
-
-### Install the skill
-
-```bash
-brainclaw enable-agent openclaw
-```
-
-This copies the brainclaw skill to `~/.openclaw/workspace/skills/brainclaw/`.
-
-Or manually:
-
-```bash
-mkdir -p ~/.openclaw/workspace/skills/brainclaw
-cp "$(npm root -g)/brainclaw/skills/openclaw/SKILL.md" ~/.openclaw/workspace/skills/brainclaw/
-```
-
-### Initialize a project
-
-```bash
-cd /path/to/your/project
-brainclaw init
-```
-
-### Restart OpenClaw
-
-```
-/new
-```
-
-or restart the Gateway. The brainclaw skill will be loaded automatically.
-
-## What the agent sees
-
-After installation, your OpenClaw agent will:
-
-- Run `brainclaw context` before project work to load constraints, traps, and plans
-- Record rules you give it as brainclaw constraints (not just MEMORY.md entries)
-- Record problems it discovers as traps (with severity)
-- Log architectural decisions with their reasoning
-- Clean up with `brainclaw session-end` when finished
-
-## Memory split
-
-The brainclaw skill establishes a clear split:
-
-- **MEMORY.md** — your preferences, habits, personal context (OpenClaw manages this)
-- **brainclaw** — project constraints, traps, decisions, plans (shared with all agents)
-
-This means if you switch from OpenClaw to Claude Code or Codex for coding, the project memory follows — it's in `.brainclaw/`, not in `~/.openclaw/`.
-
-## Multi-agent coordination
-
-If you use both OpenClaw and a coding agent (Claude Code, Cursor, etc.) on the same project, brainclaw coordinates between them:
-
-- OpenClaw records a constraint → Claude Code sees it at next session
-- Claude Code claims a file scope → OpenClaw knows not to edit there
-- Either agent creates a plan → both see it in their context
-
-## Profile
-
-When loading context for OpenClaw, use the `openclaw` profile for optimized scoring:
-
-```bash
-brainclaw context --profile openclaw
-```
-
-This boosts constraints, handoffs, and runtime notes — the items most relevant to an agent that might not be editing code directly but needs to understand the project state.
+# OpenClaw Integration
+
+## Why brainclaw for OpenClaw users
+
+OpenClaw's built-in memory (`MEMORY.md` + daily logs) is great for personal notes and preferences, but it doesn't distinguish between different types of project knowledge. After many conversations, constraints get buried, decisions lose their reasoning, and the agent drifts from its original instructions.
+
+brainclaw adds a structured memory layer on top:
+
+| Problem | OpenClaw alone | With brainclaw |
+|---|---|---|
+| "Don't deploy on Friday" gets forgotten | Buried in MEMORY.md after 50 conversations | Stored as a constraint, always visible |
+| Agent repeats a known mistake | No trap system | Traps scored by relevance to current scope |
+| Two agents work on same file | No coordination | Claims prevent collisions |
+| Decision reasoning is lost | Mixed with daily notes | Preserved as typed decisions, searchable |
+
+## How it works
+
+brainclaw integrates as an OpenClaw **skill**. The skill instructs the agent to:
+
+1. Load brainclaw project context before any coding work
+2. Record constraints, traps, and decisions in brainclaw (not MEMORY.md)
+3. Keep MEMORY.md for personal preferences and daily observations
+4. Coordinate with other agents through plans and claims
+
+## Installation
+
+### Prerequisites
+
+```bash
+npm install -g brainclaw
+```
+
+### Install the skill
+
+```bash
+brainclaw enable-agent openclaw
+```
+
+This copies the brainclaw skill to `~/.openclaw/workspace/skills/brainclaw/`.
+
+Or manually:
+
+```bash
+brainclaw export --format openclaw --output /tmp/brainclaw-openclaw-skill.md
+mkdir -p ~/.openclaw/workspace/skills/brainclaw
+cp /tmp/brainclaw-openclaw-skill.md ~/.openclaw/workspace/skills/brainclaw/SKILL.md
+```
+
+### Initialize a project
+
+```bash
+cd /path/to/your/project
+brainclaw init
+```
+
+### Restart OpenClaw
+
+```
+/new
+```
+
+or restart the Gateway. The brainclaw skill will be loaded automatically.
+
+## What the agent sees
+
+After installation, your OpenClaw agent will:
+
+- Run `brainclaw context` before project work to load constraints, traps, and plans
+- Record rules you give it as brainclaw constraints (not just MEMORY.md entries)
+- Record problems it discovers as traps (with severity)
+- Log architectural decisions with their reasoning
+- Clean up with `brainclaw session-end` when finished
+
+## Memory split
+
+The brainclaw skill establishes a clear split:
+
+- **MEMORY.md** — your preferences, habits, personal context (OpenClaw manages this)
+- **brainclaw** — project constraints, traps, decisions, plans (shared with all agents)
+
+This means if you switch from OpenClaw to Claude Code or Codex for coding, the project memory follows — it's in `.brainclaw/`, not in `~/.openclaw/`.
+
+## Multi-agent coordination
+
+If you use both OpenClaw and a coding agent (Claude Code, Cursor, etc.) on the same project, brainclaw coordinates between them:
+
+- OpenClaw records a constraint → Claude Code sees it at next session
+- Claude Code claims a file scope → OpenClaw knows not to edit there
+- Either agent creates a plan → both see it in their context
+
+## Profile
+
+When loading context for OpenClaw, use the `openclaw` profile for optimized scoring:
+
+```bash
+brainclaw context --profile openclaw
+```
+
+This boosts constraints, handoffs, and runtime notes — the items most relevant to an agent that might not be editing code directly but needs to understand the project state.

package/docs/integrations/opencode.md

@@ -1,84 +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.
+# 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.