brainclaw 0.19.12 → 0.20.0

package/README.md

@@ -21,6 +21,8 @@ The best setup is to tell your agent, in natural language, to install and initia
 
 It sits alongside Copilot, Claude Code, Cursor, Codex, Windsurf, OpenCode, Antigravity/Gemini CLI and other coding agents. It does not replace them. It gives them a shared state layer they can resume from reliably across sessions.
 
+brainclaw is also starting to model other local AI work surfaces on the same machine, such as ChatGPT Desktop, Claude Desktop, Claude Cowork, and Gemini web or CLI. That makes it possible to keep a project-level queue of non-code work for those surfaces, instead of treating every task as something the active coding agent must do itself.
+
 ---
 
 ## Why brainclaw exists
@@ -40,6 +42,8 @@ brainclaw solves this by making the repo itself agent-readable and agent-writeab
 | **Coordination state** | shared plans, file claims, runtime notes, and board views for active work |
 | **Agent-ready context** | compact, prompt-sized context built from real workspace state instead of stale instructions |
 | **Native agent files** | auto-writes `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`, and similar local guidance |
+| **Machine AI surface discovery** | detects local coding agents plus desktop AI work surfaces such as ChatGPT Desktop and Gemini CLI |
+| **Queued surface tasks** | stores project-scoped requests for other local AI surfaces, such as visual generation, drafting, summaries, or research |
 | **Local-first storage** | plain text + JSON, Git-friendly, no mandatory cloud, no telemetry by default |
 
 ---
@@ -62,18 +66,20 @@ If you are documenting or integrating an agent workflow, treat MCP as the primar
 
 brainclaw is designed to sit alongside the coding agents teams are already using, not behind a separate hosted control plane.
 
-| Logo | Agent | Brainclaw fit | Best use today |
+| Logo | Agent | Integration | What brainclaw configures |
 |---|---|---|---|
