brainclaw 1.9.0 → 1.9.1

package/dist/commands/mcp.js

@@ -39,7 +39,7 @@ import { createCapability, createTool as createRegistryTool } from '../core/regi
 import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, getDetectedSetupAgentNames, getInstalledAgentNames, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
 import { buildAgentInventory } from '../core/agent-inventory.js';
-import { resolveEffectiveCwd, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.js';
+import { resolveEffectiveCwd, resolveEffectiveCwdInfo, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.js';
 import { assessBootstrapNeed, probeForQuickSetup, buildQuickSetupProbeResponse, buildOnboardingPreview, resolveEmptyMemoryRecommendation } from '../core/setup-flow.js';
 import { ensureUserStore, resolveHomeDir } from '../core/setup-state.js';
 import { createPlan, addStep as addStepOp, completeStep as completeStepOp, updateStep as updateStepOp, deleteStep as deleteStepOp, deletePlan as deletePlanOp } from '../core/operations/plan.js';
@@ -167,6 +167,8 @@ export const MCP_READ_TOOLS = [
                 type: { type: 'string', description: 'Filter by section: decisions, constraints, traps, handoffs, candidates, plans, sequences.' },
                 section: { type: 'string', description: 'Filter by section (state, candidates, runtime).' },
                 since: { type: 'string', description: 'Filter items created after this ISO date.' },
+                project: { type: 'string', description: 'Optional project name/path to search. Defaults to the active project.' },
+                includeLegacy: { type: 'boolean', description: 'Include records with provenance.kind="legacy" (default false). Response reports excluded_legacy when false.' },
                 limit: { type: 'number', description: 'Maximum number of results to return (default 10).' },
                 offset: { type: 'number', description: 'Number of results to skip (for pagination).' },
                 budget_tokens: { type: 'number', description: 'Optional token budget for the result page (~4 chars/token). The page is size-bounded; has_more/next_offset advertise the rest.' },
@@ -1782,6 +1784,32 @@ function explicitSessionIdFromEnv() {
         || process.env.CLAUDE_SESSION_ID?.trim()
         || process.env.COPILOT_SESSION_ID?.trim();
 }
+function projectInfoForCwd(cwd) {
+    try {
+        const config = loadConfig(cwd);
+        return { path: cwd, name: config.project_name };
+    }
+    catch {
+        return { path: cwd };
+    }
+}
+function scopeMetadataForTarget(args, targetCwd, effectiveScope) {
+    const hasExplicitProject = typeof args.project === 'string' && args.project.trim().length > 0;
+    return {
+        resolved_project: projectInfoForCwd(targetCwd),
+        active_source: hasExplicitProject ? 'explicit' : effectiveScope.active_source,
+    };
+}
+function renderProvenanceFilterNote(result) {
+    const parts = [];
+    if ((result.excluded_legacy ?? 0) > 0) {
+        parts.push(`${result.excluded_legacy} legacy item(s) excluded (pass filter.includeLegacy=true to include them)`);
+    }
+    if ((result.excluded_low_confidence_auto_reflect ?? 0) > 0) {
+        parts.push(`${result.excluded_low_confidence_auto_reflect} low-confidence auto_reflect item(s) excluded (lower filter.minAutoReflectConfidence to include them)`);
+    }
+    return parts.length > 0 ? parts.join('; ') : undefined;
+}
 export function parseMcpLine(line) {
     let parsed;
     try {
@@ -2557,6 +2585,11 @@ import { handleMcpReadToolCall } from './mcp-read-handlers.js';
 export { handleMcpReadToolCall };
 async function _executeMcpToolCallInner(payload) {
     const { name, args, cwd, connectionSessionId } = payload;
+    const scopeInfo = payload.effectiveScope ?? {
+        cwd,
+        active_source: 'cwd',
+        resolved_project: projectInfoForCwd(cwd),
+    };
     try {
         if (isLegacyMcpToolFacadeDisabled(name)) {
             return { response: createLegacyMcpToolDisabledResponse() };
@@ -2568,7 +2601,7 @@ async function _executeMcpToolCallInner(payload) {
         }
         if (MCP_READ_TOOLS.some((tool) => tool.name === name) || LEGACY_READ_TOOL_HANDLERS.has(name)) {
             return {
-                response: appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd })), name),
+                response: appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd, connectionSessionId, effectiveScope: scopeInfo })), name),
             };
         }
         // Resolve model once for all write operations
