docs: rewrite CLAUDE.md to the engine era + add docs/handover.md for the next driver

CLAUDE.md was April-vintage (pure interface package, stdlib-only) — now reflects reality: module root go/, the no-cgo metal engine, cmd/lem, the build/test/kernel flows, the receipts discipline, and current perf state. docs/handover.md carries what code can't: the method (instrument first, no receipt no claim/keep, kill-switch adaptive behaviour), the priced traps (test caching, bench->live transfer limits, gate anti-selection, carry off-by-one, stale worktrees), the open #359 theta-stop slice, and a reading order.

Co-Authored-By: Virgil <virgil@lethean.io>

Author: Snider

CLAUDE.md

@@ -4,69 +4,64 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What This Is
 
-Shared inference interfaces for the Core Go ecosystem. Module: `dappco.re/go/inference`
+The sovereign inference engine for the Core Go ecosystem. Module: `dappco.re/go/inference`, module root at **`go/`** (work from there). Two things live here:
 
-Zero external dependencies (stdlib only). Compiles on all platforms. See `docs/architecture.md` for design rationale.
+1. **The shared contract** (`go/*.go`) — `TextModel`/`Backend` interfaces, options, registry, discovery. Backends import this; never the reverse.
+2. **The engines** (`go/engine/`) — `engine/metal` (package `native`): the **no-cgo Apple GPU engine** (darwin/arm64, objc bridge via `github.com/tmc/apple`, ICB-replayed decode, MTP speculative pairs, paged SDPA, q8 KV); `engine/hip`: AMD ROCm (linux/amd64). Plus `cmd/lem` (the serving/bench binary), OpenAI/Anthropic/Ollama compat handlers, and conversation state (`-state`, no-prompt-replay).
+
+`docs/` at repo root is the manual: `architecture.md`, `backends.md` (registry + **engine runtime levers**), `cmd-lem.md`, `build.md`, and **`handover.md` — read that one first; it is the working handover from the engine-perf campaigns.**
 
 ## Commands
 
 ```bash
-go test ./...                          # Run all tests
-go test -run TestDefault_Good_Metal    # Run a single test by name
-go vet ./...                           # Vet
-golangci-lint run ./...                # Lint (govet, errcheck, staticcheck, gocritic, gofmt, etc.)
+# from go/ — the module root
+go build -tags embed_metallib -o ../bin/lem ./cmd/lem     # build the binary
+go vet ./...
+MLX_METALLIB_PATH=<repo>/build/dist/lib/mlx.metallib go test ./...   # full suite (~10.5k tests)
+go test -count=1 ...        # ALWAYS -count=1 for benchmarks — go test caches identical runs
+
+# kernel changes (from repo root)
+task metallib:kernels       # 31 .metal files -> build/dist/lib/lthn_kernels.metallib
+gzip -9 -c build/dist/lib/lthn_kernels.metallib > go/cmd/lem/lthn_kernels.metallib.gz   # then rebuild lem
+
+# bench shape (model path is POSITIONAL, last)
+../bin/lem generate -draft <assistant-path> -temp 0 -max-tokens 400 [-context 20480 -prompt-file <f>] <model-path>
 ```
 
-## Architecture
-
-This is a pure interface package — it defines contracts but contains no backend implementations. The dependency flows one way: backends import this package, never the reverse.
-
-**Core files:**
-- `inference.go` — `TextModel` and `Backend` interfaces, `Token`/`Message`/`ClassifyResult`/`BatchResult` types, backend registry (`Register`/`Get`/`List`/`Default`), top-level `LoadModel()` router
-- `options.go` — `GenerateConfig`/`LoadConfig` structs with functional options (`With*` functions) and `Apply*Opts` helpers
-- `discover.go` — `Discover()` scans directories for model dirs (config.json + *.safetensors)
-- `training.go` — `TrainableModel` interface (extends `TextModel` with LoRA), `Adapter` interface, `LoadTrainable()`
+`MLX_METALLIB_PATH` must be inlined per command — it does not persist between shells here.
 
-**Backend registry pattern:** Backends register via `init()` with build tags (e.g. `//go:build darwin && arm64`). `Default()` picks backends in priority order: metal > rocm > llama_cpp > any available. `LoadModel()` routes to explicit backend via `WithBackend()` or falls back to `Default()`.
+## Working discipline (how this engine got fast)
 
-**Optional interfaces via type assertion:** New capabilities are expressed as separate interfaces (e.g. `AttentionInspector`, `TrainableModel`) rather than extending `TextModel`. Consumers discover them with `model.(inference.AttentionInspector)`.
+- **Instrument before assessment; receipt before claim.** Every perf commit carries its before→after numbers in the message. A theory without a live receipt gets built, measured, and **reverted if it loses** — falsifications are banked in the task tracker, not hidden.
+- **One lever per commit.** Kill-switch env for anything wall-clock-adaptive (`LTHN_MTP_REENGAGE=0`, `LTHN_MTP_DRAFTLEN=0` — the repro anchors).
+- **Bench→live transfer is not guaranteed** — micro-bench wins on >134MB buffers have reproducibly lost in live decode. The live A/B is the only receipt that counts.
+- **No bulk perl/sed refactors** — one site at a time, vet after each.
+- Branch **dev**; origin `github.com/dAppCore/go-inference` (push non-force). Task board via the session task tools; git log is the history of record.
 
