brainclaw 0.28.0 → 1.5.3

package/docs/concepts/troubleshooting.md

@@ -0,0 +1,220 @@
+# Troubleshooting & recovery
+
+Runbook for the most common ways a brainclaw workspace gets into a degraded state during multi-agent coordination, and how to bring it back. Symptoms first, causes second, remediation third — pattern-matchable when you don't have time to read the whole page.
+
+This is **operator-facing**: it assumes you can run CLI commands. Agents you orchestrate don't read this page; you do, when something stalls.
+
+## Quick-reference cheatsheet
+
+| Symptom | First-line check | First-line fix |
+|---|---|---|
+| Agent crashed, claim still active | `brainclaw claim list` | `brainclaw claim release <id>` (or `brainclaw stale resolve <id>`) |
+| Plan stuck `in_progress` for days | `brainclaw stale list` | `brainclaw stale resolve <plan_id>` (transitions to `dropped`) |
+| Dispatched worker finished without committing | `git -C <worktree> status` | manually `git add` + `git commit` in the worktree, then merge |
+| `Cannot find module 'mcp-worker.js'` | `brainclaw doctor` | `brainclaw doctor --repair` |
+| Octopus merge fails on parallel lanes | `git status` | merge lanes one-by-one, resolve conflicts, then proceed |
+| `.brainclaw/` schema looks corrupt | `brainclaw doctor --after-migration` | `brainclaw upgrade --rollback` (restores last backup) |
+| Inbox messages stuck / not delivered | `brainclaw inbox list` | `brainclaw inbox ack <id>` or check `bclaw_assignment_events` |
+| `bclaw_work` returns 25k-token error | n/a | already mitigated since v1.0.14 (compact mode default); pass `compact: true` if older clients |
+| Stale runtime notes flood `bclaw_context` | `brainclaw stale list` | `brainclaw stale resolve <id>` per noisy item |
+
+If your symptom isn't here, jump to the relevant section below or run `brainclaw doctor --json` and inspect the `checks` array.
+
+---
+
+## Stale claims after a crashed agent
+
+**Symptom**: an agent died (credit limit, terminal closed, network drop). Other agents see the scope as held and refuse to claim it.
+
+**Why**: claims are advisory locks with a TTL, but expiry is not enforced by a daemon — it surfaces only when something queries it. So a crashed agent's claim stays "active" until someone runs a check.
+
+**Fix**:
+
+```bash
+# See what's stale (uses the staleness scoring from src/core/staleness.ts)
+brainclaw stale list
+
+# Release a specific stale claim
+brainclaw claim release <claim_id>
+
+# Or, for any stale entity (plan, handoff, candidate, runtime_note, claim),
+# trigger the canonical action:
+brainclaw stale resolve <id>
+```
+
+`stale resolve` dispatches to the right transition per entity:
+- claim → release
+- plan → `bclaw_transition(entity="plan", to="dropped")`
+- handoff → `bclaw_transition(entity="handoff", to="closed")`
+- candidate → `bclaw_transition(entity="candidate", to="rejected")`
+- trap → `bclaw_transition(entity="trap", to="resolved")`
+- runtime_note → `bclaw_remove(entity="runtime_note", id=…)`
+
+**Prevention**: agents that respect the protocol call `bclaw_session_end(auto_release: true)` on exit, which releases all their claims. This is the recommended default in every dispatch brief.
+
+---
+
+## Dispatched worker finished work but never committed
+
+**Symptom**: a sequence's lane shows the worker as "task_complete" in the run log, but `git -C <worktree-path> status` shows uncommitted changes.
+
+**Why**: some agents (notably codex when running in `--sandbox workspace-write`) sometimes finish editing without ever creating a git commit — they exit on `task_complete` from the prompt without the wrap-up step. The brief-ack file confirms the spawn *started*, not that it *committed*. See `trp#178`.
+
+**Fix** (manual harvest):
+
+```bash
+# 1. Locate the worktree
+git worktree list | grep feat/pln_<lane_id>
+
+# 2. cd into it, inspect the work
+cd ~/.brainclaw/worktrees/<project-hash>/feat_pln_xxxx
+git status
+git diff --stat
+
+# 3. Stage + commit with a clear message that references the plan id
+git add <files>
+git commit -m "feat(<scope>): <summary> (pln#<id>)"
+
+# 4. Back on master, octopus-merge as usual
+cd <main repo>
+git merge --no-ff feat/pln_xxxx -m "merge: <description>"
+```
+
+**Prevention**: every dispatch brief targeting agents prone to this pattern (notably codex) should include explicit commit instructions at the end, e.g. *"When done editing, stage your changes and create a commit with a clear message referencing the plan id (e.g. `feat(scope): summary (pln#XXX)`). Do not stop until the commit exists."*
+
+---
+
+## MCP runtime corrupted (mcp-worker.js missing)
+
+**Symptom**: `MCP error -32603: Cannot find module 'mcp-worker.js'` or the server logs `MCP runtime corrupted (mcp-worker.js missing)` on startup.
+
+**Why**: `dist/` was wiped or partially deleted. Common causes: a `git merge` that triggered worktree cleanup before pln#477 landed, an `npm run clean:dist` followed by an interrupted build, or filesystem-level corruption.
+
+**Fix**:
+
+```bash
+brainclaw doctor --repair
+```
+
+This rebuilds `dist/` from `src/` (TypeScript compile + copy default profiles) and validates by running `node dist/cli.js --version`. The repair also writes `dist/.brainclaw-build.json` so subsequent runs can do a stale-check (compare `src_hash` vs `dist_hash`).
+
+**If `--repair` fails**: it usually means `node_modules` is also damaged. Run a clean `npm install` first, then re-run `brainclaw doctor --repair`.
+
+**Note**: read-only MCP handlers stay available in-process even when the worker is missing (since pln#478) — so basic `bclaw_context` and `bclaw_find` calls still respond, but anything requiring the worker (most write operations) returns `runtime_corrupted` with a repair pointer.
+
+---
+
+## Octopus merge fails on parallel lanes
+
+**Symptom**: after a sequenced parallel dispatch finishes, you run `git merge --no-ff lane1 lane2 lane3 -m "merge: …"` and git refuses with conflict markers.
+
+**Why**: octopus merges only succeed when the lanes touch disjoint files. If two lanes wrote to the same file, octopus aborts and you must merge them sequentially.
+
+**Fix**:
+
+```bash
+# Cancel the failed octopus
+git merge --abort
+
+# Merge lanes one at a time, resolving conflicts as needed
+git merge --no-ff lane1
+# (resolve any conflicts, commit)
+git merge --no-ff lane2
+# (resolve any conflicts, commit)
+git merge --no-ff lane3
+```
+
+**Prevention**: when defining a sequence, choose lane scopes that minimize file overlap. Use `hard_after` dependencies for lanes that genuinely need to land in order. The dispatcher does not itself enforce disjoint scopes — that's the caller's responsibility when designing the sequence.
+
+---
+
+## `.brainclaw/` looks corrupted (schema drift, malformed JSON)
+
+**Symptom**: `bclaw_doctor` reports `state is invalid: <ZodError>` or files in `.brainclaw/memory/` fail to parse.
+
+**Why**: usually a half-written file from an interrupted write (process killed mid-write), a migration that didn't complete, or a manual edit that introduced syntax errors. `brainclaw upgrade --rollback` exists precisely for this case.
+
+**Fix**:
+
+```bash
+# 1. Inspect what's wrong
+brainclaw doctor --after-migration
+
+# 2. If the most recent migration is the cause, roll back
+brainclaw upgrade --rollback
+# This restores the last backup at <store>.bak-<iso-ts>/ and parks the
+# current corrupted store at <store>.rollback-<iso-ts>/ for inspection.
+
+# 3. If a single file is corrupted (and rollback is too aggressive),
+# inspect the parked rollback dir and copy individual files back manually.
+```
+
+**Prevention**: brainclaw takes a backup before every `upgrade` run (see `docs/concepts/upgrade-cli.md`). For non-upgrade scenarios, rely on git: `.brainclaw/` is git-versioned by default, so `git log` and `git checkout <prev>` recover any committed state.
+
+---
+
+## Plan stuck `in_progress`
+
+**Symptom**: a plan has been marked `in_progress` for days with no commits or claim activity.
+
+**Why**: the agent that started it crashed, was rerouted, or simply forgot to transition to `done` / `blocked` / `dropped`.
+
+**Fix**:
+
+```bash
+# Survey
+brainclaw stale list  # plan_in_progress flagged after 7 days by default
+
+# Decide based on context
+brainclaw stale resolve <plan_id>            # → dropped (default for stale)
+# or, via canonical grammar, transition to a different terminal state:
+# bclaw_transition(entity="plan", id="<plan_id>", to="done")
+# bclaw_transition(entity="plan", id="<plan_id>", to="blocked")
+```
+
+**Threshold tuning**: defaults live in `src/core/staleness.ts`. A config-driven override is on the roadmap (open follow-up); for now you adjust the source file if 7 days is too aggressive for your project.
+
+---
+
+## Inbox messages stuck / brief-ack never arrived
+
+**Symptom**: a dispatched assignment shows `running` indefinitely, and `bclaw_assignment_events` shows `run_running` but no further progress.
+
+**Why**: the spawned worker process either (a) crashed before reading its inbox, (b) read the inbox but couldn't acknowledge (e.g., MCP unavailable inside the spawned sandbox — common with codex `--sandbox workspace-write`), or (c) is genuinely still working but slow.
+
+**Diagnostic order**:
+
+```bash
+# 1. Is the worker process still alive?
+ps -ef | grep <agent-binary>      # codex, claude, copilot, …
+
+# 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
+git -C <worktree> log --oneline -5
+git -C <worktree> status
+
+# 4. Check the run log
+brainclaw inbox list --agent <agent>
+# or via MCP: bclaw_assignment_events(assignmentId="<id>")
+```
+
+**Fix paths**:
+- Worker dead, no ack → reroute via `bclaw_coordinate(intent="reroute", …)` to another agent
+- Worker dead, ack present, work uncommitted → manual harvest (see "Dispatched worker finished without committing" above)
+- Worker still alive but slow → wait, or `kill` and reroute
+
+**Brief-ack TTL** is configurable via `BRAINCLAW_HANDSHAKE_TIMEOUT_MS` (default 30s since pln#475+#476). Past that, the dispatcher times the spawn out and surfaces the failure in the assignment events log.
+
+---
+
+## See also
+
+- [`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
+- [`docs/cli.md`](../cli.md) — full command reference for `doctor`, `stale`, `claim`, `upgrade`, `inbox`, `worktree`
+- [`docs/concepts/multi-agent-workflows.md`](multi-agent-workflows.md) — happy-path coordination patterns (the inverse of this page)

package/docs/concepts/upgrade-cli.md

@@ -0,0 +1,202 @@
+# `brainclaw upgrade` — store schema upgrade CLI
+
+Design for the CLI command that upgrades a `.brainclaw/` store to a
+newer schema version (first target: 1.0 = MCP schema 0.8.0 final
+step). Hard prerequisite before the Phase 3 grammar refactor
+(`pln_c6472192`) can start.
+
+**Extension, not new command.** `brainclaw upgrade` already exists
+for store housekeeping (entity-dir migration, Zod schema doc
+migration on load, managed agent-file refresh, optional
+`--self-update` of the binary). The v1.0 work extends this command
+with three additions:
+
+1. `--to <version>` — run the one-shot v1.0 patches (candidate
+   archive, handoff review-strip, provenance rollout) on top of the
+   housekeeping work. Idempotent — re-running after success is a
+   no-op.
+2. `--backup` — create a timestamped backup before any write
+   (safety net reusable for *any* upgrade run, not only v1.0).
+3. `--rollback` — restore the most recent backup, park the current
+   live store for inspection.
+
+**Distinct from `brainclaw migrate`.** `migrate` remains recurring
+memory housekeeping (moves misplaced items between stores). It is
+orthogonal to schema progression and stays untouched.
+
+Tracked under `pln_bc6e88cc` / step `stp_3a866463`.
+
+## Goals
+
+- One authoritative command to move any existing store from schema
+  0.6.x → 0.8.0 (covers all post-consult patches: P6.1 tombstone,
+  P6.3 provenance, P6.6 candidate archive, handoff review-field
+  strip).
+- Safe by default: dry-run first, backup before any write, health
+  check after apply, rollback path when things go wrong.
+- Idempotent: running migrate twice on a store already at the target
+  schema is a no-op (exit 0, no writes).
+- Dogfoodable on real stores (this machine + monorepo test server)
+  before Phase 3 unblocks.
+
+## Command surface
+
+```
+brainclaw upgrade [options]
+
+Options:
+  --to <version>           Target schema (default: 1.0). Must match a
+                           known migration path from current schema.
+  --dry-run                Simulate all stages, print diff summary,
+                           perform no writes. Exits non-zero if issues
+                           are found that would abort a real run.
+  --backup-dir <path>      Backup destination (default:
+                           `<store>/../<store-name>.bak-<iso-ts>/`).
+                           Ignored with --dry-run and --rollback.
+  --rollback               Restore the most recent backup for this
+                           store, then refuse to proceed if the schema
+                           version after restore does not match a
+                           known pre-migration state.
+  --store <path>           Store root (default: auto-resolved via
+                           existing store chain).
+  --yes                    Skip the final confirmation prompt.
+  --verbose                Per-record mutation log (default: summary
+                           only).
+  --json                   Machine-readable summary on stdout. Errors
+                           still go to stderr as text.
+```
+
+Sub-command shape matches existing CLI conventions (`brainclaw
+bootstrap`, `brainclaw doctor`, `brainclaw setup`). Implementation
+lives in `src/commands/migrate.ts`; registration in `src/cli.ts`.
+
+## Execution pipeline
+
+Every stage runs in order. Any stage failing aborts the run *before*
+any writes are committed (except when already past the backup stage —
+then rollback is the recovery path).
+
+1. **Resolve store.** Find `.brainclaw/` via the usual chain; refuse
+   to operate on a non-store directory.
+2. **Read current schema version.** From
+   `.brainclaw/schema-version.json` if present, else infer from store
+   shape (handoffs with `review` field → pre-migration). Refuse if
+   ambiguous — require operator to pin `--from-schema`.
+3. **Plan.** Compute the set of patches to apply (P6.1, P6.3, P6.6,
+   handoff strip, SCHEMA_VERSION bumps). Each patch knows its
+   pre-condition (does this store need it?) and post-condition (what
+   does the store look like after).
+4. **Pre-flight checks.** Read-only validation pass:
+   - All memory records deserialize under the current schema.
+   - No live claims (would be invalidated by the migration).
+   - Store not on a schema version newer than the target (refuse
+     down-migration).
+   - Free disk space ≥ 2× store size (for backup).
+5. **Print plan.** Human-readable summary of what will change (N
+   candidates archived, M handoffs stripped, K records stamped with
+   legacy provenance). With `--dry-run`, stop here.
+6. **Confirm.** Prompt unless `--yes`. Shows backup destination.
+7. **Backup.** Atomic copy `.brainclaw/` → `<backup-dir>/`. Write a
+   manifest (`backup.json`) with original path, timestamp, schema
+   version, brainclaw version.
+8. **Apply patches.** Each patch is a function `(store) => void`
+   working on an in-memory representation. All patches run against
+   one snapshot, then the result is committed atomically via
+   rename-based write to a `.brainclaw.new/` sibling, then swap.
+9. **Bump schema version.** Write `schema-version.json` with history
+   trail:
+   ```json
+   {
+     "current": "0.8.0",
+     "history": [
+       { "from": "0.6.0", "to": "0.8.0", "at": "2026-04-18T...",
+         "patches": ["candidate_archive", "handoff_strip",
+                     "provenance_legacy_stamp"] }
+     ]
+   }
+   ```
+10. **Health check.** Run `brainclaw doctor --after-migration` as a
+    subprocess. If it exits non-zero, print the doctor output, leave
+    the backup in place, suggest `brainclaw upgrade --rollback`. Do
+    not attempt auto-rollback — the operator decides.
+11. **Summary.** Lines changed, backup path, next suggested command
+    (`brainclaw doctor`, or if dogfood phase, the Phase 3 plan id).
+
+## Rollback path
+
+`brainclaw upgrade --rollback` resolves the most recent backup for
+the store, validates its manifest, then does an atomic swap:
+
+1. Rename `.brainclaw/` → `.brainclaw.rollback-<ts>/` (kept for
+   inspection, deleted after 7 days by a future `brainclaw clean`).
+2. Copy `<backup>/` → `.brainclaw/`.
+3. Verify `schema-version.json` matches the pre-migration state
+   declared in the backup manifest. Refuse if mismatch.
+4. Print "rolled back to schema <version>".
+
+Rollback is the recovery action, not an automatic fallback. Automatic
+rollback would mask migration bugs we need to see.
+
+## Idempotency
+
+Running `brainclaw upgrade` on a store already at the target schema:
+
+- Pre-flight detects current == target.
+- Plan stage produces zero patches.
+- Prints "already on schema 0.8.0, nothing to do" and exits 0.
+- No backup, no writes.
+
+Running with a partial schema version (e.g., 0.7.0, after a prior
+migration interrupted) resumes from the first un-applied patch.
+
+## Failure modes
+
+| Mode | Detection | Recovery |
+|---|---|---|
+| Disk full during backup | `copy` write fails | Abort before any schema write; original store untouched. |
+| Patch throws mid-run | Exception in apply stage | Abort before atomic swap; original store untouched. |
+| Atomic swap fails | rename() fails (antivirus, lock) | `.brainclaw.new/` persists; operator can inspect and retry. |
+| Doctor post-check fails | doctor exits non-zero | Store is on new schema but invalid; operator inspects + runs `--rollback`. |
+| Rollback manifest missing | No `backup.json` | Refuse rollback. Operator restores manually. |
+
+No silent recovery. Every failure leaves a diagnosable trail.
+
+## Patch catalogue (v1.0 scope)
+
+Each patch is a named, independently testable unit:
+
+- **`candidate_archive`** (P6.6) — move `.brainclaw/memory/candidates/`
+  items to `.brainclaw/archive/candidates/<migration-date>/` with
+  manifest.
+- **`handoff_review_strip`** (groundwork for P6.1) — remove `review`
+  sub-object from existing handoffs.
+- **`provenance_legacy_stamp`** (P6.3) — stamp
+  `provenance: { kind: 'legacy' }` on pre-existing memory records.
+  Infer `auto_reflect` for items already tagged `source=auto`.
+- **`schema_version_marker`** — write `.brainclaw/schema-version.json`
+  with history trail.
+
+Future patches add to the catalogue; each declares its source schema
+and target schema, so the planner stitches a path.
+
+## Open implementation questions
+
+- Should `migrate` live under the `bootstrap` family or as a top-level
+  command? Leaning top-level — the action is orthogonal to setup.
+- Do we gate migration on `brainclaw --version` matching a known
+  "migration-capable" range? For now yes: if the binary is older than
+  0.63.0 it refuses to migrate to schema 0.8.0.
+- Where do the patch implementations live? Proposal:
+  `src/core/migrations/<name>.ts`, registered in
+  `src/core/migrations/index.ts`, discoverable for tests.
+
+## Acceptance criteria (step `stp_3a866463`)
+
+- [x] Command surface documented (flags, exit codes, streaming
+      semantics).
+- [x] Execution pipeline defined stage-by-stage with failure semantics.
+- [x] Idempotency and rollback behaviours specified.
+- [x] Patch catalogue enumerated with source/target schemas.
+- [x] Open questions captured for implementation follow-up.
+
+Next step: implement the backup pass (`stp_b41a3bcc`).

package/docs/concepts/upgrade-dogfood-procedure.md

@@ -0,0 +1,114 @@
+# `brainclaw upgrade --to=1.0` — dogfood procedure
+
+Step 9 of `pln_bc6e88cc`. Runs the v1.0 schema upgrade on real stores
+before `feat/phase-3-canonical-grammar` (`pln_c6472192`) can start.
+
+## Prerequisites
+
+- CLI built from latest master: `npm run dev`.
+- Store to migrate has an accessible `.brainclaw/` (any depth).
+- **No agents actively writing** to the store during the upgrade
+  — the transaction lock will serialize but aborted writes can
+  leave half-written JSON that the patches will refuse on read.
+- Disk space: roughly 2× the current `.brainclaw/` size (for the
+  backup snapshot).
+
+## Procedure
+
+### 1. Dry-run
+
+```
+node dist/cli.js upgrade --to=1.0 --dry-run
+```
+
+Expected output (not a strict match — counts will differ per store):
+
+- `(dry run — would create backup before upgrade)`
+- `(dry run — would archive N pending candidate(s) to …/archive/candidates/<date>)`
+- `(dry run — would strip review from N handoff(s) out of M scanned)`
+- `(dry run — would stamp legacy provenance on N of M record(s))`
+- `(dry run — would bump schema 0.6.0 → 0.8.0)`
+- Plus any housekeeping actions from the pre-existing `upgrade` path
+  (legacy → entity dir moves, Zod schema doc migrations, agent file
+  refreshes).
+
+**Abort conditions** — do not proceed if the dry-run:
+- Reports any action the operator does not recognise or expect.
+- Throws an unhandled exception (a `ZodError` during the archive
+  pass, for instance, is a schema resilience regression).
+
+### 2. Apply
+
+```
+node dist/cli.js upgrade --to=1.0
+```
+
+The real run does the following in order under the store-wide lock:
+
+1. Creates a backup at `<parent>/.brainclaw.bak-<iso-ts>/` with a
+   manifest carrying the store's prior schema version.
+2. Archives pending candidates into
+   `.brainclaw/archive/candidates/<YYYY-MM-DD>/` with a typed
+   manifest. Legacy candidates that fail the current Zod schema are
+   still archived; the manifest records the parse error.
+3. Strips the `review` sub-object from every handoff that carries
+   one. Logs each mutation at
+   `.brainclaw/archive/migrations/<YYYY-MM-DD>/handoff-review-strip.json`.
+4. Stamps `provenance: { kind: 'legacy' }` on every memory record
+   (decision / constraint / trap / handoff / runtime_note) that
+   lacks a valid v1 provenance. Logs at
+   `.brainclaw/archive/migrations/<YYYY-MM-DD>/provenance-rollout.json`.
+5. Writes `.brainclaw/schema-version.json` with `current: 0.8.0`
+   and a history entry listing the patches applied.
+6. Runs the existing upgrade housekeeping (entity dir moves,
+   schema doc Zod migrations, agent file refreshes, MCP config
+   patching).
+7. Commits the memory repo if initialised.
+
+### 3. Health check
+
+```
+node dist/cli.js doctor --after-migration
+```
+
+Exits non-zero on any failure. Expected green checks:
+
+- `[provenance]` All N memory record(s) carry a valid provenance field.
+- `[handoff_review]` No handoff carries a `review` sub-object.
+- `[candidate_archive]` No pending candidates remain at
+  `coordination/inbox/` root.
+- `[schema_version]` Store is at schema 0.8.0.
+
+### 4. Spot-check
+
+- Open a few records in `.brainclaw/memory/decisions/` — every
+  file should end with `"provenance": { "kind": "legacy" }`.
+- Confirm `.brainclaw/schema-version.json` exists and shows
+  `current: "0.8.0"` plus one history entry.
+- Confirm `.brainclaw/coordination/inbox/` has no `*.json` at the
+  root (only `accepted/` and `rejected/` subdirs).
+
+## Rollback
+
+If anything looks wrong:
+
+```
+node dist/cli.js upgrade --rollback
+```
+
+Restores the most recent backup and parks the current live store at
+`<parent>/.brainclaw.rollback-<iso-ts>/`. The parked tree is kept
+for manual inspection; delete it when you have confirmed rollback is
+complete.
+
+## Dogfood sign-off
+
+The dogfood gate is considered passed once:
+
+- [ ] This machine's store migrated cleanly + doctor green.
+- [ ] Monorepo test server store migrated cleanly + doctor green.
+- [ ] No manual intervention was needed beyond what this doc lists.
+
+Once both checkmarks are ticked, `pln_c6472192` (Phase 3 grammar
+refactor) can start. Capture any manual interventions inline in this
+doc for future operators.

package/docs/context-format-changelog.md

@@ -1,12 +1,12 @@
 # Context Format Changelog
 
-## 1.3
+## 1.3 (planned / not yet emitted as `context_schema`)
 
 - Added `available_capabilities` field to structured context containing registered project capabilities with metadata (id, name, category)
 - Added `available_tools` field to structured context containing registered project tools with metadata (id, name, type)
 - Enhanced text output to include "Available Capabilities" and "Available Tools" sections when metadata is present
 - Added discovery hints pointing users to `bclaw_get_capabilities`, `bclaw_list_tools`, and `bclaw_search_tools` MCP tools
-- Kept the contract additive and backward-compatible with `1.2`
+- These fields are currently additive enrichments around the `1.2` contract; update `CONTEXT_SCHEMA_VERSION` before treating this section as the shipped schema version
 
 ## 1.2
 

package/docs/context-format.md

@@ -1,6 +1,6 @@
 # Context Format
 
-`brainclaw context` and `bclaw_get_context` expose a versioned public contract for agent consumers.
+`brainclaw context` (CLI) and `bclaw_context` (MCP) expose a versioned public contract for agent consumers.
 
 Current version: `1.2`
 
@@ -26,7 +26,7 @@ Current version: `1.2`
 
 ## `1.2` additions over `1.1`
 
-- `context_diff` is available for session-aware deltas through `brainclaw context --since-session` and `bclaw_get_context`.
+- `context_diff` is available for session-aware deltas through `brainclaw context --since-session` (CLI) and `bclaw_context(kind="delta", since=<session_id>)` (MCP).
 - `context_schema: 1.2` is emitted across JSON, markdown, template, and MCP structured content.
 
 ## `1.1` additions over `1.0`

package/docs/index.md

@@ -0,0 +1,68 @@
+# Documentation Index
+
+Use this page as the entry point into the packaged Markdown documentation.
+
+## Getting Started
+
+- [quickstart.md](quickstart.md) — fastest onboarding path for a new project (greenfield)
+- [quickstart-existing-project.md](quickstart-existing-project.md) — joining a project that already has `.brainclaw/`
+- [server-operations.md](server-operations.md) — remote server, DGX, SSH, and multi-project operator workflow
+- [integrations/overview.md](integrations/overview.md) — integration model by agent surface
+
+## Guides
+
+- [integrations/mcp.md](integrations/mcp.md) — recommended runtime path for MCP-capable agents
+- [integrations/agents.md](integrations/agents.md) — agent integration principles and setup details
+- [release-maintenance.md](release-maintenance.md) — release checklist for CLI/MCP/context-schema changes
+- [review.md](review.md) — reflective workflow and candidate promotion
+- [storage.md](storage.md) — storage model and canonical vs derived state
+- [security.md](security.md) — security model and guardrails
+
+## Concepts
+
+- [concepts/memory.md](concepts/memory.md)
+- [concepts/plans-and-claims.md](concepts/plans-and-claims.md)
+- [concepts/runtime-notes.md](concepts/runtime-notes.md)
+- [concepts/coordination.md](concepts/coordination.md)
+- [concepts/multi-agent-workflows.md](concepts/multi-agent-workflows.md)
+- [concepts/workspace-bootstrapping.md](concepts/workspace-bootstrapping.md)
+- [concepts/troubleshooting.md](concepts/troubleshooting.md) — runbook for degraded coordination state
+- [concepts/memory-staleness.md](concepts/memory-staleness.md)
+- [concepts/loop-engine.md](concepts/loop-engine.md)
+- [concepts/ideation-loop.md](concepts/ideation-loop.md) — memory-confrontation ideation loop (v1.5.0+)
+- [concepts/mcp-governance.md](concepts/mcp-governance.md)
+
+## Reference
+
+- [cli.md](cli.md) — CLI reference
+- [context-format.md](context-format.md) — public context contract
+- [context-format-changelog.md](context-format-changelog.md)
+- [mcp-schema-changelog.md](mcp-schema-changelog.md)
+
+## Agent-Specific Notes
+
+- [integrations/claude-code.md](integrations/claude-code.md)
+- [integrations/codex.md](integrations/codex.md)
+- [integrations/cursor.md](integrations/cursor.md)
+- [integrations/copilot.md](integrations/copilot.md)
+- [integrations/continue.md](integrations/continue.md)
+- [integrations/roo.md](integrations/roo.md)
+- [integrations/windsurf.md](integrations/windsurf.md)
+- [integrations/opencode.md](integrations/opencode.md)
+- [integrations/kilocode.md](integrations/kilocode.md)
+- [integrations/mistral-vibe.md](integrations/mistral-vibe.md)
+- [integrations/openclaw.md](integrations/openclaw.md)
+
+## Audience Design Constraints
+
+Internal design reference — constraints that guide brainclaw development per target audience.
+
+- [playbooks/productivity/](playbooks/productivity/index.md) — end-users & solo devs
+- [playbooks/team/](playbooks/team/index.md) — teams & ops
+- [playbooks/integration/](playbooks/integration/index.md) — AI builders
+
+## Design And Proposals
+
+- [architecture/project-refs.md](architecture/project-refs.md) — target navigation model, not the fully shipped surface
+- [product/positioning.md](product/positioning.md)
+- [adapters/openclaw.md](adapters/openclaw.md)