Add brains/sovereign-v3/README.md

brains/sovereign-v3/README.md

@@ -11,8 +11,11 @@ TeacherV2/StudentV2 blueprint.
 > behavior. Its real weapons: **return conditioning (RPO)**,
 > **opponent-intent mirrors** and **one-step dynamics** (trained on
 > labels the shards already contain), a **win-probability critic**, a
-> **multi-scale attention cortex**, and an optional **GRU memory**. It is
-> not a planner — search is the documented roadmap, not a promise.
+> **multi-scale attention cortex**, an optional **GRU memory**, and now
+> **MCTS planning over the learned dynamics** (search.py) with
+> **league self-play** (league.py) and **wake-sleep distillation**
+> (distill.py). It plans — with the honest caveats stated in
+> search.py's docstring (fixed rollout pct, abstract latent).
 
 ---
 
@@ -20,10 +23,13 @@ TeacherV2/StudentV2 blueprint.
 
 | File | What |
 |---|---|
-| `model.py` | the whole model, torch-only. Run `python model.py` for the CPU smoke test (prints exact per-module params + shape checks). |
-| `data_adapters.py` | shard → training samples: RTG, AWR weights, intent-mirror masks, next-frame labels, win labels, sequence windows. `python data_adapters.py` smoke-tests it. |
-| `ARCHITECTURE.md` | design reasoning, module table, memory math, citations. |
-| `train_notes.md` | the exact recipe: Stage A (return-conditioned filtered BC + dynamics), Stage B (RPO with KL guard, league-lite), Stage C (eval + wake-sleep distill), ablations, risks. |
+| `model.py` | the whole model, torch-only (~290M incl. the MuZero-lite planning block). Run `python model.py` for the CPU smoke test (exact per-module params + shape checks). |
+| `search.py` | MCTS planning (PUCT over the learned dynamics) — `python search.py` smoke-tests it. |
+| `league.py` | league-lite self-play pool (frozen past selves, Elo, promotion). |
+| `distill.py` | wake-sleep teacher→student distillation (+ search-target distillation). |
+| `data_adapters.py` | shard → training samples: RTG, AWR weights, intent mirrors, next-frame labels, win labels, consecutive-frame dynamics targets. `python data_adapters.py` smoke-tests it. |
+| `ARCHITECTURE.md` | design reasoning, module table, memory math, planning section, citations. |
+| `train_notes.md` | the exact recipe: Stage A (return-conditioned BC + world model), Stage B (RPO + AlphaZero-lite visit distillation + league), Stage C (eval + wake-sleep), ablations, risks. |
 | `sovereign_v3_init.pt` | optional random-init checkpoint (seed 0), exported by the upload script. |
 
 ## Input/output contract (the pipeline's fair-play rule)