brainclaw 1.8.0 → 1.9.1

package/docs/quickstart.md

@@ -1,18 +1,18 @@
-# Quickstart
-
-Get brainclaw running in your project in under 5 minutes.
-
-> **Joining a project that already has `.brainclaw/`?** Use [quickstart-existing-project.md](quickstart-existing-project.md) instead — this page is for setting up a new project from scratch.
-
-If you're about to cut a release that changes the CLI, MCP, or context surface, run the checklist in [release-maintenance.md](release-maintenance.md) before publishing a local pack or npm build.
-
+# Quickstart
+
+Get brainclaw running in your project in under 5 minutes.
+
+> **Joining a project that already has `.brainclaw/`?** Use [quickstart-existing-project.md](quickstart-existing-project.md) instead — this page is for setting up a new project from scratch.
+
+If you're about to cut a release that changes the CLI, MCP, or context surface, run the checklist in [release-maintenance.md](release-maintenance.md) before publishing a local pack or npm build.
+
 ## Step 1: Install
 
 ```bash
 npm install -g brainclaw
 ```
 
-Requires Node.js 20+. Verify with `brainclaw --version`.
+Requires Node.js 20+ (`engines.node = ">=20.0.0"`). CI exercises Node 22 (Active LTS) and Node 24 (current LTS) — Node 22 or 24 is the recommended runtime; Node 20 still installs but is no longer CI-verified since its April 2026 EOL. Verify with `brainclaw --version`.
 
 ## Step 2: Bootstrap this machine
 
@@ -46,143 +46,144 @@ brainclaw enable-agent <agent-name>
 If you have multiple repos, use `brainclaw setup --yes` instead — it bootstraps the machine, scans your project directories, and initializes everything at once.
 
 ## Step 4: Restart your agent
-
-Your coding agent needs to reload to pick up the new MCP configuration.
-
-| Agent | How to reload |
-|-------|---------------|
-| **Claude Code** | Restart the CLI session or VS Code window |
-| **Cursor** | Cmd/Ctrl+Shift+P → "Reload Window" |
-| **Codex** | Start a new `codex` session |
-| **Cline** | Reload VS Code window |
-| **Windsurf** | Reload the editor |
-| **Copilot** | Reload VS Code window (uses instruction file, not MCP) |
-
+
+Your coding agent needs to reload to pick up the new MCP configuration.
+
+| Agent | How to reload |
+|-------|---------------|
+| **Claude Code** | Restart the CLI session or VS Code window |
+| **Cursor** | Cmd/Ctrl+Shift+P → "Reload Window" |
+| **Codex** | Start a new `codex` session |
+| **Cline** | Reload VS Code window |
+| **Windsurf** | Reload the editor |
+| **Copilot** | Reload VS Code window (uses instruction file, not MCP) |
+
 ## Step 5: Verify it works
-
-After reloading, tell your agent:
-
-```text
-Call bclaw_work with intent "resume" to check that brainclaw is connected.
-```
-
-The agent should respond with session info, project context, and available tools. If it does, brainclaw is connected.
-
-From the CLI, you can also verify:
-
-```bash
-brainclaw status          # active sessions, claims, plans
-brainclaw agent-board     # what each agent sees
-brainclaw context         # current project memory
-```
-
+
+After reloading, tell your agent:
+
+```text
+Call bclaw_work with intent "resume" to check that brainclaw is connected.
+```
+
+The agent should respond with session info, project context, and available tools. If it does, brainclaw is connected.
+
+From the CLI, you can also verify:
+
+```bash
+brainclaw status          # active sessions, claims, plans
+brainclaw agent-board     # what each agent sees
+brainclaw context         # current project memory
+```
+
 ## Step 6: Start using brainclaw
