brainclaw 1.9.0 → 1.10.0

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, resolveCurrentSessionId, 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';
@@ -139,59 +160,70 @@ export function runSwitch(projectRef, options = {}) {
     }
     // --list: show available projects
     if (options.list) {
-        listProjects(wsRoot, options.json ?? false);
+        listProjects(wsRoot, cwd, options.json ?? false);
         return;
     }
-    // --clear: remove active project
+    // --clear: remove active project. Session-scoped by default (F3) — clearing
+    // the SHARED global pointer is an opt-in (--global) so one agent's clear no
+    // longer wipes every other agent's resolution.
     if (options.clear) {
-        const session = loadCurrentSession(cwd);
-        if (session?.active_project) {
-            const { active_project: _removed, ...rest } = session;
-            saveCurrentSession(rest, cwd);
+        let scope;
+        if (options.global) {
+            clearActiveProject(wsRoot);
+            scope = 'global';
+        }
+        else {
+            const session = loadCurrentSession(cwd);
+            if (session?.active_project) {
+                const { active_project: _removed, ...rest } = session;
+                saveCurrentSession(rest, cwd);
+            }
+            scope = 'session';
         }
-        clearActiveProject(wsRoot);
         if (options.json) {
-            console.log(JSON.stringify({ cleared: true }));
+            console.log(JSON.stringify({ cleared: true, scope }));
         }
         else {
-            console.log('✔ Active project cleared. Commands will use current directory.');
+            const hint = scope === 'session' ? ' (session-scoped)' : ' (global)';
+            console.log(`✔ Active project cleared${hint}. Commands will use current directory.`);
         }
         return;
     }
     // No argument: show current active project
     if (!projectRef) {
-        showCurrent(wsRoot, options.json ?? false);
+        showCurrent(wsRoot, cwd, options.json ?? false);
         return;
     }
     // Switch to project
-    const resolved = resolveProjectRef(projectRef, cwd);
-    if (!resolved) {
-        console.error(`Error: cannot resolve project "${projectRef}".`);
-        console.error('Use `brainclaw switch --list` to see available projects.');
-        process.exit(1);
-    }
-    let projectName;
-    try {
-        const config = loadConfig(resolved);
-        projectName = config.project_name;
-    }
-    catch {
-        // name is optional
-    }
     const now = new Date().toISOString();
-    const session = loadCurrentSession(cwd);
-    const scopedToSession = options.session ?? !!session;
     let scope;
-    if (scopedToSession && session) {
-        // Write to session state — only this agent sees this switch
-        saveCurrentSession({
-            ...session,
-            active_project: { path: resolved, name: projectName, switched_at: now },
-        }, cwd);
-        scope = 'session';
-    }
-    else {
-        // Fall back to global active-project.json
+    let switchedPath;
+    let switchedName;
+    if (options.global) {
+        // Opt-in, audited: set the SHARED workspace default for every agent on the
+        // host. Bypasses the session entirely (an operator setting a default).
+        // Resolve store-chain children AND cross-project links (mirror switchProject)
+        // so `switch <linked> --global` matches what --list shows and what the
+        // session path can target (Codex final review F3-F5 finding).
+        let resolved = resolveProjectRef(projectRef, cwd);
+        if (!resolved) {
+            try {
+                const linkResolved = resolveProjectCwd(projectRef, cwd);
+                if (linkResolved !== cwd)
+                    resolved = linkResolved;
+            }
+            catch { /* falls through to the error below */ }
+        }
+        if (!resolved) {
+            console.error(`Error: cannot resolve project "${projectRef}".`);
+            console.error('Use `brainclaw switch --list` to see available projects.');
+            process.exit(1);
+        }
+        let projectName;
+        try {
+            projectName = loadConfig(resolved).project_name;
+        }
+        catch { /* name is optional */ }
         saveActiveProject(wsRoot, {
             path: resolved,
             name: projectName,
@@ -199,21 +231,47 @@ export function runSwitch(projectRef, options = {}) {
             switched_by: process.env.BRAINCLAW_AGENT_NAME ?? process.env.USER ?? 'unknown',
         });
         scope = 'global';
+        switchedPath = resolved;
+        switchedName = projectName;
+    }
+    else {
+        // F3 default: session-scoped + isolated. Delegate to switchProject — the
+        // safe model that auto-creates the session, honours an explicit
+        // BRAINCLAW_SESSION_ID (resolveCurrentSessionId returns it WITHOUT
+        // persisting, so the session file must be created), resolves cross-project
+        // links, and never touches the shared global pointer.
+        try {
+            const explicitSessionId = resolveCurrentSessionId(process.env, cwd) || undefined;
+            const result = switchProject(projectRef, { cwd, sessionOnly: true, sessionId: explicitSessionId });
+            scope = 'session';
+            switchedPath = result.path;
+            switchedName = result.name;
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            console.error('Use `brainclaw switch --list` to see available projects.');
+            process.exit(1);
+        }
     }
     if (options.json) {
-        console.log(JSON.stringify({ switched: true, path: resolved, name: projectName, scope }));
+        console.log(JSON.stringify({ switched: true, path: switchedPath, name: switchedName, scope }));
     }
     else {
-        const rel = path.relative(wsRoot, resolved) || '.';
-        const scopeHint = scope === 'session' ? ' (session-scoped)' : '';
-        console.log(`✔ Switched to ${projectName ? `"${projectName}" (${rel})` : rel}${scopeHint}`);
+        const rel = path.relative(wsRoot, switchedPath) || '.';
+        const scopeHint = scope === 'session' ? ' (session-scoped)' : ' (global — all agents)';
+        console.log(`✔ Switched to ${switchedName ? `"${switchedName}" (${rel})` : rel}${scopeHint}`);
     }
 }
-function showCurrent(wsRoot, json) {
-    const active = loadActiveProject(wsRoot);
+function showCurrent(wsRoot, cwd, json) {
+    // F5: prefer the session's own active project so an agent sees its own
+    // session-scoped switch, not just the shared global pointer.
+    const sessionActive = loadCurrentSession(cwd)?.active_project;
+    const globalActive = loadActiveProject(wsRoot);
+    const active = sessionActive ?? globalActive;
+    const source = sessionActive ? 'session' : globalActive ? 'global' : 'none';
     if (!active) {
         if (json) {
-            console.log(JSON.stringify({ active: false }));
+            console.log(JSON.stringify({ active: false, scope: 'none' }));
         }
         else {
             console.log('No active project. Commands use current directory.');
@@ -222,67 +280,41 @@ function showCurrent(wsRoot, json) {
         return;
     }
     const rel = path.relative(wsRoot, active.path) || '.';
+    const switchedBy = 'switched_by' in active ? active.switched_by : undefined;
     if (json) {
-        console.log(JSON.stringify({ active: true, ...active, relative_path: rel }));
+        console.log(JSON.stringify({ active: true, ...active, relative_path: rel, scope: source }));
     }
     else {
-        console.log(`Active project: ${active.name ? `"${active.name}" (${rel})` : rel}`);
+        const scopeHint = source === 'session' ? ' (session-scoped)' : ' (global — all agents)';
+        console.log(`Active project: ${active.name ? `"${active.name}" (${rel})` : rel}${scopeHint}`);
         console.log(`  switched at: ${active.switched_at}`);
-        if (active.switched_by)
-            console.log(`  switched by: ${active.switched_by}`);
+        if (switchedBy)
+            console.log(`  switched by: ${switchedBy}`);
     }
 }
-function listProjects(wsRoot, json) {
-    const active = loadActiveProject(wsRoot);
-    const projects = [];
-    // Add workspace root itself
-    if (memoryExists(wsRoot)) {
-        try {
-            const config = loadConfig(wsRoot);
-            projects.push({
-                name: config.project_name,
-                path: wsRoot,
-                relative_path: '.',
-                active: active?.path === wsRoot,
-            });
-        }
-        catch {
-            projects.push({
-                path: wsRoot,
-                relative_path: '.',
-                active: active?.path === wsRoot,
-            });
-        }
-    }
-    // Discover child projects (depth 7 covers deep workspace layouts like /srv/dev/repos/global/applications/*/...)
-    const children = scanNestedBrainclawProjects(wsRoot, 7);
-    for (const child of children) {
-        const childPath = path.resolve(child.path);
-        if (childPath === wsRoot)
-            continue;
-        const rel = path.relative(wsRoot, childPath) || '.';
-        projects.push({
-            name: child.project_name,
-            path: childPath,
-            relative_path: rel,
-            active: active?.path === childPath,
-        });
-    }
+function listProjects(wsRoot, cwd, json) {
+    // F5: delegate to the session-aware lister so the active marker reflects the
+    // agent's own session active project, falling back to the global pointer.
+    const result = listAvailableProjectsForSession(cwd);
     if (json) {
-        console.log(JSON.stringify({ workspace: wsRoot, projects }, null, 2));
+        console.log(JSON.stringify({
+            workspace: result.workspace_root,
+            active_source: result.active_source,
+            projects: result.projects,
+        }, null, 2));
         return;
     }
-    if (projects.length === 0) {
+    if (result.projects.length === 0) {
         console.log('No brainclaw projects found in this workspace.');
         return;
     }
-    console.log(`Projects in ${wsRoot}:\n`);
-    for (const p of projects) {
+    console.log(`Projects in ${result.workspace_root}:\n`);
+    for (const p of result.projects) {
         const marker = p.active ? '→ ' : '  ';
         const name = p.name ? `${p.name} (${p.relative_path})` : p.relative_path;
         console.log(`${marker}${name}`);
     }
-    if (!active) {
+    if (result.active_source === 'none') {
         console.log('\nNo active project. Use `brainclaw switch <project>` to set one.');
     }
 }

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,58 @@ 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 editing unfamiliar code (Code Map)
+
+Don't grep the repo blind. Orient with the Code Map first:
+
+\`\`\`bash
+brainclaw code-map brief <symbol-or-path>   # ranked reading list + related decisions/traps (MCP: bclaw_code_brief)
+brainclaw code-map find <name>              # locate a symbol/class/component (MCP: bclaw_code_find)
+brainclaw code-map status                   # freshness
+brainclaw code-map refresh --all            # when status is missing_index
+brainclaw code-map refresh --changed        # when status is stale_*
+\`\`\`
+
+### 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 +739,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 +811,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 +852,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 +889,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 +1017,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 {