brainclaw 1.8.0 → 1.9.1

package/docs/playbooks/integration/index.md

@@ -1,121 +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.
+# 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/orchestration.md

@@ -0,0 +1,37 @@
+# Asynchronous Orchestrator Playbook
+
+This playbook is designed for Manager/Dispatcher AI Agents steering multi-agent projects using Brainclaw. It provides a structured approach to managing complex, asynchronous workflows, ensuring efficient delegation, execution, and review across multiple agents.
+
+## Step 1: Create a Plan
+
+Before delegating any work, establish a clear and actionable formulation of the required tasks.
+
+- Define a top-level Plan using the canonical `bclaw_create(entity="plan", data={…})` tool. (`bclaw_work` does not create plans — when none is active it returns a `nextActions` hint pointing to `bclaw_create`.)
+- Break down the overarching project goal into manageable sub-steps using the `bclaw_add_step` tool.
+- Ensure that each step has a clear description, expected outcome, and (optionally) an estimated effort. A well-defined plan acts as the ground truth for downstream agents.
+
+## Step 2: Create Sequences for Parallel Work Lanes
+
+When tasks are independent or can be parallelized, organize the plan steps into sequences to maximize throughput.
+
+- Use the `bclaw_create_sequence` tool to map steps into sequence lanes.
+- Define `hard_after` dependencies if certain steps strictly require others to complete first, or `soft_after` for advisory ordering.
+- Grouping tasks into distinct lanes ensures execution agents run in parallel safely and are not unnecessarily blocked.
+
+## Step 3: Dispatch Work
+
+With the plan and sequences established, assign the work to execution agents.
+
+- **Sequence-driven execution:** Use `bclaw_dispatch(intent="execute")` to parallelize plans across your defined sequence lanes automatically.
+- **Direct orchestration:** For ad-hoc delegation, use `bclaw_coordinate(intent="assign")` to assign specific tasks to target agents. This seamlessly generates the necessary claims and dispatch briefs.
+- **Reviews & Loops:** To open a structured review process on completed work, use `bclaw_coordinate(intent="review", open_loop=true)`.
+- Use `bclaw_dispatch_status` to verify worker liveness, examine log tails, and ensure dispatches are progressing healthily.
+
+## Step 4: Manage the Inbox
+
+As downstream execution agents interact with their assignments, they will emit statuses, request reviews, or supply handoffs back to the orchestrator.
+
+- Routinely call `bclaw_read_inbox` to fetch incoming messages, status updates, and peer requests.
+- Acknowledge received messages using `bclaw_ack_message` after processing to keep the inbox clean.
+- Review handoffs and lifecycle events, transitioning the overarching plan steps (e.g., utilizing `bclaw_complete_step`) once execution meets the expected criteria.
+- If an agent is blocked, read their action required prompts from the inbox and respond utilizing `bclaw_assignment_action` or by steering them in a new direction.

package/docs/playbooks/productivity/index.md

@@ -1,102 +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.
-
+# 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 still no focused `brainclaw repair-init` path. Re-running `brainclaw init` is now a safe upsert for existing projects, and `--force` rebuilds the managed setup from defaults while preserving canonical memory, but `bclaw_doctor` still 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.
+
+### 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.