-
-### For agents with MCP (most agents)
-
-This is the primary path. Your agent calls brainclaw tools directly during work:
-
-| Tool | What it does |
-|------|-------------|
-| `bclaw_work(intent)` | Start a session, load context, claim scope — all in one call |
-| `bclaw_coordinate(intent, agents)` | Assign work, consult, request review, open an ideation loop, reroute, or summarize |
-| `bclaw_context(kind, path?)` | Read memory / execution / board / delta — narrow to a path when given |
-| `bclaw_claim(scope)` | Claim a file/directory before editing (prevents conflicts) |
-| `bclaw_write_note(text)` | Record an observation, decision, or trap during work |
-| `bclaw_session_end(narrative)` | Close session, release claims, hand off cleanly |
-
-The facades `bclaw_work` and `bclaw_coordinate` are the recommended entry points — they handle session setup, context loading, and claim management automatically. For entity reads and writes (plans, decisions, traps, handoffs, candidates, etc.), use the canonical grammar: `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition`.
-
-### For autonomous agents (no MCP)
-
-Autonomous agents (OpenClaw, NanoClaw, NemoClaw, PicoClaw, ZeroClaw) operate from a SKILL.md file generated by brainclaw. For Tier B/C agents that have MCP but no hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe, etc.), an opt-in `.live.md` companion (regenerated on session-end and handoff) carries plans, claims, traps, candidates, and handoffs as a parity backstop.
-
-Regenerate when project memory changes:
-
-```bash
-brainclaw export --detect --write
-```
-
-### Human operators (CLI)
-
-The CLI is for inspection, scripting, and fallback:
-
-```bash
-brainclaw plan create "Implement auth module" --priority high
-brainclaw plan list
-brainclaw claim list
-brainclaw context --for src/auth/routes.ts
-brainclaw export --detect --write    # regenerate all instruction files
-```
-
-## Onboarding an existing project
-
-If the repo already has code, brainclaw can extract context from it:
-
-```bash
-brainclaw bootstrap --json     # preview: CI patterns, ADRs, Docker, branches, tags
-brainclaw bootstrap --apply    # import detected signals into memory
-```
-
-Or let your agent drive it:
-
-```text
-Call bclaw_bootstrap to detect project signals, then review what was found.
-```
-
-## Common scenarios
-
-The same primitives serve multiple workflows. Pick the one that matches what you're doing — full walkthroughs in [`concepts/multi-agent-workflows.md`](concepts/multi-agent-workflows.md).
-
-### Active orchestration — parallel lanes across agent instances
-
-```text
-brainclaw sequence create "feature-cycle" --items '[…]' --status active
-bclaw_dispatch(intent="execute", agents=[…])
-```
-
-The dispatcher creates one worktree + claim per lane and routes inbox messages by `claim_id`. Lanes with `hard_after` unblock as predecessors finish.
-
-### Agent switching — when an agent runs out of credits mid-task
-
-```text
-# On the outgoing agent:
-bclaw_session_end(narrative="Did X. Need to finish Y.")
-
-# On the next agent (same or different):
-bclaw_work(intent="resume")
-```
-
-The new agent picks up the open plans, the latest handoff narrative, and the unfinished claims it can adopt. No re-explanation needed.
-
-### Project recovery — returning after weeks away
-
-```text
-bclaw_work(intent="resume")
-```
-
-Returns active plans, decisions taken since you left, active constraints, known traps, and where the last session stopped. Use `bclaw_context(kind="memory", profile="briefing")` for a narrower scope-focused view.
-
-### Team async — humans and agents sharing the same project
-
-Capture decisions, constraints, and traps as you discover them — they propagate to every teammate's agent on the next context read:
-
-```text
-bclaw_create(entity="decision",   data={ text: "…", outcome: "approved" })
-bclaw_create(entity="constraint", data={ text: "…", category: "security" })
-bclaw_create(entity="trap",       data={ text: "…", severity: "high" })
-```
-
-Hand off work for review with `bclaw_coordinate(intent="review", scope="…")`. Reviewers pick it up via `bclaw_read_inbox()`.
-
-### One rule across all four
-
-Scope-level claim isolation is strict — only one active claim per scope at a time, regardless of agent type. That's how parallel work stays safe and async handoffs stay clean.
-
-## Next reads
-
-- [integrations/overview.md](integrations/overview.md) — how brainclaw adapts to each agent
-- [integrations/mcp.md](integrations/mcp.md) — the MCP runtime path in detail
-- [concepts/memory.md](concepts/memory.md) — what project memory includes
-- [concepts/plans-and-claims.md](concepts/plans-and-claims.md) — coordination layer
-- [cli.md](cli.md) — full CLI reference
+
+### For agents with MCP (most agents)
+
+This is the primary path. Your agent calls brainclaw tools directly during work:
+
+| Tool | What it does |
+|------|-------------|
+| `bclaw_work(intent)` | Start a session, load context, claim scope — all in one call |
+| `bclaw_coordinate(intent, agents)` | Assign work, consult, request review, open an ideation loop, reroute, or summarize |
+| `bclaw_context(kind, path?)` | Read memory / execution / board / delta — narrow to a path when given |
+| `bclaw_claim(scope)` | Claim a file/directory before editing (prevents conflicts) |
+| `bclaw_write_note(text)` | Record an observation, decision, or trap during work |
+| `bclaw_session_end(narrative)` | Close session, release claims, hand off cleanly |
+
+The facades `bclaw_work` and `bclaw_coordinate` are the recommended entry points — they handle session setup, context loading, and claim management automatically. For entity reads and writes (plans, decisions, traps, handoffs, candidates, etc.), use the canonical grammar: `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition`.
+
+### For autonomous agents (no MCP)
+
+Autonomous agents (OpenClaw, NanoClaw, NemoClaw, PicoClaw, ZeroClaw) operate from a SKILL.md file generated by brainclaw. For Tier B/C agents that have MCP but no hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe, etc.), an opt-in `.live.md` companion (regenerated on session-end and handoff) carries plans, claims, traps, candidates, and handoffs as a parity backstop.
+
+Regenerate when project memory changes:
+
+```bash
+brainclaw export --detect --write
+```
+
+### Human operators (CLI)
+
+The CLI is for inspection, scripting, and fallback:
+
+```bash
+brainclaw plan create "Implement auth module" --priority high
+brainclaw plan list
+brainclaw claim list
+brainclaw context --for src/auth/routes.ts
+brainclaw export --detect --write    # regenerate the detected agent instruction file
+brainclaw export --all               # regenerate all known instruction files
+```
+
+## Onboarding an existing project
+
+If the repo already has code, brainclaw can extract context from it:
+
+```bash
+brainclaw bootstrap --json     # preview: CI patterns, ADRs, Docker, branches, tags
+brainclaw bootstrap --apply    # import detected signals into memory
+```
+
+Or let your agent drive it:
+
+```text
+Call bclaw_bootstrap to detect project signals, then review what was found.
+```
+
+## Common scenarios
+
+The same primitives serve multiple workflows. Pick the one that matches what you're doing — full walkthroughs in [`concepts/multi-agent-workflows.md`](concepts/multi-agent-workflows.md).
+
+### Active orchestration — parallel lanes across agent instances
+
+```text
+brainclaw sequence create "feature-cycle" --items '[…]' --status active
+bclaw_dispatch(intent="execute", agents=[…])
+```
+
+The dispatcher creates one worktree + claim per lane and routes inbox messages by `claim_id`. Lanes with `hard_after` unblock as predecessors finish.
+
+### Agent switching — when an agent runs out of credits mid-task
+
+```text
+# On the outgoing agent:
+bclaw_session_end(narrative="Did X. Need to finish Y.")
+
+# On the next agent (same or different):
+bclaw_work(intent="resume")
+```
+
+The new agent picks up the open plans, the latest handoff narrative, and the unfinished claims it can adopt. No re-explanation needed.
+
+### Project recovery — returning after weeks away
+
+```text
+bclaw_work(intent="resume")
+```
+
+Returns active plans, decisions taken since you left, active constraints, known traps, and where the last session stopped. Use `bclaw_context(kind="memory", profile="briefing")` for a narrower scope-focused view.
+
+### Team async — humans and agents sharing the same project
+
+Capture decisions, constraints, and traps as you discover them — they propagate to every teammate's agent on the next context read:
+
+```text
+bclaw_create(entity="decision",   data={ text: "…", outcome: "approved" })
+bclaw_create(entity="constraint", data={ text: "…", category: "security" })
+bclaw_create(entity="trap",       data={ text: "…", severity: "high" })
+```
+
+Hand off work for review with `bclaw_coordinate(intent="review", scope="…")`. Reviewers pick it up via `bclaw_read_inbox()`.
+
+### One rule across all four
+
+Scope-level claim isolation is strict — only one active claim per scope at a time, regardless of agent type. That's how parallel work stays safe and async handoffs stay clean.
+
+## Next reads
+
+- [integrations/overview.md](integrations/overview.md) — how brainclaw adapts to each agent
+- [integrations/mcp.md](integrations/mcp.md) — the MCP runtime path in detail
+- [concepts/memory.md](concepts/memory.md) — what project memory includes
+- [concepts/plans-and-claims.md](concepts/plans-and-claims.md) — coordination layer
+- [cli.md](cli.md) — full CLI reference

package/docs/release-maintenance.md

@@ -1,79 +1,79 @@
-# Release Maintenance
-
-Use this guide when a Brainclaw release changes the shipped CLI, MCP surface, context schema, or other operator-facing behavior.
-
-The goal is simple: if the product surface changed, the packaged docs and the anti-drift checks must change in the same branch before publishing.
-
-## When to run this checklist
-
-Run it before:
-
-- `brainclaw version --publish-local`
-- a merge that changes operator-visible behavior
-- a release candidate or local tarball build used for real agent testing
-
-Run it whenever a change affects one of these surfaces:
-
-- CLI commands, aliases, flags, help text, or examples
-- MCP tools, argument semantics, or read/write classification
-- context schema version or documented fields
-- packaged workflows such as worktrees, notes, plans, claims, bootstrap, or upgrade/reconcile flows
-
-## Release checklist
-
-1. Confirm the runtime surface that changed.
-   Check the relevant source files first, typically `src/cli.ts`, `src/commands/mcp.ts`, `src/commands/mcp-read-handlers.ts`, and `src/core/context.ts`.
-2. Update the packaged docs in the same branch.
-   At minimum touch the matching reference page in `docs/`, and update `README.md` if the change affects the product story or the primary entry path.
-3. Reconcile CLI and MCP wording.
-   If a concept exists on both surfaces, document the mapping explicitly. Example: `bclaw_write_note` ↔ `brainclaw runtime-note` / `brainclaw note create`.
-4. Re-check proposal versus shipped surface.
-   If a change is still design-only, keep it out of stable reference pages or mark it clearly as a proposal.
-5. Run the doc/reference verification before publishing.
-
-```bash
-npm run build:test
-node --test dist-test/tests/unit/docs-reference.test.js
-```
-
-6. Run targeted command tests for the changed surface.
-   Prefer focused tests over broad slow suites when the behavior is small and operator-facing.
-
-Examples from the current repo:
-
-```bash
-node --test dist-test/tests/unit/plan-resource-command.test.js
-node --test --test-name-pattern "accepts note create as an alias for runtime-note" dist-test/tests/collaboration.test.js
-```
-
-7. Only then publish or pack a local release.
-
-```bash
-brainclaw version --publish-local --release-notes "..."
-```
-
-## Minimum files to review
-
-This is the smallest practical review set for release-visible drift:
-
-- `README.md`
-- `docs/index.md`
-- `docs/cli.md`
-- `docs/integrations/mcp.md`
-- `docs/context-format.md`
-- `docs/context-format-changelog.md`
-- `tests/unit/docs-reference.test.ts`
-
-Add workflow-specific docs when needed, for example:
-
-- `docs/server-operations.md`
-- `docs/quickstart.md`
-- `docs/concepts/plans-and-claims.md`
-
-## What this checklist is trying to prevent
-
-- shipping a command that exists in code but not in `docs/cli.md`
-- claiming a feature is unavailable when the code already ships it
-- documenting a proposal as if it were stable product behavior
-- leaving MCP and CLI with different names for the same operator workflow
-- publishing a local tarball that agents test against while bundled docs still describe the previous surface
+# Release Maintenance
+
+Use this guide when a Brainclaw release changes the shipped CLI, MCP surface, context schema, or other operator-facing behavior.
+
+The goal is simple: if the product surface changed, the packaged docs and the anti-drift checks must change in the same branch before publishing.
+
+## When to run this checklist
+
+Run it before:
+
+- `brainclaw version --publish-local`
+- a merge that changes operator-visible behavior
+- a release candidate or local tarball build used for real agent testing
+
+Run it whenever a change affects one of these surfaces:
+
+- CLI commands, aliases, flags, help text, or examples
+- MCP tools, argument semantics, or read/write classification
+- context schema version or documented fields
+- packaged workflows such as worktrees, notes, plans, claims, bootstrap, or upgrade/reconcile flows
+
+## Release checklist
+
+1. Confirm the runtime surface that changed.
+   Check the relevant source files first, typically `src/cli.ts`, `src/commands/mcp.ts`, `src/commands/mcp-read-handlers.ts`, and `src/core/context.ts`.
+2. Update the packaged docs in the same branch.
+   At minimum touch the matching reference page in `docs/`, and update `README.md` if the change affects the product story or the primary entry path.
+3. Reconcile CLI and MCP wording.
+   If a concept exists on both surfaces, document the mapping explicitly. Example: `bclaw_write_note` ↔ `brainclaw runtime-note` / `brainclaw note create`.
+4. Re-check proposal versus shipped surface.
+   If a change is still design-only, keep it out of stable reference pages or mark it clearly as a proposal.
+5. Run the doc/reference verification before publishing.
+
+```bash
+npm run build:test
+node --test dist-test/tests/unit/docs-reference.test.js
+```
+
+6. Run targeted command tests for the changed surface.
+   Prefer focused tests over broad slow suites when the behavior is small and operator-facing.
+
+Examples from the current repo:
+
+```bash
+node --test dist-test/tests/unit/plan-resource-command.test.js
+node --test --test-name-pattern "accepts note create as an alias for runtime-note" dist-test/tests/collaboration.test.js
+```
+
+7. Only then publish or pack a local release.
+
+```bash
+brainclaw version --publish-local --release-notes "..."
+```
+
+## Minimum files to review
+
+This is the smallest practical review set for release-visible drift:
+
+- `README.md`
+- `docs/index.md`
+- `docs/cli.md`
+- `docs/integrations/mcp.md`
+- `docs/context-format.md`
+- `docs/context-format-changelog.md`
+- `tests/unit/docs-reference.test.ts`
+
+Add workflow-specific docs when needed, for example:
+
+- `docs/server-operations.md`
+- `docs/quickstart.md`
+- `docs/concepts/plans-and-claims.md`
+
+## What this checklist is trying to prevent
+
+- shipping a command that exists in code but not in `docs/cli.md`
+- claiming a feature is unavailable when the code already ships it
+- documenting a proposal as if it were stable product behavior
+- leaving MCP and CLI with different names for the same operator workflow
+- publishing a local tarball that agents test against while bundled docs still describe the previous surface

