Add dev scripts + simplify CLAUDE.md

CLAUDE.md

@@ -4,39 +4,20 @@
 Kids mental math app. Correct answers earn AI-generated cute animal images (FLUX.1-schnell).
 Stack: Python · Gradio · diffusers · HuggingFace Spaces (ZeroGPU).
 
-## Mandatory dev loop — follow for EVERY change
-
-```
-1. CODE   → edit files
-2. SYNTAX → ~/miniforge3/bin/python3 -c "import ast; [ast.parse(open(f).read()) for f in ['app.py','image_generator.py','math_engine.py']]"
-3. IMPORT → ~/miniforge3/bin/python3 -c "import app" 2>&1   # catches version conflicts & bad imports
-             must produce NO errors (warnings OK)
-   SDK CHK → verify README.md sdk_version matches local gradio (HF Spaces pins gradio to sdk_version):
-             python3 -c "
-             import re, subprocess
-             sdk = re.search(r'sdk_version: \"(.+?)\"', open('README.md').read()).group(1)
-             local = subprocess.check_output(['pip','show','gradio']).decode()
-             ver = re.search(r'Version: (.+)', local).group(1)
-             assert sdk == ver, f'MISMATCH: README sdk_version={sdk} but local gradio={ver}'
-             print(f'✅ sdk_version {sdk} matches local gradio')
-             " 2>&1
-4. RUN    → kill previous instance, start fresh:
-             pkill -f "python3 app.py"; ~/miniforge3/bin/python3 app.py > /tmp/numzoo.log 2>&1 &
-             sleep 10 && cat /tmp/numzoo.log   # must show no errors
-5. TEST   → run Puppeteer (arm64 Node):
-             arch -arm64 /bin/zsh -c "source ~/.nvm/nvm.sh && nvm use 20 && cd /Users/uplab/projects/puppeteer && node test_lovemath.mjs"
-             → take screenshots, read them, verify visually
-6. FIX    → if any step fails, fix and restart from step 1
-7. PUSH   → only when all steps pass:
-             git add -A && git commit -m "..." && git push origin main
-```
-
-**Version pinning rules:**
-- **Never put `gradio` in `requirements.txt`** — HF Spaces installs it separately using `sdk_version` from README.md frontmatter. Conflicting versions cause build failure.
-- **Always keep `sdk_version` in README.md in sync with local gradio** — run the SDK check above before every push.
-- To upgrade gradio: update `sdk_version` in README.md, reinstall locally (`pip install gradio==x.y.z`), re-run full loop.
-
-**Never push broken code.** If Puppeteer tests fail, do not proceed to push.
+## Mandatory dev loop
+Run these scripts in order before every push. Fix failures before proceeding.
+
+| Step | Command | Must pass |
+|------|---------|-----------|
+| Syntax | `bash scripts/syntax.sh` | No syntax errors |
+| Imports | `bash scripts/check_imports.sh` | No import errors |
+| SDK version | `bash scripts/check_sdk.sh` | README sdk_version == local gradio |
+| Run | `bash scripts/run.sh` | App starts, no errors in logs |
+| Test | `bash scripts/test.sh` | All Puppeteer checks pass, screenshots look correct |
+
+Full loop shortcut: `bash scripts/dev.sh` (runs steps 1–4, then run test.sh manually).
+
+**Never push if any step fails.**
 
 ## Key files
 
@@ -45,8 +26,9 @@ Stack: Python · Gradio · diffusers · HuggingFace Spaces (ZeroGPU).
 | `app.py` | Gradio UI, game logic, panel visibility, event wiring |
 | `image_generator.py` | FLUX.1-schnell pipeline, emoji→text prompt builder |
 | `math_engine.py` | Question generation, level names & thresholds |
-| `requirements.txt` | Python dependencies (HF Spaces uses Python 3.13) |
-| `README.md` | HF Spaces config (frontmatter) + user docs |
+| `requirements.txt` | Python dependencies — never include `gradio` here |
+| `README.md` | HF Spaces config (frontmatter `sdk_version`) + user docs |
+| `scripts/` | Dev loop automation scripts |
 
 ## Architecture
 
@@ -54,36 +36,35 @@ Stack: Python · Gradio · diffusers · HuggingFace Spaces (ZeroGPU).
 
 **Game state dict keys:**
 `name`, `level`, `score`, `streak`, `correct_since_reward`, `level_correct`,
-`question`, `answer`, `selected_animals`, `selected_places`,
-`future` (ThreadPoolExecutor Future), `awaiting_reward`
+`question`, `answer`, `selected_animals`, `selected_places`, `generate_now`
 
 **Reward trigger:** every `REWARD_EVERY = 3` correct answers.
-Image generation starts in background (ThreadPoolExecutor) as soon as quiz begins.
+Image generated via `.then()` chaining on the Check button — synchronous, within Gradio request context (required for ZeroGPU).
 
 ## Gradio rules
-- Use `gr.update(visible=True/False)` — never return bare `True/False` for component visibility
+- Use `gr.update(visible=True/False)` for visibility — never return bare booleans
 - Theme and CSS go in `demo.launch(css=..., theme=...)`, NOT in `gr.Blocks()`
-- `gr.Group` has no `.change()` event — use explicit output returns from handlers
-- HF Spaces runs Python 3.13 — watch for removed stdlib modules (`audioop` → add `audioop-lts`)
+- `gr.Group` has no `.change()` event
+- Never put `gradio` in `requirements.txt` — HF Spaces pins it via `sdk_version` in README
+- Keep `sdk_version` in README in sync with local gradio (run `scripts/check_sdk.sh`)
 
 ## Python runtime
 - **Local:** `~/miniforge3/bin/python3` (arm64, Python 3.13, torch 2.12, MPS)
-- **HF Spaces:** Python 3.13, ZeroGPU (A100 on demand via `@spaces.GPU`)
-- **DO NOT use** `/usr/local/bin/python3` — it's x64 Rosetta, torch 2.2, incompatible with latest diffusers
+- **HF Spaces:** Python 3.13, ZeroGPU (A100 via `@spaces.GPU`)
+- Do not use system Python (`/usr/local/bin/python3`) — it's x64 Rosetta, incompatible
 
 ## Image generation
-- Model: `black-forest-labs/FLUX.1-schnell` (gated — must accept license on HF)
-- Local speed: ~5 min on MPS · HF ZeroGPU: ~5 sec
-- Always wrap generation in try/except → return `(None, "")` on failure
+- Model: `black-forest-labs/FLUX.1-schnell` (gated — accept license on HF before first run)
+- Local: ~5 min on MPS · HF ZeroGPU: ~5 sec
+- Always wrap in try/except → return `(None, "")` on failure
 - `IS_HF_SPACE = os.environ.get("SPACE_ID") is not None` controls ZeroGPU decorator
 
 ## HuggingFace deployment
 - Space: `https://huggingface.co/spaces/Goumsss/numzoo`
-- Remote: `https://huggingface.co/spaces/Goumsss/numzoo` (already set)
-- Push = redeploy. Space rebuilds automatically on every push.
-- ZeroGPU requires HF Pro or hackathon grant (set in Space Settings → Hardware)
+- Push = redeploy. Rebuilds automatically.
+- ZeroGPU: set in Space Settings → Hardware (requires HF Pro or hackathon grant)
 
 ## UI/UX principles
-- Text: English, minimal — **words not sentences** (kids with limited English)
-- Feedback: emoji-heavy, short (`✅ Great! 🔥🔥` not `Congratulations, your answer was correct!`)
-- Never crash visibly — all handlers wrapped in try/except with safe fallback returns
+- English only, minimal text — words not sentences (kids with limited English)
+- Emoji-heavy feedback (`✅ Great! 🔥🔥` not full sentences)
+- Never crash visibly — all handlers wrapped in try/except with safe fallbacks

scripts/check_imports.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+cd "$(dirname "$0")/.."
+echo "Checking imports..."
+~/miniforge3/bin/python3 -c "import app" 2>&1
+if [ $? -eq 0 ]; then echo "✅ imports OK"; else echo "❌ import failed"; exit 1; fi

scripts/check_sdk.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+cd "$(dirname "$0")/.."
+~/miniforge3/bin/python3 - <<'EOF'
+import re, subprocess, sys
+sdk = re.search(r'sdk_version: "(.+?)"', open('README.md').read()).group(1)
+out = subprocess.check_output(['/Users/uplab/miniforge3/bin/pip','show','gradio']).decode()
+ver = re.search(r'Version: (.+)', out).group(1)
+if sdk != ver:
+    print(f'❌ MISMATCH: README sdk_version={sdk} but local gradio={ver}')
+    sys.exit(1)
+print(f'✅ sdk_version {sdk} matches local gradio')
+EOF

scripts/dev.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+set -e
+DIR="$(dirname "$0")"
+echo "=== 1/4 Syntax ===" && bash "$DIR/syntax.sh"
+echo "=== 2/4 Imports ===" && bash "$DIR/check_imports.sh"
+echo "=== 3/4 SDK ===" && bash "$DIR/check_sdk.sh"
+echo "=== 4/4 Run ===" && bash "$DIR/run.sh"
+echo ""
+echo "App is running. Now run: bash scripts/test.sh"

scripts/run.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+cd "$(dirname "$0")/.."
+pkill -f "python3 app.py" 2>/dev/null; sleep 1
+~/miniforge3/bin/python3 app.py > /tmp/numzoo.log 2>&1 &
+echo "Starting app..."
+sleep 10
+PORT=$(lsof -i :7860 -i :7861 -i :7862 -i :7863 -i :7864 -i :7865 2>/dev/null | grep LISTEN | tail -1 | grep -oE '786[0-9]')
+if [ -z "$PORT" ]; then
+    echo "❌ App failed to start. Logs:"
+    cat /tmp/numzoo.log
+    exit 1
+fi
+echo "✅ App running on http://localhost:$PORT"
+echo $PORT > /tmp/numzoo.port

scripts/syntax.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+cd "$(dirname "$0")/.."
+~/miniforge3/bin/python3 -c "
+import ast, sys
+for f in ['app.py','image_generator.py','math_engine.py']:
+    try:
+        ast.parse(open(f).read())
+        print(f'✅ {f}')
+    except SyntaxError as e:
+        print(f'❌ {f}: {e}')
+        sys.exit(1)
+"

scripts/test.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+cd "$(dirname "$0")/.."
+PORT=$(cat /tmp/numzoo.port 2>/dev/null || echo "7864")
+# Update port in test file
+sed -i '' "s|http://localhost:[0-9]*/|http://localhost:$PORT/|g" /Users/uplab/projects/puppeteer/test_lovemath.mjs
+arch -arm64 /bin/zsh -c "source ~/.nvm/nvm.sh && nvm use 20 && cd /Users/uplab/projects/puppeteer && node test_lovemath.mjs"