fix: remove stray } after showManaPool stub (line 1856)

fix: update tracked paths — files moved from root to lan-client/
fix: restore ui.js from placeholder corruption + Phase 1 patches
2026-04-04 13:33:37 -04:00 · 2026-04-03 23:31:36 -04:00 · 2026-04-03 23:25:01 -04:00 · 2026-04-03 18:54:22 -04:00 · 2026-04-03 18:51:15 -04:00 · 2026-04-03 18:50:51 -04:00
25 changed files with 35560 additions and 440 deletions
@@ -18,5 +18,9 @@ FORGE_WORKING_DIR=D:/ForgeCommander/forge-repo/forge-gui
 # ── Deck Paths ────────────────────────────────────────────────────
 # Directory containing your precon .dck files.
 # Forge reads deck files directly from this folder.
+#
+# IMPORTANT: lab_api.py reads PRECON_DIR (not PRECON_DECKS_DIR).
+# PRECON_DECKS_DIR is kept below for backwards compat but is NOT used by the server.
+PRECON_DIR=D:\ForgeCommander\commander-ai-lab\precon-decks
 PRECON_DECKS_DIR=D:\ForgeCommander\commander-ai-lab\precon-decks
 FORGE_DECKS_DIR=D:\ForgeCommander\commander-ai-lab\precon-decks
@@ -1,46 +1,179 @@
 # Commander AI Lab

-A full-stack MTG Commander AI research platform. Simulate hundreds of games overnight, train ML models on the results, and let simulation data automatically shape the AI deck builder — all from a web UI or CLI.
+A full-stack Magic: The Gathering Commander research platform. Run thousands of simulated games, train neural networks on the outcomes, build decks with AI that learns from simulation data, get LLM-powered coaching, and play live 4-player battles — all from a single unified system.

-## What It Does
+---

-| Layer | What it is |
-|---|---|
-| **Monte Carlo Engine** | Pure-Python headless sim — runs thousands of games in minutes, no JVM needed |
-| **Forge Engine** | Java/Forge rules-complete sim for ground-truth validation |
-| **Overnight Runner** | Unattended batch runner — runs sims, updates sim weights, trains neural net |
-| **ML Pipeline** | Outcome-weighted RL nudges card scoring weights; neural net trains on decision logs |
-| **Deck Builder** | 7-step LLM pipeline (EDHrec → Scryfall → Ollama) now injected with sim-learned insights |
-| **AI Coach** | LLM-powered coaching sessions (Anthropic/Ollama) with streaming support |
-| **Web UI** | React + FastAPI dashboard for decks, sims, training, and deck building |
+## Overview
+
+Commander AI Lab connects a rules-complete Forge engine, a fast Monte Carlo simulator, an LLM deck builder, an ML training pipeline, and multiple game clients (web, LAN, Unity) into one closed-loop platform. Simulation results feed back into deck building and AI decision-making, so the system improves the more it plays.
+
+### Key Capabilities
+
+- **Batch Simulation** — Run hundreds or thousands of Commander games unattended using Forge (rules-complete) or a headless Python Monte Carlo engine
+- **ML Training Pipeline** — Reinforcement learning (PPO) trains a neural net on game decision logs; outcome-weighted scoring nudges card weights automatically
+- **AI Deck Builder** — 7-step LLM pipeline (EDHrec → Scryfall → Ollama) with simulation-learned insights injected into prompts
+- **LLM Coach** — Streaming coaching sessions powered by Anthropic Claude or local Ollama models, enriched with RAG-retrieved card knowledge
+- **RAG Card Knowledge** — ChromaDB vector store over 30,000+ Scryfall cards with semantic search and auto-staleness monitoring
+- **LAN Battlefield** — Browser-based 4-player Commander game client with ML-powered AI opponents and precon deck support
+- **Unity Client** — Full Unity application with battleground scene, lobby system, WebSocket game state sync, and cross-platform builds
+- **Card Scanner** — OCR pipeline for physical card recognition via Ximilar API
+- **163 Precon Decks** — Complete preconstructed deck library in `.dck` format
+
+---

 ## Architecture

 ```
-┌─────────────────────────────────────────────────────────────────┐
-│  Web UI  (React/TypeScript — frontend/)                         │
-│    Deck Builder · Sim Dashboard · Training · Coach              │
-└────────────────────────┬────────────────────────────────────────┘
-                         │ HTTP/REST + WebSocket
-┌────────────────────────┴────────────────────────────────────────┐
-│  FastAPI Server  (lab_api.py / routes/ — port 8080)             │
-│    /api/lab/*   /api/ml/*   /api/coach/*   /api/deck-builder/*  │
-└────────┬──────────────────┬──────────────────┬──────────────────┘
-         │                  │                  │
-   Java subprocess    Python sim engine    Ollama (local LLM)
-   (Forge rules)      (Monte Carlo)        qwen2.5:7b + others
-         │                  │
-┌────────┴───────┐  ┌───────┴────────────────────────────────────┐
-│  Forge Engine  │  │  src/commander_ai_lab/                      │
-│  (rules-       │  │    sim/   — engine, models, rules           │
-│   complete)    │  │    deck_builder/ — 7-step LLM pipeline      │
-└────────────────┘  │    coach/ — streaming LLM coach             │
-                    └────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────┐
+│  Clients                                                            │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────┐ │
+│  │  Web UI      │ │  LAN Client  │ │  Unity Client                │ │
+│  │  (React/TS)  │ │  (HTML/JS)   │ │  (C# / URP)                 │ │
+│  │  /ui         │ │  /lan        │ │  /unity-client               │ │
+│  └──────┬───────┘ └──────┬───────┘ └──────┬───────────────────────┘ │
+│         └────────────────┼────────────────┘                         │
+│                          │ HTTP/REST + WebSocket                    │
+│  ┌───────────────────────┴─────────────────────────────────────────┐│
+│  │  FastAPI Backend (lab_api.py — port 8080)                       ││
+│  │                                                                  ││
+│  │  /api/lab/*          Batch simulation (Forge + Monte Carlo)     ││
+│  │  /api/deck-builder/* 7-step LLM deck construction               ││
+│  │  /api/coach/*        Streaming LLM coaching sessions            ││
+│  │  /api/ml/*           Neural net training + policy server        ││
+│  │  /api/rag/*          ChromaDB vector search                     ││
+│  │  /api/game/*         Live game sessions (Forge IPC)             ││
+│  │  /api/policy/*       ML policy decisions for AI players         ││
+│  │  /ws/game/{id}       WebSocket game state streaming             ││
+│  └───────┬──────────────┬──────────────┬──────────────┬────────────┘│
+│          │              │              │              │              │
+│   ┌──────┴──────┐ ┌────┴─────┐ ┌──────┴──────┐ ┌────┴──────┐      │
+│   │ Forge       │ │ Monte    │ │ Ollama      │ │ ChromaDB  │      │
+│   │ Engine      │ │ Carlo    │ │ (local LLM) │ │ (vector   │      │
+│   │ (Java/JVM)  │ │ Engine   │ │ qwen2.5:7b  │ │  store)   │      │
+│   └─────────────┘ │ (Python) │ └─────────────┘ └───────────┘      │
+│                    └──────────┘                                      │
+│  ┌──────────────────────────────────────────────────────────────────┐│
+│  │  ML Pipeline                                                     ││
+│  │  decisions_*.jsonl → update_weights.py → learned_weights.json    ││
+│  │                    → /api/ml/train    → neural net checkpoints   ││
+│  └──────────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────────┘
 ```

-## Quick Start (Windows)
+---

