brainclaw 0.19.7 → 0.19.11

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,30 +1,66 @@
 # 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
+
+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
+```
+
+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
+
+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 setup --yes
+brainclaw init
+brainclaw export --detect --write
+```
+
+### Record the first important facts
 
 ```bash
 brainclaw memory create decision "OAuth migration now goes through auth-gateway" --tag auth
@@ -32,68 +68,82 @@ brainclaw memory create constraint "Payments module frozen until 2026-04-01" --t
 brainclaw memory create trap "Checkout E2E tests are flaky on Windows" --severity high --tag tests
 ```
 
-These become part of the shared project memory.
-
-## 3. Create a shared plan
+### Create and claim work
 
 ```bash
 brainclaw plan create "Coordinate auth rollout" --priority high
-brainclaw plan list
+brainclaw claim create "Take auth rollout" --scope src/auth/
 ```
 
-## 4. Claim work before editing
+### Refresh context before edits
 
 ```bash
-brainclaw claim create "Taking auth rollout" --agent copilot --scope src/auth/ --plan pln_001
-brainclaw claim list --plan pln_001
+brainclaw context --for src/auth/routes.ts --digest
+brainclaw status
 ```
 
-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.
+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
+
+Use this path when you are adopting Brainclaw into an existing workspace and do not want to hand-author all memory from scratch.
 
-## 5. Create an explicit handoff
+### Build the initial bootstrap view
 
 ```bash
-brainclaw memory create handoff "Review auth patch" --from copilot --to claude --plan pln_001
+brainclaw setup --yes
+brainclaw init
+brainclaw bootstrap --json
 ```
 
-## 6. Generate context for an agent
+### Fill the gaps
 
 ```bash
-brainclaw context --for src/auth/routes.ts --digest
-brainclaw context --json --max-chars 1200
+brainclaw bootstrap --interview --audience cli
+brainclaw bootstrap --interview --audience ide_chat
 ```
 
-Use this to prepare compact context before edits or reviews.
+Use the returned question IDs to prepare a small JSON answers file when the interview needs to confirm durable memory:
+
+```json
+[
+  {
+    "question_id": "biq_example",
+    "response_items": ["Use agents sequentially in one checkout."],
+    "suggestions": []
+  }
+]
+```
 
-## 7. Export to your agent's native instruction file
+Preview the enriched import proposal:
 
 ```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 bootstrap --answers-file ./bootstrap-answers.json --json
 ```
 
-## 8. Inspect the current board
+### Apply or rollback managed imports
 
 ```bash
-brainclaw status
-brainclaw agent-board --agent copilot
+brainclaw bootstrap --answers-file ./bootstrap-answers.json --apply
+brainclaw bootstrap --uninstall
 ```
 
-## Recommended first workflow
-
-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
+Use this path when the repo already has native instruction files, partial docs, or conventions that Brainclaw should adopt selectively instead of replacing blindly.
 
-## Next reads
+## Recommended First Workflow
 
-- [cli.md](cli.md) — full command reference
+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,18 +1,18 @@
 {
   "name": "brainclaw",
-  "version": "0.19.7",
+  "version": "0.19.11",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {
     "brainclaw": "dist/cli.js",
     "bclaw": "dist/cli.js"
   },
-  "files": [
-    "dist/**/*.js",
-    "docs/**/*.md",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": [
+    "dist/**/*.js",
+    "docs/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc && node dist/cli.js",