Docs: update CLAUDE.md + README for FLUX.2-klein-4B

- Reflect model switch (FLUX.1-schnell → FLUX.2-klein-4B) everywhere
- Document persistent cache behaviour + path-bump recovery pattern
- Note NUMZOO_STYLE shared constant between app and dataset generator

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -1,7 +1,7 @@
 # NumZoo — Agent Guidelines
 
 ## What this project is
-Kids mental math app. Correct answers earn AI-generated cute animal images (FLUX.1-schnell).
+Kids mental math app. Correct answers earn AI-generated cute animal images (FLUX.2-klein-4B).
 Stack: Python · Gradio · diffusers · HuggingFace Spaces (ZeroGPU).
 
 ## Mandatory dev loop
@@ -24,7 +24,7 @@ Full loop shortcut: `bash scripts/dev.sh` (runs steps 1–4, then run test.sh ma
 | File | Role |
 |------|------|
 | `app.py` | Gradio UI, game logic, panel visibility, event wiring |
-| `image_generator.py` | FLUX.1-schnell pipeline, emoji→text prompt builder |
+| `image_generator.py` | FLUX.2-klein-4B pipeline, persistent cache setup, emoji→text prompt builder |
 | `math_engine.py` | Question generation, level names & thresholds |
 | `requirements.txt` | Python dependencies — never include `gradio` here |
 | `README.md` | HF Spaces config (frontmatter `sdk_version`) + user docs |
@@ -75,10 +75,22 @@ This is more reliable in Gradio 6 than toggling visibility on gr.HTML components
 - Do not use system Python (`/usr/local/bin/python3`) — it's x64 Rosetta, incompatible
 
 ## Image generation
-- Model: `black-forest-labs/FLUX.1-schnell` (gated — accept license on HF before first run)
-- Local: ~5 min on MPS · HF ZeroGPU: ~5 sec
+- Model: `black-forest-labs/FLUX.2-klein-4B` (Apache 2.0 — accept license on HF before first run)
+- Same model local + HF Spaces. 4 steps, `guidance_scale=1.0`, 512×512
+- Local: float16 on MPS (needs ~13GB, fits in 32GB unified mem) · HF ZeroGPU: ~fast on A100
+- Pipeline class: `Flux2KleinPipeline` (diffusers ≥ 0.38)
 - Always wrap in try/except → return `(None, "")` on failure
 - `IS_HF_SPACE = os.environ.get("SPACE_ID") is not None` controls ZeroGPU decorator
+- Logs generation time (`✅ Generated in Xs`)
+
+## Persistent model cache (HF Spaces)
+- `/data/hf_cache_v4` mount caches the model across restarts (set in Space Settings → Storage)
+- Setup is **bulletproof**: poisoned/partial cache is auto-wiped & re-downloaded;
+  any `/data` failure falls back to ephemeral container cache; import never crashes
+- If the cache tree gets poisoned again (`[Errno 20] Not a directory`), bump the
+  path suffix (`_v4` → `_v5`) to escape it — established repo pattern
+- `NUMZOO_STYLE` constant in `image_generator.py` is the single source of truth for
+  the art style; `scripts/generate_dataset.py` imports it so training captions match
 
 ## HuggingFace deployment
 - Space: `https://huggingface.co/spaces/Goumsss/numzoo`

README.md

@@ -38,7 +38,7 @@ A mental math app for kids — answer questions, earn cute AI-generated animal i
 
 ## Image model
 
-Rewards generated with **FLUX.1-schnell** (12B params, Apache 2.0) via 🤗 Diffusers.  
+Rewards generated with **FLUX.2-klein-4B** (4B params, Apache 2.0) via 🤗 Diffusers.  
 Images start generating in the background as soon as the quiz begins.
 
 ## Run locally
@@ -49,8 +49,8 @@ Images start generating in the background as soon as the quiz begins.
 # 1. Install dependencies
 ~/miniforge3/bin/pip install -r requirements.txt
 
-# 2. Accept FLUX.1-schnell license on HuggingFace
-#    → https://huggingface.co/black-forest-labs/FLUX.1-schnell
+# 2. Accept FLUX.2-klein-4B license on HuggingFace
+#    → https://huggingface.co/black-forest-labs/FLUX.2-klein-4B
 #    Then log in:
 hf auth login