-**Prerequisites:** Java 17+, Python 3.10+, Maven 3.8+, [Forge](https://github.com/Card-Forge/forge) built at `D:\ForgeCommander\forge-repo`
+## Features
+
+### Simulation Engines
+
+| Engine | Description | Speed |
+|---|---|---|
+| **Forge** | Rules-complete Java engine — handles the stack, instants, triggered abilities, and all Commander rules. Each game spawns a JVM subprocess. | ~0.04 sims/sec (single-threaded) |
+| **Monte Carlo** | Headless Python engine — models combat keywords (flying, trample, deathtouch, lifelink, menace, reach, haste), summoning sickness, tapped state, commander zone, multiplayer targeting, and board wipes. No JVM required. | Thousands of games in minutes |
+
+Both engines feed structured results into the same ML pipeline.
+
+### Deck Builder
+
+The `POST /api/deck-builder/build` endpoint runs a 7-step pipeline:
+
+1. Resolve commander via Scryfall
+2. Fetch EDHrec recommendations
+3. Fetch Scryfall candidates by category (ramp, removal, draw, lands)
+4. Ollama suggests synergy/protection/wincon cards — **simulation insights injected here**
+5. Filter by color identity, collection, and ban list
+6. Ollama enforces ratios (trim/expand to 99) — **simulation insights injected here**
+7. Assemble final deck with smart substitution (guarantees 99-card output)
+
+### AI Coach
+
+LLM-powered coaching with two modes:
+
+- **Full Session** — Deep analysis including removal coverage, ramp quality, draw engine profiling, win conditions, anti-synergy detection, pod meta evaluation, and tempo assessment
+- **Quick Digest** — Fast ~5-second summary for rapid feedback
+
+Coaching prompts are enriched with semantically relevant cards from the ChromaDB RAG store (15 cards for full sessions, 8 for quick digests). Supports both Anthropic Claude and local Ollama models with streaming responses.
+
+### RAG Card Knowledge
+
+- **SQLite FTS5** bulk card database from Scryfall data
+- **ChromaDB** vector index with natural-language card embeddings
+- Automatic staleness monitoring (checks every 6 hours, auto-rebuilds if >14 days old)
+- Graceful fallback — RAG failures never block coaching or deck building
+
+### ML Training Pipeline
+
+```
+Overnight sims → decisions_*.jsonl
+       ↓
+update_weights.py → learned_weights.json (feeds deck builder)
+       ↓
+/api/ml/train → neural net training on decision dataset
+       ↓
+/api/policy/decide → ML policy serves AI decisions in live games
+```
+
+- **Outcome-weighted RL** nudges card scoring weights from game results
+- **Neural net** trains on the full decision log dataset
+- **Distillation loop** — self-play → collect data → retrain → repeat
+- **ELO tracking** and model tournaments for comparing AI versions
+- Weights clamped to `[-20.0, 20.0]`, stored in `learned_weights.json`
+
+### Win Condition Tracking
+
+Games are classified by win type — not just "Combat" vs "Other":
+
+- **Combat** — standard creature damage wins
+- **Combo** — Approach of the Second Sun, Felidar Sovereign, Happily Ever After, and 30+ known alternate-win cards
+- **Drain** — life drain effects
+- **Mill** — library depletion
+- **Poison** — infect/poison counter wins
+
+Draw games (timeout) are analyzed separately with per-player life-at-timeout snapshots and likely cause identification.
+
+### LAN Battlefield Client
+
+Browser-based 4-player Commander game at `/lan`:
+
+- **AI Bridge** — REST + WebSocket connectivity with ML policy decisions as Priority 1 (falls back to local heuristic AI)
+- **Deck System** — 3-tab selector: Precons (163 decks, grouped by set), EDHREC search, and custom deck import
+- **Player Panels** — Life counters, commander damage bars, poison/energy/experience/rad counters, emblem management
+- **Backend Detection** — Auto-detects the Commander AI Lab backend; works offline with local precon data
+
+### Unity Client
+
+Full Unity application (URP, .NET Standard 2.1) with:
+
+- **Battleground Scene** — 4-seat layout with rotated perspectives, life/poison/commander damage widgets, phase tracker, turn order bar
+- **Card System** — Hand, battlefield, graveyard, exile zones with card art, tapped rotation, face-down state, summoning sickness indicators
+- **Stack & Mana** — LIFO stack display and 6-pip mana pool
+- **Lobby System** — Configure 4 seats (human/AI), POST to backend, WebSocket game state sync
+- **Elimination** — Grayscale shader overlay on eliminated players
+- **Token System** — Create, tap, add counters, delete tokens
+- **Cross-Platform** — Windows, WebGL, Android, iOS build targets
+- **Scenes** — MainMenu, Collection, DeckBuilder, DeckGenerator, Simulator, Coach, Scanner, Training, Precon, Battleground
+
+### Card Scanner
+
+OCR pipeline for physical Magic cards using the Ximilar API. Scan cards from photos and match them to the Scryfall database.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+| Tool | Version |
+|---|---|
+| Python | 3.10+ |
+| Java | 17+ |
+| Maven | 3.8+ |
+| Node.js | 18+ (for LAN client scripts) |
+| Ollama | Latest (for local LLM inference) |
+| [Forge](https://github.com/Card-Forge/forge) | Built at `D:\ForgeCommander\forge-repo` |
+
+### Setup (Windows)

 ```powershell
 # 1. Build Forge (one-time)
@@ -51,17 +184,29 @@ mvn package -pl forge-gui-desktop "-DskipTests" "-Drevision=2.0.12-SNAPSHOT" -am
 cd D:\ForgeCommander\commander-ai-lab
 mvn package "-DskipTests"

-# 3. Install Python deps
-pip install -e .
+# 3. Install Python dependencies
+pip install -e ".[rag,dev]"

-# 4. Launch
+# 4. Pull an Ollama model for the deck builder
+ollama pull qwen2.5:7b
+
+# 5. Launch
 .\start-lab.bat
-# → open http://localhost:8080
+# → Web UI:        http://localhost:8080
+# → LAN Client:    http://localhost:8080/lan/
 ```

+Or use the automated installer:
+
+```powershell
+.\install-commander-ai-lab.ps1
+```
+
+---
+
 ## Overnight AFK Runner

-Runs batch sims unattended, then updates card weights and trains the neural net:
+Run batch simulations unattended, then automatically update card weights and train the neural net:

 ```powershell
 python overnight-run.py                          # default: 11.5h DeepSeek sims
@@ -74,9 +219,9 @@ python overnight-run.py --no-train               # skip neural net training
 1. `update_weights.py` — nudges `learned_weights.json` from decision logs (feeds deck builder)
 2. `/api/ml/train` — trains the neural net on the full decision dataset

-## Sim → Deck Builder Feedback Loop
+---

-Simulation outcomes automatically improve deck recommendations:
+## Simulation → Deck Builder Feedback Loop

 ```
 Overnight sims → decisions_*.jsonl
@@ -90,24 +235,63 @@ Ollama prompts (suggest_cards + enforce_deck_ratios)
 Better card recommendations
 ```

-When active, `BuildResult.sources_consulted` includes `"sim_weights"`. No-op until real sim data exists.
+When active, `BuildResult.sources_consulted` includes `"sim_weights"`. The loop is a no-op until real sim data exists.

-## Deck Builder Pipeline
+---

-The `POST /api/deck-builder/build` endpoint runs 7 steps:
+## API Reference

-1. Resolve commander via Scryfall
-2. Fetch EDHrec recommendations
-3. Fetch Scryfall candidates by category (ramp, removal, draw, lands)
-4. Ollama suggests synergy/protection/wincon cards ← **sim insights injected here**
-5. Filter by color identity, collection, ban list
-6. Ollama enforces ratios (trim/expand to 99) ← **sim insights injected here**
-7. Assemble final deck
+### Simulation

-## ML Pipeline
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/lab/decks` | GET | List available Commander decks |
+| `/api/lab/start` | POST | Start Forge batch (returns batchId) |
+| `/api/lab/start-deepseek` | POST | Start Python/DeepSeek batch |
+| `/api/lab/status?batchId=X` | GET | Poll batch progress |
+| `/api/lab/result?batchId=X` | GET | Get completed batch JSON |
+| `/api/lab/history` | GET | List past batch runs |
+| `/api/lab/precons/deck` | GET | Fetch precon `.dck` file content |
+
+### Deck Builder & Coach
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/deck-builder/build` | POST | Build a 99-card Commander deck |
+| `/api/coach/chat` | POST | Full coaching session (streaming) |
+| `/api/coach/quick-digest` | POST | Fast ~5s coaching summary |
+
+### ML & Policy
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/ml/train` | POST | Start neural net training |
+| `/api/ml/train/status` | GET | Poll training progress |
+| `/api/policy/decide` | POST | Get ML policy decision for game state |
+
+### RAG
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/rag/build` | POST | Build/rebuild ChromaDB index |
+| `/api/rag/search` | POST | Semantic card search |
+| `/api/rag/status` | GET | Index health and staleness |
+
+### Live Game
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/game/start` | POST | Create a live game session |
+| `/api/game/action` | POST | Submit a player action |
+| `/api/game/{id}/actions` | GET | Poll Forge IPC actions |
+| `/ws/game/{game_id}` | WS | Real-time game state streaming |
+
+---
+
+## ML Scripts

 ```powershell
-# Update sim card weights from decision logs (runs automatically in overnight-run.py)
+# Update card weights from decision logs
 python -m ml.scripts.update_weights --min-games 10 --lr 0.05 --dry-run

 # Reset weights to defaults
@@ -117,7 +301,7 @@ python -m ml.scripts.update_weights --reset
 python ml/scripts/generate_synthetic_data.py
 ```

-Learned weights are clamped to `[-20.0, 20.0]` and stored in `src/commander_ai_lab/sim/learned_weights.json`.
+---

 ## Python Simulator API

@@ -129,52 +313,122 @@ stats = run_simulation(deck, num_games=100, name_a="My Deck")
 print(f"Win rate: {stats['win_rate']:.1%}, Avg turns: {stats['avg_turns']:.1f}")
 ```

-The Monte Carlo engine models: combat keywords (flying, trample, deathtouch, lifelink, menace, reach, haste), summoning sickness, tapped/untap state, commander zone, multiplayer attack targeting, and board wipes. It does **not** model the stack, instants, or continuous type-changing effects.
-
-## API Reference
-
-| Endpoint | Method | Description |
-|---|---|---|
-| `/api/lab/decks` | GET | List available Commander decks |
-| `/api/lab/start` | POST | Start Forge batch (returns batchId) |
-| `/api/lab/start-deepseek` | POST | Start Python/DeepSeek batch |
-| `/api/lab/status?batchId=X` | GET | Poll batch progress |
-| `/api/lab/result?batchId=X` | GET | Get completed batch JSON |
-| `/api/lab/history` | GET | List past batch runs |
-| `/api/ml/train` | POST | Start neural net training |
-| `/api/ml/train/status` | GET | Poll training progress |
-| `/api/coach/chat` | POST | LLM coaching session (streaming) |
-| `/api/deck-builder/build` | POST | Build a 99-card Commander deck |
+---

 ## Project Structure

 ```
 commander-ai-lab/
+├── lab_api.py                    # FastAPI server entry point
 ├── overnight-run.py              # AFK batch runner
 ├── start-lab.bat                 # Windows one-click launcher
-├── lab_api.py                    # FastAPI server entry point
-├── frontend/                     # React + TypeScript web UI
-├── ui/                           # Legacy static HTML UI
+├── install-commander-ai-lab.ps1  # Automated setup script
+├── pom.xml                       # Maven build (Java/Forge components)
+├── pyproject.toml                # Python package config
+│
+├── routes/                       # FastAPI route modules
+│   ├── lab.py                    #   Batch simulation
+│   ├── deckbuilder.py            #   Deck builder pipeline
+│   ├── coach.py                  #   LLM coaching
+│   ├── ml.py                     #   ML training
+│   ├── rag.py                    #   ChromaDB vector search
+│   ├── game.py                   #   Live game sessions
+│   ├── policy.py                 #   ML policy server
+│   ├── precon.py                 #   Precon deck serving
+│   ├── scanner.py                #   Card OCR
+│   └── ws_game.py                #   WebSocket game state
+│
+├── services/                     # Core service layer
+│   ├── forge_runner.py           #   Forge subprocess management
+│   ├── draw_game_analyzer.py     #   Draw/timeout analysis
+│   ├── rag_store.py              #   ChromaDB vector store
+│   └── card_text.py              #   Shared card text builder
+│
 ├── src/commander_ai_lab/
-│   ├── sim/                      # Monte Carlo engine (engine, models, rules)
-│   ├── deck_builder/             # LLM deck builder pipeline
-│   │   ├── api/                  # Scryfall, EDHrec, Ollama, sim_insights
-│   │   ├── core/                 # Models, rules engine, assembler
-│   │   └── pipeline/             # build_deck.py (7-step orchestrator)
-│   └── coach/                    # LLM coaching (Anthropic + Ollama)
-├── ml/
-│   ├── scripts/                  # update_weights.py, ml_cli.py
-│   ├── training/                 # Neural net trainer
-│   ├── encoder/                  # Feature encoding
-│   └── models/                   # Saved model checkpoints
-├── scanner/                      # Card OCR pipeline
-├── logs/decisions/               # ML decision logs (gitignored)
-└── src/main/java/commanderailab/ # Java/Forge batch runner
+│   ├── sim/                      # Monte Carlo engine
+│   │   ├── engine.py             #   Game loop
+│   │   ├── models.py             #   GameResult, Card, Player
+│   │   ├── rules.py              #   Combat, keywords, commander rules
+│   │   ├── win_condition_parser.py  # Alternate win detection
+│   │   └── learned_weights.json  #   ML-learned card weights
+│   ├── deck_builder/             # 7-step LLM pipeline
+│   │   ├── api/                  #   Scryfall, EDHrec, Ollama, sim_insights
+│   │   ├── core/                 #   Models, rules engine, assembler
+│   │   └── pipeline/             #   build_deck.py orchestrator
+│   └── coach/                    # LLM coaching
+│       ├── coach_service.py      #   Session + quick digest
+│       ├── prompt_template.py    #   System/user prompts
+│       └── embeddings.py         #   Card embedding utilities
+│
+├── ml/                           # ML training pipeline
+│   ├── scripts/                  #   update_weights.py, ml_cli.py
+│   ├── training/                 #   Neural net trainer
+│   ├── encoder/                  #   Feature encoding
+│   └── models/                   #   Saved checkpoints
+│
+├── lan-client/                   # Browser-based LAN battlefield
+│   ├── index.html                #   Entry point
+│   ├── engine.js                 #   Game engine + ML AI turns
+│   ├── ai-bridge.js              #   Backend connector + policy bridge
+│   ├── player-panels.js          #   Enhanced player panels
+│   ├── ui.js                     #   3-tab deck selector + setup
+│   └── precons.js                #   163 precon deck data
+│
+├── unity-client/                 # Unity game client
+│   └── Assets/
+│       ├── Scenes/               #   11 scenes (MainMenu → Battleground)
+│       ├── Scripts/              #   C# controllers, models, services
+│       ├── Prefabs/              #   Card, deck slot, chat bubble
+│       └── Materials/            #   URP materials + grayscale shader
+│
+├── scanner/                      # Card OCR pipeline (Ximilar)
+├── precon-decks/                 # 163 preconstructed decks (.dck)
+├── sample-decks/                 # Sample deck files
+├── data/                         # Runtime data (ChromaDB, bulk DB)
+├── logs/                         # Simulation + decision logs
+├── docs/                         # Architecture docs + schemas
+├── tests/                        # Test suite
+├── scripts/                      # Utility scripts
+├── .github/workflows/            # CI + Unity build automation
+└── src/main/java/                # Java/Forge batch runner
+    └── commanderailab/
 ```

+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Backend | Python 3.10+, FastAPI, Uvicorn |
+| Simulation (rules-complete) | Java 17, Maven, Forge |
+| Simulation (fast) | Python Monte Carlo engine |
+| LLM Inference | Ollama (qwen2.5:7b), Anthropic Claude |
+| Vector Store | ChromaDB with all-MiniLM-L6-v2 embeddings |
+| Card Database | SQLite FTS5 (Scryfall bulk data) |
+| ML Training | PyTorch, PPO reinforcement learning |
+| Web Client | HTML/CSS/JS |
+| Unity Client | Unity 2022 LTS, URP, C# |
+| CI/CD | GitHub Actions |
+
+---
+
 ## Known Limitations

- **Monte Carlo engine** — no stack, no instants, no continuous type changes (animated lands don't attack)
- **Forge engine** — each game spawns a new JVM (~2-3s overhead), ~0.04 sims/sec single-threaded
- **Forge winner life total** not captured (quiet mode only reports losers)
- **Deck builder** — Ollama suggestions are only as good as the local model; `qwen2.5:7b` works well
+- **Monte Carlo engine** — no stack, no instants, no continuous type-changing effects (animated lands don't attack)
+- **Forge engine** — each game spawns a new JVM (~2–3s overhead); ~0.04 sims/sec single-threaded
+- **Forge** — winner life total not captured in quiet mode (only reports losers)
+- **Deck builder** — Ollama suggestions depend on the local model quality; `qwen2.5:7b` works well
+- **LAN client** — EDHREC commander search is a stub (backend-powered, not yet fully wired)
+
+---
+
+## Contributing
+
+Commander AI Lab is an active research project. Check the [open issues](https://github.com/KoalaTrapLord/commander-ai-lab/issues) for areas where contributions are welcome.
+
+---
+
+## License
+
+See repository for license details.
@@ -0,0 +1,257 @@
+<#
+.SYNOPSIS
+    Smoke-tests the Commander AI Lab policy server from PowerShell.
+    Checks: server reachable -> /api/policy/health -> /api/policy/decide.
+    Prints a plain-English pass/fail for every step.
+
+.USAGE
+    # From repo root (server already running in another window):
+    .\Test-PolicyServer.ps1
+
+    # Custom host/port:
+    .\Test-PolicyServer.ps1 -BaseUrl http://localhost:9000
+
+    # Pretty-print the full decide response:
+    .\Test-PolicyServer.ps1 -Verbose
+#>
+param(
+    [string]$BaseUrl = "http://localhost:8080",
+    [switch]$Verbose
+)
+
+$ErrorActionPreference = "Stop"
+
+# ---- helpers ----------------------------------------------------------------
+
+function Write-Pass { param([string]$msg) Write-Host "  [PASS] $msg" -ForegroundColor Green  }
+function Write-Fail { param([string]$msg) Write-Host "  [FAIL] $msg" -ForegroundColor Red    }
+function Write-Info { param([string]$msg) Write-Host "  [INFO] $msg" -ForegroundColor Cyan   }
+function Write-Warn { param([string]$msg) Write-Host "  [WARN] $msg" -ForegroundColor Yellow }
+function Write-Step { param([string]$msg) Write-Host "`n-- $msg" -ForegroundColor White       }
+
+$allPassed = $true
+
+function Invoke-Step {
+    param(
+        [string]      $Name,
+        [scriptblock] $Block
+    )
+    Write-Step $Name
+    try   { & $Block }
+    catch {
+        Write-Fail $_.Exception.Message
+        $script:allPassed = $false
+    }
+}
+
+# ---- Step 1: server reachable -----------------------------------------------
+
+Invoke-Step "Step 1 -- Server reachable at $BaseUrl" {
+    $r1 = $null
+    try { $r1 = Invoke-WebRequest -Uri "$BaseUrl/docs" -UseBasicParsing -TimeoutSec 5 } catch {}
+    if ($r1 -and $r1.StatusCode -eq 200) {
+        Write-Pass "FastAPI server is up (GET /docs -> 200)"
+        return
+    }
+    $r2 = $null
+    try { $r2 = Invoke-WebRequest -Uri "$BaseUrl/" -UseBasicParsing -TimeoutSec 5 } catch {}
+    if ($r2 -and $r2.StatusCode -lt 500) {
+        Write-Pass "FastAPI server is up (GET / -> $($r2.StatusCode))"
+        return
+    }
+    throw "Cannot reach $BaseUrl -- is lab_api.py / uvicorn running?"
+}
+
+# ---- Step 2: /api/policy/health ---------------------------------------------
+
+$modelLoaded = $false
+
+Invoke-Step "Step 2 -- GET $BaseUrl/api/policy/health" {
+    $resp = Invoke-RestMethod -Uri "$BaseUrl/api/policy/health" -Method Get -TimeoutSec 10
+    if ($Verbose) { $resp | ConvertTo-Json -Depth 5 | Write-Host }
+
+    if ($resp.ready -eq $true) {
+        Write-Pass "Model is loaded and ready  (ready=true)"
+        $script:modelLoaded = $true
+    } elseif ($resp.status -eq "degraded") {
+        Write-Fail "Health returned status=degraded / ready=false"
+        Write-Warn "  -> Policy model is NOT loaded."
+        Write-Warn "  -> Start the server with --load-policy, or call POST /api/ml/load_model first."
+        Write-Warn "  -> Confirm models/ contains a valid .pt checkpoint."
+        $script:allPassed = $false
+    } else {
+        Write-Warn "Unexpected health response -- dumping:"
+        $resp | ConvertTo-Json -Depth 5 | Write-Host
+        $script:allPassed = $false
+    }
+}
+
+# ---- Step 3: /api/policy/decide (synthetic snapshot) ------------------------
+
+Invoke-Step "Step 3 -- POST $BaseUrl/api/policy/decide  (synthetic 4-player snapshot)" {
+
+    if (-not $script:modelLoaded) {
+        Write-Warn "Skipping /decide -- model not loaded (Step 2 failed)."
+        Write-Warn "Fix Step 2 first, then re-run."
+        return
+    }
+
+    $body = [ordered]@{
+        game_id       = "ps1-smoke-test"
+        turn          = 3
+        phase         = "MAIN1"
+        active_player = 0
+        playstyle     = "midrange"
+        temperature   = 1.0
+        greedy        = $false
+        players       = @(
+            [ordered]@{
+                seat              = 0
+                name              = "TestPlayer0"
+                life              = 40
+                manaAvailable     = 3
+                landCount         = 3
+                creaturesOnField  = 1
+                totalPowerOnBoard = 2
+                hand              = @("Cultivate", "Solemn Simulacrum", "Sol Ring")
+                battlefield       = @("Forest", "Forest", "Forest", "Birds of Paradise")
+                graveyard         = @()
+                commandZone       = @("Atraxa, Praetors Voice")
+            },
+            [ordered]@{
+                seat              = 1
+                name              = "TestPlayer1"
+                life              = 38
+                manaAvailable     = 2
+                landCount         = 2
+                creaturesOnField  = 0
+                totalPowerOnBoard = 0
+                handCount         = 4
+                hand              = @()
+                battlefield       = @("Island", "Swamp")
+                graveyard         = @()
+                commandZone       = @("Ur-Dragon")
+            },
+            [ordered]@{
+                seat              = 2
+                name              = "TestPlayer2"
+                life              = 35
+                manaAvailable     = 4
+                landCount         = 4
+                creaturesOnField  = 2
+                totalPowerOnBoard = 5
+                handCount         = 3
+                hand              = @()
+                battlefield       = @("Mountain", "Mountain", "Mountain", "Mountain", "Goblin Guide", "Monastery Swiftspear")
+                graveyard         = @()
+                commandZone       = @("Krenko, Mob Boss")
+            },
+            [ordered]@{
+                seat              = 3
+                name              = "TestPlayer3"
+                life              = 40
+                manaAvailable     = 0
+                landCount         = 0
+                creaturesOnField  = 0
+                totalPowerOnBoard = 0
+                handCount         = 7
+                hand              = @()
+                battlefield       = @()
+                graveyard         = @()
+                commandZone       = @("Prossh, Skyraider of Kher")
+            }
+        )
+    } | ConvertTo-Json -Depth 10
+
+    $resp = Invoke-RestMethod `
+        -Uri         "$BaseUrl/api/policy/decide" `
+        -Method      Post `
+        -Body        $body `
+        -ContentType "application/json" `
+        -TimeoutSec  30
+
+    if ($Verbose) {
+        Write-Host ""
+        Write-Host "  Full /decide response:" -ForegroundColor White
+        $resp | ConvertTo-Json -Depth 6 | Write-Host
+    }
+
+    $ok = $true
+    if ([string]::IsNullOrEmpty($resp.action)) {
+        Write-Fail "response.action is empty"
+        $ok = $false
+    }
+    if ($null -eq $resp.confidence) {
+        Write-Fail "response.confidence is missing"
+        $ok = $false
+    }
+    if ($resp.PSObject.Properties["error"] -and -not [string]::IsNullOrEmpty($resp.error)) {
+        Write-Fail "Server returned error: $($resp.error)"
+        $ok = $false
+    }
+
+    if ($ok) {
+        $confPct = [math]::Round($resp.confidence * 100, 1)
+        Write-Pass "Decision received  ->  action='$($resp.action)'  conf=$($confPct)%  latency=$($resp.inference_ms)ms  src=$($resp.vector_source)"
+
+        if ($resp.probabilities) {
+            $top3 = $resp.probabilities.PSObject.Properties |
+                Sort-Object { $_.Value } -Descending |
+                Select-Object -First 3
+            Write-Info "Top-3 action probabilities:"
+            foreach ($p in $top3) {
+                $pct = [math]::Round($p.Value * 100, 1)
+                Write-Info ("  " + $p.Name.PadRight(22) + "$pct%")
+            }
+        }
+    } else {
+        $script:allPassed = $false
+    }
+}
+
+# ---- Step 4: log line guidance ----------------------------------------------
+
+Invoke-Step "Step 4 -- Confirm [routes.policy.decide] log line in server console" {
+    Write-Info "After Step 3 you should see in the uvicorn window:"
+    Write-Info "  [decide] turn=3 phase=main_1 -> cast_ramp (conf=0.810) | top5=[...] | src=encoder"
+    Write-Info ""
+    Write-Info "If that line is MISSING:"
+    Write-Info "  1. Confirm uvicorn started with --log-level info (the default)"
+    Write-Info "  2. Confirm lab_api.py calls register_policy_routes(app, policy_svc)"
+    Write-Info "  3. Confirm routes/policy.py is included via routes/__init__.py"
+    Write-Info "  4. Logger name is [routes.policy.decide] -- check no filter silences it"
+    Write-Pass "Guidance printed"
+}
+
+# ---- Step 5: why Forge ignores the policy server ----------------------------
+
+Invoke-Step "Step 5 -- Forge IPC status (informational)" {
+    Write-Warn "Forge does NOT call /api/policy/decide on its own."
+    Write-Warn "routes/game.py POST /api/game/start has a TODO: wire Forge engine launch."
+    Write-Warn ""
+    Write-Warn "Until wired, /decide is only hit by:"
+    Write-Warn "  - This script"
+    Write-Warn "  - overnight-run.py  (batch sim path)"
+    Write-Warn "  - Manual Invoke-RestMethod / curl calls"
+    Write-Warn ""
+    Write-Warn "Forge launches its built-in AI and plays lands because it has"
+    Write-Warn "no HTTP client pointed at localhost:8080."
+    Write-Warn ""
+    Write-Warn "Next step: wire GameSession inside POST /api/game/start,"
+    Write-Warn "or add a PolicyClient hook in Forge AiController.java."
+    Write-Pass "Status explained"
+}
+
+# ---- Summary ----------------------------------------------------------------
+
+Write-Host ""
+if ($allPassed) {
+    Write-Host "==========================================" -ForegroundColor Green
+    Write-Host "  ALL STEPS PASSED -- policy server live"  -ForegroundColor Green
+    Write-Host "==========================================" -ForegroundColor Green
+} else {
+    Write-Host "==========================================" -ForegroundColor Red
+    Write-Host "  ONE OR MORE STEPS FAILED -- see above"   -ForegroundColor Red
+    Write-Host "==========================================" -ForegroundColor Red
+    exit 1
+}
@@ -50,6 +50,9 @@ _DEFAULT_ORIGINS = "http://localhost:5173,http://localhost:3000,http://localhost
 _allowed = os.environ.get("ALLOWED_ORIGINS", _DEFAULT_ORIGINS)
 allowed_origins = [o.strip() for o in _allowed.split(",") if o.strip()]

+# Module-level handle so lifespan can call .load() after routes are registered.
+_POLICY_SVC = None
+

 # ── Lifespan (replaces deprecated @app.on_event) ────────────────────────────────────────────────────────
@asynccontextmanager
@@ -77,7 +80,6 @@ async def _lifespan(application: FastAPI):
    # RAG Phase 3: background staleness monitor (rebuilds if >14 days old)
    async def _rag_staleness_monitor():
        """Periodically check if the RAG index needs rebuilding."""
-        import time as _time
        while True:
            await asyncio.sleep(6 * 3600)  # check every 6 hours
            try:
@@ -92,20 +94,17 @@ async def _lifespan(application: FastAPI):
                log.warning("RAG staleness monitor failed: %s", exc)
    asyncio.ensure_future(_rag_staleness_monitor())

-    # Policy routes: register if ML policy model is available
+    # Policy model load — routes were already registered at module scope (before
+    # any app.mount() calls) so /api/policy/* is reachable regardless of the
+    # StaticFiles root mount.  Only the heavyweight model load happens here.
    try:
-        from ml.serving.policy_server import PolicyInferenceService
-        from routes.policy import register_policy_routes
-        _policy_svc = PolicyInferenceService()
-        if _policy_svc.load():
-            register_policy_routes(application, _policy_svc)
-            log.info("Policy routes registered (/api/policy/*)")
-        else:
-            log.warning("Policy model not loaded — /api/policy/* routes inactive")
-    except ImportError:
-        log.info("Policy service not available (ml.serving not installed)")
+        if _POLICY_SVC is not None:
+            if _POLICY_SVC.load():
+                log.info("Policy model loaded successfully")
+            else:
+                log.warning("Policy model not loaded — /api/policy/health will report degraded")
    except Exception as e:
-        log.warning("Policy route registration failed (non-fatal): %s", e)
+        log.warning("Policy model load failed (non-fatal): %s", e)

    yield  # ← server is running

@@ -138,6 +137,23 @@ app.include_router(ws_game_router)
 app.include_router(ml_router)
 app.include_router(game_router)   # live game session routes

+# ── Policy routes — MUST be registered here, before any app.mount() calls ────────────────────
+# StaticFiles mounted at "/" acts as a sub-application and returns its own 404 for
+# paths it doesn't serve, rather than falling through to later-registered routes.
+# Any include_router() called after app.mount("/", ...) will be unreachable.
+# Registering here (module scope) guarantees the /api/policy/* endpoints exist in
+# the route list before the root static mount is added below.
+try:
+    from ml.serving.policy_server import PolicyInferenceService
+    from routes.policy import register_policy_routes
+    _POLICY_SVC = PolicyInferenceService()
+    register_policy_routes(app, _POLICY_SVC)
+    log.info("Policy routes registered (/api/policy/*)")
+except ImportError:
+    log.info("Policy service not available (ml.serving not installed)")
+except Exception as e:
+    log.warning("Policy route registration failed (non-fatal): %s", e)
+

 # ── API endpoints ─────────────────────────────────────────────────────────────────────────────
 # NOTE: all @app.get routes MUST be registered before app.mount() calls.
@@ -149,11 +165,21 @@ async def health_check():
    """Health check endpoint for load balancers and Unity client polling."""
    return {"status": "ok"}

-# ── Static UI (MUST come after all @app.get routes) ──────────────────────────────────────────
+# ── Static UI (MUST come after all @app.get / include_router calls) ──────────────────────────
 from pathlib import Path as _Path
 _legacy_ui_dir = _Path(__file__).parent / "ui"
+_lan_client_dir = _Path(__file__).parent / "lan-client"
+_precon_decks_dir = _Path(__file__).parent / "precon-decks"
 _spa_dir = _Path(__file__).parent / "frontend" / "commander-ai-lab-ui" / "dist"

+# Mount LAN client at /lan (served before the root catch-all)
+if _lan_client_dir.exists():
+    app.mount("/lan", StaticFiles(directory=str(_lan_client_dir), html=True), name="lan-client")
+
+# Mount precon-decks/ so .dck files are fetchable at /precon-decks/{file}.dck
+if _precon_decks_dir.exists():
+    app.mount("/precon-decks", StaticFiles(directory=str(_precon_decks_dir)), name="precon-decks")
+
 if _legacy_ui_dir.exists():
    app.mount("/", StaticFiles(directory=str(_legacy_ui_dir), html=True), name="ui")
 elif _spa_dir.exists():
@@ -0,0 +1,651 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>MTG Commander Battlefield</title>
+<link rel="stylesheet" href="style.css?v=20260403_0300">
+</head>
+<body>
+
+<!-- ====================================================
+     SETUP SCREEN
+     ==================================================== -->
+<div id="setup-screen">
+  <!-- Populated by ui.js initSetupScreen() -->
+</div>
+
+<!-- ====================================================
+     TABLE SURFACE — 4-Quadrant Battlefield
+     ==================================================== -->
+<div class="table-surface" id="game-battlefield" style="display:none;">
+
+  <!-- TOP BAR: Phase tracker + controls -->
+  <div id="top-bar">
+    <span class="top-bar-logo">Commander</span>
+
+    <div class="turn-counter-badge" id="turn-counter">Turn <span>1</span></div>
+
+    <div class="active-player-indicator" id="active-player-indicator">
+      <span class="active-player-dot" id="active-dot" style="background:#c0392b;"></span>
+      Player 1's Turn
+    </div>
+
+    <!-- Phase track -->
+    <div class="phase-track-wrapper">
+      <div class="phase-track" id="phase-track"></div>
+    </div>
+
+    <!-- Phase/turn action buttons -->
+    <div class="top-bar-actions">
+      <button class="btn-phase" onclick="nextPhase()" title="Advance to next phase (N)">Next Phase</button>
+      <button class="btn-phase btn-next-turn" onclick="nextTurn()" title="End turn, advance to next player (T)">Next Turn</button>
+    </div>
+
+    <!-- Utility buttons -->
+    <div class="top-bar-utils">
+      <button class="btn-util" id="btn-undo" onclick="undo()" title="Undo (Ctrl+Z)" disabled>&#x21A9;</button>
+      <button class="btn-util" id="btn-redo" onclick="redo()" title="Redo (Ctrl+Y)" disabled>&#x21AA;</button>
+      <button class="btn-util" id="btn-triggers" onclick="toggleTriggerStack()" title="Trigger Stack">&#x2747;</button>
+      <button class="btn-util" onclick="openDiceModal()" title="Dice &amp; Coins (G)">&#x1F3B2;</button>
+      <button class="btn-util" onclick="checkStateBasedActions()" title="Check State-Based Actions">SBA</button>
+      <button class="btn-util" onclick="toggleSettingsPanel()" title="Settings">&#x2699;</button>
+      <button class="btn-util" id="btn-search-toggle" onclick="document.getElementById('card-search-sidebar').classList.toggle('collapsed')" title="Card Search (S)">&#x1F50D;</button>
+    </div>
+
+    <!-- Storm counter -->
+    <span id="storm-badge" style="display:none;font-size:10px;color:var(--mtg-gold);background:rgba(200,168,67,0.15);border:1px solid rgba(200,168,67,0.3);border-radius:4px;padding:2px 7px;white-space:nowrap;">Storm: 0</span>
+  </div>
+
+  <!-- DIVIDER LINES -->
+  <div class="divider-h"></div>
+  <div class="divider-v"></div>
+
+  <!-- CORNER ACCENTS -->
+  <div class="corner-accent tl"></div>
+  <div class="corner-accent tr"></div>
+  <div class="corner-accent bl"></div>
+  <div class="corner-accent br"></div>
+
+  <!-- CENTER EMBLEM -->
+  <div class="center-emblem">
+    <svg viewBox="0 0 100 100" fill="none">
+      <circle cx="50" cy="50" r="42" stroke="rgba(255,255,255,0.2)" stroke-width="1.5"/>
+      <circle cx="50" cy="50" r="28" stroke="rgba(255,255,255,0.1)" stroke-width="1"/>
+      <polygon points="50,15 58.5,37 82,37 63,51 69,74 50,60 31,74 37,51 18,37 41.5,37"
+               fill="rgba(255,255,255,0.1)" stroke="rgba(255,255,255,0.2)" stroke-width="0.8"/>
+    </svg>
+  </div>
+
+  <!-- ================================================
+       4-QUADRANT BATTLEFIELD
+       ================================================ -->
+  <div class="battlefield">
+
+    <!-- PLAYER 1: Top-Left (Crimson) -->
+    <div class="player-area p1" id="player-area-1">
+      <span class="player-label" id="player-label-1">Player 1</span>
+      <div class="life-counter" id="life-counter-1">
+        <button onclick="adjustLife(0,-1)" aria-label="Decrease P1 life">&#x2212;</button>
+        <span class="life-counter-value" id="life-0" onclick="showSetLifeDialog(0)">40</span>
+        <button onclick="adjustLife(0,1)" aria-label="Increase P1 life">+</button>
+      </div>
+      <div class="poison-badge" id="poison-0" style="display:none;" onclick="adjustPoison(0,1)" title="Poison counters (click +1, right-click -1)" oncontextmenu="event.preventDefault();adjustPoison(0,-1)">0 poison</div>
+
+      <!-- Zone Row: Library, Exile, Graveyard, Hand -->
+      <div class="zone-row" id="zone-row-1">
+        <div class="zone library" id="lib-zone-1" data-player="1" data-zone="library"
+             onclick="openZoneModal(0,'library')" data-tooltip="Library">
+          <span class="card-count" id="lib-count-1">0</span>
+          <span class="zone-icon">&#x1F4DA;</span>
+          <span class="zone-name">Library</span>
+        </div>
+        <div class="zone exile" id="exile-zone-1" data-player="1" data-zone="exile"
+             onclick="openZoneModal(0,'exile')" data-tooltip="Exile">
+          <span class="card-count" id="exile-count-1" style="display:none;">0</span>
+          <span class="zone-icon">&#x2B21;</span>
+          <span class="zone-name">Exile</span>
+        </div>
+        <div class="zone graveyard" id="gv-zone-1" data-player="1" data-zone="graveyard"
+             onclick="openZoneModal(0,'graveyard')" data-tooltip="Graveyard">
+          <span class="card-count" id="gv-count-1" style="display:none;">0</span>
+          <span class="zone-icon">&#x2620;</span>
+          <span class="zone-name">Grave</span>
+        </div>
+        <div class="zone hand" id="hand-zone-1" data-player="1" data-zone="hand"
+             onclick="openZoneModal(0,'hand')" data-tooltip="Hand">
+          <span class="zone-icon">&#x1F0CF;</span>
+          <span class="zone-name">Hand (<span id="hand-count-1">0</span>)</span>
+        </div>
+      </div>
+
+      <!-- Commander Row -->
+      <div class="commander-row" id="cmd-row-1">
+        <div class="zone commander" id="cmd-zone-1" data-player="1" data-zone="command"
+             onclick="openZoneModal(0,'command')" data-tooltip="Command Zone">
+          <span class="zone-icon">&#x1F451;</span>
+          <span class="zone-name">Commander</span>
+        </div>
+      </div>
+
+      <!-- Battle Zone -->
+      <div class="battle-zone" id="battle-zone-1">
+        <div class="battle-zone-inner"></div>
+        <span class="battle-zone-label">Battlefield</span>
+        <!-- Battlefield cards injected here -->
+      </div>
+    </div>
+
+    <!-- PLAYER 2: Top-Right (Sapphire) -->
+    <div class="player-area p2" id="player-area-2">
+      <span class="player-label" id="player-label-2">Player 2</span>
+      <div class="life-counter" id="life-counter-2">
+        <button onclick="adjustLife(1,-1)" aria-label="Decrease P2 life">&#x2212;</button>
+        <span class="life-counter-value" id="life-1" onclick="showSetLifeDialog(1)">40</span>
+        <button onclick="adjustLife(1,1)" aria-label="Increase P2 life">+</button>
+      </div>
+      <div class="poison-badge" id="poison-1" style="display:none;" onclick="adjustPoison(1,1)" oncontextmenu="event.preventDefault();adjustPoison(1,-1)">0 poison</div>
+
+      <div class="zone-row" id="zone-row-2">
+        <div class="zone library" id="lib-zone-2" data-player="2" data-zone="library"
+             onclick="openZoneModal(1,'library')" data-tooltip="Library">
+          <span class="card-count" id="lib-count-2">0</span>
+          <span class="zone-icon">&#x1F4DA;</span>
+          <span class="zone-name">Library</span>
+        </div>
+        <div class="zone exile" id="exile-zone-2" data-player="2" data-zone="exile"
+             onclick="openZoneModal(1,'exile')" data-tooltip="Exile">
+          <span class="card-count" id="exile-count-2" style="display:none;">0</span>
+          <span class="zone-icon">&#x2B21;</span>
+          <span class="zone-name">Exile</span>
+        </div>
+        <div class="zone graveyard" id="gv-zone-2" data-player="2" data-zone="graveyard"
+             onclick="openZoneModal(1,'graveyard')" data-tooltip="Graveyard">
+          <span class="card-count" id="gv-count-2" style="display:none;">0</span>
+          <span class="zone-icon">&#x2620;</span>
+          <span class="zone-name">Grave</span>
+        </div>
+        <div class="zone hand" id="hand-zone-2" data-player="2" data-zone="hand"
+             onclick="openZoneModal(1,'hand')" data-tooltip="Hand">
+          <span class="zone-icon">&#x1F0CF;</span>
+          <span class="zone-name">Hand (<span id="hand-count-2">0</span>)</span>
+        </div>
+      </div>
+
+      <div class="commander-row" id="cmd-row-2">
+        <div class="zone commander" id="cmd-zone-2" data-player="2" data-zone="command"
+             onclick="openZoneModal(1,'command')" data-tooltip="Command Zone">
+          <span class="zone-icon">&#x1F451;</span>
+          <span class="zone-name">Commander</span>
+        </div>
+      </div>
+
+      <div class="battle-zone" id="battle-zone-2">
+        <div class="battle-zone-inner"></div>
+        <span class="battle-zone-label">Battlefield</span>
+      </div>
+    </div>
+
+    <!-- PLAYER 3: Bottom-Left (Emerald) -->
+    <div class="player-area p3" id="player-area-3">
+      <!-- Battle zone on top for bottom players -->
+      <div class="battle-zone" id="battle-zone-3">
+        <div class="battle-zone-inner"></div>
+        <span class="battle-zone-label">Battlefield</span>
+      </div>
+
+      <div class="commander-row" id="cmd-row-3">
+        <div class="zone commander" id="cmd-zone-3" data-player="3" data-zone="command"
+             onclick="openZoneModal(2,'command')" data-tooltip="Command Zone">
+          <span class="zone-icon">&#x1F451;</span>
+          <span class="zone-name">Commander</span>
+        </div>
+      </div>
+
+      <div class="zone-row" id="zone-row-3">
+        <div class="zone library" id="lib-zone-3" data-player="3" data-zone="library"
+             onclick="openZoneModal(2,'library')" data-tooltip="Library">
+          <span class="card-count" id="lib-count-3">0</span>
+          <span class="zone-icon">&#x1F4DA;</span>
+          <span class="zone-name">Library</span>
+        </div>
+        <div class="zone exile" id="exile-zone-3" data-player="3" data-zone="exile"
+             onclick="openZoneModal(2,'exile')" data-tooltip="Exile">
+          <span class="card-count" id="exile-count-3" style="display:none;">0</span>
+          <span class="zone-icon">&#x2B21;</span>
+          <span class="zone-name">Exile</span>
+        </div>
+        <div class="zone graveyard" id="gv-zone-3" data-player="3" data-zone="graveyard"
+             onclick="openZoneModal(2,'graveyard')" data-tooltip="Graveyard">
+          <span class="card-count" id="gv-count-3" style="display:none;">0</span>
+          <span class="zone-icon">&#x2620;</span>
+          <span class="zone-name">Grave</span>
+        </div>
+        <div class="zone hand" id="hand-zone-3" data-player="3" data-zone="hand"
+             onclick="openZoneModal(2,'hand')" data-tooltip="Hand">
+          <span class="zone-icon">&#x1F0CF;</span>
+          <span class="zone-name">Hand (<span id="hand-count-3">0</span>)</span>
+        </div>
+      </div>
+
+      <span class="player-label" id="player-label-3">Player 3</span>
+      <div class="life-counter" id="life-counter-3">
+        <button onclick="adjustLife(2,-1)" aria-label="Decrease P3 life">&#x2212;</button>
+        <span class="life-counter-value" id="life-2" onclick="showSetLifeDialog(2)">40</span>
+        <button onclick="adjustLife(2,1)" aria-label="Increase P3 life">+</button>
+      </div>
+      <div class="poison-badge" id="poison-2" style="display:none;" onclick="adjustPoison(2,1)" oncontextmenu="event.preventDefault();adjustPoison(2,-1)">0 poison</div>
+    </div>
+
+    <!-- PLAYER 4: Bottom-Right (Gold) -->
+    <div class="player-area p4" id="player-area-4">
+      <div class="battle-zone" id="battle-zone-4">
+        <div class="battle-zone-inner"></div>
+        <span class="battle-zone-label">Battlefield</span>
+      </div>
+
+      <div class="commander-row" id="cmd-row-4">
+        <div class="zone commander" id="cmd-zone-4" data-player="4" data-zone="command"
+             onclick="openZoneModal(3,'command')" data-tooltip="Command Zone">
+          <span class="zone-icon">&#x1F451;</span>
+          <span class="zone-name">Commander</span>
+        </div>
+      </div>
+
+      <div class="zone-row" id="zone-row-4">
+        <div class="zone library" id="lib-zone-4" data-player="4" data-zone="library"
+             onclick="openZoneModal(3,'library')" data-tooltip="Library">
+          <span class="card-count" id="lib-count-4">0</span>
+          <span class="zone-icon">&#x1F4DA;</span>
+          <span class="zone-name">Library</span>
+        </div>
+        <div class="zone exile" id="exile-zone-4" data-player="4" data-zone="exile"
+             onclick="openZoneModal(3,'exile')" data-tooltip="Exile">
+          <span class="card-count" id="exile-count-4" style="display:none;">0</span>
+          <span class="zone-icon">&#x2B21;</span>
+          <span class="zone-name">Exile</span>
+        </div>
+        <div class="zone graveyard" id="gv-zone-4" data-player="4" data-zone="graveyard"
+             onclick="openZoneModal(3,'graveyard')" data-tooltip="Graveyard">
+          <span class="card-count" id="gv-count-4" style="display:none;">0</span>
+          <span class="zone-icon">&#x2620;</span>
+          <span class="zone-name">Grave</span>
+        </div>
+        <div class="zone hand" id="hand-zone-4" data-player="4" data-zone="hand"
+             onclick="openZoneModal(3,'hand')" data-tooltip="Hand">
+          <span class="zone-icon">&#x1F0CF;</span>
+          <span class="zone-name">Hand (<span id="hand-count-4">0</span>)</span>
+        </div>
+      </div>
+
+      <span class="player-label" id="player-label-4">Player 4</span>
+      <div class="life-counter" id="life-counter-4">
+        <button onclick="adjustLife(3,-1)" aria-label="Decrease P4 life">&#x2212;</button>
+        <span class="life-counter-value" id="life-3" onclick="showSetLifeDialog(3)">40</span>
+        <button onclick="adjustLife(3,1)" aria-label="Increase P4 life">+</button>
+      </div>
+      <div class="poison-badge" id="poison-3" style="display:none;" onclick="adjustPoison(3,1)" oncontextmenu="event.preventDefault();adjustPoison(3,-1)">0 poison</div>
+    </div>
+
+  </div><!-- /.battlefield -->
+
+  <!-- COMBAT SVG OVERLAY (arrows) -->
+  <svg id="combat-overlay" xmlns="http://www.w3.org/2000/svg" style="position:absolute;inset:44px 0 0 0;pointer-events:none;z-index:30;">
+    <defs>
+      <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+        <polygon points="0 0, 10 3.5, 0 7" fill="rgba(211,32,42,0.7)"/>
+      </marker>
+    </defs>
+    <g id="combat-arrows-svg"></g>
+  </svg>
+
+  <!-- FLOATING LOG -->
+  <div id="floating-log" class="floating-log"></div>
+
+  <!-- SHORTCUT HINT -->
+  <div class="shortcut-hint"></div>
+
+  <!-- CARD SEARCH SIDEBAR (right side, collapsible) -->
+  <div id="card-search-sidebar" class="collapsed">
+    <div class="sidebar-header">
+      <span class="sidebar-title">Card Search</span>
+      <button class="sidebar-toggle" onclick="document.getElementById('card-search-sidebar').classList.toggle('collapsed')" title="Close search">&#x2715;</button>
+    </div>
+    <div class="search-input-wrap">
+      <input class="search-input" id="card-search-input" type="text" placeholder="Search Scryfall..." autocomplete="off"/>
+    </div>
+    <div class="search-status" id="search-status">Type to search cards...</div>
+    <div class="card-results" id="card-results"></div>
+  </div>
+
+  <!-- Sidebar edge tab -->
+  <div id="sidebar-edge-tab" class="sidebar-edge-tab" title="Toggle card search">&#x2039;</div>
+
+</div><!-- /.table-surface / #game-battlefield -->
+
+<!-- ====================================================
+     CONTEXT MENU
+     ==================================================== -->
+<div id="context-menu"></div>
+
+<!-- ====================================================
+     FLOATING CARD PREVIEW
+     ==================================================== -->
+<div id="card-preview">
+  <img src="" alt="Card Preview"/>
+  <div class="card-preview-pt-overlay" id="card-preview-pt-overlay"></div>
+  <div class="card-preview-info">
+    <div class="card-preview-name"></div>
+    <div class="card-preview-type"></div>
+    <div class="card-preview-oracle"></div>
+    <div class="card-preview-pt"></div>
+  </div>
+</div>
+
+<!-- ====================================================
+     ZONE MODAL
+     ==================================================== -->
+<div id="zone-modal">
+  <div class="zone-modal-card">
+    <div class="zone-modal-header">
+      <span class="zone-modal-title" id="zone-modal-title">Player Zones</span>
+      <button class="btn-close" onclick="closeZoneModal()">&#x2715;</button>
+    </div>
+    <div class="zone-modal-tabs" id="zone-modal-tabs">
+      <!-- Populated by renderZoneModal() -->
+    </div>
+    <div class="zone-modal-body" id="zone-modal-body">
+      <!-- Populated by renderZoneModal() -->
+    </div>
+  </div>
+</div>
+
+<!-- ====================================================
+     DICE MODAL
+     ==================================================== -->
+<div id="dice-modal">
+  <div class="dice-modal-card">
+    <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:1rem;">
+      <span style="font-family:var(--font-display);font-size:14px;font-weight:700;color:var(--color-text-muted);text-transform:uppercase;letter-spacing:0.08em;">Dice &amp; Coins</span>
+      <button class="btn-close" onclick="closeDiceModal()">&#x2715;</button>
+    </div>
+    <div class="dice-result-display" id="dice-result-display">&#x2014;</div>
+    <div class="dice-label" id="dice-label">Choose a die</div>
+    <div class="dice-buttons">
+      <button class="btn-dice" onclick="rollDice(4)">d4</button>
+      <button class="btn-dice" onclick="rollDice(6)">d6</button>
+      <button class="btn-dice" onclick="rollDice(8)">d8</button>
+      <button class="btn-dice" onclick="rollDice(10)">d10</button>
+      <button class="btn-dice" onclick="rollDice(12)">d12</button>
+      <button class="btn-dice" onclick="rollDice(20)">d20</button>
+      <button class="btn-dice" onclick="rollDice(100)">d100</button>
+      <button class="btn-dice coin" onclick="flipCoin()">Coin Flip</button>
+    </div>
+  </div>
+</div>
+
+<!-- ====================================================
+     TOKEN MODAL
+     ==================================================== -->
+<div id="token-modal">
+  <div class="token-modal-card">
+    <div class="modal-header">
+      <span class="modal-title">Create Token</span>
+      <button class="btn-close" onclick="closeTokenModal()">&#x2715;</button>
+    </div>
+    <div class="modal-body" id="token-modal-body">
+      <div style="display:grid;grid-template-columns:1fr 1fr;gap:10px;margin-bottom:12px;">
+        <div>
+          <label style="font-size:11px;font-weight:600;color:var(--color-text);display:block;margin-bottom:4px;">Token Name</label>
+          <input class="game-input" id="token-name" type="text" placeholder="e.g. 1/1 White Soldier"/>
+        </div>
+        <div>
+          <label style="font-size:11px;font-weight:600;color:var(--color-text);display:block;margin-bottom:4px;">Type Line</label>
+          <input class="game-input" id="token-type" type="text" placeholder="Creature — Soldier"/>
+        </div>
+        <div>
+          <label style="font-size:11px;font-weight:600;color:var(--color-text);display:block;margin-bottom:4px;">Power/Toughness</label>
+          <input class="game-input" id="token-pt" type="text" placeholder="1/1"/>
+        </div>
+        <div>
+          <label style="font-size:11px;font-weight:600;color:var(--color-text);display:block;margin-bottom:4px;">Count</label>
+          <input class="game-input" id="token-count" type="number" value="1" min="1" max="20"/>
+        </div>
+      </div>
+      <div style="margin-bottom:10px;">
+        <label style="font-size:11px;font-weight:600;color:var(--color-text);display:block;margin-bottom:4px;">Keywords (comma-separated)</label>
+        <input class="game-input" id="token-keywords" type="text" placeholder="Flying, Vigilance"/>
+      </div>
+      <div style="margin-bottom:12px;">
+        <label style="font-size:11px;font-weight:600;color:var(--color-text);display:block;margin-bottom:4px;">Player</label>
+        <select class="game-input" id="token-player-select" style="height:28px;">
+          <option value="0">Player 1</option>
+          <option value="1">Player 2</option>
+          <option value="2">Player 3</option>
+          <option value="3">Player 4</option>
+        </select>
+      </div>
+      <div style="display:flex;gap:8px;">
+        <button class="btn btn-primary" onclick="createTokenFromModal()">Create Token(s)</button>
+        <button class="btn btn-cancel" onclick="closeTokenModal()">Cancel</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- ====================================================
+     DECK MODAL
+     ==================================================== -->
+<div id="deck-modal">
+  <div class="deck-modal-card">
+    <div class="modal-header">
+      <span class="modal-title">Deck Manager</span>
+      <button class="btn-close" onclick="closeDeckModal()">&#x2715;</button>
+    </div>
+    <div class="modal-body" id="deck-modal-body">
+      <!-- Populated by renderDeckModalContent() -->
+    </div>
+  </div>
+</div>
+
+<!-- ====================================================
+     COMMANDER DAMAGE MATRIX MODAL
+     ==================================================== -->
+<div id="cmd-dmg-matrix-modal">
+  <!-- Populated by renderCmdDmgMatrix() -->
+</div>
+
+<!-- ====================================================
+     TRIGGER STACK PANEL
+     ==================================================== -->
+<div id="trigger-stack-panel">
+  <div class="trigger-stack-card">
+    <div class="trigger-stack-header">
+      <span class="trigger-stack-title">Trigger Stack</span>
+      <button class="btn-close" style="font-size:14px;width:20px;height:20px;" onclick="closeTriggerStack()">&#x2715;</button>
+    </div>
+    <div class="trigger-stack-body" id="trigger-stack-body">
+      <div class="trigger-stack-empty">No pending triggers.</div>
+    </div>
+    <div class="trigger-stack-actions">
+      <button class="btn-resolve" onclick="resolveNextTrigger()">Resolve Next</button>
+      <button class="btn-resolve-all" onclick="resolveAllTriggers()">Resolve All</button>
+    </div>
+  </div>
+</div>
+
+<!-- ====================================================
+     SETTINGS PANEL
+     ==================================================== -->
+<div id="settings-panel">
+  <div class="modal-header" style="flex-shrink:0;">
+    <span class="modal-title">Settings</span>
+    <button class="btn-close" onclick="toggleSettingsPanel()">&#x2715;</button>
+  </div>
+  <div class="settings-body" id="settings-body" style="flex:1;overflow-y:auto;padding:12px;">
+    <!-- Populated by renderSettingsPanel() -->
+  </div>
+  <div style="padding:10px 14px;border-top:1px solid var(--color-border);display:flex;gap:8px;flex-wrap:wrap;flex-shrink:0;">
+    <button class="btn btn-primary" onclick="openDiceModal()">&#x1F3B2; Dice</button>
+    <button class="btn btn-gold" onclick="openCmdDmgMatrix()">CMD Damage Matrix</button>
+    <button class="btn btn-cancel" onclick="checkStateBasedActions()">Check SBA</button>
+    <button class="btn btn-cancel" onclick="autoArrangeBattlefield()">Auto-Arrange</button>
+  </div>
+</div>
+
+<!-- ====================================================
+     PRIORITY BANNER
+     ==================================================== -->
+<div id="priority-banner">
+  <span class="priority-text" id="priority-text">Waiting for priority...</span>
+  <button class="btn-priority-pass" onclick="passPriority()">Pass Priority</button>
+  <button class="btn-close" style="font-size:13px;" onclick="closePriorityWindow()">&#x2715;</button>
+</div>
+
+<!-- ====================================================
+     LEGAL ACTIONS BAR
+     ==================================================== -->
+<div id="legal-actions-bar">
+  <!-- Populated by renderLegalActionsBar() -->
+</div>
+
+<!-- ====================================================
+     UNDO HISTORY PANEL
+     ==================================================== -->
+<div id="undo-history-panel">
+  <!-- Populated by renderUndoHistory() -->
+</div>
+
+<!-- ====================================================
+     MANA COLOR PICKER (dynamically appended) -->
+<!-- Zone card context menu (dynamically appended) -->
+<!-- SBA alert panel (dynamically appended) -->
+<!-- Set-life dialog (dynamically appended) -->
+
+<!-- ====================================================
+     SCRIPTS
+     Load order matters:
+       1. precons.js      — static PRECON_DATA fallback
+       2. engine.js       — game state & core logic
+       3. ai-bridge.js    — backend connector & DeckSourceClient
+       4. precon-loader.js — startGameWithDecks() + loadPreconDeckFromDck()
+       5. player-panels.js — player panel rendering
+       6. ui.js           — setup screen, deck picker, UI wiring
+     ==================================================== -->
+<script src="precons.js?v=20260403_0300"></script>
+<script src="engine.js?v=20260403_0300"></script>
+<script src="ai-bridge.js?v=20260403_0300"></script>
+<script src="precon-loader.js?v=20260403_0300"></script>
+<script src="player-panels.js?v=20260403_0300"></script>
+<script src="ui.js?v=20260403_0300"></script>
+
+<script>
+// ============================================================
+// STARTUP & BRIDGE FUNCTIONS
+// ============================================================
+
+// Token creation from modal
+function createTokenFromModal() {
+  if (!gameState) return;
+  const name = document.getElementById('token-name').value.trim() || '1/1 Token';
+  const typeLine = document.getElementById('token-type').value.trim() || 'Creature';
+  const pt = document.getElementById('token-pt').value.trim() || '1/1';
+  const count = parseInt(document.getElementById('token-count').value) || 1;
+  const keywords = document.getElementById('token-keywords').value.trim();
+  const playerIdx = parseInt(document.getElementById('token-player-select').value) || 0;
+
+  const parts = pt.split('/');
+  const power = parts[0] ? parts[0].trim() : '1';
+  const toughness = parts[1] ? parts[1].trim() : '1';
+
+  for (let i = 0; i < count; i++) {
+    addCardToBattlefield(name, '', typeLine, playerIdx, undefined, undefined,
+      keywords ? keywords.replace(/,/g, ' ') : '',
+      { power, toughness, pt, isToken: true });
+  }
+  addLogEntry('Created ' + count + 'x <strong>' + name + '</strong> token(s) for Player ' + (playerIdx + 1));
+  closeTokenModal();
+}
+
+// Pass priority
+function passPriority() {
+  addLogEntry('Priority passed.');
+  closePriorityWindow();
+}
+
+// Open precon browser (stub - opens deck modal for current player)
+function openPreconBrowser() {
+  if (gameState) openDeckModal(gameState.currentPlayerIndex);
+}
+
+// Open collection modal (stub)
+function openCollectionModal() { showToast('Collection tracker available in full version.'); }
+
+// Scry dialog stub
+function showScryDialog(playerId) {
+  if (!gameState) return;
+  const player = gameState.players[playerId];
+  if (!player || player.zones.library.length === 0) {
+    addLogEntry('!! ' + (player ? player.name : 'Player') + ' has no cards to scry.');
+    return;
+  }
+  const count = Math.min(parseInt(prompt('Scry how many? (1-7)', '1') || '1'), 7, player.zones.library.length);
+  if (isNaN(count) || count < 1) return;
+  const topCards = player.zones.library.slice(0, count);
+  const names = topCards.map(c => c.name || '?').join(', ');
+  addLogEntry('<strong>' + player.name + '</strong> scrys ' + count + ': [' + names + ']');
+}
+
+// Mill dialog stub
+function showMillDialog(playerId) {
+  if (!gameState) return;
+  const count = parseInt(prompt('Mill how many cards?', '1') || '1');
+  if (isNaN(count) || count < 1) return;
+  millCards(playerId, count);
+}
+
+// Become monarch
+function becomeMonarch(playerId) {
+  if (!gameState) return;
+  gameState.monarchPlayerIndex = playerId;
+  const player = gameState.players[playerId];
+  addLogEntry('&#x1F451; <strong>' + (player ? player.name : 'Player') + '</strong> becomes the Monarch!');
+  updateMonarchBadges();
+}
+
+// Empower the life counter right-click on the quadrant labels
+document.addEventListener('DOMContentLoaded', function() {
+  // Wire right-click on life values to set-life dialog
+  for (var i = 0; i < 4; i++) {
+    (function(idx) {
+      var lifeEl = document.getElementById('life-' + idx);
+      if (lifeEl) {
+        lifeEl.addEventListener('contextmenu', function(e) {
+          e.preventDefault();
+          showSetLifeDialog(idx);
+        });
+      }
+    })(i);
+  }
+
+  // Life counter right-click on quadrant buttons too
+  // (already handled via inline onclick in HTML)
+
+  // Auto-detect Commander-AI-Lab backend on page load
+  if (typeof AIBridge !== 'undefined') {
+    AIBridge.init().then(function(status) {
+      var indicator = document.getElementById('backend-status-indicator');
+      if (indicator) {
+        indicator.textContent = status.connected
+          ? (status.modelLoaded ? '\u{1F9E0} ML Backend Connected' : '\u26a1 Backend Connected (no ML model)')
+          : '\u{1F4E1} Local Mode (no backend)';
+        indicator.className = 'backend-status ' +
+          (status.connected ? (status.modelLoaded ? 'connected-ml' : 'connected') : 'disconnected');
+      }
+    });
+  }
+});
+</script>
+
+</body>
+</html>
@@ -0,0 +1,270 @@
+// player-panels.js — Enhanced Player Panel Component
+// Provides collapsible panels with life, commander damage, counters, and emblems.
+
+'use strict';
+
+/**
+ * Create an enhanced player panel widget for a quadrant.
+ * Replaces the basic life counter with a full tracking panel.
+ *
+ * @param {object} player - Player object from gameState
+ * @param {number} quadrant - 1-4 (matches CSS class p1-p4)
+ * @param {boolean} isActive - Whether this is the active player
+ */
+function createEnhancedPlayerPanel(player, quadrant, isActive) {
+  var panel = document.createElement('div');
+  panel.className = 'enhanced-player-panel' +
+    (isActive ? ' active-turn' : '') +
+    (player.eliminated ? ' eliminated' : '');
+  panel.id = 'enhanced-panel-' + player.id;
+  panel.setAttribute('data-player-id', player.id);
+
+  // Track collapse state
+  var collapseKey = 'panel-collapsed-' + player.id;
+  var isCollapsed = localStorage.getItem(collapseKey) === 'true';
+
+  // ── Header Row ──────────────────────────────────────────
+  var headerHtml =
+    '<div class="epp-header" onclick="togglePlayerPanel(' + player.id + ')">' +
+      '<span class="epp-collapse-arrow">' + (isCollapsed ? '\u25b8' : '\u25be') + '</span>' +
+      '<div class="epp-name-dot" style="background:' + player.color + '"></div>' +
+      '<span class="epp-name">' + player.name + '</span>' +
+      (player.isAI ? '<span class="epp-ai-badge">AI</span>' : '') +
+      '<span class="epp-life-badge">' +
+        '\u2665 ' + player.life +
+        (player.life < player.startingLife
+          ? ' / ' + player.startingLife
+          : '') +
+      '</span>' +
+    '</div>';
+
+  // ── Life Counter Row ────────────────────────────────────
+  var lifeHtml =
+    '<div class="epp-life-row">' +
+      '<button class="epp-life-btn minus" onclick="adjustLife(' + player.id + ',-1)" ' +
+        'oncontextmenu="event.preventDefault();adjustLife(' + player.id + ',-5)" ' +
+        'title="Left: -1 | Right: -5">\u2212</button>' +
+      '<div class="epp-life-value" id="epp-life-' + player.id + '" ' +
+        'onclick="showSetLifeDialog(' + player.id + ')">' +
+        player.life +
+      '</div>' +
+      '<button class="epp-life-btn plus" onclick="adjustLife(' + player.id + ',1)" ' +
+        'oncontextmenu="event.preventDefault();adjustLife(' + player.id + ',5)" ' +
+        'title="Left: +1 | Right: +5">+</button>' +
+    '</div>';
+
+  // ── Commander Damage Section ────────────────────────────
+  var otherPlayers = gameState.players.filter(function(p) {
+    return p.id !== player.id && !p.eliminated;
+  });
+
+  var cmdDmgHtml =
+    '<div class="epp-section">' +
+      '<div class="epp-section-label">Commander Damage</div>' +
+      '<div class="epp-cmd-dmg-grid">';
+
+  otherPlayers.forEach(function(op) {
+    var dmg = player.commanderDamage[op.id] || 0;
+    var pct = Math.round((dmg / 21) * 100);
+    var dangerClass = dmg >= 18 ? 'critical' : dmg >= 10 ? 'warning' : '';
+
+    cmdDmgHtml +=
+      '<div class="epp-cmd-dmg-item ' + dangerClass + '">' +
+        '<div class="epp-cmd-dmg-bar" style="width:' + pct + '%"></div>' +
+        '<div class="epp-cmd-dmg-dot" style="background:' + op.color + '"></div>' +
+        '<span class="epp-cmd-dmg-name">' + op.name + '</span>' +
+        '<span class="epp-cmd-dmg-value">' + dmg + '/21</span>' +
+        '<button class="epp-counter-btn" ' +
+          'onclick="event.stopPropagation();adjustCommanderDamage(' + player.id + ',' + op.id + ',1)" ' +
+          'title="Add commander damage">+</button>' +
+        '<button class="epp-counter-btn" ' +
+          'onclick="event.stopPropagation();adjustCommanderDamage(' + player.id + ',' + op.id + ',-1)" ' +
+          'title="Remove commander damage">\u2212</button>' +
+      '</div>';
+  });
+
+  cmdDmgHtml += '</div></div>';
+
+  // ── Counters Section ────────────────────────────────────
+  var poison = player.poison || 0;
+  var energy = player.energy || 0;
+  var experience = player.experience || 0;
+  var rad = player.rad || 0;
+
+  var countersHtml =
+    '<div class="epp-section">' +
+      '<div class="epp-section-label">Counters</div>' +
+      '<div class="epp-counters-grid">' +
+        _buildCounterWidget('Poison', '\u2620', poison, 10,
+          'adjustPoison(' + player.id + ',1)',
+          'adjustPoison(' + player.id + ',-1)',
+          poison >= 8 ? 'critical' : poison >= 5 ? 'warning' : '') +
+        _buildCounterWidget('Energy', '\u269b', energy, 0,
+          'adjustEnergy(' + player.id + ',1)',
+          'adjustEnergy(' + player.id + ',-1)', '') +
+        _buildCounterWidget('Experience', '\u2605', experience, 0,
+          'adjustExperience(' + player.id + ',1)',
+          'adjustExperience(' + player.id + ',-1)', '') +
+        _buildCounterWidget('Rad', '\u2622', rad, 0,
+          'adjustRad(' + player.id + ',1)',
+          'adjustRad(' + player.id + ',-1)', '') +
+      '</div>' +
+    '</div>';
+
+  // ── Emblems Section ─────────────────────────────────────
+  var emblems = player.emblems || [];
+  var emblemsHtml =
+    '<div class="epp-section">' +
+      '<div class="epp-section-label">Emblems</div>' +
+      '<div class="epp-emblems">';
+
+  if (emblems.length === 0) {
+    emblemsHtml += '<span class="epp-no-emblems">None</span>';
+  } else {
+    emblems.forEach(function(emb, idx) {
+      emblemsHtml +=
+        '<div class="epp-emblem-chip" title="' + emb.name + '">' +
+          '<span class="epp-emblem-name">' + emb.name + '</span>' +
+          '<button class="epp-emblem-remove" ' +
+            'onclick="event.stopPropagation();removeEmblem(' + player.id + ',' + idx + ')">\u00d7</button>' +
+        '</div>';
+    });
+  }
+
+  emblemsHtml +=
+      '<button class="epp-add-emblem-btn" ' +
+        'onclick="event.stopPropagation();showAddEmblemDialog(' + player.id + ')" ' +
+        'title="Add an emblem">+ Emblem</button>' +
+      '</div>' +
+    '</div>';
+
+  // ── Assemble Panel ──────────────────────────────────────
+  var bodyHtml =
+    '<div class="epp-body" id="epp-body-' + player.id + '" ' +
+      'style="' + (isCollapsed ? 'display:none;' : '') + '">' +
+      lifeHtml + cmdDmgHtml + countersHtml + emblemsHtml +
+    '</div>';
+
+  panel.innerHTML = headerHtml + bodyHtml;
+  return panel;
+}
+
+function _buildCounterWidget(label, icon, value, threshold, onInc, onDec, dangerClass) {
+  return '<div class="epp-counter ' + dangerClass + '">' +
+    '<div class="epp-counter-icon">' + icon + '</div>' +
+    '<div class="epp-counter-info">' +
+      '<span class="epp-counter-value">' + value + '</span>' +
+      '<span class="epp-counter-label">' + label + '</span>' +
+    '</div>' +
+    '<div class="epp-counter-btns">' +
+      '<button class="epp-counter-btn" onclick="event.stopPropagation();' + onInc + '">+</button>' +
+      '<button class="epp-counter-btn" onclick="event.stopPropagation();' + onDec + '">\u2212</button>' +
+    '</div>' +
+  '</div>';
+}
+
+function togglePlayerPanel(playerId) {
+  var body = document.getElementById('epp-body-' + playerId);
+  var panel = document.getElementById('enhanced-panel-' + playerId);
+  if (!body || !panel) return;
+
+  var isCollapsed = body.style.display === 'none';
+  body.style.display = isCollapsed ? '' : 'none';
+
+  var arrow = panel.querySelector('.epp-collapse-arrow');
+  if (arrow) arrow.textContent = isCollapsed ? '\u25be' : '\u25b8';
+
+  localStorage.setItem('panel-collapsed-' + playerId, !isCollapsed);
+}
+
+// Counter adjustment functions
+function adjustEnergy(playerId, amount) {
+  if (!gameState) return;
+  var player = gameState.players[playerId];
+  if (!player) return;
+  player.energy = Math.max(0, (player.energy || 0) + amount);
+  addLogEntry('<strong>' + player.name + '</strong> energy: ' + player.energy);
+  renderEnhancedPanels();
+}
+
+function adjustExperience(playerId, amount) {
+  if (!gameState) return;
+  var player = gameState.players[playerId];
+  if (!player) return;
+  player.experience = Math.max(0, (player.experience || 0) + amount);
+  addLogEntry('<strong>' + player.name + '</strong> experience: ' + player.experience);
+  renderEnhancedPanels();
+}
+
+function adjustRad(playerId, amount) {
+  if (!gameState) return;
+  var player = gameState.players[playerId];
+  if (!player) return;
+  player.rad = Math.max(0, (player.rad || 0) + amount);
+  addLogEntry('<strong>' + player.name + '</strong> rad counters: ' + player.rad);
+  renderEnhancedPanels();
+}
+
+function showAddEmblemDialog(playerId) {
+  var name = prompt('Enter emblem name (e.g., "Sorin, Vengeful Bloodlord"):');
+  if (!name || !name.trim()) return;
+  if (!gameState) return;
+  var player = gameState.players[playerId];
+  if (!player) return;
+  if (!player.emblems) player.emblems = [];
+  player.emblems.push({ name: name.trim() });
+  addLogEntry('<strong>' + player.name + '</strong> gained emblem: ' + name.trim());
+  renderEnhancedPanels();
+}
+
+function removeEmblem(playerId, idx) {
+  if (!gameState) return;
+  var player = gameState.players[playerId];
+  if (!player || !player.emblems) return;
+  var removed = player.emblems.splice(idx, 1);
+  if (removed.length > 0) {
+    addLogEntry('<strong>' + player.name + '</strong> lost emblem: ' + removed[0].name);
+  }
+  renderEnhancedPanels();
+}
+
+/**
+ * Re-render all enhanced player panels in their quadrant positions.
+ */
+function renderEnhancedPanels() {
+  if (!gameState) return;
+
+  for (var i = 0; i < gameState.players.length; i++) {
+    var player = gameState.players[i];
+    var quadrant = i + 1;
+    var areaEl = document.getElementById('player-area-' + quadrant);
+    if (!areaEl) continue;
+
+    // Find or create the enhanced panel container
+    var container = areaEl.querySelector('.epp-container');
+    if (!container) {
+      container = document.createElement('div');
+      container.className = 'epp-container';
+      // Insert before the zone row
+      var zoneRow = areaEl.querySelector('.zone-row');
+      if (zoneRow) {
+        areaEl.insertBefore(container, zoneRow);
+      } else {
+        areaEl.appendChild(container);
+      }
+    }
+
+    var isActive = gameState.currentPlayerIndex === i;
+    var panel = createEnhancedPlayerPanel(player, quadrant, isActive);
+    container.innerHTML = '';
+    container.appendChild(panel);
+
+    // Hide the old life counter (we have our own now)
+    var oldLifeCounter = areaEl.querySelector('.life-counter');
+    if (oldLifeCounter) oldLifeCounter.style.display = 'none';
+
+    // Hide old poison badge (we have counters section)
+    var oldPoison = areaEl.querySelector('.poison-badge');
+    if (oldPoison) oldPoison.style.display = 'none';
+  }
+}
@@ -0,0 +1,299 @@
+/**
+ * precon-loader.js
+ * Handles loading precon .dck files from the backend into the lan-client simulator.
+ * Depends on: engine.js (gameState, initGame, addLogEntry, renderPlayerPanels)
+ *             ai-bridge.js (AIBridge.deckSource.fetchPreconDeck)
+ *             ui.js (setupDeckChoices, setupPlayerCount, setupStartingLife)
+ */
+
+'use strict';
+
+// In-memory Scryfall image cache: cardName -> { imageUrl, typeLine, oracleText, manaCost, power, toughness }
+const _scryfallCache = {};
+
+// Scryfall collection endpoint — accepts up to 75 card identifiers per call
+const SCRYFALL_COLLECTION_URL = 'https://api.scryfall.com/cards/collection';
+
+// ============================================================
+// startGameWithDecks
+// Called by ui.js startGame() when players have selected precon decks.
+// ============================================================
+async function startGameWithDecks() {
+  const playerNames = [];
+  for (let i = 0; i < (setupPlayerCount || 4); i++) {
+    const inp = document.getElementById('player-name-' + i);
+    playerNames.push(inp && inp.value.trim() ? inp.value.trim() : 'Player ' + (i + 1));
+  }
+
+  initGame(setupPlayerCount || 4, playerNames, setupStartingLife || 40);
+
+  const choices = typeof setupDeckChoices !== 'undefined' ? setupDeckChoices : {};
+  const loadPromises = Object.entries(choices).map(async ([idxStr, choice]) => {
+    const playerIdx = parseInt(idxStr, 10);
+    if (choice.type !== 'precon' || !choice.preconId) return;
+    try {
+      const fileName = choice.preconId.endsWith('.dck') ? choice.preconId : choice.preconId + '.dck';
+      const data = await AIBridge.deckSource.fetchPreconDeck(fileName);
+      if (!data || !data.decklist) {
+        addLogEntry('\u26A0 Could not load deck for Player ' + (playerIdx + 1) + ' (no decklist returned)');
+        return;
+      }
+      loadPreconDeckFromDck(playerIdx, data.decklist, choice.preconId);
+    } catch (e) {
+      console.warn('[precon-loader] Failed to load deck for player', playerIdx, e);
+      addLogEntry('\u26A0 Deck load failed for Player ' + (playerIdx + 1) + ': ' + e.message);
+    }
+  });
+
+  await Promise.all(loadPromises);
+
+  if (typeof renderPlayerPanels === 'function') renderPlayerPanels();
+  if (typeof updateActivePlayerHighlight === 'function') updateActivePlayerHighlight();
+
+  // Kick off image enrichment for all players in the background (non-blocking)
+  enrichAllZonesWithScryfall();
+}
+
+
+// ============================================================
+// loadPreconDeckFromDck
+// Parses a Forge-format .dck file string and populates a player's zones.
+// ============================================================
+function loadPreconDeckFromDck(playerIdx, dckContent, deckLabel) {
+  if (!gameState) return;
+  const player = gameState.players[playerIdx];
+  if (!player) return;
+
+  let commander = '';
+  let section = '';
+  const mainCards = [];
+
+  for (const rawLine of dckContent.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('//')) continue;
+
+    if (line.startsWith('[') && line.endsWith(']')) {
+      section = line.slice(1, -1);
+      continue;
+    }
+    if (line.includes('=') && !line.match(/^\d/)) continue;
+
+    const m = line.match(/^(\d+)\s+(.+?)(?:\|.*)?$/);
+    if (!m) continue;
+
+    const qty = parseInt(m[1], 10);
+    const name = m[2].trim();
+
+    if (section === 'Commander') {
+      commander = name;
+    } else if (section === 'Main') {
+      for (let q = 0; q < qty; q++) mainCards.push(name);
+    }
+  }
+
+  player.zones.command   = [];
+  player.zones.library   = [];
+  player.zones.hand      = [];
+  player.zones.graveyard = [];
+  player.zones.exile     = [];
+
+  if (commander) {
+    player.zones.command.push({
+      id: 'cmd-' + playerIdx + '-' + Date.now(),
+      name: commander,
+      imageUrl: '',
+      typeLine: 'Legendary Creature',
+      oracleText: '',
+      manaCost: '',
+    });
+    player.commanderCardName = commander;
+  }
+
+  for (const cardName of mainCards) {
+    player.zones.library.push({
+      id: 'lib-' + playerIdx + '-' + cardName + '-' + Math.random().toString(36).slice(2, 6),
+      name: cardName,
+      imageUrl: '',
+      typeLine: '',
+      oracleText: '',
+      manaCost: '',
+    });
+  }
+
+  // Fisher-Yates shuffle
+  const lib = player.zones.library;
+  for (let i = lib.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [lib[i], lib[j]] = [lib[j], lib[i]];
+  }
+
+  // Draw opening hand
+  for (let d = 0; d < 7 && lib.length > 0; d++) {
+    player.zones.hand.push(lib.shift());
+  }
+
+  if (typeof updateZoneCountsForPlayer === 'function') updateZoneCountsForPlayer(playerIdx);
+  if (typeof renderCommanderZone === 'function') renderCommanderZone(playerIdx);
+  if (typeof renderHandZone === 'function') renderHandZone(playerIdx);
+
+  const label = deckLabel ? deckLabel.replace('.dck', '') : 'Unknown Deck';
+  addLogEntry(
+    '\uD83C\uDCCF <strong>' + player.name + '</strong> loaded: <em>' + label + '</em>' +
+    (commander ? ' \u2014 Commander: <strong>' + commander + '</strong>' : '') +
+    ' (' + lib.length + ' in library, 7 in hand)'
+  );
+}
+
+
+// ============================================================
+// SCRYFALL IMAGE ENRICHMENT
+// After zones are populated with card names, batch-fetch card
+// data from Scryfall and backfill imageUrl on every card object.
+// Uses the /cards/collection endpoint (75 cards per request).
+// Results are cached in _scryfallCache so re-renders are instant.
+// ============================================================
+
+async function enrichAllZonesWithScryfall() {
+  if (!gameState) return;
+
+  // Gather all unique card names across all players and all zones
+  const nameSet = new Set();
+  for (const player of gameState.players) {
+    for (const zone of Object.values(player.zones)) {
+      for (const card of zone) {
+        if (card.name && !_scryfallCache[card.name]) nameSet.add(card.name);
+      }
+    }
+  }
+
+  if (nameSet.size === 0) return;
+
+  const names = Array.from(nameSet);
+  addLogEntry('\uD83C\uDF0D Fetching card images from Scryfall (' + names.length + ' unique cards)...');
+
+  // Split into batches of 75 (Scryfall max)
+  const BATCH = 75;
+  for (let i = 0; i < names.length; i += BATCH) {
+    const batch = names.slice(i, i + BATCH);
+    try {
+      await _fetchScryfallBatch(batch);
+    } catch (e) {
+      console.warn('[precon-loader] Scryfall batch failed', e);
+    }
+    // Polite delay between batches to respect Scryfall rate limit (50-100ms)
+    if (i + BATCH < names.length) await _sleep(100);
+  }
+
+  // Apply cached data to every card object in every zone
+  _applyScryfallDataToAllCards();
+
+  addLogEntry('\u2705 Card images loaded.');
+}
+
+async function _fetchScryfallBatch(names) {
+  const identifiers = names.map(name => ({ name }));
+  const resp = await fetch(SCRYFALL_COLLECTION_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ identifiers }),
+  });
+  if (!resp.ok) throw new Error('Scryfall HTTP ' + resp.status);
+  const json = await resp.json();
+
+  for (const card of (json.data || [])) {
+    const name = card.name;
+    // Pick the best image: normal > large > small, handle double-faced
+    let imageUrl = '';
+    if (card.image_uris) {
+      imageUrl = card.image_uris.normal || card.image_uris.large || card.image_uris.small || '';
+    } else if (card.card_faces && card.card_faces[0] && card.card_faces[0].image_uris) {
+      imageUrl = card.card_faces[0].image_uris.normal || card.card_faces[0].image_uris.large || '';
+    }
+    _scryfallCache[name] = {
+      imageUrl,
+      typeLine:   card.type_line   || '',
+      oracleText: card.oracle_text || (card.card_faces && card.card_faces[0] ? card.card_faces[0].oracle_text : '') || '',
+      manaCost:   card.mana_cost   || (card.card_faces && card.card_faces[0] ? card.card_faces[0].mana_cost : '') || '',
+      power:      card.power       || '',
+      toughness:  card.toughness   || '',
+    };
+  }
+
+  // Mark not-found cards so we don't re-fetch them on next enrichment
+  for (const name of names) {
+    if (!_scryfallCache[name]) _scryfallCache[name] = { imageUrl: '', typeLine: '', oracleText: '', manaCost: '', power: '', toughness: '' };
+  }
+}
+
+function _applyScryfallDataToAllCards() {
+  if (!gameState) return;
+  for (const player of gameState.players) {
+    for (const zone of Object.values(player.zones)) {
+      for (const card of zone) {
+        const data = _scryfallCache[card.name];
+        if (data) {
+          card.imageUrl   = data.imageUrl   || card.imageUrl;
+          card.typeLine   = data.typeLine   || card.typeLine;
+          card.oracleText = data.oracleText || card.oracleText;
+          card.manaCost   = data.manaCost   || card.manaCost;
+          if (data.power)     card.power     = data.power;
+          if (data.toughness) card.toughness = data.toughness;
+        }
+      }
+    }
+    // Also enrich battlefield cards owned by this player
+    if (gameState.battlefieldCards) {
+      for (const card of gameState.battlefieldCards) {
+        if (card.ownerIndex !== player.id) continue;
+        const data = _scryfallCache[card.name];
+        if (data && !card.imageUrl) {
+          card.imageUrl   = data.imageUrl   || '';
+          card.typeLine   = data.typeLine   || card.typeLine;
+          card.oracleText = data.oracleText || card.oracleText;
+          card.manaCost   = data.manaCost   || card.manaCost;
+        }
+      }
+    }
+  }
+
+  // Trigger UI refresh so images appear without a full reload
+  if (typeof renderPlayerPanels === 'function') renderPlayerPanels();
+  if (typeof renderCommanderZone === 'function') {
+    for (let i = 0; i < gameState.players.length; i++) renderCommanderZone(i);
+  }
+  if (typeof renderHandZone === 'function') {
+    for (let i = 0; i < gameState.players.length; i++) renderHandZone(i);
+  }
+  if (typeof updateZoneCounts === 'function') updateZoneCounts();
+}
+
+/**
+ * Enrich a single card object on-demand (useful for cards drawn or played after initial load).
+ * Returns a Promise that resolves when the card's imageUrl is set.
+ */
+async function enrichCardWithScryfall(card) {
+  if (!card || !card.name) return;
+  if (card.imageUrl) return; // already has image
+
+  const cached = _scryfallCache[card.name];
+  if (cached) {
+    card.imageUrl   = cached.imageUrl   || '';
+    card.typeLine   = cached.typeLine   || card.typeLine;
+    card.oracleText = cached.oracleText || card.oracleText;
+    card.manaCost   = cached.manaCost   || card.manaCost;
+    return;
+  }
+
+  await _fetchScryfallBatch([card.name]);
+  const data = _scryfallCache[card.name];
+  if (data) {
+    card.imageUrl   = data.imageUrl   || '';
+    card.typeLine   = data.typeLine   || card.typeLine;
+    card.oracleText = data.oracleText || card.oracleText;
+    card.manaCost   = data.manaCost   || card.manaCost;
+  }
+}
+
+function _sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
@@ -0,0 +1,167 @@
+// Auto-generated from precon-decks/precon-index.json
+// Run: node scripts/generate-precons-js.js to regenerate
+var PRECON_DATA = [
+  {"id":"Counterpunch","name":"Counterpunch","commander":"Ghave, Guru of Spores","set":"Commander 2011","fileName":"Counterpunch.dck","colors":[],"year":2011},
+  {"id":"Devour_for_Power_CMD","name":"Devour for Power","commander":"The Mimeoplasm","set":"Commander 2011","fileName":"Devour_for_Power_CMD.dck","colors":[],"year":2011},
+  {"id":"Heavenly_Inferno_CMD","name":"Heavenly Inferno","commander":"Kaalia of the Vast","set":"Commander 2011","fileName":"Heavenly_Inferno_CMD.dck","colors":[],"year":2011},
+  {"id":"Mirror_Mastery","name":"Mirror Mastery","commander":"Riku of Two Reflections","set":"Commander 2011","fileName":"Mirror_Mastery.dck","colors":[],"year":2011},
+  {"id":"Political_Puppets","name":"Political Puppets","commander":"Zedruu the Greathearted","set":"Commander 2011","fileName":"Political_Puppets.dck","colors":[],"year":2011},
+  {"id":"Eternal_Bargain","name":"Eternal Bargain","commander":"Oloro, Ageless Ascetic","set":"Commander 2013","fileName":"Eternal_Bargain.dck","colors":[],"year":2013},
+  {"id":"Evasive_Maneuvers_C13","name":"Evasive Maneuvers","commander":"Derevi, Empyrial Tactician","set":"Commander 2013","fileName":"Evasive_Maneuvers_C13.dck","colors":[],"year":2013},
+  {"id":"Mind_Seize","name":"Mind Seize","commander":"Jeleva, Nephalia's Scourge","set":"Commander 2013","fileName":"Mind_Seize.dck","colors":[],"year":2013},
+  {"id":"Nature_of_the_Beast","name":"Nature of the Beast","commander":"Marath, Will of the Wild","set":"Commander 2013","fileName":"Nature_of_the_Beast.dck","colors":[],"year":2013},
+  {"id":"Power_Hungry","name":"Power Hungry","commander":"Prossh, Skyraider of Kher","set":"Commander 2013","fileName":"Power_Hungry.dck","colors":[],"year":2013},
+  {"id":"Built_From_Scratch_C14","name":"Built From Scratch","commander":"Daretti, Scrap Savant","set":"Commander 2014","fileName":"Built_From_Scratch_C14.dck","colors":[],"year":2014},
+  {"id":"Forged_In_Stone","name":"Forged In Stone","commander":"Nahiri, the Lithomancer","set":"Commander 2014","fileName":"Forged_In_Stone.dck","colors":[],"year":2014},
+  {"id":"Guided_By_Nature","name":"Guided By Nature","commander":"Freyalise, Llanowar's Fury","set":"Commander 2014","fileName":"Guided_By_Nature.dck","colors":[],"year":2014},
+  {"id":"Peer_Through_Time","name":"Peer Through Time","commander":"Teferi, Temporal Archmage","set":"Commander 2014","fileName":"Peer_Through_Time.dck","colors":[],"year":2014},
+  {"id":"Sworn_To_Darkness","name":"Sworn To Darkness","commander":"Ob Nixilis of the Black Oath","set":"Commander 2014","fileName":"Sworn_To_Darkness.dck","colors":[],"year":2014},
+  {"id":"Call_the_Spirits","name":"Call the Spirits","commander":"Daxos the Returned","set":"Commander 2015","fileName":"Call_the_Spirits.dck","colors":[],"year":2015},
+  {"id":"Plunder_the_Graves_C15","name":"Plunder the Graves","commander":"Meren of Clan Nel Toth","set":"Commander 2015","fileName":"Plunder_the_Graves_C15.dck","colors":[],"year":2015},
+  {"id":"Seize_Control","name":"Seize Control","commander":"Mizzix of the Izmagnus","set":"Commander 2015","fileName":"Seize_Control.dck","colors":[],"year":2015},
+  {"id":"Swell_the_Host","name":"Swell the Host","commander":"Ezuri, Claw of Progress","set":"Commander 2015","fileName":"Swell_the_Host.dck","colors":[],"year":2015},
+  {"id":"Wade_into_Battle_C15","name":"Wade into Battle","commander":"Kalemne, Disciple of Iroas","set":"Commander 2015","fileName":"Wade_into_Battle_C15.dck","colors":[],"year":2015},
+  {"id":"Breed_Lethality_C16","name":"Breed Lethality","commander":"Atraxa, Praetors' Voice","set":"Commander 2016","fileName":"Breed_Lethality_C16.dck","colors":[],"year":2016},
+  {"id":"Entropic_Uprising","name":"Entropic Uprising","commander":"Yidris, Maelstrom Wielder","set":"Commander 2016","fileName":"Entropic_Uprising.dck","colors":[],"year":2016},
+  {"id":"Invent_Superiority","name":"Invent Superiority","commander":"Breya, Etherium Shaper","set":"Commander 2016","fileName":"Invent_Superiority.dck","colors":[],"year":2016},
+  {"id":"Open_Hostility","name":"Open Hostility","commander":"Saskia the Unyielding","set":"Commander 2016","fileName":"Open_Hostility.dck","colors":[],"year":2016},
+  {"id":"Stalwart_Unity","name":"Stalwart Unity","commander":"Kynaios and Tiro of Meletis","set":"Commander 2016","fileName":"Stalwart_Unity.dck","colors":[],"year":2016},
+  {"id":"Evasive_Maneuvers_CMA","name":"Evasive Maneuvers","commander":"Derevi, Empyrial Tactician","set":"Commander Anthology","fileName":"Evasive_Maneuvers_CMA.dck","colors":[],"year":2017},
+  {"id":"Guided_by_Nature","name":"Guided by Nature","commander":"Freyalise, Llanowar's Fury","set":"Commander Anthology","fileName":"Guided_by_Nature.dck","colors":[],"year":2017},
+  {"id":"Heavenly_Inferno_CMA","name":"Heavenly Inferno","commander":"Kaalia of the Vast","set":"Commander Anthology","fileName":"Heavenly_Inferno_CMA.dck","colors":[],"year":2017},
+  {"id":"Plunder_the_Graves_CMA","name":"Plunder the Graves","commander":"Meren of Clan Nel Toth","set":"Commander Anthology","fileName":"Plunder_the_Graves_CMA.dck","colors":[],"year":2017},
+  {"id":"Arcane_Wizardry","name":"Arcane Wizardry","commander":"Inalla, Archmage Ritualist","set":"Commander 2017","fileName":"Arcane_Wizardry.dck","colors":[],"year":2017},
+  {"id":"Draconic_Domination","name":"Draconic Domination","commander":"The Ur-Dragon","set":"Commander 2017","fileName":"Draconic_Domination.dck","colors":[],"year":2017},
+  {"id":"Feline_Ferocity","name":"Feline Ferocity","commander":"Arahbo, Roar of the World","set":"Commander 2017","fileName":"Feline_Ferocity.dck","colors":[],"year":2017},
+  {"id":"Vampiric_Bloodlust","name":"Vampiric Bloodlust","commander":"Edgar Markov","set":"Commander 2017","fileName":"Vampiric_Bloodlust.dck","colors":[],"year":2017},
+  {"id":"Breed_Lethality_CM2","name":"Breed Lethality","commander":"Atraxa, Praetors' Voice","set":"Commander Anthology Volume II","fileName":"Breed_Lethality_CM2.dck","colors":[],"year":2018},
+  {"id":"Built_From_Scratch_CM2","name":"Built From Scratch","commander":"Daretti, Scrap Savant","set":"Commander Anthology Volume II","fileName":"Built_From_Scratch_CM2.dck","colors":[],"year":2018},
+  {"id":"Devour_for_Power_CM2","name":"Devour for Power","commander":"The Mimeoplasm","set":"Commander Anthology Volume II","fileName":"Devour_for_Power_CM2.dck","colors":[],"year":2018},
+  {"id":"Wade_into_Battle_CM2","name":"Wade into Battle","commander":"Kalemne, Disciple of Iroas","set":"Commander Anthology Volume II","fileName":"Wade_into_Battle_CM2.dck","colors":[],"year":2018},
+  {"id":"Adaptive_Enchantment","name":"Adaptive Enchantment","commander":"Estrid, the Masked","set":"Commander 2018","fileName":"Adaptive_Enchantment.dck","colors":[],"year":2018},
+  {"id":"Exquisite_Invention","name":"Exquisite Invention","commander":"Saheeli, the Gifted","set":"Commander 2018","fileName":"Exquisite_Invention.dck","colors":[],"year":2018},
+  {"id":"Natures_Vengeance","name":"Nature's Vengeance","commander":"Lord Windgrace","set":"Commander 2018","fileName":"Natures_Vengeance.dck","colors":[],"year":2018},
+  {"id":"Subjective_Reality","name":"Subjective Reality","commander":"Aminatou, the Fateshifter","set":"Commander 2018","fileName":"Subjective_Reality.dck","colors":[],"year":2018},
+  {"id":"Faceless_Menace","name":"Faceless Menace","commander":"Kadena, Slinking Sorcerer","set":"Commander 2019","fileName":"Faceless_Menace.dck","colors":[],"year":2019},
+  {"id":"Merciless_Rage","name":"Merciless Rage","commander":"Anje Falkenrath","set":"Commander 2019","fileName":"Merciless_Rage.dck","colors":[],"year":2019},
+  {"id":"Mystic_Intellect","name":"Mystic Intellect","commander":"Sevinne, the Chronoclasm","set":"Commander 2019","fileName":"Mystic_Intellect.dck","colors":[],"year":2019},
+  {"id":"Primal_Genesis","name":"Primal Genesis","commander":"Ghired, Conclave Exile","set":"Commander 2019","fileName":"Primal_Genesis.dck","colors":[],"year":2019},
+  {"id":"Arcane_Maelstrom","name":"Arcane Maelstrom","commander":"Kalamax, the Stormsire","set":"Commander 2020","fileName":"Arcane_Maelstrom.dck","colors":[],"year":2020},
+  {"id":"Enhanced_Evolution","name":"Enhanced Evolution","commander":"Otrimi, the Ever-Playful","set":"Commander 2020","fileName":"Enhanced_Evolution.dck","colors":[],"year":2020},
+  {"id":"Ruthless_Regiment","name":"Ruthless Regiment","commander":"Jirina Kudro","set":"Commander 2020","fileName":"Ruthless_Regiment.dck","colors":[],"year":2020},
+  {"id":"Symbiotic_Swarm","name":"Symbiotic Swarm","commander":"Kathril, Aspect Warper","set":"Commander 2020","fileName":"Symbiotic_Swarm.dck","colors":[],"year":2020},
+  {"id":"Timeless_Wisdom","name":"Timeless Wisdom","commander":"Gavi, Nest Warden","set":"Commander 2020","fileName":"Timeless_Wisdom.dck","colors":[],"year":2020},
+  {"id":"Lands_Wrath","name":"Land's Wrath","commander":"Obuun, Mul Daya Ancestor","set":"Zendikar Rising Commander","fileName":"Lands_Wrath.dck","colors":[],"year":2020},
+  {"id":"Sneak_Attack","name":"Sneak Attack","commander":"Anowon, the Ruin Thief","set":"Zendikar Rising Commander","fileName":"Sneak_Attack.dck","colors":[],"year":2020},
+  {"id":"Arm_for_Battle","name":"Arm for Battle","commander":"Wyleth, Soul of Steel","set":"Commander Legends","fileName":"Arm_for_Battle.dck","colors":[],"year":2020},
+  {"id":"Reap_the_Tides","name":"Reap the Tides","commander":"Aesi, Tyrant of Gyre Strait","set":"Commander Legends","fileName":"Reap_the_Tides.dck","colors":[],"year":2020},
+  {"id":"Elven_Empire","name":"Elven Empire","commander":"Lathril, Blade of the Elves","set":"Kaldheim Commander","fileName":"Elven_Empire.dck","colors":[],"year":2021},
+  {"id":"Phantom_Premonition","name":"Phantom Premonition","commander":"Ranar the Ever-Watchful","set":"Kaldheim Commander","fileName":"Phantom_Premonition.dck","colors":[],"year":2021},
+  {"id":"Lorehold_Legacies","name":"Lorehold Legacies","commander":"Osgir, the Reconstructor","set":"Commander 2021","fileName":"Lorehold_Legacies.dck","colors":[],"year":2021},
+  {"id":"Prismari_Performance","name":"Prismari Performance","commander":"Zaffai, Thunder Conductor","set":"Commander 2021","fileName":"Prismari_Performance.dck","colors":[],"year":2021},
+  {"id":"Quantum_Quandrix","name":"Quantum Quandrix","commander":"Adrix and Nev, Twincasters","set":"Commander 2021","fileName":"Quantum_Quandrix.dck","colors":[],"year":2021},
+  {"id":"Silverquill_Statement","name":"Silverquill Statement","commander":"Breena, the Demagogue","set":"Commander 2021","fileName":"Silverquill_Statement.dck","colors":[],"year":2021},
+  {"id":"Witherbloom_Witchcraft","name":"Witherbloom Witchcraft","commander":"Willowdusk, Essence Seer","set":"Commander 2021","fileName":"Witherbloom_Witchcraft.dck","colors":[],"year":2021},
+  {"id":"Aura_of_Courage","name":"Aura of Courage","commander":"Galea, Kindler of Hope","set":"Forgotten Realms Commander","fileName":"Aura_of_Courage.dck","colors":[],"year":2021},
+  {"id":"Draconic_Rage","name":"Draconic Rage","commander":"Vrondiss, Rage of Ancients","set":"Forgotten Realms Commander","fileName":"Draconic_Rage.dck","colors":[],"year":2021},
+  {"id":"Dungeons_of_Death","name":"Dungeons of Death","commander":"Sefris of the Hidden Ways","set":"Forgotten Realms Commander","fileName":"Dungeons_of_Death.dck","colors":[],"year":2021},
+  {"id":"Planar_Portal","name":"Planar Portal","commander":"Prosper, Tome-Bound","set":"Forgotten Realms Commander","fileName":"Planar_Portal.dck","colors":[],"year":2021},
+  {"id":"Coven_Counters","name":"Coven Counters","commander":"Leinore, Autumn Sovereign","set":"Midnight Hunt Commander","fileName":"Coven_Counters.dck","colors":[],"year":2021},
+  {"id":"Undead_Unleashed","name":"Undead Unleashed","commander":"Wilhelt, the Rotcleaver","set":"Midnight Hunt Commander","fileName":"Undead_Unleashed.dck","colors":[],"year":2021},
+  {"id":"Spirit_Squadron","name":"Spirit Squadron","commander":"Millicent, Restless Revenant","set":"Crimson Vow Commander","fileName":"Spirit_Squadron.dck","colors":[],"year":2021},
+  {"id":"Vampiric_Bloodline","name":"Vampiric Bloodline","commander":"Strefan, Maurer Progenitor","set":"Crimson Vow Commander","fileName":"Vampiric_Bloodline.dck","colors":[],"year":2021},
+  {"id":"Buckle_Up","name":"Buckle Up","commander":"Kotori, Pilot Prodigy","set":"Neon Dynasty Commander","fileName":"Buckle_Up.dck","colors":[],"year":2022},
+  {"id":"Upgrades_Unleashed","name":"Upgrades Unleashed","commander":"Chishiro, the Shattered Blade","set":"Neon Dynasty Commander","fileName":"Upgrades_Unleashed.dck","colors":[],"year":2022},
+  {"id":"Heads_I_Win,_Tails_You_Lose","name":"Heads I Win, Tails You Lose","commander":"Zndrsplt, Eye of Wisdom","set":"Secret Lair Drop","fileName":"Heads_I_Win,_Tails_You_Lose.dck","colors":[],"year":2022},
+  {"id":"Bedecked_Brokers","name":"Bedecked Brokers","commander":"Perrie, the Pulverizer","set":"New Capenna Commander","fileName":"Bedecked_Brokers.dck","colors":[],"year":2022},
+  {"id":"Cabaretti_Cacophony","name":"Cabaretti Cacophony","commander":"Kitt Kanto, Mayhem Diva","set":"New Capenna Commander","fileName":"Cabaretti_Cacophony.dck","colors":[],"year":2022},
+  {"id":"Maestros_Massacre","name":"Maestros Massacre","commander":"Anhelo, the Painter","set":"New Capenna Commander","fileName":"Maestros_Massacre.dck","colors":[],"year":2022},
+  {"id":"Obscura_Operation","name":"Obscura Operation","commander":"Kamiz, Obscura Oculus","set":"New Capenna Commander","fileName":"Obscura_Operation.dck","colors":[],"year":2022},
+  {"id":"Riveteers_Rampage","name":"Riveteers Rampage","commander":"Henzie \"Toolbox\" Torre","set":"New Capenna Commander","fileName":"Riveteers_Rampage.dck","colors":[],"year":2022},
+  {"id":"Draconic_Dissent","name":"Draconic Dissent","commander":"Firkraag, Cunning Instigator","set":"Commander Legends: Battle for Baldur's Gate","fileName":"Draconic_Dissent.dck","colors":[],"year":2022},
+  {"id":"Exit_from_Exile","name":"Exit from Exile","commander":"Faldorn, Dread Wolf Herald","set":"Commander Legends: Battle for Baldur's Gate","fileName":"Exit_from_Exile.dck","colors":[],"year":2022},
+  {"id":"Mind_Flayarrrs","name":"Mind Flayarrrs","commander":"Captain N'ghathrod","set":"Commander Legends: Battle for Baldur's Gate","fileName":"Mind_Flayarrrs.dck","colors":[],"year":2022},
+  {"id":"Party_Time","name":"Party Time","commander":"Nalia de'Arnise","set":"Commander Legends: Battle for Baldur's Gate","fileName":"Party_Time.dck","colors":[],"year":2022},
+  {"id":"Legends_Legacy","name":"Legends' Legacy","commander":"Dihada, Binder of Wills","set":"Dominaria United Commander","fileName":"Legends_Legacy.dck","colors":[],"year":2022},
+  {"id":"Painbow","name":"Painbow","commander":"Jared Carthalion","set":"Dominaria United Commander","fileName":"Painbow.dck","colors":[],"year":2022},
+  {"id":"Forces_of_the_Imperium","name":"Forces of the Imperium","commander":"Inquisitor Greyfax","set":"Warhammer 40,000 Commander","fileName":"Forces_of_the_Imperium.dck","colors":[],"year":2022},
+  {"id":"Forces_of_the_Imperium_Collectors_Edition","name":"Forces of the Imperium Collector's Edition","commander":"Inquisitor Greyfax","set":"Warhammer 40,000 Commander","fileName":"Forces_of_the_Imperium_Collectors_Edition.dck","colors":[],"year":2022},
+  {"id":"Necron_Dynasties","name":"Necron Dynasties","commander":"Szarekh, the Silent King","set":"Warhammer 40,000 Commander","fileName":"Necron_Dynasties.dck","colors":[],"year":2022},
+  {"id":"Necron_Dynasties_Collectors_Edition","name":"Necron Dynasties Collector's Edition","commander":"Szarekh, the Silent King","set":"Warhammer 40,000 Commander","fileName":"Necron_Dynasties_Collectors_Edition.dck","colors":[],"year":2022},
+  {"id":"The_Ruinous_Powers","name":"The Ruinous Powers","commander":"Abaddon the Despoiler","set":"Warhammer 40,000 Commander","fileName":"The_Ruinous_Powers.dck","colors":[],"year":2022},
+  {"id":"The_Ruinous_Powers_Collectors_Edition","name":"The Ruinous Powers Collector's Edition","commander":"Abaddon the Despoiler","set":"Warhammer 40,000 Commander","fileName":"The_Ruinous_Powers_Collectors_Edition.dck","colors":[],"year":2022},
+  {"id":"Tyranid_Swarm","name":"Tyranid Swarm","commander":"The Swarmlord","set":"Warhammer 40,000 Commander","fileName":"Tyranid_Swarm.dck","colors":[],"year":2022},
+  {"id":"Tyranid_Swarm_Collectors_Edition","name":"Tyranid Swarm Collector's Edition","commander":"The Swarmlord","set":"Warhammer 40,000 Commander","fileName":"Tyranid_Swarm_Collectors_Edition.dck","colors":[],"year":2022},
+  {"id":"Mishras_Burnished_Banner","name":"Mishra's Burnished Banner","commander":"Mishra, Eminent One","set":"The Brothers' War Commander","fileName":"Mishras_Burnished_Banner.dck","colors":[],"year":2022},
+  {"id":"Urzas_Iron_Alliance","name":"Urza's Iron Alliance","commander":"Urza, Chief Artificer","set":"The Brothers' War Commander","fileName":"Urzas_Iron_Alliance.dck","colors":[],"year":2022},
+  {"id":"Chaos_Incarnate","name":"Chaos Incarnate","commander":"Kardur, Doomscourge","set":"Starter Commander Decks","fileName":"Chaos_Incarnate.dck","colors":[],"year":2022},
+  {"id":"Draconic_Destruction","name":"Draconic Destruction","commander":"Atarka, World Render","set":"Starter Commander Decks","fileName":"Draconic_Destruction.dck","colors":[],"year":2022},
+  {"id":"First_Flight","name":"First Flight","commander":"Isperia, Supreme Judge","set":"Starter Commander Decks","fileName":"First_Flight.dck","colors":[],"year":2022},
+  {"id":"Grave_Danger","name":"Grave Danger","commander":"Gisa and Geralf","set":"Starter Commander Decks","fileName":"Grave_Danger.dck","colors":[],"year":2022},
+  {"id":"Token_Triumph","name":"Token Triumph","commander":"Emmara, Soul of the Accord","set":"Starter Commander Decks","fileName":"Token_Triumph.dck","colors":[],"year":2022},
+  {"id":"Corrupting_Influence","name":"Corrupting Influence","commander":"Ixhel, Scion of Atraxa","set":"Phyrexia: All Will Be One Commander","fileName":"Corrupting_Influence.dck","colors":[],"year":2023},
+  {"id":"Rebellion_Rising","name":"Rebellion Rising","commander":"Neyali, Suns' Vanguard","set":"Phyrexia: All Will Be One Commander","fileName":"Rebellion_Rising.dck","colors":[],"year":2023},
+  {"id":"From_Cute_to_Brute","name":"From Cute to Brute","commander":"Esika, God of the Tree","set":"Secret Lair Drop","fileName":"From_Cute_to_Brute.dck","colors":[],"year":2023},
+  {"id":"Elven_Council","name":"Elven Council","commander":"Galadriel, Elven-Queen","set":"Tales of Middle-earth Commander","fileName":"Elven_Council.dck","colors":[],"year":2023},
+  {"id":"Food_and_Fellowship","name":"Food and Fellowship","commander":"Frodo, Adventurous Hobbit","set":"Tales of Middle-earth Commander","fileName":"Food_and_Fellowship.dck","colors":[],"year":2023},
+  {"id":"Riders_of_Rohan","name":"Riders of Rohan","commander":"Éowyn, Shieldmaiden","set":"Tales of Middle-earth Commander","fileName":"Riders_of_Rohan.dck","colors":[],"year":2023},
+  {"id":"The_Hosts_of_Mordor","name":"The Hosts of Mordor","commander":"Sauron, Lord of the Rings","set":"Tales of Middle-earth Commander","fileName":"The_Hosts_of_Mordor.dck","colors":[],"year":2023},
+  {"id":"Eldrazi_Unbound","name":"Eldrazi Unbound","commander":"Zhulodok, Void Gorger","set":"Commander Masters","fileName":"Eldrazi_Unbound.dck","colors":[],"year":2023},
+  {"id":"Enduring_Enchantments","name":"Enduring Enchantments","commander":"Anikthea, Hand of Erebos","set":"Commander Masters","fileName":"Enduring_Enchantments.dck","colors":[],"year":2023},
+  {"id":"Planeswalker_Party","name":"Planeswalker Party","commander":"Commodore Guff","set":"Commander Masters","fileName":"Planeswalker_Party.dck","colors":[],"year":2023},
+  {"id":"Sliver_Swarm","name":"Sliver Swarm","commander":"Sliver Gravemother","set":"Commander Masters","fileName":"Sliver_Swarm.dck","colors":[],"year":2023},
+  {"id":"Angels_Theyre_Just_Like_Us_but_Cooler_and_with_Wings","name":"Angels: They're Just Like Us but Cooler and with Wings","commander":"Gisela, the Broken Blade","set":"Secret Lair Drop","fileName":"Angels_Theyre_Just_Like_Us_but_Cooler_and_with_Wings.dck","colors":[],"year":2023},
+  {"id":"Fae_Dominion","name":"Fae Dominion","commander":"Tegwyll, Duke of Splendor","set":"Wilds of Eldraine Commander","fileName":"Fae_Dominion.dck","colors":[],"year":2023},
+  {"id":"Virtue_and_Valor","name":"Virtue and Valor","commander":"Ellivere of the Wild Court","set":"Wilds of Eldraine Commander","fileName":"Virtue_and_Valor.dck","colors":[],"year":2023},
+  {"id":"Ahoy_Mateys","name":"Ahoy Mateys","commander":"Admiral Brass, Unsinkable","set":"The Lost Caverns of Ixalan Commander","fileName":"Ahoy_Mateys.dck","colors":[],"year":2023},
+  {"id":"Blood_Rites","name":"Blood Rites","commander":"Clavileño, First of the Blessed","set":"The Lost Caverns of Ixalan Commander","fileName":"Blood_Rites.dck","colors":[],"year":2023},
+  {"id":"Explorers_of_the_Deep","name":"Explorers of the Deep","commander":"Hakbal of the Surging Soul","set":"The Lost Caverns of Ixalan Commander","fileName":"Explorers_of_the_Deep.dck","colors":[],"year":2023},
+  {"id":"Veloci-Ramp-Tor","name":"Veloci-Ramp-Tor","commander":"Pantlaza, Sun-Favored","set":"The Lost Caverns of Ixalan Commander","fileName":"Veloci-Ramp-Tor.dck","colors":[],"year":2023},
+  {"id":"Raining_Cats_and_Dogs","name":"Raining Cats and Dogs","commander":"Rin and Seri, Inseparable","set":"Secret Lair Drop","fileName":"Raining_Cats_and_Dogs.dck","colors":[],"year":2024},
+  {"id":"Blame_Game","name":"Blame Game","commander":"Nelly Borca, Impulsive Accuser","set":"Murders at Karlov Manor Commander","fileName":"Blame_Game.dck","colors":[],"year":2024},
+  {"id":"Deadly_Disguise","name":"Deadly Disguise","commander":"Kaust, Eyes of the Glade","set":"Murders at Karlov Manor Commander","fileName":"Deadly_Disguise.dck","colors":[],"year":2024},
+  {"id":"Deep_Clue_Sea","name":"Deep Clue Sea","commander":"Morska, Undersea Sleuth","set":"Murders at Karlov Manor Commander","fileName":"Deep_Clue_Sea.dck","colors":[],"year":2024},
+  {"id":"Revenant_Recon","name":"Revenant Recon","commander":"Mirko, Obsessive Theorist","set":"Murders at Karlov Manor Commander","fileName":"Revenant_Recon.dck","colors":[],"year":2024},
+  {"id":"Hail,_Caesar","name":"Hail, Caesar","commander":"Caesar, Legion's Emperor","set":"Fallout","fileName":"Hail,_Caesar.dck","colors":[],"year":2024},
+  {"id":"Mutant_Menace","name":"Mutant Menace","commander":"The Wise Mothman","set":"Fallout","fileName":"Mutant_Menace.dck","colors":[],"year":2024},
+  {"id":"Science","name":"Science!","commander":"Dr. Madison Li","set":"Fallout","fileName":"Science.dck","colors":[],"year":2024},
+  {"id":"Scrappy_Survivors","name":"Scrappy Survivors","commander":"Dogmeat, Ever Loyal","set":"Fallout","fileName":"Scrappy_Survivors.dck","colors":[],"year":2024},
+  {"id":"Desert_Bloom","name":"Desert Bloom","commander":"Yuma, Proud Protector","set":"Outlaws of Thunder Junction Commander","fileName":"Desert_Bloom.dck","colors":[],"year":2024},
+  {"id":"Grand_Larceny","name":"Grand Larceny","commander":"Gonti, Canny Acquisitor","set":"Outlaws of Thunder Junction Commander","fileName":"Grand_Larceny.dck","colors":[],"year":2024},
+  {"id":"Most_Wanted","name":"Most Wanted","commander":"Olivia, Opulent Outlaw","set":"Outlaws of Thunder Junction Commander","fileName":"Most_Wanted.dck","colors":[],"year":2024},
+  {"id":"Quick_Draw","name":"Quick Draw","commander":"Stella Lee, Wild Card","set":"Outlaws of Thunder Junction Commander","fileName":"Quick_Draw.dck","colors":[],"year":2024},
+  {"id":"Creative_Energy","name":"Creative Energy","commander":"Satya, Aetherflux Genius","set":"Modern Horizons 3 Commander","fileName":"Creative_Energy.dck","colors":[],"year":2024},
+  {"id":"Creative_Energy_Collectors_Edition","name":"Creative Energy Collector's Edition","commander":"Satya, Aetherflux Genius","set":"Modern Horizons 3 Commander","fileName":"Creative_Energy_Collectors_Edition.dck","colors":[],"year":2024},
+  {"id":"Eldrazi_Incursion","name":"Eldrazi Incursion","commander":"Ulalek, Fused Atrocity","set":"Modern Horizons 3 Commander","fileName":"Eldrazi_Incursion.dck","colors":[],"year":2024},
+  {"id":"Eldrazi_Incursion_Collectors_Edition","name":"Eldrazi Incursion Collector's Edition","commander":"Ulalek, Fused Atrocity","set":"Modern Horizons 3 Commander","fileName":"Eldrazi_Incursion_Collectors_Edition.dck","colors":[],"year":2024},
+  {"id":"Graveyard_Overdrive","name":"Graveyard Overdrive","commander":"Disa the Restless","set":"Modern Horizons 3 Commander","fileName":"Graveyard_Overdrive.dck","colors":[],"year":2024},
+  {"id":"Graveyard_Overdrive_Collectors_Edition","name":"Graveyard Overdrive Collector's Edition","commander":"Disa the Restless","set":"Modern Horizons 3 Commander","fileName":"Graveyard_Overdrive_Collectors_Edition.dck","colors":[],"year":2024},
+  {"id":"Tricky_Terrain","name":"Tricky Terrain","commander":"Omo, Queen of Vesuva","set":"Modern Horizons 3 Commander","fileName":"Tricky_Terrain.dck","colors":[],"year":2024},
+  {"id":"Tricky_Terrain_Collectors_Edition","name":"Tricky Terrain Collector's Edition","commander":"Omo, Queen of Vesuva","set":"Modern Horizons 3 Commander","fileName":"Tricky_Terrain_Collectors_Edition.dck","colors":[],"year":2024},
+  {"id":"Animated_Army","name":"Animated Army","commander":"Bello, Bard of the Brambles","set":"Bloomburrow Commander","fileName":"Animated_Army.dck","colors":[],"year":2024},
+  {"id":"Family_Matters","name":"Family Matters","commander":"Zinnia, Valley's Voice","set":"Bloomburrow Commander","fileName":"Family_Matters.dck","colors":[],"year":2024},
+  {"id":"Peace_Offering","name":"Peace Offering","commander":"Ms. Bumbleflower","set":"Bloomburrow Commander","fileName":"Peace_Offering.dck","colors":[],"year":2024},
+  {"id":"Squirreled_Away","name":"Squirreled Away","commander":"Hazel of the Rootbloom","set":"Bloomburrow Commander","fileName":"Squirreled_Away.dck","colors":[],"year":2024},
+  {"id":"20_Ways_to_Win","name":"20 Ways to Win","commander":"Go-Shintai of Life's Origin","set":"Secret Lair Drop","fileName":"20_Ways_to_Win.dck","colors":[],"year":2024},
+  {"id":"Eternal_Might","name":"Eternal Might","commander":"Temmet, Naktamun's Will","set":"Aetherdrift Commander","fileName":"Eternal_Might.dck","colors":[],"year":2025},
+  {"id":"Living_Energy","name":"Living Energy","commander":"Saheeli, Radiant Creator","set":"Aetherdrift Commander","fileName":"Living_Energy.dck","colors":[],"year":2025},
+  {"id":"Abzan_Armor","name":"Abzan Armor","commander":"Felothar the Steadfast","set":"Tarkir: Dragonstorm Commander","fileName":"Abzan_Armor.dck","colors":[],"year":2025},
+  {"id":"Jeskai_Striker","name":"Jeskai Striker","commander":"Shiko and Narset, Unified","set":"Tarkir: Dragonstorm Commander","fileName":"Jeskai_Striker.dck","colors":[],"year":2025},
+  {"id":"Mardu_Surge","name":"Mardu Surge","commander":"Zurgo Stormrender","set":"Tarkir: Dragonstorm Commander","fileName":"Mardu_Surge.dck","colors":[],"year":2025},
+  {"id":"Sultai_Arisen","name":"Sultai Arisen","commander":"Teval, the Balanced Scale","set":"Tarkir: Dragonstorm Commander","fileName":"Sultai_Arisen.dck","colors":[],"year":2025},
+  {"id":"Temur_Roar","name":"Temur Roar","commander":"Eshki, Temur's Roar","set":"Tarkir: Dragonstorm Commander","fileName":"Temur_Roar.dck","colors":[],"year":2025},
+  {"id":"Everyones_Invited","name":"Everyone's Invited!","commander":"Morophon, the Boundless","set":"Secret Lair Drop","fileName":"Everyones_Invited.dck","colors":[],"year":2025},
+  {"id":"Counter_Blitz_(FINAL_FANTASY_X)","name":"Counter Blitz (FINAL FANTASY X)","commander":"Tidus, Yuna's Guardian","set":"Final Fantasy Commander","fileName":"Counter_Blitz_(FINAL_FANTASY_X).dck","colors":[],"year":2025},
+  {"id":"Counter_Blitz_Collectors_Edition_(FINAL_FANTASY_X)","name":"Counter Blitz Collector's Edition (FINAL FANTASY X)","commander":"Tidus, Yuna's Guardian","set":"Final Fantasy Commander","fileName":"Counter_Blitz_Collectors_Edition_(FINAL_FANTASY_X).dck","colors":[],"year":2025},
+  {"id":"Limit_Break_(FINAL_FANTASY_VII)","name":"Limit Break (FINAL FANTASY VII)","commander":"Cloud, Ex-SOLDIER","set":"Final Fantasy Commander","fileName":"Limit_Break_(FINAL_FANTASY_VII).dck","colors":[],"year":2025},
+  {"id":"Limit_Break_Collectors_Edition_(FINAL_FANTASY_VII)","name":"Limit Break Collector's Edition (FINAL FANTASY VII)","commander":"Cloud, Ex-SOLDIER","set":"Final Fantasy Commander","fileName":"Limit_Break_Collectors_Edition_(FINAL_FANTASY_VII).dck","colors":[],"year":2025},
+  {"id":"Revival_Trance_(FINAL_FANTASY_VI)","name":"Revival Trance (FINAL FANTASY VI)","commander":"Terra, Herald of Hope","set":"Final Fantasy Commander","fileName":"Revival_Trance_(FINAL_FANTASY_VI).dck","colors":[],"year":2025},
+  {"id":"Revival_Trance_Collectors_Edition_(FINAL_FANTASY_VI)","name":"Revival Trance Collector's Edition (FINAL FANTASY VI)","commander":"Terra, Herald of Hope","set":"Final Fantasy Commander","fileName":"Revival_Trance_Collectors_Edition_(FINAL_FANTASY_VI).dck","colors":[],"year":2025},
+  {"id":"Scions_&_Spellcraft_(FINAL_FANTASY_XIV)","name":"Scions & Spellcraft (FINAL FANTASY XIV)","commander":"Y'shtola, Night's Blessed","set":"Final Fantasy Commander","fileName":"Scions_&_Spellcraft_(FINAL_FANTASY_XIV).dck","colors":[],"year":2025},
+  {"id":"Scions_&_Spellcraft_Collectors_Edition_(FINAL_FANTASY_XIV)","name":"Scions & Spellcraft Collector's Edition (FINAL FANTASY XIV)","commander":"Y'shtola, Night's Blessed","set":"Final Fantasy Commander","fileName":"Scions_&_Spellcraft_Collectors_Edition_(FINAL_FANTASY_XIV).dck","colors":[],"year":2025},
+  {"id":"Counter_Intelligence","name":"Counter Intelligence","commander":"Inspirit, Flagship Vessel","set":"Edge of Eternities Commander","fileName":"Counter_Intelligence.dck","colors":[],"year":2025},
+  {"id":"World_Shaper","name":"World Shaper","commander":"Hearthhull, the Worldseed","set":"Edge of Eternities Commander","fileName":"World_Shaper.dck","colors":[],"year":2025},
+  {"id":"Blight_Curse","name":"Blight Curse","commander":"Auntie Ool, Cursewretch","set":"Lorwyn Eclipsed Commander","fileName":"Blight_Curse.dck","colors":[],"year":2026},
+  {"id":"Dance_of_the_Elements","name":"Dance of the Elements","commander":"Ashling, the Limitless","set":"Lorwyn Eclipsed Commander","fileName":"Dance_of_the_Elements.dck","colors":[],"year":2026},
+  {"id":"Turtle_Power","name":"Turtle Power!","commander":"Heroes in a Half Shell","set":"Teenage Mutant Ninja Turtles Eternal","fileName":"Turtle_Power.dck","colors":[],"year":2026}
+];
@@ -4,10 +4,15 @@ Commander AI Lab — Action Labeler
 Maps raw Forge action records (from DecisionSnapshot JSONL)
 to one of 8 macro-action labels for supervised policy learning.

-Classification logic:
-  1. Check action.type (cast, attack, land, cast_commander, pass)
-  2. For "cast" actions, classify by card oracle text / card type keywords
-  3. For ambiguous cases, use the raw log line and card name heuristics
+Classification logic (updated):
+  1. Check action.type for unambiguous types (attack, land, pass, hold,
+     cast_commander)
+  2. For "cast" actions:
+     a. If action.card is present, match directly against name databases
+     b. If action.card is absent (Forge omits it), scan the active
+        player's hand against name databases to infer the cast type.
+        Priority: removal > ramp > draw > commander > creature (default)
+  3. Fallback: PASS

 Macro-actions (from ml.config.scope):
  0: CAST_CREATURE    — Play a creature
@@ -41,11 +46,6 @@ logger = logging.getLogger("ml.labeler")
 # Card Type Keyword Databases
 # ══════════════════════════════════════════════════════════

-# Known removal spells (partial list — expanded from common Commander staples)
-REMOVAL_KEYWORDS = {
-    "destroy", "exile", "sacrifice", "counter", "bounce", "return.*to.*hand",
-    "-\\d+/-\\d+", "damage to", "fight", "deathtouch",
-}
 REMOVAL_CARD_NAMES = {
    "swords to plowshares", "path to exile", "beast within", "chaos warp",
    "counterspell", "swan song", "negate", "arcane denial", "doomblade",
@@ -62,45 +62,52 @@ REMOVAL_CARD_NAMES = {
    "decree of pain", "in garruk's wake", "plague wind",
    "fire covenant", "imprisoned in the moon", "darksteel mutation",
    "kenrith's transformation", "song of the dryads",
+    "abrade", "disenchant", "naturalize", "wear", "tear",
+    "shattering spree", "shatter", "smash to smithereens",
+    "lightning bolt", "lightning helix", "condemn", "oust",
+    "pongify", "reality shift", "turn to frog", "polymorph",
+    "boros charm", "utter end", "anguished unmaking", "mortify",
+    "putrefy", "maelstrom pulse", "void rend", "render silent",
+    "overwhelming denial", "test of talents", "dispel", "spell pierce",
+    "flusterstorm", "mental misstep", "pact of negation",
+    "opposition agent", "hullbreacher", "narset parter of veils",
+    "grafdigger's cage", "rest in peace", "leyline of the void",
+    "tormod's crypt", "relic of progenitus",
 }

-# Known draw spells
-DRAW_KEYWORDS = {
-    "draw", "scry", "look at the top", "reveal.*library",
-    "search your library.*hand", "impulse", "brainstorm",
-}
 DRAW_CARD_NAMES = {
    "rhystic study", "mystic remora", "phyrexian arena", "sylvan library",
    "harmonize", "blue sun's zenith", "pull from tomorrow",
    "windfall", "wheel of fortune", "timetwister", "brainstorm",
    "ponder", "preordain", "opt", "consider", "treasure cruise",
-    "dig through time", "fact or fiction", "nights whisper",
-    "nights whisper", "sign in blood", "read the bones",
-    "painful truths", "ambition's cost", "promise of power",
-    "necropotence", "dark confidant", "toski bearer of secrets",
-    "beast whisperer", "guardian project", "the great henge",
-    "skullclamp", "esper sentinel", "archivist of oghma",
-    "mind's eye", "consecrated sphinx", "ancient craving",
-    "faithless looting", "cathartic reunion", "thrill of possibility",
-    "jeska's will", "valakut awakening", "stinging study",
-    "night's whisper", "notion thief", "tymna the weaver",
-    "shamanic revelation", "rishkar's expertise", "return of the wildspeaker",
-    "garruk's uprising", "elemental bond", "kindred discovery",
-    "coastal piracy", "reconnaissance mission", "bident of thassa",
+    "dig through time", "fact or fiction", "night's whisper",
+    "sign in blood", "read the bones", "painful truths",
+    "ambition's cost", "promise of power", "necropotence",
+    "dark confidant", "toski bearer of secrets", "beast whisperer",
+    "guardian project", "the great henge", "skullclamp",
+    "esper sentinel", "archivist of oghma", "mind's eye",
+    "consecrated sphinx", "ancient craving", "faithless looting",
+    "cathartic reunion", "thrill of possibility", "jeska's will",
+    "valakut awakening", "stinging study", "notion thief",
+    "tymna the weaver", "shamanic revelation", "rishkar's expertise",
+    "return of the wildspeaker", "garruk's uprising", "elemental bond",
+    "kindred discovery", "coastal piracy", "reconnaissance mission",
+    "bident of thassa", "distant melody", "slate of ancestry",
+    "wheel of fate", "reforge the soul", "magus of the wheel",
+    "river's rebuke", "prosperity", "intellectual offering",
+    "peer into the abyss", "mind spring", "stroke of genius",
+    "jace's ingenuity", "tidings", "concentrate", "divination",
+    "inspiration", "counsel of the soratami", "accumulated knowledge",
+    "predict", "pressure point", "quicken", "serum visions",
+    "gitaxian probe", "mental note", "thought scour",
 }

-# Known ramp cards
-RAMP_KEYWORDS = {
-    "add {", "add one mana", "mana of any color",
-    "land.*onto the battlefield", "search.*basic land.*battlefield",
-}
 RAMP_CARD_NAMES = {
    "sol ring", "mana crypt", "mana vault", "arcane signet",
    "commander's sphere", "chromatic lantern", "fellwar stone",
    "mind stone", "thought vessel", "thran dynamo", "worn powerstone",
    "gilded lotus", "hedron archive", "everflowing chalice",
-    "coalition relic", "prismatic lens", "signets",  # catch-all partial
-    "talisman",  # catch-all for talisman cycle
+    "coalition relic", "prismatic lens",
    "cultivate", "kodama's reach", "rampant growth", "farseek",
    "nature's lore", "three visits", "skyshroud claim",
    "explosive vegetation", "migration path", "circuitous route",
@@ -112,13 +119,144 @@ RAMP_CARD_NAMES = {
    "birds of paradise", "llanowar elves", "elvish mystic",
    "fyndhorn elves", "avacyn's pilgrim", "elves of deep shadow",
    "bloom tender", "priest of titania", "selvala heart of the wilds",
+    "boreal druid", "green sun's zenith", "eternal witness",
+    "reclamation sage", "mystic snake", "fierce empath",
+    "signal the clans", "crop rotation", "harrow", "kodama's reach",
+    "traverse the ulvenwald", "search for tomorrow", "primal growth",
+    "land grant", "untamed wilds", "rangers path", "rangers' path",
+    "nissa's pilgrimage", "forest grove", "grove of the burnwillows",
+    "cabal stronghold", "urborg tomb of yawgmoth", "urborg, tomb of yawgmoth",
+    "bojuka bog", "ghost quarter", "field of ruin", "strip mine",
+    "wasteland", "tectonic edge", "dust bowl",
+    "worn powerstone", "basalt monolith", "grim monolith",
+    "mana geode", "darksteel ingot", "manalith", "opaline unicorn",
+    "vessel of endless rest", "corrupted grafstone", "dreamstone hedron",
+    "sisay's ring", "ur-golem's eye", "blinkmoth urn",
+    "astral cornucopia", "druids' repository", "black market",
+    "cryptolith rite", "earthcraft", "citanul hierophants",
+    "zendikar resurgent", "mirari's wake", "mana reflection",
+    "vorinclex voice of hunger", "vorinclex, voice of hunger",
 }

-# Known creature-type indicators
-CREATURE_KEYWORDS = {
-    "creature", "token", "enters the battlefield",
+# Partial-match prefixes (for cycles like Signets, Talismans)
+RAMP_PARTIAL_PREFIXES = {
+    "talisman", "signet", "locket", "banner", "obelisk",
+    "keyrune", "cluestone", "monolith", "medallion",
 }

+DRAW_PARTIAL_PREFIXES = {
+    "scroll", "tome", "journal",
+}
+
+
+# ══════════════════════════════════════════════════════════
+# Core classification helpers
+# ══════════════════════════════════════════════════════════
+
+def _classify_card_name(name: str) -> Optional[MacroAction]:
+    """
+    Classify a single card name into a MacroAction, or None if unknown.
+
+    Checks exact matches first, then partial prefix matches.
+    Returns None for unrecognised cards (caller handles the default).
+    """
+    n = name.lower().strip()
+    if not n:
+        return None
+
+    if n in REMOVAL_CARD_NAMES:
+        return MacroAction.CAST_REMOVAL
+    if n in DRAW_CARD_NAMES:
+        return MacroAction.CAST_DRAW
+    if n in RAMP_CARD_NAMES:
+        return MacroAction.CAST_RAMP
+
+    # Partial prefix match for cycles (Talismans, Signets, etc.)
+    for prefix in RAMP_PARTIAL_PREFIXES:
+        if n.startswith(prefix):
+            return MacroAction.CAST_RAMP
+    for prefix in DRAW_PARTIAL_PREFIXES:
+        if n.startswith(prefix):
+            return MacroAction.CAST_DRAW
+
+    # Substring match (catches "Doom Blade" inside longer names etc.)
+    for known in REMOVAL_CARD_NAMES:
+        if known in n or n in known:
+            return MacroAction.CAST_REMOVAL
+    for known in DRAW_CARD_NAMES:
+        if known in n or n in known:
+            return MacroAction.CAST_DRAW
+    for known in RAMP_CARD_NAMES:
+        if known in n or n in known:
+            return MacroAction.CAST_RAMP
+
+    return None  # Unknown → caller defaults to CAST_CREATURE
+
+
+def _classify_from_hand(
+    players: list,
+    active_seat: int,
+    commander_names: Optional[set] = None,
+) -> MacroAction:
+    """
+    Infer the cast action type by scanning the active player's hand.
+
+    When action.card is absent (Forge omits it), the hand snapshot
+    is the best available signal.  We scan all hand cards and return
+    the highest-priority match:
+
+        removal > ramp > draw > commander > creature (default)
+
+    Priority rationale: Forge's AI plays the highest-impact available
+    action, so if any removal/ramp/draw spell is in hand during a cast
+    decision, it's the most likely card played.
+    """
+    if active_seat >= len(players):
+        return MacroAction.CAST_CREATURE
+
+    hand: List[str] = players[active_seat].get("hand", [])
+    command_zone: List[str] = players[active_seat].get("command_zone", [])
+
+    # Build commander name set from command_zone if not provided
+    if commander_names is None:
+        commander_names = {c.lower().strip() for c in command_zone if c}
+
+    found_removal = False
+    found_ramp = False
+    found_draw = False
+    found_commander = False
+
+    for card in hand:
+        card_lower = card.lower().strip()
+
+        # Commander check: hand card matches a command zone card
+        if card_lower in commander_names:
+            found_commander = True
+            continue
+
+        result = _classify_card_name(card_lower)
+        if result == MacroAction.CAST_REMOVAL:
+            found_removal = True
+        elif result == MacroAction.CAST_RAMP:
+            found_ramp = True
+        elif result == MacroAction.CAST_DRAW:
+            found_draw = True
+
+    # Return highest-priority found
+    if found_removal:
+        return MacroAction.CAST_REMOVAL
+    if found_ramp:
+        return MacroAction.CAST_RAMP
+    if found_draw:
+        return MacroAction.CAST_DRAW
+    if found_commander:
+        return MacroAction.CAST_COMMANDER
+    return MacroAction.CAST_CREATURE
+
+
+# ══════════════════════════════════════════════════════════
+# Main label_action entry point
+# ══════════════════════════════════════════════════════════

 def label_action(decision: dict) -> int:
    """
@@ -133,74 +271,52 @@ def label_action(decision: dict) -> int:
    action = decision.get("action", {})
    action_type = action.get("type", "").lower()
    card_name = (action.get("card", "") or "").lower().strip()
-    raw_line = (action.get("raw", "") or "").lower()

-    # ── Direct type matching ────────────────────────────
+    players = decision.get("players", [])
+    active_seat = decision.get("active_seat", 0)
+
+    # ── Unambiguous direct-type matches ──────────────────────

-    # Commander cast is unambiguous
    if action_type == "cast_commander":
        return ACTION_TO_IDX[MacroAction.CAST_COMMANDER]

-    # Attack is unambiguous
    if action_type == "attack":
        return ACTION_TO_IDX[MacroAction.ATTACK_OPPONENT]

-    # Land play → classify as CAST_RAMP (developing mana is ramp)
+    # Land play → developing mana base = ramp
    if action_type == "land":
        return ACTION_TO_IDX[MacroAction.CAST_RAMP]

-    # Pass / hold mana
+    # Pass / hold mana — check available mana to distinguish
    if action_type in ("pass", "hold"):
-        # Check if player had mana open (from state)
-        active_seat = decision.get("active_seat", 0)
-        players = decision.get("players", [])
        if active_seat < len(players):
            mana = players[active_seat].get("mana", 0)
            if mana >= 2:
                return ACTION_TO_IDX[MacroAction.HOLD_MANA]
        return ACTION_TO_IDX[MacroAction.PASS]

-    # ── Cast actions: classify by card identity ─────────
+    # ── Cast actions ──────────────────────────────────────

    if action_type == "cast":
-        # 1. Check known card name databases
-        if card_name in REMOVAL_CARD_NAMES or _partial_match(card_name, REMOVAL_CARD_NAMES):
-            return ACTION_TO_IDX[MacroAction.CAST_REMOVAL]
+        # Path A: action.card is present — classify it directly
+        if card_name:
+            result = _classify_card_name(card_name)
+            if result is not None:
+                return ACTION_TO_IDX[result]
+            # Unrecognised named card → default creature
+            return ACTION_TO_IDX[MacroAction.CAST_CREATURE]

-        if card_name in DRAW_CARD_NAMES or _partial_match(card_name, DRAW_CARD_NAMES):
-            return ACTION_TO_IDX[MacroAction.CAST_DRAW]
+        # Path B: action.card absent (Forge omits it) — infer from hand
+        inferred = _classify_from_hand(players, active_seat)
+        return ACTION_TO_IDX[inferred]

-        if card_name in RAMP_CARD_NAMES or _partial_match(card_name, RAMP_CARD_NAMES):
-            return ACTION_TO_IDX[MacroAction.CAST_RAMP]
-
-        # 2. Check raw log line for keyword patterns
-        for keyword in REMOVAL_KEYWORDS:
-            if re.search(keyword, raw_line):
-                return ACTION_TO_IDX[MacroAction.CAST_REMOVAL]
-
-        for keyword in DRAW_KEYWORDS:
-            if re.search(keyword, raw_line):
-                return ACTION_TO_IDX[MacroAction.CAST_DRAW]
-
-        for keyword in RAMP_KEYWORDS:
-            if re.search(keyword, raw_line):
-                return ACTION_TO_IDX[MacroAction.CAST_RAMP]
-
-        # 3. Default: if it's a spell cast and not recognized, assume creature
-        #    (most casts in Commander are creatures or creature-adjacent)
-        return ACTION_TO_IDX[MacroAction.CAST_CREATURE]
-
-    # ── Fallback ────────────────────────────────────────
+    # ── Fallback ──────────────────────────────────────────
    return ACTION_TO_IDX[MacroAction.PASS]


-def _partial_match(name: str, name_set: set) -> bool:
-    """Check if card name partially matches any name in the set."""
-    for known in name_set:
-        if known in name or name in known:
-            return True
-    return False
-
+# ══════════════════════════════════════════════════════════
+# File-level helpers
+# ══════════════════════════════════════════════════════════

 def label_decisions_file(jsonl_path: str) -> Tuple[np.ndarray, List[dict]]:
    """
@@ -232,7 +348,11 @@ def label_decisions_file(jsonl_path: str) -> Tuple[np.ndarray, List[dict]]:


 def print_label_distribution(labels: np.ndarray) -> Dict[str, int]:
-    """Print and return the distribution of action labels."""
+    """Print and return the distribution of action labels.
+
+    Iterates MacroAction enum in index order so the display always
+    matches ACTION_TO_IDX regardless of dict insertion order.
+    """
    dist = {}
    for action in MacroAction:
        idx = ACTION_TO_IDX[action]
@@ -242,10 +362,11 @@ def print_label_distribution(labels: np.ndarray) -> Dict[str, int]:
    total = len(labels)
    logger.info(f"\n{'Action':<25} {'Count':>8} {'Pct':>8}")
    logger.info("─" * 43)
+    # Sort descending by count for readability
    for action_name, count in sorted(dist.items(), key=lambda x: -x[1]):
        pct = (count / total * 100) if total > 0 else 0
        logger.info(f"  {action_name:<23} {count:>8} {pct:>7.1f}%")
-    logger.info(f"{'─' * 43}")
+    logger.info("─" * 43)
    logger.info(f"  {'TOTAL':<23} {total:>8}")

    return dist
@@ -6,8 +6,9 @@ Reads ML decision JSONL files, encodes states, labels actions,
 and produces a training-ready dataset saved as NPZ.

 Phase 2: Source Awareness (Issue #66)
-  - Scans both Forge sim files (ml-decisions-sim-*.jsonl) and
-    PPO self-play files (ml-decisions-ppo-*.jsonl)
+  - Scans Forge sim files  (ml-decisions-sim-*.jsonl)  → source "forge"
+  - Scans PPO self-play    (ml-decisions-ppo-*.jsonl)  → source "ppo"
+  - Scans DeepSeek files   (ml-decisions-ds-*.jsonl)   → source "ds"
  - Configurable source_weights for sampling ratios
  - min_reward_threshold filter for PPO data quality
  - Each sample tagged with source for downstream analysis
@@ -21,7 +22,7 @@ Output NPZ structure:
    game_ids:   object  (N,)      — game ID for each sample
    outcomes:   object  (N,)      — game outcome per sample
    playstyles: object  (N,)      — deck archetype per sample
-    sources:    object  (N,)      — data source ("forge" or "ppo")
+    sources:    object  (N,)      — data source ("forge", "ppo", or "ds")
 """

 import argparse
@@ -62,11 +63,11 @@ class DatasetConfig:
    embeddings_dir: Optional[str] = None
    max_samples: Optional[int] = None

-    # Source weights control sampling ratios between Forge and PPO data.
-    # Default: Forge-only (ppo=0.0). Use MIXED_MODE_PRESETS from
-    # ml.config.scope for blended configurations (e.g. 90/10, 80/20).
+    # Source weights control sampling ratios between Forge, PPO, and DS data.
+    # ds=4.0 oversamples the 8 DeepSeek files from ~5.8% → ~20% of effective
+    # training tokens, matching their higher signal quality relative to sim data.
    source_weights: Dict[str, float] = field(
-        default_factory=lambda: {"forge": 1.0, "ppo": 0.0}
+        default_factory=lambda: {"forge": 1.0, "ppo": 0.0, "ds": 4.0}
    )

    # Minimum reward threshold for PPO data — only include decisions
@@ -81,12 +82,13 @@ class DatasetConfig:

 def _discover_jsonl_files(results_dir: str) -> Dict[str, List[Path]]:
    """
-    Scan results directory for both Forge sim and PPO decision files.
+    Scan results directory for Forge sim, PPO, and DeepSeek decision files.

    Returns:
        Dict mapping source name to list of JSONL file paths.
        Keys: "forge" for ml-decisions-sim-*.jsonl
              "ppo"   for ml-decisions-ppo-*.jsonl
+              "ds"    for ml-decisions-ds-*.jsonl
    """
    results_path = Path(results_dir)
    sources = {}
@@ -101,10 +103,16 @@ def _discover_jsonl_files(results_dir: str) -> Dict[str, List[Path]]:
    if ppo_files:
        sources["ppo"] = ppo_files

-    # Also pick up legacy files that don't have sim/ppo prefix
+    # DeepSeek high-quality decisions (upweighted by default)
+    ds_files = sorted(results_path.glob("ml-decisions-ds-*.jsonl"))
+    if ds_files:
+        sources["ds"] = ds_files
+
+    # Legacy files that don't match any known prefix — treat as forge
+    known = set(forge_files + ppo_files + ds_files)
    legacy_files = sorted(
        f for f in results_path.glob("ml-decisions-*.jsonl")
-        if f not in set(forge_files + ppo_files)
+        if f not in known
    )
    if legacy_files:
        sources.setdefault("forge", []).extend(legacy_files)
@@ -123,7 +131,7 @@ def _passes_reward_filter(
 ) -> bool:
    """
    Filter PPO decisions by reward threshold.
-    Forge data always passes. PPO data must meet the threshold.
+    Forge and DS data always passes. PPO data must meet the threshold.
    """
    if source != "ppo":
        return True
@@ -155,7 +163,7 @@ def _apply_source_weights(
        if weight <= 0:
            logger.info("  Skipping %d %s samples (weight=0)", len(samples), source)
            continue
-        if weight >= 1.0 and weight == 1.0:
+        if weight == 1.0:
            combined.extend(samples)
        elif weight < 1.0:
            # Subsample
@@ -193,8 +201,9 @@ def build_dataset(
    Build complete training dataset from all ML decision files.

    Phase 2 additions:
-      - Scans both Forge and PPO JSONL files
+      - Scans Forge, PPO, and DeepSeek (ds) JSONL files
      - Applies source_weights for configurable mixing
+        (default: ds=4.0 to oversample high-quality DeepSeek decisions)
      - Filters PPO data by min_reward_threshold
      - Tags each sample with its source

@@ -202,14 +211,15 @@ def build_dataset(
        results_dir: Path to results/ directory containing JSONL files
        embeddings_dir: Path to embeddings/ directory (default: auto-detect)
        max_samples: Cap total samples (None = unlimited)
-        source_weights: Dict of source → sampling weight (default: forge=1.0, ppo=0.5)
+        source_weights: Dict of source → sampling weight
+                        (default: forge=1.0, ppo=0.0, ds=4.0)
        min_reward_threshold: Min episode_return for PPO data (default: 0.0)

    Returns:
        Dict with keys: states, labels, game_ids, outcomes, playstyles, sources
    """
    if source_weights is None:
-        source_weights = {"forge": 1.0, "ppo": 0.0}
+        source_weights = {"forge": 1.0, "ppo": 0.0, "ds": 4.0}

    # Load card embeddings
    card_index = CardEmbeddingIndex(embeddings_dir)
@@ -225,7 +235,7 @@ def build_dataset(

    encoder = StateEncoder(card_index)

-    # --- Phase 2 Task 1: Discover files from both sources ---
+    # --- Phase 2 Task 1: Discover files from all sources ---
    source_files = _discover_jsonl_files(results_dir)
    if not source_files:
        logger.error("No ML decision files found in %s", results_dir)
@@ -503,7 +513,11 @@ def main():
    )
    parser.add_argument(
        "--ppo-weight", type=float, default=0.0,
-        help="Sampling weight for PPO self-play data (default: 0.0, Forge-only)",
+        help="Sampling weight for PPO self-play data (default: 0.0, disabled)",
+    )
+    parser.add_argument(
+        "--ds-weight", type=float, default=4.0,
+        help="Sampling weight for DeepSeek decision data (default: 4.0, ~20%% effective share)",
    )
    parser.add_argument(
        "--min-reward", type=float, default=0.0,
@@ -515,6 +529,7 @@ def main():
    source_weights = {
        "forge": args.forge_weight,
        "ppo": args.ppo_weight,
+        "ds": args.ds_weight,
    }

    # Build dataset
@@ -167,6 +167,24 @@ class CardEmbeddingIndex:
        return self._loaded


+def _resolve_cmdr_dmg(raw) -> int:
+    """Collapse cmdr_dmg to a scalar integer regardless of source format.
+
+    Forge sends cmdr_dmg as a dict keyed by opponent seat string, e.g.
+    {"0": 14, "2": 7}.  _build_encoder_snapshot already sums this before
+    passing to predict(), but the live Forge IPC path (and legacy JSONL)
+    may send the raw dict.  Summing all values is correct for Commander:
+    the total commander damage received from all opponents is what matters
+    for the life-loss threshold (21).
+    """
+    if isinstance(raw, dict):
+        return sum(int(v) for v in raw.values())
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return 0
+
+
 class StateEncoder:
    """
    Encodes a decision snapshot JSON dict into a fixed-size numpy vector.
@@ -241,6 +259,10 @@ class StateEncoder:
        Index 7 priority for total_power:
          1. p['total_power']  — real Forge value from Step 4 / _build_encoder_snapshot()
          2. p['creatures'] * 3  — legacy heuristic for old JSONL snapshots
+
+        cmdr_dmg is resolved via _resolve_cmdr_dmg() which handles both the
+        live Forge format (dict keyed by opponent seat) and the pre-collapsed
+        int from _build_encoder_snapshot / JSONL training snapshots.
        """
        features = []

@@ -250,7 +272,8 @@ class StateEncoder:
            features.append(life / 40.0)

            # idx 1: commander damage taken
-            cmdr_dmg = p.get("cmdr_dmg", 0)
+            # _resolve_cmdr_dmg handles dict (live Forge IPC) and int (JSONL/pre-collapsed)
+            cmdr_dmg = _resolve_cmdr_dmg(p.get("cmdr_dmg", 0))
            features.append(cmdr_dmg / 21.0)

            # idx 2: mana available
@@ -52,14 +52,44 @@ from ml.config.scope import (
 )
 from ml.encoder.state_encoder import CardEmbeddingIndex, StateEncoder

-logger = logging.getLogger("ml.serving")
+# Unique logger name so log lines are attributable to this module specifically
+logger = logging.getLogger("ml.serving.policy_server")
+
+
+def _unwrap_logits(raw):
+    """
+    Normalise whatever self.model() returns to a plain logits tensor.
+
+    PolicyNetwork.forward() returns a raw tensor, but the model may be
+    wrapped (DataParallel, torch.compile) or accidentally swapped for
+    PolicyValueNetwork whose forward_with_value() returns (logits, value).
+    A dict return would cause 'dict / float' TypeError on the temperature
+    division -- guard against all three cases here.
+    """
+    if isinstance(raw, (tuple, list)):
+        # (logits, value) from PolicyValueNetwork or similar
+        return raw[0]
+    if isinstance(raw, dict):
+        # e.g. {"logits": tensor, "value": tensor}
+        for key in ("logits", "policy", "action_logits"):
+            if key in raw:
+                return raw[key]
+        # Fallback: grab the first tensor value in the dict
+        for v in raw.values():
+            if isinstance(v, torch.Tensor):
+                return v
+        raise TypeError(
+            f"model() returned a dict with no recognisable logits key: {list(raw.keys())}"
+        )
+    # Plain tensor -- the normal case
+    return raw


 class PolicyInferenceService:
    """
    Loads a trained PolicyNetwork and provides action predictions.

-    Thread-safe — uses torch.no_grad() for inference.
+    Thread-safe -- uses torch.no_grad() for inference.
    Designed to be embedded in lab_api.py or run standalone.
    """

@@ -100,7 +130,7 @@ class PolicyInferenceService:
        """
        if not TORCH_AVAILABLE:
            self._load_error = "PyTorch not installed"
-            logger.error("PyTorch not installed — cannot serve policy")
+            logger.error("PyTorch not installed -- cannot serve policy")
            return False

        # 1. Load card embeddings
@@ -146,7 +176,7 @@ class PolicyInferenceService:

        except Exception as e:
            self._load_error = str(e)
-            logger.error("Failed to load checkpoint: %s", e)
+            logger.error("Failed to load checkpoint: %s", e, exc_info=True)
            return False

    def reload(self, checkpoint_path: str = None) -> bool:
@@ -178,7 +208,7 @@ class PolicyInferenceService:

        except Exception as e:
            self._load_error = str(e)
-            logger.error("Hot-reload failed: %s", e)
+            logger.error("Hot-reload failed: %s", e, exc_info=True)
            return False

    def predict(
@@ -224,7 +254,10 @@ class PolicyInferenceService:

            # Run inference
            with torch.no_grad():
-                logits = self.model(state_tensor)
+                raw_output = self.model(state_tensor)
+                # Guard: unwrap tuple/dict returns (DataParallel, torch.compile,
+                # or accidental PolicyValueNetwork swap) before any arithmetic.
+                logits = _unwrap_logits(raw_output)

                if greedy:
                    action_idx = logits.argmax(dim=-1).item()
@@ -254,7 +287,7 @@ class PolicyInferenceService:

        except Exception as e:
            elapsed_ms = (time.time() - t_start) * 1000
-            logger.error("Inference error: %s", e)
+            logger.error("Inference error: %s", e, exc_info=True)
            return {
                "error": str(e),
                "inference_ms": round(elapsed_ms, 2),
@@ -286,7 +319,9 @@ class PolicyInferenceService:

            # Batch inference
            with torch.no_grad():
-                logits = self.model(state_tensor)
+                raw_output = self.model(state_tensor)
+                # Same guard as predict() -- unwrap before softmax/argmax.
+                logits = _unwrap_logits(raw_output)
                probs = torch.softmax(logits, dim=-1).cpu().numpy()

                if greedy:
@@ -312,7 +347,7 @@ class PolicyInferenceService:
            )

        except Exception as e:
-            logger.error("Batch inference error: %s", e)
+            logger.error("Batch inference error: %s", e, exc_info=True)
            results = [{"error": str(e)}] * len(snapshots)

        return results
@@ -331,9 +366,9 @@ class PolicyInferenceService:
        }


-# ══════════════════════════════════════════════════════════
+# ==========================================================
 # Standalone FastAPI Server
-# ══════════════════════════════════════════════════════════
+# ==========================================================

 def create_standalone_app():
    """Create a standalone FastAPI app for the policy server."""
@@ -341,7 +376,7 @@ def create_standalone_app():
    from pydantic import BaseModel

    app = FastAPI(
-        title="Commander AI Lab — Policy Server",
+        title="Commander AI Lab -- Policy Server",
        description="Serves macro-action predictions from a trained policy network",
        version="1.0.0",
    )
@@ -424,7 +459,7 @@ def main():
    import uvicorn

    parser = argparse.ArgumentParser(
-        description="Commander AI Lab — Policy Inference Server"
+        description="Commander AI Lab -- Policy Inference Server"
    )
    parser.add_argument("--port", type=int, default=8090)
    parser.add_argument("--host", default="127.0.0.1")
@@ -34,6 +34,7 @@ from ml.training.reward import (
    compute_intermediate_reward,
    compute_terminal_reward,
 )
+from ml.training.decision_exporter import DecisionExporter, ExporterConfig

 logger = logging.getLogger("ml.forge_episode_generator")

@@ -51,6 +52,8 @@ class ForgeTransition:
    log_prob: float
    value: float
    done: bool
+    # Raw snapshot retained so the exporter can reconstruct game-state context
+    snapshot: Optional[Dict[str, Any]] = None


@dataclass
@@ -61,6 +64,8 @@ class ForgeEpisode:
    winner: Optional[int] = None
    total_turns: int = 0
    deck_names: List[str] = field(default_factory=list)
+    agent_seat: int = 0
+    playstyle: str = "midrange"

    @property
    def length(self) -> int:
@@ -70,6 +75,10 @@ class ForgeEpisode:
    def total_reward(self) -> float:
        return sum(t.reward for t in self.transitions)

+    @property
+    def won(self) -> bool:
+        return self.winner == self.agent_seat
+

 # ══════════════════════════════════════════════════════════
 # JSONL Parser — reads Forge ML decision snapshots
@@ -95,9 +104,44 @@ def parse_forge_jsonl(path: Path) -> List[Dict[str, Any]]:
    return snapshots


+def _make_minimal_state(snap: Dict[str, Any]) -> Dict[str, Any]:
+    """Build a minimal prev/curr state dict from a Forge snapshot.
+
+    compute_intermediate_reward() expects a dict with a 'players' list
+    where each player has 'life_total', 'cards_in_hand',
+    'creatures_on_battlefield', etc.  Forge snapshots carry a 'players'
+    array directly; we forward it as-is and fall back to scalar fields
+    when the array is absent.
+    """
+    if "players" in snap:
+        return {"players": snap["players"]}
+
+    # Fallback: reconstruct a two-player view from flat snapshot fields
+    agent_seat = snap.get("active_seat", 0)
+    opp_seat = 1 - agent_seat
+    players = [None, None]
+
+    def _player(life_key: str, hand_key: str, creatures_key: str) -> Dict:
+        return {
+            "life_total": snap.get(life_key, 40),
+            "cards_in_hand": snap.get(hand_key, 0),
+            "creatures_on_battlefield": snap.get(creatures_key, 0),
+            "cards_in_graveyard": 0,
+            "mana_available": snap.get("mana_available", 0),
+            "commander_damage_taken": 0,
+            "total_power_on_board": 0,
+        }
+
+    players[agent_seat] = _player("agent_life", "agent_hand_size", "agent_creatures")
+    players[opp_seat] = _player("opp_life", "opp_hand_size", "opp_creatures")
+    return {"players": players}
+
+
 def snapshots_to_episode(
    snapshots: List[Dict[str, Any]],
    reward_config: Optional[RewardConfig] = None,
+    agent_seat: int = 0,
+    playstyle: str = "midrange",
 ) -> ForgeEpisode:
    """Convert a sequence of Forge snapshots into a ForgeEpisode.

@@ -111,6 +155,8 @@ def snapshots_to_episode(
    episode = ForgeEpisode(
        game_id=first.get("game_id", "unknown"),
        deck_names=first.get("deck_names", []),
+        agent_seat=agent_seat,
+        playstyle=playstyle,
    )

    rc = reward_config or RewardConfig()
@@ -130,20 +176,26 @@ def snapshots_to_episode(
        except (ValueError, KeyError):
            action_idx = ACTION_TO_IDX[MacroAction.PASS]

-        # Reward
+        # Reward — use correct reward.py signatures
        is_done = i == len(snapshots) - 1
        if is_done and "outcome" in snap:
+            outcome = snap["outcome"]
            reward = compute_terminal_reward(
-                won=snap["outcome"].get("won", False),
-                turns=snap.get("turn", 1),
-                life_remaining=snap["outcome"].get("life_remaining", 0),
+                won=outcome.get("won", False),
+                draw=outcome.get("draw", False),
+                timeout=outcome.get("timeout", False),
                config=rc,
            )
        else:
+            # Build minimal prev/curr dicts for intermediate reward
+            prev_snap = snapshots[i - 1] if i > 0 else snap
+            prev_state = _make_minimal_state(prev_snap)
+            curr_state = _make_minimal_state(snap)
            reward = compute_intermediate_reward(
-                life_delta=snap.get("life_delta", 0),
-                cards_drawn=snap.get("cards_drawn", 0),
-                creatures_played=snap.get("creatures_played", 0),
+                prev_state=prev_state,
+                curr_state=curr_state,
+                action_taken=action_label,
+                agent_seat=agent_seat,
                config=rc,
            )

@@ -154,6 +206,7 @@ def snapshots_to_episode(
            log_prob=snap.get("log_prob", 0.0),
            value=snap.get("value", 0.0),
            done=is_done,
+            snapshot=snap,
        ))

    episode.total_turns = snapshots[-1].get("turn", len(snapshots))
@@ -163,6 +216,61 @@ def snapshots_to_episode(
    return episode


+# ══════════════════════════════════════════════════════════
+# DecisionExporter adapter for Forge episodes
+# ══════════════════════════════════════════════════════════
+
+def _export_forge_episode(episode: ForgeEpisode, exporter: DecisionExporter) -> None:
+    """Feed a completed ForgeEpisode into the DecisionExporter.
+
+    Translates each ForgeTransition back into the game_state_snapshot
+    format expected by DecisionExporter.record_step(), then finalises
+    the episode so the exporter can apply its win/length gates.
+
+    The raw snapshot stored on each ForgeTransition is used directly
+    when available; otherwise a minimal dict is synthesised from the
+    transition's action index and reward so the schema is always valid.
+    """
+    exporter.begin_episode(
+        agent_seat=episode.agent_seat,
+        playstyle=episode.playstyle,
+    )
+
+    for t in episode.transitions:
+        if t.snapshot is not None:
+            game_state = _make_minimal_state(t.snapshot)
+            # Carry through turn/phase/active_seat if present
+            game_state["turn"] = t.snapshot.get("turn", 1)
+            game_state["phase"] = t.snapshot.get("phase", "main_1")
+            game_state["active_seat"] = t.snapshot.get("active_seat", episode.agent_seat)
+        else:
+            # Minimal fallback — exporter only needs players list for schema
+            game_state = {
+                "turn": 1,
+                "phase": "main_1",
+                "active_seat": episode.agent_seat,
+                "players": [
+                    {"life_total": 40, "cards_in_hand": 0, "creatures_on_battlefield": 0,
+                     "cards_in_graveyard": 0, "mana_available": 0,
+                     "commander_damage_taken": 0, "total_power_on_board": 0, "commander_tax": 0},
+                    {"life_total": 40, "cards_in_hand": 0, "creatures_on_battlefield": 0,
+                     "cards_in_graveyard": 0, "mana_available": 0,
+                     "commander_damage_taken": 0, "total_power_on_board": 0, "commander_tax": 0},
+                ],
+            }
+
+        exporter.record_step(
+            game_state_snapshot=game_state,
+            action_idx=t.action,
+            reward=t.reward,
+        )
+
+    exporter.end_episode(
+        won=episode.won,
+        episode_return=episode.total_reward,
+    )
+
+
 # ══════════════════════════════════════════════════════════
 # Async Episode Queue (producer-consumer)
 # ══════════════════════════════════════════════════════════
@@ -271,6 +379,7 @@ async def ppo_consumer(
    queue: ForgeEpisodeQueue,
    buffer_size: int = 64,
    on_batch_ready=None,
+    exporter: Optional[DecisionExporter] = None,
 ) -> int:
    """Consumer coroutine: pulls episodes from the queue and batches
    them for PPO training updates.
@@ -279,6 +388,11 @@ async def ppo_consumer(
        queue: ForgeEpisodeQueue to consume from
        buffer_size: number of episodes per training batch
        on_batch_ready: callback(episodes) when a batch is full
+        exporter: Optional DecisionExporter — when provided, every
+                  consumed episode is fed into the exporter so winning
+                  Forge games accumulate in the distillation JSONL pool.
+                  Call exporter.flush() after the pipeline completes to
+                  write the JSONL file.

    Returns total episodes consumed.
    """
@@ -292,6 +406,14 @@ async def ppo_consumer(
                break
            continue

+        # Feed into distillation exporter (win-gate applied inside exporter)
+        if exporter is not None:
+            try:
+                _export_forge_episode(episode, exporter)
+            except Exception as exc:
+                logger.warning("[CONSUMER] Exporter error for episode %s: %s",
+                               episode.game_id, exc)
+
        batch.append(episode)
        total_consumed += 1

@@ -322,12 +444,24 @@ async def run_forge_pipeline(
    max_queue: int = 256,
    on_batch_ready=None,
    reward_config: Optional[RewardConfig] = None,
-) -> Dict[str, int]:
+    exporter: Optional[DecisionExporter] = None,
+) -> Dict[str, Any]:
    """Run the full Forge producer → PPO consumer pipeline.

    The Forge Java batch must be started separately (via forge_runner.py
    or MultiThreadBatchRunner). This function handles the Python side:
    reading JSONL output and feeding episodes into the PPO trainer.
+
+    If an exporter is provided, winning Forge episodes are recorded and
+    flushed to a PPO JSONL file at the end of the pipeline run.  The
+    output path is returned in the stats dict under "exporter_file".
+
+    Example::
+
+        from ml.training.decision_exporter import DecisionExporter, ExporterConfig
+        exporter = DecisionExporter(ExporterConfig(model_version="gen-1"))
+        stats = await run_forge_pipeline(num_games=128, exporter=exporter)
+        print(stats["exporter_file"])   # data/results/ml-decisions-ppo-<id>.jsonl
    """
    queue = ForgeEpisodeQueue(max_size=max_queue)

@@ -336,16 +470,25 @@ async def run_forge_pipeline(
                       reward_config=reward_config)
    )
    consumer_task = asyncio.create_task(
-        ppo_consumer(queue, buffer_size, on_batch_ready)
+        ppo_consumer(queue, buffer_size, on_batch_ready, exporter=exporter)
    )

    produced = await producer_task
    queue.close()
    consumed = await consumer_task

-    stats = {
+    # Flush exporter to disk and capture output path
+    exporter_file = None
+    if exporter is not None:
+        exporter_file = exporter.flush()
+        if exporter_file:
+            logger.info("[PIPELINE] Distillation export: %s  stats=%s",
+                        exporter_file, exporter.stats)
+
+    stats: Dict[str, Any] = {
        "produced": produced,
        "consumed": consumed,
+        "exporter_file": exporter_file,
        **queue.stats,
    }
    logger.info("[PIPELINE] Complete: %s", stats)
@@ -1,131 +1,154 @@
-"""Runtime configuration, state classes, and static data for Commander AI Lab."""
-from __future__ import annotations
-import json
-import logging
-import os
-import subprocess
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-
-
-log = logging.getLogger("commander_ai_lab.api")
-
-
-# ══════════════════════════════════════════════════════════════
-# Configuration
-# ══════════════════════════════════════════════════════════════
-class Config:
-    """Runtime configuration -- set via CLI args or env vars."""
-    forge_jar: str = ""
-    forge_dir: str = ""
-    forge_decks_dir: str = ""
-    lab_jar: str = ""
-    precon_dir: str = ""
-    results_dir: str = "results"
-    port: int = 8080
-    ximilar_api_key: str = ""
-    pplx_api_key: str = ""
-    anthropic_api_key: str = ""
-
-
-CFG = Config()
-# Pre-populate from env so ASGI mode (uvicorn lab_api:app) works without main()
-CFG.anthropic_api_key = os.environ.get("ANTHROPIC_API_KEY", "")
-
-
-def validate_forge_config() -> None:
-    """Warn clearly at startup if FORGE_DIR is misconfigured."""
-    if not CFG.forge_dir:
-        log.warning("FORGE_DIR not set -- Forge card enrichment disabled. "
-                    "Set FORGE_DIR to your forge-repo root or forge-gui directory.")
-        return
-    base = Path(CFG.forge_dir)
-    a = base / "forge-gui" / "res" / "cardsfolder"
-    b = base / "res" / "cardsfolder"
-    if not a.is_dir() and not b.is_dir():
-        log.warning(
-            "FORGE_DIR=%s is set but cardsfolder not found at:\n"
-            "  %s\n  %s\n"
-            "Check that FORGE_DIR points to forge-repo root or forge-gui/.",
-            CFG.forge_dir, a, b
-        )
-    else:
-        resolved = a if a.is_dir() else b
-        log.info("Forge cardsfolder confirmed at %s", resolved)
-CFG.ximilar_api_key = os.environ.get("XIMILAR_API_KEY", "")
-CFG.pplx_api_key = os.environ.get("PPLX_API_KEY", "")
-
-
-# ══════════════════════════════════════════════════════════════
-# In-Memory State
-# ══════════════════════════════════════════════════════════════
-class BatchState:
-    def __init__(self, batch_id: str, total_games: int, threads: int):
-        self.batch_id = batch_id
-        self.total_games = total_games
-        self.threads = threads
-        self.completed_games = 0
-        self.running = True
-        self.start_time = datetime.now()
-        self.elapsed_ms = 0
-        self.result_path: Optional[str] = None
-        self.error: Optional[str] = None
-        self.process: Optional[subprocess.Popen] = None
-        self.log_lines: list = []
-        self.sims_per_sec: float = 0.0
-
-
-import asyncio as _asyncio
-active_batches: dict[str, BatchState] = {}
-active_batches_lock = _asyncio.Lock()
-
-
-COMMANDER_META: dict = {}
-
-BUILTIN_COMMANDERS: dict = {
-    "Edgar Markov": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["W","B","R"]}],
-    "Atraxa, Praetors' Voice": [{"source": "edhrec", "archetype": "midrange", "colorIdentity": ["W","U","B","G"]}],
-    "Korvold, Fae-Cursed King": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["B","R","G"]}],
-    "Muldrotha, the Gravetide": [{"source": "edhrec", "archetype": "midrange", "colorIdentity": ["U","B","G"]}],
-    "The Ur-Dragon": [{"source": "edhrec", "archetype": "midrange", "colorIdentity": ["W","U","B","R","G"]}],
-    "Yuriko, the Tiger's Shadow": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["U","B"]}],
-    "Krenko, Mob Boss": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["R"]}],
-    "Meren of Clan Nel Toth": [{"source": "edhrec", "archetype": "midrange", "colorIdentity": ["B","G"]}],
-    "Prossh, Skyraider of Kher": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["B","R","G"]}],
-    "Kaalia of the Vast": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["W","B","R"]}],
-    "Talrand, Sky Summoner": [{"source": "edhrec", "archetype": "control", "colorIdentity": ["U"]}],
-    "Omnath, Locus of Creation": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["W","U","R","G"]}],
-    "Teysa Karlov": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["W","B"]}],
-    "Lathril, Blade of the Elves": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["B","G"]}],
-    "Breya, Etherium Shaper": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["W","U","B","R"]}],
-}
-
-
-def load_commander_meta() -> None:
-    """Load commander meta mapping from file or fall back to builtins."""
-    meta_path = Path(__file__).parent.parent / "commander-meta.json"
-    if meta_path.exists():
-        try:
-            with open(meta_path, "r", encoding="utf-8") as f:
-                COMMANDER_META.clear()
-                COMMANDER_META.update(json.load(f))
-            log.info(f" Meta: Loaded {len(COMMANDER_META)} commanders from {meta_path}")
-            return
-        except Exception as e:
-            log.warning(f" WARNING: Failed to load commander-meta.json: {e}")
-    COMMANDER_META.clear()
-    COMMANDER_META.update(BUILTIN_COMMANDERS)
-    log.info(f" Meta:    {len(COMMANDER_META)} built-in commanders")
-
-
-# ══════════════════════════════════════════════════════════════
-# AI Profiles
-# ══════════════════════════════════════════════════════════════
-AI_PROFILES = {
-    "default": {"name": "default", "description": "Balanced \u2014 Forge's default AI behavior", "aggression": 0.5, "cardAdvantage": 0.5, "removalPriority": 0.5, "boardPresence": 0.5, "comboPriority": 0.3, "patience": 0.5},
-    "aggro": {"name": "aggro", "description": "Aggressive \u2014 attacks early, prioritizes damage", "aggression": 0.9, "cardAdvantage": 0.3, "removalPriority": 0.3, "boardPresence": 0.8, "comboPriority": 0.1, "patience": 0.1},
-    "control": {"name": "control", "description": "Control \u2014 defensive, removal-heavy, card advantage", "aggression": 0.2, "cardAdvantage": 0.9, "removalPriority": 0.9, "boardPresence": 0.3, "comboPriority": 0.4, "patience": 0.9},
-    "combo": {"name": "combo", "description": "Combo \u2014 ramps, digs for pieces, assembles combos", "aggression": 0.2, "cardAdvantage": 0.8, "removalPriority": 0.4, "boardPresence": 0.3, "comboPriority": 0.95, "patience": 0.7},
-    "midrange": {"name": "midrange", "description": "Midrange \u2014 flexible, strong board presence, value-oriented", "aggression": 0.5, "cardAdvantage": 0.6, "removalPriority": 0.6, "boardPresence": 0.7, "comboPriority": 0.3, "patience": 0.5},
-}
+"""Runtime configuration, state classes, and static data for Commander AI Lab."""
+from __future__ import annotations
+import json
+import logging
+import os
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+# ── .env bootstrap ────────────────────────────────────────────
+# Load .env automatically so plain `python script.py` and bare uvicorn
+# both pick up FORGE_DIR, PRECON_DIR, etc. without a manual load_dotenv
+# call at every entry point. override=False means real env vars always win.
+try:
+    from dotenv import load_dotenv as _load_dotenv
+    _here = Path(__file__).resolve().parent
+    for _candidate in [_here, _here.parent, _here.parent.parent]:
+        _env_file = _candidate / ".env"
+        if _env_file.is_file():
+            _load_dotenv(dotenv_path=_env_file, override=False)
+            break
+except ImportError:
+    pass  # python-dotenv not installed; rely on real environment variables
+# ─────────────────────────────────────────────────────────────
+
+log = logging.getLogger("commander_ai_lab.api")
+
+
+# ══════════════════════════════════════════════════════════════
+# Configuration
+# ══════════════════════════════════════════════════════════════
+class Config:
+    """Runtime configuration -- set via CLI args or env vars."""
+    forge_jar: str = ""
+    forge_dir: str = ""
+    forge_decks_dir: str = ""
+    lab_jar: str = ""
+    precon_dir: str = ""
+    results_dir: str = "results"
+    port: int = 8080
+    ximilar_api_key: str = ""
+    pplx_api_key: str = ""
+    anthropic_api_key: str = ""
+
+
+CFG = Config()
+
+# Pre-populate from environment so uvicorn/ASGI mode works without CLI args.
+# CLI args (lab_api.py main()) will override these if provided.
+CFG.anthropic_api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+CFG.ximilar_api_key   = os.environ.get("XIMILAR_API_KEY", "")
+CFG.pplx_api_key      = os.environ.get("PPLX_API_KEY", "")
+CFG.forge_jar         = os.environ.get("FORGE_JAR", "")
+CFG.forge_dir         = os.environ.get("FORGE_DIR", "")
+CFG.lab_jar           = os.environ.get("LAB_JAR", "")
+# PRECON_DIR / PRECON_DECKS_DIR are aliases -- prefer PRECON_DIR
+CFG.precon_dir        = os.environ.get("PRECON_DIR") or os.environ.get("PRECON_DECKS_DIR", "")
+CFG.forge_decks_dir   = os.environ.get("FORGE_DECKS_DIR", "")
+
+
+def validate_forge_config() -> None:
+    """Warn clearly at startup if FORGE_DIR is misconfigured."""
+    if not CFG.forge_dir:
+        log.warning("FORGE_DIR not set -- Forge card enrichment disabled. "
+                    "Set FORGE_DIR to your forge-repo root or forge-gui directory.")
+        return
+    base = Path(CFG.forge_dir)
+    a = base / "forge-gui" / "res" / "cardsfolder"
+    b = base / "res" / "cardsfolder"
+    if not a.is_dir() and not b.is_dir():
+        log.warning(
+            "FORGE_DIR=%s is set but cardsfolder not found at:\n"
+            "  %s\n  %s\n"
+            "Check that FORGE_DIR points to forge-repo root or forge-gui/.",
+            CFG.forge_dir, a, b
+        )
+    else:
+        resolved = a if a.is_dir() else b
+        log.info("Forge cardsfolder confirmed at %s", resolved)
+
+
+# ══════════════════════════════════════════════════════════════
+# In-Memory State
+# ══════════════════════════════════════════════════════════════
+class BatchState:
+    def __init__(self, batch_id: str, total_games: int, threads: int):
+        self.batch_id = batch_id
+        self.total_games = total_games
+        self.threads = threads
+        self.completed_games = 0
+        self.running = True
+        self.start_time = datetime.now()
+        self.elapsed_ms = 0
+        self.result_path: Optional[str] = None
+        self.error: Optional[str] = None
+        self.process: Optional[subprocess.Popen] = None
+        self.log_lines: list = []
+        self.sims_per_sec: float = 0.0
+
+
+import asyncio as _asyncio
+active_batches: dict[str, BatchState] = {}
+active_batches_lock = _asyncio.Lock()
+
+
+COMMANDER_META: dict = {}
+
+BUILTIN_COMMANDERS: dict = {
+    "Edgar Markov": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["W","B","R"]}],
+    "Atraxa, Praetors' Voice": [{"source": "edhrec", "archetype": "midrange", "colorIdentity": ["W","U","B","G"]}],
+    "Korvold, Fae-Cursed King": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["B","R","G"]}],
+    "Muldrotha, the Gravetide": [{"source": "edhrec", "archetype": "midrange", "colorIdentity": ["U","B","G"]}],
+    "The Ur-Dragon": [{"source": "edhrec", "archetype": "midrange", "colorIdentity": ["W","U","B","R","G"]}],
+    "Yuriko, the Tiger's Shadow": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["U","B"]}],
+    "Krenko, Mob Boss": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["R"]}],
+    "Meren of Clan Nel Toth": [{"source": "edhrec", "archetype": "midrange", "colorIdentity": ["B","G"]}],
+    "Prossh, Skyraider of Kher": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["B","R","G"]}],
+    "Kaalia of the Vast": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["W","B","R"]}],
+    "Talrand, Sky Summoner": [{"source": "edhrec", "archetype": "control", "colorIdentity": ["U"]}],
+    "Omnath, Locus of Creation": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["W","U","R","G"]}],
+    "Teysa Karlov": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["W","B"]}],
+    "Lathril, Blade of the Elves": [{"source": "edhrec", "archetype": "aggro", "colorIdentity": ["B","G"]}],
+    "Breya, Etherium Shaper": [{"source": "edhrec", "archetype": "combo", "colorIdentity": ["W","U","B","R"]}],
+}
+
+
+def load_commander_meta() -> None:
+    """Load commander meta mapping from file or fall back to builtins."""
+    meta_path = Path(__file__).parent.parent / "commander-meta.json"
+    if meta_path.exists():
+        try:
+            with open(meta_path, "r", encoding="utf-8") as f:
+                COMMANDER_META.clear()
+                COMMANDER_META.update(json.load(f))
+            log.info(f" Meta: Loaded {len(COMMANDER_META)} commanders from {meta_path}")
+            return
+        except Exception as e:
+            log.warning(f" WARNING: Failed to load commander-meta.json: {e}")
+    COMMANDER_META.clear()
+    COMMANDER_META.update(BUILTIN_COMMANDERS)
+    log.info(f" Meta:    {len(COMMANDER_META)} built-in commanders")
+
+
+# ══════════════════════════════════════════════════════════════
+# AI Profiles
+# ══════════════════════════════════════════════════════════════
+AI_PROFILES = {
+    "default": {"name": "default", "description": "Balanced — Forge's default AI behavior", "aggression": 0.5, "cardAdvantage": 0.5, "removalPriority": 0.5, "boardPresence": 0.5, "comboPriority": 0.3, "patience": 0.5},
+    "aggro": {"name": "aggro", "description": "Aggressive — attacks early, prioritizes damage", "aggression": 0.9, "cardAdvantage": 0.3, "removalPriority": 0.3, "boardPresence": 0.8, "comboPriority": 0.1, "patience": 0.1},
+    "control": {"name": "control", "description": "Control — defensive, removal-heavy, card advantage", "aggression": 0.2, "cardAdvantage": 0.9, "removalPriority": 0.9, "boardPresence": 0.3, "comboPriority": 0.4, "patience": 0.9},
+    "combo": {"name": "combo", "description": "Combo — ramps, digs for pieces, assembles combos", "aggression": 0.2, "cardAdvantage": 0.8, "removalPriority": 0.4, "boardPresence": 0.3, "comboPriority": 0.95, "patience": 0.7},
+    "midrange": {"name": "midrange", "description": "Midrange — flexible, strong board presence, value-oriented", "aggression": 0.5, "cardAdvantage": 0.6, "removalPriority": 0.6, "boardPresence": 0.7, "comboPriority": 0.3, "patience": 0.5},
+}
@@ -1,11 +1,29 @@
 """Live game session routes.

 Endpoints:
-  POST /api/game/start   — create a new live game session (called by LobbySetupModal)
-  POST /api/game/action  — submit a human player action   (called by HumanActionBar)
+  POST /api/game/start   -- create and launch a live Forge game session
+  POST /api/game/action  -- submit a human player action  (called by HumanActionBar)
+  GET  /api/game/{game_id}/status   -- poll session status and last known game state
+  GET  /api/game/{game_id}/actions  -- Forge IPC: drain pending human actions
+  GET  /api/game/sessions           -- list active sessions (debug)
+
+Forge IPC flow
+--------------
+  1. POST /api/game/start
+       - Validates seats, resolves deck names
+       - Picks a playstyle per AI seat from seat_type (e.g. "AI Aggro" -> "aggro")
+       - Calls run_batch_subprocess(num_games=1, use_learned_policy=True, ...)
+         which builds the Java command with --policy <style> --policyServer http://localhost:8080
+         and spawns the Forge JAR in a background thread
+       - Returns game_id + ws_url immediately (non-blocking)
+  2. Forge JAR (once launched) calls POST /api/policy/decide on every AI decision
+  3. Human actions are queued via POST /api/game/action and drained by
+     GET /api/game/{game_id}/actions (polled by the Forge IPC loop inside the JAR)
+  4. GET /api/game/{game_id}/status returns live log tail + completion state
 """
 from __future__ import annotations

+import asyncio
 import logging
 import uuid
 from typing import List, Optional
@@ -13,14 +31,39 @@ from typing import List, Optional
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field

+from models.state import BatchState
+from services.forge_runner import run_batch_subprocess
+
 log = logging.getLogger("routes.game")

 router = APIRouter(tags=["game"])

+# ---------------------------------------------------------------------------
+# Playstyle mapping:  seat_type string -> policy playstyle token
+# ---------------------------------------------------------------------------

-# ───────────────────────────────────────────────────────────────
+_PLAYSTYLE_MAP: dict[str, str] = {
+    "ai aggro":     "aggro",
+    "ai control":   "control",
+    "ai combo":     "combo",
+    "ai political": "political",
+    "ai midrange":  "midrange",
+    "ai":           "midrange",   # bare "AI" seat -> midrange default
+    "human":        None,         # human seats skipped for policy
+}
+
+
+def _seat_playstyle(seat_type: str) -> Optional[str]:
+    """Map a SeatConfig.seat_type string to a policy playstyle token.
+
+    Returns None for human seats (no policy needed).
+    """
+    return _PLAYSTYLE_MAP.get(seat_type.lower().strip(), "midrange")
+
+
+# ---------------------------------------------------------------------------
 # Request / Response models
-# ───────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------

 class SeatConfig(BaseModel):
    seat_index: int = 0
@@ -31,12 +74,16 @@ class SeatConfig(BaseModel):

 class StartGameRequest(BaseModel):
    seats: List[SeatConfig] = Field(default_factory=list)
+    clock: int = Field(default=6000, description="Per-game wall-clock limit in seconds (0 = unlimited)")
+    use_learned_policy: bool = Field(default=True, description="Route AI decisions through /api/policy/decide")
+    policy_greedy: bool = Field(default=False, description="Use greedy (argmax) action selection instead of sampling")


 class StartGameResponse(BaseModel):
    game_id: str
    status: str = "started"
    ws_url: str
+    policy_enabled: bool = False


 class GameActionRequest(BaseModel):
@@ -54,73 +101,139 @@ class GameActionResponse(BaseModel):
    action: str


-# ───────────────────────────────────────────────────────────────
-# In-memory session store  (replace with DB / Redis for persistence)
-# ───────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------
+# In-memory session store
+# ---------------------------------------------------------------------------

-# { game_id: { "seats": [...], "status": "active" | "ended", "pending_actions": [...] } }
+# { game_id: { "seats": [...], "status": "active"|"ended"|"error",
+#              "batch_state": BatchState|None, "pending_actions": [...] } }
 _sessions: dict[str, dict] = {}


-# ───────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------
 # POST /api/game/start
-# ───────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------

@router.post("/api/game/start", response_model=StartGameResponse)
 async def start_game(req: StartGameRequest):
-    """Create a new live game session.
+    """Create and launch a live Forge game session.

-    Called by Unity's LobbySetupModal after the player configures seats.
-    Returns a game_id that Unity uses to connect to the WebSocket at
-    /ws/game/{game_id}.
+    Resolves deck names from the seat config, launches the Forge JAR
+    as a background subprocess with --policy routing enabled (unless
+    use_learned_policy=False), and returns a game_id immediately.

-    TODO: Wire Forge engine launch here once the IPC layer is ready.
-    For now, creates a session record and returns the game_id so Unity
-    can connect and receive state pushes from the Forge IPC client.
+    The Forge JAR will begin calling POST /api/policy/decide for every
+    AI seat decision as soon as it is up. Human actions are queued via
+    POST /api/game/action and polled by the JAR via GET /api/game/{id}/actions.
    """
    if not req.seats:
        raise HTTPException(status_code=400, detail="At least one seat is required.")

+    # Collect deck names from seats that have one, preserving seat order.
+    decks = [s.deck_name for s in req.seats if s.deck_name.strip()]
+    if not decks:
+        raise HTTPException(status_code=400, detail="At least one seat must have a deck_name.")
+
+    # Determine playstyle from the first AI seat (the JAR uses a single global
+    # playstyle for its --policy flag; per-seat styles are a future extension).
+    policy_style = "midrange"
+    for seat in req.seats:
+        ps = _seat_playstyle(seat.seat_type)
+        if ps is not None:           # skip human seats
+            policy_style = ps
+            break
+
    game_id = uuid.uuid4().hex

+    # Build a BatchState so the forge_runner watchdog and progress tracking
+    # work the same way they do for overnight batch runs.
+    state = BatchState(batch_id=game_id)
+
    _sessions[game_id] = {
-        "game_id": game_id,
-        "seats": [s.dict() for s in req.seats],
-        "status": "active",
+        "game_id":         game_id,
+        "seats":           [s.dict() for s in req.seats],
+        "status":          "active",
        "pending_actions": [],
+        "batch_state":     state,
    }

    log.info(
-        "Game session created: game_id=%s seats=%d",
-        game_id,
-        len(req.seats),
+        "Game session created: game_id=%s seats=%d decks=%s policy=%s greedy=%s",
+        game_id, len(req.seats), decks, policy_style if req.use_learned_policy else "off",
+        req.policy_greedy,
+    )
+
+    # Launch Forge subprocess in the background (non-blocking).
+    # num_games=1 -> single live game, threads=1, no seed.
+    # clock is passed through from the request (default 6000s for live play).
+    asyncio.create_task(
+        _run_and_finalize(
+            game_id=game_id,
+            state=state,
+            decks=decks,
+            clock=req.clock,
+            use_learned_policy=req.use_learned_policy,
+            policy_style=policy_style,
+            policy_greedy=req.policy_greedy,
+        )
    )

    return StartGameResponse(
        game_id=game_id,
        status="started",
        ws_url=f"/ws/game/{game_id}",
+        policy_enabled=req.use_learned_policy,
    )


-# ───────────────────────────────────────────────────────────────
+async def _run_and_finalize(
+    game_id: str,
+    state: BatchState,
+    decks: list,
+    clock: int,
+    use_learned_policy: bool,
+    policy_style: str,
+    policy_greedy: bool,
+):
+    """Background task: run Forge subprocess then mark session ended."""
+    try:
+        await run_batch_subprocess(
+            state=state,
+            decks=decks,
+            num_games=1,
+            threads=1,
+            seed=None,
+            clock=clock,
+            output_path=f"results/live-{game_id}.json",
+            use_learned_policy=use_learned_policy,
+            policy_style=policy_style,
+            policy_greedy=policy_greedy,
+        )
+    except Exception as exc:
+        log.error("Game %s subprocess error: %s", game_id, exc)
+        if game_id in _sessions:
+            _sessions[game_id]["status"] = "error"
+        return
+
+    if game_id in _sessions:
+        _sessions[game_id]["status"] = "ended" if not state.error else "error"
+        log.info(
+            "Game %s finished: status=%s error=%s",
+            game_id, _sessions[game_id]["status"], state.error or "none",
+        )
+
+
+# ---------------------------------------------------------------------------
 # POST /api/game/action
-# ───────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------

@router.post("/api/game/action", response_model=GameActionResponse)
 async def game_action(req: GameActionRequest):
    """Submit a human player action during a live game.

-    Called by Unity's HumanActionBar when seat 0 (human) has priority.
-    The action is queued in the session's pending_actions list, where
-    the Forge IPC polling loop will pick it up.
-
-    Valid actions:
-      pass_priority     — pass priority to the next player
-      end_turn          — end the current turn
-      declare_attackers — declare attacking creatures
-      declare_blockers  — declare blocking creatures
-      select_target     — select a target (requires target_id)
+    Called by Unity's HumanActionBar when the human seat has priority.
+    The action is queued in the session; the Forge IPC polling loop
+    drains it via GET /api/game/{game_id}/actions.
    """
    valid_actions = {
        "pass_priority", "end_turn",
@@ -142,47 +255,73 @@ async def game_action(req: GameActionRequest):

    session = _sessions.get(req.game_id)
    if session is None:
-        raise HTTPException(
-            status_code=404,
-            detail=f"Game session '{req.game_id}' not found.",
-        )
+        raise HTTPException(status_code=404, detail=f"Game session '{req.game_id}' not found.")

    if session["status"] != "active":
        raise HTTPException(
            status_code=409,
-            detail=f"Game session '{req.game_id}' is not active (status={session['status']}).",
+            detail=f"Game '{req.game_id}' is not active (status={session['status']}).",
        )

-    action_record = {
-        "seat": req.seat,
-        "action": req.action,
+    session["pending_actions"].append({
+        "seat":      req.seat,
+        "action":    req.action,
        "target_id": req.target_id,
-        "extra": req.extra,
+        "extra":     req.extra,
+    })
+
+    log.info("Action queued: game_id=%s seat=%d action=%s", req.game_id, req.seat, req.action)
+
+    return GameActionResponse(status="ok", game_id=req.game_id, action=req.action)
+
+
+# ---------------------------------------------------------------------------
+# GET /api/game/{game_id}/status
+# ---------------------------------------------------------------------------
+
+@router.get("/api/game/{game_id}/status")
+async def game_status(game_id: str):
+    """Return live status, log tail, and completion info for a game session.
+
+    Useful for polling from the frontend or a test script to track
+    whether Forge has finished launching and started calling /decide.
+    """
+    session = _sessions.get(game_id)
+    if session is None:
+        raise HTTPException(status_code=404, detail=f"Game session '{game_id}' not found.")
+
+    state: Optional[BatchState] = session.get("batch_state")
+    log_tail = []
+    completed = 0
+    total = 1
+    error = None
+
+    if state:
+        log_tail  = state.log_lines[-20:]   # last 20 lines
+        completed = state.completed_games
+        total     = max(state.total_games, 1)
+        error     = state.error
+
+    return {
+        "game_id":   game_id,
+        "status":    session["status"],
+        "seats":     session["seats"],
+        "progress":  {"completed": completed, "total": total},
+        "log_tail":  log_tail,
+        "error":     error,
+        "pending_actions": len(session["pending_actions"]),
    }
-    session["pending_actions"].append(action_record)
-
-    log.info(
-        "Action queued: game_id=%s seat=%d action=%s",
-        req.game_id, req.seat, req.action,
-    )
-
-    return GameActionResponse(
-        status="ok",
-        game_id=req.game_id,
-        action=req.action,
-    )


-# ───────────────────────────────────────────────────────────────
-# GET /api/game/{game_id}/actions  (Forge IPC polling endpoint)
-# ───────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------
+# GET /api/game/{game_id}/actions  (Forge IPC polling)
+# ---------------------------------------------------------------------------

@router.get("/api/game/{game_id}/actions")
 async def poll_actions(game_id: str):
-    """Drain and return all pending human actions for a game session.
+    """Drain and return all pending human actions (consume-once).

    Called by the Forge IPC polling loop to consume human player decisions.
-    Clears the queue on each call (consume-once semantics).
    """
    session = _sessions.get(game_id)
    if session is None:
@@ -193,17 +332,22 @@ async def poll_actions(game_id: str):
    return {"game_id": game_id, "actions": actions}


-# ───────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------
 # GET /api/game/sessions  (debug)
-# ───────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------

@router.get("/api/game/sessions")
 async def list_sessions():
-    """List active game sessions (debug endpoint)."""
+    """List all tracked game sessions (debug)."""
    return {
        "count": len(_sessions),
        "sessions": [
-            {"game_id": gid, "status": s["status"], "seats": len(s["seats"])}
+            {
+                "game_id": gid,
+                "status":  s["status"],
+                "seats":   len(s["seats"]),
+                "pending": len(s["pending_actions"]),
+            }
            for gid, s in _sessions.items()
        ],
    }
@@ -14,6 +14,8 @@ Batch simulation & lab management endpoints:
  GET  /api/lab/trends/{deck_name}
  GET  /api/lab/log
  GET  /api/lab/debug-log
+  GET  /api/lab/precons
+  GET  /api/lab/precons/deck
 """
 from __future__ import annotations

@@ -468,6 +470,73 @@ async def get_debug_log():
    return {"path": None, "content": "No debug log found. Run a simulation first."}


+# ════════════════════════════════════════════════════════════
+# Precon deck endpoints (used by lan-client ai-bridge.js)
+# ════════════════════════════════════════════════════════════
+
+@router.get("/api/lab/precons")
+async def list_precons():
+    """Return precon deck metadata for the LAN client deck selector."""
+    precon_dir = Path(CFG.precon_dir) if CFG.precon_dir else None
+    if not precon_dir or not precon_dir.is_dir():
+        log.warning(f"Precon dir not found or not configured: {CFG.precon_dir!r}")
+        return {"precons": []}
+
+    precons = []
+    for f in sorted(precon_dir.glob("*.dck")):
+        deck_info = {
+            "fileName": f.name,
+            "deckName": f.stem,
+            "commander": "",
+            "colors": [],
+            "set": "",
+        }
+        # Extract commander name from the [Commander] section
+        try:
+            with open(f, "r", encoding="utf-8") as fh:
+                in_commander = False
+                for line in fh:
+                    line = line.strip()
+                    if line == "[Commander]":
+                        in_commander = True
+                        continue
+                    if line.startswith("[") and line.endswith("]"):
+                        in_commander = False
+                        continue
+                    if in_commander:
+                        m = re.match(r"^\d+\s+(.+?)(?:\|.+)?$", line)
+                        if m:
+                            deck_info["commander"] = m.group(1).strip()
+                            break
+        except Exception as exc:
+            log.debug(f"Could not parse commander from {f.name}: {exc}")
+        precons.append(deck_info)
+
+    return {"precons": precons}
+
+
+@router.get("/api/lab/precons/deck")
+async def get_precon_deck(fileName: str):
+    """Return the full card list for a specific precon .dck file."""
+    precon_dir = Path(CFG.precon_dir) if CFG.precon_dir else None
+    if not precon_dir or not precon_dir.is_dir():
+        raise HTTPException(404, f"Precon directory not configured or missing: {CFG.precon_dir!r}")
+
+    # Sanitize — prevent path traversal
+    safe_name = Path(fileName).name
+    if not safe_name.endswith(".dck"):
+        raise HTTPException(400, "fileName must end with .dck")
+    deck_path = precon_dir / safe_name
+
+    if not deck_path.exists():
+        raise HTTPException(404, f"Precon deck not found: {safe_name}")
+
+    try:
+        deck_data = parse_dck_file(str(deck_path))
+        return deck_data
+    except Exception as e:
+        raise HTTPException(500, f"Failed to parse deck: {e}")
+

@router.post('/api/lab/start-deepseek')
 async def start_batch_deepseek(request: FastAPIRequest, background_tasks: BackgroundTasks):
@@ -1,5 +1,5 @@
 """Commander AI Lab — Policy Decision Routes (Phase 2)
-════════════════════════════════════════════════════
+════════════════════════════════════════════════════════
 Live Forge ↔ policy server IPC endpoints for online training.
 These endpoints are purpose-built for the real-time decision loop
 where Forge's Java side calls the Python policy server at each
@@ -24,7 +24,8 @@ import numpy as np
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field

-logger = logging.getLogger("routes.policy")
+# Unique logger name so log lines are attributable to this module specifically
+logger = logging.getLogger("routes.policy.decide")

 router = APIRouter(prefix="/api/policy", tags=["policy"])

@@ -310,7 +311,10 @@ async def decide(req: DecideRequest):
                req.snapshot_schema, req.resolved_turn(),
            )
        except Exception as e:
-            logger.warning("Precomputed vector encode failed (%s) — falling back", e)
+            logger.warning(
+                "Precomputed vector encode failed — falling back to full encoder",
+                exc_info=True,
+            )
            state_vec = None
    else:
        state_vec = None
@@ -338,6 +342,24 @@ async def decide(req: DecideRequest):
    if "error" in result:
        raise HTTPException(500, detail=result["error"])

+    # ----------------------------------------------------------------
+    # Probability diagnostic — logs top-5 actions on every decision.
+    # Remove or downgrade to logger.debug once training looks healthy.
+    # ----------------------------------------------------------------
+    probs = result.get("probabilities", {})
+    if probs:
+        top5 = sorted(probs.items(), key=lambda kv: kv[1], reverse=True)[:5]
+        top5_str = ", ".join(f"{a}:{p:.3f}" for a, p in top5)
+        logger.info(
+            "[decide] turn=%d phase=%s → %s (conf=%.3f) | top5=[%s] | src=%s",
+            req.resolved_turn(),
+            req.phase,
+            result["action"],
+            result["confidence"],
+            top5_str,
+            vector_source,
+        )
+
    log_prob = 0.0
    try:
        conf = result.get("confidence", 0.5)
@@ -373,7 +395,7 @@ async def collect_tuples(req: CollectRequest):
        try:
            _online_store.add_tuples(req.tuples)
        except Exception as e:
-            logger.error("Failed to store tuples: %s", e)
+            logger.error("Failed to store tuples: %s", e, exc_info=True)
            raise HTTPException(500, detail=str(e))

    return {
@@ -402,7 +424,7 @@ async def submit_reward(req: RewardRequest):
                winner_seat=req.winner_seat,
            )
        except Exception as e:
-            logger.error("Failed to assign reward: %s", e)
+            logger.error("Failed to assign reward: %s", e, exc_info=True)
            raise HTTPException(500, detail=str(e))

    return {
@@ -518,16 +540,24 @@ def _infer_from_vector(state_vec: np.ndarray, policy_service, temperature: float

    Mirrors the core of PolicyInferenceService.predict() but accepts an
    ndarray instead of a snapshot dict, avoiding a second encode() call.
+
+    Uses _unwrap_logits (same helper as predict()) to guard against
+    tuple/dict returns from wrapped or swapped model variants before any
+    arithmetic on the logits tensor.
    """
    import torch
    from ml.config.scope import NUM_ACTIONS, IDX_TO_ACTION
+    from ml.serving.policy_server import _unwrap_logits

    t_start = time.time()
    try:
        state_tensor = torch.from_numpy(state_vec).unsqueeze(0).to(policy_service.device)

        with torch.no_grad():
-            logits = policy_service.model(state_tensor)
+            raw_output = policy_service.model(state_tensor)
+            # Guard: unwrap tuple/dict returns (DataParallel, torch.compile,
+            # PolicyValueNetwork swap) before temperature division / argmax.
+            logits = _unwrap_logits(raw_output)

            if greedy:
                action_idx = logits.argmax(dim=-1).item()
@@ -555,7 +585,7 @@ def _infer_from_vector(state_vec: np.ndarray, policy_service, temperature: float
        }
    except Exception as e:
        elapsed_ms = (time.time() - t_start) * 1000
-        logger.error("Direct inference error: %s", e)
+        logger.error("Direct inference error in _infer_from_vector: %s", e, exc_info=True)
        return {"error": str(e), "inference_ms": round(elapsed_ms, 2)}


@@ -29,6 +29,31 @@ async def list_precons():
    return {"precons": PRECON_INDEX}        # reads current value every call


+@router.get("/api/lab/precons/deck")
+async def get_precon_deck(fileName: str):
+    """Return the raw decklist content of a precon .dck file.
+    Query: ?fileName=Elven_Empire.dck
+    """
+    if not fileName:
+        raise HTTPException(400, "fileName query parameter is required")
+    # Sanitize: only allow .dck files, no path traversal
+    if '..' in fileName or '/' in fileName or '\\' in fileName:
+        raise HTTPException(400, "Invalid fileName")
+    if not fileName.endswith('.dck'):
+        raise HTTPException(400, "Only .dck files are supported")
+
+    src = _get_precon_dir() / fileName
+    if not src.exists():
+        raise HTTPException(404, f"Precon not found: {fileName}")
+
+    try:
+        content = src.read_text(encoding='utf-8')
+    except OSError as e:
+        raise HTTPException(500, f"Failed to read deck file: {e}")
+
+    return {"fileName": fileName, "decklist": content}
+
+
@router.post("/api/lab/precons/install")
 async def install_precon(req: dict):
    """Install a precon deck to the Forge decks directory.
@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Generate lan-client/precons.js from precon-decks/precon-index.json
+ * Usage: node scripts/generate-precons-js.js
+ */
+const fs = require('fs');
+const path = require('path');
+
+const indexPath = path.join(__dirname, '..', 'precon-decks', 'precon-index.json');
+const outputPath = path.join(__dirname, '..', 'lan-client', 'precons.js');
+
+const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+
+let js = '// Auto-generated from precon-decks/precon-index.json\n';
+js += '// Run: node scripts/generate-precons-js.js to regenerate\n';
+js += 'var PRECON_DATA = [\n';
+
+index.forEach(function(p, i) {
+  const entry = {
+    id: (p.fileName || p.name || '').replace('.dck', ''),
+    name: p.name || '',
+    commander: p.commander || (p.commanders && p.commanders[0]) || '',
+    set: p.set || '',
+    fileName: p.fileName || '',
+    colors: p.colors || [],
+    year: p.year || 0,
+  };
+  js += '  ' + JSON.stringify(entry);
+  js += (i < index.length - 1) ? ',\n' : '\n';
+});
+
+js += '];\n';
+
+fs.writeFileSync(outputPath, js);
+console.log(`Generated ${outputPath} with ${index.length} precon entries`);
@@ -13,6 +13,16 @@ from services.database import _get_db_conn, _row_to_dict

 log_collect = logging.getLogger("lab.collection")

+# Repo root = two levels up from this file (services/deck_service.py)
+_REPO_ROOT = Path(__file__).parent.parent
+
+# Repo-relative deck dirs always searched as fallbacks (zero-config support)
+_BUILTIN_DECK_DIRS = [
+    _REPO_ROOT / "precon-decks",
+    _REPO_ROOT / "sample-decks",
+    _REPO_ROOT / "imported-decks",
+]
+

 _TYPE_PRIORITY = ["Land", "Instant", "Sorcery", "Artifact", "Enchantment", "Planeswalker", "Creature"]
 _TYPE_TARGETS = {
@@ -197,7 +207,7 @@ def _save_profile_to_dck(profile: dict) -> Path:
        safe_name = "imported_deck"
    save_dir = CFG.forge_decks_dir
    if not save_dir or not os.path.isdir(save_dir):
-        save_dir = os.path.join(Path(__file__).parent.parent, "imported-decks")
+        save_dir = str(_REPO_ROOT / "imported-decks")
        os.makedirs(save_dir, exist_ok=True)
    out_path = Path(save_dir) / f"{safe_name}.dck"
    out_path.write_text(content, encoding="utf-8")
@@ -209,15 +219,19 @@ def _find_dck_file(deck_name: str) -> Optional[Path]:
    """Search known deck directories for a .dck file matching deck_name.

    Resolution order:
-      1. precon_dir  (precon-decks/)
-      2. forge_decks_dir  (Forge user decks)
+      1. CFG.precon_dir  (explicit CLI/env config)
+      2. CFG.forge_decks_dir  (Forge user decks)
      3. FORGE_DIR/res/decks/commander  (Forge bundled commander decks)
+      4. Repo-relative fallbacks: precon-decks/, sample-decks/, imported-decks/
+         (always searched so precon decks work with zero configuration)

    Within each directory tries:
      a. Exact stem match  (Elven_Empire.dck)
      b. Case-insensitive fuzzy match stripping underscores/spaces
    """
-    search_dirs = []
+    search_dirs: list[Path] = []
+
+    # CFG-configured paths (set via CLI args)
    if CFG.precon_dir and os.path.isdir(CFG.precon_dir):
        search_dirs.append(Path(CFG.precon_dir))
    if CFG.forge_decks_dir and os.path.isdir(CFG.forge_decks_dir):
@@ -227,6 +241,11 @@ def _find_dck_file(deck_name: str) -> Optional[Path]:
        if forge_cmdr.is_dir():
            search_dirs.append(forge_cmdr)

+    # Repo-relative fallbacks -- always active so precon decks need no config
+    for builtin_dir in _BUILTIN_DECK_DIRS:
+        if builtin_dir.is_dir() and builtin_dir not in search_dirs:
+            search_dirs.append(builtin_dir)
+
    target_norm = deck_name.lower().replace("_", "").replace(" ", "")

    for d in search_dirs:
@@ -303,9 +322,9 @@ def _load_deck_cards_by_name(deck_name: str) -> list:

    Resolution order:
      1. SQLite DB  (decks built/imported via the Deck Builder UI)
-      2. .dck file fallback -- searches precon_dir, forge_decks_dir, and
-         FORGE_DIR/res/decks/commander so that precon decks work without
-         needing to be manually imported into the DB first.
+      2. .dck file fallback -- searches precon_dir, forge_decks_dir,
+         FORGE_DIR/res/decks/commander, and repo-relative precon-decks/
+         sample-decks/ so precon decks work without any configuration.
    """
    # -- 1. DB lookup --
    conn = _get_db_conn()
@@ -30,9 +30,13 @@ import java.util.regex.*;
 *      waits on {@code humanActionQueue}, converts the action to the
 *      macro-action string expected by /api/policy/decide, and injects it
 *      via POST /api/policy/override so the policy server returns it.
- *   4. Publishes a full state snapshot to the WebSocket frontend after every
+ *   4. AI seats (1+) are intercepted at every Priority event: the session
+ *      calls policyClient.decide() with the current state snapshot and
+ *      immediately POSTs the result to /api/policy/override so Forge uses
+ *      the learned policy instead of its built-in AI.
+ *   5. Publishes a full state snapshot to the WebSocket frontend after every
 *      meaningful Forge output event.
- *   5. Falls back to the synthetic stub loop if Forge cannot be started
+ *   6. Falls back to the synthetic stub loop if Forge cannot be started
 *      (e.g., missing JAR, wrong Java version).
 *
 * Zone sync model:
@@ -120,6 +124,12 @@ public class GameSession {
    private volatile boolean gameOver = false;
    private volatile long elapsedMs = 0;

+    // Tracks whether policy was injected for the current priority window
+    // to avoid double-injecting on duplicate log lines.
+    private volatile int lastPolicyInjectionTurn = -1;
+    private volatile String lastPolicyInjectionPhase = "";
+    private volatile int lastPolicyInjectionSeat = -1;
+
    private final int numSeats;
    private final int[] life;
    private final int[] poison;
@@ -309,6 +319,10 @@ public class GameSession {
        watchdog.setDaemon(true);
        watchdog.start();

+        // Connect to policy server before the game loop begins
+        boolean policyConnected = policyClient.connect();
+        log("[Session] Policy server connection: " + (policyConnected ? "OK" : "UNAVAILABLE — AI uses Forge built-in"));
+
        // Emit initial state so UI shows a board immediately
        onStateChange.accept(buildStateSnapshot());

@@ -326,19 +340,29 @@ public class GameSession {
        reader.setDaemon(true);
        reader.start();

-        // Main loop: drain line queue and service human input
+        // Main loop: drain line queue and service human/AI input
        while (!gameOver && running) {
            String line = lineQueue.poll(200, TimeUnit.MILLISECONDS);
            if (line != null) {
                lastActivityEpoch.incrementAndGet();
                boolean changed = parseForgeLine(line);
                if (changed) onStateChange.accept(buildStateSnapshot());
+                // Human seat
                if (awaitingHumanInput) handleHumanTurn(onStateChange);
            } else if (forgeDone.get() && lineQueue.isEmpty()) {
                break;
            }
        }

+        // Flush online learning tuples and submit reward if game finished
+        if (gameOver && policyClient.isServerAvailable()) {
+            double reward = winningSeat != null && winningSeat != 0 ? 1.0 : -0.5;
+            policyClient.submitReward("game-" + seed, reward);
+            policyClient.flushCollectedTuples();
+            log(String.format("[Session] Submitted game reward=%.1f and flushed %d tuples",
+                reward, policyClient.getPendingTuples()));
+        }
+
        watchdog.interrupt();
        try { forgeProcess.waitFor(10, TimeUnit.SECONDS); } catch (InterruptedException ignored) {}

@@ -432,8 +456,28 @@ public class GameSession {
        // Priority
        Matcher mPrio = P_PRIORITY.matcher(line);
        if (mPrio.find()) {
-            priorityPlayer = clampSeat(Integer.parseInt(mPrio.group(1)) - 1);
+            int seat = clampSeat(Integer.parseInt(mPrio.group(1)) - 1);
+            priorityPlayer = seat;
            changed = true;
+
+            // ── Policy injection for AI seats ────────────────────────
+            // Forge doesn't honour --policyServer natively, so we intercept
+            // every AI priority window here and push the policy decision to
+            // /api/policy/override before Forge's next read.
+            if (seat != 0 && policyClient.isServerAvailable()) {
+                // Deduplicate: only inject once per (turn, phase, seat) window
+                boolean alreadyInjected =
+                    lastPolicyInjectionTurn == turnNumber
+                    && lastPolicyInjectionPhase.equals(phase)
+                    && lastPolicyInjectionSeat == seat;
+
+                if (!alreadyInjected) {
+                    lastPolicyInjectionTurn = turnNumber;
+                    lastPolicyInjectionPhase = phase;
+                    lastPolicyInjectionSeat = seat;
+                    injectAiPolicyDecision(seat);
+                }
+            }
        }

        // Life totals
@@ -535,6 +579,49 @@ public class GameSession {
        return changed;
    }

+    // ----------------------------------------------------------------
+    // AI policy injection (real Forge IPC path)
+    // ----------------------------------------------------------------
+
+    /**
+     * Ask the Python policy server what action AI seat {@code seat} should
+     * take given the current game state, then POST it to /api/policy/override
+     * so that the next time Forge calls /api/policy/decide for this seat it
+     * receives the pre-computed answer without an extra round-trip.
+     *
+     * This is the core wiring that was missing: Forge's sim mode does not
+     * natively call --policyServer, so we intercept every Priority log line
+     * and drive the decision from the Java side instead.
+     */
+    private void injectAiPolicyDecision(int seat) {
+        try {
+            PolicyClient.PolicyDecision decision =
+                policyClient.decide(GSON.toJson(buildStateSnapshot()), seat);
+
+            if (decision == null || decision.action() == null) {
+                log(String.format("[Policy] seat=%d turn=%d phase=%s → null decision, skipping override",
+                    seat, turnNumber, phase));
+                return;
+            }
+
+            String action = decision.action();
+            log(String.format("[Policy] seat=%d turn=%d phase=%s → %s (conf=%.2f)",
+                seat, turnNumber, phase, action, decision.confidence()));
+
+            // Push the decision to the override endpoint so Forge's next
+            // /api/policy/decide call for this seat returns it immediately.
+            JsonObject body = new JsonObject();
+            body.addProperty("seat", seat);
+            body.addProperty("action", action);
+            httpPost(policyServerUrl + "/api/policy/override", body.toString());
+
+        } catch (Exception e) {
+            // Non-fatal: Forge falls back to its built-in AI for this window
+            log(String.format("[Policy] seat=%d override failed (%s) — Forge built-in takes over",
+                seat, e.getMessage()));
+        }
+    }
+
    // ----------------------------------------------------------------
    // Human turn handling
    // ----------------------------------------------------------------
Author	SHA1	Message	Date
rgriffith	99044342c2	fix: remove stray } after showManaPool stub (line 1856)	2026-04-04 13:33:37 -04:00
rgriffith	d5fd648139	fix: update tracked paths — files moved from root to lan-client/	2026-04-03 23:31:36 -04:00
rgriffith	022f89478d	fix: restore ui.js from placeholder corruption + Phase 1 patches	2026-04-03 23:25:01 -04:00
KoalaTrapLord	336f913d4b	feat(phase-1): no-op mana pool display functions in ui.js - renderManaPool() -> stub (floating #mana-pool-display removed from UI) - showManaPool() -> stub - Remove 'Mana Auto-Clear' row from renderSettingsPanel() Internal mana tracking state (manaPool object, canPayManaCost, clearManaPool, clearAllManaPools, etc.) fully preserved in engine.js. createInitialState() already had energy/experience/rad/emblems. setupManaPoolDrag() in engine.js already a no-op stub. index.html and style.css require no changes.	2026-04-03 18:54:22 -04:00
KoalaTrapLord	661847a4d8	feat(phase-1): no-op mana pool display functions in ui.js - renderManaPool() → stub comment (floating #mana-pool-display removed) - showManaPool() → stub comment - Remove 'Mana Auto-Clear' row from renderSettingsPanel() Internal mana tracking state (manaPool object, canPayManaCost, clearManaPool, etc.) fully preserved in engine.js. createInitialState() already had energy/experience/rad/emblems. setupManaPoolDrag() in engine.js already stubbed. index.html and style.css require no changes. Closes #190 Phase 1	2026-04-03 18:51:15 -04:00
KoalaTrapLord	e710fd5e03	placeholder	2026-04-03 18:50:51 -04:00
KoalaTrapLord	85af163123	Wire Forge IPC into POST /api/game/start via run_batch_subprocess + --policy flag	2026-04-03 17:57:35 -04:00
KoalaTrapLord	f2e87feb4e	Fix default port: 8000 -> 8080	2026-04-03 17:54:15 -04:00
KoalaTrapLord	948f8e0f8f	Fix PS1 parse errors: escape apostrophes, fix string terminators, fix scriptblock braces	2026-04-03 17:52:08 -04:00
KoalaTrapLord	84d56bf901	Add Test-PolicyServer.ps1 — smoke-test health + decide endpoint from PowerShell	2026-04-03 17:50:04 -04:00
KoalaTrapLord	74d24d606c	fix: wire PolicyClient into real Forge IPC path via Priority interception Forge's sim mode does not honour --policy/--policyServer CLI flags, so the Python brain was never called during live games. AI only played lands because Forge ran its built-in AI for every decision. Fix: when parseForgeLine() detects a Priority event for an AI seat, the session now immediately calls policyClient.decide() with the current state snapshot and POSTs the result to /api/policy/override before Forge reads the next line. This mirrors what handleHumanTurn() already does for seat 0. The synthetic fallback path is unchanged.	2026-04-03 17:42:01 -04:00
KoalaTrapLord	98e1092ebc	feat: wire DecisionExporter into Forge pipeline + fix reward call signatures - Add _export_forge_episode() adapter: translates ForgeEpisode transitions back into DecisionExporter.record_step() calls so Forge-sourced wins flow into the distillation JSONL pipeline (closes Phase 1 for real games) - ppo_consumer() now accepts an optional `exporter: DecisionExporter` arg; begin_episode / record_step / end_episode are called around each episode as it is dequeued - run_forge_pipeline() forwards the exporter kwarg down to ppo_consumer and calls exporter.flush() after the pipeline completes, returning the output path in the stats dict under "exporter_file" - Fix snapshots_to_episode(): compute_terminal_reward() was called with non-existent kwargs `turns=` and `life_remaining=`; compute_intermediate_reward() was called with non-existent kwargs `life_delta=`, `cards_drawn=`, `creatures_played=`. Both now use the correct signatures from reward.py (prev_state/curr_state/action_taken for intermediate; won/draw/timeout for terminal). Forge snapshots carry `players` arrays so we reconstruct minimal prev/curr dicts for the intermediate path. Ref: docs/CLOSED-LOOP-DISTILLATION.md Phase 1	2026-04-03 17:09:05 -04:00
KoalaTrapLord	9338ac881b	fix(labeler): infer cast sub-type from hand contents when action.card absent The Forge DecisionExporter writes action={"type":"cast"} without a card field — action.get("card") and action.get("raw") always returned "", causing every cast to fall through to the CAST_CREATURE default. Fix: when card_name is empty, scan the active player's hand against the removal / draw / ramp / commander name databases and pick the highest-priority match found. Priority order mirrors cast importance: removal > ramp > draw > commander > creature (default) A hand-level match is a reasonable proxy for the decision made: Forge's AI picks the highest-priority action from available options, so if the hand contains a removal spell during main phase, the cast action almost certainly represents that removal spell being played. Also fixes print_label_distribution: was sorting by dict key (string) instead of by index, causing the display order to be alphabetical rather than matching the MacroAction enum order — making cast_creature appear at position 0 in the sorted output even when it had counts. Now prints in descending count order with correct enum-keyed lookup.	2026-04-03 16:55:59 -04:00
KoalaTrapLord	c3ff9f8888	feat(data): add DeepSeek ds- source with 4x default upweight _discover_jsonl_files now recognises ml-decisions-ds-*.jsonl as its own "ds" source key instead of falling through to legacy/forge. DatasetConfig.source_weights gains ds=4.0 as a default so the 8 ds files (1775 records, ~5.8% raw) are oversampled to ~20% of effective training tokens, matching their higher signal quality. CLI gains --ds-weight argument (default 4.0) to override without code changes. The training_manifest.json produced by PowerShell already encodes weight=4.0 per ds file; this change makes dataset_builder.py honour the same ratio natively so the manifest and the builder stay in sync.	2026-04-03 16:46:57 -04:00
KoalaTrapLord	e4f35a2d8b	debug: log top-5 action probabilities on every decide() call Adds a single INFO log line after each successful inference showing: - chosen action + confidence - top-5 actions sorted by probability - turn, phase, vector_source This lets us diagnose the 'only plays lands' behaviour without a Python REPL. Remove or downgrade to DEBUG once the training issue is resolved.	2026-04-03 16:08:50 -04:00
KoalaTrapLord	084742a56a	docs: rewrite README — full feature coverage from 52 merged PRs	2026-04-03 20:04:32 +00:00
KoalaTrapLord	45a413837b	docs: rewrite README — full feature coverage from 52 merged PRs	2026-04-03 20:04:32 +00:00
KoalaTrapLord	018852c92d	fix: collapse cmdr_dmg dict to int in _encode_global before division Forge sends cmdr_dmg as a dict keyed by opponent seat (e.g. {"0": 14, "2": 7}). _encode_global read it raw and crashed on `dict / 21.0`. Fix: resolve cmdr_dmg to a scalar at the read site — sum dict values if it's a dict, cast to int if it's already a number, default to 0. This is defensive for all call paths (live Forge IPC, JSONL training, _build_encoder_snapshot pre-collapsed int) so no upstream change needed.	2026-04-03 15:46:36 -04:00
KoalaTrapLord	4ca21e5e29	debug: add exc_info=True + unique logger names to expose real traceback Both 'Inference error' log lines use identical logger strings, making it impossible to tell which except block is catching the crash. Also, broad except blocks were swallowing the full traceback so the real crash site and cause were hidden. Changes: - policy_server.py: logger renamed to 'ml.serving.policy_server'; predict() and predict_batch() error handlers add exc_info=True - routes/policy.py: logger renamed to 'routes.policy.decide'; _infer_from_vector() error handler adds exc_info=True; decide() fallback warning adds exc_info=True The next crash will print the full stack trace, pinpointing the exact line and call chain causing the TypeError.	2026-04-03 15:39:54 -04:00
KoalaTrapLord	28665bf663	fix: apply _unwrap_logits guard in _infer_from_vector (routes/policy.py) The crash `unsupported operand type(s) for /: 'dict' and 'float'` was firing from _infer_from_vector(), which is the code path taken when has_precomputed_vector() is True (GameSession 1.1.0+ snapshots with a precomputed state_vector float[29]). Unlike PolicyInferenceService.predict() — which was fixed in the previous commit via _unwrap_logits — this function calls policy_service.model(state_tensor) directly and immediately uses the return value in arithmetic (logits / max(temperature, 0.01)), so any tuple/dict return (DataParallel, torch.compile, PolicyValueNetwork swap) causes the TypeError. Fix: import _unwrap_logits from ml.serving.policy_server and apply it to the raw model output in _infer_from_vector before the temperature division and argmax calls. All three return shapes are now handled: - plain tensor → passthrough (normal case, zero overhead) - tuple/list → raw[0] (PolicyValueNetwork (logits, value)) - dict → first recognised key or first tensor value	2026-04-03 15:16:49 -04:00
KoalaTrapLord	83d05294c8	fix: type-guard logits after model() to prevent 'dict / float' inference crash If self.model is wrapped (DataParallel, torch.compile, or future PolicyValueNetwork path), forward() can return a tuple (logits, value) or even a dict. Add an explicit unwrap immediately after the forward call in both predict() and predict_batch() so every downstream temperature/softmax operation always receives a plain tensor.	2026-04-03 14:55:58 -04:00
KoalaTrapLord	e8f8766d59	fix: register policy routes at module scope before StaticFiles mounts The root cause of the persistent /api/policy/health 404: - app.mount("/", StaticFiles(...)) is called at module load time - StaticFiles acts as a sub-app and consumes matching requests, returning its own 404 for unknown files rather than falling through - register_policy_routes() was called in lifespan (runtime), AFTER the "/" mount was already in the route list — so the policy router was effectively unreachable Fix: move route registration to module scope right after all other app.include_router() calls and BEFORE any app.mount() calls. Only the model load (_POLICY_SVC.load()) stays in lifespan.	2026-04-03 13:09:12 -04:00
KoalaTrapLord	a69b273f5f	fix: always register policy routes at startup regardless of model load state Previously /api/policy/health returned 404 when the model wasn't loaded because register_policy_routes() was gated behind _policy_svc.load(). The health endpoint itself already handles the unloaded state gracefully (returns {ready: false, status: degraded}), so the router must be mounted unconditionally so ai-bridge.js can poll it during startup.	2026-04-03 12:29:18 -04:00
KoalaTrapLord	e55ac9aebf	feat: add Scryfall image enrichment after .dck load — batch fetch card art for all zones	2026-04-03 11:30:30 -04:00
KoalaTrapLord	d2b86ef2ed	fix: wire precon-loader.js into index.html script load order	2026-04-03 11:19:37 -04:00
KoalaTrapLord	081dd66121	fix: add startGameWithDecks() and loadPreconDeckFromDck() for precon .dck loading into simulator	2026-04-03 11:17:27 -04:00
KoalaTrapLord	6d89d5bb08	fix: add PRECON_DIR env var (PRECON_DECKS_DIR was never read by lab_api.py)	2026-04-03 11:15:31 -04:00
KoalaTrapLord	f29a5a31b5	feat: add /api/lab/precons and /api/lab/precons/deck endpoints Fixes 404 errors from lan-client ai-bridge.js which calls these routes to populate the deck selector. Routes were missing from lab.py — only precon_router (routes/precon.py) existed but served different paths. Also added PRECON_DECKS_DIR env var alias in lab_api.py _parse_args() to match the .env variable name users commonly set.	2026-04-03 11:08:12 -04:00
KoalaTrapLord	370d4cd92f	Merge pull request #200 from KoalaTrapLord/fix/serve-lan-client-from-backend fix: Serve lan-client from backend at /lan (same-origin)	2026-04-03 10:48:01 -04:00
Commander AI Lab	e90efe1654	fix: serve lan-client from backend at /lan on port 8080 - Mount lan-client/ as static files at /lan with html=True - Mount precon-decks/ at /precon-decks/ for direct .dck access - ai-bridge.js: use same-origin (empty URLs, auto-detect from window.location) - engine.js: simplify deck fetch to use /api/lab/precons/deck endpoint + /precon-decks/ static fallback - Eliminates cross-origin issues by serving everything from localhost:8080 Access the LAN battlefield at http://localhost:8080/lan/	2026-04-03 14:30:55 +00:00
KoalaTrapLord	bf701397b0	Merge pull request #199 from KoalaTrapLord/fix/deck-loading-and-backend-detection fix: Deck loading — wire setupDeckChoices, fetch .dck content, add precon/deck endpoint	2026-04-03 09:49:33 -04:00
Commander AI Lab	7750b43494	fix: deck loading — wire startGameWithDecks, fetch .dck content, parse [sections] Three fixes that prevented precon decks from loading into actual gameplay: 1. ui.js: window.startGame() now calls startGameWithDecks() when setupDeckChoices has entries (the 3-tab selector stores choices there). Previously it called initGame() which looked for old deck-sel-{i} dropdowns that no longer exist. 2. engine.js: loadPreconForPlayer() now fetches .dck file content from the backend (/api/lab/precons/deck?fileName=...) when precon.decklist is empty. Falls back to fetching precon-decks/{file} directly. PRECON_DATA entries only have metadata (name, commander, set) — the actual card list lives in the .dck files. 3. engine.js: parseDeckList() now handles .dck bracket-style section headers like [Commander], [Main], [metadata]. Previously only matched bare text like 'COMMANDER:' without brackets. Also skips [metadata] lines (e.g. 'Name=Elven Empire'). 4. routes/precon.py: Added GET /api/lab/precons/deck?fileName=... endpoint to serve raw .dck file content for the LAN client.	2026-04-03 13:45:15 +00:00
KoalaTrapLord	fa58463cde	Merge pull request #198 from KoalaTrapLord/fix/setup-screen-layout fix: Setup screen overflows viewport — 2-col deck grid + scroll	2026-04-03 09:38:26 -04:00
Commander AI Lab	94b1e050d8	fix: setup screen overflows viewport — constrain height and use 2-col deck grid - Add max-height: 92vh and overflow-y: auto to .setup-card - Widen .setup-card to 860px to fit 2-column deck grid - Change .deck-assignment-grid from vertical stack to 2-column grid so 4 player panels render in 2 rows instead of 4 - Tighten .deck-tab-content (170px) and .deck-precon-list (140px) - Make top gradient bar sticky on scroll - Responsive fallback to single column below 640px	2026-04-03 13:37:02 +00:00
KoalaTrapLord	8bfde0230b	fix: add precons.js with 163 entries and fix backend precon UI refresh (#197 ) - Generate lan-client/precons.js from precon-decks/precon-index.json so PRECON_DATA is always available for local/offline mode (163 precons) - Add scripts/generate-precons-js.js for regeneration when precons update - Fix _loadBackendPrecons() to re-render the precon tab UI when backend precons load successfully (was only updating status indicator text, not populating the dropdown) Without precons.js, PRECON_DATA was undefined and the dropdown showed 'No precon data loaded' even though 163 .dck files exist in the repo.	2026-04-03 09:31:54 -04:00
KoalaTrapLordandClaude Opus 4.6	4214831e59	feat: LAN Battlefield App Integration with AI Pipeline (#196 ) * feat: LAN Battlefield App integration with Commander-AI-Lab AI pipeline Add the LAN Battlefield App as a browser client (lan-client/) that connects to the Commander-AI-Lab backend for ML-powered AI opponents, 3-category deck selection, and enhanced player panels. Phase 1 - Foundation: - Remove floating mana pool display (keep internal tracking) - Add energy, experience, rad, emblems fields to game state - No-op renderManaPool(), showManaPool(), setupManaPoolDrag() Phase 2 - Backend Connection (ai-bridge.js): - BackendConnector: REST + WebSocket connectivity with retry/timeout - GameStateBridge: Serializes engine.js state for /api/policy/decide - MacroActionMapper: Translates 8 ML macro-actions to engine.js calls - DeckSourceClient: Fetches precon/EDHREC decks from backend API Phase 3 - Deck System: - 3-tab deck selector (Precons / EDHREC / My Decks) replaces dropdown - Precon grouping by set with collapsible sections and filtering - EDHREC search integration (stub, ready for backend implementation) - My Decks textarea import placeholder Phase 4 - AI Integration: - runAiTurn() priority chain: ML Pipeline > Forge > Local Heuristic - _runMlAiTurn() async turn loop with multi-phase decision requests - Backend session initialization on game start - Automatic fallback to local AI on any ML pipeline error Phase 5 - Enhanced Player Panels (player-panels.js): - Collapsible panels with localStorage persistence - Commander damage progress bars with warning/critical thresholds - Poison, energy, experience, rad counter widgets - Emblem tracking with add/remove Phase 6 - Polish: - Script loading order: precons > engine > ai-bridge > panels > ui - Backend auto-detection on page load with status indicator - Connection status display on setup screen Closes #184, Closes #185, Closes #186, Closes #187, Closes #188, Closes #189 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: refine LAN battlefield integration with full JSDoc, proper phase IDs - Add comprehensive JSDoc comments to all ai-bridge.js classes - Use optional chaining for PHASES lookup in GameStateBridge - Direct addLogEntry calls in player-panels.js (loaded after engine.js) - Remove leftover mana pool CSS that was missed in initial pass - Minor style.css cleanup for consistency Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>	2026-04-03 09:16:27 -04:00
KoalaTrapLord	e2568c731c	fix: auto-load .env in state.py so dotenv works without explicit load_dotenv call When running plain `python script.py` or bare uvicorn, .env is never loaded automatically. Added a dotenv bootstrap block at the top of state.py that finds and loads the nearest .env file (walks up from models/ to the project root). Uses load_dotenv with override=False so explicitly set environment variables always win over .env values. Gracefully skips if python-dotenv is not installed.	2026-04-03 08:41:58 -04:00
KoalaTrapLord	d6863b6d7e	fix: auto-populate all CFG paths from environment variables CFG.forge_dir, precon_dir, forge_decks_dir, forge_jar, and lab_jar were only set via CLI args. When the server starts via uvicorn directly (no CLI), all paths stayed empty and forge_card_loader could not find the cardsfolder, causing 0 lands in every deck. Fix: read FORGE_DIR, FORGE_JAR, PRECON_DIR, PRECON_DECKS_DIR, FORGE_DECKS_DIR, and LAB_JAR from environment at import time, mirroring the existing ANTHROPIC_API_KEY / XIMILAR_API_KEY pattern.	2026-04-03 04:56:44 -04:00
KoalaTrapLord	1fc99a5d4a	fix: auto-discover precon-decks/ and sample-decks/ when CFG paths unset _find_dck_file only searched CFG.precon_dir / CFG.forge_decks_dir, both of which are empty when the server is started without CLI args. This caused all precon deck lookups to return 0 cards. Fix: add _REPO_ROOT and _BUILTIN_DECK_DIRS constants, then append precon-decks/, sample-decks/, imported-decks/ to the search list whenever they exist on disk, regardless of whether CFG paths are set.	2026-04-03 04:50:49 -04:00
KoalaTrapLord	eed2c7f126	New HTML battlefield to test features before Unity (#182 )	2026-04-03 04:39:33 -04:00