brainclaw 0.23.1 → 0.25.3

package/dist/core/bootstrap.js

@@ -4,7 +4,8 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { JsonStore } from './json-store.js';
 import { generateId, generateIdWithLabel, nowISO } from './ids.js';
-import { memoryPath, resolveEntityDir, withStoreLock, writeFileAtomic } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { BootstrapApplicationReceiptSchema, BootstrapInterviewAnswerSchema, BootstrapInterviewPlanSchema, BootstrapInterviewQuestionSchema, BootstrapImportPlanDocumentSchema, BootstrapProfileDocumentSchema, BootstrapSuggestionDocumentSchema, MemorySeedDocumentSchema, } from './schema.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { analyzeRepository } from './repo-analysis.js';
@@ -13,7 +14,7 @@ import { buildAgentToolingContext } from './agent-context.js';
 import { createInstruction, loadInstructions, saveInstruction } from './instructions.js';
 import { resolveCurrentAgentName } from './agent-registry.js';
 import { loadState, persistState } from './state.js';
-import { generateMarkdown } from './markdown.js';
+import { rebuildProjectMd } from './markdown.js';
 const README_CANDIDATES = ['README.md', 'README', 'README.txt', 'README.mdx'];
 const DOC_HINTS = ['docs', 'doc'];
 const MAKEFILE_NAME = 'Makefile';
