brainclaw 1.5.4 → 1.6.0

package/docs/concepts/troubleshooting.md

@@ -187,17 +187,24 @@ brainclaw stale resolve <plan_id>            # → dropped (default for stale)
 ```bash
 # 1. Is the worker process still alive?
 ps -ef | grep <agent-binary>      # codex, claude, copilot, …
+# Windows: Get-Process -Id <pid>   # or `tasklist /FI "PID eq <pid>"`
 
 # 2. Did the brief-ack file land?
 ls .brainclaw/coordination/runtime/ack/<assignment_id>.ack
 # If yes → spawn started, worker is somewhere in its loop
 # If no → spawn never started or died before the wrap shell ran touch
 
-# 3. Inspect the worktree for activity
+# 3. (pln#504) What did the worker actually say? stdout/stderr capture
+# Spawned workers now route their streams to per-assignment log files. If the
+# worker died silently, the error usually shows up here.
+cat .brainclaw/coordination/runtime/log/<assignment_id>.stdout.log
+cat .brainclaw/coordination/runtime/log/<assignment_id>.stderr.log
+
+# 4. Inspect the worktree for activity
 git -C <worktree> log --oneline -5
 git -C <worktree> status
 
-# 4. Check the run log
+# 5. Check the run log
 brainclaw inbox list --agent <agent>
 # or via MCP: bclaw_assignment_events(assignmentId="<id>")
 ```
@@ -213,6 +220,7 @@ brainclaw inbox list --agent <agent>
 
 ## See also
 
+- [`docs/concepts/dispatch-lifecycle.md`](dispatch-lifecycle.md) — the entity model + FSMs + observability decision tree underlying every diagnostic step on this page
 - [`docs/concepts/memory-staleness.md`](memory-staleness.md) — staleness signals and resolve flow in depth
 - [`docs/concepts/loop-engine.md`](loop-engine.md) — multi-turn loops (review-fix), recovery semantics for in-flight loops
 - [`docs/concepts/upgrade-cli.md`](upgrade-cli.md) — `brainclaw upgrade` design + rollback path

package/docs/integrations/agents.md

@@ -62,20 +62,20 @@ Skill-based integration via `skills/<agent>/SKILL.md`:
 
 ## Setting up agent integration
 
-### Automatic (recommended)
-
-```bash
-brainclaw setup     # machine-level: detects agents, creates global configs
-brainclaw init      # project-level: creates .brainclaw/, writes agent files
-```
-
-Or ask your coding agent to do it:
-
-```
-"Install and initialize brainclaw in this project"
-```
-
-The agent can use `bclaw_setup` to walk through the process interactively.
+### Automatic (recommended)
+
+```bash
+brainclaw setup-machine   # machine-level: detects agents, creates global configs
+brainclaw init            # project-level: creates or refreshes .brainclaw/, writes agent files
+```
+
+Or ask your coding agent to do it:
+
+```
+"Inspect this package, explain what brainclaw does, then install it and initialize or join this project"
+```
+
+The agent can use `bclaw_setup` to walk through the process interactively.
 
 ### Per-agent manual setup
 

package/docs/integrations/codex.md

@@ -4,7 +4,14 @@ brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instru
 
 ## Auto-setup
 
-`brainclaw init` detects Codex (the presence of `~/.codex/`) and writes `AGENTS.md` to the project root. The MCP server is registered machine-wide at `~/.codex/mcp-config.json`. To regenerate manually:
+Codex setup is split across machine and project scope:
+
+- `brainclaw setup-machine --agents codex --yes` writes the machine-level MCP config at `~/.codex/config.toml`
+- `brainclaw init` creates or refreshes the current project's Brainclaw state and writes `AGENTS.md`
+
+If the project already has `.brainclaw/`, rerunning `brainclaw init` is safe and refreshes the managed Brainclaw/Codex files for the current machine.
+
+To regenerate project instructions manually:
 
 ```bash
 brainclaw export --format agents-md --write
@@ -12,17 +19,13 @@ brainclaw export --format agents-md --write
 
 ## MCP configuration
 
-Codex reads MCP servers from a machine-level config (`~/.codex/mcp-config.json` on most installs). brainclaw is registered as:
-
-```json
-{
-  "mcpServers": {
-    "brainclaw": {
-      "command": "npx",
-      "args": ["-y", "brainclaw@latest", "mcp"]
-    }
-  }
-}
+Codex reads MCP servers from a machine-level config (`~/.codex/config.toml` on most installs). brainclaw is registered as:
+
+```toml
+[mcp_servers.brainclaw]
+command = "npx"
+args = ["-y", "brainclaw@latest", "mcp"]
+startup_timeout_ms = 20000
 ```
 
 Per-session MCP config can also be passed via `--additional-mcp-config @<file>` when invoking Codex.

