@jonathangu/openclawbrain 0.3.0

package/docs/END_STATE.md

@@ -0,0 +1,244 @@
+# OpenClawBrain v2 — Definitive End-State Guide
+
+This is the canonical implementation guide for finishing the current repo to an honest 1.0.
+
+The correct posture is:
+
+- **no reroll**
+- **keep the current trunk**
+- **preserve the inherited lossless-claw substrate**
+- **finish proof, operator hardening, evidence quality, mutation gating, and packaging truth**
+
+## Canonical surfaces
+
+These files should anchor future work:
+
+- `README.md` — public front door and fast operator truth
+- `docs/RELEASE_CONTRACT.md` — what is true now vs not frozen vs not done
+- `docs/END_STATE.md` — this implementation guide
+- `docs/EVIDENCE.md` — proof ladder and artifact contract
+- `scripts/validate-openclaw-install.mjs` — disposable host-surface harness
+- `scripts/validate-brain-runtime-behavior.ts` — deterministic runtime proof harness
+
+## Keep these boundaries intact
+
+### Protected inherited substrate — do not rewrite casually
+These are inherited LCM / lossless-claw surfaces and should stay stable unless a failing test forces a narrow change:
+
+- `src/assembler.ts`
+- `src/compaction.ts`
+- `src/engine.ts`
+- `src/expansion*.ts`
+- `src/retrieval.ts`
+- `src/store/*`
+- `src/summarize.ts`
+- `src/transcript-repair.ts`
+- `tui/*`
+
+### Hard guardrails
+- Do **not** add intermediate shaping rewards to the core learning rule.
+- Do **not** replace the stochastic learning-time policy with a deterministic scorer.
+- Do **not** let serving read mutable training state.
+- Do **not** treat old planning docs or archived prototypes as authority.
+
+## Current code map
+
+### Runtime decisioning and assembly
+- `src/brain-runtime/assembler-extension.ts`
+- `src/brain-runtime/service.ts`
+- `src/brain-runtime/tools.ts`
+- Tests: `test/brain-runtime/assembler-extension.test.ts`, `test/brain-runtime/service.test.ts`
+
+### Brain core
+- `src/brain-core/traverse.ts`
+- `src/brain-core/policy.ts`
+- `src/brain-core/update.ts`
+- `src/brain-core/pack.ts`
+- `src/brain-core/replay.ts`
+- `src/brain-core/mutator.ts`
+- Tests: `test/brain-core/*.test.ts`
+
+### Evidence pipeline
+- `src/brain-runtime/harvester-extension.ts`
+- `src/brain-runtime/evidence-detectors.ts`
+- `src/brain-harvest/human.ts`
+- `src/brain-harvest/self.ts`
+- `src/brain-harvest/scanner.ts`
+- `src/brain-store/store.ts`
+- `src/brain-store/migrations.ts`
+- `src/brain-worker/worker.ts`
+- Tests: `test/brain-runtime/harvester.test.ts`, `test/brain-worker/worker.test.ts`, `test/engine.test.ts`
+
+### Child worker and operator surface
+- `src/brain-runtime/service.ts`
+- `src/brain-worker/child-runner.ts`
+- `src/brain-cli.ts`
+- `openclaw.plugin.json`
+- Tests: `test/brain-runtime/service.test.ts`
+
+### Validation and release proof
+- `scripts/validate-openclaw-install.mjs`
+- `scripts/validate-brain-runtime-behavior.ts`
+- `docs/EVIDENCE.md`
+- `docs/evidence/`
+
+## Finish order
+
+## Phase 0 — Align repo truth with repo reality
+
+Goal: make it obvious, within a minute, what is already real, what is implemented-but-not-frozen, and what is still open.
+
+### Work in
+- `README.md`
+- `docs/RELEASE_CONTRACT.md`
+- `docs/END_STATE.md`
+- `docs/EVIDENCE.md`
+
+### What success looks like
+- the README front page does not contradict the current code
+- no duplicate root planning docs compete with the canonical docs set
+- another session can orient from the docs above without spelunking old plans
+
+## Phase 1 — Finish the real host-surface validation harness
+
+Goal: prove behavior on the actual OpenClaw host surface, not just the lower-level runtime harness.
+
+### Main files
+- `scripts/validate-openclaw-install.mjs`
+- `scripts/validate-brain-runtime-behavior.ts`
+- `src/brain-runtime/assembler-extension.ts`
+- `src/brain-runtime/service.ts`
+- `src/brain-runtime/tools.ts`
+- future: `.github/workflows/validate-openclaw-install.yml`
+
+### Already true
+- recurrent host routing checks run
+- shadow-mode host assertion wiring exists
+- current local-Ollama harness runs end to end on the non-skipped matrix
+
+### Still open
+- adapt the current OpenClaw host seam first (`plugins.slots.contextEngine` / `api.registerContextEngine` drift), then rerun host-path proof on that repaired boundary
+- deterministic host-surface worker-down / last-promoted-pack fail-open proof
+- explicit `skip_no_embedding` and `skip_uninitialized` assertions on the host surface
+- frozen evidence bundle per run under `docs/evidence/YYYY-MM-DD/<git-sha>/`
+- short-static-lookup host semantics on the adapted current host seam
+
+### Key reality to remember
+`openclaw agent --local` currently exposes session targeting, timeout, delivery, and verbose controls, but no explicit deterministic “force this tool call” control. Deterministic `brain_teach` proof is now closed by the session-bound harness; raw host-path semantic claims still have to respect the current host/plugin seam that actually exists.
+
+## Phase 2 — Harden the child worker
+
+Goal: make the child worker the real learner boundary without affecting serving.
+
+### Main files
+- `src/brain-runtime/service.ts`
+- `src/brain-runtime/worker-supervisor.ts`
+- `src/brain-worker/child-runner.ts`
+- `src/brain-worker/protocol.ts`
+- `src/brain-cli.ts`
+- `test/brain-runtime/service.test.ts`
+
+### What is already real
+- `brainWorkerMode` supports `child` and `in_process`
+- child lifecycle logic now lives behind `WorkerSupervisor` instead of staying embedded in `service.ts`
+- explicit worker protocol messages now exist for `ready`, `heartbeat`, `reload-graph`, `reload-graph-ack`, `tick-result`, `shutdown`, and `fatal-error`
+- restart accounting and richer operator truth now surface through runtime status + CLI doctor/status
+- `in_process` is now marked and surfaced as a dev-only fallback
+- crash / stale-lease / second-writer / reload-ack coverage now exists in `test/brain-runtime/service.test.ts`
+
+### What remains
+- keep child-worker operator truth frozen while later phases evolve the evidence pipeline and replay bundle gates
+- preserve the narrow production claim: serving continues from immutable promoted packs even when the worker crashes or restarts
+
+## Phase 3 — Finish the evidence pipeline
+
+Goal: make structured evidence tied to exact episodes the dominant learning input.
+
+### Main files
+- `src/brain-runtime/harvester-extension.ts`
+- `src/brain-runtime/evidence-detectors.ts`
+- `src/brain-harvest/human.ts`
+- `src/brain-harvest/self.ts`
+- `src/brain-harvest/scanner.ts`
+- `src/brain-worker/worker.ts`
+- `src/brain-store/store.ts`
+- `src/brain-store/migrations.ts`
+
+### What is already real
+- `brain_evidence` and `brain_resolved_labels` exist
+- explicit episode attribution improved materially
+- trust-ordered one-winner-per-episode resolution is real
+- `brain_teach` records evidence metadata against the corrected episode path
+
+### What remains
+- expand evidence schema (`messageId`, `partId`, `toolName`, `command`, `exitCode`, `filesTouched`, `artifactPath`, `taughtNodeId`, `correctedEpisodeId`)
+- push harvesters toward raw evidence only, with final label resolution in the worker
+- reduce “most recent message” fallback to a genuine fallback
+- build richer scanner extractors (runbook/tool-chain/reuse/bridge/issue→PR→commit)
+
+## Phase 4 — Replay-gated mutation bundles
+
+Goal: stop thinking proposal-by-proposal and move to bundle-level replay decisions.
+
+### Main files
+- `src/brain-core/mutator.ts`
+- `src/brain-core/pack.ts`
+- `src/brain-worker/worker.ts`
+- `src/brain-store/store.ts`
+- `src/brain-store/migrations.ts`
+
+### Current truth
+Mutation proposals and replay-gated promotion exist, but the bundle-level end state does not.
+
+### What remains
+- persist mutation bundles
+- cluster proposals by graph neighborhood
+- evaluate bundles against comparative replay (`base` vs `candidate`)
+- reject on regression / collapse / context bloat / orphan spikes
+- keep split/merge behind flags until the bundle harness is strong enough
+
+## Phase 5 — Freeze the proof ladder
+
+Goal: make public claims map to frozen artifact evidence.
+
+### Main files
+- `docs/EVIDENCE.md`
+- `docs/evidence/`
+- `scripts/validate-openclaw-install.mjs`
+- `scripts/validate-brain-runtime-behavior.ts`
+- `test/brain-runtime/service.test.ts`
+- `test/brain-core/replay.test.ts`
+
+### What remains
+- define proof ladder levels clearly
+- require date/SHA artifact directories
+- capture host-install evidence bundles, not just ad hoc command output
+- add release-candidate summary markdown for every serious release proof run
+
+## Phase 6 — Clean packaging and type surface
+
+Goal: make installation and operator recovery boring.
+
+### Main files
+- future: `src/openclaw-sdk-compat.ts` (or equivalent compatibility wrapper)
+- `tsconfig.json`
+- `package.json`
+- `openclaw.plugin.json`
+- `README.md`
+
+### What remains
+- isolate SDK drift behind a narrow compatibility boundary
+- make `npx tsc --noEmit` green
+- document `brainWorkerMode=child` as the practical default
+- clarify embedding support as tested reality, not wishful compatibility
+- verify package contents with `npm pack --dry-run`
+
+## What to ignore now
+
+Do not use removed root planning docs or archived prototype code as design authority. The canonical truth lives in:
+
+- `README.md`
+- `docs/RELEASE_CONTRACT.md`
+- `docs/END_STATE.md`
+- `docs/EVIDENCE.md`
+- the current runtime/tests/scripts in `src/`, `test/`, and `scripts/`

