brainclaw 0.19.14 → 0.20.0

package/docs/integrations/overview.md

@@ -1,74 +1,100 @@
 # Integration Overview
 
-Brainclaw is designed to work with existing coding agents, not replace them.
+Brainclaw works alongside your existing coding agents. It does not replace them — it gives them a shared memory and coordination layer they can all read from and write to.
 
-The key integration rule is simple:
+## How agents connect to brainclaw
 
-1. use MCP for dynamic shared state when the agent supports it
-2. use native agent files for local behavioral guidance
-3. use the CLI for setup, operator workflows, scripting, and fallback access
+Brainclaw reaches each agent through multiple surfaces. Not every agent supports every surface, and that's fine — brainclaw adapts what it writes based on what the agent can handle.
 
-## Current Limitation
+| Surface | What it does | When it activates |
+|---|---|---|
+| **MCP tools** | The agent calls brainclaw directly to read context, create plans, claim files, and coordinate. This is the richest integration. | During every prompt, when the agent decides to call a tool |
+| **Instruction file** | A markdown file in the agent's native format that explains how to use brainclaw and lists active project constraints. | Read once at session start |
+| **Hooks** | Brainclaw injects fresh context into the agent's prompt automatically, without the agent asking. | Every prompt (where supported) |
+| **Auto-approve** | MCP tool calls are pre-approved so the agent doesn't have to ask the developer for permission each time. | Every MCP call (where supported) |
+| **Skills / Commands** | A shortcut the developer can trigger manually to refresh brainclaw context. | On demand |
 
-For now, Brainclaw should be used for sequential multi-agent collaboration, not true parallel editing in the same checkout.
+## What goes where: core vs run
 
-One agent can hand work to another, and the next agent can recover good project context through shared memory, plans, claims, and handoffs. But without dedicated Git worktrees per agent/session, running several coding agents concurrently on the same project checkout is still risky and can create conflicts or unstable local state.
+Instruction files contain **core** content — things that don't change between prompts:
 
-## Integration Surfaces
+- Why brainclaw matters for this project
+- The session protocol (what to call and when)
+- Active constraints
+- Project instructions
 
-brainclaw can integrate through several surfaces, but they do not have the same role.
+Everything else is **run** content — it changes constantly and belongs in the dynamic context delivered through MCP or hooks:
 
-| Surface | Role |
-|---|---|
-| **MCP tools** | primary dynamic access path for context, plans, claims, board views, and runtime writes |
-| **Native agent files** | local guidance in the agent's own surface: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/brainclaw.md`, `.windsurfrules`, etc. |
-| **Readable files** | fallback readable state such as `.brainclaw/project.md` |
-| **CLI commands** | setup, scripting, release, inspection, and fallback workflows |
-| **System/project instructions** | static reminders about how Brainclaw should be used in this workspace |
+- Active plans and their status
+- Who is working where (claims)
+- Known traps (scored by relevance to the current file)
+- Handoffs between agents
+- Runtime notes
 
-## Recommended Pattern
+This separation keeps instruction files clean and focused. The agent gets the stable rules from the file and the live state from MCP.
 
-A good default pattern is:
+## Three levels of integration
 
-1. give the agent lightweight static instructions about how to use Brainclaw
-2. let it retrieve fresh workspace state through MCP before significant edits
-3. rely on plans, claims, and handoffs during execution
-4. keep native files and readable project state available as fallback context
-5. use hooks or repeated reminders where the host surface supports them
+Brainclaw adapts its instruction file content based on what each agent can do:
 
-## Native Files Are Support, Not The Live Source Of Truth
+### Full integration (MCP + hooks)
 
-Generated files such as `CLAUDE.md` or `.cursor/rules/brainclaw.md` are useful because they keep Brainclaw visible inside the agent surface already in use.
+The agent gets dynamic context injected at every prompt. The instruction file can be lightweight — just the protocol and constraints. Everything else comes through hooks and MCP calls.
 
-They are not meant to replace:
+**Today:** Claude Code
 
-- fresh context retrieval
-- live board state
-- current claims
-- recent runtime notes
-- current handoffs
+### Standard integration (MCP, no hooks)
 