@@ -1241,7 +1242,7 @@ export function applyBootstrapImport(options = {}) {
     const managedArtifacts = [];
     let createdCount = 0;
     let skippedCount = 0;
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         const state = loadState(cwd);
         const activeInstructionKeys = new Set(loadInstructions(cwd)
             .filter((entry) => entry.active)
@@ -1380,7 +1381,7 @@ export function applyBootstrapImport(options = {}) {
             persistState(state, cwd, { writeProjectMarkdown: false });
         }
         if (createdCount > 0) {
-            writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(loadState(cwd), cwd));
+            rebuildProjectMd(loadState(cwd), cwd);
         }
     });
     const receipt = BootstrapApplicationReceiptSchema.parse({
@@ -1414,7 +1415,7 @@ export function uninstallBootstrapImport(cwd) {
     let deactivatedCount = 0;
     let deletedCount = 0;
     let skippedCount = 0;
-    withStoreLock(resolvedCwd, () => {
+    mutate({ cwd: resolvedCwd }, () => {
         const state = loadState(resolvedCwd);
         const instructions = loadInstructions(resolvedCwd);
         let stateChanged = false;
@@ -1459,7 +1460,7 @@ export function uninstallBootstrapImport(cwd) {
             persistState(state, resolvedCwd, { writeProjectMarkdown: false });
         }
         if (deactivatedCount > 0 || deletedCount > 0) {
-            writeFileAtomic(memoryPath('project.md', resolvedCwd), generateMarkdown(loadState(resolvedCwd), resolvedCwd));
+            rebuildProjectMd(loadState(resolvedCwd), resolvedCwd);
         }
     });
     const nextReceipt = BootstrapApplicationReceiptSchema.parse({

package/dist/core/candidates.js

@@ -2,7 +2,8 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { CandidateSchema } from './schema.js';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { nowISO, getNextShortLabel } from './ids.js';
 import { JsonStore } from './json-store.js';
 function inboxDir(cwd, mode = 'read') {
@@ -35,7 +36,7 @@ function candidateStore(dest = 'pending', cwd) {
     });
 }
 export function saveCandidate(candidate, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureInboxDirs(cwd);
         candidateStore('pending', cwd).save(CandidateSchema.parse(candidate));
     });
@@ -51,7 +52,7 @@ export function listCandidates(status, cwd) {
     return status ? candidates.filter((candidate) => candidate.status === status) : candidates;
 }
 export function archiveCandidate(candidate, dest, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureInboxDirs(cwd);
         candidateStore(dest, cwd).save(CandidateSchema.parse(candidate));
         candidateStore('pending', cwd).delete(candidate.id);

package/dist/core/claims.js

@@ -1,7 +1,8 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import { ClaimSchema } from './schema.js';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { nowISO } from './ids.js';
 import { JsonStore } from './json-store.js';
 function claimsDir(cwd, mode = 'read') {
@@ -22,7 +23,7 @@ function claimStore(cwd) {
     });
 }
 export function saveClaim(claim, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureClaimsDir(cwd);
         const writeStore = new JsonStore({
             dirPath: claimsDir(cwd, 'write'),

package/dist/core/instructions.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { generateId } from './ids.js';
 import { InstructionEntrySchema } from './schema.js';
 import { JsonStore } from './json-store.js';
@@ -19,7 +20,7 @@ export function loadInstructions(cwd) {
     return instructionStore(cwd).list();
 }
 export function saveInstruction(entry, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         instructionStore(cwd, 'write').save(InstructionEntrySchema.parse(entry));
     });
 }

package/dist/core/io.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { withLock, cleanStaleLocks } from './lock.js';
+export { mutate } from './mutation-pipeline.js';
 export const MEMORY_DIR = '.brainclaw';
 const STORE_LOCK_BASENAME = '.store-mutation';
 const RETRYABLE_RENAME_ERROR_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);

package/dist/core/lock.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_TIMEOUT_MS = 5000;
 const LOCK_RETRY_INTERVAL_MS = 50;
-const LOCK_EXPIRY_MS = 5000;
+const LOCK_EXPIRY_MS = 10000;
 const heldLocks = new Map();
 function lockFilePath(targetPath) {
     return targetPath + '.lock';

package/dist/core/markdown.js

@@ -1,6 +1,8 @@
 import { listClaims } from './claims.js';
 import { loadInstructions } from './instructions.js';
+import { memoryPath, writeFileAtomic } from './io.js';
 import { isTrapActive } from './traps.js';
+import { logger } from './logger.js';
 export function generateMarkdown(state, cwd) {
     const lines = ['# Project Memory', ''];
     const instructions = loadInstructions(cwd).filter((entry) => entry.active);
@@ -117,4 +119,20 @@ export function generateMarkdown(state, cwd) {
     lines.push('');
     return lines.join('\n');
 }
+/**
+ * Rebuild `.brainclaw/project.md` from canonical state.
+ *
+ * This is a **derived view** — it can always be regenerated from the
+ * canonical JSON files. Call this once at the end of a top-level mutation,
+ * not inside every nested helper. Best-effort: failures are logged but
+ * never propagate to the caller.
+ */
+export function rebuildProjectMd(state, cwd) {
+    try {
+        writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(state, cwd));
+    }
+    catch (err) {
+        logger.debug('Failed to rebuild project.md:', err);
+    }
+}
 //# sourceMappingURL=markdown.js.map

package/dist/core/mutation-pipeline.js

@@ -0,0 +1,39 @@
+/**
+ * Mutation pipeline — single entry point for all .brainclaw/ store mutations.
+ *
+ * Every write operation against the store MUST go through `mutate()`.
+ * This ensures:
+ *   1. Store-wide serialization via the advisory file lock
+ *   2. Consistent error handling and timeout behavior
+ *   3. Observable mutation metadata for debugging and auditing
+ *
+ * @module
+ */
+import { ensureMemoryDir, storeLockPath } from './io.js';
+import { withLock } from './lock.js';
+import { logger } from './logger.js';
+/** Default timeout for store-wide lock acquisition (ms). */
+export const STORE_LOCK_TIMEOUT_MS = 5_000;
+export function mutate(optionsOrFn, maybeFn) {
+    const options = typeof optionsOrFn === 'function' ? {} : optionsOrFn;
+    const fn = typeof optionsOrFn === 'function' ? optionsOrFn : maybeFn;
+    const cwd = options.cwd ?? process.cwd();
+    const timeoutMs = options.timeoutMs ?? STORE_LOCK_TIMEOUT_MS;
+    ensureMemoryDir(cwd, options.preferredDirName);
+    const lockTarget = storeLockPath(cwd, options.preferredDirName);
+    const start = performance.now();
+    try {
+        const value = withLock(lockTarget, () => fn(cwd), timeoutMs);
+        const durationMs = performance.now() - start;
+        if (durationMs > 1_000) {
+            logger.debug(`Slow mutation: ${durationMs.toFixed(0)}ms (cwd=${cwd})`);
+        }
+        return value;
+    }
+    catch (err) {
+        const durationMs = performance.now() - start;
+        logger.debug(`Mutation failed after ${durationMs.toFixed(0)}ms: ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+    }
+}
+//# sourceMappingURL=mutation-pipeline.js.map

package/dist/core/runtime.js

@@ -2,7 +2,8 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveCurrentHostId, sanitizeHostId } from './host.js';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { RuntimeNoteSchema } from './schema.js';
 import { commitMemoryChange } from './memory-git.js';
@@ -40,7 +41,7 @@ export function saveRuntimeNote(note, cwd) {
     const persistedNote = visibility === 'shared'
         ? { ...note, visibility, host_id: hostId }
         : { ...note, visibility, host_id: hostId };
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureRuntimeDir(note.agent, cwd, visibility, hostId);
         const filepath = visibility === 'shared'
             ? path.join(sharedAgentDir(note.agent, cwd, 'write'), `${note.id}.json`)
@@ -58,7 +59,7 @@ export function runtimeNotePath(note, cwd) {
         : path.join(hostAgentDir(visibility, hostId, note.agent, cwd), `${note.id}.json`);
 }
 export function deleteRuntimeNote(note, cwd) {
-    return withStoreLock(cwd, () => {
+    return mutate({ cwd }, () => {
         const filepath = runtimeNotePath(note, cwd);
         if (!fs.existsSync(filepath)) {
             return false;

package/dist/core/schema.js

@@ -164,6 +164,7 @@ export const InstructionEntrySchema = z.object({
     created_at: z.string(),
     updated_at: z.string(),
     author: z.string(),
+    model: z.string().optional(),
     tags: z.array(z.string()).default([]),
     active: z.boolean().default(true),
     supersedes: z.string().optional(),
@@ -184,6 +185,7 @@ export const ProjectCapabilitySchema = z.object({
     created_at: z.string(),
     author: z.string(),
     author_id: z.string().optional(),
+    model: z.string().optional(),
 });
 export const ToolTypeSchema = z.enum(['workflow', 'validator', 'generator', 'utility', 'explorer']);
 export const ProjectToolSchema = z.object({
@@ -204,6 +206,7 @@ export const ProjectToolSchema = z.object({
     created_at: z.string(),
     author: z.string(),
     author_id: z.string().optional(),
+    model: z.string().optional(),
 });
 // --- State schema ---
 export const StateSchema = z.object({
@@ -258,6 +261,7 @@ export const CandidateSchema = z.object({
     created_at: z.string(),
     author: z.string(),
     author_id: z.string().optional(),
+    model: z.string().optional(),
     project_id: z.string().optional(),
     host_id: z.string().optional(),
     session_id: z.string().optional(),
@@ -326,6 +330,7 @@ export const ClaimSchema = z.object({
     status: ClaimStatusSchema,
     released_at: z.string().optional(),
     expires_at: z.string().optional(),
+    model: z.string().optional(),
 });
 // --- Runtime notes schemas ---
 export const RuntimeNoteSchema = z.object({
@@ -344,6 +349,7 @@ export const RuntimeNoteSchema = z.object({
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
     note_type: z.enum(['observation', 'session_start', 'session_end']).default('observation'),
+    model: z.string().optional(),
 });
 // --- AI surface task request schemas ---
 export const AiSurfaceTaskStatusSchema = z.enum(['queued', 'in_progress', 'completed', 'cancelled', 'failed']);
@@ -369,6 +375,7 @@ export const AiSurfaceTaskRequestSchema = z.object({
     claimed_at: z.string().optional(),
     completed_at: z.string().optional(),
     result_note: z.string().optional(),
+    model: z.string().optional(),
 });
 // --- Runtime event schemas ---
 export const RuntimeEventTypeSchema = z.enum([
@@ -398,6 +405,7 @@ export const RuntimeEventSchema = z.object({
     to: z.string().optional(),
     related_paths: z.array(z.string()).optional(),
     metadata: z.record(z.unknown()).optional(),
+    model: z.string().optional(),
 });
 // --- Profile schema ---
 export const ProfileSchema = z.enum(['dev', 'openclaw', 'ops', 'research']);

package/dist/core/state.js

@@ -1,11 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ConstraintSchema, DecisionSchema, TrapSchema, HandoffSchema, PlanItemSchema } from './schema.js';
-import { ensureMemoryDir, memoryPath, resolveEntityDir, withStoreLock, writeFileAtomic } from './io.js';
+import { ensureMemoryDir, resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { commitMemoryChange } from './memory-git.js';
 import { appendEvent } from './event-log.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
-import { generateMarkdown } from './markdown.js';
+import { rebuildProjectMd } from './markdown.js';
 export function emptyState() {
     return {
         version: 1,
@@ -83,10 +84,10 @@ function writeStateDirectories(state, cwd) {
 }
 export function persistState(state, cwd, options = {}) {
     const effectiveCwd = cwd ?? process.cwd();
-    withStoreLock(effectiveCwd, () => {
+    mutate({ cwd: effectiveCwd }, () => {
         writeStateDirectories(state, effectiveCwd);
         if (options.writeProjectMarkdown ?? true) {
-            writeFileAtomic(memoryPath('project.md', effectiveCwd), generateMarkdown(state, effectiveCwd));
+            rebuildProjectMd(state, effectiveCwd);
         }
         appendEvent({
             action: options.eventAction ?? 'update',

package/docs/cli.md

@@ -86,7 +86,7 @@ brainclaw setup --roots ~/Projects,~/work --agents all  # all agents, multiple r
 
 ### `brainclaw init`
 
-Initialize workspace state for the current project root. Detects the AI agent environment and writes to its native instruction file. `brainclaw setup` must have been run first on this machine. Do not run `init` from inside `.brainclaw/`; that directory is Brainclaw's own memory store, not a project root.
+Initialize workspace state for the current project root. Detects the AI agent environment, writes to its native instruction file, and installs a git post-merge hook for automatic claim release. `brainclaw setup` must have been run first on this machine. Do not run `init` from inside `.brainclaw/`; that directory is Brainclaw's own memory store, not a project root.
 
 | Option | Description |
 |---|---|
@@ -993,13 +993,13 @@ brainclaw context --since-session --max-items 20
 
 ### `brainclaw context-diff`
 
-Show what has changed in shared memory since a reference point.
+Hybrid context view for subsequent prompts: always includes **critical anchors** (active claims, resolved instructions, top 5 traps) plus the memory delta since a reference point. Used by the Claude Code UserPromptSubmit hook after the first prompt.
 
 | Option | Description |
 |---|---|
 | `--since <date>` | Start date for the diff |
 | `--session <id>` | Compare against a specific session start |
-| `--json` | Output as JSON |
+| `--json` | Output as JSON (includes anchors + changed items) |
 
 ```bash
 brainclaw context-diff --session sess_42
@@ -1127,6 +1127,7 @@ Export memory as a native agent instruction file.
 |---|---|
 | `--format <format>` | Target format: `copilot-instructions`, `cursor-rules`, `agents-md`, `claude-md`, `gemini-md`, `windsurf`, `cline`, `roo`, or `continue` |
 | `--detect` | Auto-detect the running agent and write to its native file |
+| `--all` | Write all known agent instruction files at once (deduplicates by format) |
 | `--write` | Write output to the native file path (instead of stdout); generated workspace files are treated as local and added to `.gitignore` |
 | `--shared` | Keep the main exported instruction file versionable when used with `--write`; companion MCP/settings files stay local |
 | `--output <path>` | Write to a custom output path |
@@ -1146,6 +1147,7 @@ brainclaw export --format roo --write                    # .roo/rules/brainclaw.
 brainclaw export --format continue --write               # .continue/rules/brainclaw.md
 brainclaw export --format claude-md --write --shared     # publish CLAUDE.md intentionally
 brainclaw export --format claude-md                      # stdout
+brainclaw export --all                                   # all 9 agent files at once
 ```
 
 `brainclaw export --write` is local-first by default: the generated workspace file and any companion MCP/settings files are added to `.gitignore`. Use `--shared` only when you intentionally want the main instruction file to be committed. `brainclaw export --detect` also writes companion MCP config where relevant, including `opencode.json` for OpenCode and `.gemini/antigravity/mcp_config.json` for Antigravity/Gemini when the local environment is available.
@@ -1174,7 +1176,7 @@ See [adapters/openclaw.md](adapters/openclaw.md).
 
 ### `brainclaw install-hooks`
 
-Install Git hooks for constraint checking.
+Install Git hooks: pre-commit (constraint checking, sensitive content detection) and post-merge (auto-release of claims whose scope overlaps merged files).
 
 | Option | Description |
 |---|---|
@@ -1391,7 +1393,7 @@ brainclaw mcp
 | `bclaw_get_agent_board` | Live plan + claim board with active sessions |
 | `bclaw_search` | Full-text BM25 search across all memory items |
 | `bclaw_estimation_report` | Estimation accuracy report for completed plans |
-| `bclaw_list_plans` | List plan items with the same filters as `brainclaw plan list` |
+| `bclaw_list_plans` | List plan items with filters, pagination (`limit`/`offset`), `compact` mode, and direct `id` lookup |
 | `bclaw_list_claims` | List claims with the same filters as `brainclaw claim list` |
 | `bclaw_list_agents` | List registered agents, optionally with bounded reputation summaries |
 | `bclaw_list_instructions` | List raw or resolved shared instructions |

package/docs/concepts/memory.md

@@ -32,7 +32,7 @@ Examples: constraints, decisions, traps, completed plans, handoffs.
 
 Shared traps now have a lifecycle too: `active`, `resolved`, or `expired`. Active views such as generated context, status, and `project.md` prioritize only active traps so old machine-setup issues stop polluting the current working set, while the canonical memory still keeps resolved traps for audit and search.
 
-These live in `.brainclaw/store.json` and are shared via Git (or by reading the same file).
+These live as individual JSON files under `.brainclaw/memory/` (constraints, decisions, traps, instructions) and `.brainclaw/coordination/` (plans, claims, handoffs). They are versioned in `.brainclaw/.git` and shared via Git.
 
 ### Runtime memory
 Operational observations that may be short-lived, host-specific, or private.
@@ -59,8 +59,9 @@ brainclaw makes this context visible and versionable.
 
 brainclaw keeps:
 
-- canonical structured JSON as the source of truth (`.brainclaw/store.json`)
-- a generated readable view in each agent's native format (`CLAUDE.md`, `.cursor/rules/brainclaw.md`, etc.)
+- canonical structured JSON as the source of truth (individual files under `.brainclaw/memory/` and `.brainclaw/coordination/`)
+- a derived readable view (`project.md`) regenerated best-effort from canonical state
+- native agent instruction files (`CLAUDE.md`, `.cursor/rules/brainclaw.md`, etc.) generated via `brainclaw export`
 
 This balances machine reliability with human readability.
 

package/docs/concepts/plans-and-claims.md

@@ -106,6 +106,16 @@ brainclaw claim release <id>
 
 `claim list` shows who holds each claim and whether it is still active. If a claim has a `session_id`, the last 8 characters are shown so you can correlate with the agent session that created it.
 
+### Automatic claim release
+
+Claims are automatically released after a `git merge` if the post-merge hook is installed (default since `brainclaw init` v0.25.3+). The hook matches merged file paths against active claim scopes and releases overlapping claims.
+
+You can also install or reinstall the hook manually:
+
+```bash
+brainclaw install-hooks
+```
+
 ## Why claims matter
 
 Without claims, multiple agents can easily touch the same area at once and generate conflicting changes.

package/docs/integrations/agents.md

@@ -83,7 +83,8 @@ brainclaw export --detect --write          # auto-detect and write all formats
 When brainclaw memory changes (new constraints, resolved traps, updated plans), regenerate instruction files:
 
 ```bash
-brainclaw export --detect --write
+brainclaw export --all              # all 9 agent formats at once
+brainclaw export --detect --write   # only the detected agent
 ```
 
 For agents without MCP (Copilot), this is especially important — the instruction file is their only source of project context.

package/docs/integrations/claude-code.md

@@ -14,7 +14,7 @@ brainclaw export --format claude-md --write
 
 - use MCP as the default runtime path for dynamic retrieval and writes
 - keep `CLAUDE.md` lightweight and behavioral: it should tell Claude Code when to call Brainclaw, not carry all mutable workspace state
-- use `.brainclaw/project.md` as a readable fallback baseline, not as the primary live source of truth
+- use `.brainclaw/project.md` as a readable fallback (it is a derived view, regenerated best-effort — run `brainclaw rebuild` if stale)
 - use hooks or workflow checks when a stronger reminder is needed
 
 ## Key idea

package/docs/integrations/codex.md

@@ -14,7 +14,7 @@ brainclaw export --format agents-md --write
 
 - use MCP as the default runtime path for fresh context, plans, claims, and runtime notes
 - keep `AGENTS.md` lightweight and behavioral: it should remind Codex how to use Brainclaw, not duplicate live state
-- use `.brainclaw/project.md` only as a readable fallback when MCP is unavailable or when a human wants a simple snapshot
+- use `.brainclaw/project.md` only as a readable fallback (derived view, regenerated best-effort — run `brainclaw rebuild` if stale)
 - encourage plans, claims, and handoffs during multi-step work
 
 ## Good role for brainclaw here

package/docs/integrations/copilot.md

@@ -14,7 +14,7 @@ brainclaw export --format copilot-instructions --write
 
 - use MCP whenever the Copilot surface supports it for fresh context and coordination views
 - keep `.github/copilot-instructions.md` lightweight and behavioral
-- use `.brainclaw/project.md` as readable fallback, not as the only live context source
+- use `.brainclaw/project.md` as readable fallback (derived view, regenerated best-effort — may need `brainclaw rebuild` if stale)
 - use plans, claims, and handoffs to reduce ambiguity across sessions
 
 ## Why this matters

package/docs/integrations/cursor.md

@@ -14,7 +14,7 @@ brainclaw export --format cursor-rules --write
 
 - use MCP as the default dynamic path for context, board state, plans, and claims
 - let the generated `.cursor/rules/brainclaw.md` tell Cursor when to consult Brainclaw and how to stay inside the workflow
-- use `.brainclaw/project.md` only as readable fallback shared state
+- use `.brainclaw/project.md` only as readable fallback (derived view, may be stale — run `brainclaw rebuild` to refresh)
 - rely on claims and plans when multiple agents or humans are active in the same repo
 
 ## Key point

package/docs/integrations/mcp.md

@@ -42,7 +42,7 @@ This keeps session continuity inside Brainclaw instead of pushing the agent back
 | `bclaw_write_note` | Record a runtime note, supports `autoReflect: true` |
 | `bclaw_read_handoff` | Read active handoffs |
 | `bclaw_get_agent_board` | Coordination snapshot |
-| `bclaw_list_plans` | Structured plan listing with CLI-equivalent filters |
+| `bclaw_list_plans` | Structured plan listing with filters, pagination (`limit`/`offset`), `compact` mode, and `id` lookup |
 | `bclaw_list_claims` | Structured claim listing with CLI-equivalent filters |
 | `bclaw_list_agents` | Registered agent inventory, optionally with bounded reputation |
 | `bclaw_list_instructions` | Raw or resolved instruction listing |
@@ -58,7 +58,7 @@ This keeps session continuity inside Brainclaw instead of pushing the agent back
 | Runtime writes with session continuity | MCP |
 | Local behavioral reminders inside the agent UI | native agent files |
 | Human inspection or scripting | CLI |
-| Simple readable fallback | `.brainclaw/project.md` |
+| Simple readable fallback | `.brainclaw/project.md` (derived view, may be stale) |
 
 ## Starting The Server
 
@@ -87,16 +87,26 @@ Interview answers are keyed by question ID and may contain:
 - `response_boolean`
 - optional explicit `suggestions` when the agent wants to confirm exact canonical memory items
 
+## Mutation Safety
+
+The MCP server serializes all mutations through a single-writer queue (`McpTaskRunner`). When an agent calls a write tool (e.g. `bclaw_claim`, `bclaw_write_note`, `bclaw_create_plan`), the request is enqueued and executed one at a time. This guarantees:
+
+- no concurrent writes from the same MCP connection
+- no partial state from interleaved mutations
+- deterministic ordering of operations
+
+A secondary file-based lock (`mutate()`) provides cross-process safety in case CLI commands run alongside MCP. But for agents, MCP is the safe path by design — no extra precautions needed.
+
 ## Important Rule
 
-If the agent has MCP available, do not treat the CLI as the primary runtime interface.
+If the agent has MCP available, do not treat the CLI as the primary runtime interface. All agent mutations MUST go through MCP tools.
 
 The CLI remains valuable for:
 
-- setup
+- setup and initialization
 - bootstrap by a human operator
-- scripting
+- scripting and automation
 - release and packaging
 - debugging and fallback access
 
-But for capable agents, MCP should be the first-class path for dynamic state.
+But for capable agents, MCP is the first-class path for both reads and writes.

package/docs/integrations/overview.md

@@ -87,9 +87,9 @@ The developer can dial back individual surfaces if needed, but the default is fu
 
 ## 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.
+brainclaw's store mutations are serialized (MCP single-writer queue + file-based lock), so memory writes are safe even under contention. However, running multiple agents in parallel on the same checkout can still cause Git conflicts and confusing file-level state.
 
-Running multiple agents in parallel on the same checkout will create conflicts. Git worktree isolation per agent is planned but not yet available.
+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. Git worktree isolation per agent is planned but not yet available.
 
 ## Next reads
 

package/docs/quickstart.md

@@ -74,7 +74,9 @@ This keeps non-code work visible to the project without overloading the active c
 
 ## Important: one agent at a time
 
-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.
+brainclaw serializes all store mutations (file lock + MCP single-writer queue), so writes are safe. But running multiple agents in parallel on the same checkout can still cause Git conflicts and confusing state transitions.
+
+Use brainclaw for sequential collaboration: one agent works, finishes, and the next one picks up from shared context. Use `bclaw_session_end` to hand off cleanly.
 
 ## Next reads