Upload REWRITE_PLAN.md with huggingface_hub

REWRITE_PLAN.md

@@ -0,0 +1,116 @@
+# ClashCR Rewrite Plan
+
+## 1. Research Summary
+
+### Evaluated Projects
+| Project | URL | Credibility | Visual Mode | Approach | Gaps |
+|---------|-----|-------------|-------------|----------|------|
+| KataCR | https://github.com/wty-yy/katacr | ★★★★★ Academic paper | Live + Replay | YOLO unit detection + ResNet hand classifier + RL policy | Does NOT track opponent cards; focuses on self-play AI. Dataset stale (May 2024). |
+| CR Vision | https://github.com/bytkim/cr_vision | ★★★★☆ Active 2026 | Live (BlueStacks) | YOLO troop detection + grid tracker + wall-clock elixir + cycle inference | Correct architecture for opponent tracking. Missing evolutions/heroes/spell detection. ~60 cards in cost table. |
+| TV Royale Dataset | https://huggingface.co/datasets/chrisrca/clash-royale-tv-replays | ★★★☆☆ | Replay/TV | Frame-level card crops with x,y positions | Not usable for live opponent tracking; no opponent hand info. |
+| RoyaleAPI cr-api-data | https://royaleapi.github.io/cr-api-data/json/cards.json | ★★★☆☆ | Static data | 120 cards as of snapshot | Stale: missing 2025-2026 cards (Vines, Spirit Empress, Hero cards, etc.). |
+| Official Clash Royale API | https://developer.clashroyale.com/ | ★★★★★ | Official | /v1/cards endpoint | Requires API token; best source of truth. |
+
+### Why Current Whole-Frame Classifier Fails
+- **Opponent card art is never visible in live gameplay.** Only own hand cards are shown.
+- A whole-frame classifier trained on card images will hallucinate predictions when shown combat frames.
+- The correct signal is **unit spawns and spell effects on the arena**, not card art.
+- KataCR paper explicitly splits perception into: arena (YOLO units), hand cards (classifier), time/elixir (OCR). Opponent cards are inferred from arena detections, never classified directly.
+
+## 2. Recommended Architecture
+
+```
+Emulator Capture (Win32 / mss)
+    |
+    v
+Battle Gater (lobby vs battle detection, ROI computation)
+    |
+    v
+Event Detector (temporal differencing, persistence suppression, side separation)
+    |
+    v
+Evidence Model (YOLO unit detector + heuristic spell effect detectors)
+    |
+    v
+Card Resolver (unit->card mapping, multi-unit rules, evolution/hero handling, ambiguity->UNKNOWN)
+    |
+    v
+Elixir Tracker (wall-clock regen with mode schedule)
+Deck Tracker (cycle inference, meta priors)
+```
+
+## 3. Concrete Rewrite Plan for F:\ClashCR
+
+1. **Delete** old whole-frame card classifier code and stale card JSON dumps.
+2. **Add** `clashcr/utils/card_registry.py` with sync from RoyaleAPI + Official API.
+3. **Add** `clashcr/core/capture.py` for MuMu/BlueStacks window capture.
+4. **Add** `clashcr/core/battle_gating.py` for battle detection and ROI separation.
+5. **Add** `clashcr/core/event_detector.py` for temporal event detection.
+6. **Add** `clashcr/core/recorder.py` for evidence recording and labeling.
+7. **Add** `clashcr/models/evidence_model.py` for YOLO + spell heuristics.
+8. **Add** `clashcr/models/card_resolver.py` for unit->card mapping with ambiguity handling.
+9. **Add** `clashcr/game/elixir_tracker.py` for elixir estimation.
+10. **Add** `clashcr/game/deck_tracker.py` for deck/cycle inference.
+11. **Add** `clashcr/core/evaluator.py` for offline metrics.
+12. **Add** `clashcr/cli.py` for all CLI commands.
+
+## 4. Card Registry Sync
+- Primary: RoyaleAPI static JSON (fallback)
+- Secondary: Official API `/v1/cards` (requires token)
+- Logs: source URL, sync timestamp, card count, IDs, costs, types, rarities, evolution/hero/tower-troop flags.
+- Fails loudly if registry is stale or missing expected new cards.
+
+## 5. Dataset Collection and Labeling Plan
+- `clashcr record-battle --output data/live-recordings/session-001 --seconds 180 --fps 8`
+- Saves frames, metadata.jsonl, and creates empty labels.csv / predictions.csv.
+- User manually labels opponent card plays in labels.csv.
+- Required validation set:
+  - >= 20 full battles
+  - Multiple arenas/maps
+  - Multiple resolutions
+  - Single/double/triple elixir periods
+  - All card categories (troops, spells, buildings, champions, evolutions, heroes, tower troops)
+  - Negative recordings (lobby/menu, quiet battle periods)
+
+## 6. Training Plan
+- **Unit detector**: Fine-tune YOLOv8 on KataCR detection dataset + custom labeled spawns.
+- **Spell effects**: Heuristic color/motion detectors (no training required for MVP).
+- **Future**: Train a lightweight spell-effect classifier on recorded spell crops.
+
+## 7. CLI Commands
+```bash
+# Setup
+pip install -e .
+clashcr sync-cards --config config.yaml
+
+# Recording
+clashcr record-battle --config config.yaml --output data/live-recordings/session-001 --seconds 180 --fps 8
+
+# Labeling
+clashcr label-recording --recording data/live-recordings/session-001
+# (Then edit labels.csv manually or with a GUI tool)
+
+# Training (placeholder)
+clashcr train-event-model --config config.yaml --data data/live-recordings
+
+# Evaluation
+clashcr evaluate-recording --config config.yaml --recording data/live-recordings/session-heldout --labels data/live-recordings/session-heldout/labels.csv
+
+# Live run
+clashcr run --config config.yaml --raw --debug-frame debug-frame.jpg --debug-dir debug-events
+```
+
+## 8. Debug Checklist for Live Failures
+- [ ] Emulator window detected? Run `python -m clashcr.core.capture` to list windows.
+- [ ] Battle detected? Check battle confidence in logs.
+- [ ] Events firing? Check debug-events/ directory for crops.
+- [ ] YOLO model loaded? Verify path in config.yaml.
+- [ ] Side attribution correct? Check opponent ROI vs own ROI.
+- [ ] Elixir tracking reasonable? Compare to wall-clock regen.
+- [ ] False positives? Increase `min_event_area` or `temporal_confirmation`.
+- [ ] Missed spells? Verify spell heuristics or add new color ranges.
+
+## 9. Verification Report Requirements
+- Run evaluation on held-out labeled recordings.
+- Report: precision, recall, F1, FP/min, missed events, mean timing error.
+- If 100% not achievable, state plainly and identify missing visual signal.