-For those, use MCP when available.
+The agent can call brainclaw tools but doesn't get automatic context injection. The instruction file is more directive — it tells the agent it MUST call specific tools before working, and includes the most critical traps statically.
 
-## Getting The Native File Written Automatically
+**Today:** Cursor, Windsurf, Cline, Roo, Continue, OpenCode, Codex, Antigravity/Gemini CLI
 
-Run `brainclaw init` and Brainclaw will detect the current agent surface and write the appropriate local file automatically.
+### Limited integration (no MCP)
 
-That includes OpenCode (`AGENTS.md` + `opencode.json`) and Antigravity/Gemini CLI (`GEMINI.md` + machine-local MCP config) when those environments are present.
+The agent cannot call brainclaw tools at all. The instruction file becomes the only source of project context, so it includes everything: constraints, traps, active plans, recent decisions.
 
-Or at any time:
+**Today:** GitHub Copilot (uses skills as a partial workaround)
 
-```bash
-brainclaw export --detect --write
-```
+## Agent integration matrix
 
-By default, generated workspace files are treated as local setup and added to `.gitignore`. `--shared` should only be used when you intentionally want the main exported instruction file to be versioned.
+| 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 | — | — |
+| **Cline** | ✔ project | .clinerules/ | — | ✔ autoApprove | — |
+| **Roo** | ✔ project | .roo/rules/ | — | ✔ alwaysAllow | — |
+| **Continue** | ✔ both | .continue/rules/ | — | — | — |
+| **OpenCode** | ✔ project | AGENTS.md | — | — | — |
+| **Codex** | ✔ global | AGENTS.md | — | — | — |
+| **Gemini CLI** | ✔ global | GEMINI.md | — | — | — |
+| **Copilot** | — | .github/copilot-instructions.md | — | — | ✔ brainclaw-context |
 
-## Choose Your Next Page
+**Legend:** ✔ = fully supported, ◐ = partial (static trigger, not dynamic injection), — = not available
 
-- [mcp.md](mcp.md) — the nominal path for capable agents
-- [agents.md](agents.md) — integration principles that apply to every agent
+## Why maximum integration by default
+
+Without active pressure, agents ignore brainclaw. This is a consistent finding from real usage: if brainclaw only declares an MCP server and doesn't push the agent to use it, the agent never calls it.
+
+That's why brainclaw activates **all available surfaces** by default during setup:
+
+- The MCP server and instruction file are always configured (non-negotiable)
+- Auto-approve and hooks are enabled where supported (opt-out possible)
+- The instruction file includes a "why this matters" section so the agent understands why it should care
+
+The developer can dial back individual surfaces if needed, but the default is full integration because that's what works.
+
+## Sequential collaboration, not parallel editing
+
+For now, brainclaw works best when one agent works at a time in a given checkout. The next agent can pick up where the previous one stopped, using shared plans, claims, handoffs, and memory.
+
+Running multiple agents in parallel on the same checkout will create conflicts. Git worktree isolation per agent is planned but not yet available.
+
+## Next reads
+
+- [mcp.md](mcp.md) — the dynamic runtime path for capable agents
+- [agents.md](agents.md) — integration principles and setup details
 - [claude-code.md](claude-code.md)
-- [codex.md](codex.md)
 - [cursor.md](cursor.md)
+- [codex.md](codex.md)
 - [copilot.md](copilot.md)

package/docs/quickstart.md

@@ -1,189 +1,85 @@
 # Quickstart
 
-This guide is organized by entry path, because Brainclaw serves different surfaces with different roles.
+## The fastest way to start
 
-Use this rule first:
+Ask your coding agent:
 
-- capable agent with MCP support: prefer MCP for dynamic state
-- agent surface driven mainly by local instruction files: use generated native files plus CLI fallback
-- human operator or maintainer: use the CLI directly
+> "Install brainclaw and initialize it in this project."
 
-## Important limitation for now
+The agent will run `brainclaw setup` and `brainclaw init`, detect your environment, write the right config files, and activate MCP. After reloading, brainclaw tools become available.
 
