brainclaw 1.7.5 → 1.9.0

package/docs/integrations/cline.md

@@ -1,6 +1,6 @@
 # Cline Integration
 
-brainclaw integrates with Cline through MCP tools, instruction rules, and lifecycle hooks. Cline is a Tier A agent — full MCP access, hooks, auto-approve support, skills, and CLI spawn capability for parallel lanes.
+brainclaw integrates with Cline through MCP tools, instruction rules, auto-approval, and CLI spawn capability for parallel lanes. Cline does not currently expose a Brainclaw-managed lifecycle hook surface.
 
 ## Auto-setup
 
@@ -51,9 +51,9 @@ Cline supports per-server `alwaysAllow` for auto-approving specific tools:
 - `.clinerules/live.md` — optional local live companion with current plans, claims, traps, candidates, and handoffs. Write it with `brainclaw export --format cline --write --include-live`; it remains gitignored.
 - Static content stays behavioural and lightweight. By default, live state flows through MCP; the live companion is an optional parity/backstop file.
 
-## SKILL.md discovery
-
-Cline auto-discovers skills from `.clinerules/`, `.claude/skills/`, and `.agents/skills/`. brainclaw writes a single `.agents/skills/brainclaw/SKILL.md` that Cline picks up automatically.
+## SKILL.md discovery
+
+Cline may discover skills from agent-specific directories depending on the installed extension/version. Brainclaw's current Cline writer configures MCP and `.clinerules/brainclaw.md`; it does not write a Cline-specific SKILL.md.
 
 ## Headless invocation
 
@@ -69,11 +69,11 @@ The `-y` flag (YOLO mode) disables interactive approval prompts so the spawned w
 
 | Field | Value |
 |-------|-------|
-| Tier | A |
-| MCP | yes |
-| Hooks | yes |
-| Auto-approve | yes (`alwaysAllow` per server, `-y` per session) |
-| Skills | yes |
+| Tier | A |
+| MCP | yes |
+| Hooks | no |
+| Auto-approve | yes (`alwaysAllow` per server, `-y` per session) |
+| Skills | no Brainclaw-specific writer |
 | CLI spawnable | yes |
 | Max concurrent tasks | 3 |
 | Workflow model | interactive |
@@ -82,7 +82,6 @@ The `-y` flag (YOLO mode) disables interactive approval prompts so the spawned w
 
 ## Caveats
 
-- **Hook support varies by platform**: Cline hooks are reliable on macOS/Linux but the Windows path is less exercised. brainclaw generates hooks that gracefully degrade when the runtime doesn't honour them — the templateTier stays A regardless.
-- **Cline / Roo / Kilocode family**: Cline shares its config-pattern lineage with Roo Code and Kilocode. The directory names differ (`.clinerules/` vs `.roo/rules/` vs `.kilo/rules/`) but the auto-discovery model is the same.
+- **Cline / Roo / Kilocode family**: Cline shares its config-pattern lineage with Roo Code and Kilocode. The directory names differ (`.clinerules/` vs `.roo/rules/` vs `.kilo/rules/`) but the auto-discovery model is the same.
 - **Project-scoped MCP**: unlike machine-scoped agents (Cursor, Windsurf), Cline's MCP config lives in the repo. Each repo gets its own brainclaw registration.
 - **Long prompts**: inline arg supports up to 8000 chars before falling back to inbox-structured delivery. Briefs longer than that should arrive via inbox.

package/docs/integrations/codex.md

@@ -1,6 +1,6 @@
 # Codex Integration
 
-brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex is a Tier A agent — full MCP access, lifecycle hooks, skills support, and headless CLI spawn capability.
+brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex has MCP access, universal skills support, and headless CLI spawn capability, but no native lifecycle hook surface.
 
 ## Auto-setup
 
@@ -61,7 +61,7 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 |-------|-------|
 | Tier | A |
 | MCP | yes |
-| Hooks | yes |
+| Hooks | no |
 | Auto-approve | manual (per-tool approval) |
 | Skills | yes |
 | CLI spawnable | yes |

package/docs/integrations/continue.md

@@ -6,9 +6,9 @@ brainclaw integrates with Continue through MCP tools and project-scoped rules, g
 
 `brainclaw init` detects Continue and writes `.continue/rules/brainclaw.md` automatically. Or manually:
 
-```bash
-brainclaw export --format continue-rules --write
-```
+```bash
+brainclaw export --format continue --write
+```
 
 ## MCP configuration
 