package/docs/integrations/mcp.md

@@ -156,10 +156,16 @@ for the full 1.0.0 changelog.
 | `bclaw_remove(entity, id, purge?)` | Archive (default) or hard-delete | `bclaw_delete_memory`, `bclaw_delete_plan` |
 | `bclaw_transition(entity, id, to, reason?)` | State machine transition with side-effect tags | `bclaw_accept`, `bclaw_reject`, status-update flows |
 
-Supported entities: plan, decision, constraint, trap, handoff,
-runtime_note, candidate, claim, action, assignment, agent_run
-(read-only for the latter four). Declarative transition matrix +
-updatable field list live in [src/core/entity-registry.ts](../../src/core/entity-registry.ts).
+Supported entities: plan, decision, constraint, trap, handoff,
+runtime_note, candidate, claim, action, assignment, agent_run
+(with assignment lifecycle now writable through `bclaw_transition` and
+`bclaw_remove`; `agent_run` remains read-only). Declarative transition matrix +
+updatable field list live in [src/core/entity-registry.ts](../../src/core/entity-registry.ts).
+
+For assignments specifically:
+- `bclaw_transition(entity="assignment", id=..., to="cancelled", reason=...)` is the canonical supervisor/admin cancel path.
+- `bclaw_remove(entity="assignment", id=...)` archives by cancelling the assignment.
+- `bclaw_remove(entity="assignment", id=..., purge=true)` hard-deletes the assignment record.
 
 ##### `bclaw_find` filter keys
 

package/docs/integrations/overview.md

@@ -2,6 +2,17 @@
 
 Brainclaw works alongside your existing coding agents. It does not replace them — it gives them a shared memory and coordination layer they can all read from and write to.
 
+For coordination internals — what happens when brainclaw spawns or routes work to another agent (claims, assignments, brief-ack sentinels, stdout/stderr log files, FSM transitions) — see [../concepts/dispatch-lifecycle.md](../concepts/dispatch-lifecycle.md).
+
+## Onboarding model
+
+There are two separate setup scopes:
+
+- **Machine scope** — `brainclaw setup-machine` (or the broader `brainclaw setup`) detects agents on this machine and writes the machine-level MCP/user config Brainclaw manages.
+- **Project scope** — `brainclaw init` creates or refreshes `.brainclaw/` for the current repository and rewrites the managed project/agent files safely.
+
+That split is deliberate. A fresh machine may need MCP registration before any repository is touched, while an existing project may already have `.brainclaw/` and only need a safe refresh for the arriving agent.
+
 ## How agents connect to brainclaw
 
 Brainclaw reaches each agent through multiple surfaces. Not every agent supports every surface, and that's fine — brainclaw adapts what it writes based on what the agent can handle.

package/docs/playbooks/productivity/index.md