-Do not run multiple coding agents in parallel on the same project checkout yet.
-
-Brainclaw is already useful for sequential collaboration: one agent can pick up where another stopped, inspect shared context, and continue from explicit plans, claims, traps, and handoffs. But until Brainclaw supports dedicated Git worktrees per agent/session, parallel edits in the same checkout are still likely to create more Git and workspace problems than they solve.
-
-For now, prefer:
-
-1. one active editing agent per checkout
-2. explicit handoffs between agents
-3. claims and context to keep continuity between sessions
-
-## Path 1: Agent-First With MCP
-
-Use this path when the agent can call Brainclaw through MCP.
-
-### Operator bootstrap
+If you prefer doing it manually:
 
 ```bash
-brainclaw setup --yes
+npm install -g brainclaw
 brainclaw init
 ```
 
-`setup` installs machine-level prerequisites and agent integrations. `init` creates the workspace state, seeds stable identity, and prepares the project memory structure.
+`init` creates the user store if needed (no separate `setup` step required), initializes the project, detects your agent, and writes all integration files.
 
-### Agent runtime pattern
+## What happens after init
 
-After the workspace is initialized, the nominal flow is:
+Once initialized, your agent can:
 
-```text
-bclaw_session_start   -> open a session and return current board/context
-bclaw_get_execution_context -> inspect local tooling and notice package updates
-bclaw_get_context     -> fetch fresh prompt-ready context for the target path
-bclaw_list_plans      -> inspect active work
-bclaw_claim           -> claim scope before editing
-bclaw_write_note      -> record runtime observations
-bclaw_session_end     -> close session cleanly and hand work off
-```
-
-Use native agent files such as `AGENTS.md`, `CLAUDE.md`, or Cursor rules as local workflow guidance, not as the only source of live state.
-
-Unless the project overrides `brainclaw_update_source`, `bclaw_get_execution_context` checks the public npm `latest` channel so the agent can notice when a newer Brainclaw release is available.
+1. **See project context** — constraints, decisions, traps, plans, handoffs
+2. **Coordinate with other agents** — claim files before editing, check who's working where
+3. **Build shared memory** — record observations, create plans, track work
+4. **Resume across sessions** — the next agent (or the same one tomorrow) picks up where you left off
 
-## Path 2: CLI-Oriented Agent Or Fallback Workflow
+## For agents with MCP (most agents)
 
-Use this path when the agent does not have a good MCP integration yet, or when a human needs to drive the workflow directly.
+This is the primary path. The agent calls brainclaw tools directly.
 
-### Bootstrap and inspect
-
-```bash
-brainclaw setup --yes
-brainclaw init
-brainclaw export --detect --write
+```text
+bclaw_session_start   → identify yourself, see the board
+bclaw_get_context     → load relevant memory for your target scope
+bclaw_claim           → signal what you're about to edit
+bclaw_write_note      → record observations during work
+bclaw_session_end     → clean up claims and update plans
 ```
 
-### Record the first important facts
-
-```bash
-brainclaw memory create decision "OAuth migration now goes through auth-gateway" --tag auth
-brainclaw memory create constraint "Payments module frozen until 2026-04-01" --tag payments
-brainclaw memory create trap "Checkout E2E tests are flaky on Windows" --severity high --tag tests
-```
+Instruction files like `CLAUDE.md` or `.cursor/rules/brainclaw.md` provide the protocol and constraints. The live state (plans, claims, traps) comes through MCP.
 
-### Create and claim work
+## For agents without MCP (Copilot)
 
-```bash
-brainclaw plan create "Coordinate auth rollout" --priority high
-brainclaw claim create "Take auth rollout" --scope src/auth/
-```
+The instruction file (`.github/copilot-instructions.md`) contains everything: constraints, active plans, traps, and decisions. Use the brainclaw-context skill to refresh.
 
-### Refresh context before edits
+Regenerate the instruction file when project memory changes:
 
 ```bash