@@ -32,7 +32,7 @@ Per-server YAML configs are also supported in `.continue/mcpServers/*.yaml`.
 
 Continue uses a separate permissions file at `~/.continue/permissions.yaml`. Tool-level control uses `--allow`, `--ask`, and `--exclude` flags on the CLI.
 
-brainclaw does not yet emit `permissions.yaml` automatically — configure manually if running headless.
+`brainclaw setup-machine` writes `~/.continue/permissions.yaml` when Continue is selected. Configure it manually only if you need stricter local policy than Brainclaw's generated defaults.
 
 ## SKILL.md discovery
 
@@ -55,6 +55,6 @@ cn /path/to/project
 ## Caveats
 
 - **No hooks**: Continue delegates hook-like behavior to VS Code extensions. No native pre-prompt injection.
-- **No auto-approve writer**: brainclaw does not emit `permissions.yaml` yet — tool approval must be configured manually.
+- **Permissions are machine-local**: Brainclaw can write `~/.continue/permissions.yaml`, but it is not committed with the project.
 - **No native subagents**: Continue does not expose subagent orchestration.
 - **Windows**: Works via VS Code extension; CLI (`cn`) requires Node.js on PATH.

package/docs/integrations/copilot.md

@@ -4,10 +4,12 @@ brainclaw integrates with GitHub Copilot through MCP tools, instruction files, a
 
 ## Auto-setup
 
-`brainclaw init` detects Copilot (`gh copilot` or `copilot` CLI installed) and writes:
-
-- `.github/copilot-instructions.md` — instruction file Copilot reads automatically on each prompt
-- MCP registration at `~/.copilot/mcp-config.json` (machine-level fallback) and/or project-level `.github/copilot/mcp-config.json`
+`brainclaw init` detects Copilot (`gh copilot` or `copilot` CLI installed) and writes:
+
+- `.github/copilot-instructions.md` — instruction file Copilot reads automatically on each prompt
+- `.vscode/settings.json` and `.vscode/mcp.json` — project-level MCP registration used by VS Code/Copilot surfaces
+- `.github/copilot/hooks.json` — session lifecycle hooks where supported
+- `.github/skills/brainclaw-context/SKILL.md` and `.agents/skills/brainclaw/SKILL.md` — Copilot and cross-agent skill discovery
 
 Manual regeneration:
 
@@ -18,14 +20,14 @@ brainclaw export --format copilot-instructions --write --include-live
 
 ## MCP configuration
 
-Copilot reads MCP servers from `~/.copilot/mcp-config.json`:
-
-```json
-{
-  "mcpServers": {
-    "brainclaw": {
-      "command": "npx",
-      "args": ["-y", "brainclaw@latest", "mcp"]
+VS Code/Copilot reads project MCP configuration from `.vscode/settings.json` and `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
     }
   }
 }

package/docs/integrations/openclaw.md

@@ -38,12 +38,13 @@ 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/
-```
+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
 

package/docs/integrations/overview.md

@@ -71,16 +71,16 @@ The agent cannot call brainclaw tools at all. The instruction file or SKILL.md b
 | Agent | MCP | Instruction file | Hooks | Auto-approve | Skills |
 |---|---|---|---|---|---|
 | **Claude Code** | ✔ project + global | CLAUDE.md | ✔ pre-prompt + stop | ✔ permissions | ✔ /brainclaw |
-| **Cursor** | ✔ global | .cursor/rules/ + MDC | ◐ alwaysApply MDC | — | — |
-| **Windsurf** | ✔ global | .windsurfrules | ◐ session trigger | — | — |
+| **Cursor** | ✔ global | .cursor/rules/ + MDC | ✔ workspace hooks | — | ✔ universal skills |
+| **Windsurf** | ✔ global | .windsurfrules + .windsurf/rules/ | — | ✔ alwaysAllow | — |
 | **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 | — | — | — |
+| **Continue** | ✔ both | .continue/rules/ | — | ✔ permissions.yaml | — |
+| **Kilocode** | ✔ both | .kilo/rules/ + AGENTS.md | — | ✔ alwaysAllow | ✔ universal skills |
+| **OpenCode** | ✔ project | AGENTS.md | — | — | ✔ universal skills |
+| **Codex** | ✔ global | AGENTS.md | — | — | ✔ universal skills |
 | **Gemini CLI** | ✔ global | GEMINI.md | — | — | — |
-| **GitHub Copilot** | ✔ global + project | .github/copilot-instructions.md | — | manual (per-call) | ✔ brainclaw-context |
+| **GitHub Copilot** | ✔ project | .github/copilot-instructions.md | ✔ workspace hooks | manual (per-call) | ✔ brainclaw-context + universal skills |
 | **Mistral Vibe** | ✔ project + user (TOML) | AGENTS.md | — | `--auto-approve` flag | ✔ universal skill |
 | **Hermes** | ✔ global (YAML) | AGENTS.md | — | — | ✔ universal skill |
 | **OpenClaw** | — | — | — | — | ✔ brainclaw skill |

package/docs/integrations/roo.md

@@ -6,9 +6,9 @@ brainclaw integrates with Roo through MCP tools and project-scoped rules, provid
 
 `brainclaw init` detects Roo and writes `.roo/rules/brainclaw.md` automatically. Or manually:
 
-```bash
-brainclaw export --format roo-rules --write
-```
+```bash
+brainclaw export --format roo --write
+```
 
 ## MCP configuration
 

package/docs/integrations/windsurf.md

@@ -6,9 +6,9 @@ brainclaw integrates with Windsurf through MCP tools and instruction rules, prov
 
 `brainclaw init` detects Windsurf and writes `.windsurfrules` automatically. Or manually:
 
-```bash
-brainclaw export --format windsurfrules --write
-```
+```bash
+brainclaw export --format windsurf --write
+```
 
 ## MCP configuration
 
@@ -49,14 +49,14 @@ Windsurf supports `alwaysAllow` as an array on each MCP server entry:
 }
 ```
 
-brainclaw does not yet emit `alwaysAllow` for Windsurf automatically.
+`brainclaw setup-machine` emits the Windsurf MCP config with `alwaysAllow` for the Brainclaw tool surface.
 
 ## Instruction files
 
 - `.windsurf/rules/*.md` — modern format (recommended), multiple rule files
 - `.windsurfrules` — legacy single-file format (still supported)
 
-brainclaw currently emits the legacy format. Modern `.windsurf/rules/` support is planned.
+`brainclaw export --format windsurf --write` writes the legacy `.windsurfrules` instruction file. Project setup also writes `.windsurf/rules/brainclaw.md` when Windsurf is selected, so modern rule discovery is covered.
 
 ## SKILL.md discovery
 
@@ -77,7 +77,7 @@ Windsurf does not offer a headless CLI. It runs as a Docker-based environment
 
 - **Machine-scoped MCP**: The config at `~/.codeium/windsurf/mcp_config.json` is global, not per-project. All projects share the same server list.
 - **No hooks**: Cascade Hooks exist but are limited to logging — no pre-prompt injection.
-- **Legacy format**: brainclaw currently writes `.windsurfrules` (single file). Modern `.windsurf/rules/` multi-file support is planned (P5).
+- **Two rule paths**: `.windsurfrules` remains the portable export target; `.windsurf/rules/brainclaw.md` is written during project setup for modern Windsurf rule discovery.
 - **No headless**: Cannot be used as a brainclaw dispatch target.
 - **Plan Mode**: Windsurf's "megaplan" mode is separate from brainclaw plans — they don't conflict but don't interoperate.
 - **Windows/Linux**: Works on all platforms via the Windsurf IDE.

package/docs/mcp-schema-changelog.md

@@ -10,6 +10,17 @@ guarantees this changelog follows.
 
 ## Unreleased
 
