brainclaw 0.29.2 → 1.5.3

package/docs/integrations/roo.md

@@ -0,0 +1,74 @@
+# Roo Integration
+
+brainclaw integrates with Roo through MCP tools and project-scoped rules, providing shared memory, plans, and multi-agent coordination.
+
+## Auto-setup
+
+`brainclaw init` detects Roo and writes `.roo/rules/brainclaw.md` automatically. Or manually:
+
+```bash
+brainclaw export --format roo-rules --write
+```
+
+## MCP configuration
+
+Roo reads MCP servers from `.roo/mcp.json` (project-scoped) or the global `mcp_settings.json`. Add brainclaw:
+
+```json
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
+    }
+  }
+}
+```
+
+## Permissions
+
+Roo supports per-server auto-approval via `alwaysAllow` array, plus a global toggle:
+
+```json
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"],
+      "alwaysAllow": ["bclaw_context", "bclaw_work", "bclaw_find", "bclaw_get"]
+    }
+  }
+}
+```
+
+brainclaw emits `alwaysAllow` with all known tool names during setup.
+
+## Instruction files
+
+- `.roo/instructions.md` — global instructions (Roo reads at session start)
+- `.roo/rules/` — rule files, equivalent to `.clinerules/`
+- `.rooignore` — file-level ignore patterns (respects `.gitignore` syntax)
+
+Roo also supports mode-specific rules and skills (e.g., `skills-code/`, `skills-architect/`).
+
+## SKILL.md discovery
+
+Roo auto-discovers skills from `.roo/skills/`, `.agents/skills/`, and `.claude/skills/`. A single `.agents/skills/brainclaw/SKILL.md` is picked up automatically.
+
+## Headless invocation
+
+Roo headless is available via Cloud Agents only (no local CLI headless mode).
+
+## Invoke template
+
+```
+# From within VS Code with Roo extension
+# Use -y flag for auto-approve in supported contexts
+```
+
+## Caveats
+
+- **No hooks**: Hook support is proposed but unreleased as of April 2026.
+- **No local headless CLI**: Headless dispatch requires Roo Cloud Agents.
+- **Cline family**: Roo is a Cline fork — config patterns are similar but paths differ (`.roo/` vs `.cline/`).
+- **Windows/Linux**: Works via VS Code extension on all platforms.

package/docs/integrations/windsurf.md

@@ -0,0 +1,83 @@
+# Windsurf Integration
+
+brainclaw integrates with Windsurf through MCP tools and instruction rules, providing shared memory, plans, and coordination state to Cascade.
+
+## Auto-setup
+
+`brainclaw init` detects Windsurf and writes `.windsurfrules` automatically. Or manually:
+
+```bash
+brainclaw export --format windsurfrules --write
+```
+
+## MCP configuration
+
+Windsurf reads MCP servers from a **machine-scoped** config file:
+
+```
+~/.codeium/windsurf/mcp_config.json
+```
+
+Add brainclaw:
+
+```json
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
+    }
+  }
+}
+```
+
+Note: this is a global config — it applies to all Windsurf projects on the machine.
+
+## Permissions
+
+Windsurf supports `alwaysAllow` as an array on each MCP server entry:
+
+```json
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"],
+      "alwaysAllow": ["bclaw_context", "bclaw_work", "bclaw_find", "bclaw_get"]
+    }
+  }
+}
+```
+
+brainclaw does not yet emit `alwaysAllow` for Windsurf automatically.
+
+## Instruction files
+
+- `.windsurf/rules/*.md` — modern format (recommended), multiple rule files
+- `.windsurfrules` — legacy single-file format (still supported)
+
+brainclaw currently emits the legacy format. Modern `.windsurf/rules/` support is planned.
+
+## SKILL.md discovery
+
+Windsurf uses `.windsurf/workflows/*.md` for slash-command workflows (12k char max). It does not auto-discover `.agents/skills/`. Skills must be wired as workflows manually.
+
+## Headless invocation
+
+Windsurf does not offer a headless CLI. It runs as a Docker-based environment — no `-p` flag equivalent.
+
+## Invoke template
+
+```
+# Windsurf is GUI-only — no CLI invoke
+# Use within the Windsurf IDE (Cascade panel)
+```
+
+## Caveats
+
+- **Machine-scoped MCP**: The config at `~/.codeium/windsurf/mcp_config.json` is global, not per-project. All projects share the same server list.
+- **No hooks**: Cascade Hooks exist but are limited to logging — no pre-prompt injection.
+- **Legacy format**: brainclaw currently writes `.windsurfrules` (single file). Modern `.windsurf/rules/` multi-file support is planned (P5).
+- **No headless**: Cannot be used as a brainclaw dispatch target.
+- **Plan Mode**: Windsurf's "megaplan" mode is separate from brainclaw plans — they don't conflict but don't interoperate.
+- **Windows/Linux**: Works on all platforms via the Windsurf IDE.

package/docs/mcp-schema-changelog.md

@@ -2,9 +2,199 @@
 
 This document tracks all breaking and notable changes to the brainclaw MCP server protocol.
 
+See [docs/concepts/mcp-governance.md](concepts/mcp-governance.md) for the
+versioning rules, breaking-change policy, deprecation window, and tier
+guarantees this changelog follows.
+
+---
+
+## Unreleased
+
+**Changed — JSON Schema generation shift (pln#486, zod 4 migration)**
+- Migration from zod 3.24 → 4.3.6 changes the introspection output that
+  feeds `tools/list`. Schemas are semantically equivalent but the emitted
+  JSON differs in incidental shape (key order, optional-property
+  encoding). MCP clients that snapshot or hash schemas should re-pin.
+- Public surface fingerprint moves from `sha256:a479f710ff043ef6` (zod 3)
+  to `sha256:860fbaa30a486093` (zod 4). No tool was added, removed,
+  renamed, or had its required arguments change.
+
+**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
+- New optional field `allow_orphan: boolean` on `BclawLoopOpenSchema`.
+- Default (absent / `false`) — handler rejects with `validation_error`
+  and points to `bclaw_coordinate(intent: 'review', open_loop: true)`
+  as the recommended path. Prevents the "loop opened without
+  dispatch → no claim, no inbox, no agent picks it up" trap called
+  out in `CLAUDE.md`.
+- `allow_orphan: true` — explicit acknowledgement that the caller
+  will drive `turn()` + dispatch manually (advanced / test use only).
+- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
+  affected — they bypass `handleBclawLoop` and invoke the core
+  `openLoop()` directly.
+
+---
+
+## 1.0.0 (current)
+
+**Public launch candidate.** Phase 3 slice 3i of `pln_c6472192`.
+Completes the canonical grammar refactor: canonical verbs promoted to
+the default `standard` tier, legacy per-entity tools removed from the
+discoverable surface.
+
+**Changed — tier promotion**
+All canonical verbs land in the default `standard` catalog:
+- `bclaw_find`, `bclaw_get`, `bclaw_create`, `bclaw_update`,
+  `bclaw_remove`, `bclaw_transition`
+- `bclaw_context(kind)` — memory / execution / board / board_summary / delta
+- `bclaw_dispatch(intent)` — analysis / execute / review
+- `bclaw_correct_handoff` — P6.1 tombstone for handoff corrections
+
+**Breaking — legacy per-entity tools removed from the catalog**
+The following tools are no longer returned by `tools/list` default or
+`catalog: "standard"`. They were marked deprecated throughout the
+0.8.x window. Replacement is named in parentheses:
+
+- `bclaw_list_plans` (→ `bclaw_find(entity: "plan")`)
+- `bclaw_list_candidates` (→ `bclaw_find(entity: "candidate")`)
+- `bclaw_list_claims` (→ `bclaw_find(entity: "claim")`)
+- `bclaw_list_actions` (→ `bclaw_find(entity: "action")`)
+- `bclaw_list_assignments` (→ `bclaw_find(entity: "assignment")`)
+- `bclaw_list_runs` (→ `bclaw_find(entity: "agent_run")`)
+- `bclaw_read_handoff` (→ `bclaw_get(entity: "handoff", id)`)
+- `bclaw_create_plan` / `bclaw_create_candidate` (→ `bclaw_create`)
+- `bclaw_update_plan` (→ `bclaw_update` + `bclaw_transition`)
+- `bclaw_accept` / `bclaw_reject` (→ `bclaw_transition(entity: "candidate")`)
+- `bclaw_get_execution_context` / `bclaw_get_agent_board` /
+  `bclaw_get_agent_board_summary` (→ `bclaw_context(kind)`)
+- `bclaw_dispatch_analysis` / `bclaw_dispatch_review` (→ `bclaw_dispatch(intent)`)
+- `bclaw_update_handoff` (→ `bclaw_correct_handoff` — P6.1 tombstone)
+
+The tool *handlers* remain in place for now as defensive code — a
+direct call by a non-MCP-compliant caller that bypasses `tools/list`
+will still succeed. A follow-up PR will strip the dead handler code.
+
+**Changed — versions**
+- `SCHEMA_VERSION` bump: `0.8.0 → 1.0.0`
+- `package.json` bump: `0.63.0 → 1.0.0`
+
+**Changed — governance guard**
+- `tests/unit/mcp-governance.test.ts` now checks that the current
+  changelog records the published MCP surface fingerprint. When a tool
+  name, tier, category, or input schema changes, the test fails until
+  this section is updated.
+- MCP public surface fingerprint: `sha256:860fbaa30a486093`
+
+See `docs/integrations/mcp.md` for the full canonical surface + an
+example gallery per verb. See `docs/concepts/mcp-governance.md` for
+the stability contract now that v1.0 has shipped.
+
+---
+
+## 0.8.0
+
+Phase 3 canonical grammar slices shipped under `pln_c6472192` (slices
+3a–3g). Every addition is behind `catalog: "all"` until the v1.0 cut
+(slice 3i) promotes the new verbs to the default catalog and removes
+the deprecated surface.
+
+**Added (canonical CRUD verbs)**
+- `bclaw_find(entity, filter?)` — list query with default provenance
+  filter (excludes `legacy` + `auto_reflect < 0.6`; override via
+  `filter.includeLegacy` / `filter.minAutoReflectConfidence`).
+- `bclaw_get(entity, id)` — fetch by id or short_label.
+- `bclaw_create(entity, data)` — auto-stamps provenance (kind: user
+  by default).
+- `bclaw_update(entity, id, patch)` — rejects non-updatable fields
+  per EntityRegistry.
+- `bclaw_remove(entity, id, purge?)` — archive (default) or purge.
+- `bclaw_transition(entity, id, to, reason?)` — validated against
+  declarative transition matrix; returns side-effect tags.
+
+**Added (unified intent dispatchers)**
+- `bclaw_context(kind)` — unifies `bclaw_get_context` /
+  `_execution_context` / `_agent_board` / `_agent_board_summary`.
+  Adds `kind: "delta", since: <session_id>` for memory diffs (P6.4).
+- `bclaw_dispatch(intent)` — intent discriminator over the existing
+  bclaw_dispatch tool. `analysis` / `execute` (default, legacy) /
+  `review` (with openLoop + reviewMode).
+- `bclaw_correct_handoff(originalId, ...)` — P6.1 tombstone pattern.
+  Writes a correction handoff with `supersedes` / `superseded_by`
+  pointers; refuses to supersede already-superseded or closed
+  handoffs.
+
+**Added (schema)**
+- `Provenance` discriminated union: agent / auto_reflect / user /
+  loop_artifact / federation / correction / legacy. Exported from
+  `src/core/schema.ts`. Stamped on creates; federation-safe.
+- `Handoff.superseded_by` and `Handoff.supersedes` — P6.1 tombstone
+  pointers, optional passthrough.
+
+**Deprecated (19 tools)**
+All redirects are non-breaking (old tools still work until slice 3i
+removal). Warnings surface on every call through the
+`executeMcpToolCall` exit wrapper:
+- `bclaw_list_plans/candidates/claims/actions/assignments/runs` →
+  `bclaw_find(entity, filter)`
+- `bclaw_read_handoff` → `bclaw_get(entity: "handoff", id)`
+- `bclaw_create_plan/candidate` → `bclaw_create`
+- `bclaw_update_plan` → `bclaw_update` / `bclaw_transition`
+- `bclaw_accept/reject` → `bclaw_transition(entity: "candidate")`
+- `bclaw_get_execution_context/_agent_board/_agent_board_summary` →
+  `bclaw_context(kind)`
+- `bclaw_dispatch_analysis/_review` → `bclaw_dispatch(intent)`
+- `bclaw_update_handoff` → `bclaw_correct_handoff` (P6.1)
+
+---
+
+## 0.7.0
+
+Shipped in brainclaw app `0.63.0`. Consolidates the surface listed
+below — previously accumulating under an inaccurate `SCHEMA_VERSION = '0.6.0'`
+constant — and brings the runtime value in line with the documented
+state. Governance cross-check now passes (see governance doc).
+
+**Added (this landing)**
+- `bclaw_doctor --after-migration` — post-v1-upgrade health check
+  reporting one finding per invariant (provenance coverage, handoff
+  review-strip, candidate archive, schema-version marker). Exits
+  non-zero on any failure.
+- `brainclaw upgrade --to=1.0` — one-shot v1 schema migration
+  covering candidate archive (P6.6), handoff review-strip (P6.1
+  groundwork), provenance rollout (P6.3), schema-version bump
+  (0.6.0 → 0.8.0 in the store marker). Plus `--backup` /
+  `--no-backup` / `--rollback` flags.
+- `provenance` optional passthrough field on Decision, Constraint,
+  Trap, Handoff, RuntimeNote — discriminated-union typing lands in
+  Phase 3 (`pln_c6472192 / 3f`). The declaration lets migration
+  patches stamp `{ kind: 'legacy' }` without Zod stripping it on
+  persist.
+
+**Added (previously unreleased 0.7.0 surface)**
+- `bclaw_check_policy` — pre-execution governance check for a scope
+  - Input: `scope` (required), `agent`, `agentId`, `action`
+  - Returns `allowed` boolean, `blocks[]` (hard stops), `warnings[]` (context)
+  - Checks: claim active, claim conflict, constraint matching, trap matching
+  - Returns `governance_context` with active instructions count, matching items
+- `bclaw_audit` now supports `governance: true` parameter
+  - Returns aggregated posture report instead of chronological log
+  - Includes: constitution (global instructions), red lines (constraints by category), claims by agent, open traps by severity, mutations without claim, recommendations
+  - Supports `scope` filter for governance mode
+- `bclaw_claim` response now includes automatic policy warnings
+  - Constraints and traps matching the claimed scope are surfaced as warnings
+  - No extra call needed — governance context is provided at claim time
+- Enriched `AuditEntry` fields: `scope`, `session_id`, `host_id`
+  - Claim/release entries include the scope being claimed
+  - Session start/end entries include session and host IDs
+  - `promote_direct` and `trust_change` actions now propagated to events.jsonl
+
+**Changed**
+- MCP schema version bumped to 0.7.0
+- Governance report filters machine/private traps — only shared-visibility traps affect project posture
+- Audit chronological mode now shows `scope` field for claim actions
+
 ---
 
-## 0.6.0 (current)
+## 0.6.0
 
 **Added**
 - `bclaw_get_capabilities` — list all registered project capabilities with optional filtering by category

package/docs/playbooks/integration/index.md

@@ -0,0 +1,121 @@
+# Audience: AI Builders
+
+Design constraints for agents developing brainclaw features that serve agent integrators, tool builders, and enterprise AI governance teams.
+
+## Profiles
+
+### Agent Integrators
+Developers building new coding agents, CLI wrappers, or AI-powered tools who want to leverage brainclaw's memory and coordination instead of building their own.
+
+### Enterprise AI Governance
+IT and compliance teams who manage organizational policies across many AI agents on developer desktops. They need transparency, auditability, and control.
+
+## Design Constraints
+
+These rules apply to any feature that touches this audience:
+
+1. **MCP is the integration contract.** External tools integrate through MCP (~60 published tools today; the canonical grammar — `bclaw_work`, `bclaw_context`, `bclaw_find/get/create/update/remove/transition` plus the multi-agent facades — is the stable surface), not by reading `.brainclaw/` files directly. The file-based store is an internal implementation detail. If an integration need cannot be met through MCP, the gap is a bug, not a reason to expose internals.
+
+2. **The MCP schema is a public API.** Breaking changes to tool signatures, context format, or response shapes require versioning and changelog entries (`docs/context-format-changelog.md`, `docs/mcp-schema-changelog.md`). Integrators depend on stability — every schema change has downstream cost. The context schema is versioned (`context_schema` field in every response).
+
+3. **Agent capability profiles must be factual.** The 3-tier system (A/B/C) in `agent-capability.ts` defines per-agent: MCP support, hooks, auto-approve, skills, instruction file path, invoke templates, role capabilities (execute/coordinate/review/consult), and delivery methods (inline_arg, temp_file, stdin_pipe, inbox_structured). Profiles can degrade at runtime (`agent-integrations.ts` assesses declared vs present surfaces) — Tier A can drop to B if hooks are missing, B to C if MCP is absent.
+
+4. **Security boundaries are non-negotiable.** brainclaw operates in the user's local filesystem. It must never expose file contents, memory, or coordination state beyond the project scope. Cross-project leakage is a security bug. The policy system (`bclaw_check_policy`) enforces boundaries with glob-based scope matching. `bclaw_check_security` provides supply chain risk scoring via Socket.dev for npm/pip packages.
+
+5. **Audit must be passive and complete.** Governance teams should not need to configure anything. The audit system (`audit.ts`) logs 30+ action types in JSONL with auto-rotation (10MB), captures actor/action/before-after/scope/session_id/host_id. The governance posture report (`bclaw_audit`) aggregates into constitution, red-lines, claim activity, and structured recommendations.
+
+6. **Integration must not require brainclaw-specific agent code.** The ideal integration is: add MCP server config, the agent discovers tools, the agent uses them. The facades (`bclaw_work`, `bclaw_coordinate`) simplify the MCP surface to 2 entry points for agents that don't need granular access.
+
+## Anti-Patterns
+
+- Exposing `.brainclaw/` file structure as a stable interface (it is internal)
+- Breaking MCP tool signatures without versioning
+- Hardcoding agent-specific behavior in core brainclaw (use capability profiles instead)
+- Storing sensitive data (tokens, credentials) in brainclaw memory or state
+- Requiring agent-side code changes to use brainclaw (beyond MCP config)
+- Shipping capability profiles that overstate what an agent can actually do
+- Ignoring tier degradation — if an agent's surfaces drift, the effective tier must reflect reality
+
+## Key Features for This Audience
+
+### MCP Surface (primary integration point)
+- MCP server (`brainclaw mcp`) — ~60 published tools over stdio (canonical grammar in the default catalog; the full advanced catalog available via `tools/list { catalog: "all" }`)
+- `bclaw_work(intent)` — entry facade: session + context + claim in one call (returns a compact payload by default to stay under MCP token caps)
+- `bclaw_context(kind)` — unified context read: `memory` / `execution` / `board` / `board_summary` / `delta`
+- `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` — canonical CRUD across all entities
+- `bclaw_coordinate(intent)` / `bclaw_dispatch(intent)` / `bclaw_loop(intent)` — multi-agent facades for assign / review / reroute / parallel execute / multi-turn loops
+- Context format contract versioned via `context_schema` field
+
+### Agent Detection & Configuration
+- Auto-detection via env vars (`ai-agent-detection.ts`): BRAINCLAW_AGENT, CLAUDE_CODE_VERSION, CURSOR_*, WINDSURF_*, CLINE_*, GITHUB_COPILOT_PRODUCT, home dir checks for 10+ agents
+- AI surface inventory (`ai-surface-inventory.ts`): detects desktop apps, web surfaces, CLI agents with status (not_detected → brainclaw_ready) and capability flags (supports_mcp, remote_connectors, context_export, etc.)
+- 3-tier capability system with runtime degradation assessment
+- 14+ agent profiles with per-agent invoke templates and role capabilities
+- `bclaw_get_discovery` — scan workspace for MCP configs, skills, hooks, integrations
+- `bclaw_context(kind="execution")` — platform, shell, git, toolchains, env signals snapshot
+
+### Agent Profiles (reusable invocation templates)
+- YAML profiles in `default-profiles/`: doctor, janitor, onboarder, reviewer
+- Per-profile: trust_level, trigger (manual/auto), prompt template, invoke command
+- User profiles override defaults; loaded via agent-profiles API
+- `brainclaw run [profile-name]` — execute a profile
+
+### Security & Governance
+- `bclaw_check_policy` — pre-execution scope compliance with glob matching
+- `bclaw_check_security` — supply chain risk scoring via Socket.dev (pass/warn/block per package)
+- `bclaw_audit` — governance posture report with structured recommendations
+- `bclaw_history` — full mutation history per item with before/after snapshots
+- Lifecycle trigger tags (`trigger:post-claim`, `trigger:pre-session-end`) for event-driven constraints
+
+### Cross-Project Federation
+- Signal entities only: candidate, handoff, runtime_note (execution stays local)
+- Schema-versioned federation messages with from_project/from_agent/target_project metadata
+- Cycle detection (A→B→A prevention)
+- CLI: `brainclaw federation push/pull/status`
+- Inbox directory pattern: `coordination/inbox/cross-project/`
+
+### Versioning & Contracts
+- Context format: `docs/context-format.md` + `docs/context-format-changelog.md`
+- MCP schema: `docs/mcp-schema-changelog.md`
+- Document schemas with migration support (`schema.ts`, `migration.ts`)
+- `bclaw_release_notes` — agent-first release notes with breaking risk assessment
+
+## Known Gaps
+
+Features this audience would naturally expect but that are not yet implemented:
+
+### No plugin/extension system
+Tools added via `bclaw_add_tool` are metadata-only — they don't become callable MCP tools. There is no way for third parties to register executable MCP extensions, custom memory store backends, custom validators, or export format plugins without modifying brainclaw core. The architecture is monolithic.
+**Impact:** Integrators must fork brainclaw to add domain-specific functionality.
+
+### No tool-level API versioning or deprecation
+MCP protocol version exists (`2025-11-25` in `mcp.ts`), but individual tools have no version annotations. No compatibility negotiation ("client supports bclaw_work v2, server has v1.5"), no deprecation lifecycle (added/deprecated/removed dates), no feature flags for experimental tools.
+**Impact:** Integrators discover breaking changes at runtime, not at integration time.
+
+### No real-time event streaming
+The event log (`event-log.ts`) supports cursor-based polling but there are no WebSocket, SSE, or pub/sub subscriptions. Agents must poll every N seconds to discover changes. No event filtering ("only claim events from agent X").
+**Impact:** Integrators building real-time dashboards or reactive agents must build their own polling + change detection.
+
+### No rate limiting or quota enforcement
+No throttling or per-agent call budgets anywhere in the MCP handler path. `circuit-breaker.ts` exists but is unused. LLM-invoking tools (`bclaw_compact`, plus legacy experimental `codev` when enabled) have no usage limits. Agents can make unlimited calls.
+**Impact:** A misbehaving agent can overwhelm the store or run up LLM costs without any guardrail.
+
+### Memory type system is closed
+Fixed set of types: constraint, decision, trap, handoff, candidate, plan, sequence, runtime_note, instruction (`schema.ts`). Integrators cannot define custom types (e.g., "ProjectRisk", "DesignPattern") with custom fields. No type inheritance or middleware for custom validation.
+**Impact:** Domain-specific knowledge must be shoehorned into generic types or stored as untyped notes.
+
+### No multi-tenant isolation beyond project boundaries
+Isolation is project-directory level only. No team/department boundaries within a project, no role-based data visibility (all agents in a project see all memory), no data residency controls, no per-team audit segmentation.
+**Impact:** Enterprise teams sharing a monorepo cannot enforce internal boundaries through brainclaw.
+
+### Token/cost tracking exists but has no enforcement
+Usage tracking (`usage.ts`) records chars and estimated tokens per tool/agent, but there is no cost model ($/token), no quota enforcement ("agent X gets 100M tokens/month"), no cost alerts, no projected spend.
+**Impact:** Governance teams can see usage after the fact but cannot prevent overruns.
+
+### Tool discovery lacks trust/dependency introspection
+The default `tools/list` catalog is now curated around facades and daily runtime tools, and raw MCP clients can request the full registry, but there is still no trust-level annotation per tool and no tool dependency graph ("bclaw_dispatch requires active sequence"). Agents still need docs or source to understand tool preconditions.
+**Impact:** New agent integrations require trial-and-error to discover which tools work in their context.
+
+### No metrics MCP endpoint
+CLI metrics exist (`brainclaw metrics`, `brainclaw usage`, `brainclaw estimation-report`) but none are exposed as MCP tools. Agents cannot programmatically query coordination health or usage data through the standard integration surface.
+**Impact:** Governance dashboards must shell out to CLI instead of using the MCP contract.

package/docs/playbooks/productivity/index.md

@@ -0,0 +1,102 @@
+# Audience: End-Users & Solo Devs
+
+Design constraints for agents developing brainclaw features that serve end-users, solo developers, and power-users.
+
+## Profiles
+
+### Non-Tech Creators
+People who rely on AI agents to write code for them. They never open a terminal manually. They interact with brainclaw only through their agent.
+
+### Solo Developers
+Developers who code alongside their agent. They use one agent at a time, session after session, on the same project.
+
+### Power-Users
+Developers who orchestrate multiple agents on the same project. They use handoffs, plans, and claims to coordinate between agents.
+
+## Design Constraints
+
+These rules apply to any feature that touches this audience:
+
+1. **Every feature MUST have an agent-only path.** If a feature requires the user to type a CLI command, it must also be achievable through MCP or natural language instruction to the agent. The CLI is a fallback, not the default.
+
+2. **Zero-config is the baseline.** `brainclaw init` must produce a working setup without follow-up questions for simple projects. Sensible defaults over configuration dialogs.
+
+3. **Memory must survive sessions.** Any decision, constraint, or trap recorded in one session must be available in the next session without the user re-stating it. This is the core value proposition for solo devs.
+
+4. **Context must be prompt-sized.** End-users don't manage context windows. brainclaw must produce compact, relevant context that fits within agent limits without manual pruning. The 9 context profiles (dev, dense, compact, copilot, quick, briefing, openclaw, ops, research) exist for this — the right profile is selected automatically based on agent tier and session type.
+
+5. **Onboarding must be expressible in one sentence.** The install path is: user tells agent "install brainclaw and use it". If onboarding requires more steps, the feature is too complex for this audience. The auto-bootstrap (`bclaw_bootstrap`) handles brownfield scanning (README, docs, git history, existing agent files) and derives memory seeds without user input.
+
+6. **Handoffs must be seamless.** When a power-user switches from one agent to another, the next agent must pick up where the last one left off without the user re-explaining the current state. Context diff (`context-diff.ts`) shows exactly what changed since the last session so agents resume from delta, not from scratch.
+
+## Anti-Patterns
+
+- Adding CLI-only features with no MCP equivalent
+- Requiring manual file editing to configure brainclaw behavior
+- Producing context that exceeds prompt limits or requires the user to select what to include
+- Assuming the user understands brainclaw internals (store structure, export formats, tier model)
+- Breaking session continuity — any mutation that makes the next session start from scratch
+- Forcing the user to manually maintain memory — `bclaw_compact` (semantic deduplication) and `bclaw_quick_capture` (auto-classification) exist to reduce this friction
+
+## Key Features for This Audience
+
+### Session & Context (core loop)
+- `bclaw_work(intent)` — entry facade: session + context + claim in one call (compact payload by default to stay under MCP token caps; pass `compact: false` for the full memory dump)
+- `bclaw_session_start` / `bclaw_session_end` — explicit session lifecycle with auto-reflect (when finer control is needed)
+- `bclaw_context(kind)` — unified context read with profile selection (9 profiles): `memory` / `execution` / `board` / `board_summary` / `delta`
+- Context diff via `bclaw_context(kind="delta", since=…)` — incremental delta since the last session
+
+### Memory (persistence across sessions)
+- `bclaw_write_note` — persistent runtime observations
+- `bclaw_quick_capture` — free-form text auto-classified into decision/trap/note
+- `bclaw_search` — BM25 full-text search across all memory items
+- `bclaw_compact` — semantic deduplication with archive (never deletes)
+- Project memory types: constraints, decisions, traps, handoffs, layered instructions
+
+### Onboarding & Discovery
+- `brainclaw init` / `brainclaw setup` / `bclaw_setup` — onboarding path
+- `bclaw_bootstrap` — brownfield auto-scan with interview and profile caching
+- `bclaw_context(kind="execution")` — workspace detection, toolchains, git status
+- `bclaw_release_notes` — agent-first version notes (breaking risk, highlights)
+- Native agent file generation (CLAUDE.md, AGENTS.md, .cursor/rules/, .windsurfrules, GEMINI.md, etc.)
+
+### Multi-Agent Handoffs (power-users)
+- `bclaw_get(entity="handoff", id)` / `bclaw_update(entity="handoff", id, patch)` — structured agent transitions with git diff
+- `bclaw_create(entity="plan", data)` / `bclaw_update(entity="plan", id, patch)` / `bclaw_transition(entity="plan", id, to)` — shared work that survives agent switches
+- `bclaw_claim` / `bclaw_release_claim` — scope reservation before editing
+
+## Known Gaps
+
+Features this audience would naturally expect but that are not yet implemented:
+
+### Session continuity diff not auto-surfaced on start
+`bclaw_session_start` returns a full context snapshot but does not auto-include "here's what changed since your last session". The diff logic exists (`context-diff.ts`, `since_session` parameter) but the agent must explicitly request it via `bclaw_context(kind="delta", since=<sess_id>)`. For solo devs resuming next morning, the agent should get the delta automatically.
+**Impact:** Solo devs re-read stale context instead of focusing on what changed.
+
+### No fuzzy search or typo tolerance
+`bclaw_search` uses BM25 with exact tokenization only (`search.ts`). No Levenshtein distance, no prefix matching, no "did you mean?" suggestions. Searching "postgre" when the memory says "PostgreSQL" returns nothing.
+**Impact:** Non-tech creators who can't spell technical terms get zero results.
+
+### Memory accumulates with no staleness management
+Traps have `expires_at` and `status` fields (`traps.ts`), and `bclaw_doctor` lists expired items, but there is no auto-expiry workflow. No staleness warnings ("this constraint hasn't been reviewed in 90 days"), no "mark as resolved" flow that archives instead of deletes. Memory grows until manual cleanup via `bclaw_compact` or `bclaw_delete_memory`.
+**Impact:** After months of use, context becomes noisy with obsolete items.
+
+### No context weight personalization
+Context profiles are hardcoded in `context.ts` with fixed section weights (plans +4, handoffs +3, decisions/traps +2 in dense mode). There is no per-user or per-agent configuration to say "show me more traps, fewer plans" or "pin this item to always appear".
+**Impact:** One-size-fits-all context may miss what matters most to a specific user.
+
+### No undo beyond single-item rollback
+`rollback.ts` can revert a single item to its previous state via audit snapshots, but there is no batch undo ("undo all changes from session X"), no point-in-time restore, no "undo last 5 edits" convenience.
+**Impact:** If an agent writes bad memory, cleanup is manual and item-by-item.
+
+### No init repair path
+If `brainclaw init` partially fails or produces a bad config, there is no `brainclaw repair` command. Re-init requires `--force` which risks destroying existing memory. `bclaw_doctor` checks for issues but auto-repairs very little.
+**Impact:** Corrupted setups require manual intervention that non-tech creators cannot do.
+
+### Cross-project learning is manual only
+Projects are siloed. Federation exists (`federation-transport.ts`) but requires explicit config and manual push/pull. There is no auto-detection of common learnings across projects (e.g., "3 projects use React, here are shared patterns"). No cross-project search.
+**Impact:** Solo devs working on multiple repos re-discover the same constraints.
+
+### Quick capture is keyword-heuristic only
+`bclaw_quick_capture` uses keyword heuristics, not LLM inference. An agent cannot say "remember that we decided to use PostgreSQL" and have it auto-classified as a decision with confidence scoring.
+**Impact:** Agents must use structured MCP calls with explicit type parameters instead of natural language.