-brainclaw context --for src/auth/routes.ts --digest
-brainclaw status
+brainclaw export --detect --write
 ```
 
-Claims reduce collisions, but they are not a substitute for isolated worktrees yet. Use them mainly to coordinate sequential work or human/agent awareness in the same repo.
-
-## Path 2.5: Desktop AI Work Surfaces Around The Repo
-
-Use this path when the active coding agent should stay focused on code, but the project could benefit from another local AI surface on the same machine, such as ChatGPT Desktop or Claude Desktop.
-
-Typical use cases:
-
-- visual asset generation
-- polished copy or release-note drafting
-- synthesis for operators or stakeholders
-- side research that should not consume the coding agent's main context window
+## Onboarding an existing project
 
-### Discover what is available on the machine
+If the repo already has code, brainclaw can extract context from it:
 
 ```bash
-brainclaw machine-profile --refresh
+brainclaw bootstrap --json        # see what brainclaw detected
+brainclaw bootstrap --apply       # import into memory
 ```
 
-### Queue work for another local AI surface
+Or let your agent drive the conversation — it can call `bclaw_bootstrap`, review the detected signals, ask you about gaps, and structure the results into brainclaw memory.
 
-```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 \
-  --path src/pages/Home.tsx
-```
+## Desktop AI surfaces
 
-### Review queued work later
+brainclaw can also track work for desktop AI tools on your machine (ChatGPT Desktop, Claude Desktop, Gemini CLI) as a project-scoped task queue:
 
 ```bash
+brainclaw surface-task create "Generate hero visual" --target chatgpt --kind visual_asset
 brainclaw surface-task list
-brainclaw surface-task list --all --target chatgpt
-```
-
-This queue does not automate the target desktop app yet. It gives the project a clean place to stage work that another local AI surface should pick up during its next session.
-
-## Path 3: Brownfield Onboarding
-
-Use this path when you are adopting Brainclaw into an existing workspace and do not want to hand-author all memory from scratch.
-
-### Build the initial bootstrap view
-
-```bash
-brainclaw setup --yes
-brainclaw init
-brainclaw bootstrap --json
-```
-
-### Fill the gaps
-
-```bash
-brainclaw bootstrap --interview --audience cli
-brainclaw bootstrap --interview --audience ide_chat
-```
-
-Use the returned question IDs to prepare a small JSON answers file when the interview needs to confirm durable memory:
-
-```json
-[
-  {
-    "question_id": "biq_example",
-    "response_items": ["Use agents sequentially in one checkout."],
-    "suggestions": []
-  }
-]
-```
-
-Preview the enriched import proposal:
-
-```bash
-brainclaw bootstrap --answers-file ./bootstrap-answers.json --json
-```
-
-### Apply or rollback managed imports
-
-```bash
-brainclaw bootstrap --answers-file ./bootstrap-answers.json --apply
-brainclaw bootstrap --uninstall
 ```
 
-Use this path when the repo already has native instruction files, partial docs, or conventions that Brainclaw should adopt selectively instead of replacing blindly.
+This keeps non-code work visible to the project without overloading the active coding agent.
 
-## Recommended First Workflow
+## Important: one agent at a time
 
-1. initialize the workspace
-2. choose the correct entry path for your surface
-3. record or import 3-5 high-signal facts
-4. create one shared plan
-5. claim scope before editing
-6. refresh context before significant edits
-7. hand off explicitly when switching between agents
+For now, use brainclaw for sequential collaboration. One agent works, finishes, and the next one picks up from shared context. Running multiple agents in parallel on the same checkout will cause conflicts.
 
-## Next Reads
+## Next reads
 
-- [integrations/overview.md](integrations/overview.md) — integration model by surface
-- [integrations/mcp.md](integrations/mcp.md) — nominal dynamic path for capable agents
-- [cli.md](cli.md) — operator and fallback reference
-- [concepts/memory.md](concepts/memory.md)
-- [concepts/plans-and-claims.md](concepts/plans-and-claims.md)
+- [integrations/overview.md](integrations/overview.md) — how brainclaw adapts to each agent
+- [integrations/mcp.md](integrations/mcp.md) — the dynamic runtime path
+- [concepts/memory.md](concepts/memory.md) — what project memory includes
+- [concepts/plans-and-claims.md](concepts/plans-and-claims.md) — coordination layer
+- [cli.md](cli.md) — full CLI reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.19.14",
+  "version": "0.20.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {