brainclaw 0.19.7 → 0.19.10

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,74 @@ 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(),
+    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(),
+    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([]),
+});
+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 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(),
+    confidence: MemorySeedConfidenceSchema.optional(),
+    summary: z.string(),
+    requires_confirmation: z.boolean().default(true),
+    gaps: z.array(z.string()).default([]),
+    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,15 +106,24 @@ 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` |
+| `--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 --apply -y
 ```
 
 ### `brainclaw env`
@@ -574,6 +592,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, adaptive interview prompts, and an import proposal when memory is still sparse |
 | `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,35 @@ 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
 
-Use MCP as the dynamic access path for:
+| 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` |
 
-- 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
+## Starting The Server
 
-Readable files still matter, but MCP gives a stronger path for dynamic state.
+```bash
+brainclaw mcp
+```
 
-## Practical layering
+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`.
 
-| 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 |
+## 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,9 @@ 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`
 
 **Changed**
 - MCP schema version bumped to 0.6.0 to reflect new metadata discovery capabilities

package/docs/product/positioning.md

@@ -65,32 +65,31 @@ Local-first gives teams:
 - Git history for shared project state
 - compatibility with enterprise or offline environments
 
-## Licensing
+## License direction
 
-brainclaw is published under the **Business Source License 1.1 (BSL 1.1)**.
+Today, brainclaw is published under the **Business Source License 1.1 (BSL 1.1)**.
 
-### What this means in practice
+The direction after the closed beta is simpler:
 
-| Use case | Status |
-|----------|--------|
-| Personal use, open-source projects | Free |
-| Internal team or company use | Free |
-| Embedding brainclaw in a product or service you sell | Requires a commercial license |
-| Competitive products that replicate brainclaw's core value | Requires a commercial license |
+- the local-first brainclaw core is intended to move to MIT
+- remote shared-memory, hosted collaboration, advanced dashboards, and related private add-ons will stay separate commercial products
 
-### Why BSL instead of MIT
+The intended MIT core covers the local coordination layer:
 
-MIT gives users complete freedom, including the freedom to take the source, wrap it, and resell it as a competing product without contributing back. For a small independent project, that means large vendors can capture the market before the original author can sustain the work.
+- local project memory
+- local MCP and CLI workflows
+- onboarding and bootstrap
+- plans, claims, handoffs, and runtime notes
+- local agent integrations
 
-BSL 1.1 preserves all the practical freedoms of open source (inspect, use, modify, contribute) while protecting the economic viability of the project. It is used by projects like MariaDB, HashiCorp Vault, and Sentry.
+The commercial side is meant to cover capabilities that go beyond the local-first core:
 
-### Conversion to MIT
+- shared memory through the cloud for agents working across machines
+- hosted sync and collaboration services
+- advanced dashboards
+- private add-ons around those hosted features
 
-The BSL includes an automatic conversion clause: the license converts to **MIT** after 4 years from each release date. Every version of brainclaw will eventually become fully open source.
-
-### Commercial licensing
-
-If your use case requires a commercial license, contact the project author. The intent is not to restrict legitimate internal use — it is to prevent competitive product embedding without a fair contribution back to the project.
+The goal is not to ship a stripped-down teaser. The goal is to keep the public core complete and useful on its own, while keeping remote and hosted features in a separate product line.
 
 ## Positioning summary