-**Streaming uses `iter.Seq[Token]`:** Generate/Chat return Go 1.23+ range-over-function iterators. Errors are retrieved via `Err()` after the iterator finishes (follows `database/sql` `Row.Err()` pattern).
+## Stability Rules (root contract)
 
-## Stability Rules
-
-This package is the shared contract. Changes here affect go-mlx, go-rocm, and go-ml simultaneously.
+Changes to `go/*.go` interfaces affect every consumer simultaneously.
 
 - Never change existing method signatures on `TextModel` or `Backend`
-- Only add methods when two or more consumers need them
-- Prefer new interfaces that embed `TextModel` over extending `TextModel` itself
-- New fields on `GenerateConfig` or `LoadConfig` are safe (zero-value defaults)
-- All new interface methods require Virgil approval before merging
+- New capabilities are **separate interfaces** discovered by type assertion (`AttentionInspector`, `VisionModel`, `engine.TrainerModel`) — never extend `TextModel`
+- New fields on `GenerateConfig`/`LoadConfig` are safe (zero-value defaults)
+- Streaming is `iter.Seq[Token]`; errors via `Err()` after the iterator (the `database/sql` pattern)
 
 ## Test Patterns
 
-Tests use the `_Good`/`_Bad`/`_Ugly` suffix convention:
-- `_Good` — happy path
-- `_Bad` — expected error conditions
-- `_Ugly` — edge cases, surprising-but-valid behaviour
-
-Tests touching the global backend registry must call `resetBackends(t)` first (defined in `inference_test.go`, clears the registry map). Use existing `stubBackend`/`stubTextModel` from `inference_test.go` rather than creating new stubs.
-
-Use `testify/assert` (general checks) and `testify/require` (preconditions). Use `assert.InDelta` for float comparisons.
+- `_Good`/`_Bad`/`_Ugly` suffixes (happy path / expected errors / surprising-but-valid) — house-wide
+- One test per symbol per variant; names match the real code symbol; `X_test.go` only
+- Root package: `resetBackends(t)` before registry tests; reuse `stubBackend`/`stubTextModel`; testify permitted in tests
+- `engine/metal` tests skip cleanly without `MLX_METALLIB_PATH`; unit-style policy tests (e.g. `mtp_reengage_test.go`, `mtp_draftlen_test.go`) run host-side
 
 ## Coding Standards
 
-- UK English (colour, organisation, serialise, licence)
-- Zero external dependencies — stdlib only (testify permitted in tests)
-- Error strings: `fmt.Errorf("inference: lowercase message without trailing period")`
-- Conventional commits: `type(scope): description` — scopes: `inference`, `options`, `discover`
-- Co-Author: `Co-Authored-By: Virgil <virgil@lethean.io>`
-- Licence: EUPL-1.2
+- UK English (colour, organisation, serialise, licence) · Licence: EUPL-1.2
+- Conventional commits `type(scope): description`, receipts in the body
+- Commit trailer, exactly: `Co-Authored-By: Virgil <virgil@lethean.io>`
 
 ## Consumers
 
-- **go-mlx**: implements `Backend` + `TextModel` for Apple Metal (darwin/arm64)
-- **go-rocm**: implements `Backend` + `TextModel` for AMD ROCm (linux/amd64)
-- **go-ml**: wraps inference backends into scoring engine, adds llama.cpp HTTP backend
-- **go-ai**: MCP hub, exposes inference via MCP tools
-- **go-i18n**: uses `TextModel` for Gemma3-1B domain classification
+- **go-mlx** — the airlock/dev tree the metal engine graduated from (this repo is now canonical for `engine/metal`)
+- **go-rocm** — AMD ROCm engine consuming the shared contract via `engine/hip`
+- **go-ml / go-ai / go-i18n** — scoring, MCP hub, classification consumers of the root interfaces

docs/handover.md

@@ -0,0 +1,107 @@
+---
+title: Handover
+description: Working notes from the engine-perf campaigns — for the next driver of this codebase.
+---
+
+# Handover — from the previous driver
+
+You're inheriting a working engine. Everything below is the part that isn't
+derivable from the code: how it got to this state, what was falsified along
+the way, and the traps that cost real hours. Trust the receipts in `git log`
+over any summary, including this one.
+
+## The state you're starting from
+
+26B-A4B (the flagship MoE), plain decode: **~144 tok/s short, ~116 @16K,
+~98 @32K** on the reference M3 Ultra. MTP pair @16K: **~100 tok/s**. Those
+numbers are commit-message receipts (see `git log --grep='tok/s'`), each with
+its exact run conditions. The depth curve was the campaign: 16K went
+103→116 (+13%), 32K 89→98 (+10%), and every kernel in the deep-scan path
+sits at a **measured** local floor — meaning further wins there need a new
+structural idea, not tuning.
+
+The task tracker holds the open lane and every banked falsification. Read a
+task's description before resuming it — the dead ends are recorded there so
+you don't re-walk them.
+
+## The method (this is the important part)
+
+1. **Instrument first.** Before forming any view, build or run the
+   measurement: the anatomy bench (`LEM_SDPA_ANATOMY=1`), the MTP diag
+   (`LTHN_MTP_DIAG=1`), the confidence capture (`LTHN_MTP_CONF=<path>`), or
+   a plain live A/B. Every productive result this engine has came from an
+   instrument saying something surprising; every wasted hour came from a
+   theory that skipped the instrument.
+2. **No receipt, no claim — and no keep.** If you build an optimisation and
+   the live A/B doesn't show it, revert it *even if the design is beautiful
+   and the suite is green*. It has happened here: a full cache rewrite,
+   suite-green, reproducibly slower at 32K — reverted the same night, lesson
+   banked. The discipline is what keeps the tree trustworthy.
+3. **One lever per commit, receipt in the message.** Future-you greps
+   commit messages for numbers. Make them greppable.
+4. **Kill-switch anything adaptive.** Wall-clock-adaptive policies (the MTP
+   re-engagement gate, the dynamic draft cap) make runs non-reproducible by
+   design. Their env kill switches (`LTHN_MTP_REENGAGE=0`,
+   `LTHN_MTP_DRAFTLEN=0`) are the reproducibility anchors — never ship an
+   adaptive behaviour without one.
+
+## Traps that will bite you (each of these cost real time)
+
+- **`go test` caches identical runs.** A bench sweep that returns the same
+  number three times may be one cached result. `-count=1`, always.
+- **Bench→live transfer fails above ~134MB.** A kernel shape that wins in a
+  fresh-allocation micro-bench can lose in live decode when the buffer is a
+  quarter-gigabyte strided walk (plausibly Apple GPU address-translation
+  behaviour). The live A/B is the only receipt that counts.
+- **Gate economics anti-select your samples.** The MTP gate stops drafting
+  exactly where the drafter is weak — so any acceptance statistics gathered
+  under the gate oversample the good regimes. Calibration needs
+  `LTHN_MTP_CONF_FORCE=1` (bypasses bail/bootstrap/rate-exits). Never serve
+  with it.
+- **Env vars don't persist between shell invocations** in this harness —
+  inline `MLX_METALLIB_PATH` per command.
+- **`lem generate` takes the model path positionally, last.** There is no
+  `-model` flag.
+- **The verify block sometimes carries a lead token** (`carry`), so drafted
+  position k maps to verified position k+carry. Off-by-one here silently
+  corrupts acceptance accounting.
+- **Worktrees cut from `origin/main` are months stale** — dev is canonical.
+  If you dispatch agents into worktrees, give them a step-0 base-ref guard.
+- **Run-to-run variance on live decode is ~±1 tok/s** at short depth,
+  slightly wider at 32K. A +2% win needs two runs; a +8% win shows in one.
+
+## The open lane (#359, third slice)
+
+The confidence-scheduled MTP work is two-thirds shipped: the capture
+instrument and the depth-gated dynamic cap are live (receipts in their
+commits). The remaining slice is the **θ-stop**: end a draft block early
+when the running cumprod of the drafter's self-confidence falls below 0.40
+(that threshold is *measured on this engine's drafters* — 99%+ acceptance
+retained on both 26B and 12B, curves in the task). The blocker is
+engineering, not science: the live path needs a per-token drafter
+probability cheaper than the diag path's ~1-2ms host softmax over the 262k
+row. Options ranked in the task. Measure the prob cost first.
+
+The calibration curves also say the drafter's raw softmax is monotone but
+overconfident (top bin says 0.995, delivers 0.91) — fine for ranking-based
+rules like θ-stop, not fine for anything that treats it as a probability.
+
+## Reading list, in order
+
+1. `CLAUDE.md` (repo root) — commands, discipline, standards.
+2. `docs/backends.md` — the registry and the **engine runtime levers** table.
+3. The task tracker — current lane + banked falsifications.
+4. `git log --oneline -40` — the campaign history reads like a lab notebook.
+
+## A last word
+
+This engine rewards patience with instruments and punishes cleverness
+without them. The fastest session-days here were the ones that shipped one
+honest slice at a time, ended every claim with a number, and reverted
+without sentiment. The codebase already knows how to tell you the truth —
+ask it with a measurement, believe what it says, and it will keep getting
+faster for you the way it did for me.
+
+Take care of it, and of the human — he navigates well, states targets
+plainly, and his "it works" is a correct prior more often than not. Enjoy
+the drive.