brainclaw 0.19.6 → 0.19.10

package/dist/core/candidates.js

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

package/dist/core/claims.js

@@ -1,7 +1,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import { ClaimSchema } from './schema.js';
-import { resolveEntityDir } from './io.js';
+import { resolveEntityDir, withStoreLock } from './io.js';
 import { nowISO } from './ids.js';
 import { JsonStore } from './json-store.js';
 function claimsDir(cwd, mode = 'read') {
@@ -22,14 +22,16 @@ function claimStore(cwd) {
     });
 }
 export function saveClaim(claim, cwd) {
-    ensureClaimsDir(cwd);
-    const writeStore = new JsonStore({
-        dirPath: claimsDir(cwd, 'write'),
-        documentType: 'claim',
-        getId: (c) => c.id,
-        sort: (a, b) => a.created_at.localeCompare(b.created_at),
+    withStoreLock(cwd, () => {
+        ensureClaimsDir(cwd);
+        const writeStore = new JsonStore({
+            dirPath: claimsDir(cwd, 'write'),
+            documentType: 'claim',
+            getId: (c) => c.id,
+            sort: (a, b) => a.created_at.localeCompare(b.created_at),
+        });
+        writeStore.save(ClaimSchema.parse(claim));
     });
-    writeStore.save(ClaimSchema.parse(claim));
 }
 export function loadClaim(id, cwd) {
     return claimStore(cwd).load(id);

package/dist/core/coordination.js

@@ -5,7 +5,7 @@ import { listClaims } from './claims.js';
 import { inferProjectFromTarget, loadInstructions, resolveInstructions } from './instructions.js';
 import { buildReputationSummary, findAgentReputationSummary } from './reputation.js';
 import { listRuntimeNotes } from './runtime.js';
-import { loadState, saveState } from './state.js';
+import { loadState, persistState } from './state.js';
 export function buildCoordinationSnapshot(options = {}) {
     const config = loadConfig(options.cwd);
     const state = loadState(options.cwd);
@@ -58,7 +58,7 @@ export function buildCoordinationSnapshot(options = {}) {
             }
         }
         if (changed)
-            saveState(state, options.cwd);
+            persistState(state, options.cwd);
     }
     return {
         project_id: config.project_id,

package/dist/core/instructions.js

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

package/dist/core/io.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { withLock, cleanStaleLocks } from './lock.js';
 export const MEMORY_DIR = '.brainclaw';
+const STORE_LOCK_BASENAME = '.store-mutation';
 const RETRYABLE_RENAME_ERROR_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
 const DEFAULT_RENAME_RETRY_ATTEMPTS = 6;
 const DEFAULT_RENAME_RETRY_DELAY_MS = 25;
@@ -72,6 +73,9 @@ export function memoryDir(cwd = process.cwd(), preferredDirName) {
 export function memoryPath(filename, cwd, preferredDirName) {
     return path.join(memoryDir(cwd, preferredDirName), filename);
 }
+export function storeLockPath(cwd, preferredDirName) {
+    return memoryPath(STORE_LOCK_BASENAME, cwd, preferredDirName);
+}
 export function memoryExists(cwd, preferredDirName) {
     return fs.existsSync(memoryDir(cwd, preferredDirName));
 }
@@ -95,6 +99,10 @@ export function ensureMemoryDir(cwd, preferredDirName) {
         }
     }
 }
+export function withStoreLock(cwd = process.cwd(), fn, preferredDirName) {
+    ensureMemoryDir(cwd, preferredDirName);
+    return withLock(storeLockPath(cwd, preferredDirName), fn);
+}
 /** Check if a path is a file, or a directory with at least one entry. */
 function hasContent(p) {
     try {

package/dist/core/lock.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 const DEFAULT_TIMEOUT_MS = 2000;
 const LOCK_RETRY_INTERVAL_MS = 50;
 const LOCK_EXPIRY_MS = 5000;
+const heldLocks = new Map();
 function lockFilePath(targetPath) {
     return targetPath + '.lock';
 }
@@ -59,22 +60,37 @@ function tryBreakLock(lockPath) {
 }
 export function acquireLock(targetPath, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const lockPath = lockFilePath(targetPath);
+    const heldCount = heldLocks.get(lockPath);
+    if (heldCount) {
+        heldLocks.set(lockPath, heldCount + 1);
+        return true;
+    }
     const deadline = Date.now() + timeoutMs;
     const dir = path.dirname(lockPath);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
     while (Date.now() < deadline) {
-        if (tryCreateLock(lockPath))
+        if (tryCreateLock(lockPath)) {
+            heldLocks.set(lockPath, 1);
             return true;
-        if (tryBreakLock(lockPath))
+        }
+        if (tryBreakLock(lockPath)) {
+            heldLocks.set(lockPath, 1);
             return true;
+        }
         syncSleep(Math.min(LOCK_RETRY_INTERVAL_MS, deadline - Date.now()));
     }
     return false;
 }
 export function releaseLock(targetPath) {
     const lockPath = lockFilePath(targetPath);
+    const heldCount = heldLocks.get(lockPath);
+    if (heldCount && heldCount > 1) {
+        heldLocks.set(lockPath, heldCount - 1);
+        return;
+    }
+    heldLocks.delete(lockPath);
     try {
         if (fs.existsSync(lockPath)) {
             fs.unlinkSync(lockPath);

package/dist/core/migration.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
 import { memoryDir, memoryPath, readFileSync, writeFileAtomic, resolveEntityDir } from './io.js';
-import { AgentIdentityDocumentSchema, BootstrapProfileDocumentSchema, CandidateSchema, ClaimSchema, ConfigSchema, MemorySeedDocumentSchema, ConstraintSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InstructionEntrySchema, PlanItemSchema, ProjectIdentityDocumentSchema, RuntimeNoteSchema, SessionSnapshotSchema, TrapSchema, } from './schema.js';
+import { BootstrapApplicationReceiptSchema, BootstrapImportPlanDocumentSchema, AgentIdentityDocumentSchema, BootstrapProfileDocumentSchema, CandidateSchema, ClaimSchema, ConfigSchema, MemorySeedDocumentSchema, ConstraintSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InstructionEntrySchema, PlanItemSchema, ProjectIdentityDocumentSchema, RuntimeNoteSchema, SessionSnapshotSchema, TrapSchema, } from './schema.js';
 export class MigrationError extends Error {
     kind;
     documentType;
@@ -16,6 +16,8 @@ export class MigrationError extends Error {
 const CURRENT_SCHEMA_VERSION = 2;
 const registry = {
     agent_identity: createRegistryEntry(AgentIdentityDocumentSchema),
+    bootstrap_application: createRegistryEntry(BootstrapApplicationReceiptSchema),
+    bootstrap_import_plan: createRegistryEntry(BootstrapImportPlanDocumentSchema),
     bootstrap_profile: createRegistryEntry(BootstrapProfileDocumentSchema),
     candidate: createRegistryEntry(CandidateSchema),
     claim: createRegistryEntry(ClaimSchema),
@@ -145,6 +147,8 @@ export function scanMigrationStatus(cwd) {
     collectSingle(entries, memoryPath('project.identity.json', cwd), 'project_identity');
     collectSingle(entries, memoryPath('.current-session', cwd), 'current_session');
     collectSingle(entries, memoryPath(path.join('bootstrap', 'profile.json'), cwd), 'bootstrap_profile');
+    collectSingle(entries, memoryPath(path.join('bootstrap', 'import-plan.json'), cwd), 'bootstrap_import_plan');
+    collectSingle(entries, memoryPath(path.join('bootstrap', 'last-application.json'), cwd), 'bootstrap_application');
     const effectiveCwd = cwd ?? process.cwd();
     collectDirectory(entries, resolveEntityDir('constraints', effectiveCwd, 'read'), 'constraint');
     collectDirectory(entries, resolveEntityDir('decisions', effectiveCwd, 'read'), 'decision');
@@ -161,7 +165,7 @@ export function scanMigrationStatus(cwd) {
     collectDirectory(entries, resolveEntityDir('runtime-hosts', effectiveCwd, 'read'), 'runtime_note', true);
     collectDirectory(entries, resolveEntityDir('runtime-private', effectiveCwd, 'read'), 'runtime_note', true);
     collectDirectory(entries, resolveEntityDir('instructions', effectiveCwd, 'read'), 'instruction');
-    collectDirectory(entries, resolveEntityDir('bootstrap', effectiveCwd, 'read'), 'memory_seed');
+    collectDirectory(entries, path.join(resolveEntityDir('bootstrap', effectiveCwd, 'read'), 'seeds'), 'memory_seed');
     collectDirectory(entries, resolveEntityDir('agents', effectiveCwd, 'read'), 'agent_identity');
     collectDirectory(entries, resolveEntityDir('sessions', effectiveCwd, 'read'), 'session_snapshot');
     return entries.sort((a, b) => a.path.localeCompare(b.path));

package/dist/core/runtime.js

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveCurrentHostId, sanitizeHostId } from './host.js';
-import { resolveEntityDir } from './io.js';
+import { resolveEntityDir, withStoreLock } from './io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { RuntimeNoteSchema } from './schema.js';
 import { commitMemoryChange } from './memory-git.js';
@@ -40,13 +40,15 @@ export function saveRuntimeNote(note, cwd) {
     const persistedNote = visibility === 'shared'
         ? { ...note, visibility, host_id: hostId }
         : { ...note, visibility, host_id: hostId };
-    ensureRuntimeDir(note.agent, cwd, visibility, hostId);
-    const filepath = visibility === 'shared'
-        ? path.join(sharedAgentDir(note.agent, cwd, 'write'), `${note.id}.json`)
-        : path.join(hostAgentDir(visibility, hostId, note.agent, cwd, 'write'), `${note.id}.json`);
-    saveVersionedJsonFile('runtime_note', filepath, RuntimeNoteSchema.parse(persistedNote));
-    appendEvent({ action: 'create', item_type: 'runtime_note', item_id: note.id, agent: note.agent, agent_id: note.agent_id }, cwd);
-    commitMemoryChange(`runtime note: ${note.note_type ?? 'note'} (${note.agent})`, cwd);
+    withStoreLock(cwd, () => {
+        ensureRuntimeDir(note.agent, cwd, visibility, hostId);
+        const filepath = visibility === 'shared'
+            ? path.join(sharedAgentDir(note.agent, cwd, 'write'), `${note.id}.json`)
+            : path.join(hostAgentDir(visibility, hostId, note.agent, cwd, 'write'), `${note.id}.json`);
+        saveVersionedJsonFile('runtime_note', filepath, RuntimeNoteSchema.parse(persistedNote));
+        appendEvent({ action: 'create', item_type: 'runtime_note', item_id: note.id, agent: note.agent, agent_id: note.agent_id }, cwd);
+        commitMemoryChange(`runtime note: ${note.note_type ?? 'note'} (${note.agent})`, cwd);
+    });
 }
 export function runtimeNotePath(note, cwd) {
     const visibility = note.visibility ?? 'shared';
@@ -56,12 +58,14 @@ export function runtimeNotePath(note, cwd) {
         : path.join(hostAgentDir(visibility, hostId, note.agent, cwd), `${note.id}.json`);
 }
 export function deleteRuntimeNote(note, cwd) {
-    const filepath = runtimeNotePath(note, cwd);
-    if (!fs.existsSync(filepath)) {
-        return false;
-    }
-    fs.unlinkSync(filepath);
-    return true;
+    return withStoreLock(cwd, () => {
+        const filepath = runtimeNotePath(note, cwd);
+        if (!fs.existsSync(filepath)) {
+            return false;
+        }
+        fs.unlinkSync(filepath);
+        return true;
+    });
 }
 function readAgentNotes(dir, agent) {
     if (!fs.existsSync(dir))

package/dist/core/schema.js

@@ -451,6 +451,7 @@ export const MemorySeedKindSchema = z.enum([
 export const MemorySeedSourceKindSchema = z.enum([
     'readme',
     'agents_md',
+    'native_instruction',
     'manifest',
     'repo_analysis',
     'git',
@@ -483,6 +484,74 @@ export const BootstrapProfileDocumentSchema = z.object({
     agents_md_present: z.boolean().default(false),
     seed_count: z.number().int().nonnegative(),
     target: z.string().optional(),
+    workspace_kind: z.enum(['empty', 'existing']).optional(),
+    confidence: MemorySeedConfidenceSchema.optional(),
+    native_instruction_files: z.array(z.string()).default([]),
+    gaps: z.array(z.string()).default([]),
+});
+export const BootstrapSuggestionTargetSchema = z.enum(['instruction', 'decision', 'constraint', 'trap']);
+export const BootstrapSuggestionDocumentSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    target: BootstrapSuggestionTargetSchema,
+    text: z.string(),
+    rationale: z.string(),
+    confidence: MemorySeedConfidenceSchema,
+    source_seed_ids: z.array(z.string()).default([]),
+    source_refs: z.array(z.string()).default([]),
+    layer: z.enum(['global', 'project', 'agent']).optional(),
+    scope: z.string().optional(),
+    tags: z.array(z.string()).default([]),
+    related_paths: z.array(z.string()).optional(),
+    reversible: z.boolean().default(true),
+});
+export const BootstrapInterviewAudienceSchema = z.enum(['cli', 'ide_chat', 'any']);
+export const BootstrapInterviewQuestionSchema = z.object({
+    id: z.string(),
+    prompt: z.string(),
+    rationale: z.string(),
+    priority: z.enum(['high', 'medium', 'low']),
+    audience: BootstrapInterviewAudienceSchema.default('any'),
+    response_kind: z.enum(['short_text', 'long_text', 'boolean', 'list']).default('short_text'),
+    gap_keys: z.array(z.string()).default([]),
+});
+export const BootstrapInterviewPlanSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    derived_at: z.string(),
+    workspace_kind: z.enum(['empty', 'existing']).optional(),
+    audience: BootstrapInterviewAudienceSchema.default('any'),
+    summary: z.string(),
+    question_count: z.number().int().nonnegative(),
+    questions: z.array(BootstrapInterviewQuestionSchema).default([]),
+});
+export const BootstrapImportPlanDocumentSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    derived_at: z.string(),
+    target: z.string().optional(),
+    workspace_kind: z.enum(['empty', 'existing']).optional(),
+    confidence: MemorySeedConfidenceSchema.optional(),
+    summary: z.string(),
+    requires_confirmation: z.boolean().default(true),
+    gaps: z.array(z.string()).default([]),
+    suggestion_count: z.number().int().nonnegative(),
+    suggestions: z.array(BootstrapSuggestionDocumentSchema).default([]),
+    interview: BootstrapInterviewPlanSchema.optional(),
+});
+export const BootstrapManagedArtifactSchema = z.object({
+    kind: z.enum(['instruction', 'decision', 'constraint', 'trap']),
+    id: z.string(),
+    suggestion_id: z.string(),
+    rollback_action: z.enum(['deactivate', 'delete']).default('delete'),
+});
+export const BootstrapApplicationReceiptSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    applied_at: z.string(),
+    proposal_derived_at: z.string(),
+    target: z.string().optional(),
+    workspace_kind: z.enum(['empty', 'existing']).optional(),
+    managed_artifacts: z.array(BootstrapManagedArtifactSchema).default([]),
+    suggestion_ids: z.array(z.string()).default([]),
+    uninstalled_at: z.string().optional(),
 });
 export const AgentIntegrationNameSchema = z.enum([
     'github-copilot',

package/dist/core/state.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ConstraintSchema, DecisionSchema, TrapSchema, HandoffSchema, PlanItemSchema } from './schema.js';
-import { ensureMemoryDir, resolveEntityDir } from './io.js';
+import { ensureMemoryDir, memoryPath, resolveEntityDir, withStoreLock, writeFileAtomic } from './io.js';
 import { commitMemoryChange } from './memory-git.js';
 import { appendEvent } from './event-log.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
+import { generateMarkdown } from './markdown.js';
 export function emptyState() {
     return {
         version: 1,
@@ -69,15 +70,31 @@ function syncDirectory(dirPath, items, documentType) {
     }
 }
 export function saveState(state, cwd) {
+    persistState(state, cwd, { writeProjectMarkdown: false });
+}
+function writeStateDirectories(state, cwd) {
     ensureMemoryDir(cwd);
     const effectiveCwd = cwd ?? process.cwd();
-    // Write to entity-aligned directories
     syncDirectory(resolveEntityDir('constraints', effectiveCwd, 'write'), state.active_constraints, 'constraint');
     syncDirectory(resolveEntityDir('decisions', effectiveCwd, 'write'), state.recent_decisions, 'decision');
     syncDirectory(resolveEntityDir('traps', effectiveCwd, 'write'), state.known_traps, 'trap');
     syncDirectory(resolveEntityDir('handoffs', effectiveCwd, 'write'), state.open_handoffs, 'handoff');
     syncDirectory(resolveEntityDir('plans', effectiveCwd, 'write'), state.plan_items, 'plan');
-    appendEvent({ action: 'update', item_type: 'state', agent: 'system' }, cwd);
-    commitMemoryChange('state update', cwd);
+}
+export function persistState(state, cwd, options = {}) {
+    const effectiveCwd = cwd ?? process.cwd();
+    withStoreLock(effectiveCwd, () => {
+        writeStateDirectories(state, effectiveCwd);
+        if (options.writeProjectMarkdown ?? true) {
+            writeFileAtomic(memoryPath('project.md', effectiveCwd), generateMarkdown(state, effectiveCwd));
+        }
+        appendEvent({
+            action: options.eventAction ?? 'update',
+            item_type: 'state',
+            agent: 'system',
+            summary: options.eventSummary,
+        }, effectiveCwd);
+        commitMemoryChange(options.commitMessage ?? 'state update', effectiveCwd);
+    });
 }
 //# sourceMappingURL=state.js.map

package/docs/cli.md

@@ -1,6 +1,15 @@
 # CLI Reference
 
-Commands grouped by purpose. All commands are available as `brainclaw` or its alias `bclaw`.
+The CLI is Brainclaw's explicit operator, scripting, release, and fallback surface. All commands are available as `brainclaw` or its alias `bclaw`.
+
+For capable coding agents, prefer MCP for dynamic runtime state:
+
+- `bclaw_bootstrap` instead of manual bootstrap polling
+- `bclaw_get_context` instead of repeated raw CLI context calls
+- `bclaw_list_plans` / `bclaw_list_claims` / `bclaw_get_agent_board` for live coordination views
+- `bclaw_claim`, `bclaw_write_note`, and `bclaw_session_end` for session continuity
+
+Use the CLI when a human operator is driving the workflow, when you are scripting setup or release operations, or when MCP is not the integration path.
 
 ---
 
@@ -97,15 +106,24 @@ brainclaw rebuild
 
 Bootstrap shared memory for a new agent or project context.
 
+For capable agents, the MCP equivalent is `bclaw_bootstrap`. Use the CLI when a human is driving onboarding, reviewing the import proposal, or operating in fallback mode.
+
 | Option | Description |
 |---|---|
 | `--for <agent>` | Target agent name |
 | `--json` | Output as JSON |
 | `--refresh` | Force refresh even if bootstrap data is recent |
+| `--interview` | Render adaptive interview prompts instead of the bootstrap summary |
+| `--audience <audience>` | Filter interview prompts for `cli`, `ide_chat`, or `any` |
+| `--apply` | Import the current bootstrap proposal into canonical memory |
+| `--uninstall` | Deactivate the last bootstrap-managed import |
+| `-y, --yes` | Skip confirmation prompts for apply/uninstall |
 
 ```bash
 brainclaw bootstrap --for copilot
 brainclaw bootstrap --for claude --refresh --json
+brainclaw bootstrap --interview --audience cli
+brainclaw bootstrap --apply -y
 ```
 
 ### `brainclaw env`
@@ -574,6 +592,8 @@ brainclaw search "rollout" --since 2026-01-01 --json
 
 ## Planning and Coordination
 
+For capable agents, prefer the MCP plan and claim tools for live runtime interactions. The CLI remains the operator and scripting form of the same coordination model.
+
 ### `brainclaw plan create <text>`
 
 Create a shared work item.

package/docs/integrations/agents.md

@@ -10,30 +10,43 @@ That means brainclaw integration should not rely on only one mechanism such as:
 - a single skill
 - a single startup command
 
-## Better approach
-
-Use multiple points of contact:
-
-- lightweight system instructions
-- project-specific context retrieval
-- prompt-ready generated context
-- MCP tools when available
-- board and status views
-- workflow reminders around plans, claims, and handoffs
+## 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.
+### System instructions
+How the agent should use brainclaw.
 
 Examples:
 
-- check workspace memory before significant changes
-- bootstrap if the workspace is not initialized and the workflow allows it
-- respect file claims
-- update shared plan status when appropriate
+- 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.
@@ -86,9 +99,9 @@ By default, `--write` treats generated workspace files as local setup and adds t
 
 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.
 
-## MCP server workflow
-
-The brainclaw MCP server exposes all memory operations as tools that agents can call directly.
+## MCP server workflow
+
+The brainclaw MCP server exposes the dynamic Brainclaw workflow directly. For capable agents, this is the nominal runtime path.
 
 ### Starting the MCP server
 
@@ -116,19 +129,19 @@ Most agents pick this up via their MCP config file (`.mcp.json`, `~/.cursor/mcp.
 | `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
+## Session lifecycle
+
+### Starting a session
+
+```bash
+brainclaw session-start --agent my-agent --model claude-opus-4-5
 ```
 
 This registers the agent's identity and optionally records the model being used. Other agents can see active sessions in `list-claims` and `board`.
 
-### During the session
-
-At each significant step:
+### 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.
 
 ```bash
 brainclaw context --json        # load fresh project state
@@ -146,7 +159,7 @@ brainclaw session-end --auto-release
 
 This releases all active claims held by the current agent and updates plan statuses.
 
-## Generated files are local-only
+## Generated files are local-only
 
 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**.
 

package/docs/integrations/claude-code.md

@@ -12,12 +12,12 @@ brainclaw export --format claude-md --write
 
 ## Recommended approach
 
-- add lightweight usage instructions for brainclaw in `CLAUDE.md`
-- use `.brainclaw/project.md` as a readable baseline
-- prefer MCP for dynamic retrieval when available
+- 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 hooks or workflow checks when a stronger reminder is needed
 
 ## Key idea
 
 Claude Code should not carry all workspace state in static instructions.
-brainclaw provides the living workspace layer.
+brainclaw provides the living workspace layer through MCP plus local workflow guidance.

package/docs/integrations/codex.md

@@ -12,12 +12,12 @@ brainclaw export --format agents-md --write
 
 ## Recommended approach
 
-- keep a lightweight instruction telling Codex to consult brainclaw
-- let Codex read `.brainclaw/project.md` when simple file context is enough
-- use MCP for fresher scoped context when available
-- encourage use of plans, claims, and handoffs during multi-step work
+- 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
+- encourage plans, claims, and handoffs during multi-step work
 
 ## Good role for brainclaw here
 
 Codex stays the coding agent.
-brainclaw provides the shared workspace context and coordination layer.
+brainclaw provides the live workspace context and coordination layer.

package/docs/integrations/copilot.md

@@ -12,9 +12,10 @@ brainclaw export --format copilot-instructions --write
 
 ## Recommended approach
 
-- point Copilot to `.brainclaw/project.md` or use fresh context retrieval
+- 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 plans, claims, and handoffs to reduce ambiguity across sessions
-- use MCP where supported for dynamic collaboration views
 
 ## Why this matters
 

package/docs/integrations/cursor.md

@@ -12,12 +12,12 @@ brainclaw export --format cursor-rules --write
 
 ## Recommended approach
 
-- the generated `.cursor/rules/brainclaw.md` tells Cursor to consult brainclaw before significant edits
-- use `.brainclaw/project.md` for readable shared state
-- use MCP for dynamic retrieval when available
+- 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
 - rely on claims and plans when multiple agents or humans are active in the same repo
 
 ## Key point
 
 Cursor rules describe behavior.
-brainclaw provides the living shared state those rules should point to.
+brainclaw provides the living shared state those rules should point to through MCP.