brainclaw 0.29.2 → 1.5.4

package/docs/product/entity-model-audit.md

@@ -0,0 +1,462 @@
+# Entity model audit — pre-v1.0 strategic reflection
+
+Captured 2026-04-18 during a second round of strategic review before
+the MCP grammar Phase 3 refactor. This document complements
+`docs/product/agent-first-model.md` (which defines the two-layer
+product model) and should be read before any entity-shape or API-verb
+decision.
+
+## Context
+
+brainclaw has grown organically over months and some older concepts
+deserve challenge before the public launch:
+
+- The MCP surface has 70 tools, 26 dedicated to CRUD variants per
+  entity type.
+- Some lifecycles (candidate review queue) are rarely used as designed.
+- Some entities overlap in role (runtime_note vs decision-candidate,
+  capability vs tool).
+- The upcoming API grammar refactor (Phase 3 in the broader plan)
+  will bake current entity shapes into permanent verbs. Cleaning the
+  model first avoids fossilising bad decisions.
+
+Since brainclaw is not yet publicly distributed, backward compatibility
+is not a blocker — the priority is internal coherence at v1.0 launch.
+
+## Design principles that emerged
+
+### P1 — Engine delivers value, cockpit sells adoption
+See `agent-first-model.md`. Every engine feature should emit
+machine-readable signals the cockpit can consume. Human visibility is
+a critical adoption gate at enterprise scale, not optional.
+
+### P2 — Three review modes must coexist without penalty
+brainclaw must support three review intensities and let the agent
+choose consciously:
+
+| Mode | When | Cost | Entry point today |
+|---|---|---|---|
+| Self-review inline | Solo default path (~70% of sessions) | Few LLM cycles | No brainclaw tool, agent self-checks |
+| Dispatch-review | When a second opinion is worth a round-trip | One inbox message + reply | `bclaw_dispatch_review(openLoop: false)` |
+| Review loop | Quality bar high, multi-round likely, structured feedback needed | Multiple rounds, multi-slot | `bclaw_dispatch_review(openLoop: true)` or `bclaw_loop(intent='open', kind='review')` |
+
+The simpler modes must not pay a tax because the heavier mode exists.
+Primitives like session, claim, handoff, inbox must all work fully
+without loops.
+
+### P3 — Loops are opt-in enhancement, not default path
+Loops (review, ideation, debug, research) are structured, multi-agent,
+expensive. In the majority of sessions agents work directly without
+them. Every primitive must be fully usable without a loop; loops are
+invoked when the complexity justifies the cost.
+
+### P4 — Teams cross-machine is a first-class scenario
+brainclaw supports three modes of work without compromise:
+
+- **Solo agent** — local, no coordination, fast.
+- **Solo dev + external reviewer** — dispatch-review or review_loop.
+- **Teams cross-machine** — federation push/pull, inbox cross-project,
+  handoff as the artifact for resuming on another machine.
+
+Team primitives (federation, cross-project inbox, handoff) must stay
+load-bearing; simplifications cannot break them.
+
+## Entity-by-entity verdicts
+
+### ✅ Keep as-is
+
+- **Plan / Step / Sequence** — the three-tier hierarchy is
+  semantically distinct and useful for precise agent communication.
+  - Plan: a work item with a goal, text, priority, status, tags,
+    dependencies, steps.
+  - Step: sub-element of a plan; inherits lifecycle from its parent
+    but has its own status.
+  - Sequence: coordinates execution across plans/steps by defining
+    parallelizable lanes with hard/soft dependencies between items.
+  The distinction was confirmed as valuable by the operator.
+
+- **Decision / Constraint / Trap (trichotomy)** — each carries
+  distinct semantics that earn their keep:
+  - **Decision**: anchors a strategic choice (e.g., "chose
+    PostgreSQL", "use X testing framework"). Retrospective reference.
+  - **Constraint**: imposes a process or rule that must be followed
+    (e.g., "minimize core dependencies", "all APIs must be REST",
+    "never init --force"). Strongest concept; drives hook injection
+    to remind agents of the process.
+  - **Trap**: environmental or process pitfall to avoid (e.g., "git
+    merge wipes node_modules", "sandbox X blocks MCP writes"). May
+    trigger a corrective plan when resolvable.
+  All three drive different agent behaviours (decisions = retrieve for
+  context, constraints = enforce, traps = warn + resolve).
+
+- **Claim** — file-level advisory lock, scope boundary, worktree
+  attachment point. Clear lifecycle (active → released/expired).
+
+- **Session** — execution envelope, links work to an agent identity.
+
+- **Assignment / AgentRun** — runtime tracking of dispatched work.
+  Distinction is technical (assignment = the ask, run = the execution)
+  but useful for observability; the agent does not need to interact
+  with them directly.
+
+### 🔴 Remove
+
+- **Candidate lifecycle** — the "create candidate → accept/reject →
+  promote to decision/constraint/trap/handoff" workflow is badly used
+  in practice. Very few candidates in the current store have been
+  processed; most are auto-generated and ignored. The review queue
+  concept duplicates what the Loop engine now provides better via
+  `review_loop`.
+
+  **After removal:**
+  - `bclaw_create_candidate`, `bclaw_list_candidates`, `bclaw_accept`,
+    `bclaw_reject`, `bclaw_harvest_candidates` disappear from the
+    surface.
+  - Auto-reflection at session_end writes directly to decision /
+    constraint / trap / handoff with a `source: 'auto'` field and a
+    `confidence` score. Agents or humans filter low-confidence auto
+    items via `bclaw_find(source: 'auto', confidence_gte: 0.8)`.
+  - Intentional batch review moves to `review_loop` (open a loop
+    whose change_summary points to the memory items under review).
+  - Cross-project signals arrive directly in `inbox/cross-project/`
+    (already the pattern for other signals).
+
+### ⚠️ Downscale
+
+- **Handoff** — keep as a session-end auto-artifact, strip the
+  review sub-flow.
+
+  **Keep:**
+  - Automatic generation at `bclaw_session_end` with commits, files
+    touched, narrative, pre/post conditions, linked plans.
+  - Read-only access via `bclaw_get(entity='handoff', id)` for context
+    resumption on the same or another machine.
+  - Federation push/pull across linked projects (critical for teams;
+    without this teammate B's agent loses teammate A's session story).
+  - Optional linking to a `review_loop` when a structured review is
+    dispatched via `bclaw_dispatch_review(openLoop: true)`.
+
+  **Drop:**
+  - The `review` sub-object on the handoff entity (requester,
+    reviewer, thread_id, requested_at, review_message_id). Never
+    used as designed.
+  - Active `update_handoff` for mid-life edits. Only the narrative
+    override at session_end stays (single write at creation).
+
+  **Rationale:** handoffs are a *passive artefact* of the default
+  path, not a coordination surface. Review happens via dispatch-review
+  or review_loop, not via mutating a handoff.
+
+### 🟡 Examine further during implementation
+
+- **RuntimeNote** — if auto-reflect + direct memory writes land,
+  runtime_note becomes redundant with low-confidence decision/trap
+  candidates. Consider removing. Keep for this audit, revisit during
+  Phase 3 implementation.
+
+- **Instruction layers** (global / project / agent) — functionally
+  similar to constraints with different scopes. Could merge into a
+  unified `memory` entity with a `scope` field. Not urgent; valid to
+  keep distinct for now since instructions have lifecycle triggers
+  (`trigger:post-claim`, `trigger:pre-session-end`) that constraints
+  do not.
+
+- **Capability vs Tool** — two registries under `.brainclaw/memory/`
+  with a thin distinction (capability = what the project can do, tool
+  = what the project uses). Good candidate for merger under a
+  `resource` entity with a `kind` field. Low priority.
+
+## Phase 3 grammar outline (post-audit)
+
+### Canonical verbs (6)
+
+```
+bclaw_find(entity, filters, limit, offset)      — query many
+bclaw_get(entity, id | short_label)             — fetch one
+bclaw_create(entity, data)                      — new item, returns id
+bclaw_update(entity, id, patch)                 — partial merge
+bclaw_remove(entity, id, purge?)                — archive (default) or hard delete
+bclaw_transition(entity, id, to, reason?)       — state machine transitions with side effects
+```
+
+### Workflow intents that stay distinct
+
+```
+bclaw_work(intent)          — session + claim + context facade
+bclaw_coordinate(intent)    — multi-agent coordination
+bclaw_loop(intent)          — loop lifecycle
+bclaw_dispatch(intent)      — dispatch analysis + execution + review (unified from 3 tools)
+bclaw_quick_capture(text)   — NL → typed memory
+bclaw_bootstrap, bclaw_setup, bclaw_switch, bclaw_compact
+bclaw_context(kind)         — unified from get_context, get_execution_context, get_discovery, get_agent_board, get_agent_board_summary
+bclaw_audit(mode)           — chronological or governance report
+bclaw_doctor, bclaw_check_policy, bclaw_check_security
+bclaw_history, bclaw_estimation_report, bclaw_release_notes
+```
+
+### Approximate surface size
+
+From 70 tools to ~20. Each verb is memorable, schema-discoverable, and
+has a clear semantic.
+
+### EntityRegistry as single source of truth
+
+A new `src/core/entity-registry.ts` module holds:
+
+- Short-label prefix per entity (plan → `pln`, claim → `clm`, …)
+- Updatable fields per entity (Zod schema — what `update` can touch)
+- Valid status transitions per entity (state machine definition)
+- Side effects per transition (hardcoded for MVP, configurable later)
+
+`bclaw_update` and `bclaw_transition` both consult this registry. A
+grammar-consistency test suite verifies every entity has a complete
+schema declaration.
+
+### Transition logging — three destinations
+
+| Destination | For whom | Why |
+|---|---|---|
+| `audit.log` | Forensics, compliance, governance | Authoritative chronological record |
+| `events.jsonl` (already exists) | Reactive agents + cockpit live feed | Low-level event stream |
+| `bclaw_activity` (new derived tool) | Humans, coordinator agents | Narrative digest, aggregated by entity/agent/session |
+
+The cockpit (human-visibility layer) is built by consuming these
+signals. Engine features emit; cockpit aggregates.
+
+## Open questions for external validation
+
+Before committing to implementation, we are consulting external
+perspectives (codex, another claude-code instance, github-copilot) to
+pressure-test these decisions. The four questions:
+
+**Q0 — Teams cross-machine completeness.** Our current primitives
+(handoff federation, inbox cross-project, claims local, runtime_note
+federation) — do they cover common team cases (2–5 devs on different
+machines, shared monorepo, distributed reviewers)? Is there an obvious
+missing pattern?
+
+**Q1 — Handoff simplification safety.** After stripping the review
+sub-flow and keeping the handoff as a passive session-end artefact
+(with federation + read-only + optional review_loop link), is there
+any agent-facing use case this simplification breaks that we haven't
+seen?
+
+**Q2 — Transition side effects hardcoded vs configurable.** For MVP we
+plan to hardcode side effects of transitions (close claims on
+plan.status=done, promote candidate on accept, etc.) in the
+`bclaw_transition` handler rather than declaring them in the
+EntityRegistry. Is this the right tradeoff for now, or does the
+configurable approach pay for itself early?
+
+**Q3 — Version strategy pre-public.** Given we are pre-public with no
+external integrators, should we:
+- (a) bump v0.8 → v1.0 directly with the cleaned grammar, accepting
+  the internal breaking change in one go; or
+- (b) go v0.8 → v0.9 (add new verbs, deprecate legacy) → v1.0 (remove
+  legacy), using two internal releases as buffer?
+
+Option (a) is cleaner but less battle-tested before public launch;
+(b) is slower but lets us dogfood the new grammar before removing the
+old.
+
+## §6 — Patches integrated post-consult
+
+Three external reviewers (codex, a second claude-code instance,
+github-copilot) returned verdict `proceed_with_patches` on the audit.
+Their convergent recommendations are integrated below. Each patch is
+load-bearing for Phase 3 and must land either before or during the
+grammar refactor.
+
+### P6.1 — Tombstone pattern for handoff corrections
+
+**What.** Handoffs stay immutable session-end artefacts. Post-session
+corrections (a teammate spotted a mistake, a follow-up clarified
+something) do not mutate the original handoff — they create a *new
+correction handoff* that carries a `superseded_by` pointer back to the
+original.
+
+**Why.** Preserves the "passive artefact" property while keeping an
+audit trail of who revised what. Federation remains safe (each record
+is whole, no partial merges).
+
+**How to apply.** Reject all `bclaw_update(entity='handoff', …)`
+outside the narrative override at creation. Expose instead a
+`bclaw_correct_handoff(original_id, correction_data)` helper that
+writes a new handoff and patches `original.superseded_by`.
+
+### P6.2 — Declarative transition matrix + imperative side effects
+
+**What.** Valid status transitions per entity live in the
+EntityRegistry as a declarative matrix (`{ from: [to1, to2] }`). Side
+effects (close linked claims, write audit entry, emit event) stay
+imperative in `bclaw_transition` for MVP.
+
+**Why.** Hybrid lets us test the declarative matrix (grammar
+consistency tests, static analysis) without over-engineering a rules
+engine we do not need yet. Migration to declarative side effects later
+is a drop-in without breaking callers.
+
+**How to apply.** `EntityRegistry[entity].transitions` is the
+authoritative matrix; `bclaw_transition` rejects moves not in the
+matrix, then runs a hardcoded side-effect dispatch per (entity, to)
+pair.
+
+### P6.3 — Provenance as a typed discriminated union
+
+**What.** Replace the single `source: 'auto' | 'user' | …` string with
+a typed discriminated union:
+
+```ts
+type Provenance =
+  | { kind: 'agent';         agent_id: string; session_id: string }
+  | { kind: 'auto_reflect';  source_session: string; confidence: number }
+  | { kind: 'user';          author: string }
+  | { kind: 'loop_artifact'; loop_id: string; slot: string; turn: number }
+  | { kind: 'federation';    source_project: string; remote_id: string }
+  | { kind: 'correction';    supersedes: string }
+  | { kind: 'legacy' };
+```
+
+**Why.** Each origin has different downstream implications (retention,
+confidence, federation behavior, audit narrative). A single string
+field cannot carry the metadata cleanly; a union keeps type-safety and
+makes queries like `bclaw_find(provenance.kind='auto_reflect',
+confidence_gte:0.8)` natural.
+
+**How to apply.** Add `provenance` field to
+decision/constraint/trap/handoff/runtime_note schemas. On v1.0
+migration, existing records receive `{ kind: 'legacy' }`. Default
+filter on memory reads: exclude `legacy` + auto below threshold,
+configurable via the query.
+
+### P6.4 — Delta context via bclaw_context(kind='delta')
+
+**What.** `bclaw_context` currently returns full state every call. Add
+a `kind: 'delta', since: <handoff_id | timestamp | event_seq>`
+parameter that returns only what changed since the reference point.
+
+**Why.** At scale (long sessions, cross-agent resumption, federation
+sync) returning full state is a token tax. Resumption needs the delta,
+not the world.
+
+**How to apply.** Implement as a filter over the events.jsonl stream +
+a diff against the referenced snapshot. Falls back to full context if
+the reference point is too old (compacted out).
+
+### P6.5 — MCP schema version strategy: 0.6 → 0.7 → 0.8 → 1.0
+
+**What.** The MCP schema version (`SCHEMA_VERSION` in
+`src/commands/mcp.ts`, currently `0.6.0`) is distinct from the app
+version (`package.json`, currently `0.62.0`). Progression:
+
+| Step | MCP schema | App version | Scope |
+|---|---|---|---|
+| Now | 0.6.0 | 0.62.x | baseline |
+| Patches | 0.7.0 | 0.63.x | P6.1–P6.4 + provenance rollout |
+| Migration | 0.8.0 | 0.64.x | `brainclaw migrate` + candidate archive |
+| Phase 3 | 1.0.0 | 1.0.0 | canonical 6 verbs + legacy removal |
+
+**Why.** App version tracks code changes; schema version tracks the
+contract MCP clients bind to. Agents that cache tool catalogs need to
+know when verbs changed shape.
+
+**How to apply.** Bump `SCHEMA_VERSION` at each step. Tool catalog
+response always includes schema_version so clients can invalidate.
+
+### P6.6 — Pending candidates archived on migration
+
+**What.** On v1.0 migration, existing candidates are not promoted or
+rejected — they are archived to `.brainclaw/archive/candidates/` with a
+manifest listing their original paths. The runtime stops reading them.
+
+**Why.** No information loss (archive stays on disk for later
+inspection), no forced triage on the operator, clean cutover.
+
+**How to apply.** `brainclaw migrate --to-schema=1.0` copies
+`.brainclaw/memory/candidates/` to `.brainclaw/archive/candidates/<date>/`,
+writes an index, removes the live directory.
+
+### P6.7 — Schema migration as a hard pre-Phase-3 step
+
+**What.** Do not start Phase 3 (the grammar refactor) until
+`brainclaw migrate` command exists and has been dogfooded on both live
+installations (this machine + the monorepo test server).
+
+**Why.** Phase 3 ships the canonical grammar. Existing stores must
+upgrade cleanly to v1.0 schema before any tool rewrites remove the
+legacy paths. Migration first = safety net; grammar refactor second =
+execute with confidence.
+
+**How to apply.** Migration plan (`feat/v1-schema-migration`, see §7)
+is a hard blocker on the Phase 3 plan (`feat/phase-3-canonical-grammar`).
+
+### P6.8 — Keep runtime_note / instruction / capability/tool distinct
+
+**What.** Reviewers recommended leaving runtime_note, instruction
+layers, and capability/tool as distinct entities for v1.0. They were
+flagged as "examine further" in §5 — verdict is *keep as-is*.
+
+**Why.** Instructions carry lifecycle triggers (`post-claim`,
+`pre-session-end`) that constraints do not. Capability vs tool has a
+semantic distinction (what the project *can do* vs what it *uses*)
+that matters for discoverability. Runtime notes remain a natural
+slot for low-confidence, scoped observations that do not yet deserve
+promotion to decision/trap. Premature merger would lose information.
+
+**How to apply.** No change for v1.0. Flag for a dedicated audit pass
+post-v1.0 once usage data confirms or contradicts the distinctions.
+
+## §7 — Consolidated Phase 3 checklist
+
+Hard prerequisite before any item below: **`feat/v1-schema-migration`
+plan must be executed and dogfooded** (see P6.7).
+
+Phase 3 itself is sliced into nine sub-items; each is independently
+mergeable behind a feature flag or catalog filter:
+
+- **3a — EntityRegistry core.** New `src/core/entity-registry.ts`:
+  short-label prefixes, updatable-field Zod schemas, transition
+  matrices, side-effect map. Grammar consistency tests.
+- **3b — Six canonical CRUD verbs.** Implement `bclaw_find`,
+  `bclaw_get`, `bclaw_create`, `bclaw_update`, `bclaw_remove`,
+  `bclaw_transition` consuming EntityRegistry. Behind `catalog: "all"`
+  filter first, public in `catalog: "default"` at v1.0.
+- **3c — `bclaw_context(kind)` unified.** Consolidates
+  `bclaw_get_context`, `bclaw_get_execution_context`,
+  `bclaw_get_agent_board`, `bclaw_get_agent_board_summary` under one
+  intent with a `kind` discriminator. Includes `kind='delta'` from
+  P6.4.
+- **3d — `bclaw_dispatch(intent)` unified.** Consolidates
+  `bclaw_dispatch_analysis`, `bclaw_dispatch_review`, and the raw
+  `bclaw_dispatch`. Review sub-intent carries `openLoop` flag for the
+  review_loop escalation path.
+- **3e — Handoff downscale.** Strip the review sub-object, remove
+  `bclaw_update_handoff`, expose `bclaw_correct_handoff` for tombstone
+  corrections (P6.1). Federation push/pull preserved end-to-end.
+- **3f — Provenance rollout.** Apply discriminated-union provenance
+  (P6.3) to decision/constraint/trap/handoff/runtime_note. Default
+  memory reads filter on confidence + non-legacy.
+- **3g — Legacy deprecation warnings.** Keep old tool names in
+  `catalog: "all"` with `LEGACY_MCP_TOOL_WARNINGS` entries pointing to
+  the new verb. Warnings fire server-side on every call during 0.9.x.
+- **3h — Docs sync.** Update `docs/integrations/mcp.md`,
+  `CLAUDE.md`, release notes, and agent profile exports. Canonical
+  grammar example galleries.
+- **3i — Legacy removal + v1.0 cut.** Remove deprecated tool names
+  from the MCP surface entirely. Bump schema to 1.0.0 and app to
+  1.0.0. Public launch candidate.
+
+Slices 3a–3b are the architecture core; 3c–3e are the intent
+consolidations; 3f is cross-cutting; 3g–3i are the soft→hard cutover.
+
+## Sources
+
+- `docs/product/agent-first-model.md` — engine/cockpit two-layer model
+- `docs/concepts/loop-engine.md` — v8 RFC for the loop primitive
+- Session transcript 2026-04-18 (strategic round 2) — post-consult
+  integration pass
+- Memory decisions `cnd#587` (product model) and `cnd#588` (loop
+  protocols roadmap)
+- External consult verdicts 2026-04-18 (codex / claude-code /
+  github-copilot) — all `proceed_with_patches`, patches integrated in
+  §6

package/docs/product/positioning.md

@@ -65,16 +65,16 @@ Local-first gives teams:
 - Git history for shared project state
 - compatibility with enterprise or offline environments
 
-## License direction
-
-Today, brainclaw is published under the **Business Source License 1.1 (BSL 1.1)**.
-
-The direction after the closed beta is simpler:
-
-- the local-first brainclaw core is intended to move to MIT
-- remote shared-memory, hosted collaboration, advanced dashboards, and related private add-ons will stay separate commercial products
-
-The intended MIT core covers the local coordination layer:
+## License
+
+brainclaw core is published under the **MIT License**.
+
+The product split is:
+
+- the local-first brainclaw core is MIT
+- remote shared-memory, hosted collaboration, advanced dashboards, and related private add-ons will stay separate commercial products
+
+The MIT core covers the local coordination layer:
 
 - local project memory
 - local MCP and CLI workflows

package/docs/quickstart-existing-project.md

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