brainclaw 0.19.7 → 0.19.11

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 { 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, } from './schema.js';
 export class MigrationError extends Error {
     kind;
     documentType;
@@ -16,6 +16,8 @@ export class MigrationError extends Error {
 const CURRENT_SCHEMA_VERSION = 2;
 const registry = {
     agent_identity: createRegistryEntry(AgentIdentityDocumentSchema),
+    bootstrap_application: createRegistryEntry(BootstrapApplicationReceiptSchema),
+    bootstrap_import_plan: createRegistryEntry(BootstrapImportPlanDocumentSchema),
     bootstrap_profile: createRegistryEntry(BootstrapProfileDocumentSchema),
     candidate: createRegistryEntry(CandidateSchema),
     claim: createRegistryEntry(ClaimSchema),
@@ -145,6 +147,8 @@ export function scanMigrationStatus(cwd) {
     collectSingle(entries, memoryPath('project.identity.json', cwd), 'project_identity');
     collectSingle(entries, memoryPath('.current-session', cwd), 'current_session');
     collectSingle(entries, memoryPath(path.join('bootstrap', 'profile.json'), cwd), 'bootstrap_profile');
+    collectSingle(entries, memoryPath(path.join('bootstrap', 'import-plan.json'), cwd), 'bootstrap_import_plan');
+    collectSingle(entries, memoryPath(path.join('bootstrap', 'last-application.json'), cwd), 'bootstrap_application');
     const effectiveCwd = cwd ?? process.cwd();
     collectDirectory(entries, resolveEntityDir('constraints', effectiveCwd, 'read'), 'constraint');
     collectDirectory(entries, resolveEntityDir('decisions', effectiveCwd, 'read'), 'decision');
@@ -161,7 +165,7 @@ export function scanMigrationStatus(cwd) {
     collectDirectory(entries, resolveEntityDir('runtime-hosts', effectiveCwd, 'read'), 'runtime_note', true);
     collectDirectory(entries, resolveEntityDir('runtime-private', effectiveCwd, 'read'), 'runtime_note', true);
     collectDirectory(entries, resolveEntityDir('instructions', effectiveCwd, 'read'), 'instruction');
-    collectDirectory(entries, resolveEntityDir('bootstrap', effectiveCwd, 'read'), 'memory_seed');
+    collectDirectory(entries, path.join(resolveEntityDir('bootstrap', effectiveCwd, 'read'), 'seeds'), 'memory_seed');
     collectDirectory(entries, resolveEntityDir('agents', effectiveCwd, 'read'), 'agent_identity');
     collectDirectory(entries, resolveEntityDir('sessions', effectiveCwd, 'read'), 'session_snapshot');
     return entries.sort((a, b) => a.path.localeCompare(b.path));

package/dist/core/schema.js

@@ -451,6 +451,7 @@ export const MemorySeedKindSchema = z.enum([
 export const MemorySeedSourceKindSchema = z.enum([
     'readme',
     'agents_md',
+    'native_instruction',
     'manifest',
     'repo_analysis',
     'git',
@@ -483,6 +484,102 @@ export const BootstrapProfileDocumentSchema = z.object({
     agents_md_present: z.boolean().default(false),
     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([]),
+});
+export const BootstrapSuggestionTargetSchema = z.enum(['instruction', 'decision', 'constraint', 'trap']);
+export const BootstrapSuggestionDocumentSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    target: BootstrapSuggestionTargetSchema,
+    text: z.string(),
+    rationale: z.string(),
+    confidence: MemorySeedConfidenceSchema,
+    source_seed_ids: z.array(z.string()).default([]),
+    source_refs: z.array(z.string()).default([]),
+    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(),
+    reversible: z.boolean().default(true),
+});
+export const BootstrapInterviewAudienceSchema = z.enum(['cli', 'ide_chat', 'any']);
+export const BootstrapInterviewQuestionSchema = z.object({
+    id: z.string(),
+    prompt: z.string(),
+    rationale: z.string(),
+    priority: z.enum(['high', 'medium', 'low']),
+    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(),
+    derived_at: z.string(),
+    workspace_kind: z.enum(['empty', 'existing']).optional(),
+    audience: BootstrapInterviewAudienceSchema.default('any'),
+    summary: z.string(),
+    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(),
+});
+export const BootstrapManagedArtifactSchema = z.object({
+    kind: z.enum(['instruction', 'decision', 'constraint', 'trap']),
+    id: z.string(),
+    suggestion_id: z.string(),
+    rollback_action: z.enum(['deactivate', 'delete']).default('delete'),
+});
+export const BootstrapApplicationReceiptSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    applied_at: z.string(),
+    proposal_derived_at: z.string(),
+    target: z.string().optional(),
+    workspace_kind: z.enum(['empty', 'existing']).optional(),
+    managed_artifacts: z.array(BootstrapManagedArtifactSchema).default([]),
+    suggestion_ids: z.array(z.string()).default([]),
+    uninstalled_at: z.string().optional(),
 });
 export const AgentIntegrationNameSchema = z.enum([
     'github-copilot',

package/docs/cli.md

@@ -1,6 +1,15 @@
 # CLI Reference
 
-Commands grouped by purpose. All commands are available as `brainclaw` or its alias `bclaw`.
+The CLI is Brainclaw's explicit operator, scripting, release, and fallback surface. All commands are available as `brainclaw` or its alias `bclaw`.
+
+For capable coding agents, prefer MCP for dynamic runtime state:
+
+- `bclaw_bootstrap` instead of manual bootstrap polling
+- `bclaw_get_context` instead of repeated raw CLI context calls
+- `bclaw_list_plans` / `bclaw_list_claims` / `bclaw_get_agent_board` for live coordination views
+- `bclaw_claim`, `bclaw_write_note`, and `bclaw_session_end` for session continuity
+
+Use the CLI when a human operator is driving the workflow, when you are scripting setup or release operations, or when MCP is not the integration path.
 
 ---
 
@@ -97,17 +106,31 @@ brainclaw rebuild
 
 Bootstrap shared memory for a new agent or project context.
 
+For capable agents, the MCP equivalent is `bclaw_bootstrap`. Use the CLI when a human is driving onboarding, reviewing the import proposal, or operating in fallback mode.
+
 | Option | Description |
 |---|---|
 | `--for <agent>` | Target agent name |
 | `--json` | Output as JSON |
 | `--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 |
 
 ```bash
 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.
@@ -574,6 +597,8 @@ brainclaw search "rollout" --since 2026-01-01 --json
 
 ## Planning and Coordination
 
+For capable agents, prefer the MCP plan and claim tools for live runtime interactions. The CLI remains the operator and scripting form of the same coordination model.
+
 ### `brainclaw plan create <text>`
 
 Create a shared work item.

package/docs/integrations/agents.md

@@ -10,30 +10,43 @@ That means brainclaw integration should not rely on only one mechanism such as:
 - a single skill
 - a single startup command
 
-## Better approach
-
-Use multiple points of contact:
-
-- lightweight system instructions
-- project-specific context retrieval
-- prompt-ready generated context
-- MCP tools when available
-- board and status views
-- workflow reminders around plans, claims, and handoffs
+## Better approach
+
+Use multiple points of contact:
+
+- lightweight system instructions
+- project-specific context retrieval through MCP when available
+- prompt-ready generated context
+- native agent files for local reminders
+- MCP tools for dynamic state
+- board and status views
+- workflow reminders around plans, claims, and handoffs
+
+## Surface hierarchy
+
+The default order is:
+
+1. MCP for live state
+2. native agent files for local workflow guidance
+3. readable files as fallback
+4. CLI for setup, operator tasks, scripting, and fallback workflows
+
+This keeps dynamic state dynamic instead of trying to encode it permanently into static instructions.
 
 ## System instructions vs project instructions
 
 Keep these separate.
 
-### System instructions
-How the agent should use brainclaw.
+### System instructions
+How the agent should use brainclaw.
 
 Examples:
 
-- check workspace memory before significant changes
-- bootstrap if the workspace is not initialized and the workflow allows it
-- respect file claims
-- update shared plan status when appropriate
+- check workspace memory before significant changes
+- prefer MCP over manual CLI calls when MCP is available
+- bootstrap if the workspace is not initialized and the workflow allows it
+- respect file claims
+- update shared plan status when appropriate
 
 ### Project instructions
 What is true for the current workspace.
@@ -86,9 +99,9 @@ By default, `--write` treats generated workspace files as local setup and adds t
 
 If a repo already contains tracked local agent files from an older setup, `brainclaw session-start` warns at the beginning of work and `brainclaw doctor --fix-agent-ignore` can repair the missing `.gitignore` entries. Tracked files still need to be untracked manually with Git after the ignore rules are in place.
 
-## MCP server workflow
-
-The brainclaw MCP server exposes all memory operations as tools that agents can call directly.
+## MCP server workflow
+
+The brainclaw MCP server exposes the dynamic Brainclaw workflow directly. For capable agents, this is the nominal runtime path.
 
 ### Starting the MCP server
 
@@ -116,19 +129,19 @@ Most agents pick this up via their MCP config file (`.mcp.json`, `~/.cursor/mcp.
 | `bclaw_bootstrap` | Initialize the workspace if not already done |
 | `bclaw_get_execution_context` | Get execution context (identity, claims, active plans) |
 
-## Session lifecycle
-
-### Starting a session
-
-```bash
-brainclaw session-start --agent my-agent --model claude-opus-4-5
+## Session lifecycle
+
+### Starting a session
+
+```bash
+brainclaw session-start --agent my-agent --model claude-opus-4-5
 ```
 
 This registers the agent's identity and optionally records the model being used. Other agents can see active sessions in `list-claims` and `board`.
 
-### During the session
-
-At each significant step:
+### During the session
+
+For MCP-capable agents, prefer the MCP equivalents of these actions. The CLI examples below are the operator and fallback form of the same lifecycle.
 
 ```bash
 brainclaw context --json        # load fresh project state
@@ -146,7 +159,7 @@ brainclaw session-end --auto-release
 
 This releases all active claims held by the current agent and updates plan statuses.
 
-## Generated files are local-only
+## Generated files are local-only
 
 Agent config files generated by brainclaw — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/brainclaw.md`, `.windsurfrules`, `.github/copilot-instructions.md` — are **not committed to Git**.
 

package/docs/integrations/claude-code.md

@@ -12,12 +12,12 @@ brainclaw export --format claude-md --write
 
 ## Recommended approach
 
-- add lightweight usage instructions for brainclaw in `CLAUDE.md`
-- use `.brainclaw/project.md` as a readable baseline
-- prefer MCP for dynamic retrieval when available
+- use MCP as the default runtime path for dynamic retrieval and writes
+- keep `CLAUDE.md` lightweight and behavioral: it should tell Claude Code when to call Brainclaw, not carry all mutable workspace state
+- use `.brainclaw/project.md` as a readable fallback baseline, not as the primary live source of truth
 - use hooks or workflow checks when a stronger reminder is needed
 
 ## Key idea
 
 Claude Code should not carry all workspace state in static instructions.
-brainclaw provides the living workspace layer.
+brainclaw provides the living workspace layer through MCP plus local workflow guidance.

package/docs/integrations/codex.md

@@ -12,12 +12,12 @@ brainclaw export --format agents-md --write
 
 ## Recommended approach
 
-- keep a lightweight instruction telling Codex to consult brainclaw
-- let Codex read `.brainclaw/project.md` when simple file context is enough
-- use MCP for fresher scoped context when available
-- encourage use of plans, claims, and handoffs during multi-step work
+- use MCP as the default runtime path for fresh context, plans, claims, and runtime notes
+- keep `AGENTS.md` lightweight and behavioral: it should remind Codex how to use Brainclaw, not duplicate live state
+- use `.brainclaw/project.md` only as a readable fallback when MCP is unavailable or when a human wants a simple snapshot
+- encourage plans, claims, and handoffs during multi-step work
 
 ## Good role for brainclaw here
 
 Codex stays the coding agent.
-brainclaw provides the shared workspace context and coordination layer.
+brainclaw provides the live workspace context and coordination layer.

package/docs/integrations/copilot.md

@@ -12,9 +12,10 @@ brainclaw export --format copilot-instructions --write
 
 ## Recommended approach
 
-- point Copilot to `.brainclaw/project.md` or use fresh context retrieval
+- use MCP whenever the Copilot surface supports it for fresh context and coordination views
+- keep `.github/copilot-instructions.md` lightweight and behavioral
+- use `.brainclaw/project.md` as readable fallback, not as the only live context source
 - use plans, claims, and handoffs to reduce ambiguity across sessions
-- use MCP where supported for dynamic collaboration views
 
 ## Why this matters
 

package/docs/integrations/cursor.md

@@ -12,12 +12,12 @@ brainclaw export --format cursor-rules --write
 
 ## Recommended approach
 
-- the generated `.cursor/rules/brainclaw.md` tells Cursor to consult brainclaw before significant edits
-- use `.brainclaw/project.md` for readable shared state
-- use MCP for dynamic retrieval when available
+- use MCP as the default dynamic path for context, board state, plans, and claims
+- let the generated `.cursor/rules/brainclaw.md` tell Cursor when to consult Brainclaw and how to stay inside the workflow
+- use `.brainclaw/project.md` only as readable fallback shared state
 - rely on claims and plans when multiple agents or humans are active in the same repo
 
 ## Key point
 
 Cursor rules describe behavior.
-brainclaw provides the living shared state those rules should point to.
+brainclaw provides the living shared state those rules should point to through MCP.

package/docs/integrations/mcp.md

@@ -1,24 +1,40 @@
 # MCP Integration
 
-brainclaw can expose collaboration and context views through MCP-readable tools.
+MCP is the primary Brainclaw integration path for capable coding agents.
 
-## Why MCP matters
+Use it whenever the agent can retrieve or mutate shared state directly instead of relying only on static files.
 
-MCP is especially useful when the agent should retrieve fresh workspace state directly instead of relying only on static files.
+## Why MCP Is The Nominal Path
 
-That is valuable for:
+MCP matters because Brainclaw's value is mostly in dynamic state:
 
-- ranked context retrieval
-- collaboration board views
-- write flows such as runtime notes
-- scoped activity retrieval
+- fresh context for the exact path being edited
+- current board state
+- active plans and claims
+- runtime observations
+- handoffs and review queues
 
-## Available tools
+Static files still help, but they age immediately. MCP is the stronger path for live coordination.
+
+## 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
+
+This keeps session continuity inside Brainclaw instead of pushing the agent back to manual CLI usage.
+
+## Available Tools
 
 | Tool | Purpose |
 |---|---|
 | `bclaw_get_context` | Ranked prompt-ready context, supports `digest: true` |
-| `bclaw_bootstrap` | Derive brownfield bootstrap signals 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 |
@@ -30,22 +46,52 @@ That is valuable for:
 | `bclaw_list_candidates` | Pending or archived review queue listing |
 | `bclaw_search` | Full-text search across memory |
 
-## Recommended use
+## When To Use MCP Versus Other Surfaces
+
+| Need | Best surface |
+|---|---|
+| Fresh path-scoped context | MCP |
+| Current plans, claims, board state | MCP |
+| Runtime writes with session continuity | MCP |
+| Local behavioral reminders inside the agent UI | native agent files |
+| Human inspection or scripting | CLI |
+| Simple readable fallback | `.brainclaw/project.md` |
 
-Use MCP as the dynamic access path for:
+## Starting The Server
 
-- fresh context
-- runtime coordination views
-- structured list views for plans, claims, agents, instructions, and review queues
-- shared board state
-- write operations that should preserve session continuity
+```bash
+brainclaw mcp
+```
 
-Readable files still matter, but MCP gives a stronger path for dynamic state.
+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`.
 
-## Practical layering
+## Bootstrap Through MCP
 
-| Surface | When to use |
-|---|---|
-| Files (`.brainclaw/project.md`) | Simple readable fallback, always available |
-| CLI | Explicit operational entry point, scripting |
-| MCP | Best dynamic integration path for capable agents |
+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.
+
+The CLI remains valuable for:
+
+- setup
+- bootstrap by a human operator
+- scripting
+- release and packaging
+- debugging and fallback access
+
+But for capable agents, MCP should be the first-class path for dynamic state.

package/docs/integrations/overview.md

@@ -1,61 +1,74 @@
 # Integration Overview
 
-brainclaw is designed to work with existing coding agents, not replace them.
-
-## Current limitation
-
-For now, Brainclaw should be used for sequential multi-agent collaboration, not true parallel editing in the same checkout.
-
-One agent can hand work to another, and the next agent can recover good project context through shared memory, plans, claims, and handoffs. But without dedicated Git worktrees per agent/session, running several coding agents concurrently on the same project checkout is still risky and can create conflicts or unstable local state.
-
-## Integration surfaces
-
-brainclaw can integrate through several surfaces:
-
-- **Readable files** — `.brainclaw/project.md`, `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md`
-- **Native agent files** — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/brainclaw.md`, `.windsurfrules`, etc. (via `brainclaw export`)
-- **CLI commands** — direct operational entry point
-- **MCP tools** — dynamic access path for capable agents
-- **System or project instructions** — static guidance for how to use brainclaw
-
-## Recommended pattern
+Brainclaw is designed to work with existing coding agents, not replace them.
+
+The key integration rule is simple:
+
+1. use MCP for dynamic shared state when the agent supports it
+2. use native agent files for local behavioral guidance
+3. use the CLI for setup, operator workflows, scripting, and fallback access
+
+## Current Limitation
+
+For now, Brainclaw should be used for sequential multi-agent collaboration, not true parallel editing in the same checkout.
+
+One agent can hand work to another, and the next agent can recover good project context through shared memory, plans, claims, and handoffs. But without dedicated Git worktrees per agent/session, running several coding agents concurrently on the same project checkout is still risky and can create conflicts or unstable local state.
+
+## Integration Surfaces
+
+brainclaw can integrate through several surfaces, but they do not have the same role.
+
+| Surface | Role |
+|---|---|
+| **MCP tools** | primary dynamic access path for context, plans, claims, board views, and runtime writes |
+| **Native agent files** | local guidance in the agent's own surface: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/brainclaw.md`, `.windsurfrules`, etc. |
+| **Readable files** | fallback readable state such as `.brainclaw/project.md` |
+| **CLI commands** | setup, scripting, release, inspection, and fallback workflows |
+| **System/project instructions** | static reminders about how Brainclaw should be used in this workspace |
+
+## Recommended Pattern
 
 A good default pattern is:
 
-1. use lightweight system instructions to tell the agent how to use brainclaw
-2. retrieve fresh workspace context before significant edits
-3. use shared plans and claims during execution
-4. use handoffs and runtime notes when switching work or surfacing issues
+1. give the agent lightweight static instructions about how to use Brainclaw
+2. let it retrieve fresh workspace state through MCP before significant edits
+3. rely on plans, claims, and handoffs during execution
+4. keep native files and readable project state available as fallback context
+5. use hooks or repeated reminders where the host surface supports them
+
+## Native Files Are Support, Not The Live Source Of Truth
 
-## Important principle
+Generated files such as `CLAUDE.md` or `.cursor/rules/brainclaw.md` are useful because they keep Brainclaw visible inside the agent surface already in use.
 
-Do not rely on a single point of contact.
+They are not meant to replace:
 
-Agents are not perfectly reliable at following instructions every time.
-The strongest integrations combine:
+- fresh context retrieval
+- live board state
+- current claims
+- recent runtime notes
+- current handoffs
 
-- instructions (static)
-- readable workspace state (file)
-- MCP or CLI access (dynamic)
-- repeated reminders in the workflow
-- optional hooks where supported
+For those, use MCP when available.
 
-## Getting the native file written automatically
+## Getting The Native File Written Automatically
+
+Run `brainclaw init` and Brainclaw will detect the current agent surface and write the appropriate local file automatically.
 
-Run `brainclaw init` — it detects the running agent and writes to its native file automatically.
 That includes OpenCode (`AGENTS.md` + `opencode.json`) and Antigravity/Gemini CLI (`GEMINI.md` + machine-local MCP config) when those environments are present.
 
 Or at any time:
 
 ```bash
-brainclaw export --detect
+brainclaw export --detect --write
 ```
 
-## Related pages
+By default, generated workspace files are treated as local setup and added to `.gitignore`. `--shared` should only be used when you intentionally want the main exported instruction file to be versioned.
 
-- [agents.md](agents.md)
-- [mcp.md](mcp.md)
-- [copilot.md](copilot.md)
-- [cursor.md](cursor.md)
+## Choose Your Next Page
+
+- [mcp.md](mcp.md) — the nominal path for capable agents
+- [agents.md](agents.md) — integration principles that apply to every agent
 - [claude-code.md](claude-code.md)
 - [codex.md](codex.md)
+- [cursor.md](cursor.md)
+- [copilot.md](copilot.md)

package/docs/mcp-schema-changelog.md

@@ -24,6 +24,15 @@ This document tracks all breaking and notable changes to the brainclaw MCP serve
   - Constraints can now have a category: architecture, performance, security, reliability, compatibility, process, other
   - Decisions can now have an outcome: approved, rejected, deferred, pending
 - Doctor check `metadata_consistency` — validates capability and tool completeness
+- `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