@@ -6214,6 +6247,7 @@ async function _executeMcpToolCallInner(payload) {
             try {
                 const entity = String(args.entity ?? '');
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 // pln#460 follow-up — some MCP clients (notably Claude Code with a
                 // tool schema that declares `filter: { type: 'object' }` without a
                 // sub-property schema) stringify the filter object before shipping
@@ -6269,10 +6303,10 @@ async function _executeMcpToolCallInner(payload) {
                 const bounded = boundListResult(result, offset, charBudget);
                 const warnings = collectLoadValidationWarnings(entity, targetCwd);
                 const nextActions = [
-                    { tool: 'bclaw_get', args: { entity, id: '<id from items>' }, when: 'to read one item in full' },
+                    { tool: 'bclaw_get', args: { entity, id: '<id from items>', ...(args.project ? { project: args.project } : {}), ...(args.budget_tokens ? { budget_tokens: args.budget_tokens } : {}) }, when: 'to read one item in full' },
                 ];
                 if (bounded.has_more) {
-                    nextActions.push({ tool: 'bclaw_find', args: { entity, filter: { ...filter, offset: bounded.next_offset } }, when: 'to fetch the next page' });
+                    nextActions.push({ tool: 'bclaw_find', args: { entity, filter: { ...filter, offset: bounded.next_offset }, ...(args.project ? { project: args.project } : {}), ...(args.budget_tokens ? { budget_tokens: args.budget_tokens } : {}) }, when: 'to fetch the next page' });
                 }
                 // structuredContent is the canonical MCP return channel that clients
                 // (VS Code extension, Codex, etc.) read for machine-parseable data.
@@ -6281,10 +6315,20 @@ async function _executeMcpToolCallInner(payload) {
                 // `result.items` arrived as undefined on the client — the root cause
                 // of the VS Code Backlog section rendering empty.
                 const moreNote = bounded.has_more ? ` (returned ${bounded.returned}; ${result.total - bounded.returned} more — offset ${bounded.next_offset})` : '';
+                const provenanceFilterNote = renderProvenanceFilterNote(result);
+                const legacyNote = provenanceFilterNote
+                    ? `; ${provenanceFilterNote}`
+                    : '';
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)${moreNote}` }],
-                        structuredContent: { ...bounded, warnings, next_actions: nextActions },
+                        content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)${moreNote}${legacyNote}` }],
+                        structuredContent: {
+                            ...bounded,
+                            warnings,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                            next_actions: nextActions,
+                        },
                     }),
                 };
             }
@@ -6361,6 +6405,7 @@ async function _executeMcpToolCallInner(payload) {
                 }
                 const rawData = (args.data ?? {});
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 // Auto-fill identity fields. Without this, a caller who omits author/agent
                 // creates a schema-invalid record that is silently dropped on read and
                 // GC'd from disk on the next mutation.
@@ -6392,7 +6437,11 @@ async function _executeMcpToolCallInner(payload) {
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ created ${entity} ${result.id}` }],
-                        structuredContent: { ...result },
+                        structuredContent: {
+                            ...result,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                        },
                     }),
                 };
             }
@@ -6406,13 +6455,18 @@ async function _executeMcpToolCallInner(payload) {
                 const id = String(args.id ?? '');
                 const patch = (args.patch ?? {});
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = updateEntity(entity, id, patch, targetCwd);
                 appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'update', item_id: id, item_type: entity }, targetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ updated ${entity} ${id}` }],
-                        structuredContent: { ...result },
+                        structuredContent: {
+                            ...result,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                        },
                     }),
                 };
             }
@@ -6426,13 +6480,18 @@ async function _executeMcpToolCallInner(payload) {
                 const id = String(args.id ?? '');
                 const purge = args.purge === true;
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = removeEntity(entity, id, targetCwd, purge);
                 appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'delete', item_id: id, item_type: entity, reason: purge ? 'purged' : 'archived' }, targetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ removed ${entity} ${id}` }],
-                        structuredContent: { ...result },
+                        structuredContent: {
+                            ...result,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                        },
                     }),
                 };
             }
@@ -6454,13 +6513,18 @@ async function _executeMcpToolCallInner(payload) {
                 const to = String(args.to ?? '');
                 const reason = args.reason;
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = transitionEntity(entity, id, to, targetCwd, reason);
                 appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'update', item_id: id, item_type: entity, reason: `transition ${result.from} → ${to}${reason ? ` (${reason})` : ''}` }, targetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ ${entity} ${id}: ${result.from} → ${to}` }],
