brainclaw 0.29.2 → 1.5.4

package/README.md

@@ -4,33 +4,26 @@
 
 <h1 align="center">brainclaw</h1>
 
-<p align="center"><strong>Local-first coordination for coding agents, with human-readable local control.</strong></p>
+<p align="center"><strong>Local-first coordination and shared memory for coding agents.</strong></p>
 
 ---
 
-brainclaw gives a workspace a shared coordination layer for coding agents: project memory, explicit plans, file claims, handoffs, layered instructions, and prompt-ready context, all stored locally, versioned in Git, and readable in plain text.
+If you've ever:
+- **lost your conversation** when your agent hit credit limits mid-task,
+- returned to a project **after a week** with no idea where you left off,
+- watched two coworkers (or two agents) **edit the same files** without knowing it,
+- or **gave up running multiple agents in parallel** because keeping them in sync was a pain,
 
-For capable agents, the nominal path is:
+brainclaw gives you durable shared state across sessions, agents, and teammates. Plans, claims, handoffs, decisions, and traps live in `.brainclaw/`, work identically across any compatible agent (Claude Code, Codex, Copilot, Cline, OpenCode, Cursor, Windsurf, Kilocode, Roo Code, Continue, Mistral Vibe, Antigravity/Gemini CLI, …), and stay accessible whether you orchestrate them in parallel or pick them up one after another.
 
-1. read dynamic state through MCP
-2. use native agent files such as `AGENTS.md`, `CLAUDE.md`, or Cursor rules as local guidance
-3. leave the CLI to operators, scripts, setup, release, and fallback workflows
+Use it two ways — **together or separately**:
 
-The best setup is usually not "open a terminal and run Brainclaw yourself".
-The best setup is to tell your agent, in natural language, to install and initialize Brainclaw in the repo so it can bootstrap its own working context correctly.
+- **Active orchestration** — dispatch work in parallel across multiple agent instances. Claims prevent conflicts, sequences manage lane dependencies, the dispatcher routes by capacity.
+- **Async shared state** — when an agent runs out of credits, when you return to a project after weeks, or when teammates work in parallel: the next agent (or you) resumes cleanly with the same context, plans, and constraints.
 
-It sits alongside Copilot, Claude Code, Cursor, Codex, Windsurf, OpenCode, Antigravity/Gemini CLI and other coding agents. It does not replace them. It gives them a shared state layer they can resume from reliably across sessions.
+The same primitives — plans, claims, handoffs, decisions, traps — serve both modes. That's the design point. brainclaw stores everything locally as plain text + JSON, versions it in Git, and asks no opinion about which agent you should use for what.
 
-brainclaw is also starting to model other local AI work surfaces on the same machine, such as ChatGPT Desktop, Claude Desktop, Claude Cowork, and Gemini web or CLI. That makes it possible to keep a project-level queue of non-code work for those surfaces, instead of treating every task as something the active coding agent must do itself.
-
----
-
-## Why brainclaw exists
-
-Coding agents are getting better at local code generation, but they still struggle with shared project state.
-Across real projects, agents often miss active constraints, forget known traps, duplicate work, step on the same files, and lose context between sessions or tool surfaces.
-
-brainclaw solves this by making the repo itself agent-readable and agent-writeable through MCP, local memory files, and explicit coordination primitives.
+It sits alongside your coding agents and gives them a shared state layer they can resume from reliably. brainclaw is also starting to model other local AI work surfaces on the same machine, such as ChatGPT Desktop, Claude Desktop, Claude Cowork, and Gemini web or CLI, to keep a project-level queue of non-code work for those surfaces.
 
 ---
 
@@ -42,6 +35,7 @@ brainclaw solves this by making the repo itself agent-readable and agent-writeab
 | **Coordination state** | shared plans, file claims, runtime notes, and board views for active work |
 | **Agent-ready context** | compact, prompt-sized context built from real workspace state instead of stale instructions |
 | **Native agent files** | auto-writes `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`, and similar local guidance |
+| **Multi-turn loops** | review and ideation loops with structured phases, iteration semantics, and per-phase memory filters — see [loop engine](docs/concepts/loop-engine.md) and [ideation loop](docs/concepts/ideation-loop.md) |
 | **Machine AI surface discovery** | detects local coding agents plus desktop AI work surfaces such as ChatGPT Desktop and Gemini CLI |
 | **Queued surface tasks** | stores project-scoped requests for other local AI surfaces, such as visual generation, drafting, summaries, or research |
 | **Local-first storage** | plain text + JSON, Git-friendly, no mandatory cloud, no telemetry by default |
@@ -68,32 +62,32 @@ brainclaw is designed to sit alongside the coding agents teams are already using
 
 ### Code Agents
 
-| Logo | Agent | Integration | What brainclaw configures |
+| Logo | Agent | Tier | What brainclaw configures |
 |---|---|---|---|
