brainclaw 0.19.10 → 0.19.11

package/dist/cli.js

@@ -515,6 +515,7 @@ program
     .option('--refresh', 'Force a fresh bootstrap scan instead of reusing the current profile')
     .option('--interview', 'Render the adaptive interview prompts instead of the bootstrap summary')
     .option('--audience <audience>', 'Target interview prompts for cli, ide_chat, or any')
+    .option('--answers-file <path>', 'Load structured bootstrap interview answers from a JSON file')
     .option('--apply', 'Import the current bootstrap proposal into canonical memory')
     .option('--uninstall', 'Deactivate the last bootstrap import managed by this workspace')
     .option('-y, --yes', 'Skip confirmation prompts for apply/uninstall')

package/dist/commands/bootstrap.js

@@ -1,7 +1,9 @@
+import fs from 'node:fs';
 import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { memoryExists } from '../core/io.js';
 import { applyBootstrapImport, renderBootstrapInterview, renderBootstrapSummary, runBootstrapProfile, uninstallBootstrapImport, } from '../core/bootstrap.js';
+import { BootstrapInterviewAnswerSchema } from '../core/schema.js';
 export async function runBootstrap(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
@@ -14,6 +16,7 @@ export async function runBootstrap(options = {}) {
             process.exit(1);
         }
         const audience = resolveBootstrapInterviewAudience(options.audience);
+        const interviewAnswers = loadBootstrapInterviewAnswers(options.answersFile);
         if (options.uninstall) {
             await confirmBootstrapAction('Remove the last bootstrap import?', options.yes);
             const result = uninstallBootstrapImport(cwd);
@@ -21,7 +24,7 @@ export async function runBootstrap(options = {}) {
                 console.log('No bootstrap import receipt found.');
                 return;
             }
-            console.log(`✔ Bootstrap uninstall completed: ${result.deactivatedCount} instruction(s) deactivated, ${result.skippedCount} artifact(s) skipped.`);
+            console.log(`✔ Bootstrap uninstall completed: ${result.deactivatedCount} instruction(s) deactivated, ${result.deletedCount} artifact(s) deleted, ${result.skippedCount} artifact(s) skipped.`);
             return;
         }
         if (options.apply) {
@@ -29,6 +32,7 @@ export async function runBootstrap(options = {}) {
             const result = applyBootstrapImport({
                 target: options.for,
                 refresh: options.refresh,
+                interviewAnswers,
                 cwd,
             });
             console.log(`✔ Bootstrap import applied: ${result.createdCount} item(s) created, ${result.skippedCount} suggestion(s) skipped.`);
@@ -40,6 +44,7 @@ export async function runBootstrap(options = {}) {
         const result = runBootstrapProfile({
             target: options.for,
             refresh: options.refresh,
+            interviewAnswers,
             cwd,
         });
         if (options.json) {
@@ -76,6 +81,17 @@ function resolveBootstrapInterviewAudience(value) {
     }
     throw new Error(`Unsupported bootstrap interview audience '${value}'. Use cli, ide_chat, or any.`);
 }
+function loadBootstrapInterviewAnswers(filepath) {
+    if (!filepath) {
+        return [];
+    }
+    const raw = fs.readFileSync(filepath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+        throw new Error(`Bootstrap interview answers file must contain a JSON array: ${filepath}`);
+    }
+    return parsed.map((entry) => BootstrapInterviewAnswerSchema.parse(entry));
+}
 async function confirmBootstrapAction(question, yes) {
     if (yes) {
         return;

package/dist/commands/init.js

@@ -243,6 +243,7 @@ export async function runInit(options = {}) {
     if ((onboardingPreflight.importPlan.interview?.question_count ?? 0) > 0) {
         console.log('');
         console.log(`Interview: run 'brainclaw bootstrap --interview --audience cli' for terminal agents or '--audience ide_chat' for IDE chat agents.`);
+        console.log(`Apply confirmed answers: write a JSON answers file and run 'brainclaw bootstrap --answers-file <path> --apply'.`);
     }
     else if ((onboardingPreflight.profile.gaps?.length ?? 0) > 0) {
         console.log('');

package/dist/commands/mcp.js

@@ -2,7 +2,7 @@ import readline from 'node:readline';
 import { Worker } from 'node:worker_threads';
 import { getTriggeredItems, renderTriggeredItems } from '../core/lifecycle.js';
 import { resolveCrossProjectTarget, writeCrossProjectNote } from '../core/cross-project.js';
-import { renderBootstrapSummary, runBootstrapProfile } from '../core/bootstrap.js';
+import { applyBootstrapImport, renderBootstrapInterview, renderBootstrapSummary, runBootstrapProfile, uninstallBootstrapImport } from '../core/bootstrap.js';
 import { buildAgentToolingContext, renderAgentToolingSummary } from '../core/agent-context.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { buildContext, renderContextMarkdown, renderContextPromptTemplate } from '../core/context.js';
@@ -30,6 +30,7 @@ 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 { readUnseenEvents, buildNotificationSummary } from '../core/event-log.js';
+import { BootstrapInterviewAnswerSchema } from '../core/schema.js';
 export const SCHEMA_VERSION = '0.6.0';
 export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2024-11-05'];
 export const MCP_SERVER_NOT_INITIALIZED = -32002;
@@ -67,6 +68,15 @@ export const MCP_READ_TOOLS = [
             properties: {
                 target: { type: 'string', description: 'Optional path or scope to tailor the bootstrap.' },
                 refresh: { type: 'boolean', description: 'Force a fresh bootstrap scan.' },
+                audience: { type: 'string', description: 'Optional interview audience filter: cli, ide_chat, or any.' },
+                interview: { type: 'boolean', description: 'Render interview text instead of the summary text.' },
+                apply: { type: 'boolean', description: 'Apply the current import proposal into canonical memory.' },
+                uninstall: { type: 'boolean', description: 'Uninstall the last bootstrap-managed import.' },
+                interviewAnswers: {
+                    type: 'array',
+                    description: 'Optional structured interview answers. Each answer may include question_id, response_text, response_items, response_boolean, and explicit suggestions.',
+                    items: { type: 'object' },
+                },
             },
         },
     },
@@ -506,6 +516,18 @@ export function createToolErrorResponse(kind, message, details) {
         },
     }, true);
 }
+function normalizeBootstrapInterviewAnswersArg(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry) => BootstrapInterviewAnswerSchema.parse(entry));
+}
+function normalizeBootstrapInterviewAudienceArg(value) {
+    if (value === 'cli' || value === 'ide_chat' || value === 'any') {
+        return value;
+    }
+    return 'any';
+}
 function requireObjectParams(params, id) {
     if (params === undefined) {
         return {};
@@ -1040,19 +1062,64 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         };
     }
     if (name === 'bclaw_bootstrap') {
+        const interviewAnswers = normalizeBootstrapInterviewAnswersArg(args.interviewAnswers);
+        if (args.apply && args.uninstall) {
+            throw new Error('bclaw_bootstrap does not allow apply and uninstall at the same time.');
+        }
+        if (args.uninstall) {
+            const result = uninstallBootstrapImport(cwd);
+            const text = !result.receipt
+                ? 'No bootstrap import receipt found.'
+                : `Bootstrap uninstall completed: ${result.deactivatedCount} instruction(s) deactivated, ${result.deletedCount} artifact(s) deleted, ${result.skippedCount} artifact(s) skipped.`;
+            return {
+                content: [{ type: 'text', text }],
+                structuredContent: {
+                    receipt: result.receipt,
+                    deactivated_count: result.deactivatedCount,
+                    deleted_count: result.deletedCount,
+                    skipped_count: result.skippedCount,
+                },
+            };
+        }
+        if (args.apply) {
+            const applied = applyBootstrapImport({
+                target: args.target,
+                refresh: args.refresh,
+                interviewAnswers,
+                cwd,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Bootstrap import applied: ${applied.createdCount} item(s) created, ${applied.skippedCount} suggestion(s) skipped.`,
+                    }],
+                structuredContent: {
+                    created_count: applied.createdCount,
+                    skipped_count: applied.skippedCount,
+                    receipt: applied.receipt,
+                    import_plan: applied.proposal,
+                },
+            };
+        }
         const result = runBootstrapProfile({
             target: args.target,
             refresh: args.refresh,
+            interviewAnswers,
             cwd,
         });
+        const audience = normalizeBootstrapInterviewAudienceArg(args.audience);
+        const text = args.interview
+            ? renderBootstrapInterview(result, audience)
+            : renderBootstrapSummary(result);
         return {
-            content: [{ type: 'text', text: renderBootstrapSummary(result) }],
+            content: [{ type: 'text', text }],
             structuredContent: {
                 summary: result.profile.summary,
                 target: result.profile.target,
                 repo_fingerprint: result.profile.repo_fingerprint,
                 sources_scanned: result.profile.sources_scanned,
                 workspace_kind: result.profile.workspace_kind,
+                onboarding_mode: result.profile.onboarding_mode,
                 confidence: result.profile.confidence,
                 native_instruction_files: result.profile.native_instruction_files,
                 gaps: result.profile.gaps,

package/dist/core/bootstrap.js

@@ -1,17 +1,18 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { JsonStore } from './json-store.js';
-import { generateId, nowISO } from './ids.js';
+import { generateId, generateIdWithLabel, nowISO } from './ids.js';
 import { memoryPath, resolveEntityDir, withStoreLock, writeFileAtomic } from './io.js';
-import { BootstrapApplicationReceiptSchema, BootstrapInterviewPlanSchema, BootstrapInterviewQuestionSchema, BootstrapImportPlanDocumentSchema, BootstrapProfileDocumentSchema, BootstrapSuggestionDocumentSchema, MemorySeedDocumentSchema, } from './schema.js';
+import { BootstrapApplicationReceiptSchema, BootstrapInterviewAnswerSchema, BootstrapInterviewPlanSchema, BootstrapInterviewQuestionSchema, BootstrapImportPlanDocumentSchema, BootstrapProfileDocumentSchema, BootstrapSuggestionDocumentSchema, MemorySeedDocumentSchema, } from './schema.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { analyzeRepository } from './repo-analysis.js';
 import { buildExecutionContext, compactExecutionContext } from './execution-context.js';
 import { buildAgentToolingContext } from './agent-context.js';
 import { createInstruction, loadInstructions, saveInstruction } from './instructions.js';
 import { resolveCurrentAgentName } from './agent-registry.js';
-import { loadState } from './state.js';
+import { loadState, persistState } from './state.js';
 import { generateMarkdown } from './markdown.js';
 const README_CANDIDATES = ['README.md', 'README', 'README.txt', 'README.mdx'];
 const DOC_HINTS = ['docs', 'doc'];
@@ -47,25 +48,56 @@ const NATIVE_INSTRUCTION_DIRS = [
 export function runBootstrapProfile(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const target = normalizeTarget(options.target);
+    const interviewAnswers = normalizeBootstrapInterviewAnswers(options.interviewAnswers);
     const existing = loadBootstrapProfile(cwd);
     const existingPlan = loadBootstrapImportPlan(cwd);
     const lastApplication = loadBootstrapApplication(cwd);
     const existingFingerprint = currentRepoFingerprint(cwd);
     if (!options.refresh && existing && existingPlan && isProfileReusable(existing, target, existingFingerprint)) {
+        const seeds = listBootstrapSeeds(cwd);
+        const importPlan = interviewAnswers.length > 0
+            ? buildBootstrapImportPlan({
+                cwd,
+                target,
+                workspaceKind: existing.workspace_kind ?? 'existing',
+                onboardingMode: existing.onboarding_mode ?? inferOnboardingMode({
+                    workspaceKind: existing.workspace_kind ?? 'existing',
+                    confidence: existing.confidence ?? 'low',
+                    readmePresent: existing.sources_scanned.includes('README'),
+                    nativeInstructionFiles: existing.native_instruction_files,
+                }),
+                confidence: existing.confidence ?? 'low',
+                gaps: existing.gaps,
+                seeds,
+                interviewAnswers,
+            })
+            : existingPlan;
         return {
             profile: existing,
-            seeds: listBootstrapSeeds(cwd),
-            importPlan: existingPlan,
+            seeds,
+            importPlan,
             lastApplication,
             reusedProfile: true,
         };
     }
     const artifacts = buildBootstrapArtifacts({ cwd, target, repoFingerprint: existingFingerprint });
     persistBootstrapArtifacts(artifacts, cwd);
+    const importPlan = interviewAnswers.length > 0
+        ? buildBootstrapImportPlan({
+            cwd,
+            target,
+            workspaceKind: artifacts.profile.workspace_kind ?? 'existing',
+            onboardingMode: artifacts.profile.onboarding_mode ?? 'existing_sparse',
+            confidence: artifacts.profile.confidence ?? 'low',
+            gaps: artifacts.profile.gaps,
+            seeds: artifacts.seeds,
+            interviewAnswers,
+        })
+        : artifacts.importPlan;
     return {
         profile: artifacts.profile,
         seeds: artifacts.seeds,
-        importPlan: artifacts.importPlan,
+        importPlan,
         lastApplication,
         reusedProfile: false,
     };
@@ -120,6 +152,9 @@ export function renderBootstrapSummary(result) {
     if (result.profile.workspace_kind) {
         lines.push(`Workspace kind: ${result.profile.workspace_kind}`);
     }
+    if (result.profile.onboarding_mode) {
+        lines.push(`Onboarding mode: ${result.profile.onboarding_mode}`);
+    }
     if (result.profile.confidence) {
         lines.push(`Confidence: ${result.profile.confidence}`);
     }
@@ -132,6 +167,9 @@ export function renderBootstrapSummary(result) {
         lines.push(`Open gaps: ${result.profile.gaps.join(' | ')}`);
     }
     lines.push(`Import suggestions: ${result.importPlan.suggestion_count}`);
+    if ((result.importPlan.confirmed_suggestion_count ?? 0) > 0) {
+        lines.push(`Confirmed by interview: ${result.importPlan.confirmed_suggestion_count}`);
+    }
     if (result.profile.repo_fingerprint) {
         lines.push(`Repo fingerprint: ${result.profile.repo_fingerprint}`);
     }
@@ -156,7 +194,7 @@ export function renderBootstrapSummary(result) {
         lines.push('');
         lines.push('Adaptive interview:');
         for (const question of result.importPlan.interview.questions.slice(0, 6)) {
-            lines.push(`- [${question.priority}/${question.audience}] ${question.prompt}`);
+            lines.push(`- [${question.priority}/${question.audience}] [${question.id}] ${question.prompt}`);
         }
     }
     if (result.seeds.length > 0) {
@@ -180,9 +218,12 @@ export function renderBootstrapInterview(result, audience = 'any') {
     const lines = [interview.summary, `Audience: ${audience}`];
     lines.push('');
     for (const [index, question] of questions.entries()) {
-        lines.push(`${index + 1}. ${question.prompt}`);
+        lines.push(`${index + 1}. [${question.id}] ${question.prompt}`);
         lines.push(`   Why: ${question.rationale}`);
         lines.push(`   Expected answer: ${question.response_kind}`);
+        if (question.target_hints.length > 0) {
+            lines.push(`   Target hints: ${question.target_hints.join(', ')}`);
+        }
     }
     return lines.join('\n');
 }
@@ -239,6 +280,12 @@ function buildBootstrapArtifacts(input) {
         nativeInstructionFiles,
         seedCount: uniqueSeeds.length,
     });
+    const onboardingMode = inferOnboardingMode({
+        workspaceKind: workspace.kind,
+        readmePresent: Boolean(readmePath),
+        nativeInstructionFiles,
+        confidence,
+    });
     const gaps = inferBootstrapGaps({
         workspaceKind: workspace.kind,
         readmePresent: Boolean(readmePath),
@@ -253,6 +300,7 @@ function buildBootstrapArtifacts(input) {
         repoAnalysis,
         seeds: uniqueSeeds,
         target: input.target,
+        onboardingMode,
         confidence,
         gaps,
     });
@@ -260,6 +308,7 @@ function buildBootstrapArtifacts(input) {
         cwd: input.cwd,
         target: input.target,
         workspaceKind: workspace.kind,
+        onboardingMode,
         confidence,
         gaps,
         seeds: uniqueSeeds,
@@ -276,6 +325,7 @@ function buildBootstrapArtifacts(input) {
             seed_count: uniqueSeeds.length,
             target: input.target,
             workspace_kind: workspace.kind,
+            onboarding_mode: onboardingMode,
             confidence,
             native_instruction_files: nativeInstructionFiles,
             gaps,
@@ -748,6 +798,7 @@ function dedupeSeeds(seeds) {
 function buildSummary(input) {
     const parts = [];
     parts.push(`Bootstrap summary${input.target ? ` for ${input.target}` : ''}: ${input.workspaceKind} workspace, ${input.seeds.length} derived signal(s).`);
+    parts.push(`Onboarding mode: ${input.onboardingMode}.`);
     parts.push(`Confidence: ${input.confidence}.`);
     parts.push(`Repository mode looks ${input.repoAnalysis.recommendedMode}.`);
     if (input.agentsPresent) {
@@ -786,7 +837,7 @@ function buildBootstrapImportPlan(input) {
         if (!suggestion) {
             continue;
         }
-        const suggestionKey = suggestionIdentityKey(suggestion);
+        const suggestionKey = genericSuggestionIdentityKey(suggestion);
         if (seenSuggestionKeys.has(suggestionKey) || activeInstructionKeys.has(suggestionKey)) {
             continue;
         }
@@ -809,7 +860,7 @@ function buildBootstrapImportPlan(input) {
         if (!suggestion) {
             continue;
         }
-        const suggestionKey = suggestionIdentityKey(suggestion);
+        const suggestionKey = genericSuggestionIdentityKey(suggestion);
         if (seenSuggestionKeys.has(suggestionKey) || activeInstructionKeys.has(suggestionKey)) {
             continue;
         }
@@ -819,9 +870,6 @@ function buildBootstrapImportPlan(input) {
             schema_version: DERIVED_SCHEMA_VERSION,
         }));
     }
-    const summary = suggestions.length === 0
-        ? 'No safe bootstrap imports are ready yet; review the gaps and use an interview/import step before promoting derived context.'
-        : `${suggestions.length} bootstrap instruction suggestion(s) are ready to import after review.`;
     const interview = buildBootstrapInterviewPlan({
         workspaceKind: input.workspaceKind,
         gaps: input.gaps,
@@ -830,15 +878,35 @@ function buildBootstrapImportPlan(input) {
                 .filter((seed) => seed.source_kind === 'native_instruction')
                 .map((seed) => seed.source_ref))],
     });
+    const interviewSuggestions = buildBootstrapInterviewSuggestions(interview, input.interviewAnswers ?? []);
+    let confirmedSuggestionCount = 0;
+    for (const suggestion of interviewSuggestions) {
+        const suggestionKey = genericSuggestionIdentityKey(suggestion);
+        if ((suggestion.target === 'instruction' && activeInstructionKeys.has(suggestionKey)) || seenSuggestionKeys.has(suggestionKey)) {
+            continue;
+        }
+        seenSuggestionKeys.add(suggestionKey);
+        confirmedSuggestionCount++;
+        suggestions.push(BootstrapSuggestionDocumentSchema.parse({
+            ...suggestion,
+            schema_version: DERIVED_SCHEMA_VERSION,
+        }));
+    }
+    const summary = suggestions.length === 0
+        ? 'No safe bootstrap imports are ready yet; review the gaps and use an interview/import step before promoting derived context.'
+        : `${suggestions.length} bootstrap suggestion(s) are ready to import after review${confirmedSuggestionCount > 0 ? `, including ${confirmedSuggestionCount} confirmed via interview` : ''}.`;
     return BootstrapImportPlanDocumentSchema.parse({
         schema_version: DERIVED_SCHEMA_VERSION,
         derived_at: nowISO(),
         target: input.target,
         workspace_kind: input.workspaceKind,
+        onboarding_mode: input.onboardingMode,
         confidence: input.confidence,
         summary,
         requires_confirmation: true,
         gaps: input.gaps,
+        confirmed_suggestion_count: confirmedSuggestionCount,
+        interview_answer_count: input.interviewAnswers?.length ?? 0,
         suggestion_count: suggestions.length,
         suggestions,
         interview,
@@ -846,37 +914,38 @@ function buildBootstrapImportPlan(input) {
 }
 function buildBootstrapInterviewPlan(input) {
     const questions = [];
-    const add = (prompt, rationale, priority, audience, responseKind, gapKeys) => {
+    const add = (prompt, rationale, priority, audience, responseKind, gapKeys, targetHints) => {
         questions.push(BootstrapInterviewQuestionSchema.parse({
-            id: generateId('bootstrap_suggestions'),
+            id: bootstrapInterviewQuestionId(prompt, audience),
             prompt,
             rationale,
             priority,
             audience,
             response_kind: responseKind,
             gap_keys: gapKeys,
+            target_hints: targetHints,
         }));
     };
     if (input.workspaceKind === 'empty') {
-        add('What is this workspace trying to build in one sentence?', 'An empty workspace needs a product intent anchor before Brainclaw can create durable guidance.', 'high', 'any', 'short_text', ['project intent is not documented yet']);
-        add('Which coding agents do you expect to use here, and should they work mostly sequentially or in parallel later?', 'Bootstrap should capture collaboration expectations early, especially before worktree isolation exists.', 'high', 'any', 'list', ['agent workflow expectations should be captured explicitly']);
-        add('For a CLI-only agent, what should the very first safe action be after reading context?', 'Pure CLI agents need an explicit first action because they do not benefit from rich IDE affordances.', 'medium', 'cli', 'short_text', ['agent workflow expectations should be captured explicitly']);
-        add('For an IDE chat agent, what should it ask or inspect before editing code?', 'IDE chat agents can ask targeted follow-up questions; capturing that expectation avoids drift between surfaces.', 'medium', 'ide_chat', 'short_text', ['agent workflow expectations should be captured explicitly']);
+        add('What is this workspace trying to build in one sentence?', 'An empty workspace needs a product intent anchor before Brainclaw can create durable guidance.', 'high', 'any', 'short_text', ['project intent is not documented yet'], ['decision']);
+        add('Which coding agents do you expect to use here, and should they work mostly sequentially or in parallel later?', 'Bootstrap should capture collaboration expectations early, especially before worktree isolation exists.', 'high', 'any', 'list', ['agent workflow expectations should be captured explicitly'], ['constraint', 'instruction']);
+        add('For a CLI-only agent, what should the very first safe action be after reading context?', 'Pure CLI agents need an explicit first action because they do not benefit from rich IDE affordances.', 'medium', 'cli', 'short_text', ['agent workflow expectations should be captured explicitly'], ['instruction']);
+        add('For an IDE chat agent, what should it ask or inspect before editing code?', 'IDE chat agents can ask targeted follow-up questions; capturing that expectation avoids drift between surfaces.', 'medium', 'ide_chat', 'short_text', ['agent workflow expectations should be captured explicitly'], ['instruction']);
     }
     if (input.gaps.includes('no README-level project overview detected')) {
-        add('What is the current purpose of this existing project, and what would you want a new agent to understand first?', 'When README context is missing, Brainclaw needs an explicit project overview to avoid weak brownfield inference.', 'high', 'any', 'long_text', ['no README-level project overview detected']);
+        add('What is the current purpose of this existing project, and what would you want a new agent to understand first?', 'When README context is missing, Brainclaw needs an explicit project overview to avoid weak brownfield inference.', 'high', 'any', 'long_text', ['no README-level project overview detected'], ['decision']);
     }
     if (input.gaps.includes('no native agent instruction files detected')) {
-        add('Should Brainclaw treat this project as agent-guided even though no native agent instruction files were found?', 'This determines whether Brainclaw should synthesize workflow guidance or stay memory-only for now.', 'medium', 'any', 'boolean', ['no native agent instruction files detected']);
+        add('Should Brainclaw treat this project as agent-guided even though no native agent instruction files were found?', 'This determines whether Brainclaw should synthesize workflow guidance or stay memory-only for now.', 'medium', 'any', 'boolean', ['no native agent instruction files detected'], ['decision']);
     }
     if (input.gaps.includes('derived context is sparse and may need an interview')) {
-        add('Which constraints or conventions are important enough that every future agent should see them immediately?', 'Sparse derived context should be turned into a small set of high-signal shared instructions or constraints.', 'high', 'any', 'list', ['derived context is sparse and may need an interview']);
+        add('Which constraints or conventions are important enough that every future agent should see them immediately?', 'Sparse derived context should be turned into a small set of high-signal shared instructions or constraints.', 'high', 'any', 'list', ['derived context is sparse and may need an interview'], ['constraint']);
     }
     if (input.nativeInstructionSources.length > 0) {
-        add(`Which parts of ${input.nativeInstructionSources.join(', ')} should become durable Brainclaw memory, and which parts should remain local agent guidance only?`, 'Native agent files are derived context first; Brainclaw needs a selective import decision instead of silently promoting them.', 'medium', 'ide_chat', 'long_text', ['native instruction import boundary']);
+        add(`Which parts of ${input.nativeInstructionSources.join(', ')} should become durable Brainclaw memory, and which parts should remain local agent guidance only?`, 'Native agent files are derived context first; Brainclaw needs a selective import decision instead of silently promoting them.', 'medium', 'ide_chat', 'long_text', ['native instruction import boundary'], ['decision', 'instruction', 'constraint']);
     }
     if (questions.length === 0 && input.confidence !== 'high') {
-        add('What is still ambiguous enough that a future agent would likely ask you before proceeding?', 'Fallback question when bootstrap confidence is not high but no specific gap generated a dedicated prompt.', 'medium', 'any', 'long_text', ['confidence fallback']);
+        add('What is still ambiguous enough that a future agent would likely ask you before proceeding?', 'Fallback question when bootstrap confidence is not high but no specific gap generated a dedicated prompt.', 'medium', 'any', 'long_text', ['confidence fallback'], ['instruction', 'constraint']);
     }
     const summary = questions.length === 0
         ? 'No adaptive interview questions are needed right now.'
@@ -891,6 +960,139 @@ function buildBootstrapInterviewPlan(input) {
         questions,
     });
 }
+function bootstrapInterviewQuestionId(prompt, audience) {
+    const digest = crypto.createHash('sha1').update(`${audience}:${prompt}`).digest('hex').slice(0, 8);
+    return `biq_${digest}`;
+}
+function normalizeBootstrapInterviewAnswers(answers) {
+    if (!answers || answers.length === 0) {
+        return [];
+    }
+    return answers.map((answer) => BootstrapInterviewAnswerSchema.parse(answer));
+}
+function buildBootstrapInterviewSuggestions(interview, answers) {
+    if (!interview || answers.length === 0) {
+        return [];
+    }
+    const questionsById = new Map(interview.questions.map((question) => [question.id, question]));
+    const suggestions = [];
+    for (const answer of answers) {
+        const question = questionsById.get(answer.question_id);
+        if (!question) {
+            continue;
+        }
+        if (answer.suggestions.length > 0) {
+            for (const suggestion of answer.suggestions) {
+                suggestions.push({
+                    id: generateId('bootstrap_suggestions'),
+                    target: suggestion.target,
+                    text: suggestion.text.trim(),
+                    rationale: suggestion.rationale ?? renderBootstrapInterviewRationale(question),
+                    confidence: suggestion.confidence ?? 'high',
+                    source_seed_ids: [],
+                    source_refs: [`bootstrap-interview:${question.id}`],
+                    layer: suggestion.layer,
+                    scope: suggestion.scope,
+                    tags: normalizeBootstrapSuggestionTags(['bootstrap-interview', ...suggestion.tags]),
+                    related_paths: suggestion.related_paths,
+                    category: suggestion.category,
+                    outcome: suggestion.outcome,
+                    severity: suggestion.severity,
+                    reversible: true,
+                });
+            }
+            continue;
+        }
+        suggestions.push(...deriveBootstrapSuggestionsFromAnswer(question, answer));
+    }
+    return suggestions.filter((suggestion) => suggestion.text.trim().length > 0);
+}
+function deriveBootstrapSuggestionsFromAnswer(question, answer) {
+    const itemTexts = answer.response_items.map((entry) => entry.trim()).filter(Boolean);
+    const text = answer.response_text?.trim();
+    const base = {
+        id: generateId('bootstrap_suggestions'),
+        rationale: renderBootstrapInterviewRationale(question),
+        confidence: 'high',
+        source_seed_ids: [],
+        source_refs: [`bootstrap-interview:${question.id}`],
+        tags: normalizeBootstrapSuggestionTags(['bootstrap-interview']),
+        related_paths: undefined,
+        reversible: true,
+    };
+    if (question.gap_keys.includes('project intent is not documented yet') && text) {
+        return [{ ...base, target: 'decision', text: `Project intent: ${text}` }];
+    }
+    if (question.gap_keys.includes('no README-level project overview detected') && text) {
+        return [{ ...base, target: 'decision', text: `Project overview: ${text}` }];
+    }
+    if (question.prompt.startsWith('Which coding agents do you expect to use here') && (itemTexts.length > 0 || text)) {
+        const values = itemTexts.length > 0 ? itemTexts : [text];
+        return values.map((entry) => ({
+            ...base,
+            id: generateId('bootstrap_suggestions'),
+            target: 'constraint',
+            text: `Agent workflow expectation: ${entry}`,
+            category: 'process',
+        }));
+    }
+    if (question.prompt.startsWith('For a CLI-only agent') && text) {
+        return [{ ...base, target: 'instruction', text: `CLI-only agents should first: ${text}`, layer: 'global' }];
+    }
+    if (question.prompt.startsWith('For an IDE chat agent') && text) {
+        return [{ ...base, target: 'instruction', text: `IDE chat agents should ask or inspect: ${text}`, layer: 'global' }];
+    }
+    if (question.gap_keys.includes('no native agent instruction files detected') && answer.response_boolean !== undefined) {
+        return [{
+                ...base,
+                target: 'decision',
+                text: answer.response_boolean
+                    ? 'Brainclaw should treat this project as agent-guided.'
+                    : 'Brainclaw should stay memory-only until agent guidance is clarified.',
+            }];
+    }
+    if (question.gap_keys.includes('derived context is sparse and may need an interview') && (itemTexts.length > 0 || text)) {
+        const values = itemTexts.length > 0 ? itemTexts : [text];
+        return values.map((entry) => ({
+            ...base,
+            id: generateId('bootstrap_suggestions'),
+            target: 'constraint',
+            text: entry,
+            category: 'process',
+        }));
+    }
+    if (question.gap_keys.includes('native instruction import boundary') && text) {
+        return [{ ...base, target: 'decision', text: `Native instruction import boundary: ${text}` }];
+    }
+    if (question.gap_keys.includes('confidence fallback') && text) {
+        return [{
+                ...base,
+                target: question.target_hints.includes('constraint') ? 'constraint' : 'instruction',
+                text,
+                category: question.target_hints.includes('constraint') ? 'process' : undefined,
+                layer: question.target_hints.includes('instruction') ? 'global' : undefined,
+            }];
+    }
+    if (itemTexts.length > 0 && question.target_hints.includes('constraint')) {
+        return itemTexts.map((entry) => ({
+            ...base,
+            id: generateId('bootstrap_suggestions'),
+            target: 'constraint',
+            text: entry,
+            category: 'process',
+        }));
+    }
+    if (text && question.target_hints.includes('instruction')) {
+        return [{ ...base, target: 'instruction', text, layer: 'global' }];
+    }
+    if (text && question.target_hints.includes('decision')) {
+        return [{ ...base, target: 'decision', text }];
+    }
+    return [];
+}
+function renderBootstrapInterviewRationale(question) {
+    return `Confirmed via bootstrap interview answer to ${question.id}: ${question.prompt}`;
+}
 function seedToBootstrapSuggestion(seed, allowSummaryFallback) {
     if (seed.seed_kind !== 'agent_rule' && seed.seed_kind !== 'command') {
         return undefined;
@@ -968,8 +1170,14 @@ function normalizeBootstrapSuggestionTags(tags) {
 function isBootstrapSummarySeed(text) {
     return text.startsWith('Agent guide: ') || text.startsWith('Native agent guidance from ');
 }
-function suggestionIdentityKey(suggestion) {
-    return instructionIdentityKey(suggestion.text, suggestion.layer ?? 'global', suggestion.scope);
+function genericSuggestionIdentityKey(suggestion) {
+    if (suggestion.target === 'instruction') {
+        return instructionIdentityKey(suggestion.text, suggestion.layer ?? 'global', suggestion.scope);
+    }
+    if (suggestion.target === 'trap') {
+        return `trap:${suggestion.severity ?? 'medium'}:${suggestion.text.trim().toLowerCase()}`;
+    }
+    return `${suggestion.target}:${suggestion.text.trim().toLowerCase()}`;
 }
 function instructionIdentityKey(text, layer, scope) {
     return `${layer}:${scope ?? '*'}:${text.trim().toLowerCase()}`;
@@ -986,40 +1194,149 @@ export function applyBootstrapImport(options = {}) {
             skippedCount: 0,
         };
     }
-    const activeInstructionKeys = new Set(loadInstructions(cwd)
-        .filter((entry) => entry.active)
-        .map((entry) => instructionIdentityKey(entry.text, entry.layer, entry.scope)));
     const managedArtifacts = [];
     let createdCount = 0;
     let skippedCount = 0;
     withStoreLock(cwd, () => {
+        const state = loadState(cwd);
+        const activeInstructionKeys = new Set(loadInstructions(cwd)
+            .filter((entry) => entry.active)
+            .map((entry) => instructionIdentityKey(entry.text, entry.layer, entry.scope)));
+        const activeDecisionKeys = new Set(state.recent_decisions.map((entry) => genericSuggestionIdentityKey({
+            target: 'decision',
+            text: entry.text,
+            layer: 'global',
+            scope: undefined,
+            severity: undefined,
+        })));
+        const activeConstraintKeys = new Set(state.active_constraints
+            .filter((entry) => entry.status === 'active')
+            .map((entry) => genericSuggestionIdentityKey({
+            target: 'constraint',
+            text: entry.text,
+            layer: 'global',
+            scope: undefined,
+            severity: undefined,
+        })));
+        const activeTrapKeys = new Set(state.known_traps
+            .filter((entry) => entry.status === 'active')
+            .map((entry) => genericSuggestionIdentityKey({
+            target: 'trap',
+            text: entry.text,
+            layer: 'global',
+            scope: undefined,
+            severity: entry.severity,
+        })));
+        let stateChanged = false;
         for (const suggestion of proposal.suggestions) {
-            if (suggestion.target !== 'instruction') {
+            const identityKey = genericSuggestionIdentityKey(suggestion);
+            if ((suggestion.target === 'instruction' && activeInstructionKeys.has(identityKey)) ||
+                (suggestion.target === 'decision' && activeDecisionKeys.has(identityKey)) ||
+                (suggestion.target === 'constraint' && activeConstraintKeys.has(identityKey)) ||
+                (suggestion.target === 'trap' && activeTrapKeys.has(identityKey))) {
                 skippedCount++;
                 continue;
             }
-            const identityKey = suggestionIdentityKey(suggestion);
-            if (activeInstructionKeys.has(identityKey)) {
-                skippedCount++;
-                continue;
+            switch (suggestion.target) {
+                case 'instruction': {
+                    const entry = createInstruction(suggestion.text, {
+                        layer: suggestion.layer ?? 'global',
+                        scope: suggestion.scope,
+                        tags: suggestion.tags,
+                        author: resolveCurrentAgentName(cwd),
+                    }, cwd);
+                    activeInstructionKeys.add(identityKey);
+                    managedArtifacts.push({
+                        kind: 'instruction',
+                        id: entry.id,
+                        suggestion_id: suggestion.id,
+                        rollback_action: 'deactivate',
+                    });
+                    createdCount++;
+                    break;
+                }
+                case 'decision': {
+                    const { id, short_label } = generateIdWithLabel('recent_decisions', cwd);
+                    const entry = {
+                        id,
+                        short_label,
+                        text: suggestion.text,
+                        created_at: nowISO(),
+                        author: resolveCurrentAgentName(cwd),
+                        outcome: suggestion.outcome,
+                        tags: suggestion.tags ?? [],
+                        related_paths: suggestion.related_paths,
+                    };
+                    state.recent_decisions.push(entry);
+                    activeDecisionKeys.add(identityKey);
+                    managedArtifacts.push({
+                        kind: 'decision',
+                        id: entry.id,
+                        suggestion_id: suggestion.id,
+                        rollback_action: 'delete',
+                    });
+                    stateChanged = true;
+                    createdCount++;
+                    break;
+                }
+                case 'constraint': {
+                    const { id, short_label } = generateIdWithLabel('active_constraints', cwd);
+                    const entry = {
+                        id,
+                        short_label,
+                        text: suggestion.text,
+                        created_at: nowISO(),
+                        author: resolveCurrentAgentName(cwd),
+                        status: 'active',
+                        category: suggestion.category,
+                        tags: suggestion.tags ?? [],
+                        related_paths: suggestion.related_paths,
+                    };
+                    state.active_constraints.push(entry);
+                    activeConstraintKeys.add(identityKey);
+                    managedArtifacts.push({
+                        kind: 'constraint',
+                        id: entry.id,
+                        suggestion_id: suggestion.id,
+                        rollback_action: 'delete',
+                    });
+                    stateChanged = true;
+                    createdCount++;
+                    break;
+                }
+                case 'trap': {
+                    const { id, short_label } = generateIdWithLabel('known_traps', cwd);
+                    const entry = {
+                        id,
+                        short_label,
+                        text: suggestion.text,
+                        created_at: nowISO(),
+                        author: resolveCurrentAgentName(cwd),
+                        status: 'active',
+                        severity: suggestion.severity ?? 'medium',
+                        tags: suggestion.tags ?? [],
+                        related_paths: suggestion.related_paths,
+                        visibility: 'shared',
+                    };
+                    state.known_traps.push(entry);
+                    activeTrapKeys.add(identityKey);
+                    managedArtifacts.push({
+                        kind: 'trap',
+                        id: entry.id,
+                        suggestion_id: suggestion.id,
+                        rollback_action: 'delete',
+                    });
+                    stateChanged = true;
+                    createdCount++;
+                    break;
+                }
             }
-            const entry = createInstruction(suggestion.text, {
-                layer: suggestion.layer ?? 'global',
-                scope: suggestion.scope,
-                tags: suggestion.tags,
-                author: resolveCurrentAgentName(cwd),
-            }, cwd);
-            activeInstructionKeys.add(identityKey);
-            managedArtifacts.push({
-                kind: 'instruction',
-                id: entry.id,
-                suggestion_id: suggestion.id,
-                rollback_action: 'deactivate',
-            });
-            createdCount++;
+        }
+        if (stateChanged) {
+            persistState(state, cwd, { writeProjectMarkdown: false });
         }
         if (createdCount > 0) {
-            writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(loadState(cwd)));
+            writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(loadState(cwd), cwd));
         }
     });
     const receipt = BootstrapApplicationReceiptSchema.parse({
@@ -1046,30 +1363,59 @@ export function uninstallBootstrapImport(cwd) {
         return {
             receipt,
             deactivatedCount: 0,
+            deletedCount: 0,
             skippedCount: 0,
         };
     }
-    const instructions = loadInstructions(resolvedCwd);
     let deactivatedCount = 0;
+    let deletedCount = 0;
     let skippedCount = 0;
     withStoreLock(resolvedCwd, () => {
+        const state = loadState(resolvedCwd);
+        const instructions = loadInstructions(resolvedCwd);
+        let stateChanged = false;
         for (const artifact of receipt.managed_artifacts) {
-            if (artifact.kind !== 'instruction') {
-                skippedCount++;
+            if (artifact.kind === 'instruction') {
+                const instruction = instructions.find((entry) => entry.id === artifact.id);
+                if (!instruction || !instruction.active) {
+                    skippedCount++;
+                    continue;
+                }
+                instruction.active = false;
+                instruction.updated_at = nowISO();
+                saveInstruction(instruction, resolvedCwd);
+                deactivatedCount++;
                 continue;
             }
-            const instruction = instructions.find((entry) => entry.id === artifact.id);
-            if (!instruction || !instruction.active) {
+            const beforeCounts = {
+                decisions: state.recent_decisions.length,
+                constraints: state.active_constraints.length,
+                traps: state.known_traps.length,
+            };
+            if (artifact.kind === 'decision') {
+                state.recent_decisions = state.recent_decisions.filter((entry) => entry.id !== artifact.id);
+            }
+            else if (artifact.kind === 'constraint') {
+                state.active_constraints = state.active_constraints.filter((entry) => entry.id !== artifact.id);
+            }
+            else if (artifact.kind === 'trap') {
+                state.known_traps = state.known_traps.filter((entry) => entry.id !== artifact.id);
+            }
+            const changed = beforeCounts.decisions !== state.recent_decisions.length
+                || beforeCounts.constraints !== state.active_constraints.length
+                || beforeCounts.traps !== state.known_traps.length;
+            if (!changed) {
                 skippedCount++;
                 continue;
             }
-            instruction.active = false;
-            instruction.updated_at = nowISO();
-            saveInstruction(instruction, resolvedCwd);
-            deactivatedCount++;
+            stateChanged = true;
+            deletedCount++;
+        }
+        if (stateChanged) {
+            persistState(state, resolvedCwd, { writeProjectMarkdown: false });
         }
-        if (deactivatedCount > 0) {
-            writeFileAtomic(memoryPath('project.md', resolvedCwd), generateMarkdown(loadState(resolvedCwd)));
+        if (deactivatedCount > 0 || deletedCount > 0) {
+            writeFileAtomic(memoryPath('project.md', resolvedCwd), generateMarkdown(loadState(resolvedCwd), resolvedCwd));
         }
     });
     const nextReceipt = BootstrapApplicationReceiptSchema.parse({
@@ -1080,6 +1426,7 @@ export function uninstallBootstrapImport(cwd) {
     return {
         receipt: nextReceipt,
         deactivatedCount,
+        deletedCount,
         skippedCount,
     };
 }
@@ -1125,6 +1472,15 @@ function inferBootstrapConfidence(input) {
     }
     return 'low';
 }
+function inferOnboardingMode(input) {
+    if (input.workspaceKind === 'empty') {
+        return 'empty_workspace';
+    }
+    if (input.readmePresent || input.nativeInstructionFiles.length > 0 || input.confidence === 'high') {
+        return 'existing_documented';
+    }
+    return 'existing_sparse';
+}
 function inferBootstrapGaps(input) {
     const gaps = [];
     if (input.workspaceKind === 'empty') {

package/dist/core/schema.js

@@ -485,6 +485,7 @@ export const BootstrapProfileDocumentSchema = z.object({
     seed_count: z.number().int().nonnegative(),
     target: z.string().optional(),
     workspace_kind: z.enum(['empty', 'existing']).optional(),
+    onboarding_mode: z.enum(['empty_workspace', 'existing_documented', 'existing_sparse']).optional(),
     confidence: MemorySeedConfidenceSchema.optional(),
     native_instruction_files: z.array(z.string()).default([]),
     gaps: z.array(z.string()).default([]),
@@ -503,6 +504,9 @@ export const BootstrapSuggestionDocumentSchema = z.object({
     scope: z.string().optional(),
     tags: z.array(z.string()).default([]),
     related_paths: z.array(z.string()).optional(),
+    category: ConstraintCategorySchema.optional(),
+    outcome: DecisionOutcomeSchema.optional(),
+    severity: SeveritySchema.optional(),
     reversible: z.boolean().default(true),
 });
 export const BootstrapInterviewAudienceSchema = z.enum(['cli', 'ide_chat', 'any']);
@@ -514,6 +518,7 @@ export const BootstrapInterviewQuestionSchema = z.object({
     audience: BootstrapInterviewAudienceSchema.default('any'),
     response_kind: z.enum(['short_text', 'long_text', 'boolean', 'list']).default('short_text'),
     gap_keys: z.array(z.string()).default([]),
+    target_hints: z.array(BootstrapSuggestionTargetSchema).default([]),
 });
 export const BootstrapInterviewPlanSchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -524,15 +529,38 @@ export const BootstrapInterviewPlanSchema = z.object({
     question_count: z.number().int().nonnegative(),
     questions: z.array(BootstrapInterviewQuestionSchema).default([]),
 });
+export const BootstrapInterviewAnswerSuggestionSchema = z.object({
+    target: BootstrapSuggestionTargetSchema,
+    text: z.string(),
+    rationale: z.string().optional(),
+    confidence: MemorySeedConfidenceSchema.optional(),
+    layer: z.enum(['global', 'project', 'agent']).optional(),
+    scope: z.string().optional(),
+    tags: z.array(z.string()).default([]),
+    related_paths: z.array(z.string()).optional(),
+    category: ConstraintCategorySchema.optional(),
+    outcome: DecisionOutcomeSchema.optional(),
+    severity: SeveritySchema.optional(),
+});
+export const BootstrapInterviewAnswerSchema = z.object({
+    question_id: z.string(),
+    response_text: z.string().optional(),
+    response_items: z.array(z.string()).default([]),
+    response_boolean: z.boolean().optional(),
+    suggestions: z.array(BootstrapInterviewAnswerSuggestionSchema).default([]),
+});
 export const BootstrapImportPlanDocumentSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     derived_at: z.string(),
     target: z.string().optional(),
     workspace_kind: z.enum(['empty', 'existing']).optional(),
+    onboarding_mode: z.enum(['empty_workspace', 'existing_documented', 'existing_sparse']).optional(),
     confidence: MemorySeedConfidenceSchema.optional(),
     summary: z.string(),
     requires_confirmation: z.boolean().default(true),
     gaps: z.array(z.string()).default([]),
+    confirmed_suggestion_count: z.number().int().nonnegative().default(0),
+    interview_answer_count: z.number().int().nonnegative().default(0),
     suggestion_count: z.number().int().nonnegative(),
     suggestions: z.array(BootstrapSuggestionDocumentSchema).default([]),
     interview: BootstrapInterviewPlanSchema.optional(),

package/docs/cli.md

@@ -115,6 +115,7 @@ For capable agents, the MCP equivalent is `bclaw_bootstrap`. Use the CLI when a
 | `--refresh` | Force refresh even if bootstrap data is recent |
 | `--interview` | Render adaptive interview prompts instead of the bootstrap summary |
 | `--audience <audience>` | Filter interview prompts for `cli`, `ide_chat`, or `any` |
+| `--answers-file <path>` | Load structured interview answers from JSON and enrich the import proposal before preview/apply |
 | `--apply` | Import the current bootstrap proposal into canonical memory |
 | `--uninstall` | Deactivate the last bootstrap-managed import |
 | `-y, --yes` | Skip confirmation prompts for apply/uninstall |
@@ -123,9 +124,13 @@ For capable agents, the MCP equivalent is `bclaw_bootstrap`. Use the CLI when a
 brainclaw bootstrap --for copilot
 brainclaw bootstrap --for claude --refresh --json
 brainclaw bootstrap --interview --audience cli
+brainclaw bootstrap --answers-file ./bootstrap-answers.json --json
+brainclaw bootstrap --answers-file ./bootstrap-answers.json --apply -y
 brainclaw bootstrap --apply -y
 ```
 
+`--answers-file` expects a JSON array keyed by interview question IDs. Each entry can provide free-form answers (`response_text`, `response_items`, `response_boolean`) and optional explicit `suggestions` to confirm durable imports such as `decision`, `constraint`, `instruction`, or `trap`.
+
 ### `brainclaw env`
 
 Display environment and tooling detection information.

package/docs/integrations/mcp.md

@@ -34,7 +34,7 @@ This keeps session continuity inside Brainclaw instead of pushing the agent back
 | Tool | Purpose |
 |---|---|
 | `bclaw_get_context` | Ranked prompt-ready context, supports `digest: true` |
-| `bclaw_bootstrap` | Derive brownfield bootstrap signals, adaptive interview prompts, and an import proposal when memory is still sparse |
+| `bclaw_bootstrap` | Derive brownfield bootstrap signals, return adaptive interview prompts, accept structured interview answers, and preview/apply a selective import proposal |
 | `bclaw_get_execution_context` | Inspect local execution context and agent tooling |
 | `bclaw_write_note` | Record a runtime note, supports `autoReflect: true` |
 | `bclaw_read_handoff` | Read active handoffs |
@@ -65,6 +65,23 @@ brainclaw mcp
 
 In practice, most agents pick this up through generated MCP config such as `.mcp.json`, `~/.cursor/mcp.json`, or other agent-specific config files written by `brainclaw setup`, `brainclaw init`, or `brainclaw export`.
 
+## Bootstrap Through MCP
+
+For agent-first onboarding, `bclaw_bootstrap` is the nominal path:
+
+1. call `bclaw_bootstrap` to get the current `import_plan` and adaptive interview questions
+2. collect answers in the agent surface
+3. call `bclaw_bootstrap` again with `interviewAnswers` to preview confirmed `decision`, `constraint`, `instruction`, or `trap` suggestions
+4. call `bclaw_bootstrap` with `apply: true` to create canonical memory
+5. call `bclaw_bootstrap` with `uninstall: true` to revert the last bootstrap-managed import
+
+Interview answers are keyed by question ID and may contain:
+
+- `response_text`
+- `response_items`
+- `response_boolean`
+- optional explicit `suggestions` when the agent wants to confirm exact canonical memory items
+
 ## Important Rule
 
 If the agent has MCP available, do not treat the CLI as the primary runtime interface.

package/docs/mcp-schema-changelog.md

@@ -27,6 +27,12 @@ This document tracks all breaking and notable changes to the brainclaw MCP serve
 - `bclaw_bootstrap` now returns adaptive interview prompts alongside the import proposal when bootstrap confidence is incomplete
   - `structuredContent.import_plan.interview` exposes `summary`, `question_count`, and audience-tagged questions
   - Questions can be targeted to `cli`, `ide_chat`, or `any`
+  - Interview questions now expose stable IDs and `target_hints`
+  - `structuredContent.onboarding_mode` distinguishes `empty_workspace`, `existing_documented`, and `existing_sparse`
+  - `structuredContent.import_plan.confirmed_suggestion_count` reports how many suggestions were confirmed by interview answers
+- `bclaw_bootstrap` now accepts `interviewAnswers`, `apply`, `uninstall`, `audience`, and `interview`
+  - capable agents can preview confirmed selective imports through MCP before applying them
+  - bootstrap apply/uninstall now covers selective canonical memory imports beyond instructions
 
 **Changed**
 - MCP schema version bumped to 0.6.0 to reflect new metadata discovery capabilities

package/docs/quickstart.md

@@ -103,10 +103,28 @@ brainclaw bootstrap --interview --audience cli
 brainclaw bootstrap --interview --audience ide_chat
 ```
 
+Use the returned question IDs to prepare a small JSON answers file when the interview needs to confirm durable memory:
+
+```json
+[
+  {
+    "question_id": "biq_example",
+    "response_items": ["Use agents sequentially in one checkout."],
+    "suggestions": []
+  }
+]
+```
+
+Preview the enriched import proposal:
+
+```bash
+brainclaw bootstrap --answers-file ./bootstrap-answers.json --json
+```
+
 ### Apply or rollback managed imports
 
 ```bash
-brainclaw bootstrap --apply
+brainclaw bootstrap --answers-file ./bootstrap-answers.json --apply
 brainclaw bootstrap --uninstall
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.19.10",
+  "version": "0.19.11",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {