feat(sim): forest carries real multi-strength Right variants

Ran the baker for the forest scale: real flow-stabilized painterly Right variants
1-4 now back the dreamlike axis on real Yosemite footage (was: 1 real + 3 ffmpeg
placeholders). By-eye finding this surfaced: sd-turbo's painterly transform is
sharply non-linear in img2img strength (barely registers <0.5, ramps hard through
~0.5-0.65), so the initial linear 0.28-0.58 ramp left levels 1-3 ~identical to
raw. Re-baked with a clustered 0.46/0.52/0.58/0.64 curve -> a real perceptual
ramp: gentle dream haze -> clearly impressionist -> strongest, each notch visibly
dreamier, temporally calm (flow-stabilized).

- manifest: forest right_variants 1-4 all model 'sd-turbo+farneback-flow'
- setup_sample_media.py: now only stages the neutral base; the baker owns the
  Right variants, so re-running it never clobbers a real bake
- docs: USER_GUIDE setup steps + ROADMAP v2v vertical-slice-done note

Suite 228 passed / 2 skipped.

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

simulator/bake_right_variants.py

@@ -35,10 +35,14 @@ MEDIA = Path(__file__).parent / "sample_media"
 
 RIGHT_LEVELS = (1, 2, 3, 4)
 
-# Keyframe img2img strength per Right level (by-eye ramp). Level 4 ~ the POC's
-# proven painterly look (key-strength 0.5-0.58); level 1 is a barely-there dream
-# haze. Tune by eye in the sim, then re-bake.
-_KEY_STRENGTH = {1: 0.28, 2: 0.38, 3: 0.48, 4: 0.58}
+# Keyframe img2img strength per Right level (by-eye ramp). sd-turbo's painterly
+# transformation is sharply NON-LINEAR in strength — it barely registers below
+# ~0.5 and ramps hard through ~0.5-0.65 (verified by eye, session 0012: a linear
+# 0.28-0.58 ramp left levels 1-3 ~indistinguishable from raw). So the curve is
+# clustered in that active band for real perceptual progression: a gentle dream
+# haze (L1) -> clearly painterly (L3, ~the POC's proven look) -> strongest (L4).
+# Still by-eye tunable — re-run the baker after editing.
+_KEY_STRENGTH = {1: 0.46, 2: 0.52, 3: 0.58, 4: 0.64}
 _TWEEN_RATIO = 0.36  # POC ratio (0.18 / 0.5): tweens are a light refine only.
 
 # The restyle target (matches the POC spike that the operator approved).

simulator/sample_media/manifest.json

@@ -25,9 +25,9 @@
       "license": "poc-sample (look-tuning only; not shipped content)",
       "source": "hef-poc/out/neutral.mp4",
       "right_variants": {
-        "1": {"file": "forest/right1.mp4", "model": "placeholder"},
-        "2": {"file": "forest/right2.mp4", "model": "placeholder"},
-        "3": {"file": "forest/right3.mp4", "model": "placeholder"},
+        "1": {"file": "forest/right1.mp4", "model": "sd-turbo+farneback-flow"},
+        "2": {"file": "forest/right2.mp4", "model": "sd-turbo+farneback-flow"},
+        "3": {"file": "forest/right3.mp4", "model": "sd-turbo+farneback-flow"},
         "4": {"file": "forest/right4.mp4", "model": "sd-turbo+farneback-flow"}
       },
       "annotations": [

simulator/setup_sample_media.py

@@ -1,52 +1,33 @@
-"""Populate simulator/sample_media/forest/ from the session-0008 POC artifacts.
+"""Stage the forest scale's neutral BASE clip from the session-0008 POC artifacts.
 
-Copies the real neutral base + the real flow-stabilized Right restyle out of
-~/hef-poc/out/, and generates placeholder intermediate Right strengths (1..3) by
-blending the base toward the real restyle with ffmpeg. The media binaries are
-gitignored; only the manifest is committed. Sample footage is for look-tuning
-only, not shipped content.
+Copies the real neutral Yosemite base out of ~/hef-poc/out/ into
+simulator/sample_media/forest/. The real multi-strength Right variants are then
+produced by the offline baker (`simulator/bake_right_variants.py`) — this script
+no longer generates placeholder Right strengths, so re-running it never clobbers
+a real bake. The media binaries are gitignored; only the manifest is committed.
+Sample footage is for look-tuning only, not shipped content.
 
-Usage:  python simulator/setup_sample_media.py
-Requires: ffmpeg on PATH (or `pip install imageio-ffmpeg`), and ~/hef-poc/out/.
+Usage:
+    python simulator/setup_sample_media.py          # stage the base
+    python -m simulator.bake_right_variants --scale forest   # then bake variants
+Requires: ~/hef-poc/out/neutral.mp4 (the POC neutral base).
 """
 
 from __future__ import annotations
 
 import shutil
-import subprocess
 from pathlib import Path
 
 POC = Path.home() / "hef-poc" / "out"
 DEST = Path(__file__).parent / "sample_media" / "forest"
 
 
-def _ffmpeg() -> str:
-    if shutil.which("ffmpeg"):
-        return "ffmpeg"
-    import imageio_ffmpeg
-    return imageio_ffmpeg.get_ffmpeg_exe()
-
-
 def main() -> None:
     DEST.mkdir(parents=True, exist_ok=True)
     base = DEST / "base.mp4"
-    right4 = DEST / "right4.mp4"
     shutil.copyfile(POC / "neutral.mp4", base)
-    shutil.copyfile(POC / "right_flow.mp4", right4)
-    ff = _ffmpeg()
-    # Placeholder strengths 1..3: opacity-blend base toward the real restyle.
-    for strength, alpha in ((1, 0.25), (2, 0.5), (3, 0.75)):
-        out = DEST / f"right{strength}.mp4"
-        subprocess.run(
-            [ff, "-y", "-i", str(base), "-i", str(right4),
-             "-filter_complex",
-             f"[1:v]format=yuva444p,colorchannelmixer=aa={alpha}[top];"
-             f"[0:v][top]overlay=shortest=1[v]",
-             "-map", "[v]", "-an", str(out)],
-            check=True,
-        )
-        print(f"generated {out.name} (alpha {alpha})")
-    print(f"sample media ready in {DEST}")
+    print(f"staged {base} (real POC neutral base)")
+    print("next: python -m simulator.bake_right_variants --scale forest")
 
 
 if __name__ == "__main__":