brainclaw 0.19.10 → 0.19.12

package/dist/core/brainclaw-version.js

@@ -1,11 +1,20 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { BrainclawLocalReleaseManifestSchema, } from './schema.js';
 export const DEFAULT_LOCAL_RELEASES_DIR = '.releases';
 export const DEFAULT_LOCAL_RELEASE_MANIFEST_PATH = `${DEFAULT_LOCAL_RELEASES_DIR}/brainclaw-local.json`;
+export const DEFAULT_NPM_UPDATE_PACKAGE = 'brainclaw';
+export const DEFAULT_NPM_UPDATE_DIST_TAG = 'latest';
+export const DEFAULT_INSTALLABLE_UPDATE_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 const SEMVER_RE = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const DEFAULT_NPM_UPDATE_SOURCE = {
+    type: 'npm',
+    package_name: DEFAULT_NPM_UPDATE_PACKAGE,
+    dist_tag: DEFAULT_NPM_UPDATE_DIST_TAG,
+};
 let cachedCliVersion;
 export function getInstalledBrainclawVersion() {
     if (cachedCliVersion) {
@@ -87,8 +96,10 @@ export function assessBrainclawVersion(config) {
         message,
     };
 }
-export function checkBrainclawInstallableUpdate(config, cwd) {
-    const source = config?.brainclaw_update_source;
+export function checkBrainclawInstallableUpdate(config, cwd, options = {}) {
+    const source = config?.brainclaw_update_source
+        ?? (options.useDefaultNpmSource ? DEFAULT_NPM_UPDATE_SOURCE : undefined);
+    const defaultSource = !config?.brainclaw_update_source && source?.type === 'npm';
     if (!source) {
         return {
             checked: false,
@@ -103,22 +114,181 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
         };
     }
     if (source.type === 'npm') {
-        const packageName = source.package_name?.trim() || 'brainclaw';
-        const distTag = source.dist_tag?.trim() || 'latest';
+        return checkNpmInstallableUpdate(source, config, cwd, options, defaultSource);
+    }
+    return checkLocalPackInstallableUpdate(source.manifest_path, config, cwd);
+}
+export function renderBrainclawInstallableUpdateNotice(updateCheck) {
+    if (!updateCheck || updateCheck.status !== 'update_available') {
+        return null;
+    }
+    const lines = [updateCheck.message];
+    if (updateCheck.install_command) {
+        lines.push(`Install: ${updateCheck.install_command}`);
+    }
+    if (updateCheck.release_notes) {
+        lines.push(`Why update: ${updateCheck.release_notes}`);
+    }
+    return lines.join('\n');
+}
+export function publishLocalBrainclawRelease(cwd, options = {}) {
+    const workspacePackage = readWorkspaceBrainclawPackage(cwd);
+    const outputDir = path.resolve(cwd, options.outputDir ?? DEFAULT_LOCAL_RELEASES_DIR);
+    const manifestPath = path.resolve(cwd, options.manifestPath ?? DEFAULT_LOCAL_RELEASE_MANIFEST_PATH);
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    const packResult = spawnSync(resolveNpmCommand(), resolveNpmPackArgs(outputDir), {
+        cwd,
+        encoding: 'utf-8',
+        timeout: 120000,
+    });
+    if (packResult.error) {
+        throw new Error(`Failed to run npm pack: ${packResult.error.message}`);
+    }
+    if (packResult.status !== 0) {
+        throw new Error(firstNonEmptyLine(packResult.stderr) ?? firstNonEmptyLine(packResult.stdout) ?? 'npm pack failed');
+    }
+    const artifactFilename = parsePackedFilename(packResult.stdout);
+    if (!artifactFilename) {
+        throw new Error('npm pack did not report the generated tarball filename.');
+    }
+    const artifactAbsolutePath = path.join(outputDir, artifactFilename);
+    if (!fs.existsSync(artifactAbsolutePath)) {
+        throw new Error(`npm pack reported ${artifactFilename}, but the tarball was not found in ${outputDir}.`);
+    }
+    const manifestArtifactPath = toManifestRelativePath(path.relative(path.dirname(manifestPath), artifactAbsolutePath));
+    const projectArtifactPath = toManifestRelativePath(path.relative(cwd, artifactAbsolutePath));
+    const projectManifestPath = toPortablePath(path.relative(cwd, manifestPath));
+    const installCommand = `npm install -g "${projectArtifactPath}"`;
+    const releaseNotes = options.releaseNotes?.trim() || null;
+    const manifest = BrainclawLocalReleaseManifestSchema.parse({
+        version: 1,
+        channel: 'local-pack',
+        package_name: workspacePackage.name,
+        latest_installable_version: workspacePackage.version,
+        published_at: new Date().toISOString(),
+        artifact_path: manifestArtifactPath,
+        install_command: installCommand,
+        release_notes: releaseNotes ?? undefined,
+    });
+    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+    return {
+        package_name: workspacePackage.name,
+        workspace_version: workspacePackage.version,
+        manifest_path: projectManifestPath,
+        artifact_path: projectArtifactPath,
+        install_command: installCommand,
+        release_notes: releaseNotes,
+    };
+}
+function checkNpmInstallableUpdate(source, config, cwd, options, defaultSource) {
+    const packageName = source.package_name?.trim() || DEFAULT_NPM_UPDATE_PACKAGE;
+    const distTag = source.dist_tag?.trim() || DEFAULT_NPM_UPDATE_DIST_TAG;
+    if (packageName.length === 0) {
         return {
             checked: false,
             source_type: 'npm',
-            source_description: `${packageName}@${distTag}`,
+            source_description: null,
             latest_installable_version: null,
             artifact_path: null,
             install_command: null,
             release_notes: null,
-            status: 'unsupported_source',
-            message: 'The npm update source is modeled in config but is not implemented yet in this build.',
+            status: 'invalid_config',
+            message: 'brainclaw_update_source.package_name must not be empty.',
+            default_source: defaultSource,
         };
     }
-    const manifestPath = source.manifest_path.trim();
-    if (manifestPath.length === 0) {
+    if (distTag.length === 0) {
+        return {
+            checked: false,
+            source_type: 'npm',
+            source_description: packageName,
+            latest_installable_version: null,
+            artifact_path: null,
+            install_command: null,
+            release_notes: null,
+            status: 'invalid_config',
+            message: 'brainclaw_update_source.dist_tag must not be empty.',
+            default_source: defaultSource,
+        };
+    }
+    try {
+        const lookup = (options.npmLookup ?? lookupNpmDistTags)(packageName, {
+            cwd,
+            now: options.now,
+            cacheTtlMs: options.cacheTtlMs,
+        });
+        const latestVersion = normalizeConfiguredVersion(lookup.dist_tags[distTag]);
+        if (!latestVersion) {
+            return {
+                checked: true,
+                source_type: 'npm',
+                source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+                latest_installable_version: null,
+                artifact_path: null,
+                install_command: null,
+                release_notes: config?.brainclaw_upgrade_message?.trim() || null,
+                status: 'check_failed',
+                message: `The npm channel ${packageName}@${distTag} did not resolve to a valid semver release.`,
+                checked_at: lookup.checked_at,
+                cached: lookup.cached,
+                default_source: defaultSource,
+            };
+        }
+        const installCommand = config?.brainclaw_upgrade_command?.trim()
+            || `npm install -g ${packageName}@${latestVersion}`;
+        const releaseNotes = config?.brainclaw_upgrade_message?.trim() || null;
+        const installedVersion = getInstalledBrainclawVersion();
+        if (compareVersions(installedVersion, latestVersion) < 0) {
+            return {
+                checked: true,
+                source_type: 'npm',
+                source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+                latest_installable_version: latestVersion,
+                artifact_path: null,
+                install_command: installCommand,
+                release_notes: releaseNotes,
+                status: 'update_available',
+                message: `A newer installable brainclaw build is available from npm: ${latestVersion} (installed ${installedVersion}).`,
+                checked_at: lookup.checked_at,
+                cached: lookup.cached,
+                default_source: defaultSource,
+            };
+        }
+        return {
+            checked: true,
+            source_type: 'npm',
+            source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+            latest_installable_version: latestVersion,
+            artifact_path: null,
+            install_command: installCommand,
+            release_notes: releaseNotes,
+            status: 'up_to_date',
+            message: `Installed brainclaw ${installedVersion} is up to date for npm channel ${packageName}@${distTag}.`,
+            checked_at: lookup.checked_at,
+            cached: lookup.cached,
+            default_source: defaultSource,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            checked: true,
+            source_type: 'npm',
+            source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+            latest_installable_version: null,
+            artifact_path: null,
+            install_command: null,
+            release_notes: config?.brainclaw_upgrade_message?.trim() || null,
+            status: 'check_failed',
+            message: `Failed to check npm installable updates: ${message}`,
+            default_source: defaultSource,
+        };
+    }
+}
+function checkLocalPackInstallableUpdate(manifestPath, config, cwd) {
+    const trimmedManifestPath = manifestPath.trim();
+    if (trimmedManifestPath.length === 0) {
         return {
             checked: false,
             source_type: 'local-pack',
@@ -129,11 +299,12 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'invalid_config',
             message: 'brainclaw_update_source.manifest_path must not be empty.',
+            default_source: false,
         };
     }
-    const resolvedManifestPath = path.isAbsolute(manifestPath)
-        ? manifestPath
-        : path.resolve(cwd, manifestPath);
+    const resolvedManifestPath = path.isAbsolute(trimmedManifestPath)
+        ? trimmedManifestPath
+        : path.resolve(cwd, trimmedManifestPath);
     if (!fs.existsSync(resolvedManifestPath)) {
         return {
             checked: true,
@@ -145,6 +316,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'check_failed',
             message: `The configured local-pack manifest was not found: ${resolvedManifestPath}`,
+            default_source: false,
         };
     }
     try {
@@ -162,6 +334,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
                 release_notes: manifest.release_notes?.trim() || config?.brainclaw_upgrade_message?.trim() || null,
                 status: 'check_failed',
                 message: `The local-pack manifest has an invalid latest_installable_version: ${manifest.latest_installable_version}`,
+                default_source: false,
             };
         }
         const artifactPath = manifest.artifact_path
@@ -182,6 +355,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
                 release_notes: releaseNotes,
                 status: 'update_available',
                 message: `A newer installable brainclaw build is available: ${latestVersion} (installed ${installedVersion}).`,
+                default_source: false,
             };
         }
         return {
@@ -194,6 +368,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: releaseNotes,
             status: 'up_to_date',
             message: `Installed brainclaw ${installedVersion} is up to date for the configured local-pack channel.`,
+            default_source: false,
         };
     }
     catch (error) {
@@ -208,59 +383,10 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'check_failed',
             message: `Failed to read the configured local-pack manifest: ${message}`,
+            default_source: false,
         };
     }
 }
-export function publishLocalBrainclawRelease(cwd, options = {}) {
-    const workspacePackage = readWorkspaceBrainclawPackage(cwd);
-    const outputDir = path.resolve(cwd, options.outputDir ?? DEFAULT_LOCAL_RELEASES_DIR);
-    const manifestPath = path.resolve(cwd, options.manifestPath ?? DEFAULT_LOCAL_RELEASE_MANIFEST_PATH);
-    fs.mkdirSync(outputDir, { recursive: true });
-    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-    const packResult = spawnSync(resolveNpmCommand(), resolveNpmPackArgs(outputDir), {
-        cwd,
-        encoding: 'utf-8',
-        timeout: 120000,
-    });
-    if (packResult.error) {
-        throw new Error(`Failed to run npm pack: ${packResult.error.message}`);
-    }
-    if (packResult.status !== 0) {
-        throw new Error(firstNonEmptyLine(packResult.stderr) ?? firstNonEmptyLine(packResult.stdout) ?? 'npm pack failed');
-    }
-    const artifactFilename = parsePackedFilename(packResult.stdout);
-    if (!artifactFilename) {
-        throw new Error('npm pack did not report the generated tarball filename.');
-    }
-    const artifactAbsolutePath = path.join(outputDir, artifactFilename);
-    if (!fs.existsSync(artifactAbsolutePath)) {
-        throw new Error(`npm pack reported ${artifactFilename}, but the tarball was not found in ${outputDir}.`);
-    }
-    const manifestArtifactPath = toManifestRelativePath(path.relative(path.dirname(manifestPath), artifactAbsolutePath));
-    const projectArtifactPath = toManifestRelativePath(path.relative(cwd, artifactAbsolutePath));
-    const projectManifestPath = toPortablePath(path.relative(cwd, manifestPath));
-    const installCommand = `npm install -g "${projectArtifactPath}"`;
-    const releaseNotes = options.releaseNotes?.trim() || null;
-    const manifest = BrainclawLocalReleaseManifestSchema.parse({
-        version: 1,
-        channel: 'local-pack',
-        package_name: workspacePackage.name,
-        latest_installable_version: workspacePackage.version,
-        published_at: new Date().toISOString(),
-        artifact_path: manifestArtifactPath,
-        install_command: installCommand,
-        release_notes: releaseNotes ?? undefined,
-    });
-    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
-    return {
-        package_name: workspacePackage.name,
-        workspace_version: workspacePackage.version,
-        manifest_path: projectManifestPath,
-        artifact_path: projectArtifactPath,
-        install_command: installCommand,
-        release_notes: releaseNotes,
-    };
-}
 function resolveNpmCommand() {
     return process.platform === 'win32' ? (process.env.ComSpec?.trim() || 'cmd.exe') : 'npm';
 }
@@ -270,6 +396,12 @@ function resolveNpmPackArgs(outputDir) {
     }
     return ['pack', '--json', '--pack-destination', outputDir];
 }
+function resolveNpmViewArgs(packageName) {
+    if (process.platform === 'win32') {
+        return ['/d', '/s', '/c', 'npm', 'view', packageName, 'dist-tags', '--json'];
+    }
+    return ['view', packageName, 'dist-tags', '--json'];
+}
 function findOwnPackageJson() {
     let currentDir = path.dirname(fileURLToPath(import.meta.url));
     while (true) {
@@ -331,6 +463,115 @@ function parsePackedFilename(stdout) {
         return firstNonEmptyLine(stdout);
     }
 }
+function lookupNpmDistTags(packageName, options) {
+    const now = options.now ?? new Date();
+    const cachePath = resolveNpmUpdateCachePath(packageName);
+    const ttlMs = options.cacheTtlMs ?? DEFAULT_INSTALLABLE_UPDATE_CACHE_TTL_MS;
+    const cached = readCachedNpmDistTags(cachePath, packageName, now, ttlMs);
+    if (cached) {
+        return cached;
+    }
+    const viewResult = spawnSync(resolveNpmCommand(), resolveNpmViewArgs(packageName), {
+        cwd: options.cwd,
+        encoding: 'utf-8',
+        timeout: 15000,
+    });
+    if (viewResult.error) {
+        throw new Error(`npm view failed: ${viewResult.error.message}`);
+    }
+    if (viewResult.status !== 0) {
+        throw new Error(firstNonEmptyLine(viewResult.stderr) ?? firstNonEmptyLine(viewResult.stdout) ?? 'npm view failed');
+    }
+    const distTags = parseNpmDistTags(viewResult.stdout);
+    const result = {
+        dist_tags: distTags,
+        checked_at: now.toISOString(),
+        cached: false,
+    };
+    writeCachedNpmDistTags(cachePath, {
+        version: 1,
+        package_name: packageName,
+        fetched_at: result.checked_at,
+        dist_tags: distTags,
+    });
+    return result;
+}
+function parseNpmDistTags(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`npm view returned invalid JSON: ${message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('npm view did not return a dist-tag object.');
+    }
+    const distTags = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value === 'string' && value.trim().length > 0) {
+            distTags[key] = value.trim();
+        }
+    }
+    if (Object.keys(distTags).length === 0) {
+        throw new Error('npm view returned an empty dist-tag object.');
+    }
+    return distTags;
+}
+function resolveNpmUpdateCachePath(packageName) {
+    const safeName = packageName.replace(/[^a-z0-9._-]+/gi, '_').replace(/^_+|_+$/g, '') || DEFAULT_NPM_UPDATE_PACKAGE;
+    return path.join(os.homedir(), '.brainclaw', 'cache', 'installable-updates', `${safeName}.json`);
+}
+function readCachedNpmDistTags(cachePath, packageName, now, ttlMs) {
+    if (!fs.existsSync(cachePath)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+        if (parsed.version !== 1
+            || parsed.package_name !== packageName
+            || typeof parsed.fetched_at !== 'string'
+            || !parsed.dist_tags
+            || typeof parsed.dist_tags !== 'object'
+            || Array.isArray(parsed.dist_tags)) {
+            return undefined;
+        }
+        const fetchedAt = Date.parse(parsed.fetched_at);
+        if (!Number.isFinite(fetchedAt) || now.getTime() - fetchedAt > ttlMs) {
+            return undefined;
+        }
+        const distTags = {};
+        for (const [key, value] of Object.entries(parsed.dist_tags)) {
+            if (typeof value === 'string' && value.trim().length > 0) {
+                distTags[key] = value.trim();
+            }
+        }
+        if (Object.keys(distTags).length === 0) {
+            return undefined;
+        }
+        return {
+            dist_tags: distTags,
+            checked_at: parsed.fetched_at,
+            cached: true,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCachedNpmDistTags(cachePath, document) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, `${JSON.stringify(document, null, 2)}\n`, 'utf-8');
+    }
+    catch {
+        // Cache writes are best-effort only.
+    }
+}
+function formatNpmSourceDescription(packageName, distTag, defaultSource) {
+    return defaultSource ? `${packageName}@${distTag} (default npm channel)` : `${packageName}@${distTag}`;
+}
 function firstNonEmptyLine(value) {
     return value
         .split(/\r?\n/)

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,12 +124,16 @@ 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.
+Display environment, tooling detection, and installable Brainclaw update information.
 
 | Option | Description |
 |---|---|
@@ -141,6 +146,8 @@ brainclaw env --json
 brainclaw env --agent-tooling
 ```
 
+When the project does not pin a local release channel, `brainclaw env` checks the public npm `latest` channel for installable updates. Projects can override that with `brainclaw_update_source`, for example to use `prelaunch` or a local-pack manifest.
+
 ---
 
 ## Memory Management
@@ -1248,3 +1255,10 @@ brainclaw version
 brainclaw version --check
 brainclaw version --publish-local --release-notes "Add estimation-report command"
 ```
+
+`brainclaw version --check` now follows this order:
+
+- if `brainclaw_update_source` is configured, use it
+- otherwise, fall back to the public npm channel `brainclaw@latest`
+
+This keeps end-user installs aware of published npm releases without requiring a local tarball channel. To keep beta testers on a different channel, set `brainclaw_update_source` to `type: npm` with a different `dist_tag`, such as `prelaunch`.

package/docs/integrations/mcp.md

@@ -16,16 +16,19 @@ MCP matters because Brainclaw's value is mostly in dynamic state:
 
 Static files still help, but they age immediately. MCP is the stronger path for live coordination.
 
+That now also includes Brainclaw's own install channel state: `bclaw_get_execution_context` surfaces whether a newer npm or local-pack build is available, so the agent can notice upgrades without relying on a human to run `brainclaw version --check`.
+
 ## Recommended Agent Pattern
 
 The default dynamic workflow is:
 
 1. `bclaw_session_start` to open work and get the current board/context
-2. `bclaw_get_context` when the target path or task changes
-3. `bclaw_list_plans` and `bclaw_list_claims` to inspect active work
-4. `bclaw_claim` before editing
-5. `bclaw_write_note` for runtime observations
-6. `bclaw_session_end` to close cleanly and hand work off
+2. `bclaw_get_execution_context` early in the session when the agent needs local tooling signals or package update visibility
+3. `bclaw_get_context` when the target path or task changes
+4. `bclaw_list_plans` and `bclaw_list_claims` to inspect active work
+5. `bclaw_claim` before editing
+6. `bclaw_write_note` for runtime observations
+7. `bclaw_session_end` to close cleanly and hand work off
 
 This keeps session continuity inside Brainclaw instead of pushing the agent back to manual CLI usage.
 
@@ -34,8 +37,8 @@ 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_get_execution_context` | Inspect local execution context and agent tooling |
+| `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, installable update status, and agent tooling |
 | `bclaw_write_note` | Record a runtime note, supports `autoReflect: true` |
 | `bclaw_read_handoff` | Read active handoffs |
 | `bclaw_get_agent_board` | Coordination snapshot |
@@ -65,6 +68,25 @@ 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`.
 
+By default, installable update checks use the public npm channel `brainclaw@latest`. Projects that need a different channel can override `brainclaw_update_source`, for example with `type: npm` and `dist_tag: prelaunch`, or with `type: local-pack` for local tarball workflows.
+
+## 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