brainclaw 0.19.4 → 0.19.6

package/docs/integrations/cursor.md

@@ -0,0 +1,23 @@
+# Cursor Integration
+
+brainclaw works well next to Cursor because Cursor can already operate with project rules and can benefit from explicit workspace context.
+
+## Auto-setup
+
+`brainclaw init` detects Cursor (`CURSOR_TRACE_ID`) and writes `.cursor/rules/brainclaw.md` automatically. Or manually:
+
+```bash
+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
+- 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.

package/docs/integrations/mcp.md

@@ -0,0 +1,51 @@
+# MCP Integration
+
+brainclaw can expose collaboration and context views through MCP-readable tools.
+
+## Why MCP matters
+
+MCP is especially useful when the agent should retrieve fresh workspace state directly instead of relying only on static files.
+
+That is valuable for:
+
+- ranked context retrieval
+- collaboration board views
+- write flows such as runtime notes
+- scoped activity retrieval
+
+## 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_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 |
+| `bclaw_get_agent_board` | Coordination snapshot |
+| `bclaw_list_plans` | Structured plan listing with CLI-equivalent filters |
+| `bclaw_list_claims` | Structured claim listing with CLI-equivalent filters |
+| `bclaw_list_agents` | Registered agent inventory, optionally with bounded reputation |
+| `bclaw_list_instructions` | Raw or resolved instruction listing |
+| `bclaw_list_candidates` | Pending or archived review queue listing |
+| `bclaw_search` | Full-text search across memory |
+
+## Recommended use
+
+Use MCP as the dynamic access path for:
+
+- 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
+
+Readable files still matter, but MCP gives a stronger path for dynamic state.
+
+## Practical layering
+
+| 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 |

package/docs/integrations/overview.md

@@ -0,0 +1,61 @@
+# 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
+
+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
+
+## Important principle
+
+Do not rely on a single point of contact.
+
+Agents are not perfectly reliable at following instructions every time.
+The strongest integrations combine:
+
+- instructions (static)
+- readable workspace state (file)
+- MCP or CLI access (dynamic)
+- repeated reminders in the workflow
+- optional hooks where supported
+
+## Getting the native file written 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
+```
+
+## Related pages
+
+- [agents.md](agents.md)
+- [mcp.md](mcp.md)
+- [copilot.md](copilot.md)
+- [cursor.md](cursor.md)
+- [claude-code.md](claude-code.md)
+- [codex.md](codex.md)

package/docs/mcp-schema-changelog.md

@@ -0,0 +1,108 @@
+# brainclaw MCP Schema Changelog
+
+This document tracks all breaking and notable changes to the brainclaw MCP server protocol.
+
+---
+
+## 0.6.0 (current)
+
+**Added**
+- `bclaw_get_capabilities` — list all registered project capabilities with optional filtering by category
+  - Returns array of capabilities with id, name, category, and tags
+  - Supports category filtering parameter
+- `bclaw_list_tools` — list all registered project tools with optional filtering by type
+  - Returns array of tools with id, name, type, and tags
+  - Supports type and tag filtering parameters
+- `bclaw_search_tools` — full-text search across project tools
+  - Filters by query string, type, and tags
+  - Returns matching tools with detailed metadata
+- Enhanced `bclaw_get_context` to include metadata discovery:
+  - New `available_capabilities` field in structured content (array of capability objects)
+  - New `available_tools` field in structured content (array of tool objects)
+  - Suggestions section in text output showing relevant capabilities and tools (up to 5 each)
+- Support for `category` and `outcome` fields in `bclaw_create_candidate`:
+  - 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
+
+**Changed**
+- MCP schema version bumped to 0.6.0 to reflect new metadata discovery capabilities
+
+---
+
+## 0.5.0
+
+**Added**
+- `bclaw_delete_memory` — delete a constraint, decision, or trap by ID (trusted trust required)
+  - Searches across store chain to locate item
+  - Supports deletion from any store level (local, repo, workspace, user)
+  - Returns `deleted_id`, `item_type`, `store_level` in response
+- `bclaw_update_memory` — update text/tags or move an item to a different store level (trusted trust required)
+  - Supports updating constraint, decision, or trap in-place
+  - `moveToStore` parameter enables moving items between levels (local → repo → workspace → user)
+  - Returns `updated_id`, `item_type`, `previous_store`, `new_store` in response
+- Doctor checks `scope_hygiene` and `cross_level_duplicates` — warn about machine-level items at project scope and potential duplicates across store levels
+
+**Changed**
+- `bclaw_get_context` and related tools now properly merge instructions from parent stores in the chain
+
+---
+
+## 0.4.0
+
+**Added**
+- `bclaw_create_plan` — create a plan item from an agent (contributor trust required)
+- `bclaw_update_plan` — update status, actual effort, priority, or assignee of a plan item
+- `bclaw_add_step` — add a sub-step to a plan item
+- `bclaw_complete_step` — mark a plan sub-step as done
+- All plan management tools return structured `plan_id`, `step_id`, `status`, `progress` fields
+
+**Fixed**
+- `bclaw_release_claim`: `planStatus` parameter was declared in the schema but not applied — now correctly updates the linked plan's status when provided
+
+---
+
+## 0.3.0
+
+**Added**
+- `initialize` handshake support (MCP protocol conformance)
+- `schema_version: "0.3.0"` field in all `structuredContent` responses
+- Write tools: `bclaw_write_note`, `bclaw_create_candidate`, `bclaw_accept`, `bclaw_reject`, `bclaw_claim`, `bclaw_release_claim`, `bclaw_session_start`, `bclaw_session_end`
+- `bclaw_search` tool — full-text BM25 search across all memory items
+- Trust-level access control on write tools (contributor / trusted / curator)
+- `context_schema` field in `bclaw_get_context` structured responses
+- Explicit identity arguments on mutation tools:
+  - `agentId` on `bclaw_write_note`, `bclaw_create_candidate`, `bclaw_claim`, `bclaw_session_start`, `bclaw_session_end`
+  - `byId` on `bclaw_accept`, `bclaw_reject`
+- Stable MCP tool errors:
+  - `identity_error`
+  - `trust_error`
+  - `validation_error`
+
+**Changed**
+- All read tool responses now include `schema_version` in `structuredContent`
+- `bclaw_get_context` `structuredContent` flattens the full `ContextResult` object
+- `bclaw_get_context` now exposes `context_schema: "1.2"` and additive fields from the current public context contract
+- Mutation tools now require a registered identity on write paths; `agent`/`agentId` and `by`/`byId` must resolve to the same registered identity when both are provided
+- `bclaw_reject` is now restricted to `trusted` / `curator` agents, aligned with `bclaw_accept`
+
+---
+
+## 0.2.0
+
+**Added**
+- `bclaw_get_agent_board` read tool
+- `bclaw_read_handoff` read tool
+- Tool prefix renamed: `tmem_` → `bclaw_`
+
+**Changed**
+- Environment variables renamed: `TEAM_MEMORY_*` → `BRAINCLAW_*`
+- Storage directory renamed: `.memory/` → `.brainclaw/`
+
+---
+
+## 0.1.0
+
+**Initial**
+- `bclaw_get_context` read tool (was `tmem_get_context`)
+- Basic stdio NDJSON transport

package/docs/product/positioning.md

@@ -0,0 +1,97 @@
+# 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
+
+## Licensing
+
+brainclaw is published under the **Business Source License 1.1 (BSL 1.1)**.
+
+### What this means in practice
+
+| 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 |
+
+### Why BSL instead of MIT
+
+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.
+
+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.
+
+### Conversion to MIT
+
+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.
+
+## Positioning summary
+
+> A local-first coordination layer for humans and coding agents.

package/docs/quickstart.md