@@ -89,9 +89,9 @@ Context profiles are hardcoded in `context.ts` with fixed section weights (plans
 `rollback.ts` can revert a single item to its previous state via audit snapshots, but there is no batch undo ("undo all changes from session X"), no point-in-time restore, no "undo last 5 edits" convenience.
 **Impact:** If an agent writes bad memory, cleanup is manual and item-by-item.
 
-### No init repair path
-If `brainclaw init` partially fails or produces a bad config, there is no `brainclaw repair` command. Re-init requires `--force` which risks destroying existing memory. `bclaw_doctor` checks for issues but auto-repairs very little.
-**Impact:** Corrupted setups require manual intervention that non-tech creators cannot do.
+### 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.

package/docs/quickstart-existing-project.md

@@ -6,13 +6,17 @@ If the repo is brand new and `.brainclaw/` is absent, see [quickstart.md](quicks
 
 ## 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.
+| Situation | Use |
+|---|---|
+| Repo has no `.brainclaw/` | [quickstart.md](quickstart.md) (`brainclaw init`) |
+| Repo has `.brainclaw/`, you've never worked here | **this page** (`brainclaw init` upsert + discovery) |
+| Repo has memory but it was scraped from docs/git, not curated | [bootstrap](concepts/workspace-bootstrapping.md) (`brainclaw bootstrap --apply`) |
+
+The three commands now target different lifecycle stages:
+- `setup-machine` bootstraps the current machine
+- `init` creates or refreshes project setup safely
+- `bootstrap` extracts project context into memory
+- `enable-agent` explicitly joins another agent to the same project
 
 ## Step 0 — verify your install is compatible
 
@@ -30,23 +34,39 @@ 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
+## Step 1 — bootstrap this machine if needed
+
+```bash
+brainclaw setup-machine --yes
+```
+
+Run this once on a fresh machine so Brainclaw can configure the agents it detects before you touch any project-level state.
+
+## Step 2 — refresh project setup for the current agent
+
+```bash
+brainclaw init
+```
+
+On a project that already has `.brainclaw/`, `brainclaw init` acts as a safe upsert. It preserves the existing memory and refreshes the managed Brainclaw and detected-agent files for the machine you're using now.
+
+If you want the explicit path for a different or additional agent, run:
+
+```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).
+
+These commands:
+- Detect 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 3 — read what already exists
 
 Before touching code, load the project's accumulated knowledge so you don't re-discover what others already learned.
 
@@ -74,7 +94,7 @@ For a narrower view focused on the area you're about to touch:
 bclaw_context(kind="memory", path="src/<area>/")
 ```
 
-## Step 3 — discover in-flight work
+## Step 4 — discover in-flight work
 
 Several things may be already underway when you arrive:
 
@@ -100,7 +120,7 @@ bclaw_context(kind="board")
 
 The board surfaces all four (plans, claims, sequences, handoffs) in one structured response.
 
-## Step 4 — pick what to work on
+## Step 5 — pick what to work on
 
 You have a few honest options:
 
@@ -110,7 +130,7 @@ You have a few honest options:
 
 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
+## Step 6 — verify your setup is healthy before commiting changes
 
 Once you've started working, sanity-check:
 
@@ -124,7 +144,7 @@ This runs a series of checks: state validity, MCP runtime health (post-pln#478),
 
 - **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)
+- **Setting up brainclaw on your machine for the first time** → [docs/integrations/overview.md](integrations/overview.md) (`brainclaw setup-machine` or the broader `brainclaw setup` flow)
 - **Recovering from a degraded state** → [docs/concepts/troubleshooting.md](concepts/troubleshooting.md)
 
 ## See also

package/docs/quickstart.md

@@ -6,32 +6,46 @@ Get brainclaw running in your project in under 5 minutes.
 
 If you're about to cut a release that changes the CLI, MCP, or context surface, run the checklist in [release-maintenance.md](release-maintenance.md) before publishing a local pack or npm build.
 
-## Step 1: Install
-
-```bash
-npm install -g brainclaw
-```
-
-Requires Node.js 20+. Verify with `brainclaw --version`.
-
-## Step 2: Initialize your project
-
-```bash
-cd your-project
-brainclaw init
-```
-
-**What happens:**
-- Creates `.brainclaw/` directory (project memory store)
-- Detects your coding agent (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.)
-- Writes MCP configuration for the detected agent
-- Writes instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/brainclaw.md`, etc.)
-- Installs session hooks (if supported by your agent)
-- Adds `.brainclaw/` to `.gitignore`
-
-If you have multiple repos, use `brainclaw setup --yes` instead — it scans your project directories and initializes everything at once.
-
-## Step 3: Restart your agent
+## Step 1: Install
+
+```bash
+npm install -g brainclaw
+```
+
+Requires Node.js 20+. Verify with `brainclaw --version`.
+
+## Step 2: Bootstrap this machine
+
+```bash
+brainclaw setup-machine --yes
+```
+
+This configures the agents Brainclaw can see on the current machine and writes the machine-level MCP/user files it manages. It does **not** initialize the current repository yet.
+
+## Step 3: Initialize or refresh your project
+
+```bash
+cd your-project
+brainclaw init
+```
+
+**What happens:**
+- Creates `.brainclaw/` when the project is new, or refreshes it safely when it already exists
+- Detects your coding agent (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.)
+- Refreshes the detected agent's project and machine integration files when applicable
+- Writes instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/brainclaw.md`, etc.)
+- Installs session hooks (if supported by your agent)
+- Adds `.brainclaw/` to `.gitignore`
+
+If you want the explicit path for a second or late-arriving agent on an already initialized project, use:
+
+```bash
+brainclaw enable-agent <agent-name>
+```
+
+If you have multiple repos, use `brainclaw setup --yes` instead — it bootstraps the machine, scans your project directories, and initializes everything at once.
+
+## Step 4: Restart your agent
 
 Your coding agent needs to reload to pick up the new MCP configuration.
 
@@ -44,7 +58,7 @@ Your coding agent needs to reload to pick up the new MCP configuration.
 | **Windsurf** | Reload the editor |
 | **Copilot** | Reload VS Code window (uses instruction file, not MCP) |
 
-## Step 4: Verify it works
+## Step 5: Verify it works
 
 After reloading, tell your agent:
 
@@ -62,7 +76,7 @@ brainclaw agent-board     # what each agent sees
 brainclaw context         # current project memory
 ```
 
-## Step 5: Start using brainclaw
+## Step 6: Start using brainclaw
 
 ### For agents with MCP (most agents)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {