brainclaw 0.19.6 → 0.19.10

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
 

package/docs/quickstart.md

@@ -1,99 +1,131 @@
 # Quickstart
 
-This guide walks through the shortest path to getting value from brainclaw.
-
-## Important limitation for now
-
-Do not run multiple coding agents in parallel on the same project checkout yet.
-
-brainclaw is already useful for sequential collaboration: one agent can pick up where another stopped, inspect shared context, and continue from explicit plans, claims, traps, and handoffs. But until Brainclaw supports dedicated Git worktrees per agent/session, parallel edits in the same checkout are still likely to create more Git and workspace problems than they solve.
-
-For now, prefer:
-
-1. one active editing agent per checkout
-2. explicit handoffs between agents
-3. claims and context to keep continuity between sessions
-
-## 1. Bootstrap and initialize the workspace
+This guide is organized by entry path, because Brainclaw serves different surfaces with different roles.
+
+Use this rule first:
+
+- capable agent with MCP support: prefer MCP for dynamic state
+- agent surface driven mainly by local instruction files: use generated native files plus CLI fallback
+- human operator or maintainer: use the CLI directly
+
+## Important limitation for now
+
+Do not run multiple coding agents in parallel on the same project checkout yet.
+
+Brainclaw is already useful for sequential collaboration: one agent can pick up where another stopped, inspect shared context, and continue from explicit plans, claims, traps, and handoffs. But until Brainclaw supports dedicated Git worktrees per agent/session, parallel edits in the same checkout are still likely to create more Git and workspace problems than they solve.
+
+For now, prefer:
+
+1. one active editing agent per checkout
+2. explicit handoffs between agents
+3. claims and context to keep continuity between sessions
+
+## Path 1: Agent-First With MCP
+
+Use this path when the agent can call Brainclaw through MCP.
+
+### Operator bootstrap
 
 ```bash
 brainclaw setup --yes
 brainclaw init
 ```
 
-`setup` installs the machine-level prerequisites and agent integrations. `init` then creates the workspace state, seeds stable identity, and prepares the project memory structure.
-If an AI coding agent is detected in the environment, brainclaw also writes to its native instruction file automatically.
+`setup` installs machine-level prerequisites and agent integrations. `init` creates the workspace state, seeds stable identity, and prepares the project memory structure.
 
-## 2. Capture the first important facts
+### Agent runtime pattern
 
-```bash
-brainclaw memory create decision "OAuth migration now goes through auth-gateway" --tag auth
-brainclaw memory create constraint "Payments module frozen until 2026-04-01" --tag payments
-brainclaw memory create trap "Checkout E2E tests are flaky on Windows" --severity high --tag tests
+After the workspace is initialized, the nominal flow is:
+
+```text
+bclaw_session_start   -> open a session and return current board/context
+bclaw_get_context     -> fetch fresh prompt-ready context for the target path
+bclaw_list_plans      -> inspect active work
+bclaw_claim           -> claim scope before editing
+bclaw_write_note      -> record runtime observations
+bclaw_session_end     -> close session cleanly and hand work off
 ```
 
-These become part of the shared project memory.
+Use native agent files such as `AGENTS.md`, `CLAUDE.md`, or Cursor rules as local workflow guidance, not as the only source of live state.
+
+## Path 2: CLI-Oriented Agent Or Fallback Workflow
 
-## 3. Create a shared plan
+Use this path when the agent does not have a good MCP integration yet, or when a human needs to drive the workflow directly.
+
+### Bootstrap and inspect
 
 ```bash
-brainclaw plan create "Coordinate auth rollout" --priority high
-brainclaw plan list
+brainclaw setup --yes
+brainclaw init
+brainclaw export --detect --write
 ```
 
-## 4. Claim work before editing
+### Record the first important facts
 
 ```bash
-brainclaw claim create "Taking auth rollout" --agent copilot --scope src/auth/ --plan pln_001
-brainclaw claim list --plan pln_001
+brainclaw memory create decision "OAuth migration now goes through auth-gateway" --tag auth
+brainclaw memory create constraint "Payments module frozen until 2026-04-01" --tag payments
+brainclaw memory create trap "Checkout E2E tests are flaky on Windows" --severity high --tag tests
 ```
 
-Claims reduce collisions, but they are not a substitute for isolated worktrees yet.
-Use them mainly to coordinate sequential work or human/agent awareness in the same repo.
-
-## 5. Create an explicit handoff
+### Create and claim work
 
 ```bash
-brainclaw memory create handoff "Review auth patch" --from copilot --to claude --plan pln_001
+brainclaw plan create "Coordinate auth rollout" --priority high
+brainclaw claim create "Take auth rollout" --scope src/auth/
 ```
 
-## 6. Generate context for an agent
+### Refresh context before edits
 
 ```bash
 brainclaw context --for src/auth/routes.ts --digest
-brainclaw context --json --max-chars 1200
+brainclaw status
 ```
 
-Use this to prepare compact context before edits or reviews.
+Claims reduce collisions, but they are not a substitute for isolated worktrees yet. Use them mainly to coordinate sequential work or human/agent awareness in the same repo.
+
+## Path 3: Brownfield Onboarding
 
-## 7. Export to your agent's native instruction file
+Use this path when you are adopting Brainclaw into an existing workspace and do not want to hand-author all memory from scratch.
+
+### Build the initial bootstrap view
 
 ```bash
-brainclaw export --detect          # auto-detects running agent, writes to its file
-brainclaw export --format claude-md --write   # writes CLAUDE.md and gitignores it by default
-brainclaw export --format cursor-rules --write  # writes .cursor/rules/brainclaw.md and gitignores it by default
-brainclaw export --format claude-md --write --shared  # only if you intentionally want to commit it
+brainclaw setup --yes
+brainclaw init
+brainclaw bootstrap --json
 ```
 
-## 8. Inspect the current board
+### Fill the gaps
 
 ```bash
-brainclaw status
-brainclaw agent-board --agent copilot
+brainclaw bootstrap --interview --audience cli
+brainclaw bootstrap --interview --audience ide_chat
 ```
 
-## Recommended first workflow
+### Apply or rollback managed imports
 
-1. initialize the workspace
-2. record 3–5 important decisions or traps
-3. create one shared plan
-4. use claims for touched folders
-5. generate context before edits
-6. hand off explicitly when switching between agents
+```bash
+brainclaw bootstrap --apply
+brainclaw bootstrap --uninstall
+```
 
-## Next reads
+Use this path when the repo already has native instruction files, partial docs, or conventions that Brainclaw should adopt selectively instead of replacing blindly.
 
-- [cli.md](cli.md) — full command reference
+## Recommended First Workflow
+
+1. initialize the workspace
+2. choose the correct entry path for your surface
+3. record or import 3-5 high-signal facts
+4. create one shared plan
+5. claim scope before editing
+6. refresh context before significant edits
+7. hand off explicitly when switching between agents
+
+## Next Reads
+
+- [integrations/overview.md](integrations/overview.md) — integration model by surface
+- [integrations/mcp.md](integrations/mcp.md) — nominal dynamic path for capable agents
+- [cli.md](cli.md) — operator and fallback reference
 - [concepts/memory.md](concepts/memory.md)
 - [concepts/plans-and-claims.md](concepts/plans-and-claims.md)
-- [integrations/overview.md](integrations/overview.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.19.6",
+  "version": "0.19.10",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {
@@ -10,7 +10,6 @@
   "files": [
     "dist/**/*.js",
     "docs/**/*.md",
-    "!docs/plan.md",
     "README.md",
     "LICENSE"
   ],