package/docs/EVIDENCE.md

@@ -0,0 +1,128 @@
+# OpenClawBrain v2 — Evidence Ladder
+
+This document defines what proof must exist before public claims are treated as frozen.
+
+## Artifact layout
+
+Store release and benchmark artifacts under:
+
+```text
+docs/evidence/YYYY-MM-DD/<git-sha>/
+```
+
+Each bundle should contain at minimum:
+
+- `status.json`
+- `doctor.json`
+- `trace.json`
+- `validation-report.json`
+- `config-snapshot.json`
+- `logs.txt`
+- `summary.md`
+
+For Level 4 host-install runs, the bundle should also include the pre-run diagnostic ladder outputs:
+
+- `status-all.txt`
+- `gateway-probe.txt`
+- `gateway-status.txt`
+- `channels-status.txt`
+
+If a proof run is partial, the `summary.md` should say exactly what was and was not proven.
+
+## Proof ladder
+
+### Level 1 — Mechanism proofs
+
+Purpose: prove the math/runtime primitives in isolation.
+
+Primary surfaces:
+- `test/brain-core/policy.test.ts`
+- `test/brain-core/traverse.test.ts`
+- `test/brain-core/update.test.ts`
+- `test/brain-core/seed-policy.test.ts`
+- `test/brain-runtime/service.test.ts`
+- `test/brain-runtime/harvester.test.ts`
+- `src/brain-runtime/worker-supervisor.ts`
+- `src/brain-worker/protocol.ts`
+- `scripts/validate-brain-runtime-behavior.ts`
+
+Required claims:
+- finite-horizon traversal with `STOP`
+- full-trajectory update behavior
+- seed routing is learnable
+- immediate `brain_teach` retrieval works
+- serve-from-last-promoted-pack survives worker crash at runtime level
+- child-worker supervision records restart truth, reload acknowledgements, stale-lease takeover, and second-writer refusal
+- raw harvesting preserves multiple concurrent evidence signals with extractor metadata before worker-side trust resolution collapses them into labels
+- structured tool-result/function-output parts can generate self-evidence even when flattened stored text is empty
+- explicit episode attribution, resolver attribution, and recent-conversation fallback are all audited rather than implied
+
+### Level 2 — Recorded replay proofs
+
+Purpose: prove candidate changes do not regress protected behavior.
+
+Primary surfaces:
+- `src/brain-core/replay.ts`
+- `src/brain-core/pack.ts`
+- `src/brain-worker/worker.ts`
+- `test/brain-core/replay.test.ts`
+
+Required claims:
+- promotion replay gate blocks regressions
+- human-positive episodes do not regress silently
+- candidate packs explain why they passed or failed
+
+### Level 3 — Shadow proofs
+
+Purpose: prove the runtime can record decisions safely without injecting learned context.
+
+Primary surfaces:
+- `src/brain-runtime/assembler-extension.ts`
+- `src/brain-runtime/service.ts`
+- `scripts/validate-openclaw-install.mjs`
+
+Required claims:
+- shadow mode records episode/trace ids
+- shadow mode does not visibly inject the brain block
+- host-surface status/trace stay truthful
+
+### Level 4 — Disposable host-install proofs
+
+Purpose: prove the plugin on the real OpenClaw host surface.
+
+Primary surfaces:
+- `scripts/validate-openclaw-install.mjs`
+- future: `.github/workflows/validate-openclaw-install.yml`
+- `openclaw.plugin.json`
+- `README.md`
+
+Required claims:
+- recurrent route used
+- static lookup bypassed when appropriate, or the remaining host-surface drift is explicitly classified/truth-frozen
+- shadow mode recorded
+- `brain_teach` proven by a deterministic session-bound harness (`scripts/validate-brain-teach-session-bound.ts`) with 20/20 identical passes, or honestly classified as out of scope for raw prompt-driven host proof
+- worker-down host proof stays narrow: last-promoted-pack serving continues and host status surfaces unhealthy/exit truth
+- `skip_no_embedding` and `skip_uninitialized` asserted explicitly
+
+## Release checklist
+
+Do not claim a release candidate is fully proven unless the artifact bundle includes:
+
+- the exact commit SHA
+- the validation command(s)
+- the model + embedding configuration used
+- pass/fail results for host harness assertions
+- status and doctor snapshots
+- at least one trace proving the routed path being claimed
+- a short markdown summary of what remains open
+
+## Current proof truth
+
+As of the current trunk:
+
+- **Level 1:** materially real
+- **Level 2:** present but not yet bundle-complete
+- **Level 3:** partially real on the host surface
+- **Level 4:** not frozen; deterministic session-bound `brain_teach` proof now exists under `docs/evidence/YYYY-MM-DD/<git-sha>/brain-teach-session-bound/`, short-static host classification is currently truth-frozen as stale current-OpenClaw host seam drift under `docs/evidence/YYYY-MM-DD/<git-sha>/short-static-classification/`, and the final narrow worker-down host claim still remains open
+
+That means the repo is already beyond theory-only, but it does **not** yet have a frozen release-evidence ladder.

