brainclaw 1.8.0 → 1.9.1

package/docs/product/positioning.md

@@ -1,70 +1,70 @@
-# Positioning
-
-brainclaw is a **local-first coordination layer for humans and coding agents**.
-
-It is not trying to become another coding agent, another hosted team platform, or another opaque memory service.
-
-## The problem
-
-Coding agents are good at local generation but weak at shared project state.
-
-They often struggle with:
-
-- remembering active constraints
-- keeping track of recent decisions
-- avoiding known traps
-- coordinating shared plans
-- handling handoffs cleanly
-- avoiding collisions on files
-- adapting instructions across different workspaces on the same machine
-
-Traditional agent instruction files help, but they are relatively static.
-They do not provide a living coordination layer for a workspace.
-
-## What brainclaw does differently
-
-brainclaw turns the workspace into a shared layer of:
-
-- project memory
-- implementation state
-- coordination state
-- prompt-ready context
-
-Instead of relying only on fixed instruction files, brainclaw exposes fresh workspace state through files, CLI commands, and MCP tools.
-
-It also writes directly to each agent's native instruction format — `CLAUDE.md`, `.cursor/rules/`, `.windsurfrules`, etc. — so the right context is always in the right place.
-
-## What brainclaw is not
-
-- a replacement for your coding agents
-- a project management SaaS
-- a black-box orchestration platform
-- a cloud memory layer
-- a replacement for Git
-
-It sits next to existing tools and helps them collaborate more like a development team.
-
-## Core product promise
-
-brainclaw helps coding agents and humans work together around a shared workspace by making the important things explicit:
-
-- what the project should remember
-- what is currently being worked on
-- who is touching which files
-- what needs to be handed off
-- what context is relevant right now
-
-## Why local-first matters
-
-Local-first gives teams:
-
-- full control over data
-- no network dependency
-- no hidden storage
-- plain text and JSON artifacts
-- Git history for shared project state
-- compatibility with enterprise or offline environments
-
+# Positioning
+
+brainclaw is a **local-first coordination layer for humans and coding agents**.
+
+It is not trying to become another coding agent, another hosted team platform, or another opaque memory service.
+
+## The problem
+
+Coding agents are good at local generation but weak at shared project state.
+
+They often struggle with:
+
+- remembering active constraints
+- keeping track of recent decisions
+- avoiding known traps
+- coordinating shared plans
+- handling handoffs cleanly
+- avoiding collisions on files
+- adapting instructions across different workspaces on the same machine
+
+Traditional agent instruction files help, but they are relatively static.
+They do not provide a living coordination layer for a workspace.
+
+## What brainclaw does differently
+
+brainclaw turns the workspace into a shared layer of:
+
+- project memory
+- implementation state
+- coordination state
+- prompt-ready context
+
+Instead of relying only on fixed instruction files, brainclaw exposes fresh workspace state through files, CLI commands, and MCP tools.
+
+It also writes directly to each agent's native instruction format — `CLAUDE.md`, `.cursor/rules/`, `.windsurfrules`, etc. — so the right context is always in the right place.
+
+## What brainclaw is not
+
+- a replacement for your coding agents
+- a project management SaaS
+- a black-box orchestration platform
+- a cloud memory layer
+- a replacement for Git
+
+It sits next to existing tools and helps them collaborate more like a development team.
+
+## Core product promise
+
+brainclaw helps coding agents and humans work together around a shared workspace by making the important things explicit:
+
+- what the project should remember
+- what is currently being worked on
+- who is touching which files
+- what needs to be handed off
+- what context is relevant right now
+
+## Why local-first matters
+
+Local-first gives teams:
+
+- full control over data
+- no network dependency
+- no hidden storage
+- plain text and JSON artifacts
+- Git history for shared project state
+- compatibility with enterprise or offline environments
+
 ## License
 
 brainclaw core is published under the **MIT License**.
@@ -75,22 +75,22 @@ The product split is:
 - remote shared-memory, hosted collaboration, advanced dashboards, and related private add-ons will stay separate commercial products
 
 The MIT core covers the local coordination layer:
-
-- local project memory
-- local MCP and CLI workflows
-- onboarding and bootstrap
-- plans, claims, handoffs, and runtime notes
-- local agent integrations
-
-The commercial side is meant to cover capabilities that go beyond the local-first core:
-
-- 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 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
-
-> A local-first coordination layer for humans and coding agents.
+
+- local project memory
+- local MCP and CLI workflows
+- onboarding and bootstrap
+- plans, claims, handoffs, and runtime notes
+- local agent integrations
+
+The commercial side is meant to cover capabilities that go beyond the local-first core:
+
+- 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 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
+
+> A local-first coordination layer for humans and coding agents.

package/docs/quickstart-existing-project.md

@@ -1,11 +1,11 @@
-# Joining a project that already uses brainclaw
-
-You cloned a repo and noticed `.brainclaw/` already exists — someone (or something) has set it up before you. This page walks through the read-then-register path for arriving on a configured project, which is **different** from creating a new one.
-
-If the repo is brand new and `.brainclaw/` is absent, see [quickstart.md](quickstart.md) instead.
-
-## When to use this page
-
+# Joining a project that already uses brainclaw
+
+You cloned a repo and noticed `.brainclaw/` already exists — someone (or something) has set it up before you. This page walks through the read-then-register path for arriving on a configured project, which is **different** from creating a new one.
+
+If the repo is brand new and `.brainclaw/` is absent, see [quickstart.md](quickstart.md) instead.
+
+## When to use this page
+
 | Situation | Use |
 |---|---|
 | Repo has no `.brainclaw/` | [quickstart.md](quickstart.md) (`brainclaw init`) |
@@ -17,23 +17,23 @@ The three commands now target different lifecycle stages:
 - `init` creates or refreshes project setup safely
 - `bootstrap` extracts project context into memory
 - `enable-agent` explicitly joins another agent to the same project
-
-## Step 0 — verify your install is compatible
-
-```bash
-brainclaw --version
-```
-
-Compare with what the project expects. If `.brainclaw/config.yaml` has a `version_policy` block, it tells you the minimum version the project requires. If your local version is older, `brainclaw doctor --json` will surface a `version_policy` failure.
-
-To upgrade:
-
-```bash
-npm install -g brainclaw@latest
-```
-
-(or pull the team's local-pack tarball from `.releases/` if the project doesn't publish to npm.)
-
+
+## Step 0 — verify your install is compatible
+
+```bash
+brainclaw --version
+```
+
+Compare with what the project expects. If `.brainclaw/config.yaml` has a `version_policy` block, it tells you the minimum version the project requires. If your local version is older, `brainclaw doctor --json` will surface a `version_policy` failure.
+
+To upgrade:
+
+```bash
+npm install -g brainclaw@latest
+```
+
+(or pull the team's local-pack tarball from `.releases/` if the project doesn't publish to npm.)
+
 ## Step 1 — bootstrap this machine if needed
 
 ```bash
@@ -67,89 +67,89 @@ These commands:
 If you use multiple agents on the same project, run `enable-agent` once per agent.
 
 ## Step 3 — read what already exists
-
-Before touching code, load the project's accumulated knowledge so you don't re-discover what others already learned.
-
-### Via the CLI (you, the human)
-
-```bash
-brainclaw context           # full project memory as text (constraints, decisions, traps, plans)
-brainclaw agent-board       # current state of plans, claims, and open handoffs
-brainclaw stale list        # what looks abandoned and might need attention
-```
-
-### Via your agent (recommended day-to-day)
-
-Tell the agent to call:
-
-```text
-bclaw_work(intent="resume")
-```
-
-This single MCP call returns: open plans, recent decisions, active constraints, known traps, latest handoff narrative, plus a context-diff hint. Your agent reads that *before* writing any code.
-
-For a narrower view focused on the area you're about to touch:
-
-```text
-bclaw_context(kind="memory", path="src/<area>/")
-```
-
+
+Before touching code, load the project's accumulated knowledge so you don't re-discover what others already learned.
+
+### Via the CLI (you, the human)
+
+```bash
+brainclaw context           # full project memory as text (constraints, decisions, traps, plans)
+brainclaw agent-board       # current state of plans, claims, and open handoffs
+brainclaw stale list        # what looks abandoned and might need attention
+```
+
+### Via your agent (recommended day-to-day)
+
+Tell the agent to call:
+
+```text
+bclaw_work(intent="resume")
+```
+
+This single MCP call returns: open plans, recent decisions, active constraints, known traps, latest handoff narrative, plus a context-diff hint. Your agent reads that *before* writing any code.
+
+For a narrower view focused on the area you're about to touch:
+
+```text
+bclaw_context(kind="memory", path="src/<area>/")
+```
+
 ## Step 4 — discover in-flight work
-
-Several things may be already underway when you arrive:
-
-```bash
-# Plans that other agents/humans started
-brainclaw plan list --status in_progress
-
-# Scopes someone else has claimed (don't touch those without coordination)
-brainclaw claim list
-
-# Sequences with parallel lanes still active
-brainclaw sequence list --status active
-
-# Open handoffs waiting for a reviewer
-brainclaw inbox list
-```
-
-Or one-shot via MCP:
-
-```text
-bclaw_context(kind="board")
-```
-
-The board surfaces all four (plans, claims, sequences, handoffs) in one structured response.
-
+
+Several things may be already underway when you arrive:
+
+```bash
+# Plans that other agents/humans started
+brainclaw plan list --status in_progress
+
+# Scopes someone else has claimed (don't touch those without coordination)
+brainclaw claim list
+
+# Sequences with parallel lanes still active
+brainclaw sequence list --status active
+
+# Open handoffs waiting for a reviewer
+brainclaw inbox list
+```
+
+Or one-shot via MCP:
+
+```text
+bclaw_context(kind="board")
+```
+
+The board surfaces all four (plans, claims, sequences, handoffs) in one structured response.
+
 ## Step 5 — pick what to work on
-
-You have a few honest options:
-
-1. **Pick up an open handoff** — `brainclaw inbox list` shows handoffs targeted at you (or unassigned). Read the handoff narrative, then claim its scope and start.
-2. **Take a `todo` plan** — `brainclaw plan list --status todo` returns work nobody has started yet.
-3. **Start something new** — create a fresh plan with `bclaw_create(entity="plan", data={…})`, then claim its scope. Make sure you're not duplicating an existing plan first.
-
-In all three cases, the workflow is then the same: `bclaw_work(intent="execute", scope=…, planId=…)` opens a session, claims the scope (with an isolated git worktree), and loads the relevant context.
-
+
+You have a few honest options:
+
+1. **Pick up an open handoff** — `brainclaw inbox list` shows handoffs targeted at you (or unassigned). Read the handoff narrative, then claim its scope and start.
+2. **Take a `todo` plan** — `brainclaw plan list --status todo` returns work nobody has started yet.
+3. **Start something new** — create a fresh plan with `bclaw_create(entity="plan", data={…})`, then claim its scope. Make sure you're not duplicating an existing plan first.
+
+In all three cases, the workflow is then the same: `bclaw_work(intent="execute", scope=…, planId=…)` opens a session, claims the scope (with an isolated git worktree), and loads the relevant context.
+
 ## Step 6 — verify your setup is healthy before commiting changes
-
-Once you've started working, sanity-check:
-
-```bash
-brainclaw doctor
-```
-
-This runs a series of checks: state validity, MCP runtime health (post-pln#478), agent-integration declarations, claim hygiene, freshness markers. If anything is amber or red, see [docs/concepts/troubleshooting.md](concepts/troubleshooting.md) for the runbook.
-
-## What this page does *not* cover
-
-- **Creating a new project** → [quickstart.md](quickstart.md)
-- **Extracting context from an existing repo without `.brainclaw/`** → [bootstrap](concepts/workspace-bootstrapping.md)
+
+Once you've started working, sanity-check:
+
+```bash
+brainclaw doctor
+```
+
+This runs a series of checks: state validity, MCP runtime health (post-pln#478), agent-integration declarations, claim hygiene, freshness markers. If anything is amber or red, see [docs/concepts/troubleshooting.md](concepts/troubleshooting.md) for the runbook.
+
+## What this page does *not* cover
+
+- **Creating a new project** → [quickstart.md](quickstart.md)
+- **Extracting context from an existing repo without `.brainclaw/`** → [bootstrap](concepts/workspace-bootstrapping.md)
 - **Setting up brainclaw on your machine for the first time** → [docs/integrations/overview.md](integrations/overview.md) (`brainclaw setup-machine` or the broader `brainclaw setup` flow)
-- **Recovering from a degraded state** → [docs/concepts/troubleshooting.md](concepts/troubleshooting.md)
-
-## See also
-
-- [docs/quickstart.md](quickstart.md) — full first-time setup (greenfield)
-- [docs/concepts/plans-and-claims.md](concepts/plans-and-claims.md) — claim/plan model
-- [docs/concepts/multi-agent-workflows.md](concepts/multi-agent-workflows.md) — coordination patterns once you're settled in
-- [docs/concepts/troubleshooting.md](concepts/troubleshooting.md) — when things go wrong
+- **Recovering from a degraded state** → [docs/concepts/troubleshooting.md](concepts/troubleshooting.md)
+
+## See also
+
+- [docs/quickstart.md](quickstart.md) — full first-time setup (greenfield)
+- [docs/concepts/plans-and-claims.md](concepts/plans-and-claims.md) — claim/plan model
+- [docs/concepts/multi-agent-workflows.md](concepts/multi-agent-workflows.md) — coordination patterns once you're settled in
+- [docs/concepts/troubleshooting.md](concepts/troubleshooting.md) — when things go wrong