@@ -0,0 +1,99 @@
+# 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
+
+```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.
+
+## 2. Capture the first important facts
+
+```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
+```
+
+These become part of the shared project memory.
+
+## 3. Create a shared plan
+
+```bash
+brainclaw plan create "Coordinate auth rollout" --priority high
+brainclaw plan list
+```
+
+## 4. Claim work before editing
+
+```bash
+brainclaw claim create "Taking auth rollout" --agent copilot --scope src/auth/ --plan pln_001
+brainclaw claim list --plan pln_001
+```
+
+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
+
+```bash
+brainclaw memory create handoff "Review auth patch" --from copilot --to claude --plan pln_001
+```
+
+## 6. Generate context for an agent
+
+```bash
+brainclaw context --for src/auth/routes.ts --digest
+brainclaw context --json --max-chars 1200
+```
+
+Use this to prepare compact context before edits or reviews.
+
+## 7. Export to your agent's native instruction file
+
+```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
+```
+
+## 8. Inspect the current board
+
+```bash
+brainclaw status
+brainclaw agent-board --agent copilot
+```
+
+## 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
+
+## Next reads
+
+- [cli.md](cli.md) — full command reference
+- [concepts/memory.md](concepts/memory.md)
+- [concepts/plans-and-claims.md](concepts/plans-and-claims.md)
+- [integrations/overview.md](integrations/overview.md)

package/docs/reputation.md

@@ -0,0 +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.

package/docs/review.md

@@ -0,0 +1,43 @@
+# Review and Reflection
+
+brainclaw includes a reflective layer so not every observation has to become canonical memory immediately.
+
+## Why this exists
+
+Some facts are:
+
+- durable and worth keeping
+- useful but still uncertain
+- too local or too temporary to promote immediately
+
+A review layer helps filter and promote the right items.
+
+## Typical flow
+
+```
+runtime-note → reflect-runtime-note → review candidate → accept / reject
+```
+
+1. capture a runtime note (`brainclaw runtime-note`)
+2. reflect it into a candidate when useful (`brainclaw reflect-runtime-note`)
+3. review the candidate (`brainclaw review`)
+4. accept or reject it (`brainclaw accept` / `brainclaw reject`)
+
+## Star and use signals
+
+Before formal review, candidates can accumulate signals:
+
+```bash
+brainclaw star-candidate cnd_001 --by copilot    # passive interest
+brainclaw use-candidate cnd_001 --by copilot --context "auth rollout"  # active reuse
+```
+
+`review --prioritized` uses these signals (along with freshness and semantic relevance) to surface the most important candidates.
+
+## curator role
+
+The `curator` trust level has direct promote access. Other roles create candidates for review.
+
+## Why this is valuable
+
+This keeps canonical memory cleaner while still preserving useful observations long enough to evaluate them.

package/docs/security.md

@@ -0,0 +1,53 @@
+# Security
+
+brainclaw is designed to be safe by default.
+
+## Security model
+
+### No network access
+The CLI does not need to call external services to function.
+
+### No telemetry
+brainclaw does not collect or send usage data.
+
+### No secret management
+brainclaw is not a vault and should not be treated like one.
+
+### Plain-text visibility
+The storage model is intentionally inspectable.
+That makes review easier, but it also means users must be careful about what they write and commit.
+
+## Built-in safety behaviors
+
+brainclaw warns when content appears sensitive, for example when text includes patterns such as:
+
+- `api_key`
+- `secret`
+- `token`
+- `password`
+
+It can also warn about sensitive paths such as:
+
+- `.env`
+- `secrets/`
+
+Redaction behavior is configurable in `config.yaml`:
+
+```yaml
+security:
+  mode: warn               # 'warn' or 'strict'
+  strict_redaction: false  # if true, blocks entries with sensitive content
+  block_sensitive_paths: true
+```
+
+## Recommended stance
+
+- do not store secrets
+- review what gets committed
+- keep machine-local observations machine-local when appropriate
+- use stricter redaction settings in sensitive environments
+
+## Important nuance
+
+brainclaw reduces hidden behavior, but it does not remove the need for operational discipline.
+It warns; the team still decides what belongs in shared memory.

package/docs/storage.md

@@ -0,0 +1,81 @@
+# Storage Model
+
+brainclaw is local-first and workspace-centric.
+
+## Default structure
+
+```text
+.brainclaw/
+  project.md        ← Human & agent readable view (auto-generated)
+  config.yaml       ← Project configuration
+  instructions/     ← Layered shared instructions
+  plans/            ← Shared plan items
+  constraints/      ← Canonical constraint entries
+  decisions/        ← Canonical decision entries
+  traps/            ← Canonical trap entries
+  handoffs/         ← Canonical handoff entries
+```
+
+## Design principles
+
+### Canonical state is split
+Each entity is stored as its own JSON file.
+
+Benefits:
+
+- readable diffs
+- easier merges
+- clear provenance
+- straightforward automation
+- no giant monolithic memory blob
+
+### Human-readable view is generated
+`project.md` is regenerated from canonical state on every write.
+
+Benefits:
+
+- agents can read a simple file
+- humans get an inspectable summary
+- the source of truth remains structured
+
+### Topology can vary
+
+Depending on configuration, storage may be:
+
+| Topology | Behavior |
+|---|---|
+| `embedded` (default) | `.brainclaw/` inside the repo, tracked by Git |
+| `sidecar` | `.brainclaw/` inside the repo but gitignored |
+| `local-only` | Outside the repo, never tracked |
+
+## What belongs in canonical memory
+
+- decisions
+- constraints
+- traps
+- layered instructions
+- handoffs
+- plans
+
+## What may stay more operational
+
+- machine-local runtime notes
+- private notes
+- short-lived observations
+- reflective candidates awaiting review
+
+## Why this model matters
+
+The storage model is part of the product value:
+
+- local-first
+- inspectable
+- Git-friendly
+- reversible
+- suitable for both humans and agents
+
+## Related pages
+
+- [concepts/memory.md](concepts/memory.md)
+- [concepts/runtime-notes.md](concepts/runtime-notes.md)
+- [security.md](security.md)