brainclaw 0.19.12 → 0.20.0

package/dist/core/instruction-templates.js

@@ -0,0 +1,308 @@
+/**
+ * Adaptive instruction file templates — generates brainclaw section content
+ * based on the agent's capability profile (tier A/B/C).
+ *
+ * Core (static) vs Run (dynamic) separation:
+ *   Core: protocol, "why brainclaw", constraints, instructions, estimation rule
+ *   Run:  traps, plans, decisions, claims, handoffs, runtime notes
+ *
+ * Tier A (MCP + hooks): lightweight — hooks inject run content automatically
+ * Tier B (MCP, no hooks): directive — includes top traps, forces MCP calls
+ * Tier C (no MCP): rich — includes plans, traps, decisions (only source)
+ */
+/**
+ * Render the brainclaw section content for an instruction file,
+ * adapted to the agent's capability profile.
+ */
+export function renderBrainclawSection(input) {
+    const { profile } = input;
+    switch (profile.templateTier) {
+        case 'A': return renderTierA(input);
+        case 'B': return renderTierB(input);
+        case 'C': return renderTierC(input);
+    }
+}
+// ─── Tier A: Full integration (MCP + hooks) ─────────────────────────────────
+function renderTierA(input) {
+    const sections = [];
+    const included = [];
+    sections.push(renderHeader(input));
+    included.push('header');
+    sections.push(renderWhySection(input.profile));
+    included.push('why');
+    sections.push(renderProtocolTierA());
+    included.push('protocol');
+    sections.push(renderEstimationRule());
+    included.push('estimation');
+    sections.push(renderVersionCheckRule());
+    included.push('version-check');
+    const constraints = renderConstraints(input.state);
+    if (constraints) {
+        sections.push(constraints);
+        included.push('constraints');
+    }
+    const instructions = renderInstructions(input.resolvedInstructions);
+    if (instructions) {
+        sections.push(instructions);
+        included.push('instructions');
+    }
+    return {
+        content: sections.join('\n\n'),
+        tier: 'A',
+        sectionsIncluded: included,
+    };
+}
+// ─── Tier B: Standard integration (MCP, no hooks) ───────────────────────────
+function renderTierB(input) {
+    const sections = [];
+    const included = [];
+    sections.push(renderHeader(input));
+    included.push('header');
+    sections.push(renderWhySection(input.profile));
+    included.push('why');
+    sections.push(renderProtocolTierB());
+    included.push('protocol');
+    sections.push(renderEstimationRule());
+    included.push('estimation');
+    sections.push(renderVersionCheckRule());
+    included.push('version-check');
+    const constraints = renderConstraints(input.state);
+    if (constraints) {
+        sections.push(constraints);
+        included.push('constraints');
+    }
+    const instructions = renderInstructions(input.resolvedInstructions);
+    if (instructions) {
+        sections.push(instructions);
+        included.push('instructions');
+    }
+    // Tier B includes top traps statically (agent has no hooks to get them)
+    const traps = renderTopTraps(input.state, input.maxTraps ?? 5);
+    if (traps) {
+        sections.push(traps);
+        included.push('traps');
+    }
+    return {
+        content: sections.join('\n\n'),
+        tier: 'B',
+        sectionsIncluded: included,
+    };
+}
+// ─── Tier C: Limited integration (no MCP) ────────────────────────────────────
+function renderTierC(input) {
+    const sections = [];
+    const included = [];
+    sections.push(renderHeader(input));
+    included.push('header');
+    sections.push(renderWhySection(input.profile));
+    included.push('why');
+    sections.push(renderProtocolTierC(input.profile));
+    included.push('protocol');
+    sections.push(renderEstimationRule());
+    included.push('estimation');
+    const constraints = renderConstraints(input.state);
+    if (constraints) {
+        sections.push(constraints);
+        included.push('constraints');
+    }
+    const instructions = renderInstructions(input.resolvedInstructions);
+    if (instructions) {
+        sections.push(instructions);
+        included.push('instructions');
+    }
+    // Tier C includes everything statically — it's the only source of context
+    const traps = renderTopTraps(input.state, input.maxTraps ?? 10);
+    if (traps) {
+        sections.push(traps);
+        included.push('traps');
+    }
+    const plans = renderActivePlans(input.state, input.maxPlans ?? 10);
+    if (plans) {
+        sections.push(plans);
+        included.push('plans');
+    }
+    const decisions = renderRecentDecisions(input.state);
+    if (decisions) {
+        sections.push(decisions);
+        included.push('decisions');
+    }
+    return {
+        content: sections.join('\n\n'),
+        tier: 'C',
+        sectionsIncluded: included,
+    };
+}
+// ─── Shared section renderers ────────────────────────────────────────────────
+function renderHeader(input) {
+    return [
+        `> Managed by brainclaw v${input.brainclawVersion} — do not edit manually.`,
+        `> Regenerate: brainclaw export --format ${formatForAgent(input.profile.name)} --write`,
+    ].join('\n');
+}
+function renderWhySection(profile) {
+    const lines = [
+        '## brainclaw — why this matters',
+        '',
+        'This project uses brainclaw for shared memory and multi-agent coordination.',
+    ];
+    if (profile.hasMcp) {
+        lines.push('Other agents and developers work in this repo. Without brainclaw context:', '- You may edit files another agent is actively working on', '- You will miss known traps and architectural decisions', '- You will duplicate or contradict planned work');
+    }
+    else {
+        lines.push('Project context is maintained in brainclaw memory. This includes:', '- Active constraints that must be respected', '- Known traps to avoid repeating mistakes', '- Plans and decisions for ongoing work coordination');
+    }
+    return lines.join('\n');
+}
+function renderProtocolTierA() {
+    return [
+        '## brainclaw — session protocol',
+        '',
+        'Brainclaw context is injected automatically via hooks at each prompt.',
+        '',
+        '1. Read the injected board state before acting',
+        '2. Call `bclaw_get_context(target)` for deeper memory on a specific scope',
+        '3. Call `bclaw_claim(scope)` before editing if other agents are active',
+        '4. Call `bclaw_session_end(auto_release: true)` when done',
+    ].join('\n');
+}
+function renderProtocolTierB() {
+    return [
+        '## brainclaw — session protocol (REQUIRED)',
+        '',
+        'You MUST follow this protocol before any work in this project.',
+        '',
+        '1. Call `bclaw_session_start` — identify yourself and see the active board',
+        '2. Call `bclaw_get_context(target: "<file or dir>")` — load relevant memory',
+        '3. Call `bclaw_get_execution_context` — check for brainclaw updates',
+        '4. Check that no other agent has claimed your target scope',
+        '5. Call `bclaw_claim(scope)` before editing',
+        '6. Call `bclaw_write_note(text)` to record observations',
+        '7. Call `bclaw_session_end(auto_release: true)` when done',
+    ].join('\n');
+}
+function renderProtocolTierC(profile) {
+    const lines = [
+        '## brainclaw — project coordination',
+        '',
+    ];
+    if (profile.hasSkills) {
+        lines.push('Use the brainclaw-context skill to refresh project memory.', 'Trigger: "refresh project memory", "load brainclaw context", "inspect active plans"', '');
+    }
+    lines.push('Before working:', '- Review the constraints and active plans below', '- Check the known traps section for pitfalls in your scope', '', 'The sections below are regenerated from brainclaw memory.', 'For the freshest state, use the brainclaw skill or ask the developer to run `brainclaw context`.');
+    return lines.join('\n');
+}
+function renderEstimationRule() {
+    return [
+        '## brainclaw — plans and estimation',
+        '',
+        'When creating a plan or step, always estimate duration in minutes.',
+        'When completing, report actual effort. This calibrates future estimates.',
+    ].join('\n');
+}
+function renderVersionCheckRule() {
+    return [
+        '## brainclaw — version check',
+        '',
+        'Call `bclaw_get_execution_context` at session start to check for brainclaw updates.',
+        'If a newer version is available, inform the developer and suggest updating.',
+        'Brainclaw updates may include new features, bug fixes, and improved coordination.',
+    ].join('\n');
+}
+function renderConstraints(state) {
+    const active = state.active_constraints.filter((c) => c.status === 'active');
+    if (active.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — active constraints',
+        '',
+        ...active.map((c) => `- ${c.text}`),
+    ].join('\n');
+}
+function renderInstructions(instructions) {
+    if (instructions.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — active instructions',
+        '',
+        ...instructions.map((text) => `- ${text}`),
+    ].join('\n');
+}
+function renderTopTraps(state, limit) {
+    const traps = state.known_traps
+        .filter((t) => t.visibility === 'shared' && (!t.status || t.status === 'active') && !t.platform_scope)
+        .sort((a, b) => severityOrder(b.severity) - severityOrder(a.severity))
+        .slice(0, limit);
+    if (traps.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — known traps',
+        '',
+        ...traps.map((t) => `- [${t.severity}] ${t.text}`),
+    ].join('\n');
+}
+function renderActivePlans(state, limit) {
+    const active = state.plan_items
+        .filter((p) => p.status === 'in_progress' || p.status === 'todo')
+        .sort((a, b) => {
+        if (a.status === 'in_progress' && b.status !== 'in_progress')
+            return -1;
+        if (b.status === 'in_progress' && a.status !== 'in_progress')
+            return 1;
+        return priorityOrder(b.priority) - priorityOrder(a.priority);
+    })
+        .slice(0, limit);
+    if (active.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — active plans',
+        '',
+        ...active.map((p) => {
+            const assignee = p.assignee ? ` (@${p.assignee})` : '';
+            return `- [${p.status}] ${p.text}${assignee}`;
+        }),
+    ].join('\n');
+}
+function renderRecentDecisions(state) {
+    const decisions = state.recent_decisions.slice(-5);
+    if (decisions.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — recent decisions',
+        '',
+        ...decisions.map((d) => `- ${d.text}`),
+    ].join('\n');
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function severityOrder(severity) {
+    switch (severity) {
+        case 'high': return 3;
+        case 'medium': return 2;
+        case 'low': return 1;
+        default: return 0;
+    }
+}
+function priorityOrder(priority) {
+    switch (priority) {
+        case 'critical': return 4;
+        case 'high': return 3;
+        case 'medium': return 2;
+        case 'low': return 1;
+        default: return 0;
+    }
+}
+function formatForAgent(agentName) {
+    switch (agentName) {
+        case 'claude-code': return 'claude-md';
+        case 'cursor': return 'cursor-rules';
+        case 'github-copilot': return 'copilot-instructions';
+        case 'opencode':
+        case 'codex': return 'agents-md';
+        case 'antigravity': return 'gemini-md';
+        case 'windsurf': return 'windsurf';
+        case 'cline': return 'cline';
+        case 'roo': return 'roo';
+        case 'continue': return 'continue';
+        default: return 'agents-md';
+    }
+}
+//# sourceMappingURL=instruction-templates.js.map

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',

package/dist/core/machine-profile.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
 import { MEMORY_DIR } from './io.js';
+import { buildAiSurfaceInventory, renderAiSurfaceSummary } from './ai-surface-inventory.js';
 // ── Detection Functions ────────────────────────────────────────────────────────
 const TOOLCHAINS = [
     { name: 'node', command: 'node', versionArgs: ['--version'] },
@@ -227,7 +228,7 @@ function detectWslDistros() {
  */
 export function buildMachineProfile() {
     return {
-        schema_version: 1,
+        schema_version: 2,
         generated_at: new Date().toISOString(),
         hostname: os.hostname(),
         os_user: os.userInfo().username,
@@ -241,6 +242,7 @@ export function buildMachineProfile() {
         ssh_keys: detectSshKeys(),
         toolchains: detectToolchains(),
         wsl_distros: detectWslDistros(),
+        ai_surfaces: buildAiSurfaceInventory(),
     };
 }
 /**
@@ -283,6 +285,7 @@ export function loadMachineProfile() {
  */
 export function renderMachineProfileSummary(profile) {
     const lines = [];
+    const aiSurfaces = profile.ai_surfaces ?? [];
     lines.push(`Machine: ${profile.hostname} (user: ${profile.os_user})`);
     lines.push(`Home: ${profile.home_dir}`);
     lines.push(`OS: ${profile.os_variant} (${profile.platform} ${profile.os_release}, ${profile.arch})`);
@@ -326,6 +329,9 @@ export function renderMachineProfileSummary(profile) {
             lines.push(`  - ${d.name}${d.default ? ' (default)' : ''}: ${nodeInfo}`);
         }
     }
+    if (aiSurfaces.length > 0) {
+        lines.push(...renderAiSurfaceSummary(aiSurfaces));
+    }
     lines.push(`Profile generated: ${profile.generated_at}`);
     return lines.join('\n');
 }

package/dist/core/migration.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
 import { memoryDir, memoryPath, readFileSync, writeFileAtomic, resolveEntityDir } from './io.js';
-import { BootstrapApplicationReceiptSchema, BootstrapImportPlanDocumentSchema, AgentIdentityDocumentSchema, BootstrapProfileDocumentSchema, CandidateSchema, ClaimSchema, ConfigSchema, MemorySeedDocumentSchema, ConstraintSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InstructionEntrySchema, PlanItemSchema, ProjectIdentityDocumentSchema, RuntimeNoteSchema, SessionSnapshotSchema, TrapSchema, } from './schema.js';
+import { BootstrapApplicationReceiptSchema, BootstrapImportPlanDocumentSchema, AgentIdentityDocumentSchema, BootstrapProfileDocumentSchema, CandidateSchema, ClaimSchema, ConfigSchema, MemorySeedDocumentSchema, ConstraintSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InstructionEntrySchema, PlanItemSchema, ProjectIdentityDocumentSchema, RuntimeNoteSchema, SessionSnapshotSchema, TrapSchema, AiSurfaceTaskRequestSchema, } from './schema.js';
 export class MigrationError extends Error {
     kind;
     documentType;
@@ -31,6 +31,7 @@ const registry = {
     plan: createRegistryEntry(PlanItemSchema),
     project_identity: createRegistryEntry(ProjectIdentityDocumentSchema),
     runtime_note: createRegistryEntry(RuntimeNoteSchema),
+    ai_surface_task: createRegistryEntry(AiSurfaceTaskRequestSchema),
     session_snapshot: createRegistryEntry(SessionSnapshotSchema),
     trap: createRegistryEntry(TrapSchema),
 };
@@ -164,6 +165,7 @@ export function scanMigrationStatus(cwd) {
     collectDirectory(entries, resolveEntityDir('runtime', effectiveCwd, 'read'), 'runtime_note', true);
     collectDirectory(entries, resolveEntityDir('runtime-hosts', effectiveCwd, 'read'), 'runtime_note', true);
     collectDirectory(entries, resolveEntityDir('runtime-private', effectiveCwd, 'read'), 'runtime_note', true);
+    collectDirectory(entries, resolveEntityDir('surface-tasks', effectiveCwd, 'read'), 'ai_surface_task');
     collectDirectory(entries, resolveEntityDir('instructions', effectiveCwd, 'read'), 'instruction');
     collectDirectory(entries, path.join(resolveEntityDir('bootstrap', effectiveCwd, 'read'), 'seeds'), 'memory_seed');
     collectDirectory(entries, resolveEntityDir('agents', effectiveCwd, 'read'), 'agent_identity');

package/dist/core/schema.js

@@ -96,6 +96,7 @@ export const TrapSchema = z.object({
     visibility: MemoryVisibilitySchema.default('shared'),
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
+    platform_scope: z.string().optional(),
 });
 export const HandoffSchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -344,6 +345,31 @@ export const RuntimeNoteSchema = z.object({
     expires_at: z.string().optional(),
     note_type: z.enum(['observation', 'session_start', 'session_end']).default('observation'),
 });
+// --- AI surface task request schemas ---
+export const AiSurfaceTaskStatusSchema = z.enum(['queued', 'in_progress', 'completed', 'cancelled', 'failed']);
+export const AiSurfaceTaskKindSchema = z.enum(['visual_asset', 'draft', 'summary', 'analysis', 'research', 'custom']);
+export const AiSurfaceTaskRequestSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    short_label: z.string().optional(),
+    title: z.string(),
+    instructions: z.string(),
+    target_surface: z.string(),
+    kind: AiSurfaceTaskKindSchema.default('custom'),
+    created_at: z.string(),
+    updated_at: z.string(),
+    author: z.string(),
+    author_id: z.string().optional(),
+    project_id: z.string().optional(),
+    session_id: z.string().optional(),
+    status: AiSurfaceTaskStatusSchema.default('queued'),
+    requested_outputs: z.array(z.string()).default([]),
+    related_paths: z.array(z.string()).optional(),
+    tags: z.array(z.string()).default([]),
+    claimed_at: z.string().optional(),
+    completed_at: z.string().optional(),
+    result_note: z.string().optional(),
+});
 // --- Runtime event schemas ---
 export const RuntimeEventTypeSchema = z.enum([
     'task_started',
@@ -459,6 +485,12 @@ export const MemorySeedSourceKindSchema = z.enum([
     'machine',
     'skill',
     'mcp',
+    'ci_config',
+    'contributing',
+    'changelog',
+    'docker',
+    'env_example',
+    'adr',
 ]);
 export const MemorySeedConfidenceSchema = z.enum(['low', 'medium', 'high']);
 export const MemorySeedDocumentSchema = z.object({
@@ -601,9 +633,11 @@ export const AgentIntegrationSurfaceSchema = z.object({
     location: AgentIntegrationLocationSchema,
     path: z.string().optional(),
 });
+export const AgentIntegrationLevelSchema = z.enum(['full', 'standard', 'limited', 'custom']);
 export const AgentIntegrationDeclarationSchema = z.object({
     agent_name: AgentIntegrationNameSchema,
     declaration_source: AgentIntegrationDeclarationSourceSchema.default('manual'),
+    level: AgentIntegrationLevelSchema.optional(),
     surfaces: z.array(AgentIntegrationSurfaceSchema).default([]),
     notes: z.string().optional(),
 });

package/dist/core/setup-flow.js

@@ -0,0 +1,191 @@
+/**
+ * Setup flow logic for the new onboarding experience.
+ *
+ * Two modes:
+ * - Quick: init the current repo (1-2 MCP calls)
+ * - Batch: scan roots and init multiple repos (legacy 4-step flow)
+ *
+ * Quick flow:
+ *   1. Auto-detect repo, agent, nearby stores → ask project type + topology
+ *   2. Init + optional bootstrap → done
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryExists } from './io.js';
+import { detectAiAgent } from './ai-agent-detection.js';
+import { resolveStoreChain } from './store-resolution.js';
+import { analyzeRepository } from './repo-analysis.js';
+import { getAgentCapabilityProfile, getAllAgentCapabilityProfiles } from './agent-capability.js';
+import { describeAgentSurfaces } from './agent-capability.js';
+import { loadState } from './state.js';
+/**
+ * Probe the current working directory to understand what we're working with.
+ * This is the first step of the quick setup flow — no questions yet, just detection.
+ */
+export function probeForQuickSetup(cwd = process.cwd()) {
+    const isGitRepo = fs.existsSync(path.join(cwd, '.git'));
+    const alreadyInitialized = memoryExists(cwd);
+    const repoName = path.basename(cwd);
+    // Detect agent
+    const detectedAi = detectAiAgent();
+    const detectedAgent = detectedAi
+        ? { name: detectedAi.name, profile: getAgentCapabilityProfile(detectedAi.name) }
+        : undefined;
+    // Find other known agent profiles (for info)
+    const otherAgents = detectedAgent
+        ? getAllAgentCapabilityProfiles().filter((p) => p.name !== detectedAgent.name)
+        : getAllAgentCapabilityProfiles();
+    // Scan nearby stores
+    const nearbyStores = resolveStoreChain(cwd);
+    // Has content?
+    const IGNORED = new Set(['.git', '.brainclaw', '.gitignore', '.gitattributes', '.DS_Store', 'Thumbs.db']);
+    let hasContent = false;
+    try {
+        const entries = fs.readdirSync(cwd);
+        hasContent = entries.some((e) => !IGNORED.has(e));
+    }
+    catch {
+        // empty or unreadable
+    }
+    // Analyze repo for project type suggestion
+    let suggestedProjectType = 'standalone';
+    let analysisReasons = [];
+    try {
+        const analysis = analyzeRepository(cwd);
+        if (analysis.recommendedMode === 'multi-project') {
+            suggestedProjectType = 'workspace';
+        }
+        analysisReasons = analysis.reasons;
+    }
+    catch {
+        // analysis failed — default to standalone
+    }
+    // If there are nearby stores, suggest linking
+    const parentStores = nearbyStores.filter((s) => s.depth > 0 && s.role === 'workspace');
+    if (parentStores.length > 0 && !alreadyInitialized) {
+        suggestedProjectType = 'linked';
+    }
+    // Build repo summary
+    const summaryParts = [];
+    if (isGitRepo)
+        summaryParts.push('git repo');
+    if (hasContent)
+        summaryParts.push(`"${repoName}"`);
+    if (analysisReasons.length > 0)
+        summaryParts.push(analysisReasons[0]);
+    const repoSummary = summaryParts.join(', ') || 'empty directory';
+    return {
+        cwd,
+        isGitRepo,
+        alreadyInitialized,
+        repoName,
+        repoSummary,
+        detectedAgent,
+        otherAgents,
+        nearbyStores,
+        hasContent,
+        suggestedProjectType,
+        analysisReasons,
+    };
+}
+/**
+ * Build the structured response for the initial probe step of quick setup.
+ * Returns data the agent can use to present choices to the user.
+ */
+export function buildQuickSetupProbeResponse(probe) {
+    const lines = [];
+    if (probe.alreadyInitialized) {
+        lines.push(`This project (${probe.repoName}) is already initialized with brainclaw.`);
+        lines.push('Use `brainclaw export --detect --write` to regenerate agent files, or `brainclaw upgrade` to migrate.');
+        return {
+            text: lines.join('\n'),
+            structured: {
+                already_initialized: true,
+                cwd: probe.cwd,
+                repo_name: probe.repoName,
+            },
+        };
+    }
+    lines.push(`Detected: ${probe.repoSummary}`);
+    if (probe.detectedAgent) {
+        lines.push(`Agent: ${probe.detectedAgent.name} (${probe.detectedAgent.profile.templateTier === 'A' ? 'full integration' : probe.detectedAgent.profile.templateTier === 'B' ? 'standard integration' : 'limited integration'})`);
+        lines.push(`Surfaces: ${describeAgentSurfaces(probe.detectedAgent.name).join(', ')}`);
+    }
+    if (probe.nearbyStores.length > 0) {
+        lines.push('');
+        lines.push('Nearby brainclaw stores:');
+        for (const store of probe.nearbyStores) {
+            lines.push(`  - ${store.role} at ${store.cwd} (depth ${store.depth})`);
+        }
+    }
+    lines.push('');
+    lines.push('Ask the user:');
+    lines.push('');
+    lines.push('1. What kind of project is this?');
+    lines.push(`   - Standalone project (single .brainclaw/ for the whole repo)${probe.suggestedProjectType === 'standalone' ? ' ← suggested' : ''}`);
+    lines.push(`   - Workspace with sub-projects (monorepo)${probe.suggestedProjectType === 'workspace' ? ' ← suggested' : ''}`);
+    if (probe.nearbyStores.some((s) => s.role === 'workspace')) {
+        lines.push(`   - Linked to an existing workspace${probe.suggestedProjectType === 'linked' ? ' ← suggested' : ''}`);
+    }
+    lines.push('');
+    lines.push('2. Should the memory be shared with the team?');
+    lines.push('   - Yes, shared via git (.brainclaw/ tracked in git) ← recommended');
+    lines.push('   - No, local only (.brainclaw/ gitignored)');
+    return {
+        text: lines.join('\n'),
+        structured: {
+            pending_question: 'quick_init',
+            probe: {
+                cwd: probe.cwd,
+                repo_name: probe.repoName,
+                repo_summary: probe.repoSummary,
+                is_git_repo: probe.isGitRepo,
+                has_content: probe.hasContent,
+                detected_agent: probe.detectedAgent?.name ?? null,
+                agent_surfaces: probe.detectedAgent ? describeAgentSurfaces(probe.detectedAgent.name) : [],
+                nearby_stores: probe.nearbyStores.map((s) => ({ role: s.role, path: s.cwd, depth: s.depth })),
+                suggested_project_type: probe.suggestedProjectType,
+            },
+            choices: {
+                project_type: ['standalone', 'workspace', ...(probe.nearbyStores.some((s) => s.role === 'workspace') ? ['linked'] : [])],
+                topology: ['embedded', 'sidecar'],
+            },
+        },
+    };
+}
+/**
+ * Generate a "moment aha" preview after init — shows what an agent
+ * would see when calling bclaw_get_context on this project.
+ */
+export function buildOnboardingPreview(cwd) {
+    try {
+        const state = loadState(cwd);
+        const constraints = state.active_constraints.filter((c) => c.status === 'active');
+        const traps = state.known_traps.filter((t) => t.visibility === 'shared' && (!t.status || t.status === 'active'));
+        const plans = state.plan_items.filter((p) => p.status === 'in_progress' || p.status === 'todo');
+        if (constraints.length === 0 && traps.length === 0 && plans.length === 0) {
+            return 'Memory is empty. Run bclaw_bootstrap to extract initial context from this repo.';
+        }
+        const lines = ['Here is what your agent will see:'];
+        if (constraints.length > 0) {
+            lines.push(`  Constraints: ${constraints.length} active`);
+            for (const c of constraints.slice(0, 3))
+                lines.push(`    - ${c.text}`);
+        }
+        if (traps.length > 0) {
+            lines.push(`  Traps: ${traps.length} known`);
+            for (const t of traps.slice(0, 3))
+                lines.push(`    - [${t.severity}] ${t.text}`);
+        }
+        if (plans.length > 0) {
+            lines.push(`  Plans: ${plans.length} active`);
+            for (const p of plans.slice(0, 3))
+                lines.push(`    - [${p.status}] ${p.text}`);
+        }
+        return lines.join('\n');
+    }
+    catch {
+        return 'Memory is empty. Run bclaw_bootstrap to extract initial context from this repo.';
+    }
+}
+//# sourceMappingURL=setup-flow.js.map

package/dist/core/setup-state.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { writeFileAtomic } from './io.js';
+import { ensureMemoryDir, writeFileAtomic } from './io.js';
+import { defaultConfig, saveConfig } from './config.js';
 export function resolveHomeDir(env = process.env) {
     return env.HOME?.trim() || env.USERPROFILE?.trim() || undefined;
 }
@@ -47,4 +48,32 @@ export function hasCompletedSetup(env = process.env) {
     const configPath = userStoreConfigPath(env);
     return configPath ? fs.existsSync(configPath) : false;
 }
+/**
+ * Ensure the user-global store (~/.brainclaw/) exists, creating it implicitly
+ * if absent. This replaces the old "setup required before init" guard —
+ * init can now auto-create the minimal user store on first run.
+ *
+ * Idempotent: returns immediately if the user store already exists.
+ * Non-fatal: logs a warning if creation fails but does not throw.
+ */
+export function ensureUserStore(env = process.env) {
+    const home = resolveHomeDir(env);
+    if (!home)
+        return false;
+    const configPath = path.join(home, '.brainclaw', 'config.yaml');
+    if (fs.existsSync(configPath)) {
+        return true; // already exists
+    }
+    try {
+        ensureMemoryDir(home);
+        const cfg = defaultConfig('user-global');
+        saveConfig(cfg, home);
+        fs.appendFileSync(configPath, 'store_type: user\n');
+        return true;
+    }
+    catch (err) {
+        console.warn(`Warning: could not create user store at ${path.join(home, '.brainclaw')}:`, err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
 //# sourceMappingURL=setup-state.js.map