-| [![Claude Code](https://img.shields.io/badge/Claude_Code-111111?logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code) | **[Claude Code](https://github.com/anthropics/claude-code)** | Full | MCP + CLAUDE.md + hooks + permissions + /brainclaw command |
-| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/) | **[Codex](https://openai.com/codex/)** | Standard | MCP + AGENTS.md |
-| [![Cursor](https://img.shields.io/badge/Cursor-1F2430?logo=cursor&logoColor=white)](https://cursor.com/en-US) | **[Cursor](https://cursor.com/en-US)** | Standard | MCP + .cursor/rules/ + alwaysApply MDC |
-| [![OpenCode](https://img.shields.io/badge/OpenCode-0F172A?logoColor=white)](https://github.com/opencode-ai/opencode) | **[OpenCode](https://github.com/opencode-ai/opencode)** | Standard | MCP + AGENTS.md |
-| [![Windsurf](https://img.shields.io/badge/Windsurf-0B1220?logo=codeium&logoColor=white)](https://windsurf.com/) | **[Windsurf](https://windsurf.com/)** | Standard | MCP + .windsurfrules session trigger |
-| [![Roo](https://img.shields.io/badge/Roo-7C3AED?logoColor=white)](https://github.com/RooCodeInc/Roo-Code) | **[Roo](https://github.com/RooCodeInc/Roo-Code)** | Standard | MCP (auto-approve) + .roo/rules/ |
-| [![Cline](https://img.shields.io/badge/Cline-0F766E?logoColor=white)](https://github.com/cline/cline) | **[Cline](https://github.com/cline/cline)** | Standard | MCP (auto-approve) + .clinerules/ |
-| [![Continue](https://img.shields.io/badge/Continue-2563EB?logoColor=white)](https://github.com/continuedev/continue) | **[Continue](https://github.com/continuedev/continue)** | Standard | MCP + .continue/rules/ |
-| [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-1A73E8?logo=googlegemini&logoColor=white)](https://github.com/google-gemini/gemini-cli) | **[Antigravity / Gemini CLI](https://github.com/google-gemini/gemini-cli)** | Standard | MCP + GEMINI.md |
-| [![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-181717?logo=githubcopilot&logoColor=white)](https://github.com/features/copilot) | **[GitHub Copilot](https://github.com/features/copilot)** | Limited | copilot-instructions.md + brainclaw-context skill |
-
-**Full** = MCP + hooks + auto-approve (context injected every prompt). **Standard** = MCP + instruction file (agent must call tools explicitly). **Limited** = skill-based (agent calls brainclaw CLI via skill instructions).
+| [![Claude Code](https://img.shields.io/badge/Claude_Code-111111?logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code) | **[Claude Code](https://github.com/anthropics/claude-code)** | A | MCP + CLAUDE.md + hooks + auto-approve + permissions + /brainclaw skill |
+| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/) | **[Codex](https://openai.com/codex/)** | A | MCP + AGENTS.md + hooks + skills |
+| [![Cursor](https://img.shields.io/badge/Cursor-1F2430?logo=cursor&logoColor=white)](https://cursor.com/en-US) | **[Cursor](https://cursor.com/en-US)** | A | MCP (machine) + .cursor/rules/ + hooks + skills |
+| [![Windsurf](https://img.shields.io/badge/Windsurf-0B1220?logo=codeium&logoColor=white)](https://windsurf.com/) | **[Windsurf](https://windsurf.com/)** | A | MCP (machine) + .windsurfrules + hooks + skills |
+| [![Cline](https://img.shields.io/badge/Cline-0F766E?logoColor=white)](https://github.com/cline/cline) | **[Cline](https://github.com/cline/cline)** | A | MCP + auto-approve + .clinerules/ + hooks + skills |
+| [![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-181717?logo=githubcopilot&logoColor=white)](https://github.com/features/copilot) | **[GitHub Copilot](https://github.com/features/copilot)** | A | MCP + copilot-instructions.md + hooks + skills |
+| [![Roo](https://img.shields.io/badge/Roo-7C3AED?logoColor=white)](https://github.com/RooCodeInc/Roo-Code) | **[Roo](https://github.com/RooCodeInc/Roo-Code)** | B | MCP + auto-approve + .roo/rules/ |
+| [![Continue](https://img.shields.io/badge/Continue-2563EB?logoColor=white)](https://github.com/continuedev/continue) | **[Continue](https://github.com/continuedev/continue)** | B | MCP + .continue/rules/ |
+| [![OpenCode](https://img.shields.io/badge/OpenCode-0F172A?logoColor=white)](https://github.com/opencode-ai/opencode) | **[OpenCode](https://github.com/opencode-ai/opencode)** | B | MCP + AGENTS.md |
+| [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-1A73E8?logo=googlegemini&logoColor=white)](https://github.com/google-gemini/gemini-cli) | **[Antigravity / Gemini CLI](https://github.com/google-gemini/gemini-cli)** | B | MCP + GEMINI.md |
+
+**Tier A** = MCP + hooks + skills (context injected dynamically, lightweight instruction files). **Tier B** = MCP only, no hooks (richer static instruction files with architecture + top traps). Tier can degrade at runtime if integration surfaces are missing.
 
 ### Autonomous Agents
 
-| Logo | Agent | Workflow | What brainclaw configures |
+| Logo | Agent | Tier | What brainclaw configures |
 |---|---|---|---|
-| [![OpenClaw](https://img.shields.io/badge/OpenClaw-FF6B35?logoColor=white)](https://github.com/openclaw/openclaw) | **[OpenClaw](https://github.com/openclaw/openclaw)** | Task-based | brainclaw skill (SKILL.md) for structured project memory |
-| [![NanoClaw](https://img.shields.io/badge/NanoClaw-4A90D9?logoColor=white)](https://github.com/qwibitai/nanoclaw) | **[NanoClaw](https://github.com/qwibitai/nanoclaw)** | Task-based | brainclaw skill — messaging agent (WhatsApp, Telegram, Slack) |
-| [![NemoClaw](https://img.shields.io/badge/NemoClaw-76B900?logo=nvidia&logoColor=white)](https://github.com/NVIDIA/NemoClaw) | **[NemoClaw](https://github.com/NVIDIA/NemoClaw)** | Task-based | brainclaw skill — NVIDIA enterprise agent stack |
-| [![PicoClaw](https://img.shields.io/badge/PicoClaw-00ADD8?logo=go&logoColor=white)](https://github.com/sipeed/picoclaw) | **[PicoClaw](https://github.com/sipeed/picoclaw)** | Scheduled | brainclaw skill — edge/IoT agent (Go, <10MB RAM) |
-| [![ZeroClaw](https://img.shields.io/badge/ZeroClaw-B7410E?logoColor=white)](https://github.com/zeroclaw-labs/zeroclaw) | **[ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw)** | Task-based | brainclaw skill — ultra-lightweight Rust agent (20+ channels) |
+| [![OpenClaw](https://img.shields.io/badge/OpenClaw-FF6B35?logoColor=white)](https://github.com/openclaw/openclaw) | **[OpenClaw](https://github.com/openclaw/openclaw)** | B | MCP + brainclaw skill (SKILL.md) for structured project memory |
+| [![NanoClaw](https://img.shields.io/badge/NanoClaw-4A90D9?logoColor=white)](https://github.com/qwibitai/nanoclaw) | **[NanoClaw](https://github.com/qwibitai/nanoclaw)** | C | brainclaw skill — messaging agent (WhatsApp, Telegram, Slack) |
+| [![NemoClaw](https://img.shields.io/badge/NemoClaw-76B900?logo=nvidia&logoColor=white)](https://github.com/NVIDIA/NemoClaw) | **[NemoClaw](https://github.com/NVIDIA/NemoClaw)** | C | brainclaw skill — NVIDIA enterprise agent stack |
+| [![PicoClaw](https://img.shields.io/badge/PicoClaw-00ADD8?logo=go&logoColor=white)](https://github.com/sipeed/picoclaw) | **[PicoClaw](https://github.com/sipeed/picoclaw)** | C | brainclaw skill — edge/IoT agent (Go, <10MB RAM) |
+| [![ZeroClaw](https://img.shields.io/badge/ZeroClaw-B7410E?logoColor=white)](https://github.com/zeroclaw-labs/zeroclaw) | **[ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw)** | C | brainclaw skill — ultra-lightweight Rust agent (20+ channels) |
 
-Autonomous agents use brainclaw via CLI skills with `--profile compact` for short sessions and constrained resources.
+**Tier C** = no MCP, no hooks — skill-based only with inline context and constrained resources. Autonomous agents use `--profile compact` for short sessions.
 
 brainclaw is most effective today when one agent works at a time in a given checkout and the next agent resumes from shared context, claims, and handoffs.
 
@@ -101,11 +95,11 @@ brainclaw is most effective today when one agent works at a time in a given chec
 
 ## Platform Support
 
-brainclaw targets Node.js 20+ across major developer operating systems, but real-world support is not perfectly even yet.
+brainclaw declares support for Node.js 20+ in `package.json`, and CI actively exercises Node 20, 22, and 24 across the main Linux path (Windows runs on Node 24). Real-world support is still not perfectly even yet.
 
 | Logo | Platform | Status today | Notes |
 |---|---|---|---|
-| [![Linux](https://img.shields.io/badge/Linux-111111?logo=linux&logoColor=white)](https://www.kernel.org/) | **[Linux](https://www.kernel.org/)** | Recommended | best-supported environment today; GitHub CI runs on Ubuntu with Node 20 and 22 |
+| [![Linux](https://img.shields.io/badge/Linux-111111?logo=linux&logoColor=white)](https://www.kernel.org/) | **[Linux](https://www.kernel.org/)** | Recommended | best-supported environment today; GitHub CI runs on Ubuntu with Node 20, 22, and 24 |
 | [![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)](https://www.apple.com/macos/) | **[macOS](https://www.apple.com/macos/)** | Likely supported | Unix-like path and shell model should map well, but it is less exercised than Linux |
 | [![Windows](https://img.shields.io/badge/Windows-0078D4?logo=windows&logoColor=white)](https://www.microsoft.com/windows/) | **[Windows](https://www.microsoft.com/windows/)** | Supported with caveats | native support exists, but PATH, npm, SSH, and PowerShell quoting still create more friction than on Unix systems |
 | [![Windows + WSL2](https://img.shields.io/badge/Windows%20%2B%20WSL2-0078D4?logo=windows&logoColor=white)](https://learn.microsoft.com/windows/wsl/) | **[Windows + WSL2](https://learn.microsoft.com/windows/wsl/)** | Important, still maturing | Brainclaw detects this setup explicitly, but setup/install/store parity across Windows and WSL is not fully seamless yet |
@@ -114,168 +108,167 @@ If you want the least surprising setup today, use Linux first. If you are on Win
 
 ---
 
-## Best Setup
+## Get Started
+
+### 1. Install
 
-If you want the cleanest Brainclaw onboarding, ask your agent to do it.
+```bash
+npm install -g brainclaw
+```
 
-Example:
+### 2. Initialize a project
 
-```text
-Install Brainclaw in this repo, initialize it, configure the agent integration if needed,
-and then use Brainclaw for shared context, plans, claims, and handoffs while you work.
+```bash
+cd your-project
+brainclaw init
 ```
 
-That is the product's intended entry path.
-The human expresses the intent in plain language. The agent installs Brainclaw, bootstraps the repo, and then keeps using it through MCP and local agent files.
+This creates `.brainclaw/` in your repo, detects your coding agent, writes MCP config and instruction files, and sets up session hooks. It takes about 10 seconds.
 
-If the agent supports MCP well, this produces a better bootstrap than a human manually running setup commands first, because the agent can immediately:
+### 3. Restart your agent
 
-- set up the workspace in the right environment
-- write the local agent-facing files it will actually use
-- configure MCP where supported
-- start from shared context instead of ad hoc instructions
+Restart your coding agent (or reload MCP servers) so it picks up the new configuration. After that, brainclaw tools are available.
 
----
+### 4. Start working
 
-## Quick Example
+Pick one of the canonical entry points depending on what you're doing:
 
-```bash
-# behind the scenes, the agent will typically bootstrap Brainclaw in the repo
-npx brainclaw setup --yes
-npx brainclaw init
+```text
+# Solo work — start a session, load context, claim a scope:
+bclaw_work(intent="execute", scope="src/feature")
+
+# Multi-agent — assign work, consult, open a review, or open an ideation loop:
+bclaw_coordinate(intent="assign|consult|review|ideate", task="...", targetAgents=[...])
+
+# Parallel lanes — dispatch a sequence across several agent instances:
+bclaw_dispatch(intent="execute", agents=[...])
 ```
 
-After that, the agent should stay on Brainclaw's MCP path for live state:
+Common follow-ups during work — all use the canonical CRUD grammar:
 
 ```text
-bclaw_session_start      -> open session + return board/context
-bclaw_get_execution_context -> inspect local tooling + notice Brainclaw package updates
-bclaw_get_context        -> fetch fresh prompt-ready context for a path
-bclaw_list_plans         -> inspect shared work
-bclaw_claim              -> claim scope before editing
-bclaw_write_note         -> record runtime observations
-bclaw_session_end        -> close session and hand work off cleanly
+bclaw_context(kind="memory", path=...)        → narrow project memory to a scope
+bclaw_find(entity="...", filter=...)          → list plans, claims, handoffs, candidates, …
+bclaw_get(entity="...", id=...)               → read one item
+bclaw_create(entity="runtime_note", data=…)   → record an observation, decision, or trap
+bclaw_read_inbox()                            → pick up assigned work or review requests
+bclaw_session_end(narrative=…)                → close cleanly, hand off context to the next agent
 ```
 
-Humans can still use the CLI directly for inspection, scripting, and fallback workflows:
+For agents without MCP (e.g. Copilot reads `.github/copilot-instructions.md`), regenerate the instruction file when project memory changes:
 
 ```bash
-brainclaw plan create "Coordinate auth rollout" --priority high
-brainclaw claim create "Take auth rollout" --scope src/auth/
-brainclaw context --for src/auth/routes.ts --digest
-brainclaw status
+brainclaw export --detect --write
 ```
 
-And if the current coding agent wants to hand off a non-code task to another local AI surface for later:
+### 5. Verify it works
 
 ```bash
-brainclaw surface-task create "Generate homepage hero visual" \
-  --target chatgpt \
-  --kind visual_asset \
-  --instructions "Create a lightweight product hero visual for the landing page." \
-  --output assets/hero-home.png
-
-brainclaw surface-task list
+brainclaw status          # see active sessions, claims, plans
+brainclaw agent-board     # see what each agent is doing
 ```
 
----
+### Multi-agent setup
 
-## Installation
+To configure brainclaw for all your repos and agents at once:
 
-The intended path is agent-driven bootstrap inside the target repo, not a human doing a manual install flow first.
+```bash
+brainclaw setup --yes
+```
 
-In practice, that means:
+This scans your projects, detects installed agents (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.), and writes MCP configs for each.
 
-1. tell the agent to install and initialize Brainclaw in the repo
-2. let the agent bootstrap MCP and native agent files
-3. let the agent keep using Brainclaw for shared context and coordination while it works
+### Existing projects
 
-If you need the underlying commands, the agent will usually do something close to:
+For repos that already have code, brainclaw can extract context automatically:
 
 ```bash
-npx brainclaw setup --yes
-npx brainclaw init
+brainclaw bootstrap --json     # preview what brainclaw detected
+brainclaw bootstrap --apply    # import into memory
 ```
 
-That gives the agent a better bootstrap path because Brainclaw can immediately:
+See `docs/quickstart.md` for the full walkthrough, `docs/integrations/overview.md` for agent-specific details.
 
-- detect the workspace
-- write native agent files
-- configure MCP where supported
-- seed local project memory and coordination state
+---
 
-If you want a machine-level CLI for operator workflows, debugging, or repeated local use, a global install is still available, but it is not the primary onboarding path:
+## Current state
 
-```bash
-npm install -g brainclaw
-```
+Recent releases have moved a lot of multi-agent parallel work from "risky" to "supported":
 
-By default, Brainclaw's update checks for end-user installs follow the public npm `latest` channel. Projects that need a different track can override `brainclaw_update_source`, for example to use `prelaunch` or a local tarball channel.
+- **Per-claim auto-worktree** — each dispatched lane gets its own isolated git worktree; the coordinator integrates with an octopus merge.
+- **Sequenced parallel execute** — `bclaw_dispatch(intent="execute")` fans out independent lanes across several agent instances and integrates the result.
+- **Symmetric 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.
+- **Cross-platform spawn** — OS-aware prompt delivery (stdin pipe / inline arg) plus a brief-ack file handshake, so spawned workers can be detected and timed out reliably on Windows and Unix.
+- **Worktree GC is scope-bounded** — symlinks and junctions are no longer followed during cleanup, so post-merge sweeps can't wipe `node_modules` or other neighboring directories.
+- **MCP runtime self-heal** — when the runtime is corrupted, the server logs an actionable repair pointer; `brainclaw doctor --repair` rebuilds dist in one step.
 
-If you are working from source while developing Brainclaw itself:
+Still sharp:
 
-```bash
-npm install
-npm run build
-```
+1. **Same-checkout concurrent edits** — running two agents in the *same* working tree (no per-claim worktree) is still the wrong answer. Use the dispatch path (auto-worktree per claim) instead of raw concurrent CLI sessions.
+2. **Cross-machine sync** — federation across machines is on the roadmap, not in v1.x. Today brainclaw's store is local and one-machine-per-project.
+3. **Spawn-and-forget assumptions** — spawned workers don't always commit their work cleanly. The brief-ack file confirms the spawn started; in the worst case the coordinator harvests open changes.
+4. **Live state for hook-less agents** — Tier B/C agents without lifecycle hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe) get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
 
-Also available as `bclaw`:
+Recommended use today:
 
-```bash
-bclaw init
-bclaw status
-```
+1. for parallel work, dispatch a sequence with `bclaw_dispatch(intent="execute")` — each lane gets its own worktree
+2. for sequential work in the same project, let one agent claim at a time and rely on handoffs
+3. when reviewing or fixing across agents, prefer symmetric review loops over manual ping-pong
+4. keep multi-machine workflows on a single source of truth until federation lands
 
 ---
 
-## Quickstart
+## Multi-stack worktree
 
-Start here conceptually:
+When brainclaw creates an agent worktree, it auto-detects which dependency directories to symlink from the main worktree based on stack markers present in the project root:
 
-1. ask the agent to install and initialize Brainclaw in the repo
-2. let the agent use MCP for dynamic state
-3. use the CLI yourself only when you need operator-level inspection or fallback access
+| Stack marker | Symlinked directories |
+|---|---|
+| `package.json` | `node_modules` |
+| `requirements.txt` / `pyproject.toml` / `Pipfile` | `venv`, `.venv` |
+| `Gemfile` | `vendor/bundle` |
+| `go.mod` | `vendor` |
+| `composer.json` | `vendor` |
+| `mix.exs` | `deps` |
 
-Then choose the entry path that matches your surface:
+Maven, Gradle, and Cargo are intentionally excluded — their dependency caches are machine-global (`~/.m2`, `~/.gradle/caches`, `~/.cargo/registry`) and found automatically by the toolchain.
 
-- agent-first runtime: start with `docs/integrations/overview.md` and `docs/integrations/mcp.md`
-- operator CLI: use `docs/quickstart.md` and `docs/cli.md`
-- brownfield onboarding: use `brainclaw bootstrap` and the onboarding guides in `docs/`
+Build outputs like `dist` are **not** symlinked — they must be per-worktree to avoid EBUSY errors when other processes hold handles on the output directory.
 
-If you are evaluating Brainclaw as a product, start with the agent-first runtime path, not the CLI reference.
+Override detection in `.brainclaw/config.yaml`:
 
-Detailed Markdown guides are bundled in the npm package under `docs/`.
+```yaml
+worktree:
+  shared_paths: [".cache"]        # additive to auto-detected
+  exclude_shared: ["node_modules"] # opt-out a detected entry
+```
 
 ---
 
-## Current Limitation
-
-For now, avoid having multiple coding agents edit the same project in parallel in the same checkout.
-
-brainclaw already helps one agent resume or review another agent's work with better shared context, plans, claims, and handoffs. But until dedicated Git worktrees per agent or session are implemented, concurrent edits in the same checkout can still create conflicts, overwritten local state, or confusing Git transitions.
+## Cross-project links
 
-Recommended use today:
+Link a sibling brainclaw project so that signals (candidates, handoffs, runtime notes) can flow between them. Stored under `cross_project_links` in `.brainclaw/config.yaml`.
 
-1. let one agent work at a time in a given checkout
-2. use handoffs when switching from one agent to another
-3. use shared plans, claims, and context to preserve continuity
+```bash
+# Subscribe to incoming signals from a peer (default role)
+brainclaw link add ../brainclaw-cloud
 
----
+# Publish candidates only to a peer
+brainclaw link add ../brainclaw-site --role publisher --channels candidate
 
-## How it fits into agent workflows
+# Replace an existing entry of the same name/path
+brainclaw link add ../brainclaw-cloud --role publisher --force
 
-brainclaw sits *alongside* Copilot, Claude Code, Cursor, Codex, Windsurf, Cline, Roo, Continue, OpenCode, and Antigravity/Gemini CLI.
+# Inspect what's wired
+brainclaw link list
 
-Typical agent-first flow:
+# Drop a link by name, path, or basename
+brainclaw link remove brainclaw-cloud
+```
 
-1. a human asks the agent to install and initialize Brainclaw in the repo
-2. the agent bootstraps Brainclaw in the right environment for that workspace
-3. the agent connects through MCP for fresh context, board views, plans, claims, and runtime writes
-4. native agent files provide local guidance and workflow reminders in the surface the agent already uses
-5. humans use the CLI for inspection, scripting, release, and fallback operations
-6. shared plans, claims, handoffs, and runtime notes keep the next agent resumeable
+`role: publisher` is required to push signals out (`bclaw_write_note --crossProject`, `bclaw_create(entity='handoff', targetProject=…)`, etc.). `role: subscriber` (the default) marks the link as readable only.
 
-brainclaw exposes collaboration views through MCP-readable tools, including context, board views, and structured lists for plans, claims, agents, instructions, and candidates. Readable local files still matter, but MCP is the stronger path for dynamic state and write operations.
+The same surface is available through the canonical grammar for agents: `bclaw_create/find/get/update/remove(entity='cross_project_link')`.
 
 ---
 
@@ -287,13 +280,18 @@ If you are integrating Brainclaw into an agent workflow, start with the agent-fa
 
 | | |
 |---|---|
+| `docs/index.md` | Documentation index grouped by getting started, guides, reference, and design |
 | `docs/integrations/overview.md` | Start here for agent integrations |
 | `docs/integrations/mcp.md` | MCP runtime path for capable agents |
-| `docs/quickstart.md` | Setup paths, including operator and brownfield flows |
+| `docs/quickstart.md` | First-time setup on a new project (greenfield) |
+| `docs/quickstart-existing-project.md` | Joining a project that already has `.brainclaw/` |
+| `docs/server-operations.md` | Operator and remote-server workflow guide |
 | `docs/cli.md` | CLI reference for operators, scripts, and fallback use |
 | `docs/concepts/memory.md` | What "memory" means in brainclaw |
 | `docs/concepts/plans-and-claims.md` | Coordination layer |
 | `docs/concepts/runtime-notes.md` | Ephemeral observations |
+| `docs/concepts/multi-agent-workflows.md` | The four common scenarios — orchestration, agent switching, project recovery, team async |
+| `docs/concepts/troubleshooting.md` | Runbook for degraded coordination state — stale claims, missing dist, octopus failures, etc. |
 | `docs/integrations/cursor.md` | Cursor |
 | `docs/integrations/claude-code.md` | Claude Code |
 | `docs/integrations/copilot.md` | GitHub Copilot |
@@ -302,6 +300,7 @@ If you are integrating Brainclaw into an agent workflow, start with the agent-fa
 | `docs/security.md` | Security model |
 | `docs/review.md` | Reflective review |
 | `docs/reputation.md` | Reputation signals |
+| `docs/playbooks/` | Audience design constraints for brainclaw development |
 
 ---
 
@@ -319,53 +318,77 @@ npm run test:coverage      # with coverage report
 
 ## Changelog
 
-### v0.20.0
+For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
-- **Onboarding rework** : nouveau parcours d'installation en 2-3 étapes au lieu de 4, avec choix explicites (type de projet, topologie mémoire) au lieu de termes techniques
-- **Agent capability profiles** : chaque agent (10 supportés) a un profil de capacité (MCP, hooks, auto-approve, skills, rules) qui détermine le contenu de ses fichiers d'instructions
-- **Templates adaptatifs** : les fichiers d'instructions (CLAUDE.md, AGENTS.md, etc.) sont générés selon 3 tiers — Full (léger, hooks font le reste), Standard (directif, top traps inclus), Limited (riche, tout en statique)
-- **Séparation core/run** : les fichiers statiques ne contiennent plus que le protocole, les contraintes et instructions. Les traps, plans, decisions et claims sont exclusivement dans le contexte dynamique MCP
-- **Bootstrap enrichi** : scan des workflows CI/CD, ADR, CONTRIBUTING, Docker, .env.example, branches actives et tags git
-- **Quick setup MCP** : `bclaw_setup` détecte le repo courant et propose un init rapide au lieu de forcer le scan multi-repo
-- **`brainclaw uninstall`** : nouvelle commande pour retirer brainclaw d'un projet (`--project`) ou d'une machine (`--machine`)
-- **Traps machine-scoped** : nouveau champ `platform_scope` sur les traps — les traps machine ne polluent plus les fichiers d'instructions statiques
-- **Init sans setup préalable** : `brainclaw init` crée automatiquement le user store si absent, plus besoin de `brainclaw setup` d'abord
-- **Docs réécrites** : intégrations, quickstart et README avec niveaux Full/Standard/Limited et matrice agent factuelle
+### v1.5.3
 
-### v0.9.10
+- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. 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. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
+- **Site facts contract** (umbrella `pln_7fdfd70d` sprint 0) — new `scripts/emit-site-facts.mjs` emits `dist/facts.{js,json}` from `MCP_TOOL_NAMES` + `ENTITY_NAMES` so the brainclaw-site (and any consumer) can pull live tool/entity counts at build time without forking the values into a hand-maintained config. The package `files` list ships `dist/facts.json`; build:cli runs the emitter as part of the chain.
 
-- **OpenCode** : détection et auto-config MCP workspace via `opencode.json`; l'export réutilise `AGENTS.md`
-- **Antigravity / Gemini CLI** : détection et export `gemini-md` vers `GEMINI.md`, avec MCP machine-level sous `.gemini/antigravity/mcp_config.json`
-- **Workflow export** : la doc export couvre désormais explicitement les nouveaux formats et fichiers générés
+### v1.5.2
 
-### v0.7.2
+- **Grammar fix: `bclaw_update` no longer silently drops patches** (trp#187, pln#500) — the canonical CRUD surface promised that `EntityRegistry.updatable` listed every patchable field, but the legacy impls behind the dispatch (`updatePlan`, `updateMemoryItem`) only handled a typed subset. A `as UpdatePlanInput` cast in `entity-operations.ts` masked the gap from TypeScript: callers passed `{text, tags, severity, …}`, validation accepted them, and the function bodies never read them. Empirically reproduced this session on `pln#359` (text+tags drop) and `trp#187` itself (severity drop). Fix adds a generic-patch escape-hatch (`patch?: Partial<…>`) on `UpdatePlanInput` and `UpdateMemoryInput`, applied via `Object.assign` after the typed fields so legacy CLI callers keep their behaviour. The dispatch in `entity-operations.ts` now passes the full patch through that escape-hatch for plan/decision/constraint/trap. `runtime_note`, `candidate`, and `cross_project_link` were already correct. New `tests/unit/entity-update-coverage.test.ts` is parametric: for every `(entity, field)` pair in `EntityRegistry.updatable`, create + patch + get + assert the field actually persisted (29 cases). Adding a new updatable field will require adding a coverage row, so the contract stays honest.
 
-- **UserPromptSubmit hook** : correction du format — `brainclaw context` (texte markdown) au lieu de `--json` pour injection correcte dans le contexte Claude Code
+### v1.5.1
 
-### v0.7.1
+- **Cross-project link CLI + grammar parity** (pln#454 step 2) — new `brainclaw link add/list/remove` subcommands and a stateless `cross_project_link` entity wired into the canonical CRUD verbs (`bclaw_create / find / get / update / remove`). The pain point was small (config.yaml is hand-editable) but the asymmetry — runtime cross-project signaling shipped, management UX did not — meant federation peers had no first-class affordance. Storage stays in `config.cross_project_links`; the entity is intentionally stateless (no transitions). Refs: `src/commands/link.ts`, `src/core/cross-project.ts` (new `addCrossProjectLink` / `removeCrossProjectLink`), `src/core/entity-registry.ts` (new `xpl` prefix), `src/core/entity-operations.ts` dispatch cases, `tests/unit/link.test.ts` + `tests/unit/cross-project-link-grammar.test.ts` (26 new cases).
+- **Agent registry pruned** (pln#454 step 1) — 8 synthetic profiles (antigravity, copilot-vscode, claude-opus, copilot-identity, copilot, claude-sonnet, visionnaire, copilot-codev) and 11 abandoned sessions archived under `.brainclaw/archive/agents/2026-05-07/`. The whitelist that survives matches `feedback_allowed_dispatch_agents.md`: `claude-code`, `codex`, `github-copilot`, plus `jberdah` (curator). Auto-re-registration in `detectAiAgent` is intentionally preserved — if a real surface starts a session, the registry auto-rebuilds for it. Pure store cleanup, no code change.
+- **Inbox + assignment lifecycle reconciliation** (housekeeping) — 89 stale inbox messages and 7 orphan offered-assignments closed with retroactive lifecycle updates. The plans they backed (pln#478 mcp self-heal, pln#480 multi-stack worktree, pln#483 bclaw_work compact, pln#471 tier-B live companions) had all merged weeks earlier without the dispatch path calling `bclaw_assignment_update`. Captured as `feedback_dispatch_test_inbox_debris` so future drift is mass-acked instead of triaged per-message.
 
-- **Cross-platform `npx` fix** : `brainclaw init` et `brainclaw export` ajoutent désormais brainclaw en `devDependency` du projet cible — `npx brainclaw` fonctionne dans les hooks Claude Code sans dépendre du PATH global (résout Windows WSL/Git Bash)
+### v1.5.0
 
-### v0.7.0
+- **Ideation loop MVP** (pln#492) — new `bclaw_coordinate(intent='ideate')` opens a memory-confrontation loop: critic reads only adversarial categories (traps + feedback + runtime_notes + critique_history) and gets a BM25-ranked, context-filtered, 12k-token-capped brief assembled from project memory. Single-agent (champion drives manually) or multi-agent (auto-dispatch a turn per critic). Iteration block (cycle, max_iterations, exit_when), phase-advance gate (≥3 critique artifacts before leaving critique), system events (`phase_advance_blocked`, `max_iterations_reached`). Full design: [docs/concepts/ideation-loop.md](docs/concepts/ideation-loop.md).
+- **Reliable dispatch + autonomy contract** (pln#496) — codex / sandboxed task-based agents now emit the full lifecycle (accepted → started → progress → completed). `briefMode` resolution corrected: `task-based && hasMcp → 'full'` (not 'compact', which silently dropped the protocol section). Lazy reconciliation pattern: `agentrun-reconciler` runs at every read path (`bclaw_assignment_events`, `bclaw_loop intent='get'`, `doctor --dispatch`) instead of a daemon; first run auto-recovered 9 historical orphan agent_runs in <1s. New autonomy contract section in instruction surfaces — agents execute protocol-defined transitions instead of pausing to ask. New `buildClaimEnvPrefix` consolidates cross-shell env injection (Windows defaults to cmd, POSIX uses unquoted bytes per PATH conventions). New `brainclaw doctor --dispatch` for operator-facing dispatch health.
+- **Worktree junction wipe fix** (pln#498) — `detachWorktreeJunctions` runs before `git worktree remove` on Windows so git's recursive rm cannot follow the `node_modules` junction back into the main repo. Closes the recurring post-merge wipe trap; validated empirically on multiple back-to-back merges in the v1.5.0 session.
+- **Methodological lessons** captured as user auto-memory feedback memos: bisect historical state before bisecting code (regression vs. always-broken-but-hidden), lazy reconcile at read paths beats daemon polling, codex briefs MUST include the Protocol section (implicit instructions don't propagate to sandboxed CLIs).
 
-- **Claude Code** : intégration native complète — MCP (`.mcp.json`), slash command (`.claude/commands/brainclaw.md`), hooks de session (`UserPromptSubmit` + `Stop`) dans `.claude/settings.local.json`
-- **Cursor** : config MCP machine-level (`~/.cursor/mcp.json`) ajoutée à l'auto-config
-- **Roo Code** : config MCP workspace (`.roo/mcp.json`)
-- **Continue** : config MCP workspace (`.continue/config.json`, format array)
-- **Hygiene section** renforcée : workflow plan/claim/session-end inclus dans toutes les instructions générées
-- **Canal de mise à jour local** (`brainclaw version --publish-local`) : tarball + manifeste `.releases/`
+### v1.2.0
 
----
+- **zod 3 → 4 migration** (pln#486) — schemas are semantically equivalent but the JSON Schema emitted by `tools/list` shifted shape; downstream MCP clients that snapshot schemas should re-pin. See `docs/mcp-schema-changelog.md` for the public surface fingerprint.
+
+### v1.1.0
+
+- **Node 20+ baseline** (pln#485) — `engines.node` is now `>=20.0.0` (Node 18 reached EOL in April 2025). CI matrix runs Node 20, 22, and 24 on Linux; Windows on Node 24.
+- **commander 13 → 14** (requires Node 20+).
+- **@types/node 22 → 24** (LTS-aligned).
+
+### v1.0.15
+
+- **TypeScript 5.8 → 6.0** (pln#484) — migration to `module: "nodenext"` (`Node16` is deprecated in TS 6, scheduled for removal in TS 7); explicit `types: ["node"]` since TS 6 changed the default to `[]`.
 
-## License
+### v1.0.14
 
-Current releases of brainclaw are published under the [Business Source License 1.1](LICENSE) — © 2024-2026 Juan Berdah.
+- **`bclaw_work` compact payload by default** (pln#483) — avoids exceeding the ~25k MCP token cap on projects with substantial memory. Pass `compact: false` for the full payload, or call `bclaw_context(kind="memory")` after.
+- **MCP runtime self-heal + `doctor --repair`** (pln#478) — when `dist/mcp-worker.js` is missing, the server logs an actionable repair pointer and read-only handlers keep serving in-process. `brainclaw doctor --repair` rebuilds dist in one step.
+- **Tier B/C native live companions** (pln#471) — `.cursor/live.md`, `.clinerules/live.md`, `.windsurf/rules/live.md`, `.github/copilot-instructions.live.md`, `.continue/live.md`, `GEMINI.live.md` regenerated on session-end and handoff. Opt-in via `brainclaw export --include-live --write`.
 
-The long-term direction is simpler than the current wording might suggest:
+### v1.0.13
 
-- the local-first brainclaw core is intended to move to MIT after the closed beta
-- cloud shared-memory, remote collaboration services, advanced dashboards, and related hosted add-ons will live in separate commercial products
+- **Worktree GC scope hardening** (pln#477) — `safeRemoveWorktreeDir` no longer follows symlinks/junctions during cleanup. Closes a class of post-merge wipes that previously destroyed `node_modules` and other neighboring directories on Windows.
+
+### v1.0.10–v1.0.12
+
+- **GitHub Copilot CLI is spawnable** (pln#440) — Copilot CLI 1.0.35+ supports `-p "<prompt>" --allow-all --no-ask-user`; tier promoted to A.
+- **Codex spawn on Windows: stdin pipe + 30s handshake TTL** (pln#475) — fixes embedded backticks/`#`/multi-line content getting mis-parsed by `cmd.exe` when a prompt is passed as an inline argument.
+- **Brief-ack file handshake** (pln#476) — `.brainclaw/coordination/runtime/ack/<assignmentId>.ack` proves a spawned worker started, decoupling the handshake from MCP availability inside the worker (important for Codex in `--sandbox workspace-write`).
+- **`bclaw_loop(intent="open")` orphan-gate** (pln#461) — refuses to open a loop without dispatch unless `allow_orphan: true` is explicit. Use `bclaw_coordinate(intent="review", open_loop: true)` instead.
+- **Kilocode** — Tier B integration with native MCP config and live companion (pln#464).
+
+### v1.0.0
+
+- **Canonical grammar promoted to standard tier** — `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition`, plus the entry facades `bclaw_work` and `bclaw_context`, the multi-agent facades `bclaw_coordinate` and `bclaw_dispatch`, and the loop facade `bclaw_loop`. Legacy per-entity tools removed from the discoverable surface (still callable as a migration escape hatch). See `docs/concepts/mcp-governance.md` for tier rules and the deprecation policy.
+
+---
 
-The intended MIT core covers what makes brainclaw useful inside a repo today: local project memory, local MCP and CLI coordination, onboarding and bootstrap, plans, claims, handoffs, runtime notes, and local agent integrations.
+## License
+
+brainclaw core is published under the [MIT License](LICENSE) — (c) 2024-2026 Juan Berdah.
+
+The licensing split is simple:
+
+- the local-first brainclaw core is MIT
+- cloud shared-memory, remote collaboration services, advanced dashboards, and related hosted add-ons will live in separate commercial products
+
+The MIT core covers what makes brainclaw useful inside a repo today: local project memory, local MCP and CLI coordination, onboarding and bootstrap, plans, claims, handoffs, runtime notes, and local agent integrations.
 
 The goal is not to close brainclaw down. The goal is to keep the local-first core open and genuinely useful on its own, while keeping hosted collaboration features separate.