brainclaw 0.19.12 → 0.19.14

package/dist/core/agent-files.js

@@ -13,21 +13,21 @@ This project uses brainclaw for shared coordination between humans and agents.
 
 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
+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\`
+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
+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.
@@ -38,9 +38,9 @@ export function buildHygieneSection() {
 
 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>\`
+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
@@ -327,13 +327,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) {

package/dist/core/ai-surface-inventory.js

@@ -0,0 +1,321 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+function run(command, args, timeout = 5000) {
+    try {
+        const result = spawnSync(command, args, { encoding: 'utf-8', timeout, windowsHide: true });
+        return { ok: result.status === 0, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+    }
+    catch {
+        return { ok: false, stdout: '', stderr: '' };
+    }
+}
+function listRunningProcesses(platform) {
+    if (platform === 'win32') {
+        const result = run('tasklist', ['/FO', 'CSV', '/NH'], 8000);
+        if (!result.ok)
+            return [];
+        return result.stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => line.replace(/^"|"$/g, '').split('","')[0] ?? '')
+            .map((name) => name.replace(/\.exe$/i, '').toLowerCase())
+            .filter(Boolean);
+    }
+    const result = run('ps', ['-A', '-o', 'comm='], 8000);
+    if (!result.ok)
+        return [];
+    return result.stdout
+        .split(/\r?\n/)
+        .map((line) => path.basename(line.trim()).toLowerCase())
+        .filter(Boolean);
+}
+function detectWindowsAppxPackages() {
+    if (process.platform !== 'win32')
+        return [];
+    const script = [
+        "$patterns = @('OpenAI.ChatGPT-Desktop', '*ChatGPT*', 'Claude', '*Claude*');",
+        '$packages = foreach ($pattern in $patterns) { Get-AppxPackage -Name $pattern -ErrorAction SilentlyContinue };',
+        '$packages | Sort-Object Name -Unique |',
+        'ForEach-Object { "{0}`t{1}`t{2}" -f $_.Name, $_.Version.ToString(), $_.InstallLocation }',
+    ].join(' ');
+    const result = run('powershell', ['-NoProfile', '-Command', script], 15000);
+    if (!result.ok || !result.stdout.trim())
+        return [];
+    return result.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [name, version, installLocation] = line.split('\t');
+        return {
+            name: name ?? '',
+            version: version || undefined,
+            installLocation: installLocation || undefined,
+        };
+    })
+        .filter((row) => row.name);
+}
+function detectBrowsers(homeDir, platform) {
+    const browsers = new Set();
+    const commands = platform === 'win32'
+        ? ['msedge', 'chrome', 'firefox']
+        : platform === 'darwin'
+            ? ['open', 'google-chrome', 'firefox', 'safari']
+            : ['xdg-open', 'google-chrome', 'chromium-browser', 'chromium', 'firefox'];
+    for (const command of commands) {
+        const result = run(platform === 'win32' ? 'where' : 'which', [command], 3000);
+        if (result.ok)
+            browsers.add(command);
+    }
+    const footprintPaths = platform === 'win32'
+        ? [
+            path.join(process.env.LOCALAPPDATA ?? '', 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+            path.join(process.env.LOCALAPPDATA ?? '', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+            path.join(process.env.PROGRAMFILES ?? 'C:\\Program Files', 'Mozilla Firefox', 'firefox.exe'),
+        ]
+        : platform === 'darwin'
+            ? [
+                '/Applications/Google Chrome.app',
+                '/Applications/Firefox.app',
+                '/Applications/Safari.app',
+                path.join(homeDir, 'Applications', 'Google Chrome.app'),
+            ]
+            : [
+                path.join(homeDir, '.local', 'share', 'applications'),
+                '/usr/share/applications',
+            ];
+    for (const footprint of footprintPaths) {
+        if (fs.existsSync(footprint))
+            browsers.add(path.basename(footprint).toLowerCase());
+    }
+    return [...browsers];
+}
+function matchProcess(processNames, pattern) {
+    return processNames.some((name) => pattern.test(name));
+}
+function findExistingPath(paths) {
+    return paths.find((candidate) => candidate && fs.existsSync(candidate));
+}
+function matchWindowsAppxPackage(packages, pattern) {
+    return packages.find((pkg) => pattern.test(pkg.name));
+}
+export function buildAiSurfaceInventory(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? os.homedir();
+    const processNames = options.processNames ?? listRunningProcesses(platform);
+    const windowsAppxPackages = options.windowsAppxPackages ?? (platform === 'win32' ? detectWindowsAppxPackages() : []);
+    const browsers = options.browsers ?? detectBrowsers(homeDir, platform);
+    const surfaces = [];
+    const chatGptAppx = platform === 'win32'
+        ? matchWindowsAppxPackage(windowsAppxPackages, /OpenAI\.ChatGPT-Desktop|ChatGPT/i)
+        : undefined;
+    const chatGptRunning = matchProcess(processNames, /^chatgpt$/i);
+    const chatGptInstallLocation = platform === 'darwin'
+        ? findExistingPath([
+            '/Applications/ChatGPT.app',
+            path.join(homeDir, 'Applications', 'ChatGPT.app'),
+        ])
+        : platform === 'win32'
+            ? chatGptAppx?.installLocation
+            : undefined;
+    const chatGptDetected = Boolean(chatGptRunning || chatGptInstallLocation || chatGptAppx);
+    surfaces.push({
+        id: `surf_chatgpt_${platform}`,
+        product_name: 'chatgpt',
+        display_name: 'ChatGPT Desktop',
+        surface_kind: platform === 'linux' ? 'web_surface' : 'desktop_ai_app',
+        variant: platform === 'win32' ? 'windows_store' : platform === 'darwin' ? 'macos_app' : 'web',
+        status: chatGptRunning ? 'detected_running' : chatGptDetected ? 'detected_install' : (platform === 'linux' && browsers.length > 0 ? 'limited' : 'not_detected'),
+        running: chatGptRunning,
+        install_source: chatGptAppx ? 'appx' : chatGptInstallLocation ? 'bundle' : platform === 'linux' && browsers.length > 0 ? 'web' : undefined,
+        install_location: chatGptInstallLocation,
+        version: chatGptAppx?.version,
+        detection_sources: [
+            ...(chatGptAppx ? [`AppX package: ${chatGptAppx.name}`] : []),
+            ...(chatGptInstallLocation ? [`install path: ${chatGptInstallLocation}`] : []),
+            ...(chatGptRunning ? ['running process: ChatGPT'] : []),
+            ...(platform === 'linux' && browsers.length > 0 ? ['browser availability'] : []),
+        ],
+        supports_mcp: 'unknown',
+        supports_remote_connectors: 'unknown',
+        supports_local_config: 'limited',
+        supports_context_export: 'yes',
+        supports_prompt_bootstrap: 'yes',
+        supports_safe_write_actions: 'limited',
+        interactive_only: true,
+        can_edit_code: false,
+        recommended_uses: [
+            'generate visual concepts and rough assets',
+            'draft product copy and polished summaries',
+            'prepare slide, email, or launch material from project context',
+        ],
+    });
+    const claudeRunning = matchProcess(processNames, /^claude$/i);
+    const claudeAppx = platform === 'win32'
+        ? matchWindowsAppxPackage(windowsAppxPackages, /^Claude$/i)
+        : undefined;
+    const claudeInstallLocation = platform === 'darwin'
+        ? findExistingPath([
+            '/Applications/Claude.app',
+            path.join(homeDir, 'Applications', 'Claude.app'),
+        ])
+        : platform === 'win32'
+            ? (claudeAppx?.installLocation ?? findExistingPath([
+                path.join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Claude', 'Claude.exe'),
+                path.join(process.env.LOCALAPPDATA ?? '', 'AnthropicClaude', 'Claude.exe'),
+                path.join(process.env.LOCALAPPDATA ?? '', 'Claude'),
+                path.join(process.env.APPDATA ?? '', 'Claude'),
+            ]))
+            : undefined;
+    const claudeDetected = Boolean(claudeRunning || claudeInstallLocation);
+    surfaces.push({
+        id: `surf_claude_desktop_${platform}`,
+        product_name: 'claude',
+        display_name: 'Claude Desktop',
+        surface_kind: platform === 'linux' ? 'web_surface' : 'desktop_ai_app',
+        variant: platform === 'darwin' ? 'macos_app' : platform === 'win32' ? 'desktop' : 'web',
+        status: claudeRunning ? 'detected_running' : claudeDetected ? 'detected_install' : (platform === 'linux' && browsers.length > 0 ? 'limited' : 'not_detected'),
+        running: claudeRunning,
+        install_source: claudeAppx ? 'appx' : claudeInstallLocation ? 'bundle' : platform === 'linux' && browsers.length > 0 ? 'web' : undefined,
+        install_location: claudeInstallLocation,
+        version: claudeAppx?.version,
+        detection_sources: [
+            ...(claudeAppx ? [`AppX package: ${claudeAppx.name}`] : []),
+            ...(claudeInstallLocation ? [`install path: ${claudeInstallLocation}`] : []),
+            ...(claudeRunning ? ['running process: Claude'] : []),
+            ...(platform === 'linux' && browsers.length > 0 ? ['browser availability'] : []),
+        ],
+        supports_mcp: platform === 'linux' ? 'limited' : 'yes',
+        supports_remote_connectors: platform === 'linux' ? 'limited' : 'yes',
+        supports_local_config: platform === 'linux' ? 'limited' : 'yes',
+        supports_context_export: 'yes',
+        supports_prompt_bootstrap: 'yes',
+        supports_safe_write_actions: 'limited',
+        interactive_only: true,
+        can_edit_code: false,
+        recommended_uses: [
+            'project synthesis and reasoning-heavy drafting',
+            'doc and handoff preparation around a repo',
+            'MCP-oriented project context consumption when supported',
+        ],
+    });
+    surfaces.push({
+        id: `surf_claude_cowork_${platform}`,
+        product_name: 'claude-cowork',
+        display_name: 'Claude Cowork',
+        surface_kind: 'desktop_embedded_capability',
+        variant: 'embedded',
+        parent_surface_id: `surf_claude_desktop_${platform}`,
+        status: claudeDetected || claudeRunning ? 'limited' : 'not_detected',
+        running: false,
+        detection_sources: claudeDetected || claudeRunning
+            ? ['parent capability: Claude Desktop']
+            : [],
+        supports_mcp: 'limited',
+        supports_remote_connectors: 'limited',
+        supports_local_config: 'limited',
+        supports_context_export: 'yes',
+        supports_prompt_bootstrap: 'yes',
+        supports_safe_write_actions: 'limited',
+        interactive_only: true,
+        can_edit_code: false,
+        recommended_uses: [
+            'parallel collaboration on non-code deliverables',
+            'task follow-up and structured handoff work',
+            'operator-facing drafting without repo edits',
+        ],
+    });
+    const geminiCliPath = findExistingPath([
+        path.join(homeDir, '.gemini', 'antigravity'),
+    ]);
+    const geminiCliRunning = matchProcess(processNames, /gemini|antigravity/i);
+    const geminiCliVersion = run('gemini', ['--version'], 3000);
+    const geminiCliDetected = Boolean(geminiCliPath || geminiCliRunning || geminiCliVersion.ok);
+    surfaces.push({
+        id: `surf_gemini_cli_${platform}`,
+        product_name: 'gemini',
+        display_name: 'Gemini CLI / Antigravity',
+        surface_kind: 'cli_agent',
+        variant: 'antigravity',
+        status: geminiCliRunning ? 'detected_running' : geminiCliDetected ? 'brainclaw_ready' : 'not_detected',
+        running: geminiCliRunning,
+        install_source: geminiCliPath ? 'config_footprint' : geminiCliVersion.ok ? 'cli' : undefined,
+        install_location: geminiCliPath,
+        version: geminiCliVersion.ok ? geminiCliVersion.stdout.trim() : undefined,
+        detection_sources: [
+            ...(geminiCliPath ? [`config path: ${geminiCliPath}`] : []),
+            ...(geminiCliVersion.ok ? ['gemini --version'] : []),
+            ...(geminiCliRunning ? ['running process: gemini/antigravity'] : []),
+        ],
+        supports_mcp: 'yes',
+        supports_remote_connectors: 'unknown',
+        supports_local_config: 'yes',
+        supports_context_export: 'yes',
+        supports_prompt_bootstrap: 'yes',
+        supports_safe_write_actions: 'limited',
+        interactive_only: false,
+        can_edit_code: false,
+        recommended_uses: [
+            'CLI-driven analysis and automation-adjacent tasks',
+            'repo-adjacent reasoning without changing the editing agent',
+            'structured use of local MCP and exported context',
+        ],
+    });
+    const geminiWebAvailable = browsers.length > 0;
+    surfaces.push({
+        id: `surf_gemini_web_${platform}`,
+        product_name: 'gemini',
+        display_name: 'Gemini Web',
+        surface_kind: 'web_surface',
+        variant: 'browser',
+        status: geminiWebAvailable ? 'limited' : 'not_detected',
+        running: matchProcess(processNames, /chrome|msedge|firefox|safari/i),
+        install_source: geminiWebAvailable ? 'web' : undefined,
+        detection_sources: geminiWebAvailable ? [`browser availability: ${browsers.join(', ')}`] : [],
+        supports_mcp: 'unknown',
+        supports_remote_connectors: 'unknown',
+        supports_local_config: 'limited',
+        supports_context_export: 'yes',
+        supports_prompt_bootstrap: 'yes',
+        supports_safe_write_actions: 'limited',
+        interactive_only: true,
+        can_edit_code: false,
+        recommended_uses: [
+            'quick research and synthesis in a browser surface',
+            'lightweight planning, summaries, and exploration',
+            'prompt-bootstrap workflows when no native integration exists',
+        ],
+    });
+    return surfaces;
+}
+export function renderAiSurfaceSummary(surfaces) {
+    const detected = surfaces.filter((surface) => surface.status !== 'not_detected');
+    const lines = [];
+    lines.push(`AI surfaces: ${detected.length}/${surfaces.length} detected or available`);
+    for (const surface of detected) {
+        const details = [surface.surface_kind, surface.status];
+        if (surface.variant)
+            details.push(surface.variant);
+        if (surface.version)
+            details.push(surface.version);
+        lines.push(`  - ${surface.display_name} (${details.join(', ')})`);
+    }
+    return lines;
+}
+export function renderAiSurfaceUsageHints(surfaces) {
+    const eligible = surfaces.filter((surface) => surface.status !== 'not_detected');
+    const lines = [];
+    for (const surface of eligible) {
+        if (surface.recommended_uses.length === 0)
+            continue;
+        lines.push(`${surface.display_name}:`);
+        for (const useCase of surface.recommended_uses.slice(0, 2)) {
+            lines.push(`  - ${useCase}`);
+        }
+    }
+    return lines;
+}
+//# sourceMappingURL=ai-surface-inventory.js.map

package/dist/core/ai-surface-tasks.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import { JsonStore } from './json-store.js';
+import { resolveEntityDir, withStoreLock } from './io.js';
+import { AiSurfaceTaskRequestSchema } from './schema.js';
+function surfaceTasksDir(cwd, mode = 'read') {
+    return resolveEntityDir('surface-tasks', cwd ?? process.cwd(), mode);
+}
+function surfaceTaskStore(cwd) {
+    return new JsonStore({
+        dirPath: surfaceTasksDir(cwd, 'read'),
+        documentType: 'ai_surface_task',
+        getId: (task) => task.id,
+        sort: (a, b) => a.created_at.localeCompare(b.created_at),
+    });
+}
+export function ensureAiSurfaceTasksDir(cwd) {
+    const dir = surfaceTasksDir(cwd, 'write');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+export function saveAiSurfaceTask(task, cwd) {
+    withStoreLock(cwd, () => {
+        ensureAiSurfaceTasksDir(cwd);
+        const writeStore = new JsonStore({
+            dirPath: surfaceTasksDir(cwd, 'write'),
+            documentType: 'ai_surface_task',
+            getId: (entry) => entry.id,
+            sort: (a, b) => a.created_at.localeCompare(b.created_at),
+        });
+        writeStore.save(AiSurfaceTaskRequestSchema.parse(task));
+    });
+}
+export function loadAiSurfaceTask(id, cwd) {
+    return surfaceTaskStore(cwd).load(id);
+}
+export function listAiSurfaceTasks(cwd) {
+    return surfaceTaskStore(cwd).list();
+}
+//# sourceMappingURL=ai-surface-tasks.js.map

package/dist/core/claude-desktop-extension.js

@@ -0,0 +1,224 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { memoryExists } from './io.js';
+const CLAUDE_DESKTOP_TOOLS = [
+    { name: 'bclaw_session_start', description: 'Open a Brainclaw session and surface Claude-targeted tasks plus compact execution context.' },
+    { name: 'bclaw_get_context', description: 'Retrieve ranked Brainclaw project context for the current task or path.' },
+    { name: 'bclaw_list_surface_tasks', description: 'List queued or completed Brainclaw tasks delegated to Claude Desktop.' },
+    { name: 'bclaw_update_surface_task', description: 'Mark a delegated Claude Desktop task as in progress or completed.' },
+];
+export function buildClaudeDesktopExtension(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    if (!memoryExists(cwd)) {
+        throw new Error('Project memory not initialized. Run `brainclaw init` first.');
+    }
+    const workspaceDir = path.resolve(options.workspaceDir ?? path.join(cwd, 'internal-docs', 'desktop-extensions', 'claude-desktop-brainclaw'));
+    const outputFile = path.resolve(options.outputFile ?? path.join(cwd, 'internal-docs', 'desktop-extensions', 'brainclaw-claude-desktop.mcpb'));
+    if (outputFile.startsWith(`${workspaceDir}${path.sep}`) || outputFile === workspaceDir) {
+        throw new Error('The .mcpb output file must live outside the extension workspace directory.');
+    }
+    const projectRoot = path.resolve(options.projectRoot ?? cwd);
+    const runtimeRoot = path.resolve(options.runtimeRootOverride ?? resolveRuntimeRoot());
+    const packageRoot = path.resolve(options.packageRootOverride ?? findPackageRoot(runtimeRoot));
+    const metadata = readPackageMetadata(packageRoot);
+    const copiedDependencies = options.dependenciesOverride ?? resolveRuntimeDependencies(packageRoot);
+    fs.rmSync(workspaceDir, { recursive: true, force: true });
+    fs.mkdirSync(workspaceDir, { recursive: true });
+    fs.cpSync(runtimeRoot, path.join(workspaceDir, 'runtime'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceDir, 'server'), { recursive: true });
+    fs.mkdirSync(path.dirname(outputFile), { recursive: true });
+    for (const dep of copiedDependencies) {
+        const sourceDir = path.join(packageRoot, 'node_modules', dep);
+        if (!fs.existsSync(sourceDir)) {
+            throw new Error(`Missing runtime dependency for Claude Desktop extension: ${dep}`);
+        }
+        fs.cpSync(sourceDir, path.join(workspaceDir, 'node_modules', dep), { recursive: true });
+    }
+    const version = metadata.version ?? '0.0.0';
+    const manifestPath = path.join(workspaceDir, 'manifest.json');
+    const entryPointPath = path.join(workspaceDir, 'server', 'index.js');
+    const packageJsonPath = path.join(workspaceDir, 'package.json');
+    fs.writeFileSync(entryPointPath, buildServerEntryPoint(), 'utf-8');
+    fs.writeFileSync(packageJsonPath, `${JSON.stringify({
+        name: 'brainclaw-claude-desktop-extension',
+        private: true,
+        type: 'module',
+        version,
+    }, null, 2)}\n`, 'utf-8');
+    fs.writeFileSync(manifestPath, `${JSON.stringify(buildManifest(metadata, version, projectRoot), null, 2)}\n`, 'utf-8');
+    const packed = options.pack !== false ? packClaudeDesktopExtension(workspaceDir, outputFile) : false;
+    return {
+        workspaceDir,
+        outputFile,
+        packed,
+        manifestPath,
+        entryPointPath,
+        packageRoot,
+        runtimeRoot,
+        projectRoot,
+        copiedDependencies,
+    };
+}
+function buildServerEntryPoint() {
+    return `import process from 'node:process';
+
+const projectRoot = process.env.BRAINCLAW_PROJECT_ROOT?.trim();
+if (projectRoot) {
+  process.chdir(projectRoot);
+}
+
+const { runMcp } = await import('../runtime/commands/mcp.js');
+runMcp();
+`;
+}
+function buildManifest(metadata, version, projectRoot) {
+    return {
+        manifest_version: '0.3',
+        name: 'brainclaw-claude-desktop',
+        display_name: 'Brainclaw Project Memory',
+        version,
+        description: 'Brainclaw local project memory and delegated task inbox for Claude Desktop.',
+        author: {
+            name: 'Brainclaw',
+            ...(metadata.homepage ? { url: metadata.homepage } : {}),
+        },
+        ...(typeof metadata.repository === 'string'
+            ? { repository: { type: 'git', url: metadata.repository } }
+            : metadata.repository
+                ? { repository: metadata.repository }
+                : {}),
+        ...(metadata.homepage ? { homepage: metadata.homepage } : {}),
+        server: {
+            type: 'node',
+            entry_point: 'server/index.js',
+            mcp_config: {
+                command: 'node',
+                args: ['${__dirname}/server/index.js'],
+                env: {
+                    BRAINCLAW_PROJECT_ROOT: '${user_config.project_root}',
+                    BRAINCLAW_SKIP_SETUP_REQUIREMENT: '1',
+                },
+            },
+        },
+        tools: CLAUDE_DESKTOP_TOOLS,
+        compatibility: {
+            platforms: ['win32', 'darwin'],
+            runtimes: {
+                node: '>=20.0.0',
+            },
+        },
+        user_config: {
+            project_root: {
+                type: 'directory',
+                title: 'Project Root',
+                description: 'Brainclaw project root that Claude Desktop should operate on.',
+                required: true,
+                default: projectRoot,
+            },
+        },
+    };
+}
+function resolveRuntimeRoot() {
+    return path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+}
+function findPackageRoot(startDir) {
+    let current = startDir;
+    while (true) {
+        const candidate = path.join(current, 'package.json');
+        if (fs.existsSync(candidate)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`Could not locate package.json from ${startDir}`);
+        }
+        current = parent;
+    }
+}
+function readPackageMetadata(packageRoot) {
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+    return JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+}
+function resolveRuntimeDependencies(packageRoot) {
+    const metadata = readPackageMetadata(packageRoot);
+    return Object.keys(metadata.dependencies ?? {});
+}
+function packClaudeDesktopExtension(workspaceDir, outputFile) {
+    fs.rmSync(outputFile, { force: true });
+    const pythonCommand = resolveAvailableCommand(process.platform === 'win32'
+        ? ['python', 'py', 'python3']
+        : ['python3', 'python', 'py']);
+    if (pythonCommand) {
+        const script = [
+            'import os, sys, zipfile',
+            'src, dest = sys.argv[1], sys.argv[2]',
+            'with zipfile.ZipFile(dest, "w", zipfile.ZIP_DEFLATED) as zf:',
+            '  for root, _, files in os.walk(src):',
+            '    for name in files:',
+            '      full = os.path.join(root, name)',
+            '      rel = os.path.relpath(full, src)',
+            '      zf.write(full, rel)',
+        ].join('; ');
+        const result = spawnSync(pythonCommand, ['-c', script, workspaceDir, outputFile], {
+            encoding: 'utf-8',
+        });
+        if (result.status === 0) {
+            return true;
+        }
+    }
+    if (process.platform === 'win32') {
+        const shell = resolveAvailableCommand(['pwsh', 'powershell']);
+        if (!shell) {
+            throw new Error('Could not find Python or PowerShell to create the Claude Desktop .mcpb archive.');
+        }
+        const command = `Compress-Archive -Path (Join-Path '${escapePowerShellPath(workspaceDir)}' '*') -DestinationPath '${escapePowerShellPath(outputFile)}' -Force`;
+        const result = spawnSync(shell, ['-NoProfile', '-Command', command], {
+            encoding: 'utf-8',
+        });
+        if (result.status === 0) {
+            return true;
+        }
+    }
+    const zipCommand = resolveAvailableCommand(['zip']);
+    if (zipCommand) {
+        const result = spawnSync(zipCommand, ['-qr', outputFile, '.'], {
+            cwd: workspaceDir,
+            encoding: 'utf-8',
+        });
+        if (result.status === 0) {
+            return true;
+        }
+    }
+    throw new Error('Failed to create a .mcpb archive. Install Python 3, PowerShell, or zip.');
+}
+function resolveAvailableCommand(candidates) {
+    for (const candidate of candidates) {
+        const result = spawnSync(candidate, ['--version'], { encoding: 'utf-8' });
+        if (result.status === 0) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function escapePowerShellPath(value) {
+    return value.replace(/'/g, "''");
+}
+export function renderClaudeDesktopExtensionSummary(result) {
+    const lines = [
+        'Claude Desktop extension scaffold ready.',
+        `Workspace: ${path.relative(process.cwd(), result.workspaceDir) || result.workspaceDir}`,
+        `Manifest: ${path.relative(process.cwd(), result.manifestPath) || result.manifestPath}`,
+        `Server entry: ${path.relative(process.cwd(), result.entryPointPath) || result.entryPointPath}`,
+    ];
+    if (result.packed) {
+        lines.push(`Package: ${path.relative(process.cwd(), result.outputFile) || result.outputFile}`);
+        lines.push('Install in Claude Desktop via Developer -> Extensions -> Install Extension.');
+    }
+    else {
+        lines.push('Archive packing skipped (--no-pack).');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=claude-desktop-extension.js.map

package/dist/core/ids.js

@@ -11,6 +11,7 @@ const PREFIXES = {
     plan_items: 'pln',
     plan_steps: 'stp',
     instruction_entries: 'ins',
+    ai_surface_tasks: 'ast',
 };
 const ID_COUNTER_FILE = '.id-counter.json';
 function counterPath(cwd) {

package/dist/core/io.js

@@ -30,6 +30,7 @@ const ENTITY_DIR_MAP = {
     'runtime': 'coordination/runtime',
     'runtime-hosts': 'coordination/runtime-hosts',
     'runtime-private': 'coordination/runtime-private',
+    'surface-tasks': 'coordination/surface-tasks',
     // discovery/ — Project entity: what's available
     'bootstrap': 'discovery/bootstrap',
     'bootstrap/seeds': 'discovery/bootstrap/seeds',