package/docs/RELEASE_CONTRACT.md

@@ -0,0 +1,91 @@
+# OpenClawBrain v2 — Release Contract
+
+This is the fast truth surface for the repo.
+
+Use these public labels consistently:
+
+- **paper-faithful core**
+- **live-path implemented**
+- **operationally validated**
+
+Current truthful state:
+
+- **paper-faithful core:** yes
+- **live-path implemented:** yes
+- **operationally validated:** not yet
+
+That is the contract. The repo is already beyond "foundation only," but it is not yet at an honest 1.0 operating state.
+
+## 1. True in code now
+
+These are safe public claims today.
+
+### Paper-faithful routing core
+- **Finite-horizon traversal with `STOP`**
+  - Code: `src/brain-core/traverse.ts`, `test/brain-core/traverse.test.ts`
+- **Terminal reward with baseline, not shaping rewards**
+  - Code: `src/brain-core/episode.ts`, `src/brain-core/update.ts`, `src/brain-worker/worker.ts`, `test/brain-core/update.test.ts`
+- **Stochastic policy over actions**
+  - Code: `src/brain-core/policy.ts`, `src/brain-core/traverse.ts`, `test/brain-core/policy.test.ts`
+- **Full-trajectory REINFORCE updates**
+  - Code: `src/brain-core/update.ts`, `src/brain-worker/worker.ts`, `test/brain-core/integration.test.ts`
+- **Learned seed routing as part of the policy surface**
+  - Code: `src/brain-core/types.ts`, `src/brain-core/traverse.ts`, `src/brain-core/update.ts`, `src/brain-store/store.ts`, `test/brain-core/seed-policy.test.ts`
+- **Immutable promoted packs for serving**
+  - Code: `src/brain-core/pack.ts`, `src/brain-runtime/service.ts`, `src/brain-store/store.ts`, `test/brain-runtime/service.test.ts`
+
+### Live runtime path
+- **Explicit runtime decisions** (`use_brain`, `shadow`, named skip modes)
+  - Code: `src/brain-runtime/assembler-extension.ts`, `test/brain-runtime/assembler-extension.test.ts`
+- **Correction-first assembly**
+  - Code: `src/brain-runtime/assembler-extension.ts`
+- **Immediate `brain_teach` retrieval path**
+  - Code: `src/brain-runtime/service.ts`, `src/brain-runtime/tools.ts`, `test/brain-runtime/service.test.ts`
+- **Episode and trace recording on the live path**
+  - Code: `src/brain-runtime/service.ts`, `src/brain-core/trace.ts`, `test/brain-runtime/service.test.ts`
+- **Serve from the last promoted pack even when the worker is unavailable**
+  - Code: `src/brain-runtime/service.ts`, `test/brain-runtime/service.test.ts`, `scripts/validate-brain-runtime-behavior.ts`
+- **Child-worker mode exists and is real**
+  - Code: `openclaw.plugin.json`, `src/brain-runtime/service.ts`, `src/brain-worker/child-runner.ts`, `test/brain-runtime/service.test.ts`
+
+## 2. Implemented but not frozen
+
+These are real enough to build on, but not frozen enough to oversell.
+
+- **Host-surface validation harness**
+  - Current files: `scripts/validate-openclaw-install.mjs`, `scripts/validate-brain-runtime-behavior.ts`, `scripts/validate-short-static-classification.ts`
+  - Truth: recurrent routing, shadow mode, and current host checks run inside a dedicated sterile validation lane with per-run diagnostic artifacts; deterministic session-bound `brain_teach` proof now exists, but the current raw host lane is blocked by stale OpenClaw seam drift (`plugins.slots.contextEngine` rejected, `api.registerContextEngine` removed) and the final narrow worker-down host claim is still incomplete.
+  - Boundary: raw prompt-driven `openclaw agent --local` is **not** the release proof boundary for `brain_teach`; that claim is now closed by the deterministic session-bound harness rather than raw host prompting.
+  - Boundary: short-static host drift is currently truth-frozen as stale current-OpenClaw host seam drift, not as a resolved semantic behavior claim.
+  - Boundary: worker-down host proof is claimed only at the exact host-visible boundary actually proven (continued serving from the last promoted pack + unhealthy worker status / exit truth), not as a stronger deterministic crash-observation claim.
+- **Child-worker serving boundary**
+  - Current files: `src/brain-runtime/service.ts`, `src/brain-runtime/worker-supervisor.ts`, `src/brain-worker/child-runner.ts`, `src/brain-worker/protocol.ts`, `src/brain-cli.ts`
+  - Truth: the child worker now runs behind a dedicated supervisor boundary with explicit protocol messages, restart accounting, reload acknowledgements, lease protection, and stronger status/doctor truth. `in_process` mode remains available only as a dev-only fallback and must not be treated as the production operator boundary.
+- **Raw evidence → resolved labels flow**
+  - Current files: `src/brain-runtime/harvester-extension.ts`, `src/brain-runtime/evidence-detectors.ts`, `src/brain-harvest/*.ts`, `src/brain-worker/worker.ts`, `src/brain-store/store.ts`, `src/engine.ts`
+  - Truth: explicit evidence tables and trust-ordered resolution are real; harvested assistant/tool messages can now persist multiple concurrent raw signals with extractor metadata before worker resolution, and structured tool-result/function-output parts now feed self-evidence detection before regex fallback. The remaining gap is that source extraction itself still leans heavily on heuristics, especially for scanner-style evidence.
+- **Replay-gated promotion**
+  - Current files: `src/brain-core/replay.ts`, `src/brain-core/pack.ts`, `src/brain-worker/worker.ts`
+  - Truth: promotion gates exist, but mutation evaluation is still closer to proposal-by-proposal than bundle-level replay decisions.
+
+## 3. Not done yet
+
+These are still active work and must not be described as complete.
+
+- **Frozen host-surface proof for worker-down fail-open on the current host seam**
+  - Primary files: `scripts/validate-openclaw-install.mjs`, `scripts/validate-brain-teach-session-bound.ts`, `scripts/validate-short-static-classification.ts`, `src/brain-runtime/tools.ts`, `src/brain-runtime/service.ts`
+  - Required truth before this is marked done: keep deterministic session-bound `brain_teach` proof frozen, adapt the current OpenClaw host seam, and then land a narrow host worker-down claim that matches the actual artifact bundle.
+- **Resolved short-static-lookup host-surface semantics on the adapted current host seam**
+  - Primary files: `src/brain-runtime/assembler-extension.ts`, `scripts/validate-openclaw-install.mjs`, `scripts/validate-short-static-classification.ts`
+- **Bundle-based mutation evaluation with clear pass/fail explanations**
+  - Primary files: `src/brain-core/mutator.ts`, `src/brain-worker/worker.ts`, `src/brain-store/store.ts`, `src/brain-store/migrations.ts`
+- **Frozen proof ladder with dated release artifacts**
+  - Primary files: `docs/EVIDENCE.md`, `docs/evidence/`, `scripts/validate-openclaw-install.mjs`
+- **Green full-repo `npx tsc --noEmit`**
+  - Primary files: `tsconfig.json`, `package.json`, SDK-boundary imports
+- **Boring install / recovery path for another operator**
+  - Primary files: `README.md`, `docs/configuration.md`, `openclaw.plugin.json`, future release workflow/evidence files
+
+## Safe public summary
+
+> OpenClawBrain v2 already has a paper-faithful routing core and a real live runtime path. What remains is the operational hardening, host-surface proof, mutation-bundle evaluation, and release-evidence layer.