package/docs/reputation.md

@@ -1,52 +1,52 @@
-# Reputation
-
-Reputation in brainclaw is a bounded trust signal, not a gamified score system.
-
-## Purpose
-
-Its role is to support:
-
-- review routing
-- context ranking tie-breakers
-- continuity summaries
-
-It is **not** a leaderboard or a mutable points ledger.
-
-## How it works
-
-Three subscores are tracked:
-
-| Subscore | What it measures |
-|---|---|
-| `contribution_quality` | Quality and adoption of contributed items |
-| `review_reliability` | Consistency of review participation |
-| `continuity_hygiene` | Session and claim hygiene behaviour |
-
-These feed an internal bounded score named `internal_trust` computed from a rolling window of recent observable behavior.
-
-## Configuration
-
-```yaml
-reputation:
-  enabled: true
-  visibility: summary       # 'summary' or 'internal-only'
-  decay_days: 30
-  ranking_weight: 0.15
-  resume_weight: 0.35
-  mcp_exposure: true
-```
-
-## Where reputation surfaces
-
-- `status --json` — internal snapshot (when enabled)
-- `context` — compact `resume_summary` + small ranking bonus
-- `list-agents --with-reputation` — bounded public summaries
-- `agent-board --with-reputation` — aggregate + selected agent summary
-- `doctor --json` — high-level metrics only
-- MCP board consumers — opt-in with `includeReputation`
-
-## Product caution
-
-This feature is advanced and should stay secondary to the core product story.
-The primary value of brainclaw is shared workspace coordination, not reputation mechanics.
-Quality matters more than volume. Semantic relevance still dominates ranking.
+# Reputation
+
+Reputation in brainclaw is a bounded trust signal, not a gamified score system.
+
+## Purpose
+
+Its role is to support:
+
+- review routing
+- context ranking tie-breakers
+- continuity summaries
+
+It is **not** a leaderboard or a mutable points ledger.
+
+## How it works
+
+Three subscores are tracked:
+
+| Subscore | What it measures |
+|---|---|
+| `contribution_quality` | Quality and adoption of contributed items |
+| `review_reliability` | Consistency of review participation |
+| `continuity_hygiene` | Session and claim hygiene behaviour |
+
+These feed an internal bounded score named `internal_trust` computed from a rolling window of recent observable behavior.
+
+## Configuration
+
+```yaml
+reputation:
+  enabled: true
+  visibility: summary       # 'summary' or 'internal-only'
+  decay_days: 30
+  ranking_weight: 0.15
+  resume_weight: 0.35
+  mcp_exposure: true
+```
+
+## Where reputation surfaces
+
+- `status --json` — internal snapshot (when enabled)
+- `context` — compact `resume_summary` + small ranking bonus
+- `list-agents --with-reputation` — bounded public summaries
+- `agent-board --with-reputation` — aggregate + selected agent summary
+- `doctor --json` — high-level metrics only
+- MCP board consumers — opt-in with `includeReputation`
+
+## Product caution
+
+This feature is advanced and should stay secondary to the core product story.
+The primary value of brainclaw is shared workspace coordination, not reputation mechanics.
+Quality matters more than volume. Semantic relevance still dominates ranking.