-| [![Claude Code](https://img.shields.io/badge/Claude_Code-111111?logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code) | **[Claude Code](https://github.com/anthropics/claude-code)** | Best fit | full agent workflow with MCP, instructions, commands, and session hooks |
-| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/) | **[Codex](https://openai.com/codex/)** | Strong fit | agent-first repo coordination with explicit plans, claims, and handoffs |
-| [![Cursor](https://img.shields.io/badge/Cursor-1F2430?logo=cursor&logoColor=white)](https://cursor.com/en-US) | **[Cursor](https://cursor.com/en-US)** | Strong fit | repo-native agent workflows with rules plus MCP |
-| [![OpenCode](https://img.shields.io/badge/OpenCode-0F172A?logoColor=white)](https://github.com/opencode-ai/opencode) | **[OpenCode](https://github.com/opencode-ai/opencode)** | Strong fit | simple agent bootstrap with `AGENTS.md` plus workspace MCP |
-| [![Windsurf](https://img.shields.io/badge/Windsurf-0B1220?logo=codeium&logoColor=white)](https://windsurf.com/) | **[Windsurf](https://windsurf.com/)** | Good fit | guided agent workflows with instructions, hooks, and MCP |
-| [![Roo](https://img.shields.io/badge/Roo-7C3AED?logoColor=white)](https://github.com/RooCodeInc/Roo-Code) | **[Roo](https://github.com/RooCodeInc/Roo-Code)** | Good fit | workspace agent coordination with rules plus MCP |
-| [![Continue](https://img.shields.io/badge/Continue-2563EB?logoColor=white)](https://github.com/continuedev/continue) | **[Continue](https://github.com/continuedev/continue)** | Good fit | editor-based agent workflows with MCP context access |
-| [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-1A73E8?logo=googlegemini&logoColor=white)](https://github.com/google-gemini/gemini-cli) | **[Antigravity / Gemini CLI](https://github.com/google-gemini/gemini-cli)** | Promising fit | local agent workflows with `GEMINI.md` plus MCP |
-| [![Cline](https://img.shields.io/badge/Cline-0F766E?logoColor=white)](https://github.com/cline/cline) | **[Cline](https://github.com/cline/cline)** | Functional fit | lightweight agent use through rules plus MCP |
-| [![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-181717?logo=githubcopilot&logoColor=white)](https://github.com/features/copilot) | **[GitHub Copilot](https://github.com/features/copilot)** | Supported fit | project awareness and shared local instructions with lighter workflow control |
+| [![Claude Code](https://img.shields.io/badge/Claude_Code-111111?logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code) | **[Claude Code](https://github.com/anthropics/claude-code)** | Full | MCP + CLAUDE.md + hooks + permissions + /brainclaw command |
+| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/) | **[Codex](https://openai.com/codex/)** | Standard | MCP + AGENTS.md |
+| [![Cursor](https://img.shields.io/badge/Cursor-1F2430?logo=cursor&logoColor=white)](https://cursor.com/en-US) | **[Cursor](https://cursor.com/en-US)** | Standard | MCP + .cursor/rules/ + alwaysApply MDC |
+| [![OpenCode](https://img.shields.io/badge/OpenCode-0F172A?logoColor=white)](https://github.com/opencode-ai/opencode) | **[OpenCode](https://github.com/opencode-ai/opencode)** | Standard | MCP + AGENTS.md |
+| [![Windsurf](https://img.shields.io/badge/Windsurf-0B1220?logo=codeium&logoColor=white)](https://windsurf.com/) | **[Windsurf](https://windsurf.com/)** | Standard | MCP + .windsurfrules session trigger |
+| [![Roo](https://img.shields.io/badge/Roo-7C3AED?logoColor=white)](https://github.com/RooCodeInc/Roo-Code) | **[Roo](https://github.com/RooCodeInc/Roo-Code)** | Standard | MCP (auto-approve) + .roo/rules/ |
+| [![Cline](https://img.shields.io/badge/Cline-0F766E?logoColor=white)](https://github.com/cline/cline) | **[Cline](https://github.com/cline/cline)** | Standard | MCP (auto-approve) + .clinerules/ |
+| [![Continue](https://img.shields.io/badge/Continue-2563EB?logoColor=white)](https://github.com/continuedev/continue) | **[Continue](https://github.com/continuedev/continue)** | Standard | MCP + .continue/rules/ |
+| [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-1A73E8?logo=googlegemini&logoColor=white)](https://github.com/google-gemini/gemini-cli) | **[Antigravity / Gemini CLI](https://github.com/google-gemini/gemini-cli)** | Standard | MCP + GEMINI.md |
+| [![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-181717?logo=githubcopilot&logoColor=white)](https://github.com/features/copilot) | **[GitHub Copilot](https://github.com/features/copilot)** | Limited | copilot-instructions.md + brainclaw-context skill |
+
+**Full** = MCP + hooks + auto-approve (context injected every prompt). **Standard** = MCP + instruction file (agent must call tools explicitly). **Limited** = no MCP (static instruction file is the only source of context).
 
 brainclaw is most effective today when one agent works at a time in a given checkout and the next agent resumes from shared context, claims, and handoffs.
 
@@ -146,6 +152,18 @@ brainclaw context --for src/auth/routes.ts --digest
 brainclaw status
 ```
 
+And if the current coding agent wants to hand off a non-code task to another local AI surface for later:
+
+```bash
+brainclaw surface-task create "Generate homepage hero visual" \
+  --target chatgpt \
+  --kind visual_asset \
+  --instructions "Create a lightweight product hero visual for the landing page." \
+  --output assets/hero-home.png
+
+brainclaw surface-task list
+```
+
 ---
 
 ## Installation
@@ -287,6 +305,19 @@ npm run test:coverage      # with coverage report
 
 ## Changelog
 
+### v0.20.0
+
+- **Onboarding rework** : nouveau parcours d'installation en 2-3 étapes au lieu de 4, avec choix explicites (type de projet, topologie mémoire) au lieu de termes techniques
+- **Agent capability profiles** : chaque agent (10 supportés) a un profil de capacité (MCP, hooks, auto-approve, skills, rules) qui détermine le contenu de ses fichiers d'instructions
+- **Templates adaptatifs** : les fichiers d'instructions (CLAUDE.md, AGENTS.md, etc.) sont générés selon 3 tiers — Full (léger, hooks font le reste), Standard (directif, top traps inclus), Limited (riche, tout en statique)
+- **Séparation core/run** : les fichiers statiques ne contiennent plus que le protocole, les contraintes et instructions. Les traps, plans, decisions et claims sont exclusivement dans le contexte dynamique MCP
+- **Bootstrap enrichi** : scan des workflows CI/CD, ADR, CONTRIBUTING, Docker, .env.example, branches actives et tags git
+- **Quick setup MCP** : `bclaw_setup` détecte le repo courant et propose un init rapide au lieu de forcer le scan multi-repo
+- **`brainclaw uninstall`** : nouvelle commande pour retirer brainclaw d'un projet (`--project`) ou d'une machine (`--machine`)
+- **Traps machine-scoped** : nouveau champ `platform_scope` sur les traps — les traps machine ne polluent plus les fichiers d'instructions statiques
+- **Init sans setup préalable** : `brainclaw init` crée automatiquement le user store si absent, plus besoin de `brainclaw setup` d'abord
+- **Docs réécrites** : intégrations, quickstart et README avec niveaux Full/Standard/Limited et matrice agent factuelle
+
 ### v0.9.10
 
 - **OpenCode** : détection et auto-config MCP workspace via `opencode.json`; l'export réutilise `AGENTS.md`

package/dist/cli.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import { runInit } from './commands/init.js';
 import { runSetup } from './commands/setup.js';
 import { runUpgrade } from './commands/upgrade.js';
+import { runReconcile } from './commands/reconcile.js';
 import { getMemoryLog, rollbackMemory, hasMemoryRepo } from './core/memory-git.js';
 import { buildMachineProfile, saveMachineProfile, loadMachineProfile, renderMachineProfileSummary } from './core/machine-profile.js';
 import { buildAgentInventory, saveAgentInventory, loadAgentInventory, renderAgentInventorySummary } from './core/agent-inventory.js';
@@ -22,6 +23,7 @@ import { runCompleteStep } from './commands/complete-step.js';
 import { runUpdateHandoff } from './commands/update-handoff.js';
 import { runInstruction } from './commands/instruction.js';
 import { runListAgents } from './commands/list-agents.js';
+import { runSurfaceTaskResource } from './commands/surface-task-resource.js';
 import { runListInstructions } from './commands/list-instructions.js';
 import { runDoctor } from './commands/doctor.js';
 import { runRebuild } from './commands/rebuild.js';
@@ -169,7 +171,7 @@ program
 // --- machine-profile ---
 program
     .command('machine-profile')
-    .description('Detect and persist machine capabilities (OS, shells, git users, SSH keys, toolchains, WSL)')
+    .description('Detect and persist machine capabilities (OS, shells, git users, SSH keys, toolchains, WSL, AI surfaces)')
     .option('--refresh', 'Force regeneration even if profile exists')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
@@ -402,6 +404,28 @@ program
     .action((id, options) => {
     runUpdatePlan(id, { ...options, actualEffort: options.actualEffort });
 });
+// --- surface-task ---
+program
+    .command('surface-task <subcommand> [args...]')
+    .description('Manage queued tasks for desktop AI surfaces such as ChatGPT Desktop or Claude Desktop')
+    .option('--json', 'Output as JSON for list')
+    .option('--all', 'Include completed, cancelled, and failed tasks in list')
+    .option('--status <status>', 'Status filter/update: queued, in_progress, completed, cancelled, failed')
+    .option('--target <surface>', 'Target surface, e.g. chatgpt, claude, gemini')
+    .option('--kind <kind>', 'Task kind: visual_asset, draft, summary, analysis, research, custom')
+    .option('--instructions <text>', 'Detailed instructions for the target surface')
+    .option('--output <paths...>', 'Expected output paths')
+    .option('--result <text>', 'Optional result note when updating a task')
+    .option('--tag <tags...>', 'Tags for this task')
+    .option('--path <paths...>', 'Related file paths')
+    .option('--agent <agent>', 'Author agent name')
+    .option('--agent-id <agentId>', 'Author agent id')
+    .action((subcommand, args, options) => {
+    runSurfaceTaskResource(subcommand, args, {
+        ...options,
+        agentId: options.agentId,
+    });
+});
 // --- delete-plan ---
 program
     .command('delete-plan <id>')
@@ -439,6 +463,17 @@ program
     .action((options) => {
     runVersion(options);
 });
+// --- uninstall ---
+import { runUninstall } from './commands/uninstall.js';
+program
+    .command('uninstall')
+    .description('Remove brainclaw from a project and/or machine')
+    .option('--project', 'Remove brainclaw from the current project (.brainclaw/, agent files, configs)')
+    .option('--machine', 'Remove brainclaw global config (~/.brainclaw/)')
+    .option('-y, --yes', 'Skip confirmation prompts')
+    .action(async (options) => {
+    await runUninstall(options);
+});
 // --- rebuild ---
 program
     .command('rebuild')
@@ -915,6 +950,25 @@ program
     .action((options) => {
     runExport(options);
 });
+program
+    .command('reconcile')
+    .description('Refresh machine and workspace bootstrap state after updates or onboarding on complex installs')
+    .option('--json', 'Output as JSON')
+    .option('--dry-run', 'Preview the reconciliation plan without writing machine or bootstrap state')
+    .option('--apply-bootstrap', 'Apply bootstrap suggestions across all selected stores after refresh')
+    .option('-y, --yes', 'Skip confirmation prompts for multi-store bootstrap apply')
+    .option('--skip-machine-profile', 'Skip machine-profile refresh')
+    .option('--skip-agent-inventory', 'Skip agent-inventory refresh')
+    .action(async (options) => {
+    await runReconcile({
+        json: options.json,
+        dryRun: options.dryRun,
+        applyBootstrap: options.applyBootstrap,
+        yes: options.yes,
+        skipMachineProfile: options.skipMachineProfile,
+        skipAgentInventory: options.skipAgentInventory,
+    });
+});
 // --- hooks ---
 program
     .command('hooks')

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

@@ -0,0 +1,18 @@
+import path from 'node:path';
+import { buildClaudeDesktopExtension, renderClaudeDesktopExtensionSummary, } from '../core/claude-desktop-extension.js';
+export function runClaudeDesktopExtension(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const result = buildClaudeDesktopExtension({
+        cwd,
+        workspaceDir: options.workspace ? path.resolve(cwd, options.workspace) : undefined,
+        outputFile: options.output ? path.resolve(cwd, options.output) : undefined,
+        projectRoot: options.projectRoot ? path.resolve(cwd, options.projectRoot) : undefined,
+        pack: options.pack,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(renderClaudeDesktopExtensionSummary(result));
+}
+//# sourceMappingURL=claude-desktop-extension.js.map

package/dist/commands/context.js

@@ -3,6 +3,7 @@ import { buildContext, renderContextMarkdown, renderContextPromptTemplate } from
 import { writeContextMarker } from '../core/freshness.js';
 import { nowISO } from '../core/ids.js';
 import { logger } from '../core/logger.js';
+import { resolveContextStoreCwd } from '../core/store-resolution.js';
 export function runContext(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
@@ -17,6 +18,7 @@ export function runContext(options = {}) {
         }
         return;
     }
+    const contextCwd = resolveContextStoreCwd(cwd, options.for);
     const result = buildContext({
         target: options.for,
         project: options.project,
@@ -43,7 +45,7 @@ export function runContext(options = {}) {
     else {
         console.log(renderContextMarkdown(result, options.explain));
     }
-    writeLastContextMarker(result, options, cwd);
+    writeLastContextMarker(result, options, contextCwd);
 }
 function writeLastContextMarker(result, options, cwd) {
     try {

package/dist/commands/doctor.js

@@ -25,6 +25,7 @@ import { assessBrainclawVersion } from '../core/brainclaw-version.js';
 import { resolveStoreChain } from '../core/store-resolution.js';
 import { resolveCrossProjectLinks, detectCrossProjectCycles } from '../core/cross-project.js';
 import { auditLocalAgentWorkspaceFiles, ensureGitignoreEntries } from '../core/agent-files.js';
+import { summarizeWorkspaceProjects } from '../core/workspace-projects.js';
 const BACKLOG_KEYWORDS = /\b(TODO|NEXT|backlog|next[\s-]step|action[\s-]item|prochaine?s?\s+étapes?|à\s+faire)\b/i;
 function hasBacklogPatterns(text) {
     const lines = text.split(/\r?\n/);
@@ -138,14 +139,19 @@ export function runDoctor(options = {}) {
             });
         }
     }
-    if (config.project_mode === 'multi-project' && (config.projects?.known.length ?? 0) === 0) {
+    const workspaceProjects = summarizeWorkspaceProjects(options.cwd ?? process.cwd(), config);
+    if (config.project_mode === 'multi-project' && workspaceProjects.effective_project_count === 0) {
         checks.push({
             name: 'project_mode',
             status: 'warn',
-            message: 'project_mode is multi-project but no project namespaces are configured yet.',
+            message: config.projects?.strategy === 'folder'
+                ? 'project_mode is multi-project with folder strategy but no child projects were resolved from config, registry, or nested stores yet.'
+                : 'project_mode is multi-project but no project namespaces are configured yet.',
         });
         if (!options.json) {
-            console.warn('⚠ project_mode is multi-project but no project namespaces are configured yet.');
+            console.warn(config.projects?.strategy === 'folder'
+                ? '⚠ project_mode is multi-project with folder strategy but no child projects were resolved from config, registry, or nested stores yet.'
+                : '⚠ project_mode is multi-project but no project namespaces are configured yet.');
         }
         hasIssues = true;
     }
@@ -153,10 +159,11 @@ export function runDoctor(options = {}) {
         checks.push({
             name: 'project_mode',
             status: 'ok',
-            message: `project_mode=${config.project_mode}, strategy=${config.projects?.strategy ?? 'manual'}, known_projects=${config.projects?.known.length ?? 0}`,
+            message: `project_mode=${config.project_mode}, strategy=${config.projects?.strategy ?? 'manual'}, configured_projects=${workspaceProjects.configured_projects.length}, effective_projects=${workspaceProjects.effective_project_count}`,
+            details: workspaceProjects,
         });
         if (!options.json) {
-            console.log(`✔ project mode: ${config.project_mode} (${config.projects?.strategy ?? 'manual'})`);
+            console.log(`✔ project mode: ${config.project_mode} (${config.projects?.strategy ?? 'manual'}), effective projects=${workspaceProjects.effective_project_count}`);
         }
     }
     try {

package/dist/commands/export.js

@@ -8,6 +8,9 @@ import { resolveInstructions, loadInstructions } from '../core/instructions.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { resolveExportTarget, resolveExportTargetByFormat, writeExportFile, buildHygieneSection, describeAutoConfigWrite, writeExportCompanionFiles, collectExportGitignoreEntries, ensureGitignoreEntries, } from '../core/agent-files.js';
 import { logger } from '../core/logger.js';
+import { getAgentCapabilityProfile } from '../core/agent-capability.js';
+import { renderBrainclawSection } from '../core/instruction-templates.js';
+import { getInstalledBrainclawVersion } from '../core/brainclaw-version.js';
 export function runExport(options) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
@@ -125,7 +128,28 @@ function declareAgentIntegrationFromTarget(cwd, agentName, declarationSource) {
         saveConfig(config, cwd);
     }
 }
+function formatToAgentName(format) {
+    const map = {
+        'claude-md': 'claude-code',
+        'cursor-rules': 'cursor',
+        'copilot-instructions': 'github-copilot',
+        'agents-md': 'codex',
+        'gemini-md': 'antigravity',
+        'windsurf': 'windsurf',
+        'cline': 'cline',
+        'roo': 'roo',
+        'continue': 'continue',
+    };
+    return map[format];
+}
 function generateExport(format, options, cwd) {
+    const agentName = formatToAgentName(format);
+    if (agentName) {
+        const adaptive = generateAdaptiveExport(agentName, options, cwd);
+        if (adaptive)
+            return adaptive;
+    }
+    // Fallback to legacy generators for unknown formats
     switch (format) {
         case 'copilot-instructions': return generateCopilotInstructions(options, cwd);
         case 'cursor-rules': return generateCursorRules(options, cwd);
@@ -140,6 +164,26 @@ function generateExport(format, options, cwd) {
             throw new Error(`Unknown export format: ${format}`);
     }
 }
+/**
+ * Generate export content using adaptive templates when a capability profile
+ * exists for the agent, falling back to the legacy per-format generators.
+ */
+function generateAdaptiveExport(agentName, options, cwd) {
+    const profile = getAgentCapabilityProfile(agentName);
+    if (!profile)
+        return undefined;
+    const state = loadState(cwd);
+    const instructions = getInstructionText(options, cwd);
+    const config = loadConfig(cwd);
+    const result = renderBrainclawSection({
+        profile,
+        state,
+        projectName: config.project_name,
+        brainclawVersion: getInstalledBrainclawVersion(),
+        resolvedInstructions: instructions,
+    });
+    return result.content;
+}
 function getInstructionText(options, cwd) {
     try {
         const all = loadInstructions(cwd);

package/dist/commands/init.js

@@ -14,17 +14,19 @@ import { renderBootstrapSummary, runBootstrapProfile } from '../core/bootstrap.j
 import { isAgentIntegrationName, upsertAgentIntegrationDeclaration } from '../core/agent-integrations.js';
 import { describeAutoConfigWrite, ensureAgentFiles, ensureGitignoreEntries, writeDetectedAgentAutoConfig } from '../core/agent-files.js';
 import { detectAiAgent, detectWslEnvironment } from '../core/ai-agent-detection.js';
-import { hasCompletedSetup } from '../core/setup-state.js';
+import { buildAiSurfaceInventory, renderAiSurfaceUsageHints } from '../core/ai-surface-inventory.js';
+import { ensureUserStore, hasCompletedSetup } from '../core/setup-state.js';
 import { writeDetectedAgentExport } from './export.js';
 import { writeDetectedAgentHooks } from './hooks.js';
 export async function runInit(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const containingMemoryStore = resolveContainingMemoryStore(cwd);
-    const skipSetupRequirement = options.skipSetupRequirement === true || process.env.BRAINCLAW_SKIP_SETUP_REQUIREMENT === '1';
-    if (!skipSetupRequirement && !hasCompletedSetup()) {
-        console.error('Error: global brainclaw setup has not been completed on this machine.');
-        console.error('Run `brainclaw setup` first, then retry `brainclaw init` from your project root.');
-        process.exit(1);
+    // Auto-create user store if absent (replaces the old "setup required" guard).
+    // The skipSetupRequirement flag and BRAINCLAW_SKIP_SETUP_REQUIREMENT env var
+    // are kept for backward compatibility but are now effectively no-ops —
+    // init always ensures the user store exists before proceeding.
+    if (!hasCompletedSetup()) {
+        ensureUserStore();
     }
     if (containingMemoryStore) {
         console.error(`Error: cannot run \`brainclaw init\` from inside an existing project memory store (${containingMemoryStore}).`);
@@ -178,6 +180,20 @@ export async function runInit(options = {}) {
     if (detectedExport) {
         console.log(`\u2714 Agent instructions written to ${detectedExport.relativePath} (${detectedExport.created ? 'created' : 'updated'})`);
     }
+    const visibleSurfaces = buildAiSurfaceInventory().filter((surface) => surface.status !== 'not_detected');
+    if (visibleSurfaces.length > 0) {
+        console.log('✔ Other AI work surfaces detected on this machine:');
+        for (const surface of visibleSurfaces) {
+            console.log(`  - ${surface.display_name} [${surface.surface_kind}, ${surface.status}]`);
+        }
+        const usageHints = renderAiSurfaceUsageHints(visibleSurfaces);
+        if (usageHints.length > 0) {
+            console.log('  Suggested uses:');
+            for (const line of usageHints) {
+                console.log(`    ${line}`);
+            }
+        }
+    }
     for (const hook of detectedHooks) {
         console.log(`\u2714 Session hook written to ${hook.relativePath} (${hook.created ? 'created' : 'updated'})`);
     }

package/dist/commands/list-surface-tasks.js

@@ -0,0 +1,39 @@
+import { memoryExists } from '../core/io.js';
+import { listAiSurfaceTasks } from '../core/ai-surface-tasks.js';
+export function runListSurfaceTasks(options = {}) {
+    if (!memoryExists(options.cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    let tasks = listAiSurfaceTasks(options.cwd);
+    if (!options.all) {
+        tasks = tasks.filter((task) => task.status === 'queued' || task.status === 'in_progress');
+    }
+    if (options.status) {
+        tasks = tasks.filter((task) => task.status === options.status);
+    }
+    if (options.target) {
+        const target = options.target.toLowerCase();
+        tasks = tasks.filter((task) => task.target_surface.toLowerCase() === target);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(tasks, null, 2));
+        return;
+    }
+    if (tasks.length === 0) {
+        console.log('No surface tasks.');
+        return;
+    }
+    console.log(`${tasks.length} surface task(s):`);
+    console.log('');
+    for (const task of tasks) {
+        console.log(`  [${task.id}] ${task.title} (${task.status}, target ${task.target_surface}, kind ${task.kind})`);
+        if (task.requested_outputs.length > 0) {
+            console.log(`    outputs: ${task.requested_outputs.join(', ')}`);
+        }
+        if (task.result_note) {
+            console.log(`    result: ${task.result_note}`);
+        }
+    }
+}
+//# sourceMappingURL=list-surface-tasks.js.map

package/dist/commands/mcp.js

@@ -30,6 +30,8 @@ import { buildEstimationReport } from './estimation-report.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
 import { resolveTargetStore, resolveStoreChain } from '../core/store-resolution.js';
+import { probeForQuickSetup, buildQuickSetupProbeResponse, buildOnboardingPreview } from '../core/setup-flow.js';
+import { ensureUserStore } from '../core/setup-state.js';
 import { readUnseenEvents, buildNotificationSummary } from '../core/event-log.js';
 import { BootstrapInterviewAnswerSchema } from '../core/schema.js';
 export const SCHEMA_VERSION = '0.6.0';
@@ -246,14 +248,17 @@ export const MCP_READ_TOOLS = [
 const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_setup',
-        description: 'Interactive onboarding wizard — global agent install + multi-repo brainclaw init. Use the resume pattern: call without step to start, then pass step+choice to advance through each stage.',
+        description: 'Interactive onboarding wizard. Two modes: (1) Quick mode (default): probes the current repo and asks project type + topology, then inits. (2) Batch mode: scan root directories and init multiple repos. Call without step to start — brainclaw auto-detects the best mode.',
         inputSchema: {
             type: 'object',
             properties: {
-                step: { type: 'string', description: 'Current step to resume: "project_roots", "repo_selection", or "agent_selection". Omit to start from the beginning.' },
-                choice: { type: 'string', description: 'User choice for the current step (e.g. path list, "all", "detected", or comma-separated numbers).' },
-                roots: { type: 'string', description: 'Comma-separated root paths (required from step "repo_selection" onward to re-scan).' },
-                repo_selection: { type: 'string', description: 'Repo selection choice from previous step (required for "agent_selection" step).' },
+                step: { type: 'string', description: 'Resume step: "quick_init" (quick mode), or "project_roots"/"repo_selection"/"agent_selection" (batch mode). Omit to start.' },
+                choice: { type: 'string', description: 'User choice for the current step.' },
+                project_type: { type: 'string', description: 'Quick mode: "standalone", "workspace", or "linked".' },
+                topology: { type: 'string', description: 'Quick mode: "embedded" (shared via git) or "sidecar" (local only).' },
+                roots: { type: 'string', description: 'Batch mode: comma-separated root paths.' },
+                repo_selection: { type: 'string', description: 'Batch mode: repo selection from previous step.' },
+                mode: { type: 'string', description: 'Force "quick" or "batch" mode. Default: auto-detect.' },
             },
         },
     },
@@ -1112,6 +1117,16 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         const text = args.interview
             ? renderBootstrapInterview(result, audience)
             : renderBootstrapSummary(result);
+        // Extract top-level suggested questions for conversational bootstrap (step 11)
+        const suggestedQuestions = result.importPlan.interview?.questions?.map((q) => ({
+            id: q.id,
+            prompt: q.prompt,
+            rationale: q.rationale,
+            priority: q.priority,
+        })) ?? [];
+        // Separate auto-imports (high confidence) from proposals (need discussion)
+        const autoImports = result.importPlan.suggestions.filter((s) => s.confidence === 'high');
+        const proposals = result.importPlan.suggestions.filter((s) => s.confidence !== 'high');
         return {
             content: [{ type: 'text', text }],
             structuredContent: {
@@ -1127,6 +1142,9 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
                 seed_count: result.profile.seed_count,
                 seeds: result.seeds,
                 import_plan: result.importPlan,
+                auto_imports: autoImports,
+                proposals,
+                suggested_questions: suggestedQuestions,
                 last_application: result.lastApplication,
                 reused_profile: result.reusedProfile,
             },
@@ -1571,15 +1589,78 @@ export async function executeMcpToolCall(payload) {
             const choice = args.choice ?? '';
             const rootsArg = args.roots;
             const repoSelectionArg = args.repo_selection;
+            const modeArg = args.mode;
             const env = process.env;
             if (!checkGitPresence()) {
                 return { response: toolResponse({ content: [{ type: 'text', text: 'Git is not installed or not found in PATH. Install git from https://git-scm.com before running brainclaw setup.' }], structuredContent: { error: 'git_not_found' } }, true) };
             }
+            // ─── Quick mode: probe current repo ──────────────────────────────
             if (!step) {
+                // Auto-detect mode: if we're in a git repo, use quick mode unless batch is forced
+                const forceBatch = modeArg === 'batch';
+                if (!forceBatch) {
+                    const probe = probeForQuickSetup(cwd);
+                    if (probe.isGitRepo || probe.alreadyInitialized) {
+                        const response = buildQuickSetupProbeResponse(probe);
+                        return { response: toolResponse({ content: [{ type: 'text', text: response.text }], structuredContent: response.structured }) };
+                    }
+                }
+                // Fall through to batch mode
                 const existingState = readSetupState(env);
                 const alreadyRun = existingState ? `Setup was previously run on ${new Date(existingState.completed_at).toLocaleDateString()}. You can re-run it.` : undefined;
                 return { response: toolResponse({ content: [{ type: 'text', text: [alreadyRun, "Where are the user's project directories? Please ask the user to provide one or more root paths where their git repositories are located (e.g. ~/Projects, C:\\Users\\user\\code)."].filter(Boolean).join('\n\n') }], structuredContent: { pending_question: 'project_roots', prompt: 'Please ask the user: "Where are your projects? Enter one or more root directories (comma-separated):"', ...(alreadyRun ? { already_run: alreadyRun } : {}) } }) };
             }
+            // ─── Quick mode step: init with choices ──────────────────────────
+            if (step === 'quick_init') {
+                const projectType = args.project_type ?? 'standalone';
+                const topology = args.topology ?? 'embedded';
+                // Ensure user store exists
+                ensureUserStore(env);
+                // Map choices to init options
+                const projectMode = projectType === 'workspace' ? 'multi-project' : 'auto';
+                const topologyMode = topology === 'sidecar' ? 'sidecar' : 'embedded';
+                // Run init
+                try {
+                    const { runInit } = await import('./init.js');
+                    await runInit({
+                        yes: true,
+                        cwd,
+                        skipAgentBootstrap: false,
+                        projectMode,
+                        topology: topologyMode,
+                    });
+                }
+                catch (err) {
+                    return { response: toolResponse({ content: [{ type: 'text', text: `Init failed: ${err instanceof Error ? err.message : String(err)}` }], structuredContent: { error: 'init_failed', details: err instanceof Error ? err.message : String(err) } }, true) };
+                }
+                // Detect agent and report
+                const detected = detectAiAgent(env);
+                const summary = [
+                    `✔ Initialized ${cwd.split(/[\\/]/).pop() ?? cwd} (${projectType}, ${topology})`,
+                ];
+                if (detected) {
+                    summary.push(`✔ Agent detected: ${detected.name}`);
+                }
+                summary.push('✔ Reload your agent session to activate brainclaw MCP tools.');
+                // Check if bootstrap is available and generate preview
+                const probe = probeForQuickSetup(cwd);
+                const bootstrapAvailable = probe.hasContent;
+                const preview = buildOnboardingPreview(cwd);
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: summary.join('\n') + (bootstrapAvailable ? '\n\nThe repo has existing content. Run bclaw_bootstrap to extract initial project context.' : '') + '\n\n' + preview }],
+                        structuredContent: {
+                            setup_complete: true,
+                            project_type: projectType,
+                            topology,
+                            detected_agent: detected?.name ?? null,
+                            bootstrap_available: bootstrapAvailable,
+                            preview,
+                            summary,
+                        },
+                    }),
+                };
+            }
             if (step === 'project_roots') {
                 const roots = parseRoots(choice, env);
                 if (roots.length === 0) {