docs/ROADMAP.md

@@ -123,6 +123,22 @@ longer *select* a pre-tagged clip; they drive an **alteration engine** (design
 
 Plan: [`2026-06-05-player-alteration-core.md`](./superpowers/plans/2026-06-05-player-alteration-core.md).
 
+**Slice 2 — simulator-first alteration preview ✅ Done.** Merged to `main`
+(session 0009). Wires the alteration engine into the web simulator so the look is
+tunable by eye before any hardware, and **reconciles** the unmerged session-0007
+design with the merged session-0008 design (the Left-HUD conflict): Left is a
+**runtime overlay** (authored annotation track + per-language string tables),
+Right is a **discrete pre-baked** flow-stabilized variant, Dark/Light a **live**
+grade — superseding 0007's baked-HUD 5×5 grid. Engine: a parameterized
+`Calibration` (tuned by eye, baked into `DEFAULT_CALIBRATION`), `Restyle.variant`
+(discrete) replacing the continuous blend, and `AnalyticalOverlay.level`. Sim:
+`/api/alteration` + `/api/clips` over `simulator/clips.py`, an alteration-preview
+UI, and one neutral clip with a real flow-stabilized Right variant from the POC.
+Design:
+[`2026-06-07-reconciled-simulator-alteration-slice-design.md`](./superpowers/specs/2026-06-07-reconciled-simulator-alteration-slice-design.md);
+plan:
+[`2026-06-07-reconciled-simulator-alteration-slice.md`](./superpowers/plans/2026-06-07-reconciled-simulator-alteration-slice.md).
+
 **Remaining slices (not started):**
 
 - **Runtime renderer** — drive the single panoramic projector via mpv/ffmpeg;
@@ -134,7 +150,12 @@ Plan: [`2026-06-05-player-alteration-core.md`](./superpowers/plans/2026-06-05-pl
   `Controls` stream).
 - **White-noise generation** — runtime white/pink noise for that content position.
 - **Offline v2v variant pipeline** — author the pre-baked Right restyle variants
-  (the only paid AI step, design §9) + the multilingual label/string tables + TTS.
+  via the local flow-stabilized SD pipeline (now ~free, not a paid API — see the
+  scales-library/right-axis design §1/§4); a real multi-strength flow-stabilized
+  re-bake per base clip + the multilingual label/string tables + TTS.
+- **Scale-ring navigation** — the endless rotary encoder + short pre-baked AI
+  zoom/warp transitions between neutral "scales of nature" clips on a closed ring
+  (scales-library design §3); a new control + offline pipeline element.
 - **Catalog model changes** — audio *source* + "neutral base" vs "altered
   variant" flag (sub-project 2 territory, design §13).
 

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`.

docs/superpowers/specs/2026-06-05-machine-altered-perception-design.md

@@ -121,6 +121,13 @@ layers. This single rule covers the whole `5×5×5×5` space:
 
 ### 4.3 Where each transform runs
 
+> **Reconciled (2026-06-07, session 0009):** the Left HUD is a **runtime overlay**
+> driven by an authored annotation track + per-language string tables (text shaped
+> live); the Right axis selects a **discrete pre-baked** flow-stabilized variant
+> (not a continuous blend). See
+> [`2026-06-07-reconciled-simulator-alteration-slice-design.md`](./2026-06-07-reconciled-simulator-alteration-slice-design.md)
+> §1, which supersedes the session-0007 baked-HUD / 5×5-grid proposal.
+
 - **Runtime, on the Pi (free, continuous, full-res):** the Dark/Light color grade
   and the Left analytical overlay. These are cheap (LUT/curves + luma key, and
   text/graphics compositing) and can move continuously with the knob.
@@ -235,6 +242,13 @@ one-time build.
 
 ## 10. Accessibility, i18n, and the translation-cost finding
 
+> **Reconciled (2026-06-07, session 0009):** the near-free-i18n path is kept — the
+> Left HUD is a runtime overlay (authored annotation track + per-language string
+> tables, shaped live via Pango/HarfBuzz on the Pi). The session-0007 baked-HUD
+> reversal is **not** adopted. See
+> [`2026-06-07-reconciled-simulator-alteration-slice-design.md`](./2026-06-07-reconciled-simulator-alteration-slice-design.md)
+> §1.
+
 The piece is operable **blind, in the dark, in your language**, via four redundant
 channels on the control panel: **touch** (engraved symbol shape), **low-light
 color** (LEDs), **braille**, and **audio** (a read-aloud button on a small *local*