docs: point parent design at reconciliation; roadmap + user guide for sim alteration

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/USER_GUIDE.md

@@ -287,11 +287,23 @@ Records point at files via `file_path`. Those files live on the player's drive,
 `file_path` values consistent with wherever you mount that drive on the machine
 that will eventually run the room.
 
-## Playing with the simulator (curator's X-ray)
+## Playing with the simulator (alteration preview)
 
 The simulator is a web stand-in for the installation's control panel. It runs the
-real `hef.selection` code against a synthetic catalog so you can feel whether the
-dials surface fitting pieces before any hardware exists.
+real `player.alteration` engine and **alters** a neutral base clip toward the knob
+state in the browser, so you can tune the *look* of the filter before any hardware
+exists. (The earlier selection-era "curator's X-ray" view was retired when the
+piece moved from *selecting* clips to *altering* them.)
+
+**One-time setup — populate the sample footage** (look-tuning only; not shipped
+content):
+
+    python simulator/setup_sample_media.py
+
+This copies the session-0008 POC artifacts (`~/hef-poc/out/`) into
+`simulator/sample_media/forest/` — the neutral base clip and the real
+flow-stabilized Right restyle — and generates placeholder intermediate Right
+strengths. The `.mp4` binaries are gitignored.
 
 **Run it (Docker):**
 
@@ -304,11 +316,22 @@ then open http://localhost:8000.
     pip install -e ".[sim]"
     make sim-local
 
-**What you see:** the five real dials (mode + Left/Right/Dark/Light), the model
-knobs (brain/mood weights, pool size, approved-only), and the X-ray — the picked
-piece, the ranked candidate pool with distances, and brain/mood coordinate maps
-showing where your knob point and the candidates sit.
+**What you see and can do:**
 
-By default it loads a generated fixture catalog. To point it at a real catalog,
-set `HEF_SIM_CATALOG=catalog/library.jsonl` (used automatically when that file is
-non-empty).
+- **Content dial** — picks audio/video channel; "off" and audio-only positions go
+  to black walls.
+- **Four experience knobs (0–4):**
+  - **Dark / Light** — a live runtime color grade (cool/dark ↔ warm/bright; equal
+    or zero = the raw footage).
+  - **Right (dreamlike)** — selects a discrete pre-baked, flow-stabilized restyle
+    variant and crossfades to it (strength 0 = raw base).
+  - **Left (analytical)** — a live overlay: labelled boxes from the clip's authored
+    annotation track, with more annotations appearing at higher levels. Text is
+    shaped live (the simulator analogue of the Pi's Pango/HarfBuzz path).
+- **Calibration sliders** — adjust the grade/overlay gain curves live; once a look
+  is liked, bake the values into `DEFAULT_CALIBRATION` in `player/alteration.py`.
+- **RenderPlan readout** — always shows the exact numbers the engine produced (the
+  project's honesty "X-ray," now over the alteration model).
+
+The base clips, Right variants, Left annotation track, and string tables come from
+`simulator/sample_media/manifest.json`.