brainclaw 1.8.0 → 1.9.1

package/dist/core/worktree.js

@@ -10,6 +10,30 @@ import { parsePorcelainZ, isSystemDirtyPath } from './dirty-scope.js';
 function gitPath(p) {
     return p.replace(/\\/g, '/');
 }
+/**
+ * can_45316d5c — sanitize a scope-derived slug into a valid git branch
+ * component (`git check-ref-format` rules). Scopes like `.github/workflows`
+ * produced `feat/.github-workflows`, which git rejects (component starting
+ * with a dot), failing the whole worktree creation.
+ *
+ * Rules covered: no leading dots/dashes, no trailing dots, no `..`, no
+ * `@{`, no control/space/`~^:?*[\\` characters, no trailing `.lock`.
+ */
+export function sanitizeBranchComponent(raw, fallback = 'scope') {
+    let slug = raw
+        .replace(/[\s~^:?*[\]\\]/g, '-') // chars forbidden by check-ref-format
+        .replace(/@\{/g, '-') // reflog syntax
+        .replace(/\.\.+/g, '.') // no double dots
+        .replace(/[^a-zA-Z0-9._-]/g, '-') // conservative whitelist for the rest
+        .replace(/-+/g, '-') // collapse dashes
+        .replace(/^[.-]+/, '') // no leading dot/dash
+        .replace(/[.-]+$/, ''); // no trailing dot/dash
+    if (/\.lock$/i.test(slug))
+        slug = slug.slice(0, -'.lock'.length);
+    if (!slug)
+        slug = fallback;
+    return slug.slice(0, 48);
+}
 /**
  * Stack marker → shared directories mapping.
  * Maven/Gradle/Cargo intentionally excluded — their dep caches live
@@ -138,7 +162,15 @@ function canonicalizeScopePath(target) {
  * project even when two projects share the same repo name.
  */
 export function worktreesBaseDir(mainWorktreePath) {
-    const hash = crypto.createHash('sha1').update(mainWorktreePath).digest('hex').slice(0, 12);
+    let stablePath = path.resolve(mainWorktreePath);
+    try {
+        stablePath = fs.realpathSync.native(stablePath);
+    }
+    catch { /* path may not exist yet; path.resolve is still deterministic */ }
+    if (process.platform === 'win32' || /^[a-zA-Z]:[\\/]/.test(mainWorktreePath)) {
+        stablePath = stablePath.toLowerCase();
+    }
+    const hash = crypto.createHash('sha1').update(stablePath).digest('hex').slice(0, 12);
     return path.join(os.homedir(), '.brainclaw', 'worktrees', hash);
 }
 /**
@@ -244,7 +276,7 @@ export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
     if (!add.ok) {
         return { committed: false, files_changed: [], reason: `git add failed: ${add.stderr.trim()}` };
     }
-    runGit(['reset', '-q', '--', 'LANE-RESULT.json', '.brainclaw'], worktreePath);
+    runGit(['reset', '-q', '--', 'LANE-RESULT.json', '.brainclaw', '.brainclaw-heartbeat-*'], worktreePath);
     // The files actually staged for this commit (post-exclusion) — also the
     // truthful files_changed report.
     const staged = runGit(['diff', '--cached', '--name-only'], worktreePath);
@@ -320,6 +352,7 @@ export function resetWorktreeToRef(worktreePath, ref) {
             const norm = p.replace(/\\/g, '/');
             return norm !== '.brainclaw-worktree.json'
                 && !norm.startsWith('.brainclaw/')
+                && !norm.startsWith('.brainclaw-heartbeat-')
                 && !norm.startsWith('.git/');
         });
         if (residue.length > 0) {
@@ -420,14 +453,42 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     const branchCheck = runGit(['rev-parse', '--verify', branchName], mainWorktreePath);
     const branchExists = branchCheck.ok;
     const baseRef = options.baseRef ?? 'HEAD';
-    if (branchExists && options.resetExistingBranch) {
+    if (branchExists) {
         const attachedWorktreePath = findWorktreePathForBranch(listWorktrees(mainWorktreePath), branchName);
         if (attachedWorktreePath) {
-            throw new Error(`Cannot reset branch ${branchName}: it is checked out in worktree ${attachedWorktreePath}. Remove or merge that worktree first.`);
+            throw new Error(`Cannot reuse branch ${branchName}: it is checked out in worktree ${attachedWorktreePath}. Remove or merge that worktree first.`);
         }
-        const reset = runGit(['branch', '--force', branchName, baseRef], mainWorktreePath);
-        if (!reset.ok) {
-            throw new Error(`git branch --force failed for ${branchName}: ${reset.stderr.trim()}`);
+        if (options.resetExistingBranch) {
+            const reset = runGit(['branch', '--force', branchName, baseRef], mainWorktreePath);
+            if (!reset.ok) {
+                throw new Error(`git branch --force failed for ${branchName}: ${reset.stderr.trim()}`);
+            }
+        }
+        else {
+            // can_2e282880 (worktree-as-contract at creation): a reused branch is a
+            // CONTRACT that the worker starts from the dispatch base, not from
+            // whatever stale base the branch happened to sit on (observed live: a
+            // June dispatch reused a feat/<scope> branch based on April master).
+            //   - branch has NO commits ahead of the base → silently re-point it to
+            //     the base (it carries nothing worth keeping);
+            //   - branch HAS commits not on the base → REFUSE and name them: they
+            //     are unharvested work — merging/harvesting first is the only safe
+            //     move, a silent reset would destroy it and a silent reuse would
+            //     run the worker on a stale base.
+            const ahead = runGit(['rev-list', '--count', `${baseRef}..${branchName}`], mainWorktreePath);
+            const aheadCount = ahead.ok ? parseInt(ahead.stdout.trim(), 10) : NaN;
+            if (!Number.isFinite(aheadCount)) {
+                throw new Error(`Cannot assess divergence of existing branch ${branchName} vs ${baseRef}: ${ahead.stderr.trim()}`);
+            }
+            if (aheadCount > 0) {
+                const commits = runGit(['log', '--oneline', '-n', '5', `${baseRef}..${branchName}`], mainWorktreePath);
+                throw new Error(`Refusing to reuse branch ${branchName}: it has ${aheadCount} commit(s) not on ${baseRef} (unharvested work). ` +
+                    `Harvest/merge or delete the branch first. Divergent commits:\n${commits.stdout.trim()}`);
+            }
+            const reset = runGit(['branch', '--force', branchName, baseRef], mainWorktreePath);
+            if (!reset.ok) {
+                throw new Error(`git branch --force failed for ${branchName}: ${reset.stderr.trim()}`);
+            }
         }
     }
     // Use forward-slash paths for git on Windows
@@ -512,24 +573,24 @@ export const WORKTREE_HOOKS_DIRNAME = '.brainclaw-hooks';
  * blocking — a tooling gap must not trap a worker.
  */
 export function buildTypecheckPreCommitScript() {
-    return `#!/bin/sh
-# brainclaw worktree typecheck gate (pln#479) — do not edit manually.
-# Blocks the commit when 'tsc --noEmit' fails. Bypass: git commit --no-verify.
-exec node -e "
-const fs = require('fs');
-const { execSync } = require('child_process');
-if (!fs.existsSync('tsconfig.json')) process.exit(0);
-if (!fs.existsSync('node_modules/typescript/bin/tsc')) {
-  process.stderr.write('\\\\n[brainclaw] typecheck gate: typescript not found in worktree node_modules — skipping (commit allowed).\\\\n');
-  process.exit(0);
-}
-try {
-  execSync('node node_modules/typescript/bin/tsc --noEmit', { stdio: 'inherit' });
-} catch (e) {
-  process.stderr.write('\\\\n[brainclaw] commit blocked: tsc --noEmit reported type errors (above). Fix them, or bypass with: git commit --no-verify\\\\n\\\\n');
-  process.exit(1);
-}
-" 2>&1 || exit $?
+    return `#!/bin/sh
+# brainclaw worktree typecheck gate (pln#479) — do not edit manually.
+# Blocks the commit when 'tsc --noEmit' fails. Bypass: git commit --no-verify.
+exec node -e "
+const fs = require('fs');
+const { execSync } = require('child_process');
+if (!fs.existsSync('tsconfig.json')) process.exit(0);
+if (!fs.existsSync('node_modules/typescript/bin/tsc')) {
+  process.stderr.write('\\\\n[brainclaw] typecheck gate: typescript not found in worktree node_modules — skipping (commit allowed).\\\\n');
+  process.exit(0);
+}
+try {
+  execSync('node node_modules/typescript/bin/tsc --noEmit', { stdio: 'inherit' });
+} catch (e) {
+  process.stderr.write('\\\\n[brainclaw] commit blocked: tsc --noEmit reported type errors (above). Fix them, or bypass with: git commit --no-verify\\\\n\\\\n');
+  process.exit(1);
+}
+" 2>&1 || exit $?
 `;
 }
 /**
@@ -817,7 +878,10 @@ export function worktreeHasOnlyBirthNoise(statusZStdout) {
     const paths = parsePorcelainZ(statusZStdout);
     return paths.every((p) => {
         const norm = p.replace(/\\/g, '/');
-        return WORKTREE_BIRTH_NOISE.has(norm) || isSystemDirtyPath(norm);
+        return WORKTREE_BIRTH_NOISE.has(norm)
+            || norm.startsWith('.brainclaw-heartbeat-') // worker liveness sentinel (sprint 1.5)
+            || norm === 'LANE-RESULT.json' // worker outcome report — harvested, never committed
+            || isSystemDirtyPath(norm);
     });
 }
 /**

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.8.0 on 2026-06-09T07:31:59.599Z
+// Source: brainclaw v1.9.1 on 2026-06-18T15:15:04.496Z
 export const FACTS = {
-  "version": "1.8.0",
-  "generated_at": "2026-06-09T07:31:59.599Z",
+  "version": "1.9.1",
+  "generated_at": "2026-06-18T15:15:04.496Z",
   "tools": {
     "count": 62,
     "published_count": 61,
@@ -197,8 +197,8 @@ export const FACTS = {
         "workflow_model": "interactive",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
-        "has_skills": true,
+        "has_hooks": false,
+        "has_skills": false,
         "has_rules": true,
         "instruction_file": ".clinerules/brainclaw.md",
         "mcp_config_scope": "project",
@@ -214,7 +214,7 @@ export const FACTS = {
         "workflow_model": "task-based",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
+        "has_hooks": false,
         "has_skills": true,
         "has_rules": true,
         "instruction_file": "AGENTS.md",
@@ -436,8 +436,8 @@ export const FACTS = {
         "workflow_model": "interactive",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
-        "has_skills": true,
+        "has_hooks": false,
+        "has_skills": false,
         "has_rules": true,
         "instruction_file": ".windsurfrules",
         "mcp_config_scope": "machine",

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.8.0",
-  "generated_at": "2026-06-09T07:31:59.599Z",
+  "version": "1.9.1",
+  "generated_at": "2026-06-18T15:15:04.496Z",
   "tools": {
     "count": 62,
     "published_count": 61,
@@ -195,8 +195,8 @@
         "workflow_model": "interactive",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
-        "has_skills": true,
+        "has_hooks": false,
+        "has_skills": false,
         "has_rules": true,
         "instruction_file": ".clinerules/brainclaw.md",
         "mcp_config_scope": "project",
@@ -212,7 +212,7 @@
         "workflow_model": "task-based",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
+        "has_hooks": false,
         "has_skills": true,
         "has_rules": true,
         "instruction_file": "AGENTS.md",
@@ -434,8 +434,8 @@
         "workflow_model": "interactive",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
-        "has_skills": true,
+        "has_hooks": false,
+        "has_skills": false,
         "has_rules": true,
         "instruction_file": ".windsurfrules",
         "mcp_config_scope": "machine",

package/docs/PROTOCOL.md

@@ -0,0 +1,223 @@
+# Brainclaw Protocol — v0.1 (draft)
+
+> Status: **draft** — pre-public RFC. Versioned in [docs/PROTOCOL.md](./PROTOCOL.md);
+> brainclaw is the reference implementation.
+>
+> Feedback target: external OSS agent integrators (Cline, OpenCode, Hermes,
+> Mistral Vibe, Continue) — see "Feedback wanted" at the bottom.
+
+## 1. What this spec is
+
+Brainclaw runs a multi-agent coordination loop on top of a shared project
+memory. The implementation has converged on a small grammar — entities, verbs,
+lifecycle sentinels — that the rest of the system (CLI, MCP server, writers,
+hooks) is just a delivery channel for.
+
+This document carves out that grammar as a **transport-agnostic protocol** so
+other agents and agent platforms can either:
+
+  - speak it natively (via brainclaw's MCP server, the reference transport), or
+  - implement it themselves and interoperate with brainclaw-managed projects.
+
+The protocol does **not** standardize storage, file layouts, or the internal
+state machine. Those are implementation details; brainclaw's are documented
+under [`docs/concepts/`](./concepts/).
+
+## 2. Versioning
+
+| Field             | Rule                                                                    |
+|-------------------|-------------------------------------------------------------------------|
+| `protocol.major`  | Bumped only for breaking entity / verb / sentinel changes.              |
+| `protocol.minor`  | Bumped for additive entities, verbs, sentinels, or new optional fields. |
+| `protocol.patch`  | Editorial / clarifying changes; no behavioral impact.                   |
+
+Current draft: **0.1** — entity surface stable; verb surface stable on the
+"canonical grammar" (see §4); lifecycle sentinels stable for sessions, claims,
+plans, assignments. Coordination / loop verbs are explicitly experimental.
+
+Implementers SHOULD advertise the maximum supported version via an
+`X-Brainclaw-Protocol` header (HTTP transports) or a server-info field
+(MCP transports). Brainclaw's MCP server returns `0.1` in `serverInfo.version`.
+
+## 3. Entities
+
+The protocol recognises eight kinds of memory objects. Each has a unique `id`,
+a canonical `kind`, and a small set of mutable fields. Storage of additional
+fields is implementation-defined.
+
+| Kind         | Purpose                                                              | Lifecycle states                                        |
+|--------------|----------------------------------------------------------------------|---------------------------------------------------------|
+| `constraint` | Active rule the project must respect.                                | `active` → `resolved` / `expired`                       |
+| `decision`   | Recorded architectural / process decision.                           | `pending` → `approved` / `rejected` / `deferred`         |
+| `trap`       | Known failure mode; reminder for future work.                        | `active` → `resolved` / `expired`                       |
+| `plan`       | Unit of work tracked across agents.                                  | `open` → `in_progress` → `done` / `cancelled`           |
+| `claim`      | Mutex over a file scope.                                             | `open` → `released` (or `expired` via TTL)              |
+| `handoff`    | Asynchronous instruction from one agent to another.                  | `open` → `accepted` → `closed`                          |
+| `candidate`  | Proposed memory item awaiting review.                                | `proposed` → `accepted` / `rejected` / `merged`         |
+| `assignment` | Dispatched work item routed to a specific agent.                     | `offered` → `accepted` → `started` → `completed` / `failed` / `blocked` / `cancelled` |
+
+Entities have these well-known fields (implementations MAY add more):
+
+```
+id          string   // implementation-assigned, opaque, stable
+kind        string   // one of the kinds above
+status      string   // one of the lifecycle states above
+text        string?  // human-readable summary
+tags        string[]?
+created_at  string   // ISO-8601 UTC
+updated_at  string   // ISO-8601 UTC
+provenance  object?  // {kind: 'agent'|'human'|'auto'|'legacy', author, source}
+```
+
+Brainclaw's full field set lives in [`src/core/schema.ts`](../src/core/schema.ts).
+Future protocol minors will promote additional fields to "well-known" as they
+prove portable across implementations.
+
+## 4. The canonical grammar (verbs)
+
+The protocol exposes seven canonical verbs. Implementations MUST support these
+in order to claim protocol compliance. They are deliberately narrow so the
+surface stays small; richer ergonomic helpers are facades on top.
+
+| Verb              | Shape                                                          | Effect                                                  |
+|-------------------|-----------------------------------------------------------------|---------------------------------------------------------|
+| `work(intent)`    | `intent: consult \| execute \| resume \| review`                 | Open a session; optionally claim a scope.               |
+| `context(kind)`   | `kind: memory \| execution \| board \| delta`                    | Read shared state.                                      |
+| `find(entity, …)` | `entity, filter, limit`                                         | Query entities.                                         |
+| `get(entity, id)` | `entity, id` (or `short_label`)                                 | Fetch one entity by identifier.                         |
+| `create(entity)`  | `entity, data`                                                  | Insert a new entity (validated against schema).         |
+| `update(entity)`  | `entity, id, patch`                                             | Patch mutable fields. Status changes go via `transition`. |
+| `transition(…)`   | `entity, id, status`                                            | Move an entity along its lifecycle. Triggers side-effects. |
+
+The reference implementation surfaces these as MCP tools named
+`bclaw_work`, `bclaw_context`, `bclaw_find`, `bclaw_get`, `bclaw_create`,
+`bclaw_update`, `bclaw_transition`. The same names appear in
+`src/commands/mcp.ts:MCP_CANONICAL_GRAMMAR_TOOL_NAMES` and are derived from
+the tool catalog, not hand-curated. Hermes and other narrow-surface agents
+include exactly this set in their MCP `tools.include`.
+
+### 4.1 Coordination verbs (experimental — protocol v0.2 candidates)
+
+These are present in the reference implementation but **not yet stable**.
+Implementations MAY support them but should expect breaking changes:
+
+  - `coordinate(intent: assign|consult|review|reroute)` — multi-agent routing.
+  - `dispatch(plan, agents)` — concrete spawn / claim ledger.
+  - `loop(kind: ideation|implementation|review)` — multi-round loops.
+
+## 5. Lifecycle sentinels
+
+The protocol defines **named state transitions** so any compliant agent can
+reason about another's progress without parsing free-form text. These are the
+strings agents are expected to emit at protocol-defined moments.
+
+### 5.1 Session sentinels
+
+| Moment                | Sentinel                                                              |
+|-----------------------|-----------------------------------------------------------------------|
+| Agent reaches its loop | Filesystem heartbeat: `.brainclaw-heartbeat-<assignment_id>`           |
+| Session opens         | `work(intent)` response carries the `session_id` and seed context.    |
+| Session ends          | `work(intent: …)` is terminal; or implementation-specific close call. |
+
+### 5.2 Assignment sentinels
+
+The lifecycle a coordinator can observe on a dispatched assignment:
+
+```
+offered → accepted → started → (progress)* → completed
+                                             | failed
+                                             | blocked
+                                             | cancelled
+```
+
+Each transition is emitted via `transition('assignment', id, <status>)`.
+A worker that cannot reach the protocol transport (sandboxed) MAY drop a
+`LANE-RESULT.json` file at the worktree root as the fallback signal — the
+coordinator harvests it.
+
+### 5.3 Claim sentinels
+
+```
+open → released         (worker calls transition('claim', id, 'released'))
+open → expired          (TTL-driven; reaper marks expired)
+```
+
+A claim that converged on `done` MAY carry a `planStatus` hint so the
+coordinator updates the linked plan atomically with the release.
+
+### 5.4 Plan-step sentinels
+
+Plans contain ordered steps with their own status. The grammar verbs
+`update('plan', id, {steps:[…]})` and `transition('plan', id, 'done')`
+operate over the whole plan; the canonical step sentinel is a step-level
+`status: done`. Implementations MAY surface `bclaw_complete_step` as a
+sugar on top.
+
+## 6. Conformance levels
+
+| Level | What conformance means                                                                 |
+|-------|----------------------------------------------------------------------------------------|
+| **L1 — Read** | Implementation can issue `work(intent: consult)` + `context` + `find` + `get` and respect active claims. Minimum bar for "I can run inside a brainclaw-managed project without breaking it." |
+| **L2 — Write** | All of L1 plus `create` / `update` / `transition` on the entities above with valid lifecycle transitions. |
+| **L3 — Coordinate** | All of L2 plus the experimental coordination verbs (§4.1) and assignment sentinels. Required for spawning / accepting dispatched work. |
+
+Hermes and Mistral Vibe ship at L1 (narrow surface). Claude Code, Codex,
+Copilot, and Cline are L3. The reference implementation enforces the
+L3 contract via assignment-convergence tests (see
+[`tests/unit/assignment-convergence.test.ts`](../tests/unit/assignment-convergence.test.ts)).
+
+## 7. Transport bindings
+
+The protocol is transport-agnostic. The reference implementation ships an
+MCP server (`brainclaw mcp`); other implementations MAY add JSON-RPC over
+stdio, HTTP, or a local IPC socket without changing the entity / verb /
+sentinel surface.
+
+A transport binding MUST specify:
+
+  - how the seven canonical verbs are named (mapping to the binding's call shape),
+  - how entity identifiers are serialised (recommend opaque strings),
+  - how lifecycle sentinels are encoded (recommend `transition` calls,
+    not free-form status strings).
+
+## 8. Storage and federation
+
+Out of scope for v0.1. The reference implementation uses git-backed
+JSON/YAML in `.brainclaw/`. Multi-project federation is a planned
+extension — see [docs/concepts/](./concepts/) and the brainclaw memory
+files for the current direction. A future protocol version will define
+the wire format for cross-project signaling.
+
+## 9. Reference implementation map
+
+| Protocol concept              | Reference implementation in brainclaw                                 |
+|-------------------------------|-----------------------------------------------------------------------|
+| Entity schemas                | [`src/core/schema.ts`](../src/core/schema.ts)                          |
+| Canonical grammar tool set    | [`src/commands/mcp.ts`](../src/commands/mcp.ts) — `MCP_CANONICAL_GRAMMAR_TOOL_NAMES` |
+| MCP tool catalog              | [`src/commands/mcp.ts`](../src/commands/mcp.ts) — `ALL_TOOLS`          |
+| Per-agent writer wiring       | [`src/core/agent-files.ts`](../src/core/agent-files.ts) — `AGENT_WIRING_REGISTRY` |
+| Capability profiles           | [`src/core/agent-capability.ts`](../src/core/agent-capability.ts)       |
+| Assignment lifecycle          | [`src/core/assignments.ts`](../src/core/assignments.ts) + [`tests/unit/assignment-convergence.test.ts`](../tests/unit/assignment-convergence.test.ts) |
+| Claim lifecycle / TTL         | [`src/core/claims.ts`](../src/core/claims.ts)                          |
+
+## 10. Feedback wanted
+
+The following questions are open for v0.2. We're soliciting input from agent
+integrators before declaring any of them stable:
+
+  1. **Coordination verb shape (§4.1)** — should `coordinate(intent: assign|…)`
+     stay as a single verb with an intent enum, or split into named verbs
+     (`assign`, `reroute`, `review_request`) per L3 capability?
+  2. **Sentinel transport for sandboxed workers** — the `LANE-RESULT.json`
+     fallback file is brainclaw-specific. Is there an interest in
+     standardising a "filesystem fallback" format so any coordinator can
+     harvest results from any sandboxed worker?
+  3. **Entity field portability** — which fields beyond the well-known set
+     (§3) are universal enough to promote in v0.2? Candidates: `severity`,
+     `priority`, `category`, `effort_minutes`, `assignee`.
+  4. **L1-only adoption surface** — would a CLI-only L1 reference (no MCP
+     dependency) lower the adoption bar for OSS agents that don't speak MCP
+     yet?
+
+Open an issue, ping `support@brainclaw.dev`, or comment on the brainclaw plan
+tracking this draft (pln#546).

package/docs/adapters/openclaw.md

@@ -1,43 +1,43 @@
-# OpenClaw Adapter Guide
-
-This adapter helps convert OpenClaw runtime traces into brainclaw candidates.
-
-## Supported Inputs
-
-- Runtime event file: JSON array of events.
-- Runtime session import: events filtered by `metadata.session` from `.brainclaw/runtime/`.
-
-## Basic Usage
-
-```bash
-brainclaw adapter-openclaw-import ./openclaw-events.json
-brainclaw adapter-openclaw-import --session sess_42
-```
-
-## Dry-Run Workflow
-
-Use `--dry-run` to preview what would be ingested without writing any files:
-
-```bash
-brainclaw adapter-openclaw-import ./openclaw-events.json --dry-run
-```
-
-Dry-run is useful for CI checks and for validating mapping quality before modifying `.brainclaw/inbox/`.
-
-## Event Mapping
-
-Current mapping converts events into reflective candidate types:
-
-- `risk_detected` -> `trap`
-- `handoff_requested` -> `handoff`
-- `observation` -> `decision`
-- `constraint_detected` -> `constraint`
-
-If an event type is unknown, it defaults to `decision`.
-
-## Recommended Team Flow
-
-1. Import events from file or session.
-2. Run `brainclaw review --prioritized`.
-3. Curators process with `brainclaw accept` or `brainclaw reject`.
-4. Use `brainclaw doctor` or `brainclaw doctor --json` to monitor quality.
+# OpenClaw Adapter Guide
+
+This adapter helps convert OpenClaw runtime traces into brainclaw candidates.
+
+## Supported Inputs
+
+- Runtime event file: JSON array of events.
+- Runtime session import: events filtered by `metadata.session` from `.brainclaw/runtime/`.
+
+## Basic Usage
+
+```bash
+brainclaw adapter-openclaw-import ./openclaw-events.json
+brainclaw adapter-openclaw-import --session sess_42
+```
+
+## Dry-Run Workflow
+
+Use `--dry-run` to preview what would be ingested without writing any files:
+
+```bash
+brainclaw adapter-openclaw-import ./openclaw-events.json --dry-run
+```
+
+Dry-run is useful for CI checks and for validating mapping quality before modifying `.brainclaw/inbox/`.
+
+## Event Mapping
+
+Current mapping converts events into reflective candidate types:
+
+- `risk_detected` -> `trap`
+- `handoff_requested` -> `handoff`
+- `observation` -> `decision`
+- `constraint_detected` -> `constraint`
+
+If an event type is unknown, it defaults to `decision`.
+
+## Recommended Team Flow
+
+1. Import events from file or session.
+2. Run `brainclaw review --prioritized`.
+3. Curators process with `brainclaw accept` or `brainclaw reject`.
+4. Use `brainclaw doctor` or `brainclaw doctor --json` to monitor quality.