+**Changed — agent-UX read-path surface (pln#542)**
+- `bclaw_work`, `bclaw_context`, `bclaw_find`, `bclaw_get`, `bclaw_search`
+  gain an optional `budget_tokens` argument (relevance-ranked fill).
+- `bclaw_work` compact payload now includes a trimmed `context_diff`
+  (event-cursor sourced, all intents) and facade responses carry
+  `next_actions` affordances.
+- `bclaw_quick_capture` gains an optional caller-asserted `type` argument;
+  contradiction detection is advisory metadata (no longer blocks promotion).
+- No tool was removed or renamed; no required argument changed.
+- MCP public surface fingerprint: `sha256:eaa8865070b10401`
+
 **Changed — JSON Schema generation shift (pln#486, zod 4 migration)**
 - Migration from zod 3.24 → 4.3.6 changes the introspection output that
   feeds `tools/list`. Schemas are semantically equivalent but the emitted
@@ -19,7 +30,7 @@ guarantees this changelog follows.
   to `sha256:860fbaa30a486093` (zod 4). No tool was added, removed,
   renamed, or had its required arguments change.
 
-**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
+**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
 - New optional field `allow_orphan: boolean` on `BclawLoopOpenSchema`.
 - Default (absent / `false`) — handler rejects with `validation_error`
   and points to `bclaw_coordinate(intent: 'review', open_loop: true)`
@@ -28,20 +39,20 @@ guarantees this changelog follows.
   out in `CLAUDE.md`.
 - `allow_orphan: true` — explicit acknowledgement that the caller
   will drive `turn()` + dispatch manually (advanced / test use only).
-- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
-  affected — they bypass `handleBclawLoop` and invoke the core
-  `openLoop()` directly.
-
-**Changed — sequence tools promoted to default discovery (pln#522)**
-- `bclaw_list_sequences`, `bclaw_create_sequence`,
-  `bclaw_update_sequence`, and `bclaw_delete_sequence` move from
-  `advanced` to `standard`, so fresh agents see them in the default
-  `tools/list` catalog. Sequences are a core agent-first coordination
-  primitive for parallel dispatch, not an advanced-only admin surface.
-- `bclaw_create_sequence.items` and `bclaw_update_sequence.items` now
-  expose the full item shape in JSON Schema: `planId`, optional
-  `stepId`, `rank`, `hard_after`, `soft_after`, `lane`, `scope_hint`,
-  and `rationale`.
+- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
+  affected — they bypass `handleBclawLoop` and invoke the core
+  `openLoop()` directly.
+
+**Changed — sequence tools promoted to default discovery (pln#522)**
+- `bclaw_list_sequences`, `bclaw_create_sequence`,
+  `bclaw_update_sequence`, and `bclaw_delete_sequence` move from
+  `advanced` to `standard`, so fresh agents see them in the default
+  `tools/list` catalog. Sequences are a core agent-first coordination
+  primitive for parallel dispatch, not an advanced-only admin surface.
+- `bclaw_create_sequence.items` and `bclaw_update_sequence.items` now
+  expose the full item shape in JSON Schema: `planId`, optional
+  `stepId`, `rank`, `hard_after`, `soft_after`, `lane`, `scope_hint`,
+  and `rationale`.
 
 ---
 
@@ -93,11 +104,31 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:a1881ff57ddce377`
-  (updated 2026-05-27: added the `ref` property to the bclaw_coordinate
-  inputSchema — pln#520 Tier 2 / trp#371, the scope-aware dirty guard;
-  `ref` lets a dispatch build its worktree from an explicit git ref.
-  Prior value `sha256:0a4ba280aeff142b` exposed `allow_dirty` in the
+- MCP public surface fingerprint: `sha256:b1d3c6a00a224509`
+  (updated 2026-06-14: journal ON by default + `migrate --enable-journal`,
+  registry post-image families + verify gate, and capped auto-handoff diff
+  preview on `bclaw_get`; pln#567/#568/#569.
+  Previous: `sha256:21fa9544977a3754`,
+  updated 2026-06-11b: observability surfaces — composite
+  `attention_required` in board_summary, observer-mode read flags,
+  `bootstrap_verdict` in FacadeResponse; pln#557/#558/#559.
+  Previous: `sha256:8f86d3998f8a24e3`,
+  updated 2026-06-11: uninitialized setup mode — the server now boots with
+  a minimal catalog on a missing project store instead of exit(1), and the
+  empty-memory decision rule is surfaced in setup/work hints; pln#556.
+  Previous: `sha256:eaa8865070b10401`,
+  updated 2026-06-10: agent-UX read-path surface — `budget_tokens` on the
+  read tools, `context_diff`/`next_actions` in facade payloads,
+  caller-asserted `type` on quick_capture; see the Unreleased entry, pln#542.
+  Previous: `sha256:333be7c3cda7e166`,
+  updated 2026-06-09: added the `preflight` boolean to the bclaw_coordinate
+  inputSchema — pln#533, the pre-flight spawn validation for open_loop reviews
+  (run one trivial validation spawn per reviewer before opening the loop so an
+  environment death surfaces with a clear reason instead of a generic timeout).
+  Prior value `sha256:a1881ff57ddce377` added the `ref` property to the
+  bclaw_coordinate inputSchema (2026-05-27, pln#520 Tier 2 / trp#371, the
+  scope-aware dirty guard; `ref` lets a dispatch build its worktree from an
+  explicit git ref). `sha256:0a4ba280aeff142b` exposed `allow_dirty` in the
   bclaw_coordinate inputSchema. `sha256:e88c1a97fc29cfd1` came from the
   pln#520 LoopPhase/LoopSlotInput schema resync, which itself reconciled
   earlier unrecorded drift from `sha256:724085642dc3e2d7`.)

package/docs/quickstart.md

@@ -6,46 +6,46 @@ Get brainclaw running in your project in under 5 minutes.
 
 If you're about to cut a release that changes the CLI, MCP, or context surface, run the checklist in [release-maintenance.md](release-maintenance.md) before publishing a local pack or npm build.
 
-## Step 1: Install
-
-```bash
-npm install -g brainclaw
-```
-
-Requires Node.js 20+. Verify with `brainclaw --version`.
-
-## Step 2: Bootstrap this machine
-
-```bash
-brainclaw setup-machine --yes
-```
-
-This configures the agents Brainclaw can see on the current machine and writes the machine-level MCP/user files it manages. It does **not** initialize the current repository yet.
-
-## Step 3: Initialize or refresh your project
-
-```bash
-cd your-project
-brainclaw init
-```
-
-**What happens:**
-- Creates `.brainclaw/` when the project is new, or refreshes it safely when it already exists
-- Detects your coding agent (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.)
-- Refreshes the detected agent's project and machine integration files when applicable
-- Writes instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/brainclaw.md`, etc.)
-- Installs session hooks (if supported by your agent)
-- Adds `.brainclaw/` to `.gitignore`
-
-If you want the explicit path for a second or late-arriving agent on an already initialized project, use:
-
-```bash
-brainclaw enable-agent <agent-name>
-```
-
-If you have multiple repos, use `brainclaw setup --yes` instead — it bootstraps the machine, scans your project directories, and initializes everything at once.
-
-## Step 4: Restart your agent
+## Step 1: Install
+
+```bash
+npm install -g brainclaw
+```
+
+Requires Node.js 20+ (`engines.node = ">=20.0.0"`). CI exercises Node 22 (Active LTS) and Node 24 (current LTS) — Node 22 or 24 is the recommended runtime; Node 20 still installs but is no longer CI-verified since its April 2026 EOL. Verify with `brainclaw --version`.
+
+## Step 2: Bootstrap this machine
+
+```bash
+brainclaw setup-machine --yes
+```
+
+This configures the agents Brainclaw can see on the current machine and writes the machine-level MCP/user files it manages. It does **not** initialize the current repository yet.
+
+## Step 3: Initialize or refresh your project
+
+```bash
+cd your-project
+brainclaw init
+```
+
+**What happens:**
+- Creates `.brainclaw/` when the project is new, or refreshes it safely when it already exists
+- Detects your coding agent (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.)
+- Refreshes the detected agent's project and machine integration files when applicable
+- Writes instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/brainclaw.md`, etc.)
+- Installs session hooks (if supported by your agent)
+- Adds `.brainclaw/` to `.gitignore`
+
+If you want the explicit path for a second or late-arriving agent on an already initialized project, use:
+
+```bash
+brainclaw enable-agent <agent-name>
+```
+
+If you have multiple repos, use `brainclaw setup --yes` instead — it bootstraps the machine, scans your project directories, and initializes everything at once.
+
+## Step 4: Restart your agent
 
 Your coding agent needs to reload to pick up the new MCP configuration.
 
@@ -58,7 +58,7 @@ Your coding agent needs to reload to pick up the new MCP configuration.
 | **Windsurf** | Reload the editor |
 | **Copilot** | Reload VS Code window (uses instruction file, not MCP) |
 
-## Step 5: Verify it works
+## Step 5: Verify it works
 
 After reloading, tell your agent:
 
@@ -76,7 +76,7 @@ brainclaw agent-board     # what each agent sees
 brainclaw context         # current project memory
 ```
 
-## Step 6: Start using brainclaw
+## Step 6: Start using brainclaw
 
 ### For agents with MCP (most agents)
 
@@ -109,11 +109,12 @@ The CLI is for inspection, scripting, and fallback:
 
 ```bash
 brainclaw plan create "Implement auth module" --priority high
-brainclaw plan list
-brainclaw claim list
-brainclaw context --for src/auth/routes.ts
-brainclaw export --detect --write    # regenerate all instruction files
-```
+brainclaw plan list
+brainclaw claim list
+brainclaw context --for src/auth/routes.ts
+brainclaw export --detect --write    # regenerate the detected agent instruction file
+brainclaw export --all               # regenerate all known instruction files
+```
 
 ## Onboarding an existing project