package/docs/agent-tools.md

@@ -0,0 +1,106 @@
+# Agent tools
+
+OpenClawBrain exposes two tool families:
+
+1. **LCM recall tools** — search and expand compacted conversation history
+2. **Brain runtime tools** — teach the live routing layer, inspect status, inspect traces
+
+## LCM recall tools
+
+Use these when you need recall from compacted history.
+
+### Escalation pattern: `lcm_grep` → `lcm_describe` → `lcm_expand_query`
+
+1. **`lcm_grep`** — find relevant summaries or messages by keyword/regex
+2. **`lcm_describe`** — inspect a specific summary or file cheaply
+3. **`lcm_expand_query`** — deep recall through bounded sub-agent expansion
+
+Start with grep. Expand only when the summary is too compressed for the task.
+
+### `lcm_grep`
+Search across messages and/or summaries using regex or full-text search.
+
+### `lcm_describe`
+Read the full content and metadata for a summary or stored large file.
+
+### `lcm_expand_query`
+Answer a focused question by expanding summaries through the DAG.
+
+### `lcm_expand`
+Low-level DAG expansion tool used internally by the delegated expansion sub-agent.
+
+## Brain runtime tools
+
+Use these when working with the learned routing layer directly.
+
+### `brain_teach`
+Teach the brain a correction or reusable guidance.
+
+Current truth:
+- immediate retrieval is wired into the runtime
+- taught nodes are embedded immediately when embeddings are configured
+- taught corrections bind most strongly when invoked from a live tool session on the active conversation
+
+Primary code:
+- `src/brain-runtime/tools.ts`
+- `src/brain-runtime/service.ts`
+- `test/brain-runtime/service.test.ts`
+
+### `brain_status`
+Inspect operator/runtime truth for the brain layer.
+
+Typical surfaces include:
+- enabled / disabled state
+- embedding configuration truth
+- worker mode / PID / heartbeat / health
+- current promoted pack metadata
+- last assembly decision
+- graph/health counters
+
+Primary code:
+- `src/brain-runtime/tools.ts`
+- `src/brain-runtime/service.ts`
+- `src/brain-cli.ts`
+
+### `brain_trace`
+Inspect the most recent trace or a specific trace id.
+
+Typical surfaces include:
+- chosen seed
+- seed scores
+- fired nodes
+- pack version
+- route footer / summary
+- episode linkage
+
+Primary code:
+- `src/brain-runtime/tools.ts`
+- `src/brain-runtime/service.ts`
+- `src/brain-core/trace.ts`
+
+## When to use what
+
+- Need compacted history recall? use **LCM tools**
+- Need to teach/update the current routing layer? use **`brain_teach`**
+- Need current runtime/operator truth? use **`brain_status`**
+- Need to inspect a specific routing decision? use **`brain_trace`**
+
+## Prompting guidance for agents
+
+A good agent prompt should make both tool families explicit:
+
+```markdown
+## Memory and routing tools
+
+For recall from compacted history:
+- `lcm_grep`
+- `lcm_describe`
+- `lcm_expand_query`
+
+For the live learned routing layer:
+- `brain_teach`
+- `brain_status`
+- `brain_trace`
+
+Use LCM tools for recall. Use brain tools only when you are teaching or auditing the routing layer itself.
+```