brainclaw 0.19.12 → 0.20.0

package/docs/integrations/agents.md

@@ -1,182 +1,134 @@
-# Agent Integration Principles
-
-## Core reality
-
-No agent should be assumed to obey a single instruction perfectly every time.
-
-That means brainclaw integration should not rely on only one mechanism such as:
-
-- a single instruction file
-- a single skill
-- a single startup command
-
-## Better approach
-
-Use multiple points of contact:
-
-- lightweight system instructions
-- project-specific context retrieval through MCP when available
-- prompt-ready generated context
-- native agent files for local reminders
-- MCP tools for dynamic state
-- board and status views
-- workflow reminders around plans, claims, and handoffs
-
-## Surface hierarchy
-
-The default order is:
-
-1. MCP for live state
-2. native agent files for local workflow guidance
-3. readable files as fallback
-4. CLI for setup, operator tasks, scripting, and fallback workflows
-
-This keeps dynamic state dynamic instead of trying to encode it permanently into static instructions.
-
-## System instructions vs project instructions
-
-Keep these separate.
-
-### System instructions
-How the agent should use brainclaw.
-
-Examples:
-
-- check workspace memory before significant changes
-- prefer MCP over manual CLI calls when MCP is available
-- bootstrap if the workspace is not initialized and the workflow allows it
-- respect file claims
-- update shared plan status when appropriate
-
-### Project instructions
-What is true for the current workspace.
-
-Examples:
-
-- active constraints
-- recent decisions
-- known traps
-- current handoffs
-- relevant plan context
+# Agent Integration
 
-## Setting up agent integration
+## The problem brainclaw solves for agents
 
-### Automatic detection
+Coding agents are stateless. Each session starts from zero. They don't know:
 
-```bash
-brainclaw init
-```
-
-`setup` and `init` write the appropriate local agent config files for the detected integrations. Workspace-local generated files are also added to `.gitignore` automatically so agent-specific config does not pollute Git status.
+- what other agents have been working on
+- what files are being actively edited by someone else
+- what decisions were made last week and why
+- what traps to avoid in a specific part of the codebase
 
-### Manual per-agent setup
+Brainclaw gives every agent access to this shared context through a combination of surfaces adapted to what each agent can handle.
 
-```bash
-brainclaw enable-agent claude-code
-brainclaw enable-agent cursor
-brainclaw enable-agent windsurf
-brainclaw enable-agent opencode
-brainclaw enable-agent antigravity
-```
+## Multiple points of contact
 
-### Export to a specific format
+No single mechanism is enough. Agents don't always obey a single instruction file. They sometimes skip MCP calls. They forget between prompts.
 
-```bash
-brainclaw export --format claude-md --write
-brainclaw export --format cursor-rules --write
-brainclaw export --format agents-md --write   # Codex, OpenCode
-brainclaw export --format gemini-md --write   # Antigravity / Gemini CLI
-brainclaw export --format claude-md --write --shared   # only if you want the main instruction file versioned
-```
-
-`--detect` auto-selects formats based on files found in the workspace:
+That's why brainclaw uses every available surface:
 
-```bash
-brainclaw export --detect --write
-```
-
-By default, `--write` treats generated workspace files as local setup and adds them to `.gitignore`. `--shared` only keeps the main exported instruction file versionable; companion MCP/settings files remain local. OpenCode also gets a workspace MCP config in `opencode.json`. Antigravity/Gemini CLI gets a machine-local MCP config in `.gemini/antigravity/mcp_config.json` when `HOME` is available.
-
-If a repo already contains tracked local agent files from an older setup, `brainclaw session-start` warns at the beginning of work and `brainclaw doctor --fix-agent-ignore` can repair the missing `.gitignore` entries. Tracked files still need to be untracked manually with Git after the ignore rules are in place.
+1. **Instruction files** set the frame — "this project uses brainclaw, here's how"
+2. **Hooks** inject context automatically — the agent sees plans and claims without asking
+3. **MCP tools** provide on-demand access — the agent calls brainclaw when it needs more detail
+4. **Auto-approve** removes friction — no popup confirmation for each tool call
+5. **Skills/commands** give the developer a manual override — force a context refresh when needed
 
-## MCP server workflow
-
-The brainclaw MCP server exposes the dynamic Brainclaw workflow directly. For capable agents, this is the nominal runtime path.
+The more surfaces are active, the more reliably the agent uses brainclaw.
 
-### Starting the MCP server
+## What the instruction file contains
 
-```bash
-brainclaw mcp
-```
+The instruction file (CLAUDE.md, .cursor/rules/, AGENTS.md, etc.) is the agent's first contact with brainclaw. Its content depends on the agent's capabilities:
 
-Most agents pick this up via their MCP config file (`.mcp.json`, `~/.cursor/mcp.json`, etc.). brainclaw writes these during `init`.
-
-### Available MCP tools
-
-| Tool | Description |
-|------|-------------|
-| `bclaw_get_context` | Full workspace context (constraints, decisions, traps, plans, handoffs) |
-| `bclaw_get_agent_board` | Live plan + claim board |
-| `bclaw_session_start` | Start an agent session (registers identity) |
-| `bclaw_session_end` | End session, optionally auto-release claims |
-| `bclaw_claim` | Claim a file scope |
-| `bclaw_release_claim` | Release a claim |
-| `bclaw_create_candidate` | Create a plan item |
-| `bclaw_accept` / `bclaw_reject` | Accept or reject a plan candidate |
-| `bclaw_write_note` | Write a runtime note |
-| `bclaw_search` | Search memory entries |
-| `bclaw_read_handoff` | Read a handoff document |
-| `bclaw_bootstrap` | Initialize the workspace if not already done |
-| `bclaw_get_execution_context` | Get execution context (identity, claims, active plans) |
-
-## Session lifecycle
-
-### Starting a session
-
-```bash
-brainclaw session-start --agent my-agent --model claude-opus-4-5
-```
+### For agents with MCP and hooks (Claude Code)
 
-This registers the agent's identity and optionally records the model being used. Other agents can see active sessions in `list-claims` and `board`.
+Short and focused:
+- Why brainclaw matters for this project
+- The session protocol (hooks handle the rest)
+- Active constraints and instructions
+- Version check reminder
 
-### During the session
-
-For MCP-capable agents, prefer the MCP equivalents of these actions. The CLI examples below are the operator and fallback form of the same lifecycle.
+### For agents with MCP but no hooks (Cursor, Codex, OpenCode, etc.)
 
-```bash
-brainclaw context --json        # load fresh project state
-brainclaw claim list            # check for conflicts
-brainclaw claim create "desc" --scope src/feature/
-brainclaw plan create "implement X" --estimate 60
-brainclaw plan update <id> --status in_progress
-```
+More directive:
+- Same core sections as above, with stronger language ("REQUIRED", "MUST")
+- The top 5 most critical traps (the agent won't see them otherwise)
+- Explicit step-by-step protocol with all MCP calls listed
+
+### For agents without MCP (Copilot)
+
+Full static context:
+- All of the above
+- Active plans with status and assignees
+- All shared traps
+- Recent architectural decisions
+
+## Setting up agent integration
 
-### Ending the session
+### Automatic (recommended)
 
 ```bash
-brainclaw session-end --auto-release
+brainclaw setup     # machine-level: detects agents, creates global configs
+brainclaw init      # project-level: creates .brainclaw/, writes agent files
 ```
 
-This releases all active claims held by the current agent and updates plan statuses.
+Or ask your coding agent to do it:
 
-## Generated files are local-only
+```
+"Install and initialize brainclaw in this project"
+```
 
-Agent config files generated by brainclaw — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/brainclaw.md`, `.windsurfrules`, `.github/copilot-instructions.md` — are **not committed to Git**.
+The agent can use `bclaw_setup` to walk through the process interactively.
 
-Each developer regenerates them locally from their own `.brainclaw/` store:
+### Per-agent manual setup
+
+```bash
+brainclaw enable-agent claude-code
+brainclaw enable-agent cursor
+brainclaw export --format claude-md --write
+brainclaw export --detect --write          # auto-detect and write all formats
+```
+
+### Regenerating after changes
+
+When brainclaw memory changes (new constraints, resolved traps, updated plans), regenerate instruction files:
 
 ```bash
 brainclaw export --detect --write
 ```
 
+For agents without MCP (Copilot), this is especially important — the instruction file is their only source of project context.
+
+## Generated files are local
+
+Agent config files generated by brainclaw are **not committed to Git**. Each developer regenerates them locally from the shared `.brainclaw/` store.
+
 This ensures:
-- no private project notes leak into the shared repo
-- each developer's local agent sees the right instructions for their setup
-- instructions stay in sync with the current brainclaw store, not a stale committed version
+- No machine-specific traps leak into the shared repo
+- Each developer's agent sees instructions tailored to their setup
+- Instructions stay in sync with current memory, not a stale committed version
+
+brainclaw adds all generated files to `.gitignore` automatically during init.
+
+Exception: use `--shared` if you intentionally want the main instruction file (e.g., CLAUDE.md) versioned for the whole team.
+
+## Session lifecycle
+
+### Starting work
+
+```
+bclaw_session_start → identify yourself, see the board
+bclaw_get_context(target: "src/auth/") → load relevant memory
+bclaw_get_execution_context → check for brainclaw updates
+```
+
+### During work
+
+```
+bclaw_claim(scope: "src/auth/") → signal what you're editing
+bclaw_write_note("Found a race condition in AuthService") → record observations
+bclaw_create_plan("Fix race condition", estimate: 30) → track work
+```
+
+### Finishing work
+
+```
+bclaw_session_end(auto_release: true) → release claims, update plans
+```
+
+### Plans and estimation
 
-brainclaw adds all generated files to `.gitignore` automatically during `init`.
+Always estimate duration in minutes when creating a plan or step. When completing, report actual effort. This builds a calibration history that helps improve future estimates — agents are typically poor at estimation, and this feedback loop helps.
 
-## Goal
+## Version awareness
 
-The goal is not perfect enforcement.
-The goal is to make brainclaw the natural path for fresh workspace context and coordination.
+Agents should call `bclaw_get_execution_context` at session start. If a newer brainclaw version is available, it tells the agent, who can then inform the developer and suggest updating. Updates may include new features, new MCP tools, and improved coordination.

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,152 +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.
-
-### Agent runtime pattern
+`init` creates the user store if needed (no separate `setup` step required), initializes the project, detects your agent, and writes all integration files.
 
-After the workspace is initialized, the nominal flow is:
+## What happens after init
 
-```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
-```
+Once initialized, your agent can:
 
-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.
+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
 
-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.
+## For agents with MCP (most agents)
 
-## Path 2: CLI-Oriented Agent Or Fallback Workflow
+This is the primary path. The agent calls brainclaw tools directly.
 
-Use this path when the agent does not have a good MCP integration yet, or when a human needs to drive the workflow 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
+Instruction files like `CLAUDE.md` or `.cursor/rules/brainclaw.md` provide the protocol and constraints. The live state (plans, claims, traps) comes through MCP.
 
-```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
-```
+## For agents without MCP (Copilot)
 
-### Create and claim work
+The instruction file (`.github/copilot-instructions.md`) contains everything: constraints, active plans, traps, and decisions. Use the brainclaw-context skill to refresh.
 
-```bash
-brainclaw plan create "Coordinate auth rollout" --priority high
-brainclaw claim create "Take auth rollout" --scope src/auth/
-```
-
-### 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 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
-```
+## Onboarding an existing project
 
-### Fill the gaps
+If the repo already has code, brainclaw can extract context from it:
 
 ```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": []
-  }
-]
+brainclaw bootstrap --json        # see what brainclaw detected
+brainclaw bootstrap --apply       # import into memory
 ```
 
-Preview the enriched import proposal:
+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 bootstrap --answers-file ./bootstrap-answers.json --json
-```
+## Desktop AI surfaces
 
-### Apply or rollback managed imports
+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 bootstrap --answers-file ./bootstrap-answers.json --apply
-brainclaw bootstrap --uninstall
+brainclaw surface-task create "Generate hero visual" --target chatgpt --kind visual_asset
+brainclaw surface-task list
 ```
 
-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.12",
+  "version": "0.20.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {