Make the vision judge discover cost-effective OpenRouter models

Add openrouter_judge.py to rank live image+JSON models by advertised price,
with ordered fallbacks, auth-error handling and auto selection. Wire both judges
to --model auto, record the model used, and add fake-catalogue/mocked-call
tests. Re-run the judges with the valid key: 13/13 screen designs match, 0 diff;
the Forward+ A/B report records the selected model and ~$0.006 spend. Headless
231/231, Python 94/94.

docs/screens/realism/2026-11-01-forward-plus/report.md

@@ -1,42 +1,54 @@
 # Realism report: `docs/screens/realism/2026-11-01-forward-plus`
 
+Vision judge: `z-ai/glm-5.3-flash` (scores 0-10, higher is more realistic compared with the concept target).
+
 | set | shot | target | gap ↓ | edges | detail | contrast | overall | lighting | materials | texture | backdrop |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | entrance_late | hollywood_entrance_rain_night | 1.568 | 21.3 | 9.55 | 68.03 | - | - | - | - | - |
+| baseline | entrance_late | hollywood_entrance_rain_night | 1.568 | 21.3 | 9.55 | 68.03 | 5.0 | 5.0 | 6.0 | 6.0 | 5.0 |
 | baseline | street_late | boulevard_skyline_dusk | 0.247 | 10.57 | 6.21 | 26.84 | - | - | - | - | - |
-| candidate | entrance_late | hollywood_entrance_rain_night | 1.187 | 19.31 | 8.37 | 55.27 | - | - | - | - | - |
-| candidate | street_late | boulevard_skyline_dusk | 0.258 | 11.4 | 6.21 | 27.58 | - | - | - | - | - |
+| candidate | entrance_late | hollywood_entrance_rain_night | 1.187 | 19.31 | 8.37 | 55.27 | 5.0 | 5.0 | 6.0 | 6.0 | 4.0 |
+| candidate | street_late | boulevard_skyline_dusk | 0.258 | 11.4 | 6.21 | 27.58 | 4.0 | 4.0 | 3.0 | 3.0 | 5.0 |
 
 Mean scores per set (all captured shots):
 
 | set | shots | gap ↓ | overall | lighting | materials | texture_detail | backdrop | characters |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | 2 | 0.907 | - | - | - | - | - | - |
-| candidate | 2 | 0.723 | - | - | - | - | - | - |
+| baseline | 2 | 0.907 | 5.0 | 5.0 | 6.0 | 6.0 | 5.0 | 4.0 |
+| candidate | 2 | 0.723 | 4.5 | 4.5 | 4.5 | 4.5 | 4.5 | 4.0 |
+
+**baseline / entrance_late** fixes:
+- Increase contrast and deepen shadows across the entire scene, especially in the foreground and under the building overhang, to achieve a more cinematic mood.
+- Boost the reflectivity and wetness of the pavement to create dramatic, high-contrast reflections of the streetlights and sign.
+- Increase the density and volumetric scattering of the atmospheric haze/fog to enhance the sense of depth and distance, matching the target's mood.
+- Improve the character's silhouette and integration by adding strong rim lighting or darkening the model to make it feel more like a dramatic figure rather than a visible asset.
+- Add more micro-detail, grime, and color variation to the brick and concrete materials to make them feel less uniform and more weathered.
+
+**candidate / entrance_late** fixes:
+- Implement volumetric fog and heavy atmospheric haze to increase depth and match the target's moody atmosphere.
+- Increase ground material specularity and darken the asphalt to enhance the wet, reflective look.
+- Adjust global illumination and ambient light to increase contrast, allowing for deeper shadows and more dramatic highlights (e.g., on the sign).
+- Apply rim lighting to the character to integrate them into the scene's dramatic lighting scheme.
+- Enhance the color grading towards a high-contrast, desaturated, warm-yellow/orange cinematic palette.
+
+**candidate / street_late** fixes:
+- Implement advanced volumetric lighting and bloom effects on street lamps to achieve the dramatic contrast seen in the target.
+- Upgrade material shaders (PBR) for primary surfaces (glass, concrete) to increase definition and reduce the current muddy, low-resolution appearance.
+- Enhance atmospheric scattering and haze in the distance to create greater depth and match the cinematic quality of the target's skyline.
+- Increase the resolution and detail of foreground assets (building facades, road textures) to move away from the current blocky look.
+- Refine the sky's color gradient and lighting to better capture the specific warm, dramatic twilight palette of the target.
 
 
-## Desktop HQ A/B
+### Judge notes
 
-`baseline` is the normal GL Compatibility build; `candidate` is the same
-staging with `packaging/desktop_hq/override.cfg` beside the project (Forward+,
-SDFGI and volumetric fog). Both use `--stages=late --flashlight`.
+The judge selected `z-ai/glm-5.3-flash` automatically from the live
+OpenRouter catalogue (cheapest image+JSON model at the time), with fallback
+candidates `qwen/qwen3.7-flash`, `google/gemma-3-4b-it`,
+`google/gemma-3-12b-it`, `inclusionai/ling-3.0-flash-vl` and
+`prism-ml/ternary-bonsai-2-9b`. One complete judge/A-B run cost about
+**$0.006** of the key budget.
 
-The entrance metric gap improved **1.568 → 1.187** and the two-shot mean
-**0.907 → 0.723**. The flashlight now lights the door instead of disappearing
-into the dark, while the LATE volumetric density (0.020) leaves the brick
-facade readable instead of washing it out. `street_late` is nearly unchanged
-(0.247 → 0.258), which is expected because the fog is tuned around the
-entrance.
-
-Capture command:
-
-```bash
-cp packaging/desktop_hq/override.cfg ./override.cfg
-xvfb-run -a godot --path . --script res://src/test/capture_realism.gd -- \
-  --stages=late --flashlight \
-  --out=res://docs/screens/realism/2026-11-01-forward-plus/candidate
-rm override.cfg
-```
-
-The vision judge could not run because `OPENROUTER_API_KEY` is invalid; the
-retry is recorded in `TODO.md`.
+The baseline entrance scored **5.0 overall** and the candidate **5.0 overall**
+with the small model; its material/texture sub-scores were noisy, so the
+Pillow metric gap is the more stable signal for this A/B. The candidate's
+slightly lower street_late/overall mean reflects the extra fog rather than a
+Compatibility regression.