-                        structuredContent: { ...result },
+                        structuredContent: {
+                            ...result,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                        },
                     }),
                 };
             }
@@ -6504,9 +6568,10 @@ async function _executeMcpToolCallInner(payload) {
  */
 export async function executeMcpToolCall(payload) {
     const baseCwd = payload.cwd;
-    const cwd = payload.name === 'bclaw_switch'
-        ? baseCwd
-        : resolveEffectiveCwd({ baseCwd });
+    const effective = payload.name === 'bclaw_switch'
+        ? { cwd: baseCwd, active_source: 'cwd', resolved_project: undefined }
+        : resolveEffectiveCwdInfo({ baseCwd, sessionId: payload.connectionSessionId });
+    const cwd = effective.cwd;
     const envClaimId = process.env.BRAINCLAW_CLAIM_ID?.trim() || undefined;
     // ── Auto-session ────────────────────────────────────────────────────────────
     let autoSessionId;
@@ -6564,6 +6629,7 @@ export async function executeMcpToolCall(payload) {
         ...payload,
         cwd,
         connectionSessionId: effectiveConnectionSessionId,
+        effectiveScope: effective,
     });
     // Apply legacy deprecation warning uniformly (Phase 3 slice 3g). Read tools
     // already get it at line 2560; write tools historically did not. This

package/dist/commands/switch.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
-import { buildOperationalIdentity, loadCurrentSession, saveCurrentSession } from '../core/identity.js';
+import { buildOperationalIdentity, loadCurrentSession, loadSessionById, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { resolveProjectRef } from '../core/store-resolution.js';
 import { resolveCrossProjectLinks, resolveProjectCwd } from '../core/cross-project.js';
@@ -44,10 +44,28 @@ export function switchProject(projectRef, options = {}) {
     catch { /* name is optional */ }
     const now = new Date().toISOString();
     const sessionOnly = options.sessionOnly ?? true;
-    let session = loadCurrentSession(cwd);
+    let session = options.sessionId ? loadSessionById(options.sessionId, cwd) : loadCurrentSession(cwd);
     if (!session && sessionOnly) {
-        buildOperationalIdentity(undefined, cwd, { persistImplicitSession: true });
-        session = loadCurrentSession(cwd);
+        if (options.sessionId) {
+            const identity = buildOperationalIdentity(undefined, cwd, {
+                sessionId: options.sessionId,
+                persistImplicitSession: false,
+            });
+            saveCurrentSession({
+                session_id: options.sessionId,
+                started_at: now,
+                last_seen_at: now,
+                agent: identity.agent,
+                agent_id: identity.agent_id,
+                host_id: identity.host_id,
+                user: process.env.USER || process.env.USERNAME || undefined,
+                pid: process.pid,
+            }, cwd);
+        }
+        else {
+            buildOperationalIdentity(undefined, cwd, { persistImplicitSession: true });
+        }
+        session = options.sessionId ? loadSessionById(options.sessionId, cwd) : loadCurrentSession(cwd);
     }
     if (session && sessionOnly) {
         saveCurrentSession({
@@ -78,11 +96,14 @@ export function switchProject(projectRef, options = {}) {
  * List available projects in the workspace.
  */
 export function listAvailableProjects(cwd) {
+    return listAvailableProjectsForSession(cwd);
+}
+export function listAvailableProjectsForSession(cwd, sessionId) {
     const wsRoot = findOutermostWorkspaceRoot(cwd ?? process.cwd());
     if (!wsRoot) {
         throw new Error('No brainclaw workspace found.');
     }
-    const sessionActive = loadCurrentSession(cwd)?.active_project;
+    const sessionActive = (sessionId ? loadSessionById(sessionId, cwd) : loadCurrentSession(cwd))?.active_project;
     const globalActive = loadActiveProject(wsRoot);
     const active = sessionActive ?? globalActive;
     const activeSource = sessionActive ? 'session' : globalActive ? 'global' : 'none';

package/dist/commands/version.js

@@ -8,7 +8,7 @@ import { generateAgentReleaseNotes } from './release-notes.js';
 export function runVersion(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const initialized = memoryExists(cwd);
-    let config = initialized ? loadConfig(cwd) : undefined;
+    const config = initialized ? loadConfig(cwd) : undefined;
     let publishedLocalRelease;
     if (options.publishLocal) {
         if (!initialized || !config) {

package/dist/core/agent-capability.js

@@ -23,9 +23,21 @@ const AGENT_ALIASES = {
     'vibe': 'mistral-vibe',
     'hermes-agent': 'hermes',
 };
-/** Resolve an alias to its canonical agent name, or return the input unchanged. */
+/**
+ * Resolve an alias to its canonical agent name (case-insensitive).
+ *
+ * Agent names are case-insensitive: every canonical profile key and every alias
+ * is lowercase, so we trim + lowercase the input before resolving. This is the
+ * single normalization point — registry, messaging, spawn-check and the
+ * coordinate/dispatch pre-flight all route through here, so a target like
+ * "Codex" or "Gemini" resolves identically to "codex" / "gemini". Without it the
+ * dispatch pre-flight collapsed an unresolved name into "no CLI spawn template
+ * (IDE-only?)" and silently dropped the reviewer (github-copilot/Gemini hit this
+ * passing targetAgents=["Codex"]).
+ */
 export function resolveAgentAlias(name) {
-    return AGENT_ALIASES[name] ?? name;
+    const key = name.trim().toLowerCase();
+    return AGENT_ALIASES[key] ?? key;
 }
 const PROFILES = {
     // --- Code agents (interactive, IDE-driven) ---
@@ -314,7 +326,10 @@ const _customProfiles = new Map();
  * Custom profiles take precedence over DEFAULT_CAPABILITY_PROFILES on lookup.
  */
 export function registerCapabilityProfile(profile) {
-    _customProfiles.set(profile.name, profile);
+    // Key by the normalized (lowercased) name so lookups through the
+    // case-insensitive resolveAgentAlias match regardless of the casing the
+    // registrant used.
+    _customProfiles.set(profile.name.trim().toLowerCase(), profile);
 }
 /**
  * Get the capability profile for an agent by name.
@@ -667,7 +682,7 @@ export function resolveBriefMode(agentName) {
  * pln#528 — capability matrix DERIVED from the spawn template, so it stays in
  * sync with how each agent is actually invoked (no per-profile duplication).
  *
- * The motivating reality (debrief LeaseUp): codex is spawned with
+ * The motivating reality (a cross-project field debrief): codex is spawned with
  * `--sandbox workspace-write`, which (a) does NOT wire the brainclaw MCP server
  * and (b) puts `.git` outside the sandbox root — so a sandboxed worker can
  * neither call `bclaw_*` nor `git commit`, regardless of the profile's nominal

package/dist/core/agent-files.js

@@ -13,46 +13,46 @@ export { resetMcpCommandCache };
 export const BRAINCLAW_SECTION_START = '<!-- brainclaw:start -->';
 export const BRAINCLAW_SECTION_END = '<!-- brainclaw:end -->';
 export function buildBrainclawSection(storageDir) {
-    return `${BRAINCLAW_SECTION_START}
-## Brainclaw — shared project memory
-
-This project uses brainclaw for shared coordination between humans and agents.
-
-### Session start (required)
-
-1. Run \`brainclaw context\` to load shared state (constraints, decisions, traps, plans, handoffs)
-2. Check **Your open work** for active claims and in-progress plans assigned to you
-3. Respect active claims from other agents — check \`brainclaw claim list\` before editing a claimed scope
-
-### Before finishing (required)
-
-1. Release claims you opened: \`brainclaw claim release <id>\` — or \`brainclaw session-end --auto-release\`
-2. Update completed plan items: \`brainclaw plan update <id> --status done\`
-
-### Recording work
-
-\`\`\`bash
-brainclaw memory create decision "<text>"          # record a decision
-brainclaw memory create constraint "<text>"        # record an active constraint
-brainclaw memory create trap "<text>"              # record a known trap
-brainclaw claim create "<text>" --scope <path>     # claim a scope before editing
-brainclaw plan create "<text>"                     # add a shared work item
-\`\`\`
-
-Memory is stored in \`${storageDir}/\`. Run \`brainclaw doctor\` to verify health.
+    return `${BRAINCLAW_SECTION_START}
+## Brainclaw — shared project memory
+
+This project uses brainclaw for shared coordination between humans and agents.
+
+### Session start (required)
+
+1. Run \`brainclaw context\` to load shared state (constraints, decisions, traps, plans, handoffs)
+2. Check **Your open work** for active claims and in-progress plans assigned to you
+3. Respect active claims from other agents — check \`brainclaw claim list\` before editing a claimed scope
+
+### Before finishing (required)
+
+1. Release claims you opened: \`brainclaw claim release <id>\` — or \`brainclaw session-end --auto-release\`
+2. Update completed plan items: \`brainclaw plan update <id> --status done\`
+
+### Recording work
+
+\`\`\`bash
+brainclaw memory create decision "<text>"          # record a decision
+brainclaw memory create constraint "<text>"        # record an active constraint
+brainclaw memory create trap "<text>"              # record a known trap
+brainclaw claim create "<text>" --scope <path>     # claim a scope before editing
+brainclaw plan create "<text>"                     # add a shared work item
+\`\`\`
+
+Memory is stored in \`${storageDir}/\`. Run \`brainclaw doctor\` to verify health.
 ${BRAINCLAW_SECTION_END}`;
 }
 export function buildHygieneSection() {
-    return `## Brainclaw — required coordination
-
-Before starting work:
-1. Run \`brainclaw context\` (or \`brainclaw context --json\`) to load shared memory
-2. Run \`brainclaw claim list\` — do not edit a file claimed by another agent
-3. Create a plan for significant work: \`brainclaw plan create "<description>"\`
-4. Claim files you will modify: \`brainclaw claim create "<description>" --scope <path>\`
-
-Before finishing:
-1. Run \`brainclaw session-end --auto-release\` — releases claims and updates plans
+    return `## Brainclaw — required coordination
+
+Before starting work:
+1. Run \`brainclaw context\` (or \`brainclaw context --json\`) to load shared memory
+2. Run \`brainclaw claim list\` — do not edit a file claimed by another agent
+3. Create a plan for significant work: \`brainclaw plan create "<description>"\`
+4. Claim files you will modify: \`brainclaw claim create "<description>" --scope <path>\`
+
+Before finishing:
+1. Run \`brainclaw session-end --auto-release\` — releases claims and updates plans
 2. Or manually: \`brainclaw claim release <id>\` and \`brainclaw plan update <id> --status done\``;
 }
 export function hasBrainclawSection(content) {
@@ -727,13 +727,13 @@ export function describeAutoConfigWrite(result) {
     return `✔ ${verb} ${result.label} at ${displayPath}`;
 }
 export function buildClaudeCodeCommandText() {
-    return `Load brainclaw project memory and prepare for coordinated work.
-
-Steps:
-1. Run \`brainclaw context --json\` — load constraints, decisions, traps, plans, handoffs
-2. Run \`brainclaw claim list\` — check what files other agents have claimed
-3. Before editing any file, run \`brainclaw claim create "<description>" --scope <path>\`
-4. Before finishing, run \`brainclaw session-end --auto-release\`
+    return `Load brainclaw project memory and prepare for coordinated work.
+
+Steps:
+1. Run \`brainclaw context --json\` — load constraints, decisions, traps, plans, handoffs
+2. Run \`brainclaw claim list\` — check what files other agents have claimed
+3. Before editing any file, run \`brainclaw claim create "<description>" --scope <path>\`
+4. Before finishing, run \`brainclaw session-end --auto-release\`
 `;
 }
 export function ensureClineMcpConfig(cwd) {
@@ -799,34 +799,34 @@ export function ensureWindsurfMcpConfig(homeDir) {
  */
 export function ensureWindsurfModernRules(cwd) {
     const filePath = path.join(cwd, WINDSURF_MODERN_RULES_RELATIVE_PATH);
-    const content = `# Brainclaw coordination rules
-
-Brainclaw is the shared coordination layer. Use its MCP facades first — the CLI is only a fallback when MCP is unavailable.
-
-## Session start
-
-Call \`bclaw_work(intent)\`. It loads memory (constraints, decisions, traps, plans, handoffs), resolves the claim, and starts a session in a single call.
-
-- \`bclaw_work(intent: "resume")\` — continue existing work (auto-surfaces the context diff).
-- \`bclaw_work(intent: "execute", scope: "<path>", task: "<text>")\` — start new work and claim the scope.
-- \`bclaw_work(intent: "consult")\` — read-only context without claiming.
-
-## During work
-
-- Mark plan steps done: \`bclaw_complete_step(planId, stepId)\`.
-- Read the inbox: \`bclaw_read_inbox\`.
-- Record notes, decisions, traps: \`bclaw_write_note\`, \`bclaw_create(entity, data)\`.
-
-## To coordinate with other agents
-
-\`bclaw_coordinate(intent)\` — \`assign\`, \`consult\`, \`review\`, or \`reroute\`.
-
-## Before finishing
-
-- Release your claims: \`bclaw_release_claim(id)\`.
-- Close the session: \`bclaw_session_end\` (auto-releases remaining claims).
-
-CLI fallback only when MCP is unavailable: \`brainclaw context\` / \`brainclaw session-end --auto-release\`.
+    const content = `# Brainclaw coordination rules
+
+Brainclaw is the shared coordination layer. Use its MCP facades first — the CLI is only a fallback when MCP is unavailable.
+
+## Session start
+
+Call \`bclaw_work(intent)\`. It loads memory (constraints, decisions, traps, plans, handoffs), resolves the claim, and starts a session in a single call.
+
+- \`bclaw_work(intent: "resume")\` — continue existing work (auto-surfaces the context diff).
+- \`bclaw_work(intent: "execute", scope: "<path>", task: "<text>")\` — start new work and claim the scope.
+- \`bclaw_work(intent: "consult")\` — read-only context without claiming.
+
+## During work
+
+- Mark plan steps done: \`bclaw_complete_step(planId, stepId)\`.
+- Read the inbox: \`bclaw_read_inbox\`.
+- Record notes, decisions, traps: \`bclaw_write_note\`, \`bclaw_create(entity, data)\`.
+
+## To coordinate with other agents
+
+\`bclaw_coordinate(intent)\` — \`assign\`, \`consult\`, \`review\`, or \`reroute\`.
+
+## Before finishing
+
+- Release your claims: \`bclaw_release_claim(id)\`.
+- Close the session: \`bclaw_session_end\` (auto-releases remaining claims).
+
+CLI fallback only when MCP is unavailable: \`brainclaw context\` / \`brainclaw session-end --auto-release\`.
 `;
     const { created, updated } = writeTextFileIfChanged(filePath, content);
     return {
@@ -840,22 +840,22 @@ CLI fallback only when MCP is unavailable: \`brainclaw context\` / \`brainclaw s
 }
 export function ensureCopilotSkill(cwd) {
     const filePath = path.join(cwd, '.github', 'skills', 'brainclaw-context', 'SKILL.md');
-    const content = `---
-name: brainclaw-context
-description: "Use this skill when you need the latest Brainclaw context, active plans, constraints, traps, or handoffs before coding. Trigger phrases: refresh project memory, load brainclaw context, inspect active plans, inspect constraints."
----
-
-# Brainclaw Context
-
-Fetch live project memory before significant edits. Prefer the Brainclaw MCP facade; use the CLI only as a fallback when MCP is unavailable.
-
-## Steps
-
-1. Call \`bclaw_work(intent: "resume")\` to continue existing work, or \`bclaw_work(intent: "consult")\` for read-only context. The response contains active plans, constraints, decisions, traps, and handoffs.
-2. Prefer Brainclaw state over stale assumptions from older instructions or prior sessions.
-3. Coordinate with other agents via \`bclaw_coordinate(intent)\` (\`assign\`, \`consult\`, \`review\`).
-
-CLI fallback: \`brainclaw context --json\` if the MCP server is not reachable.
+    const content = `---
+name: brainclaw-context
+description: "Use this skill when you need the latest Brainclaw context, active plans, constraints, traps, or handoffs before coding. Trigger phrases: refresh project memory, load brainclaw context, inspect active plans, inspect constraints."
+---
+
+# Brainclaw Context
+
+Fetch live project memory before significant edits. Prefer the Brainclaw MCP facade; use the CLI only as a fallback when MCP is unavailable.
+
+## Steps
+
+1. Call \`bclaw_work(intent: "resume")\` to continue existing work, or \`bclaw_work(intent: "consult")\` for read-only context. The response contains active plans, constraints, decisions, traps, and handoffs.
+2. Prefer Brainclaw state over stale assumptions from older instructions or prior sessions.
+3. Coordinate with other agents via \`bclaw_coordinate(intent)\` (\`assign\`, \`consult\`, \`review\`).
+
+CLI fallback: \`brainclaw context --json\` if the MCP server is not reachable.
 `;
     const { created, updated } = writeTextFileIfChanged(filePath, content);
     return {
@@ -877,24 +877,24 @@ CLI fallback: \`brainclaw context --json\` if the MCP server is not reachable.
  */
 export function ensureUniversalBrainclawSkill(cwd) {
     const filePath = path.join(cwd, UNIVERSAL_SKILL_RELATIVE_PATH);
-    const content = `---
-name: brainclaw
-description: 'Load and act on Brainclaw project memory, active claims, plans, traps, and handoffs before code changes. Trigger: refresh brainclaw context, check active claims, load coordination state.'
-allowed-tools: 'Read Bash(npx brainclaw:*)'
----
-
-# Brainclaw
-
-Load the shared coordination state before any significant code change. Prefer the Brainclaw MCP facade; the CLI is a fallback when MCP is not reachable.
-
-## Steps
-
-1. Call \`bclaw_work(intent)\` — \`resume\` to continue existing work, \`execute\` to claim a new scope, or \`consult\` for read-only context. The response gives you memory, active claims, plans, traps, and handoffs.
-2. Respect active claims from other agents reported in the response; do not edit a claimed scope unless you own the claim.
-3. Use \`bclaw_coordinate(intent)\` to assign, consult, or review other agents when needed.
-4. When done, call \`bclaw_session_end\` (auto-releases your remaining claims).
-
-CLI fallback only: \`brainclaw context --json\` / \`brainclaw claim create\` / \`brainclaw session-end --auto-release\` if the MCP server is unavailable.
+    const content = `---
+name: brainclaw
+description: 'Load and act on Brainclaw project memory, active claims, plans, traps, and handoffs before code changes. Trigger: refresh brainclaw context, check active claims, load coordination state.'
+allowed-tools: 'Read Bash(npx brainclaw:*)'
+---
+
+# Brainclaw
+
+Load the shared coordination state before any significant code change. Prefer the Brainclaw MCP facade; the CLI is a fallback when MCP is not reachable.
+
+## Steps
+
+1. Call \`bclaw_work(intent)\` — \`resume\` to continue existing work, \`execute\` to claim a new scope, or \`consult\` for read-only context. The response gives you memory, active claims, plans, traps, and handoffs.
+2. Respect active claims from other agents reported in the response; do not edit a claimed scope unless you own the claim.
+3. Use \`bclaw_coordinate(intent)\` to assign, consult, or review other agents when needed.
+4. When done, call \`bclaw_session_end\` (auto-releases your remaining claims).
+
+CLI fallback only: \`brainclaw context --json\` / \`brainclaw claim create\` / \`brainclaw session-end --auto-release\` if the MCP server is unavailable.
 `;
     const { created, updated } = writeTextFileIfChanged(filePath, content);
     return {
@@ -1005,19 +1005,19 @@ export function ensureVscodeExtensionRecommendation(cwd) {
 }
 export function ensureCursorMdc(cwd) {
     const filePath = path.join(cwd, '.cursor', 'rules', 'brainclaw-mcp-shim.mdc');
-    const content = `---
-description: Use this rule when work depends on live Brainclaw memory or active project rules.
-globs: "**/*"
-alwaysApply: true
----
-
-Brainclaw is the shared coordination layer. Call the MCP facade first; the CLI is only a fallback when MCP is not reachable.
-
-Before significant edits or when asked about project rules, call \`bclaw_work(intent: "consult")\` (or \`"resume"\` if continuing a task) via the Brainclaw MCP server. The response carries active claims, in-progress plans, constraints, decisions, traps, and handoffs.
-
-If the response lists active claims or in-progress plans, follow them before editing. Use \`bclaw_coordinate(intent)\` to dispatch, consult, or review other agents.
-
-CLI fallback only when MCP is unavailable: \`brainclaw context --json\`.
+    const content = `---
+description: Use this rule when work depends on live Brainclaw memory or active project rules.
+globs: "**/*"
+alwaysApply: true
+---
+
+Brainclaw is the shared coordination layer. Call the MCP facade first; the CLI is only a fallback when MCP is not reachable.
+
+Before significant edits or when asked about project rules, call \`bclaw_work(intent: "consult")\` (or \`"resume"\` if continuing a task) via the Brainclaw MCP server. The response carries active claims, in-progress plans, constraints, decisions, traps, and handoffs.
+
+If the response lists active claims or in-progress plans, follow them before editing. Use \`bclaw_coordinate(intent)\` to dispatch, consult, or review other agents.
+
+CLI fallback only when MCP is unavailable: \`brainclaw context --json\`.
 `;
     const { created, updated } = writeTextFileIfChanged(filePath, content);
     return {