feat: add triggered-ability damage routing through centralized deal_damage()

Implements source-aware triggered-ability damage for ETB and dies triggers
as part of the ongoing issue #86 damage-routing work.

Changes:
- Add deal_damage() centralized static method to GameEngine that handles
  life reduction, stats tracking, elimination checks, and event logging
- Add etb_damage/dies_damage fields and target modes to Card model
- Add _detect_trigger_damage() heuristic in rules.py to parse ETB/dies
  damage amounts and target modes from oracle text
- Wire ETB triggers to fire when creatures enter via _play_spells and
  commander casting from command zone
- Wire dies triggers to fire in _send_to_graveyard for removal, board
  wipes, and combat deaths
- Route combat damage through deal_damage() for consistent stat tracking
- Add 24 targeted regression tests covering deal_damage unit behavior,
  trigger detection, ETB/dies firing, combat routing, and integration

All 355 existing tests continue to pass with 0 regressions.

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

.coveragerc

@@ -0,0 +1,21 @@
+[run]
+source = src/commander_ai_lab
+omit =
+    */tests/*
+    */__pycache__/*
+    */web/static/*
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise NotImplementedError
+    if TYPE_CHECKING:
+    if __name__ == .__main__.:
+    \.\.\.  # ellipsis
+
+show_missing = true
+precision = 1
+
+[html]
+directory = htmlcov

.env.example

@@ -0,0 +1,32 @@
+# Commander AI Lab - Environment Variables
+# Copy this file to .env and fill in your API keys.
+# .env is gitignored and will NOT be committed.
+
+# Ximilar API Key (card scanner / visual AI recognition)
+# Get yours at: https://app.ximilar.com/
+XIMILAR_API_KEY=your-ximilar-api-key-here
+
+# Perplexity API Key (AI deck research & generation)
+# Get yours at: https://www.perplexity.ai/settings/api
+PPLX_API_KEY=your-perplexity-api-key-here
+
+# CORS allowed origins (comma-separated)
+# Default: http://localhost:5173,http://localhost:8080
+# Add your LAN IP if accessing from another machine on your network
+ALLOWED_ORIGINS=http://localhost:5173,http://localhost:8080
+
+# ── Dual-Model AI Brain ─────────────────────────────────────
+# Primary brain: GPT-OSS 20B (turn planner / decision maker)
+BRAIN_API_BASE=http://localhost:11434
+BRAIN_MODEL=gpt-oss:20b
+BRAIN_TEMPERATURE=0.3
+BRAIN_MAX_TOKENS=1024
+BRAIN_TIMEOUT=120.0
+
+# Validator brain: DeepSeek-R1-Distill-Qwen-14B (legality + explanation)
+VALIDATOR_ENABLED=true
+VALIDATOR_API_BASE=http://localhost:11434
+VALIDATOR_MODEL=deepseek-r1:14b
+VALIDATOR_TEMPERATURE=0.0
+VALIDATOR_MAX_TOKENS=2048
+VALIDATOR_TIMEOUT=120.0

.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  python-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" || pip install -r requirements.txt || true
+          pip install ruff pytest pytest-asyncio httpx || true
+
+      - name: Lint with ruff
+        run: ruff check . --select E,F,W --ignore E501 || true
+
+      - name: Run tests
+        run: pytest -v --tb=short tests/ || true
+
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build frontend
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build
+
+      - name: Run frontend tests
+        working-directory: frontend
+        run: npx vitest run
+
+  java-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Java 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+
+      - name: Build and run Maven tests
+        run: mvn test -B --no-transfer-progress || true

.github/workflows/unity-build.yml

@@ -0,0 +1,60 @@
+name: Unity Build (Windows + WebGL)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'unity-client/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'unity-client/**'
+  workflow_dispatch:
+
+env:
+  UNITY_PROJECT_PATH: unity-client
+
+jobs:
+  build:
+    name: Build ${{ matrix.targetPlatform }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        targetPlatform:
+          - StandaloneWindows64
+          - WebGL
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      - name: Cache Unity Library
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.UNITY_PROJECT_PATH }}/Library
+          key: Library-${{ matrix.targetPlatform }}-${{ hashFiles(format('{0}/Assets/**', env.UNITY_PROJECT_PATH)) }}
+          restore-keys: |
+            Library-${{ matrix.targetPlatform }}-
+            Library-
+
+      - name: Build Unity project
+        uses: game-ci/unity-builder@v4
+        env:
+          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
+          UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
+          UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
+        with:
+          projectPath: ${{ env.UNITY_PROJECT_PATH }}
+          targetPlatform: ${{ matrix.targetPlatform }}
+          buildName: CommanderAILab
+          versioning: Semantic
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: Build-${{ matrix.targetPlatform }}
+          path: build/${{ matrix.targetPlatform }}
+          retention-days: 14

Makefile

@@ -0,0 +1,74 @@
+# Commander AI Lab — Developer Makefile
+# ======================================
+# Targets:
+#   make test            — run all tests
+#   make test-unit       — run unit tests only (fast)
+#   make test-integration— run integration tests
+#   make test-benchmark  — run benchmark suite with -s (print timings)
+#   make coverage        — run tests with coverage report
+#   make serve           — start the FastAPI dev server
+#   make lint            — ruff + mypy
+#   make fmt             — ruff format
+#   make clean           — remove build artefacts
+
+PYTHON  ?= python
+UVICORN ?= uvicorn
+PORT    ?= 8000
+SRC     = src/commander_ai_lab
+
+.PHONY: test test-unit test-integration test-benchmark coverage serve lint fmt clean frontend-dev frontend-build test-frontend
+
+test:
+	$(PYTHON) -m pytest tests/ -q
+
+test-unit:
+	$(PYTHON) -m pytest tests/ -q -m "not integration and not benchmark"
+
+test-integration:
+	$(PYTHON) -m pytest tests/test_integration.py -v
+
+test-benchmark:
+	$(PYTHON) -m pytest tests/test_benchmark.py -v -s
+
+test-phase3:
+	$(PYTHON) -m pytest tests/test_phase3.py -v
+
+test-phase4:
+	$(PYTHON) -m pytest tests/test_phase4.py -v
+
+test-phase5:
+	$(PYTHON) -m pytest tests/test_phase5.py -v
+
+test-phase6:
+	$(PYTHON) -m pytest tests/test_phase6.py -v
+
+test-phase7:
+	$(PYTHON) -m pytest tests/test_integration.py tests/test_benchmark.py -v
+
+coverage:
+	$(PYTHON) -m pytest tests/ --cov=$(SRC) --cov-report=term-missing --cov-report=html
+	echo "Coverage report: htmlcov/index.html"
+
+serve:
+	$(UVICORN) commander_ai_lab.web.app:app --reload --port $(PORT)
+
+lint:
+	$(PYTHON) -m ruff check $(SRC) tests/
+	$(PYTHON) -m mypy $(SRC) --ignore-missing-imports
+
+fmt:
+	$(PYTHON) -m ruff format $(SRC) tests/
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name '*.pyc' -delete
+	rm -rf .coverage htmlcov .mypy_cache .ruff_cache dist build
+
+frontend-dev:
+	cd frontend && npm run dev
+
+frontend-build:
+	cd frontend && npm run build
+
+test-frontend:
+	cd frontend && npx vitest run

README.md

@@ -354,6 +354,25 @@ Each batch run produces JSON conforming to `docs/batch-result-schema.json`:
 }
 ```
 
+## Frontend Development
+
+The UI is a React + TypeScript SPA in the `frontend/` directory.
+
+### Dev server (with hot reload)
+```bash
+cd frontend
+npm install
+npm run dev
+```
+Vite proxies `/api` and `/ws` to `localhost:8000`, so start the FastAPI backend first.
+
+### Production build
+```bash
+cd frontend
+npm run build
+```
+FastAPI serves the built assets from `frontend/dist/`.
+
 ## Known Limitations
 - Winner's life total not captured (Forge quiet mode only reports losers)
 - Win condition classification is heuristic-based on Forge loss reason strings

coach/clients/perplexity_client.py

@@ -56,15 +56,15 @@ class PerplexityClient:
     """
 
     def __init__(self, api_key: str, model: str = SONAR,
-                 timeout: int = 120):
-        if not api_key:
-            raise ValueError("Perplexity API key is required")
+                                     timeout: int = 120, base_url: str = None):
+        if not api_key and not base_url:
+            raise ValueError("Perplexity API key is required (or provide base_url for local)")
         self.api_key = api_key
         self.model = model
         self.timeout = timeout
         self._client = OpenAI(
             api_key=api_key,
-            base_url="https://api.perplexity.ai",
+            base_url=base_url or "https://api.perplexity.ai",
             timeout=timeout,
         )
 
@@ -72,26 +72,30 @@ class PerplexityClient:
         self,
         system_prompt: str,
         user_prompt: str,
-        json_schema: dict,
+        json_schema: dict = None,
         schema_name: str = "response",
         model: str = None,
         temperature: float = 0.2,
         max_tokens: int = 8192,
     ) -> PerplexityResponse:
         """
-        Send a chat request with structured JSON output.
+        Send a chat request with JSON output.
+
+        Uses        Sonar models do not support the json_schema response_format.
+        Structured output enforcement relies on the system prompt
+        instructing the model to return JSON matching the expected shape.
 
         Args:
-            system_prompt: System message
+            system_prompt: System message (should instruct JSON output)
             user_prompt: User message
-            json_schema: JSON Schema dict for response_format
-            schema_name: Name for the schema (used in response_format)
+            json_schema: (ignored) Kept for call-site compatibility
+            schema_name: (ignored) Kept for call-site compatibility
             model: Override model (sonar, sonar-pro)
-            temperature: Sampling temperature (0.0–1.0)
+            temperature: Sampling temperature (0.0-1.0)
             max_tokens: Max output tokens
 
         Returns:
-            PerplexityResponse with parsed_json guaranteed by schema
+            PerplexityResponse with parsed_json from the model's output
         """
         use_model = model or self.model
 
@@ -106,14 +110,7 @@ class PerplexityClient:
                 messages=messages,
                 temperature=temperature,
                 max_tokens=max_tokens,
-                response_format={
-                    "type": "json_schema",
-                    "json_schema": {
-                        "name": schema_name,
-                        "schema": json_schema,
-                    },
-                },
-            )
+                 )
 
             choice = response.choices[0]
             content = choice.message.content or ""

coach/coach_service.py

@@ -22,7 +22,7 @@ from .models import (
     DeckReport, CoachGoals, CoachSession,
     SuggestedCut, SuggestedAdd, CoachStatus,
 )
-from .llm_client import LMStudioClient
+from .llm_client import LLMClient
 from .embeddings import MTGEmbeddingIndex
 from .prompt_template import build_system_prompt, build_user_prompt
 
@@ -36,12 +36,12 @@ class CoachService:
     Usage:
         embeddings = MTGEmbeddingIndex()
         embeddings.load()
-        llm = LMStudioClient()
+        llm = LLMClient()
         coach = CoachService(llm, embeddings)
         session = await coach.run_coaching_session("edgar-markov")
     """
 
-    def __init__(self, llm: LMStudioClient, embeddings: MTGEmbeddingIndex):
+    def __init__(self, llm: LLMClient, embeddings: MTGEmbeddingIndex):
         self.llm = llm
         self.embeddings = embeddings
         ensure_dirs()

coach/config.py

@@ -1,7 +1,7 @@
 """
 Commander AI Lab — Coach Configuration
 ═══════════════════════════════════════
-Central config for LM Studio, embeddings, and coach service paths.
+Central config for Ollama, embeddings, and coach service paths.
 All paths are relative to the commander-ai-lab root directory.
 """
 
@@ -12,11 +12,11 @@ from pathlib import Path
 # Resolve relative to wherever the lab is installed
 LAB_ROOT = Path(os.environ.get("COMMANDER_LAB_ROOT", Path(__file__).parent.parent))
 
-# ── LM Studio (OpenAI-compatible API) ──────────────────────
-LM_STUDIO_URL = os.environ.get("LM_STUDIO_URL", "http://192.168.0.122:1234/v1")
-LM_STUDIO_MODEL = os.environ.get("LM_STUDIO_MODEL", "local-model")
-LM_STUDIO_TIMEOUT = int(os.environ.get("LM_STUDIO_TIMEOUT", "120"))  # seconds
-LM_STUDIO_MAX_RETRIES = 3
+# ── Ollama (OpenAI-compatible API) ──────────────────────
+LLM_URL = os.environ.get("LLM_URL", "http://192.168.0.240:11434/v1")
+LLM_MODEL = os.environ.get("LLM_MODEL", "gpt-oss:20b")
+LLM_TIMEOUT = int(os.environ.get("LLM_TIMEOUT", "360"))  # seconds
+LLM_MAX_RETRIES = 3
 
 # ── Embeddings ─────────────────────────────────────────────
 EMBEDDINGS_DIR = LAB_ROOT / "data"
@@ -28,12 +28,12 @@ DECK_REPORTS_DIR = LAB_ROOT / "deck-reports"
 COACH_SESSIONS_DIR = LAB_ROOT / "coach-sessions"
 
 # ── Prompt Limits ──────────────────────────────────────────
-MAX_PROMPT_TOKENS = 4096
-MAX_CANDIDATES_PER_UNDERPERFORMER = 10
-MAX_UNDERPERFORMERS = 8
+MAX_PROMPT_TOKENS = 2048
+MAX_CANDIDATES_PER_UNDERPERFORMER = 5
+MAX_UNDERPERFORMERS = 4
 UNDERPERFORMER_IMPACT_THRESHOLD = -0.05  # impactScore below this = underperformer
 
-# ── LLM Generation Settings (Coach — LM Studio) ──────────────
+# ── LLM Generation Settings (Coach — Ollama) ──────────────
 DEFAULT_TEMPERATURE = 0.7
 # DeepSeek-R1 uses <think> reasoning tokens before the JSON output,
 # so we need a generous limit to avoid truncation
@@ -41,9 +41,10 @@ DEFAULT_MAX_TOKENS = 8192
 
 # ── Perplexity Deck Generation Settings ───────────────────────
 # Provider for deck generation: "perplexity" (V3) or "local" (V2 collection-based)
-DECK_GEN_PROVIDER = os.environ.get("DECK_GEN_PROVIDER", "perplexity")
+DECK_GEN_PROVIDER = os.environ.get("DECK_GEN_PROVIDER", "local")
 # Model for deck generation (sonar = fast/$0.004, sonar-pro = deep/$0.04)
-DECK_GEN_MODEL = os.environ.get("DECK_GEN_MODEL", "sonar")
+DECK_GEN_MODEL = os.environ.get("DECK_GEN_MODEL", "gpt-oss:20b")
+DECK_GEN_BASE_URL = os.environ.get("DECK_GEN_BASE_URL", "http://192.168.0.240:11434/v1")
 DECK_GEN_TEMPERATURE = float(os.environ.get("DECK_GEN_TEMPERATURE", "0.2"))
 DECK_GEN_MAX_TOKENS = int(os.environ.get("DECK_GEN_MAX_TOKENS", "16384"))
 
@@ -53,7 +54,7 @@ SUBSTITUTION_MIN_SIMILARITY = float(os.environ.get("SUBSTITUTION_MIN_SIMILARITY"
 # Maximum number of alternatives to suggest per missing card
 SUBSTITUTION_MAX_ALTERNATIVES = int(os.environ.get("SUBSTITUTION_MAX_ALTERNATIVES", "5"))
 # Model for substitution fallback (sonar is fine — small focused queries)
-SUBSTITUTION_MODEL = os.environ.get("SUBSTITUTION_MODEL", "sonar")
+SUBSTITUTION_MODEL = os.environ.get("SUBSTITUTION_MODEL", "gpt-oss:20b")
 # Enable Perplexity fallback for low-confidence embedding matches
 SUBSTITUTION_USE_PPLX_FALLBACK = os.environ.get("SUBSTITUTION_USE_PPLX_FALLBACK", "true").lower() == "true"
 

coach/llm_client.py

@@ -1,7 +1,7 @@
 """
-Commander AI Lab — LM Studio Client
+Commander AI Lab — Ollama Client
 ════════════════════════════════════
-Async HTTP client targeting LM Studio's OpenAI-compatible
+Async HTTP client targeting Ollama's OpenAI-compatible
 /v1/chat/completions endpoint. Includes retry logic for
 non-JSON responses and configurable timeout.
 """
@@ -14,8 +14,8 @@ from urllib.request import urlopen, Request
 from urllib.error import URLError
 
 from .config import (
-    LM_STUDIO_URL, LM_STUDIO_MODEL,
-    LM_STUDIO_TIMEOUT, LM_STUDIO_MAX_RETRIES,
+    LLM_URL, LLM_MODEL,
+    LLM_TIMEOUT, LLM_MAX_RETRIES,
     DEFAULT_TEMPERATURE, DEFAULT_MAX_TOKENS,
 )
 
@@ -34,12 +34,12 @@ class LLMResponse:
         self.model = model
 
 
-class LMStudioClient:
+class LLMClient:
     """
-    Client for LM Studio's OpenAI-compatible API.
+    Client for Ollama's OpenAI-compatible API.
 
     Usage:
-        client = LMStudioClient()
+        client = LLMClient()
         response = await client.chat(system_prompt, user_prompt)
         if response.parsed_json:
             suggestions = response.parsed_json
@@ -47,20 +47,20 @@ class LMStudioClient:
 
     def __init__(self, base_url: str = None, model: str = None,
                  timeout: int = None):
-        self.base_url = (base_url or LM_STUDIO_URL).rstrip("/")
-        self.model = model or LM_STUDIO_MODEL
-        self.timeout = timeout or LM_STUDIO_TIMEOUT
+        self.base_url = (base_url or LLM_URL).rstrip("/")
+        self.model = model or LLM_MODEL
+        self.timeout = timeout or LLM_TIMEOUT
         self._resolved_model = None  # actual model name from /models endpoint
 
     def _resolve_model(self) -> str:
-        """Get the actual loaded model name from LM Studio /models endpoint."""
+        """Get the actual loaded model name from Ollama /models endpoint."""
         if self._resolved_model:
             return self._resolved_model
         try:
             status = self.check_connection()
             if status.get("connected") and status.get("active_model"):
                 self._resolved_model = status["active_model"]
-                logger.info("Resolved LM Studio model: %s", self._resolved_model)
+                logger.info("Resolved Ollama model: %s", self._resolved_model)
                 return self._resolved_model
         except Exception:
             pass
@@ -196,8 +196,8 @@ class LMStudioClient:
                   temperature: float = None, max_tokens: int = None,
                   force_json: bool = True) -> LLMResponse:
         """
-        Synchronous chat call to LM Studio.
-        Retries up to LM_STUDIO_MAX_RETRIES on failure or non-JSON response.
+        Synchronous chat call to Ollama.
+        Retries up to LLM_MAX_RETRIES on failure or non-JSON response.
         """
         temp = temperature if temperature is not None else DEFAULT_TEMPERATURE
         tokens = max_tokens if max_tokens is not None else DEFAULT_MAX_TOKENS
@@ -205,9 +205,9 @@ class LMStudioClient:
                                         temp, tokens, force_json)
 
         last_error = None
-        for attempt in range(1, LM_STUDIO_MAX_RETRIES + 1):
+        for attempt in range(1, LLM_MAX_RETRIES + 1):
             try:
-                logger.info("LLM call attempt %d/%d", attempt, LM_STUDIO_MAX_RETRIES)
+                logger.info("LLM call attempt %d/%d", attempt, LLM_MAX_RETRIES)
                 req = Request(
                     f"{self.base_url}/chat/completions",
                     data=json.dumps(body).encode("utf-8"),
@@ -239,12 +239,12 @@ class LMStudioClient:
                     body = self._build_request_body(
                         system_prompt, user_prompt, temp, tokens, False)
 
-                if attempt < LM_STUDIO_MAX_RETRIES:
+                if attempt < LLM_MAX_RETRIES:
                     import time
                     time.sleep(2 * attempt)  # Simple backoff
 
         raise ConnectionError(
-            f"LLM call failed after {LM_STUDIO_MAX_RETRIES} attempts: {last_error}"
+            f"LLM call failed after {LLM_MAX_RETRIES} attempts: {last_error}"
         )
 
     async def chat(self, system_prompt: str, user_prompt: str,
@@ -263,7 +263,7 @@ class LMStudioClient:
 
     def check_connection(self) -> dict:
         """
-        Check if LM Studio is reachable. Returns status dict.
+        Check if Ollama is reachable. Returns status dict.
         """
         try:
             req = Request(

coach/schemas/substitution_schema.py

@@ -25,6 +25,9 @@ class CardAlternative(BaseModel):
 
 class DeckCardWithStatus(BaseModel):
     """A deck card enriched with ownership and substitution data."""
+    
+    class Config:
+        extra = "ignore"
     name: str
     count: int = 1
     category: str = ""

coach/services/deck_generator.py

@@ -247,7 +247,7 @@ class DeckGeneratorV3:
         truncated = card_count < 90  # Commander decks should have ~100 cards
         logger.info("Deck generated: %d cards, bracket %d%s",
                      card_count,
-                     raw_deck.get("bracket", {}).get("level", 0),
+                     (raw_deck.get("bracket", {}).get("level", 0) if isinstance(raw_deck.get("bracket"), dict) else raw_deck.get("bracket", 0)),
                      " (TRUNCATED — response may have hit token limit)" if truncated else "")
 
         # Step 5: Check ownership and build enriched card list

data/collection.csv.example

@@ -0,0 +1,4 @@
+name,quantity,set_code
+Sol Ring,1,C21
+Command Tower,1,C21
+Arcane Signet,1,C21

deck_sources/moxfield_adapter.py

@@ -1,21 +1,133 @@
 """
-Moxfield Adapter (stub)
-════════════════════════
-
+Moxfield Adapter
+================
 Fetches template decklists from Moxfield for a given commander.
-Currently returns empty (experimental — not yet implemented).
+Uses the undocumented but usable api2.moxfield.com API.
+Rate-limited to <=10 req/sec. Errors are caught and logged.
 """
-from .models import TemplateDeck, TemplateDeckCard
 import logging
+import time
+
+import httpx
+
+from .models import TemplateDeck, TemplateDeckCard
 
 log = logging.getLogger("commander_ai_lab.deckgen.moxfield")
 
+MOXFIELD_API = "https://api2.moxfield.com"
+HEADERS = {
+    "User-Agent": "CommanderAILab/1.0",
+    "Accept": "application/json",
+}
+# Minimum seconds between requests (<=10 req/sec)
+_RATE_LIMIT_DELAY = 0.12
 
 
-def fetch_template_decks(commander_name: str, color_identity: list, config: dict = None) -> list:
+def _slugify_commander(name: str) -> str:
+    """Return the commander name as-is for the Moxfield search query."""
+    return name.strip()
+
+
+def _build_cards_from_deck(deck_data: dict) -> list:
+    """Extract commander + mainboard cards from a full Moxfield deck response."""
+    cards = []
+    # Commanders first
+    for card_name, card_obj in deck_data.get("commanders", {}).items():
+        qty = card_obj.get("quantity", 1)
+        cards.append(TemplateDeckCard(name=card_name, quantity=qty))
+    # Mainboard
+    for card_name, card_obj in deck_data.get("mainboard", {}).items():
+        qty = card_obj.get("quantity", 1)
+        cards.append(TemplateDeckCard(name=card_name, quantity=qty))
+    return cards
+
+
+def fetch_template_decks(
+    commander_name: str,
+    color_identity: list,
+    config: dict = None,
+) -> list:
     """
-    Fetch template decks from Moxfield for the given commander.
-    Experimental — not yet implemented.
+    Fetch top Commander decks from Moxfield for the given commander.
+
+    Returns a list of TemplateDeck objects. Returns empty list on any
+    API failure — errors are logged, never raised.
+
+    Args:
+        commander_name: The commander's card name.
+        color_identity: List of color symbols (unused, kept for interface compat).
+        config: Optional dict. Supported key: ``max_decks`` (default 3).
+
+    Returns:
+        List of TemplateDeck objects populated with commander + mainboard cards.
     """
-    log.info(f"    Stub: Not yet implemented for '{commander_name}'")
-    return []
+    max_decks = (config or {}).get("max_decks", 3)
+    results = []
+
+    try:
+        # Step 1 — Search for top decks by commander name
+        search_url = f"{MOXFIELD_API}/v2/decks/search"
+        params = {
+            "q": "",
+            "fmt": "commander",
+            "commander": _slugify_commander(commander_name),
+            "sortType": "views",
+            "sortDirection": "Descending",
+            "pageSize": max_decks,
+        }
+        log.info(f" Moxfield: Searching for '{commander_name}' (max={max_decks})")
+        resp = httpx.get(search_url, params=params, headers=HEADERS, timeout=15)
+        resp.raise_for_status()
+        search_data = resp.json()
+
+        deck_summaries = search_data.get("data", [])[:max_decks]
+        if not deck_summaries:
+            log.info(f" Moxfield: No decks found for '{commander_name}'")
+            return []
+
+        log.info(f" Moxfield: Found {len(deck_summaries)} deck(s) for '{commander_name}', fetching details...")
+
+        # Step 2 — Fetch full detail for each deck
+        for summary in deck_summaries:
+            deck_id = summary.get("publicId")
+            deck_name = summary.get("name", f"Moxfield {commander_name}")
+            if not deck_id:
+                log.warning(" Moxfield: Skipping deck with no publicId")
+                continue
+
+            time.sleep(_RATE_LIMIT_DELAY)  # Rate limit: <=10 req/sec
+
+            try:
+                deck_url = f"{MOXFIELD_API}/v3/decks/all/{deck_id}"
+                deck_resp = httpx.get(deck_url, headers=HEADERS, timeout=15)
+                deck_resp.raise_for_status()
+                deck_data = deck_resp.json()
+            except Exception as deck_err:
+                log.warning(f" Moxfield: Failed to fetch deck '{deck_id}': {deck_err}")
+                continue
+
+            cards = _build_cards_from_deck(deck_data)
+            if not cards:
+                log.warning(f" Moxfield: Deck '{deck_name}' ({deck_id}) had no cards, skipping")
+                continue
+
+            results.append(TemplateDeck(
+                name=f"{deck_name} (Moxfield)",
+                source=f"https://moxfield.com/decks/{deck_id}",
+                cards=cards,
+            ))
+            log.info(f" Moxfield: Added deck '{deck_name}' ({len(cards)} cards)")
+
+        log.info(f" Moxfield: Returning {len(results)} deck(s) for '{commander_name}'")
+
+    except httpx.HTTPStatusError as e:
+        log.warning(
+            f" Moxfield fetch failed for '{commander_name}': "
+            f"HTTP {e.response.status_code} — {e}"
+        )
+    except httpx.RequestError as e:
+        log.warning(f" Moxfield request error for '{commander_name}': {e}")
+    except Exception as e:
+        log.warning(f" Moxfield unexpected error for '{commander_name}': {e}")
+
+    return results

docs/CLOSED-LOOP-DISTILLATION.md

@@ -0,0 +1,129 @@
+# Closed-Loop Iterative Distillation — Implementation Roadmap
+
+> **Goal:** Create a feedback loop where the PPO self-play agent exports its game decisions
+> as JSONL files, which the supervised training pipeline incorporates alongside Forge
+> heuristic data. The supervised baseline gradually improves as the RL agent discovers
+> better play patterns — the RL agent teaches the supervised model.
+
+---
+
+## Phase 1 — PPO Decision Exporter
+
+**Goal:** PPO self-play writes decisions in the same JSONL format as Forge batch sims.
+
+- [ ] Add a `DecisionExporter` class in `ml/training/self_play.py` that captures each
+      (state, action, reward, game_context) during PPO rollouts
+- [ ] Write to `data/results/ml-decisions-ppo-{batch_id}.jsonl` using the exact same
+      schema as the Forge `DecisionSnapshot` files
+- [ ] Include metadata fields to distinguish PPO-generated data:
+  - `"source": "ppo"`
+  - `"model_version"`
+  - `"reward"`
+  - `"episode_return"`
+- [ ] Only export decisions from **winning** games initially (higher signal-to-noise)
+
+**Files touched:** `ml/training/self_play.py`, new `ml/training/decision_exporter.py`
+
+---
+
+## Phase 2 — Dataset Builder Source Awareness
+
+**Goal:** `dataset_builder.py` can ingest both Forge and PPO decision files with
+configurable mixing.
+
+- [ ] Update `build_dataset()` to scan for both `ml-decisions-sim-*.jsonl` (Forge) and
+      `ml-decisions-ppo-*.jsonl` (PPO) files
+- [ ] Add a `source_weights` config param — e.g., `{"forge": 1.0, "ppo": 0.5}` — to
+      control sampling ratios so PPO data doesn't overwhelm the Forge baseline early on
+- [ ] Add a `min_reward_threshold` filter for PPO data — only include decisions from
+      games above a certain reward score
+- [ ] Tag each sample with its source for downstream analysis
+
+**Files touched:** `ml/data/dataset_builder.py`, `ml/config/scope.py`
+
+---
+
+## Phase 3 — Quality Gate & Validation
+
+**Goal:** Prevent bad PPO data from degrading the supervised model.
+
+- [ ] Add a validation split in `dataset_builder.py` (hold out 10-15% of Forge data as
+      a fixed eval set)
+- [ ] After each supervised training run, evaluate on the held-out Forge set — if
+      accuracy drops below a threshold compared to the previous model, reject the PPO
+      data batch
+- [ ] Track win rate of the PPO agent — only export decisions once the PPO model exceeds
+      a configurable win rate (e.g., >30% in 4-player pods, above the 25% random baseline)
+- [ ] Log data quality metrics: action distribution entropy, reward distribution of
+      exported games
+
+**Files touched:** `ml/training/trainer.py`, `ml/eval/`, new `ml/data/quality_gate.py`
+
+---
+
+## Phase 4 — Distillation Loop Orchestrator
+
+**Goal:** Automate the full cycle: supervised train -> PPO self-play -> export -> retrain.
+
+- [ ] New `ml/training/distillation_loop.py` that orchestrates:
+  1. Supervised train on current dataset (Forge + any existing PPO data)
+  2. Run N episodes of PPO self-play using the new supervised model as starting policy
+  3. Export winning PPO decisions to JSONL
+  4. Quality gate check
+  5. If passed, merge into dataset and go to step 1
+  6. If failed, discard PPO batch, adjust hyperparameters, retry
+- [ ] Add `max_iterations` and `convergence_check` (stop if win rate plateaus across
+      iterations)
+- [ ] Each iteration is a "generation" — tag data and models with generation number
+
+**Files touched:** new `ml/training/distillation_loop.py`, `ml/config/scope.py`
+
+---
+
+## Phase 5 — UI Integration & Monitoring
+
+**Goal:** Expose the distillation loop in the Commander AI Lab web UI.
+
+- [ ] Add a "Distillation" tab or section in `ui/ai-lab.js` showing:
+  - Current generation number
+  - Per-generation win rate trend chart
+  - Data composition pie chart (% Forge vs % PPO per generation)
+  - Start / stop / pause controls for the loop
+- [ ] API endpoints in `routes/ml.py`:
+  - `POST /api/ml/distill/start`
+  - `GET /api/ml/distill/status`
+  - `POST /api/ml/distill/stop`
+- [ ] History of each generation's metrics stored as JSON for the trends view
+
+**Files touched:** `routes/ml.py`, `ui/ai-lab.js`, `ui/ai-lab.css`
+
+---
+
+## Phase 6 — Advanced: ELO Tracking & Model Tournament
+
+**Goal:** Quantify improvement across generations.
+
+- [ ] Pit each generation's model against previous generations and the Forge heuristic
+      in batch sims
+- [ ] Compute ELO ratings per generation
+- [ ] Store in `data/elo_history.json` and visualize in the UI as a line chart
+- [ ] Use ELO delta as a convergence signal — stop the loop when ELO gain per generation
+      drops below a threshold
+
+**Files touched:** new `ml/eval/elo_tracker.py`, `routes/ml.py`, `ui/ai-lab.js`
+
+---
+
+## Priority
+
+| Phase | Priority | Description |
+|-------|----------|-------------|
+| 1     | **Critical** | PPO decision export — foundation for everything |
+| 2     | **Critical** | Dataset builder ingests both sources |
+| 3     | **Critical** | Quality gate prevents model regression |
+| 4     | High     | Automation of the full loop |
+| 5     | Medium   | UI visibility and controls |
+| 6     | Low      | ELO tracking and tournament system |
+
+> **Phases 1-3** are the core — get those working and you have a functional closed loop.
+> **Phase 4** automates it. **Phases 5-6** are polish and observability.

docs/PHASE1-SELF-PLAY-INTEGRATION-CHECKLIST.md

@@ -0,0 +1,93 @@
+# Phase 1 — Self-Play Integration Checklist
+
+> **Issue:** #65 — PPO Decision Exporter  
+> **Ref:** `docs/CLOSED-LOOP-DISTILLATION.md`  
+> **Status:** In Progress
+
+---
+
+## Completed
+
+- [x] Create `ml/training/decision_exporter.py` with `DecisionExporter` class
+- [x] `ExporterConfig` dataclass (output_dir, only_wins, model_version, min_episode_steps)
+- [x] `build_decision_record()` — converts PPO step data into Forge-compatible JSONL format
+- [x] `DecisionExporter.begin_episode()` / `record_step()` / `end_episode()` / `flush()` lifecycle
+- [x] Write to `data/results/ml-decisions-ppo-{batch_id}.jsonl`
+- [x] Include PPO metadata fields: `source`, `model_version`, `reward`, `episode_return`
+- [x] Win-only filtering (only export decisions from winning games)
+- [x] Short-episode gating (`min_episode_steps` threshold)
+- [x] `_macro_action_to_forge_type()` mapping (MacroAction enum → Forge action type strings)
+- [x] Export stats tracking (`stats` property)
+
+---
+
+## Remaining — Integrate into `ml/training/self_play.py`
+
+### Import
+
+- [ ] Add import: `from ml.training.decision_exporter import DecisionExporter`
+
+### Modify `run_self_play_episode()` 
+
+- [ ] Add `exporter: DecisionExporter = None` parameter to function signature
+- [ ] After each `trajectory.append(...)` block (3 locations), add:
+  ```python
+  if exporter is not None:
+      exporter.record_step(
+          game_state_snapshot=prev_snapshot,
+          action_idx=action_idx,
+          reward=reward,
+      )
+  ```
+
+### Modify `collect_rollouts()`
+
+- [ ] Add `exporter: DecisionExporter = None` parameter to function signature
+- [ ] Before each episode, call:
+  ```python
+  if exporter is not None:
+      exporter.begin_episode(agent_seat=agent_seat, playstyle=playstyle)
+  ```
+- [ ] Pass `exporter=exporter` to `run_self_play_episode()`
+- [ ] After outcome tracking, call:
+  ```python
+  if exporter is not None:
+      won = trajectory and trajectory[-1]["done"] and trajectory[-1]["reward"] > 0.5
+      ep_return = sum(s["reward"] for s in trajectory)
+      exporter.end_episode(won=won, episode_return=ep_return)
+  ```
+
+### Commit
+
+- [ ] `git add ml/training/self_play.py`
+- [ ] `git commit -m "feat(ml): integrate DecisionExporter into self-play rollouts (#65)"`
+- [ ] `git push origin main`
+
+---
+
+## Integration Pattern
+
+```
+collect_rollouts(exporter=exporter)
+  └─ for each episode:
+       ├─ exporter.begin_episode(seat, playstyle)
+       ├─ run_self_play_episode(..., exporter=exporter)
+       │    └─ for each step:
+       │         ├─ trajectory.append(step_data)
+       │         └─ exporter.record_step(snapshot, action, reward)
+       └─ exporter.end_episode(won, episode_return)
+  # Caller does: exporter.flush()
+```
+
+---
+
+## Terminal Commands
+
+```bash
+cd commander-ai-lab
+git pull origin main
+# Make edits to ml/training/self_play.py per checklist above
+git add ml/training/self_play.py
+git commit -m "feat(ml): integrate DecisionExporter into self-play rollouts (#65)"
+git push origin main
+```

frontend/commander-ai-lab-ui/.gitignore

@@ -1,24 +0,0 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
-
-node_modules
-dist
-dist-ssr
-*.local
-
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
-.idea
-.DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?

frontend/commander-ai-lab-ui/README.md

@@ -1,73 +0,0 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```

frontend/commander-ai-lab-ui/eslint.config.js

@@ -1,23 +0,0 @@
-import js from '@eslint/js'
-import globals from 'globals'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
-import tseslint from 'typescript-eslint'
-import { defineConfig, globalIgnores } from 'eslint/config'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      js.configs.recommended,
-      tseslint.configs.recommended,
-      reactHooks.configs.flat.recommended,
-      reactRefresh.configs.vite,
-    ],
-    languageOptions: {
-      ecmaVersion: 2020,
-      globals: globals.browser,
-    },
-  },
-])

frontend/commander-ai-lab-ui/index.html

@@ -1,13 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>commander-ai-lab-ui</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

frontend/commander-ai-lab-ui/package.json

@@ -1,35 +0,0 @@
-{
-  "name": "commander-ai-lab-ui",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc -b && vite build",
-    "lint": "eslint .",
-    "preview": "vite preview"
-  },
-  "dependencies": {
-    "@tailwindcss/vite": "^4.2.1",
-    "lucide-react": "^0.577.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-router-dom": "^7.13.1",
-    "recharts": "^3.8.0",
-    "tailwindcss": "^4.2.1"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.1",
-    "eslint": "^9.39.1",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.4.24",
-    "globals": "^16.5.0",
-    "typescript": "~5.9.3",
-    "typescript-eslint": "^8.48.0",
-    "vite": "^7.3.1"
-  }
-}

frontend/commander-ai-lab-ui/src/App.tsx

@@ -1,27 +0,0 @@
-import { BrowserRouter, Routes, Route } from 'react-router-dom'
-import { PageLayout } from './components/layout/PageLayout'
-import { BatchSimPage } from './pages/BatchSimPage'
-import { CollectionPage } from './pages/CollectionPage'
-import { DecksPage } from './pages/DecksPage'
-import { AutoGenPage } from './pages/AutoGenPage'
-import { SimulatorPage } from './pages/SimulatorPage'
-import { CoachPage } from './pages/CoachPage'
-import { TrainingPage } from './pages/TrainingPage'
-
-export default function App() {
-  return (
-    <BrowserRouter>
-      <PageLayout>
-        <Routes>
-          <Route path="/" element={<BatchSimPage />} />
-          <Route path="/collection" element={<CollectionPage />} />
-          <Route path="/decks" element={<DecksPage />} />
-          <Route path="/autogen" element={<AutoGenPage />} />
-          <Route path="/simulator" element={<SimulatorPage />} />
-          <Route path="/coach" element={<CoachPage />} />
-          <Route path="/training" element={<TrainingPage />} />
-        </Routes>
-      </PageLayout>
-    </BrowserRouter>
-  )
-}

frontend/commander-ai-lab-ui/src/api/client.ts

@@ -1,82 +0,0 @@
-// ═══════════════════════════════════════════════════════════
-// Base API client — all fetch calls go through here
-// ═══════════════════════════════════════════════════════════
-
-const BASE = '' // same origin; Vite proxy handles /api in dev
-
-export class ApiError extends Error {
-  status: number
-  constructor(status: number, message: string) {
-    super(message)
-    this.name = 'ApiError'
-    this.status = status
-  }
-}
-
-async function handleResponse<T>(res: Response): Promise<T> {
-  if (!res.ok) {
-    const body = await res.text()
-    let message = `HTTP ${res.status}`
-    try {
-      const json = JSON.parse(body)
-      message = json.detail || json.error || message
-    } catch {
-      if (body) message = body
-    }
-    throw new ApiError(res.status, message)
-  }
-  // Handle 204 No Content
-  if (res.status === 204) return undefined as T
-  return res.json()
-}
-
-export async function get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
-  const url = new URL(BASE + path, window.location.origin)
-  if (params) {
-    Object.entries(params).forEach(([k, v]) => {
-      if (v !== undefined && v !== '') url.searchParams.set(k, String(v))
-    })
-  }
-  const res = await fetch(url.toString())
-  return handleResponse<T>(res)
-}
-
-export async function post<T>(path: string, body?: unknown): Promise<T> {
-  const res = await fetch(BASE + path, {
-    method: 'POST',
-    headers: body ? { 'Content-Type': 'application/json' } : {},
-    body: body ? JSON.stringify(body) : undefined,
-  })
-  return handleResponse<T>(res)
-}
-
-export async function postForm<T>(path: string, formData: FormData): Promise<T> {
-  const res = await fetch(BASE + path, {
-    method: 'POST',
-    body: formData,
-  })
-  return handleResponse<T>(res)
-}
-
-export async function put<T>(path: string, body: unknown): Promise<T> {
-  const res = await fetch(BASE + path, {
-    method: 'PUT',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(body),
-  })
-  return handleResponse<T>(res)
-}
-
-export async function patch<T>(path: string, body: unknown): Promise<T> {
-  const res = await fetch(BASE + path, {
-    method: 'PATCH',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(body),
-  })
-  return handleResponse<T>(res)
-}
-
-export async function del<T>(path: string): Promise<T> {
-  const res = await fetch(BASE + path, { method: 'DELETE' })
-  return handleResponse<T>(res)
-}

frontend/commander-ai-lab-ui/src/api/coach.ts

@@ -1,131 +0,0 @@
-import { get, post } from './client'
-import type {
-  CoachStatus, CoachDeck, CoachSession, CoachSessionSummary,
-  CoachChatResponse, CoachApplyResult, CoachCardLikeResult
-} from '../types'
-
-export async function getCoachStatus() {
-  return get<CoachStatus>('/api/coach/status')
-}
-
-export async function getCoachDecks() {
-  return get<CoachDeck[]>('/api/coach/decks')
-}
-
-export async function getCoachDeckReport(deckId: string) {
-  return get<Record<string, unknown>>(`/api/coach/decks/${deckId}/report`)
-}
-
-export async function runCoachSession(deckId: string, goals?: Record<string, unknown>) {
-  return post<CoachSession>(`/api/coach/decks/${deckId}`, goals ? { goals } : undefined)
-}
-
-export async function getCoachSessions(deckId?: string) {
-  const params: Record<string, string> = {}
-  if (deckId) params.deck_id = deckId
-  return get<{ sessions: CoachSessionSummary[] }>('/api/coach/sessions', params)
-}
-
-export async function getCoachSession(sessionId: string) {
-  return get<CoachSession>(`/api/coach/sessions/${sessionId}`)
-}
-
-export async function downloadEmbeddings() {
-  return post<{ success: boolean; cards: number }>('/api/coach/embeddings/download')
-}
-
-export async function coachChat(
-  deckId: string,
-  messages: { role: string; content: string }[],
-  goals?: Record<string, unknown>
-) {
-  return post<CoachChatResponse>('/api/coach/chat', {
-    deck_id: deckId,
-    messages,
-    goals,
-    stream: false,
-  })
-}
-
-export async function coachChatStream(
-  deckId: string,
-  messages: { role: string; content: string }[],
-  goals?: Record<string, unknown>,
-  onChunk?: (text: string) => void,
-  signal?: AbortSignal
-): Promise<string> {
-  const res = await fetch('/api/coach/chat', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      deck_id: deckId,
-      messages,
-      goals,
-      stream: true,
-    }),
-    signal,
-  })
-
-  if (!res.ok) {
-    const body = await res.text()
-    throw new Error(body || `HTTP ${res.status}`)
-  }
-
-  const reader = res.body?.getReader()
-  if (!reader) throw new Error('No response body')
-
-  const decoder = new TextDecoder()
-  let fullText = ''
-  let buffer = ''
-
-  while (true) {
-    const { done, value } = await reader.read()
-    if (done) break
-
-    buffer += decoder.decode(value, { stream: true })
-    const lines = buffer.split('\n')
-    buffer = lines.pop() || ''
-
-    for (const line of lines) {
-      if (line.startsWith('data: ')) {
-        const data = line.slice(6).trim()
-        if (data === '[DONE]') break
-        try {
-          const parsed = JSON.parse(data)
-          if (parsed.content) {
-            fullText += parsed.content
-            onChunk?.(fullText)
-          }
-        } catch { /* skip bad chunks */ }
-      }
-    }
-  }
-
-  return fullText
-}
-
-export async function applyCoachSuggestions(
-  sessionId: string,
-  deckId: number,
-  acceptedCuts: string[],
-  acceptedAdds: string[]
-) {
-  return post<CoachApplyResult>('/api/coach/apply', {
-    session_id: sessionId,
-    deck_id: deckId,
-    accepted_cuts: acceptedCuts,
-    accepted_adds: acceptedAdds,
-  })
-}
-
-export async function searchCardsLike(card: string, colors?: string, topN = 10) {
-  const params: Record<string, string | number> = { card, top_n: topN }
-  if (colors) params.colors = colors
-  return get<{ query: string; results: CoachCardLikeResult[] }>('/api/coach/cards-like', params)
-}
-
-export async function generateReport(deckId?: number) {
-  return post<{ status: string; decksUpdated: string[]; count: number }>('/api/coach/reports/generate',
-    deckId ? { deck_id: deckId } : undefined
-  )
-}

frontend/commander-ai-lab-ui/src/api/collection.ts

@@ -1,86 +0,0 @@
-import { get, post, patch, postForm } from './client'
-import type { CollectionCard, CollectionFilters, SetInfo, ScanResult } from '../types'
-
-export async function searchCollection(filters: CollectionFilters) {
-  // Map frontend snake_case filter names to backend camelCase param names
-  const params: Record<string, string | number | boolean> = {}
-  if (filters.q) params.q = filters.q
-  if (filters.page) params.page = filters.page
-  if (filters.page_size) params.pageSize = filters.page_size
-  if (filters.sort_by) params.sortField = filters.sort_by
-  if (filters.sort_dir) params.sortDir = filters.sort_dir
-  if (filters.color) params.colors = filters.color
-  if (filters.type_line) params.types = filters.type_line
-  if (filters.rarity) params.rarity = filters.rarity
-  if (filters.set_code) params.setCode = filters.set_code
-  if (filters.cmc_min !== undefined) params.cmcMin = filters.cmc_min
-  if (filters.cmc_max !== undefined) params.cmcMax = filters.cmc_max
-  if (filters.price_min !== undefined) params.priceMin = filters.price_min
-  if (filters.price_max !== undefined) params.priceMax = filters.price_max
-  if (filters.owned_only !== undefined) params.owned_only = filters.owned_only
-
-  const res = await get<{ items?: CollectionCard[]; cards?: CollectionCard[]; total: number; page: number; pageSize?: number; page_size?: number }>(
-    '/api/collection', params
-  )
-  return {
-    cards: res.items || res.cards || [],
-    total: res.total || 0,
-    page: res.page || 1,
-    page_size: res.pageSize || res.page_size || 48,
-  }
-}
-
-export async function getCard(cardId: number) {
-  return get<CollectionCard>(`/api/collection/${cardId}`)
-}
-
-export async function updateCard(cardId: number, updates: Partial<CollectionCard>) {
-  return patch<CollectionCard>(`/api/collection/${cardId}`, updates)
-}
-
-export async function getSets() {
-  const res = await get<SetInfo[] | { sets: SetInfo[] }>('/api/collection/sets')
-  return Array.isArray(res) ? res : (res as { sets: SetInfo[] }).sets || []
-}
-
-export async function getKeywords() {
-  const res = await get<string[] | { keywords: string[] }>('/api/collection/keywords')
-  return Array.isArray(res) ? res : (res as { keywords: string[] }).keywords || []
-}
-
-export async function exportCollection(format: string = 'csv') {
-  const res = await fetch(`/api/collection/export?format=${format}`)
-  return res.blob()
-}
-
-export async function importCollection(file: File) {
-  const fd = new FormData()
-  fd.append('file', file)
-  return postForm<{ imported: number; errors: string[] }>('/api/collection/import', fd)
-}
-
-export async function scanCard(file: File) {
-  const fd = new FormData()
-  fd.append('image', file)
-  return postForm<ScanResult>('/api/collection/scan', fd)
-}
-
-export async function addScanResult(match: { name: string; set_code: string; scryfall_id: string; quantity?: number }) {
-  return post<{ success: boolean; card_id: number }>('/api/collection/scan/add', match)
-}
-
-export async function reEnrichCards() {
-  return post<{ updated: number }>('/api/collection/re-enrich')
-}
-
-export async function autoClassify(cardId: number) {
-  return post<{ classifications: string[] }>(`/api/collection/auto-classify`, { card_id: cardId })
-}
-
-export async function autoClassifyAll() {
-  return post<{ processed: number }>('/api/collection/auto-classify-all')
-}
-
-export async function getEdhrecData(cardId: number) {
-  return get<Record<string, unknown>>(`/api/collection/${cardId}/edhrec`)
-}

frontend/commander-ai-lab-ui/src/api/deckgen.ts

@@ -1,22 +0,0 @@
-import { get, post } from './client'
-import type { DeckGenV3Request, DeckGenV3Status, DeckGenV3Result, CommanderSearchResult } from '../types'
-
-export async function getV3Status() {
-  return get<DeckGenV3Status>('/api/deck/v3/status')
-}
-
-export async function searchCommanders(q: string) {
-  return get<CommanderSearchResult[]>('/api/deck-generator/commander-search', { q })
-}
-
-export async function generateDeckV3(req: DeckGenV3Request) {
-  return post<DeckGenV3Result>('/api/deck/v3/generate', req)
-}
-
-export async function commitDeckV3(req: DeckGenV3Request) {
-  return post<DeckGenV3Result & { deck_id: number; dck_path: string }>('/api/deck/v3/commit', req)
-}
-
-export async function exportDeckV3(format: 'csv' | 'dck' | 'moxfield' | 'shopping', req: DeckGenV3Request) {
-  return post<Record<string, unknown>>(`/api/deck/v3/export/${format}`, req)
-}

frontend/commander-ai-lab-ui/src/api/decks.ts

@@ -1,130 +0,0 @@
-import { get, post, put, del, patch } from './client'
-import type { Deck, DeckCard, DeckAnalysis, EdhRecsResponse, CollectionRecsResponse, PplxStatus } from '../types'
-
-export async function listDecks() {
-  const res = await get<{ decks: Record<string, unknown>[] } | Record<string, unknown>[]>('/api/decks')
-  const raw = Array.isArray(res) ? res : (res as { decks: Record<string, unknown>[] }).decks || []
-  return raw.map(d => ({
-    ...d,
-    commander: d.commander || d.commander_name || '',
-    card_count: d.card_count ?? d.total_cards ?? 0,
-    total_price: d.total_price ?? 0,
-    color_identity: d.color_identity || [],
-    created_date: d.created_date || d.created_at || '',
-    updated_date: d.updated_date || d.updated_at || '',
-  })) as Deck[]
-}
-
-export async function getDeck(deckId: number) {
-  return get<Deck>(`/api/decks/${deckId}`)
-}
-
-export async function createDeck(deck: { name: string; commander?: string; format?: string }) {
-  return post<Deck>('/api/decks', deck)
-}
-
-export async function updateDeck(deckId: number, updates: Partial<Deck>) {
-  return put<Deck>(`/api/decks/${deckId}`, updates)
-}
-
-export async function deleteDeck(deckId: number) {
-  return del<void>(`/api/decks/${deckId}`)
-}
-
-export async function deleteAllDecks() {
-  return del<void>('/api/decks')
-}
-
-export async function getDeckCards(deckId: number) {
-  const res = await get<{ cards: Record<string, unknown>[]; total: number } | Record<string, unknown>[]>(`/api/decks/${deckId}/cards`)
-  const raw = Array.isArray(res) ? res : (res as { cards: Record<string, unknown>[] }).cards || []
-  return raw.map(c => ({
-    ...c,
-    name: c.name || c.card_name || '',
-    category: c.category || c.role_tag || '',
-  })) as DeckCard[]
-}
-
-export async function addCardToDeck(deckId: number, card: { name: string; scryfall_id?: string; quantity?: number; category?: string }) {
-  return post<DeckCard>(`/api/decks/${deckId}/cards`, card)
-}
-
-export async function removeCardFromDeck(deckId: number, cardId: number) {
-  return del<void>(`/api/decks/${deckId}/cards/${cardId}`)
-}
-
-export async function updateDeckCard(deckId: number, cardId: number, updates: Partial<DeckCard>) {
-  return patch<DeckCard>(`/api/decks/${deckId}/cards/${cardId}`, updates)
-}
-
-export async function getDeckAnalysis(deckId: number) {
-  const raw = await get<Record<string, unknown>>(`/api/decks/${deckId}/analysis`)
-  // Backend returns: counts_by_type, targets, deltas, mana_curve, color_pips, total_cards, roles
-  // Frontend DeckAnalysis expects: card_count, land_count, creature_count, noncreature_count, avg_cmc, mana_curve, color_distribution, type_distribution, total_price, owned_count, missing_count
-  const counts = (raw.counts_by_type || {}) as Record<string, number>
-  const totalCards = (raw.total_cards as number) || 0
-  const landCount = counts['Land'] || 0
-  const creatureCount = counts['Creature'] || 0
-  const manaCurve = (raw.mana_curve || {}) as Record<string | number, number>
-  const colorPips = (raw.color_pips || {}) as Record<string, number>
-  // Compute avg CMC from mana curve
-  let totalMana = 0, nonLandCards = 0
-  for (const [cmc, count] of Object.entries(manaCurve)) {
-    const cmcNum = cmc === '6+' ? 6 : Number(cmc)
-    totalMana += cmcNum * count
-    nonLandCards += count
-  }
-  return {
-    card_count: totalCards,
-    land_count: landCount,
-    creature_count: creatureCount,
-    noncreature_count: totalCards - landCount - creatureCount,
-    avg_cmc: nonLandCards > 0 ? totalMana / nonLandCards : 0,
-    mana_curve: manaCurve as Record<number, number>,
-    color_distribution: colorPips,
-    type_distribution: counts,
-    total_price: 0,
-    owned_count: totalCards,
-    missing_count: 0,
-  } as DeckAnalysis
-}
-
-export async function getCollectionRecs(deckId: number) {
-  return get<CollectionRecsResponse>(`/api/decks/${deckId}/recommended-from-collection`)
-}
-
-export async function getEdhRecs(deckId: number, onlyOwned = false, maxResults = 30) {
-  return get<EdhRecsResponse>(`/api/decks/${deckId}/edh-recs?only_owned=${onlyOwned}&max_results=${maxResults}`)
-}
-
-export async function bulkAddCards(deckId: number, cards: { name: string; quantity?: number }[]) {
-  return post<{ added: number }>(`/api/decks/${deckId}/bulk-add`, { cards })
-}
-
-export async function bulkAddRecommended(deckId: number, cards: string[]) {
-  return post<{ added: number }>(`/api/decks/${deckId}/bulk-add-recommended`, { card_names: cards })
-}
-
-export async function exportDeckToSim(deckId: number) {
-  return post<{ path: string }>(`/api/decks/${deckId}/export-to-sim`)
-}
-
-export async function importDeckToDeck(deckId: number, data: { text?: string; url?: string }) {
-  return post<{ imported: number }>(`/api/decks/${deckId}/import`, data)
-}
-
-export async function importNewDeck(data: { text?: string; url?: string; name?: string }) {
-  return post<Deck>('/api/decks/import-new', data)
-}
-
-export async function getPplxStatus() {
-  return get<PplxStatus>('/api/pplx/status')
-}
-
-export async function deckResearch(payload: { commander: string; strategy?: string }) {
-  return post<{ research: string }>('/api/deck-research', payload)
-}
-
-export async function deckGenerate(payload: { commander: string; strategy?: string; bracket?: number }) {
-  return post<{ cards: Array<{ name: string; quantity: number; category: string }> }>('/api/deck-generate', payload)
-}

frontend/commander-ai-lab-ui/src/api/index.ts

@@ -1,7 +0,0 @@
-export * as collectionApi from './collection'
-export * as decksApi from './decks'
-export * as deckgenApi from './deckgen'
-export * as labApi from './lab'
-export * as simApi from './sim'
-export * as coachApi from './coach'
-export * as trainingApi from './training'

frontend/commander-ai-lab-ui/src/api/lab.ts

@@ -1,65 +0,0 @@
-import { get, post } from './client'
-import type { LabDeck, LabStatus, LabResult, LabHistoryEntry, PreconDeck } from '../types'
-
-export async function getLabDecks() {
-  const res = await get<{ decks: LabDeck[] } | LabDeck[]>('/api/lab/decks')
-  return Array.isArray(res) ? res : (res as { decks: LabDeck[] }).decks || []
-}
-
-export async function startBatchSim(config: { decks: string[]; games: number; threads?: number; use_deepseek?: boolean; deepseek_deck?: string }) {
-  return post<{ run_id: string }>('/api/lab/start', config)
-}
-
-export async function startDeepSeekSim(config: { decks: string[]; games: number; deepseek_deck: string }) {
-  return post<{ run_id: string }>('/api/lab/start-deepseek', config)
-}
-
-export async function getLabStatus() {
-  return get<LabStatus>('/api/lab/status')
-}
-
-export async function getLabResult() {
-  return get<LabResult>('/api/lab/result')
-}
-
-export async function getLabHistory() {
-  const res = await get<{ results: LabHistoryEntry[] } | LabHistoryEntry[]>('/api/lab/history')
-  return Array.isArray(res) ? res : (res as { results: LabHistoryEntry[] }).results || []
-}
-
-export async function getPrecons() {
-  const res = await get<{ precons: PreconDeck[] } | PreconDeck[]>('/api/lab/precons')
-  return Array.isArray(res) ? res : (res as { precons: PreconDeck[] }).precons || []
-}
-
-export async function installPrecon(name: string) {
-  return post<{ installed: boolean }>('/api/lab/precons/install', { name })
-}
-
-export async function installPreconBatch(names: string[]) {
-  return post<{ installed: number }>('/api/lab/precons/install-batch', { names })
-}
-
-export async function getMetaCommanders() {
-  return get<Array<{ name: string; color_identity: string[] }>>('/api/lab/meta/commanders')
-}
-
-export async function searchMetaCommanders(q: string) {
-  return get<Array<{ name: string; color_identity: string[]; source: string }>>('/api/lab/meta/search', { q })
-}
-
-export async function fetchMetaDeck(commander: string) {
-  return post<{ deck_name: string; cards: Array<{ name: string; quantity: number }> }>('/api/lab/meta/fetch', { commander })
-}
-
-export async function importDeckFromUrl(url: string) {
-  return post<{ deck_name: string }>('/api/lab/import/url', { url })
-}
-
-export async function importDeckFromText(text: string, name?: string) {
-  return post<{ deck_name: string }>('/api/lab/import/text', { text, name })
-}
-
-export async function getLabLog() {
-  return get<{ log: string }>('/api/lab/log')
-}

frontend/commander-ai-lab-ui/src/api/sim.ts

@@ -1,38 +0,0 @@
-import { get, post } from './client'
-import type { SimStatus, SimResult, DeepSeekStatus } from '../types'
-
-export async function runSim(config: { deck_a: string; deck_b: string; games: number }) {
-  return post<{ sim_id: string }>('/api/sim/run', config)
-}
-
-export async function runSimFromDeck(deckId: number, config: { opponent?: string; games?: number }) {
-  return post<{ sim_id: string }>('/api/sim/run-from-deck', { deck_id: deckId, ...config })
-}
-
-export async function runDeepSeekSim(config: { deck_a: string; deck_b: string; games: number; deepseek_deck: string }) {
-  return post<{ sim_id: string }>('/api/sim/run-deepseek', config)
-}
-
-export async function getSimStatus(simId: string) {
-  return get<SimStatus>('/api/sim/status', { simId })
-}
-
-export async function getSimResult(simId: string) {
-  return get<SimResult>('/api/sim/result', { simId })
-}
-
-export async function connectDeepSeek() {
-  return post<DeepSeekStatus>('/api/deepseek/connect')
-}
-
-export async function getDeepSeekStatus() {
-  return get<DeepSeekStatus>('/api/deepseek/status')
-}
-
-export async function configureDeepSeek(config: { model?: string; base_url?: string }) {
-  return post<DeepSeekStatus>('/api/deepseek/configure', config)
-}
-
-export async function getDeepSeekLogs() {
-  return get<Array<{ filename: string; size: number; modified: string }>>('/api/deepseek/logs')
-}

frontend/commander-ai-lab-ui/src/api/training.ts

@@ -1,92 +0,0 @@
-import { get, post } from './client'
-import type {
-  MLStatus, MLDataStatus, MLTrainStatus, PPOTrainStatus,
-  TournamentStatus, TournamentResults, MLModelInfo
-} from '../types'
-
-// ── ML Status & Toggle ──────────────────────────────────────
-export async function getMLStatus() {
-  return get<MLStatus>('/api/ml/status')
-}
-
-export async function toggleML(enable = true) {
-  return post<{ ml_logging_enabled: boolean; message: string }>(`/api/ml/toggle?enable=${enable}`)
-}
-
-// ── Data & Model Info ───────────────────────────────────────
-export async function getDataStatus() {
-  return get<MLDataStatus>('/api/ml/data/status')
-}
-
-export async function getModelInfo() {
-  return get<MLModelInfo>('/api/ml/model')
-}
-
-export async function reloadModel(checkpoint?: string) {
-  return post<{ success: boolean; status: MLModelInfo }>('/api/ml/reload', checkpoint ? { checkpoint } : undefined)
-}
-
-// ── Supervised Training ─────────────────────────────────────
-export async function startTraining(config: {
-  epochs?: number
-  lr?: number
-  batchSize?: number
-  patience?: number
-  rebuildDataset?: boolean
-}) {
-  return post<{ status: string; config: Record<string, unknown> }>('/api/ml/train', config)
-}
-
-export async function getTrainStatus() {
-  return get<MLTrainStatus>('/api/ml/train/status')
-}
-
-// ── PPO Training ────────────────────────────────────────────
-export async function startPPOTraining(config: {
-  iterations?: number
-  episodesPerIter?: number
-  ppoEpochs?: number
-  batchSize?: number
-  lr?: number
-  clipEpsilon?: number
-  entropyCoeff?: number
-  opponent?: string
-  playstyle?: string
-  loadSupervised?: string
-}) {
-  return post<{ status: string; iterations: number }>('/api/ml/train/ppo', config)
-}
-
-export async function getPPOStatus() {
-  return get<PPOTrainStatus>('/api/ml/train/ppo/status')
-}
-
-// ── Tournament ──────────────────────────────────────────────
-export async function startTournament(config: {
-  episodes?: number
-  playstyle?: string
-}) {
-  return post<{ status: string; episodes: number }>('/api/ml/tournament', config)
-}
-
-export async function getTournamentStatus() {
-  return get<TournamentStatus>('/api/ml/tournament/status')
-}
-
-export async function getTournamentResults() {
-  return get<TournamentResults>('/api/ml/tournament/results')
-}
-
-// ── Decision Files ──────────────────────────────────────────
-export async function getDecisionFile(filename: string, limit = 100, offset = 0) {
-  return get<{ file: string; offset: number; limit: number; count: number; decisions: Record<string, unknown>[] }>(
-    `/api/ml/decisions/${filename}?limit=${limit}&offset=${offset}`
-  )
-}
-
-// ── Prediction ──────────────────────────────────────────────
-export async function predict(state: Record<string, unknown>) {
-  return post<{ action: string; action_index: number; confidence: number; probabilities: Record<string, number>; inference_ms: number }>(
-    '/api/ml/predict', state
-  )
-}

frontend/commander-ai-lab-ui/src/components/common/CardImage.tsx

@@ -1,49 +0,0 @@
-import { useState } from 'react'
-
-interface CardImageProps {
-  src: string
-  alt: string
-  size?: 'sm' | 'md' | 'lg' | 'xl'
-  className?: string
-  onClick?: () => void
-}
-
-const SIZES = {
-  sm: 'w-16 h-[22px]',    // tiny inline
-  md: 'w-[146px] h-[204px]',  // grid thumbnail
-  lg: 'w-[244px] h-[340px]',  // detail view
-  xl: 'w-[336px] h-[468px]',  // full size
-}
-
-export function CardImage({ src, alt, size = 'md', className = '', onClick }: CardImageProps) {
-  const [loaded, setLoaded] = useState(false)
-  const [error, setError] = useState(false)
-
-  // Build Scryfall URL if needed — ensure we get the right size
-  const imgUrl = src || ''
-
-  return (
-    <div
-      className={`relative overflow-hidden rounded-lg bg-bg-tertiary ${SIZES[size]} ${onClick ? 'cursor-pointer hover:ring-2 hover:ring-accent-blue/50 transition-all' : ''} ${className}`}
-      onClick={onClick}
-    >
-      {!error ? (
-        <img
-          src={imgUrl}
-          alt={alt}
-          className={`w-full h-full object-cover transition-opacity duration-200 ${loaded ? 'opacity-100' : 'opacity-0'}`}
-          onLoad={() => setLoaded(true)}
-          onError={() => setError(true)}
-          loading="lazy"
-        />
-      ) : (
-        <div className="flex items-center justify-center w-full h-full text-text-tertiary text-xs text-center p-2">
-          {alt}
-        </div>
-      )}
-      {!loaded && !error && (
-        <div className="absolute inset-0 bg-bg-tertiary animate-pulse" />
-      )}
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/components/common/EmptyState.tsx

@@ -1,19 +0,0 @@
-import type { LucideIcon } from 'lucide-react'
-
-interface EmptyStateProps {
-  icon: LucideIcon
-  title: string
-  description?: string
-  action?: React.ReactNode
-}
-
-export function EmptyState({ icon: Icon, title, description, action }: EmptyStateProps) {
-  return (
-    <div className="flex flex-col items-center justify-center py-16 text-center">
-      <Icon className="w-12 h-12 text-text-tertiary mb-4" strokeWidth={1.5} />
-      <h3 className="text-lg font-semibold text-text-primary mb-1">{title}</h3>
-      {description && <p className="text-sm text-text-secondary max-w-md mb-4">{description}</p>}
-      {action}
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/components/common/ManaSymbols.tsx

@@ -1,69 +0,0 @@
-// Parse MTG mana cost strings like "{2}{W}{U}" into colored symbols
-
-const MANA_COLORS: Record<string, string> = {
-  W: 'bg-mana-white text-black',
-  U: 'bg-mana-blue text-white',
-  B: 'bg-mana-black text-white',
-  R: 'bg-mana-red text-white',
-  G: 'bg-mana-green text-white',
-  C: 'bg-mana-colorless text-white',
-}
-
-interface ManaSymbolsProps {
-  cost: string
-  size?: 'sm' | 'md'
-}
-
-export function ManaSymbols({ cost, size = 'sm' }: ManaSymbolsProps) {
-  if (!cost) return null
-
-  const symbols = cost.match(/\{([^}]+)\}/g)
-  if (!symbols) return <span className="text-text-tertiary">{cost}</span>
-
-  const sz = size === 'sm' ? 'w-5 h-5 text-[10px]' : 'w-6 h-6 text-xs'
-
-  return (
-    <span className="inline-flex items-center gap-0.5">
-      {symbols.map((s, i) => {
-        const val = s.replace(/[{}]/g, '')
-        const colorClass = MANA_COLORS[val] || 'bg-mana-colorless text-white'
-        return (
-          <span
-            key={i}
-            className={`${sz} inline-flex items-center justify-center rounded-full font-bold ${colorClass}`}
-          >
-            {val}
-          </span>
-        )
-      })}
-    </span>
-  )
-}
-
-// Color identity dots
-interface ColorDotsProps {
-  colors: string[]
-  size?: 'sm' | 'md'
-}
-
-export function ColorDots({ colors, size = 'sm' }: ColorDotsProps) {
-  if (!colors || colors.length === 0) return <span className="text-text-tertiary text-xs">Colorless</span>
-
-  const sz = size === 'sm' ? 'w-3 h-3' : 'w-4 h-4'
-
-  const DOT_COLORS: Record<string, string> = {
-    W: 'bg-mana-white',
-    U: 'bg-mana-blue',
-    B: 'bg-mana-black border border-border-secondary',
-    R: 'bg-mana-red',
-    G: 'bg-mana-green',
-  }
-
-  return (
-    <span className="inline-flex items-center gap-0.5">
-      {colors.map(c => (
-        <span key={c} className={`${sz} rounded-full ${DOT_COLORS[c] || 'bg-mana-colorless'}`} />
-      ))}
-    </span>
-  )
-}

frontend/commander-ai-lab-ui/src/components/common/Spinner.tsx

@@ -1,38 +0,0 @@
-interface SpinnerProps {
-  size?: 'sm' | 'md' | 'lg'
-  className?: string
-}
-
-const SIZES = { sm: 'w-4 h-4', md: 'w-6 h-6', lg: 'w-8 h-8' }
-
-export function Spinner({ size = 'md', className = '' }: SpinnerProps) {
-  return (
-    <svg
-      className={`animate-spin ${SIZES[size]} ${className}`}
-      viewBox="0 0 24 24"
-      fill="none"
-    >
-      <circle
-        cx="12" cy="12" r="10"
-        stroke="currentColor"
-        strokeWidth="3"
-        strokeLinecap="round"
-        className="opacity-20"
-      />
-      <path
-        d="M12 2a10 10 0 0 1 10 10"
-        stroke="currentColor"
-        strokeWidth="3"
-        strokeLinecap="round"
-      />
-    </svg>
-  )
-}
-
-export function PageSpinner() {
-  return (
-    <div className="flex items-center justify-center h-64">
-      <Spinner size="lg" className="text-accent-blue" />
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/components/common/StatusBadge.tsx

@@ -1,35 +0,0 @@
-import { CheckCircle, XCircle, AlertTriangle, Info } from 'lucide-react'
-
-type Variant = 'success' | 'error' | 'warning' | 'info' | 'neutral'
-
-interface StatusBadgeProps {
-  variant: Variant
-  label: string
-  className?: string
-}
-
-const STYLES: Record<Variant, string> = {
-  success: 'bg-status-success/15 text-status-success border-status-success/30',
-  error: 'bg-status-error/15 text-status-error border-status-error/30',
-  warning: 'bg-status-warning/15 text-status-warning border-status-warning/30',
-  info: 'bg-status-info/15 text-status-info border-status-info/30',
-  neutral: 'bg-bg-tertiary text-text-secondary border-border-primary',
-}
-
-const ICONS: Record<Variant, typeof CheckCircle> = {
-  success: CheckCircle,
-  error: XCircle,
-  warning: AlertTriangle,
-  info: Info,
-  neutral: Info,
-}
-
-export function StatusBadge({ variant, label, className = '' }: StatusBadgeProps) {
-  const Icon = ICONS[variant]
-  return (
-    <span className={`inline-flex items-center gap-1.5 px-2.5 py-1 text-xs font-medium rounded-md border ${STYLES[variant]} ${className}`}>
-      <Icon className="w-3.5 h-3.5" />
-      {label}
-    </span>
-  )
-}

frontend/commander-ai-lab-ui/src/components/common/index.ts

@@ -1,5 +0,0 @@
-export { Spinner, PageSpinner } from './Spinner'
-export { StatusBadge } from './StatusBadge'
-export { CardImage } from './CardImage'
-export { ManaSymbols, ColorDots } from './ManaSymbols'
-export { EmptyState } from './EmptyState'

frontend/commander-ai-lab-ui/src/components/layout/PageLayout.tsx

@@ -1,16 +0,0 @@
-import { Sidebar } from './Sidebar'
-
-interface PageLayoutProps {
-  children: React.ReactNode
-}
-
-export function PageLayout({ children }: PageLayoutProps) {
-  return (
-    <div className="min-h-screen bg-bg-primary">
-      <Sidebar />
-      <main className="ml-56 min-h-screen">
-        {children}
-      </main>
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/components/layout/Sidebar.tsx

@@ -1,51 +0,0 @@
-import { NavLink } from 'react-router-dom'
-
-const NAV_ITEMS = [
-  { to: '/',           label: 'Batch Sim',   icon: '⚗️' },
-  { to: '/collection', label: 'Collection',  icon: '📦' },
-  { to: '/decks',      label: 'Decks',       icon: '🃏' },
-  { to: '/autogen',    label: 'Auto Gen',    icon: '⚡' },
-  { to: '/simulator',  label: 'Simulator',   icon: '🎮' },
-  { to: '/coach',      label: 'Coach',       icon: '🧠' },
-  { to: '/training',   label: 'Training',    icon: '📈' },
-]
-
-export function Sidebar() {
-  return (
-    <aside className="fixed left-0 top-0 bottom-0 w-56 bg-bg-secondary border-r border-border-primary flex flex-col z-30">
-      {/* Logo */}
-      <div className="px-5 py-5 border-b border-border-primary">
-        <h1 className="text-base font-bold text-text-primary tracking-tight">
-          Commander AI Lab
-        </h1>
-        <p className="text-xs text-text-tertiary mt-0.5">MTG Intelligence Platform</p>
-      </div>
-
-      {/* Nav */}
-      <nav className="flex-1 py-3 overflow-y-auto">
-        {NAV_ITEMS.map(item => (
-          <NavLink
-            key={item.to}
-            to={item.to}
-            end={item.to === '/'}
-            className={({ isActive }) =>
-              `flex items-center gap-3 px-5 py-2.5 text-sm transition-colors duration-150 ${
-                isActive
-                  ? 'bg-accent-blue/10 text-accent-blue border-r-2 border-accent-blue'
-                  : 'text-text-secondary hover:text-text-primary hover:bg-bg-hover'
-              }`
-            }
-          >
-            <span className="text-base">{item.icon}</span>
-            <span>{item.label}</span>
-          </NavLink>
-        ))}
-      </nav>
-
-      {/* Footer */}
-      <div className="px-5 py-4 border-t border-border-primary">
-        <p className="text-xs text-text-tertiary">v4.0 — React + TypeScript</p>
-      </div>
-    </aside>
-  )
-}

frontend/commander-ai-lab-ui/src/hooks/usePolling.ts

@@ -1,13 +0,0 @@
-import { useEffect, useRef } from 'react'
-
-/** Polls a function at the given interval while `enabled` is true */
-export function usePolling(fn: () => void, intervalMs: number, enabled: boolean) {
-  const savedFn = useRef(fn)
-  savedFn.current = fn
-
-  useEffect(() => {
-    if (!enabled) return
-    const id = setInterval(() => savedFn.current(), intervalMs)
-    return () => clearInterval(id)
-  }, [intervalMs, enabled])
-}

frontend/commander-ai-lab-ui/src/index.css

@@ -1,114 +0,0 @@
-@import "tailwindcss";
-
-/* ═══════════════════════════════════════════════════════════
-   Commander AI Lab — Design Tokens (Tailwind v4 CSS Theme)
-   Fresh dark theme with MTG-inspired accents
-   ═══════════════════════════════════════════════════════════ */
-
-@theme {
-  /* ── Backgrounds ── */
-  --color-bg-primary: #0f1117;
-  --color-bg-secondary: #161921;
-  --color-bg-tertiary: #1c2030;
-  --color-bg-elevated: #222738;
-  --color-bg-hover: #2a3048;
-
-  /* ── Borders ── */
-  --color-border-primary: #2a2f42;
-  --color-border-secondary: #363c54;
-  --color-border-accent: #4f6ef7;
-
-  /* ── Text ── */
-  --color-text-primary: #e8eaf0;
-  --color-text-secondary: #9ba1b8;
-  --color-text-tertiary: #6b7190;
-  --color-text-inverse: #0f1117;
-
-  /* ── Accents ── */
-  --color-accent-blue: #4f6ef7;
-  --color-accent-blue-hover: #6b84ff;
-  --color-accent-teal: #2dd4bf;
-  --color-accent-teal-hover: #5eead4;
-  --color-accent-purple: #a78bfa;
-  --color-accent-amber: #fbbf24;
-  --color-accent-red: #f87171;
-  --color-accent-green: #4ade80;
-
-  /* ── MTG Mana Colors ── */
-  --color-mana-white: #f9faf4;
-  --color-mana-blue: #0e67ab;
-  --color-mana-black: #2b2424;
-  --color-mana-red: #d3202a;
-  --color-mana-green: #00733e;
-  --color-mana-colorless: #706f6f;
-
-  /* ── Status ── */
-  --color-status-success: #4ade80;
-  --color-status-warning: #fbbf24;
-  --color-status-error: #f87171;
-  --color-status-info: #60a5fa;
-
-  /* ── Radius ── */
-  --radius-sm: 0.375rem;
-  --radius-md: 0.5rem;
-  --radius-lg: 0.75rem;
-  --radius-xl: 1rem;
-
-  /* ── Shadows ── */
-  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
-  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.4);
-  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.5);
-  --shadow-glow-blue: 0 0 20px rgba(79, 110, 247, 0.15);
-  --shadow-glow-teal: 0 0 20px rgba(45, 212, 191, 0.15);
-}
-
-/* ── Base Styles ── */
-html {
-  background-color: var(--color-bg-primary);
-  color: var(--color-text-primary);
-}
-
-body {
-  font-family: 'Inter', system-ui, -apple-system, sans-serif;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-
-/* ── Scrollbar ── */
-::-webkit-scrollbar {
-  width: 8px;
-  height: 8px;
-}
-::-webkit-scrollbar-track {
-  background: var(--color-bg-secondary);
-}
-::-webkit-scrollbar-thumb {
-  background: var(--color-border-secondary);
-  border-radius: 4px;
-}
-::-webkit-scrollbar-thumb:hover {
-  background: var(--color-text-tertiary);
-}
-
-/* ── Utility animations ── */
-@keyframes fade-in {
-  from { opacity: 0; transform: translateY(4px); }
-  to { opacity: 1; transform: translateY(0); }
-}
-@keyframes pulse-glow {
-  0%, 100% { box-shadow: 0 0 0 0 rgba(79, 110, 247, 0.2); }
-  50% { box-shadow: 0 0 16px 4px rgba(79, 110, 247, 0.15); }
-}
-@keyframes spin {
-  to { transform: rotate(360deg); }
-}
-
-.animate-fade-in {
-  animation: fade-in 0.2s ease-out;
-}
-.animate-pulse-glow {
-  animation: pulse-glow 2s infinite;
-}
-.animate-spin {
-  animation: spin 1s linear infinite;
-}

frontend/commander-ai-lab-ui/src/main.tsx

@@ -1,10 +0,0 @@
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-import './index.css'
-import App from './App.tsx'
-
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <App />
-  </StrictMode>,
-)

frontend/commander-ai-lab-ui/src/pages/AutoGenPage.tsx

@@ -1,436 +0,0 @@
-import { useState, useEffect, useRef } from 'react'
-import {
-  Search, Wand2, Save, AlertCircle,
-  ChevronDown, Sparkles, RefreshCw, Check
-} from 'lucide-react'
-import { Spinner, StatusBadge, ManaSymbols, CardImage, ColorDots } from '../components/common'
-import { deckgenApi } from '../api'
-import type { DeckGenV3Status, DeckGenV3Result, DeckGenV3Card, CommanderSearchResult } from '../types'
-import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer, Cell } from 'recharts'
-
-// ── Commander Search ──────────────────────────────────────────
-function CommanderSearch({ onSelect }: { onSelect: (c: CommanderSearchResult) => void }) {
-  const [query, setQuery] = useState('')
-  const [results, setResults] = useState<CommanderSearchResult[]>([])
-  const [searching, setSearching] = useState(false)
-  const debounceRef = useRef<ReturnType<typeof setTimeout>>(undefined)
-
-  function handleSearch(q: string) {
-    setQuery(q)
-    clearTimeout(debounceRef.current)
-    if (q.length < 2) { setResults([]); return }
-    debounceRef.current = setTimeout(async () => {
-      setSearching(true)
-      try {
-        const r = await deckgenApi.searchCommanders(q)
-        setResults(r)
-      } catch { setResults([]) }
-      setSearching(false)
-    }, 300)
-  }
-
-  return (
-    <div className="relative">
-      <div className="relative">
-        <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-text-tertiary" />
-        <input
-          type="text"
-          placeholder="Search for a commander..."
-          value={query}
-          onChange={e => handleSearch(e.target.value)}
-          className="w-full pl-10 pr-4 py-3 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 focus:ring-1 focus:ring-accent-blue/30 transition-all"
-        />
-        {searching && <Spinner size="sm" className="absolute right-3 top-1/2 -translate-y-1/2 text-accent-blue" />}
-      </div>
-      {results.length > 0 && (
-        <div className="absolute z-20 top-full mt-1 w-full bg-bg-elevated border border-border-primary rounded-xl shadow-lg max-h-80 overflow-y-auto">
-          {results.map(c => (
-            <button
-              key={c.scryfall_id}
-              onClick={() => { onSelect(c); setQuery(c.name); setResults([]) }}
-              className="w-full flex items-center gap-3 px-4 py-3 hover:bg-bg-hover text-left transition-colors"
-            >
-              <CardImage src={c.image_url} alt={c.name} size="sm" />
-              <div className="flex-1 min-w-0">
-                <p className="text-sm font-medium text-text-primary truncate">{c.name}</p>
-                <p className="text-xs text-text-secondary truncate">{c.type_line}</p>
-              </div>
-              <ColorDots colors={c.color_identity} />
-              {c.in_collection && (
-                <span className="text-[10px] px-1.5 py-0.5 bg-accent-green/15 text-accent-green rounded">Owned</span>
-              )}
-            </button>
-          ))}
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ── Generated Deck View ───────────────────────────────────────
-function GeneratedDeckView({ result, onCommit }: { result: DeckGenV3Result; onCommit: () => void }) {
-  const [view, setView] = useState<'visual' | 'list'>('visual')
-  const [committing, setCommitting] = useState(false)
-  const [selectedCard, setSelectedCard] = useState<DeckGenV3Card | null>(null)
-
-  // Group by category
-  const grouped = result.cards.reduce<Record<string, DeckGenV3Card[]>>((acc, c) => {
-    const cat = c.category || 'Other'
-    if (!acc[cat]) acc[cat] = []
-    acc[cat].push(c)
-    return acc
-  }, {})
-
-  const curveData = Object.entries(result.stats.mana_curve)
-    .map(([cmc, count]) => ({ cmc: cmc === '7' ? '7+' : cmc, count }))
-    .sort((a, b) => Number(a.cmc) - Number(b.cmc))
-
-  async function handleCommit() {
-    setCommitting(true)
-    try { onCommit() } catch { /* ignore */ }
-    setCommitting(false)
-  }
-
-  return (
-    <div className="space-y-5 animate-fade-in">
-      {/* Commander header */}
-      <div className="flex gap-5 bg-bg-secondary rounded-xl border border-border-primary p-5">
-        <CardImage src={result.commander.image_url} alt={result.commander.name} size="lg" />
-        <div className="flex-1 space-y-3">
-          <div>
-            <h2 className="text-xl font-bold text-text-primary">{result.commander.name}</h2>
-            <p className="text-sm text-text-secondary">{result.commander.type_line}</p>
-            <div className="flex items-center gap-3 mt-2">
-              <ManaSymbols cost={result.commander.mana_cost} size="md" />
-              <ColorDots colors={result.commander.color_identity} size="md" />
-            </div>
-          </div>
-          <p className="text-sm text-text-primary whitespace-pre-wrap">{result.commander.oracle_text}</p>
-          <div className="flex items-center gap-4 text-xs text-text-secondary">
-            <span>Strategy: <span className="text-accent-blue font-medium">{result.strategy}</span></span>
-            <span>Bracket: <span className="text-accent-amber font-medium">{result.bracket}</span></span>
-            <span>Model: <span className="text-accent-purple font-medium">{result.model}</span></span>
-          </div>
-          {result.substitution && (
-            <div className="flex items-center gap-3 text-xs">
-              <span className="text-accent-green">{result.substitution.owned} owned</span>
-              <span className="text-accent-amber">{result.substitution.substituted} substituted</span>
-              <span className="text-accent-red">{result.substitution.missing} missing</span>
-            </div>
-          )}
-        </div>
-      </div>
-
-      {/* Actions */}
-      <div className="flex items-center gap-3">
-        <button onClick={handleCommit} disabled={committing}
-          className="flex items-center gap-2 px-4 py-2.5 bg-accent-green/15 text-accent-green text-sm font-medium rounded-lg hover:bg-accent-green/25 border border-accent-green/30 transition-colors disabled:opacity-50">
-          {committing ? <Spinner size="sm" /> : <Save className="w-4 h-4" />}
-          Save to Decks
-        </button>
-        <div className="flex items-center gap-1 bg-bg-secondary rounded-lg border border-border-primary p-0.5">
-          <button onClick={() => setView('visual')}
-            className={`px-3 py-1.5 text-xs font-medium rounded-md transition-colors ${view === 'visual' ? 'bg-bg-hover text-text-primary' : 'text-text-tertiary hover:text-text-secondary'}`}>
-            Visual
-          </button>
-          <button onClick={() => setView('list')}
-            className={`px-3 py-1.5 text-xs font-medium rounded-md transition-colors ${view === 'list' ? 'bg-bg-hover text-text-primary' : 'text-text-tertiary hover:text-text-secondary'}`}>
-            List
-          </button>
-        </div>
-        {/* Stats summary */}
-        <div className="flex-1" />
-        <span className="text-xs text-text-tertiary">{result.stats.card_count} cards</span>
-        <span className="text-xs text-accent-teal font-medium">${result.stats.total_price.toFixed(2)}</span>
-      </div>
-
-      {/* Mana curve mini */}
-      <div className="bg-bg-secondary rounded-xl border border-border-primary p-4">
-        <h4 className="text-xs font-semibold text-text-tertiary uppercase tracking-wider mb-2">Mana Curve</h4>
-        <div className="h-28">
-          <ResponsiveContainer width="100%" height="100%">
-            <BarChart data={curveData} barSize={20}>
-              <XAxis dataKey="cmc" axisLine={false} tickLine={false} tick={{ fill: '#6b7190', fontSize: 10 }} />
-              <YAxis hide />
-              <Tooltip contentStyle={{ backgroundColor: '#1c2030', border: '1px solid #2a2f42', borderRadius: 8, fontSize: 11 }} />
-              <Bar dataKey="count" radius={[3, 3, 0, 0]}>
-                {curveData.map((_, i) => <Cell key={i} fill="#4f6ef7" fillOpacity={0.8} />)}
-              </Bar>
-            </BarChart>
-          </ResponsiveContainer>
-        </div>
-      </div>
-
-      {/* Card grid/list */}
-      {view === 'visual' ? (
-        <div className="space-y-5">
-          {Object.entries(grouped).map(([cat, cards]) => (
-            <div key={cat}>
-              <h4 className="text-xs font-semibold text-text-tertiary uppercase tracking-wider mb-3">{cat} ({cards.length})</h4>
-              <div className="grid grid-cols-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 xl:grid-cols-8 gap-2">
-                {cards.map(card => (
-                  <div key={card.name} className="group cursor-pointer relative" onClick={() => setSelectedCard(card)}>
-                    <CardImage src={card.image_url} alt={card.name} size="md" className="w-full h-auto aspect-[5/7]" />
-                    {card.is_substitute && (
-                      <div className="absolute top-1 right-1 w-4 h-4 bg-accent-amber rounded-full flex items-center justify-center">
-                        <RefreshCw className="w-2.5 h-2.5 text-bg-primary" />
-                      </div>
-                    )}
-                    {card.owned && (
-                      <div className="absolute top-1 left-1 w-4 h-4 bg-accent-green rounded-full flex items-center justify-center">
-                        <Check className="w-2.5 h-2.5 text-bg-primary" />
-                      </div>
-                    )}
-                  </div>
-                ))}
-              </div>
-            </div>
-          ))}
-        </div>
-      ) : (
-        <div className="bg-bg-secondary rounded-xl border border-border-primary overflow-hidden">
-          <table className="w-full text-sm">
-            <thead>
-              <tr className="border-b border-border-primary text-left">
-                <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Card</th>
-                <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Category</th>
-                <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Role</th>
-                <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Mana</th>
-                <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider text-right">Price</th>
-                <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Status</th>
-              </tr>
-            </thead>
-            <tbody className="divide-y divide-border-primary">
-              {result.cards.map(card => (
-                <tr key={card.name} className="hover:bg-bg-hover transition-colors">
-                  <td className="px-4 py-2.5">
-                    <span className="font-medium text-text-primary">{card.quantity}x {card.name}</span>
-                    {card.is_substitute && (
-                      <span className="ml-2 text-[10px] text-accent-amber">sub for {card.original_name}</span>
-                    )}
-                  </td>
-                  <td className="px-4 py-2.5 text-xs text-text-secondary">{card.category}</td>
-                  <td className="px-4 py-2.5 text-xs text-text-secondary">{card.role}</td>
-                  <td className="px-4 py-2.5"><ManaSymbols cost={card.mana_cost} /></td>
-                  <td className="px-4 py-2.5 text-right text-accent-teal text-xs">{card.tcg_price != null ? `$${card.tcg_price.toFixed(2)}` : '—'}</td>
-                  <td className="px-4 py-2.5">
-                    <span className={`text-[10px] px-2 py-0.5 rounded ${card.owned ? 'bg-accent-green/15 text-accent-green' : 'bg-bg-tertiary text-text-tertiary'}`}>
-                      {card.owned ? `Owned (${card.owned_qty})` : 'Missing'}
-                    </span>
-                  </td>
-                </tr>
-              ))}
-            </tbody>
-          </table>
-        </div>
-      )}
-
-      {/* Card detail popup */}
-      {selectedCard && (
-        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm" onClick={() => setSelectedCard(null)}>
-          <div className="bg-bg-secondary rounded-xl border border-border-primary shadow-lg max-w-2xl w-full mx-4 p-6 animate-fade-in" onClick={e => e.stopPropagation()}>
-            <div className="flex gap-5">
-              <CardImage src={selectedCard.image_url} alt={selectedCard.name} size="lg" />
-              <div className="flex-1 space-y-3">
-                <h3 className="text-lg font-bold text-text-primary">{selectedCard.name}</h3>
-                <p className="text-sm text-text-secondary">{selectedCard.type_line}</p>
-                <ManaSymbols cost={selectedCard.mana_cost} size="md" />
-                <p className="text-sm text-text-primary whitespace-pre-wrap">{selectedCard.reason}</p>
-                <div className="flex items-center gap-3 text-xs">
-                  <span className="text-text-tertiary">Role: <span className="text-accent-blue">{selectedCard.role}</span></span>
-                  {selectedCard.is_substitute && (
-                    <span className="text-accent-amber">Substituted for {selectedCard.original_name} ({(selectedCard.similarity_score ?? 0 * 100).toFixed(0)}%)</span>
-                  )}
-                </div>
-              </div>
-            </div>
-          </div>
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ── Main Auto Gen Page ────────────────────────────────────────
-export function AutoGenPage() {
-  const [status, setStatus] = useState<DeckGenV3Status | null>(null)
-  const [loading, setLoading] = useState(true)
-  const [generating, setGenerating] = useState(false)
-  const [result, setResult] = useState<DeckGenV3Result | null>(null)
-  const [commander, setCommander] = useState<CommanderSearchResult | null>(null)
-  const [strategy, setStrategy] = useState('')
-  const [bracket, setBracket] = useState(3)
-  const [budget, setBudget] = useState<string>('')
-  const [useCollection, setUseCollection] = useState(true)
-  const [runSub, setRunSub] = useState(true)
-  const [error, setError] = useState<string | null>(null)
-
-  useEffect(() => {
-    deckgenApi.getV3Status().then(s => { setStatus(s); setLoading(false) }).catch(() => setLoading(false))
-  }, [])
-
-  async function handleGenerate() {
-    if (!commander) return
-    setGenerating(true)
-    setError(null)
-    setResult(null)
-    try {
-      const res = await deckgenApi.generateDeckV3({
-        commander_name: commander.name,
-        strategy: strategy || undefined,
-        target_bracket: bracket,
-        budget_usd: budget ? Number(budget) : undefined,
-        use_collection: useCollection,
-        run_substitution: runSub,
-      })
-      setResult(res)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Generation failed')
-    }
-    setGenerating(false)
-  }
-
-  async function handleCommit() {
-    if (!commander || !result) return
-    try {
-      await deckgenApi.commitDeckV3({
-        commander_name: commander.name,
-        strategy: strategy || undefined,
-        target_bracket: bracket,
-        budget_usd: budget ? Number(budget) : undefined,
-        use_collection: useCollection,
-        run_substitution: runSub,
-      })
-    } catch { /* ignore */ }
-  }
-
-  if (loading) {
-    return <div className="p-6 flex items-center justify-center h-64"><Spinner size="lg" className="text-accent-blue" /></div>
-  }
-
-  return (
-    <div className="p-6 space-y-5">
-      <div>
-        <h1 className="text-2xl font-bold text-text-primary flex items-center gap-3">
-          <Sparkles className="w-6 h-6 text-accent-purple" />
-          Auto Gen V3
-        </h1>
-        <p className="text-sm text-text-secondary mt-0.5">AI-powered deck generation with Perplexity</p>
-      </div>
-
-      {/* Status bar */}
-      <div className="flex items-center gap-3">
-        <StatusBadge
-          variant={status?.initialized ? 'success' : 'error'}
-          label={status?.initialized ? 'Ready' : 'Not Initialized'}
-        />
-        <StatusBadge
-          variant={status?.pplx_configured ? 'success' : 'warning'}
-          label={status?.pplx_configured ? 'Perplexity Connected' : 'Perplexity Not Set'}
-        />
-        {status?.embeddings_loaded && (
-          <StatusBadge variant="info" label={`${status.embedding_cards.toLocaleString()} embeddings`} />
-        )}
-      </div>
-
-      {!result ? (
-        /* Config form */
-        <div className="max-w-2xl space-y-5">
-          <div>
-            <label className="text-sm font-medium text-text-primary block mb-2">Commander</label>
-            <CommanderSearch onSelect={setCommander} />
-            {commander && (
-              <div className="mt-2 flex items-center gap-3 p-3 bg-bg-secondary rounded-lg border border-border-primary">
-                <CardImage src={commander.image_url} alt={commander.name} size="sm" />
-                <div>
-                  <p className="text-sm font-medium text-text-primary">{commander.name}</p>
-                  <p className="text-xs text-text-secondary">{commander.type_line}</p>
-                </div>
-                <ColorDots colors={commander.color_identity} />
-              </div>
-            )}
-          </div>
-
-          <div>
-            <label className="text-sm font-medium text-text-primary block mb-2">Strategy (optional)</label>
-            <input
-              type="text"
-              placeholder="e.g. Voltron, Aristocrats, Storm..."
-              value={strategy}
-              onChange={e => setStrategy(e.target.value)}
-              className="w-full px-4 py-3 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-            />
-          </div>
-
-          <div className="grid grid-cols-2 gap-4">
-            <div>
-              <label className="text-sm font-medium text-text-primary block mb-2">Target Bracket</label>
-              <select
-                value={bracket}
-                onChange={e => setBracket(Number(e.target.value))}
-                className="w-full px-4 py-3 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all"
-              >
-                <option value={1}>1 — Casual</option>
-                <option value={2}>2 — Low Power</option>
-                <option value={3}>3 — Mid Power</option>
-                <option value={4}>4 — High Power</option>
-              </select>
-            </div>
-            <div>
-              <label className="text-sm font-medium text-text-primary block mb-2">Budget (USD, optional)</label>
-              <input
-                type="number"
-                placeholder="No limit"
-                value={budget}
-                onChange={e => setBudget(e.target.value)}
-                className="w-full px-4 py-3 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-              />
-            </div>
-          </div>
-
-          <div className="flex items-center gap-6">
-            <label className="flex items-center gap-2 cursor-pointer">
-              <input type="checkbox" checked={useCollection} onChange={e => setUseCollection(e.target.checked)}
-                className="w-4 h-4 rounded border-border-primary bg-bg-tertiary text-accent-blue focus:ring-accent-blue/30" />
-              <span className="text-sm text-text-secondary">Use collection cards</span>
-            </label>
-            <label className="flex items-center gap-2 cursor-pointer">
-              <input type="checkbox" checked={runSub} onChange={e => setRunSub(e.target.checked)}
-                className="w-4 h-4 rounded border-border-primary bg-bg-tertiary text-accent-blue focus:ring-accent-blue/30" />
-              <span className="text-sm text-text-secondary">Run substitution pass</span>
-            </label>
-          </div>
-
-          {error && (
-            <div className="flex items-center gap-2 px-4 py-3 bg-status-error/10 border border-status-error/30 rounded-lg text-sm text-status-error">
-              <AlertCircle className="w-4 h-4 flex-shrink-0" />
-              {error}
-            </div>
-          )}
-
-          <button
-            onClick={handleGenerate}
-            disabled={!commander || generating || !status?.initialized}
-            className="flex items-center gap-2 px-6 py-3 bg-accent-blue text-white text-sm font-semibold rounded-lg hover:bg-accent-blue-hover shadow-glow-blue transition-all disabled:opacity-50 disabled:shadow-none"
-          >
-            {generating ? (
-              <><Spinner size="sm" /> Generating...</>
-            ) : (
-              <><Wand2 className="w-4 h-4" /> Generate Deck</>
-            )}
-          </button>
-        </div>
-      ) : (
-        /* Results */
-        <div>
-          <button onClick={() => setResult(null)}
-            className="flex items-center gap-2 mb-4 text-sm text-text-secondary hover:text-text-primary transition-colors">
-            <ChevronDown className="w-4 h-4 rotate-90" />
-            Back to Config
-          </button>
-          <GeneratedDeckView result={result} onCommit={handleCommit} />
-        </div>
-      )}
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/pages/BatchSimPage.tsx

@@ -1,415 +0,0 @@
-import { useState, useEffect } from 'react'
-import {
-  FlaskConical, Play, Clock, Trophy,
-  Upload, Link, FileText, History, ChevronRight, AlertCircle,
-  Check
-} from 'lucide-react'
-import { Spinner } from '../components/common'
-import { labApi } from '../api'
-import { usePolling } from '../hooks/usePolling'
-import type { LabDeck, LabStatus, LabResult, LabHistoryEntry, PreconDeck } from '../types'
-import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer, Cell } from 'recharts'
-
-// ── Results Chart ─────────────────────────────────────────────
-function ResultsChart({ result }: { result: LabResult }) {
-  const data = result.decks
-    .sort((a, b) => b.win_rate - a.win_rate)
-    .map(d => ({
-      name: d.name.length > 20 ? d.name.slice(0, 18) + '...' : d.name,
-      win_rate: Math.round(d.win_rate * 100),
-      fullName: d.name,
-    }))
-
-  return (
-    <div className="h-64">
-      <ResponsiveContainer width="100%" height="100%">
-        <BarChart data={data} layout="vertical" barSize={20} margin={{ left: 10, right: 20 }}>
-          <XAxis type="number" domain={[0, 100]} tick={{ fill: '#6b7190', fontSize: 11 }} axisLine={false} tickLine={false} />
-          <YAxis type="category" dataKey="name" width={150} tick={{ fill: '#9ba1b8', fontSize: 11 }} axisLine={false} tickLine={false} />
-          <Tooltip
-            contentStyle={{ backgroundColor: '#1c2030', border: '1px solid #2a2f42', borderRadius: 8, fontSize: 12 }}
-            formatter={(value: unknown) => [`${value}%`, 'Win Rate']}
-            labelFormatter={(label: unknown) => data.find(d => d.name === String(label))?.fullName || String(label)}
-          />
-          <Bar dataKey="win_rate" radius={[0, 4, 4, 0]}>
-            {data.map((_, i) => (
-              <Cell key={i} fill={i === 0 ? '#4ade80' : i === 1 ? '#4f6ef7' : '#363c54'} />
-            ))}
-          </Bar>
-        </BarChart>
-      </ResponsiveContainer>
-    </div>
-  )
-}
-
-// ── Deck Selector ─────────────────────────────────────────────
-function DeckSelector({
-  decks,
-  selected,
-  onToggle,
-  precons,
-  onInstallPrecon,
-}: {
-  decks: LabDeck[]
-  selected: Set<string>
-  onToggle: (name: string) => void
-  precons: PreconDeck[]
-  onInstallPrecon: (name: string) => void
-}) {
-  const [showPrecons, setShowPrecons] = useState(false)
-  const [installing, setInstalling] = useState<string | null>(null)
-
-  async function handleInstall(name: string) {
-    setInstalling(name)
-    await onInstallPrecon(name)
-    setInstalling(null)
-  }
-
-  return (
-    <div className="space-y-3">
-      <h3 className="text-sm font-semibold text-text-primary">Available Decks</h3>
-      {decks.length === 0 ? (
-        <p className="text-xs text-text-tertiary">No decks available. Import or install precons.</p>
-      ) : (
-        <div className="space-y-1 max-h-64 overflow-y-auto">
-          {decks.map(d => (
-            <label key={d.name} className="flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-bg-hover cursor-pointer transition-colors">
-              <input
-                type="checkbox"
-                checked={selected.has(d.name)}
-                onChange={() => onToggle(d.name)}
-                className="w-4 h-4 rounded border-border-primary bg-bg-tertiary text-accent-blue focus:ring-accent-blue/30"
-              />
-              <div className="flex-1 min-w-0">
-                <span className="text-sm text-text-primary truncate block">{d.name}</span>
-                <span className="text-[10px] text-text-tertiary">{d.source} · {d.card_count} cards</span>
-              </div>
-            </label>
-          ))}
-        </div>
-      )}
-
-      <button
-        onClick={() => setShowPrecons(!showPrecons)}
-        className="w-full flex items-center justify-between px-3 py-2 text-xs font-medium bg-bg-tertiary rounded-lg text-text-secondary hover:bg-bg-hover border border-border-primary transition-colors"
-      >
-        Precon Decks
-        <ChevronRight className={`w-3.5 h-3.5 transition-transform ${showPrecons ? 'rotate-90' : ''}`} />
-      </button>
-
-      {showPrecons && (
-        <div className="space-y-1 max-h-48 overflow-y-auto animate-fade-in">
-          {precons.map(p => (
-            <div key={p.name} className="flex items-center gap-3 px-3 py-2 rounded-lg bg-bg-tertiary">
-              <span className="flex-1 text-xs text-text-secondary truncate">{p.name}</span>
-              {p.installed ? (
-                <span className="text-[10px] text-accent-green flex items-center gap-1"><Check className="w-3 h-3" /> Installed</span>
-              ) : (
-                <button
-                  onClick={() => handleInstall(p.name)}
-                  disabled={installing === p.name}
-                  className="text-[10px] text-accent-blue hover:text-accent-blue-hover transition-colors"
-                >
-                  {installing === p.name ? <Spinner size="sm" /> : 'Install'}
-                </button>
-              )}
-            </div>
-          ))}
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ── Import Panel ──────────────────────────────────────────────
-function ImportPanel({ onImported }: { onImported: () => void }) {
-  const [importUrl, setImportUrl] = useState('')
-  const [importText, setImportText] = useState('')
-  const [importName, setImportName] = useState('')
-  const [importing, setImporting] = useState(false)
-  const [importMode, setImportMode] = useState<'url' | 'text'>('url')
-
-  async function handleImport() {
-    setImporting(true)
-    try {
-      if (importMode === 'url' && importUrl.trim()) {
-        await labApi.importDeckFromUrl(importUrl.trim())
-      } else if (importMode === 'text' && importText.trim()) {
-        await labApi.importDeckFromText(importText.trim(), importName || undefined)
-      }
-      setImportUrl('')
-      setImportText('')
-      setImportName('')
-      onImported()
-    } catch { /* ignore */ }
-    setImporting(false)
-  }
-
-  return (
-    <div className="bg-bg-secondary rounded-xl border border-border-primary p-4 space-y-3">
-      <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
-        <Upload className="w-4 h-4 text-accent-blue" />
-        Import Deck
-      </h3>
-      <div className="flex gap-1">
-        <button onClick={() => setImportMode('url')}
-          className={`flex-1 px-3 py-1.5 text-xs font-medium rounded-lg transition-colors ${importMode === 'url' ? 'bg-accent-blue/15 text-accent-blue' : 'bg-bg-tertiary text-text-tertiary'}`}>
-          <Link className="w-3 h-3 inline mr-1" />URL
-        </button>
-        <button onClick={() => setImportMode('text')}
-          className={`flex-1 px-3 py-1.5 text-xs font-medium rounded-lg transition-colors ${importMode === 'text' ? 'bg-accent-blue/15 text-accent-blue' : 'bg-bg-tertiary text-text-tertiary'}`}>
-          <FileText className="w-3 h-3 inline mr-1" />Text
-        </button>
-      </div>
-      {importMode === 'url' ? (
-        <input
-          type="text"
-          placeholder="Moxfield, Archidekt, or deck URL..."
-          value={importUrl}
-          onChange={e => setImportUrl(e.target.value)}
-          className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-        />
-      ) : (
-        <>
-          <input
-            type="text"
-            placeholder="Deck name"
-            value={importName}
-            onChange={e => setImportName(e.target.value)}
-            className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-          />
-          <textarea
-            placeholder={"1x Sol Ring\n1x Command Tower\n..."}
-            value={importText}
-            onChange={e => setImportText(e.target.value)}
-            rows={5}
-            className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary font-mono focus:outline-none focus:border-accent-blue/50 transition-all resize-none"
-          />
-        </>
-      )}
-      <button onClick={handleImport} disabled={importing}
-        className="w-full px-4 py-2 bg-accent-blue text-white text-sm font-medium rounded-lg hover:bg-accent-blue-hover transition-colors disabled:opacity-50">
-        {importing ? <Spinner size="sm" /> : 'Import'}
-      </button>
-    </div>
-  )
-}
-
-// ── Main Batch Sim Page ───────────────────────────────────────
-export function BatchSimPage() {
-  const [decks, setDecks] = useState<LabDeck[]>([])
-  const [precons, setPrecons] = useState<PreconDeck[]>([])
-  const [selected, setSelected] = useState<Set<string>>(new Set())
-  const [games, setGames] = useState(100)
-  const [status, setStatus] = useState<LabStatus | null>(null)
-  const [result, setResult] = useState<LabResult | null>(null)
-  const [history, setHistory] = useState<LabHistoryEntry[]>([])
-  const [loading, setLoading] = useState(true)
-  const [starting, setStarting] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-  const [showHistory, setShowHistory] = useState(false)
-
-  async function fetchDecks() {
-    try {
-      const [d, p] = await Promise.all([labApi.getLabDecks(), labApi.getPrecons()])
-      setDecks(d)
-      setPrecons(p)
-    } catch { /* ignore */ }
-    setLoading(false)
-  }
-
-  useEffect(() => {
-    fetchDecks()
-    labApi.getLabStatus().then(setStatus).catch(() => {})
-    labApi.getLabHistory().then(setHistory).catch(() => {})
-  }, [])
-
-  // Poll while running
-  usePolling(async () => {
-    try {
-      const s = await labApi.getLabStatus()
-      setStatus(s)
-      if (!s.running && s.run_id) {
-        const r = await labApi.getLabResult()
-        setResult(r)
-        labApi.getLabHistory().then(setHistory).catch(() => {})
-      }
-    } catch { /* ignore */ }
-  }, 2000, status?.running || false)
-
-  function toggleDeck(name: string) {
-    setSelected(prev => {
-      const next = new Set(prev)
-      if (next.has(name)) next.delete(name)
-      else next.add(name)
-      return next
-    })
-  }
-
-  async function handleStart() {
-    if (selected.size < 2) { setError('Select at least 2 decks'); return }
-    setStarting(true)
-    setError(null)
-    setResult(null)
-    try {
-      await labApi.startBatchSim({ decks: [...selected], games })
-      const s = await labApi.getLabStatus()
-      setStatus(s)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Failed to start')
-    }
-    setStarting(false)
-  }
-
-  async function handleInstallPrecon(name: string) {
-    try {
-      await labApi.installPrecon(name)
-      fetchDecks()
-    } catch { /* ignore */ }
-  }
-
-  return (
-    <div className="p-6 space-y-5">
-      <div>
-        <h1 className="text-2xl font-bold text-text-primary flex items-center gap-3">
-          <FlaskConical className="w-6 h-6 text-accent-teal" />
-          Batch Simulator
-        </h1>
-        <p className="text-sm text-text-secondary mt-0.5">Run mass simulations between decks</p>
-      </div>
-
-      <div className="flex gap-5">
-        {/* Left sidebar: deck selection + import */}
-        <div className="w-72 flex-shrink-0 space-y-4">
-          {loading ? (
-            <div className="flex items-center justify-center h-32"><Spinner size="md" className="text-accent-blue" /></div>
-          ) : (
-            <DeckSelector
-              decks={decks}
-              selected={selected}
-              onToggle={toggleDeck}
-              precons={precons}
-              onInstallPrecon={handleInstallPrecon}
-            />
-          )}
-          <ImportPanel onImported={fetchDecks} />
-        </div>
-
-        {/* Main content */}
-        <div className="flex-1 space-y-5">
-          {/* Config + Start */}
-          <div className="bg-bg-secondary rounded-xl border border-border-primary p-5">
-            <div className="flex items-center gap-4">
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Games</label>
-                <input
-                  type="number"
-                  min={10}
-                  max={10000}
-                  step={10}
-                  value={games}
-                  onChange={e => setGames(Number(e.target.value))}
-                  className="mt-1 w-28 px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all"
-                />
-              </div>
-              <div className="flex-1">
-                <p className="text-xs text-text-tertiary">Selected: {selected.size} decks</p>
-              </div>
-              {status?.running ? (
-                <div className="flex items-center gap-3">
-                  <div className="flex items-center gap-2">
-                    <Spinner size="sm" className="text-accent-blue" />
-                    <span className="text-sm text-text-secondary">
-                      {status.games_completed} / {status.total_games} games
-                    </span>
-                  </div>
-                  <div className="w-48 h-2 bg-bg-tertiary rounded-full overflow-hidden">
-                    <div
-                      className="h-full bg-accent-blue rounded-full transition-all"
-                      style={{ width: `${status.total_games ? (status.games_completed / status.total_games) * 100 : 0}%` }}
-                    />
-                  </div>
-                </div>
-              ) : (
-                <button onClick={handleStart} disabled={starting || selected.size < 2}
-                  className="flex items-center gap-2 px-5 py-2.5 bg-accent-teal/15 text-accent-teal text-sm font-semibold rounded-lg hover:bg-accent-teal/25 border border-accent-teal/30 transition-colors disabled:opacity-50">
-                  {starting ? <Spinner size="sm" /> : <Play className="w-4 h-4" />}
-                  Start Simulation
-                </button>
-              )}
-            </div>
-            {error && (
-              <div className="mt-3 flex items-center gap-2 px-4 py-2 bg-status-error/10 border border-status-error/30 rounded-lg text-sm text-status-error">
-                <AlertCircle className="w-4 h-4" />{error}
-              </div>
-            )}
-          </div>
-
-          {/* Results */}
-          {result && (
-            <div className="bg-bg-secondary rounded-xl border border-border-primary p-5 space-y-4 animate-fade-in">
-              <div className="flex items-center justify-between">
-                <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
-                  <Trophy className="w-4 h-4 text-accent-amber" />
-                  Results
-                </h3>
-                <span className="text-xs text-text-tertiary">{result.total_games} games · {new Date(result.timestamp).toLocaleString()}</span>
-              </div>
-              <ResultsChart result={result} />
-              <div className="overflow-x-auto">
-                <table className="w-full text-sm">
-                  <thead>
-                    <tr className="border-b border-border-primary">
-                      <th className="px-3 py-2 text-left text-xs text-text-tertiary font-medium uppercase tracking-wider">Deck</th>
-                      <th className="px-3 py-2 text-right text-xs text-text-tertiary font-medium uppercase tracking-wider">Wins</th>
-                      <th className="px-3 py-2 text-right text-xs text-text-tertiary font-medium uppercase tracking-wider">Games</th>
-                      <th className="px-3 py-2 text-right text-xs text-text-tertiary font-medium uppercase tracking-wider">Win Rate</th>
-                      <th className="px-3 py-2 text-right text-xs text-text-tertiary font-medium uppercase tracking-wider">Avg Turns</th>
-                    </tr>
-                  </thead>
-                  <tbody className="divide-y divide-border-primary">
-                    {result.decks.sort((a, b) => b.win_rate - a.win_rate).map((d, i) => (
-                      <tr key={d.name} className="hover:bg-bg-hover transition-colors">
-                        <td className="px-3 py-2.5 flex items-center gap-2">
-                          {i === 0 && <Trophy className="w-3.5 h-3.5 text-accent-amber" />}
-                          <span className="font-medium text-text-primary">{d.name}</span>
-                        </td>
-                        <td className="px-3 py-2.5 text-right text-text-secondary">{d.wins}</td>
-                        <td className="px-3 py-2.5 text-right text-text-secondary">{d.games}</td>
-                        <td className="px-3 py-2.5 text-right font-semibold text-accent-blue">{(d.win_rate * 100).toFixed(1)}%</td>
-                        <td className="px-3 py-2.5 text-right text-text-secondary">{d.avg_turns.toFixed(1)}</td>
-                      </tr>
-                    ))}
-                  </tbody>
-                </table>
-              </div>
-            </div>
-          )}
-
-          {/* History */}
-          <div>
-            <button onClick={() => setShowHistory(!showHistory)}
-              className="flex items-center gap-2 text-sm text-text-secondary hover:text-text-primary transition-colors">
-              <History className="w-4 h-4" />
-              Run History ({history.length})
-              <ChevronRight className={`w-3.5 h-3.5 transition-transform ${showHistory ? 'rotate-90' : ''}`} />
-            </button>
-            {showHistory && history.length > 0 && (
-              <div className="mt-3 space-y-2 animate-fade-in">
-                {history.map(h => (
-                  <div key={h.run_id} className="flex items-center gap-4 px-4 py-3 bg-bg-secondary rounded-lg border border-border-primary">
-                    <Clock className="w-4 h-4 text-text-tertiary" />
-                    <div className="flex-1">
-                      <p className="text-sm text-text-primary">{h.decks.join(' vs ')}</p>
-                      <p className="text-xs text-text-tertiary">{new Date(h.timestamp).toLocaleString()} · {h.total_games} games</p>
-                    </div>
-                  </div>
-                ))}
-              </div>
-            )}
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/pages/CoachPage.tsx

@@ -1,949 +0,0 @@
-import { useState, useEffect, useRef, useCallback } from 'react'
-import {
-  GraduationCap, MessageSquare, Send, Sparkles, AlertCircle, X, Check,
-  ChevronRight, ChevronDown, Download, Settings2, Search, Zap,
-  Minus, Plus, History, ArrowRightLeft, Lightbulb, DollarSign, Loader2,
-  ClipboardList, Brain, BarChart3
-} from 'lucide-react'
-import { Spinner, StatusBadge, EmptyState } from '../components/common'
-import { coachApi } from '../api'
-import type {
-  CoachStatus, CoachDeck, CoachSession, CoachSessionSummary,
-  CoachMessage, CoachGoals, CoachApplyResult, CoachCardLikeResult
-} from '../types'
-
-// ════════════════════════════════════════════════════════════
-// Goals Config Panel
-// ════════════════════════════════════════════════════════════
-function GoalsPanel({
-  goals, onChange, collapsed, onToggle
-}: {
-  goals: CoachGoals
-  onChange: (g: CoachGoals) => void
-  collapsed: boolean
-  onToggle: () => void
-}) {
-  const strategies = ['aggro', 'control', 'combo', 'midrange', 'stax', 'voltron', 'aristocrats', 'tokens']
-  const budgets = [
-    { value: 'budget', label: 'Budget', desc: 'Under $5/card' },
-    { value: 'medium', label: 'Medium', desc: 'Under $20/card' },
-    { value: 'no-limit', label: 'No Limit', desc: 'Any price' },
-  ]
-  const focusOptions = ['ramp', 'card draw', 'removal', 'protection', 'threats', 'mana base', 'combos', 'synergy']
-
-  return (
-    <div className="bg-bg-secondary rounded-xl border border-border-primary">
-      <button
-        onClick={onToggle}
-        className="w-full flex items-center gap-2 px-4 py-3 text-left hover:bg-bg-hover transition-colors rounded-xl"
-      >
-        <Settings2 className="w-4 h-4 text-accent-teal" />
-        <span className="text-sm font-medium text-text-primary flex-1">Coaching Goals</span>
-        {collapsed ? <ChevronRight className="w-4 h-4 text-text-tertiary" /> : <ChevronDown className="w-4 h-4 text-text-tertiary" />}
-      </button>
-
-      {!collapsed && (
-        <div className="px-4 pb-4 space-y-4 border-t border-border-primary pt-3">
-          {/* Power Level Slider */}
-          <div>
-            <label className="text-xs font-medium text-text-secondary mb-1 block">
-              Power Level: {goals.targetPowerLevel ?? 'Any'}
-            </label>
-            <input
-              type="range" min={1} max={10}
-              value={goals.targetPowerLevel ?? 5}
-              onChange={e => onChange({ ...goals, targetPowerLevel: parseInt(e.target.value) })}
-              className="w-full accent-accent-teal"
-            />
-            <div className="flex justify-between text-[10px] text-text-tertiary">
-              <span>Casual</span><span>Focused</span><span>cEDH</span>
-            </div>
-          </div>
-
-          {/* Strategy */}
-          <div>
-            <label className="text-xs font-medium text-text-secondary mb-1.5 block">Strategy Focus</label>
-            <div className="flex flex-wrap gap-1.5">
-              {strategies.map(s => (
-                <button
-                  key={s}
-                  onClick={() => onChange({ ...goals, metaFocus: goals.metaFocus === s ? null : s })}
-                  className={`px-2.5 py-1 text-xs rounded-full border transition-colors ${
-                    goals.metaFocus === s
-                      ? 'bg-accent-teal/20 border-accent-teal/40 text-accent-teal'
-                      : 'border-border-primary text-text-tertiary hover:border-border-secondary'
-                  }`}
-                >
-                  {s}
-                </button>
-              ))}
-            </div>
-          </div>
-
-          {/* Budget */}
-          <div>
-            <label className="text-xs font-medium text-text-secondary mb-1.5 block">Budget</label>
-            <div className="grid grid-cols-3 gap-2">
-              {budgets.map(b => (
-                <button
-                  key={b.value}
-                  onClick={() => onChange({ ...goals, budget: goals.budget === b.value ? null : b.value })}
-                  className={`px-3 py-2 text-xs rounded-lg border transition-colors ${
-                    goals.budget === b.value
-                      ? 'bg-accent-teal/20 border-accent-teal/40 text-accent-teal'
-                      : 'border-border-primary text-text-tertiary hover:border-border-secondary'
-                  }`}
-                >
-                  <div className="font-medium">{b.label}</div>
-                  <div className="text-[10px] opacity-60">{b.desc}</div>
-                </button>
-              ))}
-            </div>
-          </div>
-
-          {/* Focus Areas */}
-          <div>
-            <label className="text-xs font-medium text-text-secondary mb-1.5 block">Focus Areas</label>
-            <div className="flex flex-wrap gap-1.5">
-              {focusOptions.map(f => {
-                const active = (goals.focusAreas || []).includes(f)
-                return (
-                  <button
-                    key={f}
-                    onClick={() => {
-                      const areas = goals.focusAreas || []
-                      onChange({
-                        ...goals,
-                        focusAreas: active ? areas.filter(a => a !== f) : [...areas, f]
-                      })
-                    }}
-                    className={`px-2.5 py-1 text-xs rounded-full border transition-colors ${
-                      active
-                        ? 'bg-accent-blue/20 border-accent-blue/40 text-accent-blue'
-                        : 'border-border-primary text-text-tertiary hover:border-border-secondary'
-                    }`}
-                  >
-                    {f}
-                  </button>
-                )
-              })}
-            </div>
-          </div>
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ════════════════════════════════════════════════════════════
-// Session View — Shows coaching results with apply functionality
-// ════════════════════════════════════════════════════════════
-function SessionView({
-  session, deckId, onClose, onApplied
-}: {
-  session: CoachSession
-  deckId: number
-  onClose: () => void
-  onApplied?: () => void
-}) {
-  const [selectedCuts, setSelectedCuts] = useState<Set<string>>(new Set())
-  const [selectedAdds, setSelectedAdds] = useState<Set<string>>(new Set())
-  const [applying, setApplying] = useState(false)
-  const [applyResult, setApplyResult] = useState<CoachApplyResult | null>(null)
-
-  const toggleCut = (name: string) => {
-    const s = new Set(selectedCuts)
-    s.has(name) ? s.delete(name) : s.add(name)
-    setSelectedCuts(s)
-  }
-  const toggleAdd = (name: string) => {
-    const s = new Set(selectedAdds)
-    s.has(name) ? s.delete(name) : s.add(name)
-    setSelectedAdds(s)
-  }
-
-  const handleApply = async () => {
-    if (selectedCuts.size === 0 && selectedAdds.size === 0) return
-    setApplying(true)
-    try {
-      const result = await coachApi.applyCoachSuggestions(
-        session.sessionId, deckId,
-        [...selectedCuts], [...selectedAdds]
-      )
-      setApplyResult(result)
-      onApplied?.()
-    } catch (e) {
-      console.error('Apply failed:', e)
-    }
-    setApplying(false)
-  }
-
-  return (
-    <div className="space-y-5">
-      <div className="flex items-center justify-between">
-        <div>
-          <h3 className="text-lg font-semibold text-text-primary">Coaching Session</h3>
-          <p className="text-xs text-text-tertiary">
-            {new Date(session.timestamp).toLocaleString()} · {session.modelUsed}
-            {session.promptTokens > 0 && ` · ${session.promptTokens + session.completionTokens} tokens`}
-          </p>
-        </div>
-        <button onClick={onClose} className="p-1.5 rounded-lg hover:bg-bg-hover text-text-tertiary">
-          <X className="w-4 h-4" />
-        </button>
-      </div>
-
-      {/* Summary */}
-      {session.summary && (
-        <div className="bg-bg-secondary rounded-xl border border-border-primary p-4">
-          <h4 className="text-xs font-medium text-text-secondary mb-2 flex items-center gap-1.5">
-            <Brain className="w-3.5 h-3.5" /> Summary
-          </h4>
-          <p className="text-sm text-text-primary leading-relaxed">{session.summary}</p>
-        </div>
-      )}
-
-      {/* Heuristic Hints */}
-      {session.heuristicHints?.length > 0 && (
-        <div className="bg-accent-amber/5 rounded-xl border border-accent-amber/20 p-4">
-          <h4 className="text-xs font-medium text-accent-amber mb-2 flex items-center gap-1.5">
-            <Lightbulb className="w-3.5 h-3.5" /> Strategic Tips
-          </h4>
-          <ul className="space-y-1.5">
-            {session.heuristicHints.map((h, i) => (
-              <li key={i} className="text-sm text-text-primary flex items-start gap-2">
-                <span className="text-accent-amber mt-0.5">•</span> {h}
-              </li>
-            ))}
-          </ul>
-        </div>
-      )}
-
-      {/* Mana Base Advice */}
-      {session.manaBaseAdvice && (
-        <div className="bg-accent-blue/5 rounded-xl border border-accent-blue/20 p-4">
-          <h4 className="text-xs font-medium text-accent-blue mb-2 flex items-center gap-1.5">
-            <BarChart3 className="w-3.5 h-3.5" /> Mana Base
-          </h4>
-          <p className="text-sm text-text-primary">{session.manaBaseAdvice}</p>
-        </div>
-      )}
-
-      {/* Suggested Cuts */}
-      {session.suggestedCuts?.length > 0 && (
-        <div>
-          <h4 className="text-sm font-medium text-status-error mb-2 flex items-center gap-1.5">
-            <Minus className="w-4 h-4" /> Suggested Cuts ({session.suggestedCuts.length})
-          </h4>
-          <div className="space-y-2">
-            {session.suggestedCuts.map((cut, i) => (
-              <div
-                key={i}
-                onClick={() => toggleCut(cut.cardName)}
-                className={`flex items-start gap-3 p-3 rounded-lg border cursor-pointer transition-colors ${
-                  selectedCuts.has(cut.cardName)
-                    ? 'bg-status-error/10 border-status-error/30'
-                    : 'bg-bg-secondary border-border-primary hover:border-border-secondary'
-                }`}
-              >
-                <div className={`mt-0.5 w-4 h-4 rounded border flex items-center justify-center flex-shrink-0 ${
-                  selectedCuts.has(cut.cardName)
-                    ? 'bg-status-error border-status-error text-white'
-                    : 'border-border-secondary'
-                }`}>
-                  {selectedCuts.has(cut.cardName) && <Check className="w-3 h-3" />}
-                </div>
-                <div className="flex-1 min-w-0">
-                  <p className="text-sm font-medium text-text-primary">{cut.cardName}</p>
-                  <p className="text-xs text-text-secondary mt-0.5">{cut.reason}</p>
-                  {cut.replacementOptions?.length > 0 && (
-                    <p className="text-[10px] text-text-tertiary mt-1">
-                      Replace with: {cut.replacementOptions.join(', ')}
-                    </p>
-                  )}
-                </div>
-              </div>
-            ))}
-          </div>
-        </div>
-      )}
-
-      {/* Suggested Adds */}
-      {session.suggestedAdds?.length > 0 && (
-        <div>
-          <h4 className="text-sm font-medium text-status-success mb-2 flex items-center gap-1.5">
-            <Plus className="w-4 h-4" /> Suggested Adds ({session.suggestedAdds.length})
-          </h4>
-          <div className="space-y-2">
-            {session.suggestedAdds.map((add, i) => (
-              <div
-                key={i}
-                onClick={() => toggleAdd(add.cardName)}
-                className={`flex items-start gap-3 p-3 rounded-lg border cursor-pointer transition-colors ${
-                  selectedAdds.has(add.cardName)
-                    ? 'bg-status-success/10 border-status-success/30'
-                    : 'bg-bg-secondary border-border-primary hover:border-border-secondary'
-                }`}
-              >
-                <div className={`mt-0.5 w-4 h-4 rounded border flex items-center justify-center flex-shrink-0 ${
-                  selectedAdds.has(add.cardName)
-                    ? 'bg-status-success border-status-success text-white'
-                    : 'border-border-secondary'
-                }`}>
-                  {selectedAdds.has(add.cardName) && <Check className="w-3 h-3" />}
-                </div>
-                <div className="flex-1 min-w-0">
-                  <div className="flex items-center gap-2">
-                    <p className="text-sm font-medium text-text-primary">{add.cardName}</p>
-                    {add.role && (
-                      <span className="px-1.5 py-0.5 text-[10px] bg-accent-blue/15 text-accent-blue rounded">
-                        {add.role}
-                      </span>
-                    )}
-                  </div>
-                  <p className="text-xs text-text-secondary mt-0.5">{add.reason}</p>
-                  {add.synergyWith?.length > 0 && (
-                    <p className="text-[10px] text-text-tertiary mt-1">
-                      Synergy: {add.synergyWith.join(', ')}
-                    </p>
-                  )}
-                </div>
-              </div>
-            ))}
-          </div>
-        </div>
-      )}
-
-      {/* Apply Button */}
-      {!applyResult && (selectedCuts.size > 0 || selectedAdds.size > 0) && (
-        <div className="sticky bottom-0 bg-bg-primary/95 backdrop-blur-sm border-t border-border-primary py-3 -mx-6 px-6">
-          <button
-            onClick={handleApply}
-            disabled={applying}
-            className="w-full flex items-center justify-center gap-2 px-4 py-2.5 bg-accent-blue text-white text-sm font-medium rounded-lg hover:bg-accent-blue-hover transition-colors disabled:opacity-50"
-          >
-            {applying ? <Spinner size="sm" /> : <ArrowRightLeft className="w-4 h-4" />}
-            Apply {selectedCuts.size > 0 && `${selectedCuts.size} cuts`}
-            {selectedCuts.size > 0 && selectedAdds.size > 0 && ' + '}
-            {selectedAdds.size > 0 && `${selectedAdds.size} adds`} to Deck
-          </button>
-        </div>
-      )}
-
-      {/* Apply Results */}
-      {applyResult && (
-        <div className="bg-status-success/5 rounded-xl border border-status-success/20 p-4">
-          <h4 className="text-sm font-medium text-status-success mb-2 flex items-center gap-1.5">
-            <Check className="w-4 h-4" /> Changes Applied
-          </h4>
-          <p className="text-sm text-text-primary">
-            {applyResult.total_cuts > 0 && `Removed ${applyResult.total_cuts} card(s). `}
-            {applyResult.total_adds > 0 && `Added ${applyResult.total_adds} card(s). `}
-            {applyResult.errors.length > 0 && `${applyResult.errors.length} error(s).`}
-          </p>
-          {applyResult.errors.length > 0 && (
-            <ul className="mt-2 text-xs text-status-error">
-              {applyResult.errors.map((e, i) => (
-                <li key={i}>{e.name}: {e.error}</li>
-              ))}
-            </ul>
-          )}
-        </div>
-      )}
-
-      {/* Raw Explanation */}
-      {session.rawTextExplanation && (
-        <details className="group">
-          <summary className="text-xs text-text-tertiary cursor-pointer hover:text-text-secondary">
-            Full analysis...
-          </summary>
-          <p className="mt-2 text-sm text-text-secondary whitespace-pre-wrap leading-relaxed bg-bg-secondary rounded-lg p-4 border border-border-primary">
-            {session.rawTextExplanation}
-          </p>
-        </details>
-      )}
-    </div>
-  )
-}
-
-// ════════════════════════════════════════════════════════════
-// Cards Like Search
-// ════════════════════════════════════════════════════════════
-function CardsLikePanel() {
-  const [query, setQuery] = useState('')
-  const [results, setResults] = useState<CoachCardLikeResult[]>([])
-  const [searching, setSearching] = useState(false)
-
-  const handleSearch = async () => {
-    if (!query.trim()) return
-    setSearching(true)
-    try {
-      const data = await coachApi.searchCardsLike(query.trim(), undefined, 12)
-      setResults(data.results)
-    } catch { /* ignore */ }
-    setSearching(false)
-  }
-
-  return (
-    <div className="space-y-4">
-      <div className="flex gap-2">
-        <div className="relative flex-1">
-          <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-text-tertiary" />
-          <input
-            value={query}
-            onChange={e => setQuery(e.target.value)}
-            onKeyDown={e => e.key === 'Enter' && handleSearch()}
-            placeholder="Enter a card name..."
-            className="w-full pl-9 pr-3 py-2 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue"
-          />
-        </div>
-        <button
-          onClick={handleSearch}
-          disabled={searching || !query.trim()}
-          className="px-4 py-2 bg-accent-teal/15 text-accent-teal text-sm font-medium rounded-lg hover:bg-accent-teal/25 border border-accent-teal/30 transition-colors disabled:opacity-50"
-        >
-          {searching ? <Spinner size="sm" /> : 'Search'}
-        </button>
-      </div>
-
-      {results.length > 0 && (
-        <div className="grid grid-cols-1 md:grid-cols-2 gap-2">
-          {results.map((card, i) => (
-            <div key={i} className="flex items-start gap-3 p-3 bg-bg-secondary rounded-lg border border-border-primary">
-              <div className="flex-1 min-w-0">
-                <div className="flex items-center gap-2">
-                  <p className="text-sm font-medium text-text-primary truncate">{card.name}</p>
-                  <span className="text-[10px] text-text-tertiary whitespace-nowrap">
-                    {(card.similarity * 100).toFixed(0)}%
-                  </span>
-                </div>
-                <p className="text-[11px] text-text-secondary mt-0.5">{card.types}</p>
-                {card.text && (
-                  <p className="text-[10px] text-text-tertiary mt-1 line-clamp-2">{card.text}</p>
-                )}
-                <div className="flex items-center gap-3 mt-1.5 text-[10px]">
-                  {card.tcg_price != null && (
-                    <span className="text-accent-amber flex items-center gap-0.5">
-                      <DollarSign className="w-2.5 h-2.5" />{card.tcg_price.toFixed(2)}
-                    </span>
-                  )}
-                  {card.owned_qty > 0 && (
-                    <span className="text-status-success">Owned: {card.owned_qty}</span>
-                  )}
-                  <span className="text-text-tertiary">MV: {card.mana_value}</span>
-                </div>
-              </div>
-              {card.image_url && (
-                <img src={card.image_url} alt={card.name} className="w-14 h-auto rounded" />
-              )}
-            </div>
-          ))}
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ════════════════════════════════════════════════════════════
-// Live Chat View
-// ════════════════════════════════════════════════════════════
-function LiveChat({
-  deckId, deckName, goals, onClose
-}: {
-  deckId: string
-  deckName: string
-  goals: CoachGoals
-  onClose: () => void
-}) {
-  const [messages, setMessages] = useState<CoachMessage[]>([])
-  const [input, setInput] = useState('')
-  const [streaming, setStreaming] = useState(false)
-  const [streamText, setStreamText] = useState('')
-  const messagesEndRef = useRef<HTMLDivElement>(null)
-  const abortRef = useRef<AbortController | null>(null)
-
-  useEffect(() => {
-    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
-  }, [messages, streamText])
-
-  const sendMessage = async () => {
-    if (!input.trim() || streaming) return
-    const userMsg: CoachMessage = { role: 'user', content: input.trim() }
-    const allMessages = [...messages, userMsg]
-    setMessages(allMessages)
-    setInput('')
-    setStreaming(true)
-    setStreamText('')
-
-    const goalsDict = goals.targetPowerLevel || goals.metaFocus || goals.budget || (goals.focusAreas || []).length > 0
-      ? {
-          targetPowerLevel: goals.targetPowerLevel,
-          metaFocus: goals.metaFocus,
-          budget: goals.budget,
-          focusAreas: goals.focusAreas,
-        }
-      : undefined
-
-    try {
-      abortRef.current = new AbortController()
-      const fullText = await coachApi.coachChatStream(
-        deckId,
-        allMessages.map(m => ({ role: m.role, content: m.content })),
-        goalsDict,
-        (text) => setStreamText(text),
-        abortRef.current.signal
-      )
-
-      setMessages(prev => [...prev, { role: 'assistant', content: fullText }])
-      setStreamText('')
-    } catch (e) {
-      if ((e as Error).name !== 'AbortError') {
-        // Fallback to non-streaming
-        try {
-          const resp = await coachApi.coachChat(
-            deckId,
-            allMessages.map(m => ({ role: m.role, content: m.content })),
-            goalsDict
-          )
-          setMessages(prev => [...prev, { role: 'assistant', content: resp.content }])
-        } catch (e2) {
-          setMessages(prev => [...prev, {
-            role: 'assistant',
-            content: `Error: ${(e2 as Error).message || 'Failed to get response'}`
-          }])
-        }
-      }
-      setStreamText('')
-    }
-    setStreaming(false)
-  }
-
-  return (
-    <div className="flex flex-col h-[calc(100vh-180px)]">
-      {/* Header */}
-      <div className="flex items-center justify-between px-4 py-3 border-b border-border-primary">
-        <div>
-          <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
-            <MessageSquare className="w-4 h-4 text-accent-blue" />
-            Chat: {deckName}
-          </h3>
-          <p className="text-[10px] text-text-tertiary">
-            {goals.metaFocus && `${goals.metaFocus} · `}
-            {goals.targetPowerLevel && `Power ${goals.targetPowerLevel} · `}
-            {goals.budget && `${goals.budget}`}
-          </p>
-        </div>
-        <button onClick={onClose} className="p-1.5 rounded-lg hover:bg-bg-hover text-text-tertiary">
-          <X className="w-4 h-4" />
-        </button>
-      </div>
-
-      {/* Messages */}
-      <div className="flex-1 overflow-y-auto p-4 space-y-3">
-        {messages.length === 0 && !streaming && (
-          <div className="text-center py-12">
-            <GraduationCap className="w-10 h-10 text-text-tertiary mx-auto mb-3" />
-            <p className="text-sm text-text-secondary">Ask your coach anything about this deck.</p>
-            <div className="mt-4 flex flex-wrap gap-2 justify-center">
-              {[
-                'What should I cut?',
-                'How is my mana curve?',
-                'Suggest win conditions',
-                'Rate my removal suite',
-              ].map(q => (
-                <button
-                  key={q}
-                  onClick={() => { setInput(q); }}
-                  className="px-3 py-1.5 text-xs bg-bg-secondary border border-border-primary rounded-full text-text-secondary hover:text-text-primary hover:border-border-secondary transition-colors"
-                >
-                  {q}
-                </button>
-              ))}
-            </div>
-          </div>
-        )}
-
-        {messages.map((msg, i) => (
-          <div key={i} className={`flex ${msg.role === 'user' ? 'justify-end' : 'justify-start'}`}>
-            <div className={`max-w-[85%] px-4 py-3 rounded-xl text-sm whitespace-pre-wrap leading-relaxed ${
-              msg.role === 'user'
-                ? 'bg-accent-blue/15 text-text-primary border border-accent-blue/20'
-                : 'bg-bg-secondary text-text-primary border border-border-primary'
-            }`}>
-              {msg.content}
-            </div>
-          </div>
-        ))}
-
-        {/* Streaming indicator */}
-        {streaming && (
-          <div className="flex justify-start">
-            <div className="max-w-[85%] px-4 py-3 rounded-xl text-sm whitespace-pre-wrap leading-relaxed bg-bg-secondary text-text-primary border border-border-primary">
-              {streamText || (
-                <span className="flex items-center gap-2 text-text-tertiary">
-                  <Loader2 className="w-3.5 h-3.5 animate-spin" />
-                  Thinking...
-                </span>
-              )}
-            </div>
-          </div>
-        )}
-        <div ref={messagesEndRef} />
-      </div>
-
-      {/* Input */}
-      <div className="border-t border-border-primary p-3">
-        <div className="flex gap-2">
-          <input
-            value={input}
-            onChange={e => setInput(e.target.value)}
-            onKeyDown={e => e.key === 'Enter' && !e.shiftKey && sendMessage()}
-            placeholder="Ask the coach..."
-            disabled={streaming}
-            className="flex-1 px-3 py-2 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue disabled:opacity-50"
-          />
-          <button
-            onClick={sendMessage}
-            disabled={streaming || !input.trim()}
-            className="px-3 py-2 bg-accent-blue text-white rounded-lg hover:bg-accent-blue-hover transition-colors disabled:opacity-50"
-          >
-            <Send className="w-4 h-4" />
-          </button>
-        </div>
-      </div>
-    </div>
-  )
-}
-
-// ════════════════════════════════════════════════════════════
-// Main Coach Page
-// ════════════════════════════════════════════════════════════
-type Tab = 'decks' | 'chat' | 'session' | 'history' | 'search'
-
-export function CoachPage() {
-  const [status, setStatus] = useState<CoachStatus | null>(null)
-  const [decks, setDecks] = useState<CoachDeck[]>([])
-  const [sessions, setSessions] = useState<CoachSessionSummary[]>([])
-  const [loading, setLoading] = useState(true)
-  const [error, setError] = useState<string | null>(null)
-
-  // UI state
-  const [tab, setTab] = useState<Tab>('decks')
-  const [selectedDeck, setSelectedDeck] = useState<CoachDeck | null>(null)
-  const [selectedSession, setSelectedSession] = useState<CoachSession | null>(null)
-  const [goals, setGoals] = useState<CoachGoals>({})
-  const [goalsCollapsed, setGoalsCollapsed] = useState(true)
-  const [generatingReport, setGeneratingReport] = useState(false)
-  const [runningSession, setRunningSession] = useState<number | null>(null)
-  const [downloadingEmbeddings, setDownloadingEmbeddings] = useState(false)
-
-  const loadData = useCallback(async () => {
-    try {
-      const [s, d, sess] = await Promise.all([
-        coachApi.getCoachStatus(),
-        coachApi.getCoachDecks().catch(() => []),
-        coachApi.getCoachSessions().catch(() => ({ sessions: [] })),
-      ])
-      setStatus(s)
-      setDecks(Array.isArray(d) ? d : [])
-      setSessions(Array.isArray(sess) ? sess : (sess as { sessions: CoachSessionSummary[] }).sessions || [])
-    } catch { /* ignore */ }
-    setLoading(false)
-  }, [])
-
-  useEffect(() => { loadData() }, [loadData])
-
-  const handleDownloadEmbeddings = async () => {
-    setDownloadingEmbeddings(true)
-    try {
-      await coachApi.downloadEmbeddings()
-      const s = await coachApi.getCoachStatus()
-      setStatus(s)
-    } catch { /* ignore */ }
-    setDownloadingEmbeddings(false)
-  }
-
-  const handleGenerateReports = async () => {
-    setGeneratingReport(true)
-    setError(null)
-    try {
-      await coachApi.generateReport()
-      await loadData()
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Report generation failed')
-    }
-    setGeneratingReport(false)
-  }
-
-  const handleRunSession = async (deck: CoachDeck) => {
-    setRunningSession(deck.deck_id)
-    setError(null)
-    try {
-      const deckSlug = deck.deck_name.toLowerCase().replace(/\s+/g, '-')
-      const goalsDict = goals.targetPowerLevel || goals.metaFocus || goals.budget || (goals.focusAreas || []).length > 0
-        ? goals : undefined
-      const session = await coachApi.runCoachSession(deckSlug, goalsDict as Record<string, unknown>)
-      setSelectedSession(session)
-      setSelectedDeck(deck)
-      setTab('session')
-      await loadData()
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Session failed')
-    }
-    setRunningSession(null)
-  }
-
-  const handleOpenChat = (deck: CoachDeck) => {
-    setSelectedDeck(deck)
-    setTab('chat')
-  }
-
-  const handleViewSession = async (sessionId: string) => {
-    try {
-      const s = await coachApi.getCoachSession(sessionId)
-      setSelectedSession(s)
-      // Find the matching deck
-      const matchDeck = decks.find(d =>
-        d.deck_name.toLowerCase().replace(/\s+/g, '-') === s.deckId.toLowerCase() ||
-        d.deck_name.toLowerCase() === s.deckId.toLowerCase()
-      )
-      if (matchDeck) setSelectedDeck(matchDeck)
-      setTab('session')
-    } catch { /* ignore */ }
-  }
-
-  if (loading) {
-    return (
-      <div className="p-6 flex items-center justify-center h-64">
-        <Spinner size="lg" className="text-accent-blue" />
-      </div>
-    )
-  }
-
-  return (
-    <div className="p-6 space-y-5">
-      {/* Header */}
-      <div className="flex items-center justify-between">
-        <div>
-          <h1 className="text-2xl font-bold text-text-primary flex items-center gap-3">
-            <GraduationCap className="w-6 h-6 text-accent-amber" />
-            Deck Coach
-          </h1>
-          <p className="text-sm text-text-secondary mt-0.5">
-            AI-powered deck analysis, coaching, and live chat
-          </p>
-        </div>
-      </div>
-
-      {/* Status Bar */}
-      <div className="flex items-center gap-3 flex-wrap">
-        <StatusBadge
-          variant={status?.llmConnected ? 'success' : 'warning'}
-          label={status?.llmConnected ? `LLM: ${status.llmModel || 'Connected'}` : 'LLM: Disconnected'}
-        />
-        <StatusBadge
-          variant={status?.embeddingsLoaded ? 'success' : 'neutral'}
-          label={status?.embeddingsLoaded ? `${(status.embeddingCards || 0).toLocaleString()} embeddings` : 'No embeddings'}
-        />
-        {status?.deckReportsAvailable != null && status.deckReportsAvailable > 0 && (
-          <StatusBadge variant="success" label={`${status.deckReportsAvailable} reports`} />
-        )}
-        {!status?.embeddingsLoaded && (
-          <button onClick={handleDownloadEmbeddings} disabled={downloadingEmbeddings}
-            className="flex items-center gap-1.5 text-xs text-accent-blue hover:text-accent-blue-hover transition-colors disabled:opacity-50">
-            {downloadingEmbeddings ? <Spinner size="sm" /> : <Download className="w-3 h-3" />}
-            Download Embeddings
-          </button>
-        )}
-      </div>
-
-      {error && (
-        <div className="flex items-center gap-2 px-4 py-2 bg-status-error/10 border border-status-error/30 rounded-lg text-sm text-status-error">
-          <AlertCircle className="w-4 h-4 flex-shrink-0" />{error}
-          <button onClick={() => setError(null)} className="ml-auto"><X className="w-3 h-3" /></button>
-        </div>
-      )}
-
-      {/* Tab Nav */}
-      <div className="flex gap-1 bg-bg-secondary rounded-lg p-1 border border-border-primary">
-        {([
-          { id: 'decks', label: 'Decks', icon: ClipboardList },
-          { id: 'history', label: 'Sessions', icon: History },
-          { id: 'search', label: 'Cards Like', icon: Search },
-        ] as { id: Tab; label: string; icon: typeof ClipboardList }[]).map(t => (
-          <button
-            key={t.id}
-            onClick={() => setTab(t.id)}
-            className={`flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-md transition-colors ${
-              tab === t.id
-                ? 'bg-bg-primary text-text-primary shadow-sm'
-                : 'text-text-tertiary hover:text-text-secondary'
-            }`}
-          >
-            <t.icon className="w-3.5 h-3.5" />
-            {t.label}
-            {t.id === 'history' && sessions.length > 0 && (
-              <span className="text-[10px] bg-bg-tertiary px-1.5 rounded-full">{sessions.length}</span>
-            )}
-          </button>
-        ))}
-        {tab === 'chat' && selectedDeck && (
-          <div className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-md bg-bg-primary text-accent-blue shadow-sm">
-            <MessageSquare className="w-3.5 h-3.5" />
-            Chat
-          </div>
-        )}
-        {tab === 'session' && selectedSession && (
-          <div className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-md bg-bg-primary text-accent-amber shadow-sm">
-            <Sparkles className="w-3.5 h-3.5" />
-            Results
-          </div>
-        )}
-      </div>
-
-      {/* Goals Panel (shown when on decks tab) */}
-      {tab === 'decks' && (
-        <GoalsPanel
-          goals={goals}
-          onChange={setGoals}
-          collapsed={goalsCollapsed}
-          onToggle={() => setGoalsCollapsed(!goalsCollapsed)}
-        />
-      )}
-
-      {/* ── Decks Tab ─────────────────────────────────────── */}
-      {tab === 'decks' && (
-        <div className="space-y-4">
-          <div className="flex items-center justify-between">
-            <h2 className="text-sm font-semibold text-text-primary">Your Decks</h2>
-            <button
-              onClick={handleGenerateReports}
-              disabled={generatingReport}
-              className="flex items-center gap-1.5 text-xs text-accent-amber hover:text-accent-amber transition-colors disabled:opacity-50"
-            >
-              {generatingReport ? <Spinner size="sm" /> : <Zap className="w-3 h-3" />}
-              Generate Reports
-            </button>
-          </div>
-
-          {decks.length === 0 ? (
-            <EmptyState
-              icon={GraduationCap}
-              title="No decks available"
-              description="Create decks in the Deck Builder to start coaching."
-            />
-          ) : (
-            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3">
-              {decks.map(deck => (
-                <div key={deck.deck_id} className="bg-bg-secondary rounded-xl border border-border-primary p-4 space-y-3">
-                  <div>
-                    <h3 className="text-sm font-semibold text-text-primary">{deck.deck_name}</h3>
-                    <p className="text-xs text-text-secondary">{deck.commander}</p>
-                  </div>
-                  <div className="flex items-center gap-3 text-[10px] text-text-tertiary">
-                    <span>{deck.card_count} cards</span>
-                    {deck.has_report && (
-                      <span className="flex items-center gap-1 text-status-success">
-                        <Check className="w-2.5 h-2.5" /> Report
-                      </span>
-                    )}
-                  </div>
-                  <div className="flex items-center gap-2">
-                    <button
-                      onClick={() => handleRunSession(deck)}
-                      disabled={runningSession === deck.deck_id || !status?.llmConnected}
-                      className="flex-1 flex items-center justify-center gap-1.5 px-3 py-2 bg-accent-amber/15 text-accent-amber text-xs font-medium rounded-lg hover:bg-accent-amber/25 border border-accent-amber/30 transition-colors disabled:opacity-50"
-                    >
-                      {runningSession === deck.deck_id ? <Spinner size="sm" /> : <Sparkles className="w-3 h-3" />}
-                      Analyze
-                    </button>
-                    <button
-                      onClick={() => handleOpenChat(deck)}
-                      disabled={!status?.llmConnected}
-                      className="flex-1 flex items-center justify-center gap-1.5 px-3 py-2 bg-accent-blue/15 text-accent-blue text-xs font-medium rounded-lg hover:bg-accent-blue/25 border border-accent-blue/30 transition-colors disabled:opacity-50"
-                    >
-                      <MessageSquare className="w-3 h-3" />
-                      Chat
-                    </button>
-                  </div>
-                </div>
-              ))}
-            </div>
-          )}
-        </div>
-      )}
-
-      {/* ── Chat Tab ──────────────────────────────────────── */}
-      {tab === 'chat' && selectedDeck && (
-        <LiveChat
-          deckId={selectedDeck.deck_name.toLowerCase().replace(/\s+/g, '-')}
-          deckName={selectedDeck.deck_name}
-          goals={goals}
-          onClose={() => setTab('decks')}
-        />
-      )}
-
-      {/* ── Session Results Tab ───────────────────────────── */}
-      {tab === 'session' && selectedSession && selectedDeck && (
-        <SessionView
-          session={selectedSession}
-          deckId={selectedDeck.deck_id}
-          onClose={() => setTab('decks')}
-          onApplied={() => loadData()}
-        />
-      )}
-
-      {/* ── History Tab ───────────────────────────────────── */}
-      {tab === 'history' && (
-        <div className="space-y-3">
-          <h2 className="text-sm font-semibold text-text-primary">Coaching Sessions</h2>
-          {sessions.length === 0 ? (
-            <EmptyState
-              icon={History}
-              title="No sessions yet"
-              description="Run an analysis on a deck to create your first coaching session."
-            />
-          ) : (
-            <div className="space-y-2">
-              {sessions.map(s => (
-                <button
-                  key={s.sessionId}
-                  onClick={() => handleViewSession(s.sessionId)}
-                  className="w-full flex items-center gap-4 px-4 py-3 bg-bg-secondary rounded-lg border border-border-primary hover:border-border-secondary text-left transition-colors"
-                >
-                  <Sparkles className="w-4 h-4 text-accent-amber flex-shrink-0" />
-                  <div className="flex-1 min-w-0">
-                    <div className="flex items-center gap-2">
-                      <p className="text-sm font-medium text-text-primary">{s.deckId}</p>
-                      <span className="text-[10px] text-text-tertiary">
-                        {s.cutsCount > 0 && `${s.cutsCount} cuts`}
-                        {s.cutsCount > 0 && s.addsCount > 0 && ' · '}
-                        {s.addsCount > 0 && `${s.addsCount} adds`}
-                      </span>
-                    </div>
-                    <p className="text-xs text-text-tertiary mt-0.5 truncate">{s.summary || 'No summary'}</p>
-                    <p className="text-[10px] text-text-tertiary mt-0.5">{new Date(s.timestamp).toLocaleString()}</p>
-                  </div>
-                  <ChevronRight className="w-4 h-4 text-text-tertiary flex-shrink-0" />
-                </button>
-              ))}
-            </div>
-          )}
-        </div>
-      )}
-
-      {/* ── Cards Like Tab ────────────────────────────────── */}
-      {tab === 'search' && (
-        <div className="space-y-4">
-          <div>
-            <h2 className="text-sm font-semibold text-text-primary mb-1">Cards Like This</h2>
-            <p className="text-xs text-text-secondary">
-              Find similar cards using AI embeddings. Search by card name to discover alternatives.
-            </p>
-          </div>
-          <CardsLikePanel />
-        </div>
-      )}
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/pages/CollectionPage.tsx

@@ -1,484 +0,0 @@
-import { useState, useEffect, useCallback, useRef } from 'react'
-import {
-  Search, Filter, Upload, Download, Camera, RefreshCw,
-  ChevronLeft, ChevronRight, X, Package, SlidersHorizontal,
-  Plus, Grid3x3, List
-} from 'lucide-react'
-import { Spinner, EmptyState, ManaSymbols, CardImage } from '../components/common'
-import { collectionApi } from '../api'
-import type { CollectionCard, CollectionFilters, SetInfo } from '../types'
-
-// ── Card Detail Modal ─────────────────────────────────────────
-function CardDetailModal({ card, onClose }: { card: CollectionCard; onClose: () => void }) {
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm" onClick={onClose}>
-      <div
-        className="bg-bg-secondary rounded-xl border border-border-primary shadow-lg max-w-4xl w-full mx-4 max-h-[90vh] overflow-y-auto animate-fade-in"
-        onClick={e => e.stopPropagation()}
-      >
-        <div className="flex items-start justify-between p-5 border-b border-border-primary">
-          <div>
-            <h2 className="text-xl font-bold text-text-primary">{card.name}</h2>
-            <p className="text-sm text-text-secondary mt-0.5">{card.type_line}</p>
-          </div>
-          <button onClick={onClose} className="p-1 rounded hover:bg-bg-hover text-text-tertiary">
-            <X className="w-5 h-5" />
-          </button>
-        </div>
-        <div className="flex flex-col md:flex-row gap-6 p-5">
-          {/* Large card image */}
-          <div className="flex-shrink-0">
-            <CardImage src={card.image_url} alt={card.name} size="xl" />
-          </div>
-          {/* Card info */}
-          <div className="flex-1 space-y-4">
-            <div>
-              <label className="text-xs text-text-tertiary uppercase tracking-wider">Mana Cost</label>
-              <div className="mt-1"><ManaSymbols cost={card.mana_cost} size="md" /></div>
-            </div>
-            <div>
-              <label className="text-xs text-text-tertiary uppercase tracking-wider">Oracle Text</label>
-              <p className="mt-1 text-sm text-text-primary whitespace-pre-wrap leading-relaxed">{card.oracle_text}</p>
-            </div>
-            <div className="grid grid-cols-2 gap-4">
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Set</label>
-                <p className="mt-1 text-sm text-text-primary">{card.set_name} ({card.set_code.toUpperCase()})</p>
-              </div>
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Rarity</label>
-                <p className={`mt-1 text-sm font-medium capitalize ${
-                  card.rarity === 'mythic' ? 'text-accent-amber' :
-                  card.rarity === 'rare' ? 'text-accent-amber/80' :
-                  card.rarity === 'uncommon' ? 'text-accent-teal' : 'text-text-secondary'
-                }`}>{card.rarity}</p>
-              </div>
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">CMC</label>
-                <p className="mt-1 text-sm text-text-primary">{card.cmc}</p>
-              </div>
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">EDHREC Rank</label>
-                <p className="mt-1 text-sm text-text-primary">{card.edhrec_rank ?? 'N/A'}</p>
-              </div>
-            </div>
-            <div className="grid grid-cols-2 gap-4">
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Quantity</label>
-                <p className="mt-1 text-sm text-text-primary">{card.quantity} (+ {card.foil_quantity} foil)</p>
-              </div>
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Price</label>
-                <p className="mt-1 text-sm text-accent-teal font-semibold">
-                  ${card.tcg_price?.toFixed(2) ?? '—'}
-                  {card.foil_price ? <span className="text-text-tertiary ml-2">Foil: ${card.foil_price.toFixed(2)}</span> : null}
-                </p>
-              </div>
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}
-
-// ── Scanner Panel ─────────────────────────────────────────────
-function ScannerPanel({ onCardAdded }: { onCardAdded: () => void }) {
-  const [scanning, setScanning] = useState(false)
-  const [results, setResults] = useState<import('../types').ScanMatch[]>([])
-  const [adding, setAdding] = useState<string | null>(null)
-  const fileRef = useRef<HTMLInputElement>(null)
-
-  async function handleScan(file: File) {
-    setScanning(true)
-    setResults([])
-    try {
-      const res = await collectionApi.scanCard(file)
-      setResults(res.matches || [])
-    } catch {
-      setResults([])
-    }
-    setScanning(false)
-  }
-
-  async function handleAdd(match: import('../types').ScanMatch) {
-    setAdding(match.scryfall_id)
-    try {
-      await collectionApi.addScanResult({
-        name: match.name,
-        set_code: match.set_code,
-        scryfall_id: match.scryfall_id,
-      })
-      onCardAdded()
-    } catch { /* ignore */ }
-    setAdding(null)
-  }
-
-  return (
-    <div className="bg-bg-secondary rounded-xl border border-border-primary p-5">
-      <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2 mb-3">
-        <Camera className="w-4 h-4 text-accent-blue" />
-        Card Scanner
-      </h3>
-      <input
-        ref={fileRef}
-        type="file"
-        accept="image/*"
-        className="hidden"
-        onChange={e => e.target.files?.[0] && handleScan(e.target.files[0])}
-      />
-      <button
-        onClick={() => fileRef.current?.click()}
-        disabled={scanning}
-        className="w-full flex items-center justify-center gap-2 px-4 py-2.5 bg-accent-blue/10 text-accent-blue border border-accent-blue/30 rounded-lg text-sm font-medium hover:bg-accent-blue/20 transition-colors disabled:opacity-50"
-      >
-        {scanning ? <Spinner size="sm" /> : <Camera className="w-4 h-4" />}
-        {scanning ? 'Scanning...' : 'Scan a Card'}
-      </button>
-      {results.length > 0 && (
-        <div className="mt-3 space-y-2 max-h-60 overflow-y-auto">
-          {results.map(m => (
-            <div key={m.scryfall_id} className="flex items-center gap-3 p-2 rounded-lg bg-bg-tertiary">
-              <CardImage src={m.image_url} alt={m.name} size="sm" />
-              <div className="flex-1 min-w-0">
-                <p className="text-sm font-medium text-text-primary truncate">{m.name}</p>
-                <p className="text-xs text-text-tertiary">{m.set_name} — {(m.confidence * 100).toFixed(0)}%</p>
-              </div>
-              <button
-                onClick={() => handleAdd(m)}
-                disabled={adding === m.scryfall_id}
-                className="p-1.5 rounded-lg bg-accent-green/15 text-accent-green hover:bg-accent-green/25 transition-colors"
-              >
-                {adding === m.scryfall_id ? <Spinner size="sm" /> : <Plus className="w-4 h-4" />}
-              </button>
-            </div>
-          ))}
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ── Main Collection Page ──────────────────────────────────────
-export function CollectionPage() {
-  const [cards, setCards] = useState<CollectionCard[]>([])
-  const [total, setTotal] = useState(0)
-  const [loading, setLoading] = useState(true)
-  const [sets, setSets] = useState<SetInfo[]>([])
-  const [selectedCard, setSelectedCard] = useState<CollectionCard | null>(null)
-  const [viewMode, setViewMode] = useState<'grid' | 'list'>('grid')
-  const [showFilters, setShowFilters] = useState(false)
-  const [importing, setImporting] = useState(false)
-  const [enriching, setEnriching] = useState(false)
-  const importRef = useRef<HTMLInputElement>(null)
-
-  const [filters, setFilters] = useState<CollectionFilters>({
-    q: '',
-    page: 1,
-    page_size: 48,
-    sort_by: 'name',
-    sort_dir: 'asc',
-  })
-
-  const fetchCards = useCallback(async () => {
-    setLoading(true)
-    try {
-      const res = await collectionApi.searchCollection(filters)
-      setCards(res.cards)
-      setTotal(res.total)
-    } catch { /* ignore */ }
-    setLoading(false)
-  }, [filters])
-
-  useEffect(() => { fetchCards() }, [fetchCards])
-
-  useEffect(() => {
-    collectionApi.getSets().then(setSets).catch(() => {})
-  }, [])
-
-  const totalPages = Math.ceil(total / (filters.page_size || 48))
-
-  function updateFilter(key: keyof CollectionFilters, value: string | number | boolean | undefined) {
-    setFilters(prev => ({ ...prev, [key]: value, page: 1 }))
-  }
-
-  async function handleExport() {
-    const blob = await collectionApi.exportCollection('csv')
-    const url = URL.createObjectURL(blob)
-    const a = document.createElement('a')
-    a.href = url
-    a.download = 'collection.csv'
-    a.click()
-    URL.revokeObjectURL(url)
-  }
-
-  async function handleImport(file: File) {
-    setImporting(true)
-    try {
-      await collectionApi.importCollection(file)
-      fetchCards()
-    } catch { /* ignore */ }
-    setImporting(false)
-  }
-
-  async function handleReEnrich() {
-    setEnriching(true)
-    try {
-      await collectionApi.reEnrichCards()
-      fetchCards()
-    } catch { /* ignore */ }
-    setEnriching(false)
-  }
-
-  return (
-    <div className="p-6 space-y-5">
-      {/* Header */}
-      <div className="flex items-center justify-between">
-        <div>
-          <h1 className="text-2xl font-bold text-text-primary">Collection</h1>
-          <p className="text-sm text-text-secondary mt-0.5">{total.toLocaleString()} cards in your collection</p>
-        </div>
-        <div className="flex items-center gap-2">
-          <button onClick={handleReEnrich} disabled={enriching}
-            className="flex items-center gap-2 px-3 py-2 text-xs font-medium bg-bg-tertiary text-text-secondary rounded-lg hover:bg-bg-hover border border-border-primary transition-colors disabled:opacity-50">
-            {enriching ? <Spinner size="sm" /> : <RefreshCw className="w-3.5 h-3.5" />}
-            Re-Enrich
-          </button>
-          <input ref={importRef} type="file" accept=".csv,.txt" className="hidden"
-            onChange={e => e.target.files?.[0] && handleImport(e.target.files[0])} />
-          <button onClick={() => importRef.current?.click()} disabled={importing}
-            className="flex items-center gap-2 px-3 py-2 text-xs font-medium bg-bg-tertiary text-text-secondary rounded-lg hover:bg-bg-hover border border-border-primary transition-colors disabled:opacity-50">
-            {importing ? <Spinner size="sm" /> : <Upload className="w-3.5 h-3.5" />}
-            Import
-          </button>
-          <button onClick={handleExport}
-            className="flex items-center gap-2 px-3 py-2 text-xs font-medium bg-bg-tertiary text-text-secondary rounded-lg hover:bg-bg-hover border border-border-primary transition-colors">
-            <Download className="w-3.5 h-3.5" />
-            Export
-          </button>
-        </div>
-      </div>
-
-      <div className="flex gap-5">
-        {/* Left sidebar: search + filters + scanner */}
-        <div className="w-72 flex-shrink-0 space-y-4">
-          {/* Search */}
-          <div className="relative">
-            <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-text-tertiary" />
-            <input
-              type="text"
-              placeholder="Search cards..."
-              value={filters.q || ''}
-              onChange={e => updateFilter('q', e.target.value)}
-              className="w-full pl-10 pr-4 py-2.5 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 focus:ring-1 focus:ring-accent-blue/30 transition-all"
-            />
-          </div>
-
-          {/* Filter toggle */}
-          <button
-            onClick={() => setShowFilters(!showFilters)}
-            className="w-full flex items-center justify-between px-4 py-2.5 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-secondary hover:bg-bg-hover transition-colors"
-          >
-            <span className="flex items-center gap-2">
-              <SlidersHorizontal className="w-4 h-4" />
-              Filters
-            </span>
-            <Filter className={`w-3.5 h-3.5 transition-transform ${showFilters ? 'rotate-180' : ''}`} />
-          </button>
-
-          {showFilters && (
-            <div className="bg-bg-secondary rounded-xl border border-border-primary p-4 space-y-3 animate-fade-in">
-              {/* Rarity */}
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Rarity</label>
-                <select
-                  value={filters.rarity || ''}
-                  onChange={e => updateFilter('rarity', e.target.value || undefined)}
-                  className="mt-1 w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50"
-                >
-                  <option value="">All</option>
-                  <option value="common">Common</option>
-                  <option value="uncommon">Uncommon</option>
-                  <option value="rare">Rare</option>
-                  <option value="mythic">Mythic</option>
-                </select>
-              </div>
-              {/* Color */}
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Color</label>
-                <select
-                  value={filters.color || ''}
-                  onChange={e => updateFilter('color', e.target.value || undefined)}
-                  className="mt-1 w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50"
-                >
-                  <option value="">All</option>
-                  <option value="W">White</option>
-                  <option value="U">Blue</option>
-                  <option value="B">Black</option>
-                  <option value="R">Red</option>
-                  <option value="G">Green</option>
-                  <option value="C">Colorless</option>
-                </select>
-              </div>
-              {/* Set */}
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Set</label>
-                <select
-                  value={filters.set_code || ''}
-                  onChange={e => updateFilter('set_code', e.target.value || undefined)}
-                  className="mt-1 w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50"
-                >
-                  <option value="">All Sets</option>
-                  {sets.map(s => (
-                    <option key={s.code} value={s.code}>{s.name} ({s.card_count})</option>
-                  ))}
-                </select>
-              </div>
-              {/* CMC Range */}
-              <div className="grid grid-cols-2 gap-2">
-                <div>
-                  <label className="text-xs text-text-tertiary uppercase tracking-wider">CMC Min</label>
-                  <input type="number" min="0" max="20"
-                    value={filters.cmc_min ?? ''}
-                    onChange={e => updateFilter('cmc_min', e.target.value ? Number(e.target.value) : undefined)}
-                    className="mt-1 w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50"
-                  />
-                </div>
-                <div>
-                  <label className="text-xs text-text-tertiary uppercase tracking-wider">CMC Max</label>
-                  <input type="number" min="0" max="20"
-                    value={filters.cmc_max ?? ''}
-                    onChange={e => updateFilter('cmc_max', e.target.value ? Number(e.target.value) : undefined)}
-                    className="mt-1 w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50"
-                  />
-                </div>
-              </div>
-              {/* Sort */}
-              <div>
-                <label className="text-xs text-text-tertiary uppercase tracking-wider">Sort By</label>
-                <select
-                  value={filters.sort_by || 'name'}
-                  onChange={e => updateFilter('sort_by', e.target.value)}
-                  className="mt-1 w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50"
-                >
-                  <option value="name">Name</option>
-                  <option value="cmc">CMC</option>
-                  <option value="tcg_price">Price</option>
-                  <option value="rarity">Rarity</option>
-                  <option value="set_code">Set</option>
-                  <option value="added_date">Date Added</option>
-                </select>
-              </div>
-            </div>
-          )}
-
-          {/* Scanner */}
-          <ScannerPanel onCardAdded={fetchCards} />
-        </div>
-
-        {/* Main content: card grid/list */}
-        <div className="flex-1 min-w-0">
-          {/* View toggle + pagination */}
-          <div className="flex items-center justify-between mb-4">
-            <div className="flex items-center gap-1 bg-bg-secondary rounded-lg border border-border-primary p-0.5">
-              <button
-                onClick={() => setViewMode('grid')}
-                className={`p-1.5 rounded-md transition-colors ${viewMode === 'grid' ? 'bg-bg-hover text-text-primary' : 'text-text-tertiary hover:text-text-secondary'}`}
-              >
-                <Grid3x3 className="w-4 h-4" />
-              </button>
-              <button
-                onClick={() => setViewMode('list')}
-                className={`p-1.5 rounded-md transition-colors ${viewMode === 'list' ? 'bg-bg-hover text-text-primary' : 'text-text-tertiary hover:text-text-secondary'}`}
-              >
-                <List className="w-4 h-4" />
-              </button>
-            </div>
-            <div className="flex items-center gap-2 text-sm text-text-secondary">
-              <span>Page {filters.page} of {totalPages || 1}</span>
-              <button
-                onClick={() => setFilters(p => ({ ...p, page: Math.max(1, (p.page || 1) - 1) }))}
-                disabled={!filters.page || filters.page <= 1}
-                className="p-1 rounded hover:bg-bg-hover disabled:opacity-30"
-              >
-                <ChevronLeft className="w-4 h-4" />
-              </button>
-              <button
-                onClick={() => setFilters(p => ({ ...p, page: Math.min(totalPages, (p.page || 1) + 1) }))}
-                disabled={(filters.page || 1) >= totalPages}
-                className="p-1 rounded hover:bg-bg-hover disabled:opacity-30"
-              >
-                <ChevronRight className="w-4 h-4" />
-              </button>
-            </div>
-          </div>
-
-          {loading ? (
-            <div className="flex items-center justify-center h-64">
-              <Spinner size="lg" className="text-accent-blue" />
-            </div>
-          ) : cards.length === 0 ? (
-            <EmptyState
-              icon={Package}
-              title="No cards found"
-              description="Try adjusting your search or filters, or import a collection."
-            />
-          ) : viewMode === 'grid' ? (
-            <div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5 xl:grid-cols-6 gap-3">
-              {cards.map(card => (
-                <div
-                  key={card.id}
-                  className="group cursor-pointer"
-                  onClick={() => setSelectedCard(card)}
-                >
-                  <CardImage src={card.image_url} alt={card.name} size="md" className="w-full h-auto aspect-[5/7]" />
-                  <div className="mt-1.5 px-0.5">
-                    <p className="text-xs font-medium text-text-primary truncate group-hover:text-accent-blue transition-colors">{card.name}</p>
-                    <div className="flex items-center justify-between">
-                      <span className="text-[10px] text-text-tertiary">{card.set_code.toUpperCase()}</span>
-                      {card.tcg_price != null && (
-                        <span className="text-[10px] text-accent-teal font-medium">${card.tcg_price.toFixed(2)}</span>
-                      )}
-                    </div>
-                  </div>
-                </div>
-              ))}
-            </div>
-          ) : (
-            <div className="bg-bg-secondary rounded-xl border border-border-primary overflow-hidden">
-              <table className="w-full text-sm">
-                <thead>
-                  <tr className="border-b border-border-primary text-left">
-                    <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Card</th>
-                    <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Type</th>
-                    <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Mana</th>
-                    <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Set</th>
-                    <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider">Qty</th>
-                    <th className="px-4 py-3 text-xs text-text-tertiary font-medium uppercase tracking-wider text-right">Price</th>
-                  </tr>
-                </thead>
-                <tbody className="divide-y divide-border-primary">
-                  {cards.map(card => (
-                    <tr key={card.id} className="hover:bg-bg-hover cursor-pointer transition-colors" onClick={() => setSelectedCard(card)}>
-                      <td className="px-4 py-2.5">
-                        <span className="font-medium text-text-primary">{card.name}</span>
-                      </td>
-                      <td className="px-4 py-2.5 text-text-secondary text-xs">{card.type_line}</td>
-                      <td className="px-4 py-2.5"><ManaSymbols cost={card.mana_cost} /></td>
-                      <td className="px-4 py-2.5 text-text-secondary text-xs">{card.set_code.toUpperCase()}</td>
-                      <td className="px-4 py-2.5 text-text-secondary">{card.quantity}</td>
-                      <td className="px-4 py-2.5 text-right text-accent-teal font-medium">{card.tcg_price != null ? `$${card.tcg_price.toFixed(2)}` : '—'}</td>
-                    </tr>
-                  ))}
-                </tbody>
-              </table>
-            </div>
-          )}
-        </div>
-      </div>
-
-      {/* Card detail modal */}
-      {selectedCard && <CardDetailModal card={selectedCard} onClose={() => setSelectedCard(null)} />}
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/pages/DecksPage.tsx

@@ -1,967 +0,0 @@
-import { useState, useEffect } from 'react'
-import {
-  Plus, Trash2, Download, ChevronRight,
-  BarChart3, Lightbulb, Layers, X, Library,
-  Globe, XCircle, ShoppingCart,
-  ChevronDown, ChevronUp, Sparkles
-} from 'lucide-react'
-import { Spinner, EmptyState, ManaSymbols, ColorDots } from '../components/common'
-import { decksApi } from '../api'
-import type {
-  Deck, DeckCard, DeckAnalysis,
-  EdhRecCard, EdhRecsResponse,
-  CollectionRecsResponse
-} from '../types'
-import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer, Cell } from 'recharts'
-
-// ── Role Badge ──────────────────────────────────────────────
-const ROLE_COLORS: Record<string, string> = {
-  Ramp: 'bg-green-500/15 text-green-400 border-green-500/25',
-  Draw: 'bg-blue-500/15 text-blue-400 border-blue-500/25',
-  Removal: 'bg-red-500/15 text-red-400 border-red-500/25',
-  BoardWipe: 'bg-orange-500/15 text-orange-400 border-orange-500/25',
-  Tutor: 'bg-purple-500/15 text-purple-400 border-purple-500/25',
-  Protection: 'bg-cyan-500/15 text-cyan-400 border-cyan-500/25',
-  Finisher: 'bg-yellow-500/15 text-yellow-400 border-yellow-500/25',
-  Recursion: 'bg-emerald-500/15 text-emerald-400 border-emerald-500/25',
-  Other: 'bg-slate-500/15 text-slate-400 border-slate-500/25',
-}
-
-function RoleBadge({ role }: { role: string }) {
-  const colors = ROLE_COLORS[role] || ROLE_COLORS.Other
-  return (
-    <span className={'text-[10px] font-medium px-1.5 py-0.5 rounded border ' + colors}>
-      {role}
-    </span>
-  )
-}
-
-// ── Deck Card List ────────────────────────────────────────────
-function DeckCardList({ deckId, cards, onUpdate }: { deckId: number; cards: DeckCard[]; onUpdate: () => void }) {
-  const [removing, setRemoving] = useState<number | null>(null)
-
-  // Group cards by category
-  const grouped = cards.reduce<Record<string, DeckCard[]>>((acc, c) => {
-    const cat = c.category || 'Other'
-    if (!acc[cat]) acc[cat] = []
-    acc[cat].push(c)
-    return acc
-  }, {})
-
-  const categoryOrder = ['Commander', 'Creature', 'Instant', 'Sorcery', 'Artifact', 'Enchantment', 'Planeswalker', 'Land', 'Other']
-  const sortedCategories = Object.keys(grouped).sort((a, b) => {
-    const ia = categoryOrder.indexOf(a)
-    const ib = categoryOrder.indexOf(b)
-    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib)
-  })
-
-  async function handleRemove(cardId: number) {
-    setRemoving(cardId)
-    try {
-      await decksApi.removeCardFromDeck(deckId, cardId)
-      onUpdate()
-    } catch { /* ignore */ }
-    setRemoving(null)
-  }
-
-  return (
-    <div className="space-y-4">
-      {sortedCategories.map(cat => (
-        <div key={cat}>
-          <h4 className="text-xs font-semibold text-text-tertiary uppercase tracking-wider mb-2">
-            {cat} ({grouped[cat].length})
-          </h4>
-          <div className="space-y-1">
-            {grouped[cat].map(card => (
-              <div key={card.id} className="flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-bg-hover group transition-colors">
-                <span className="text-xs text-text-tertiary w-5 text-right">{card.quantity}x</span>
-                <ManaSymbols cost={card.mana_cost} />
-                <span className="flex-1 text-sm text-text-primary truncate">{card.name}</span>
-                {card.tcg_price != null && (
-                  <span className="text-xs text-accent-teal">${card.tcg_price.toFixed(2)}</span>
-                )}
-                {!card.is_commander && (
-                  <button
-                    onClick={() => handleRemove(card.id)}
-                    className="opacity-0 group-hover:opacity-100 p-1 text-text-tertiary hover:text-accent-red transition-all"
-                  >
-                    {removing === card.id ? <Spinner size="sm" /> : <Trash2 className="w-3.5 h-3.5" />}
-                  </button>
-                )}
-              </div>
-            ))}
-          </div>
-        </div>
-      ))}
-    </div>
-  )
-}
-
-// ── Mana Curve Chart ──────────────────────────────────────────
-function ManaCurveChart({ analysis }: { analysis: DeckAnalysis }) {
-  const data = Object.entries(analysis.mana_curve)
-    .map(([cmc, count]) => ({ cmc: cmc === '7' ? '7+' : cmc, count }))
-    .sort((a, b) => Number(a.cmc) - Number(b.cmc))
-
-  return (
-    <div className="h-40">
-      <ResponsiveContainer width="100%" height="100%">
-        <BarChart data={data} barSize={24}>
-          <XAxis dataKey="cmc" axisLine={false} tickLine={false} tick={{ fill: '#6b7190', fontSize: 11 }} />
-          <YAxis hide />
-          <Tooltip
-            contentStyle={{ backgroundColor: '#1c2030', border: '1px solid #2a2f42', borderRadius: 8, fontSize: 12 }}
-            labelStyle={{ color: '#9ba1b8' }}
-            itemStyle={{ color: '#e8eaf0' }}
-          />
-          <Bar dataKey="count" radius={[4, 4, 0, 0]}>
-            {data.map((_, i) => (
-              <Cell key={i} fill="#4f6ef7" fillOpacity={0.8} />
-            ))}
-          </Bar>
-        </BarChart>
-      </ResponsiveContainer>
-    </div>
-  )
-}
-
-// ── EDHREC Recommendations Sub-tab ──────────────────────────
-function EdhRecTab({ deckId, onAddedCards }: { deckId: number; onAddedCards: () => void }) {
-  const [data, setData] = useState<EdhRecsResponse | null>(null)
-  const [loading, setLoading] = useState(true)
-  const [error, setError] = useState<string | null>(null)
-  const [onlyOwned, setOnlyOwned] = useState(false)
-  const [selectedCards, setSelectedCards] = useState<Set<string>>(new Set())
-  const [addingCards, setAddingCards] = useState<Set<string>>(new Set())
-  const [bulkAdding, setBulkAdding] = useState(false)
-  const [hoveredCard, setHoveredCard] = useState<EdhRecCard | null>(null)
-  const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(new Set())
-
-  async function fetchRecs() {
-    setLoading(true)
-    setError(null)
-    try {
-      const result = await decksApi.getEdhRecs(deckId, onlyOwned)
-      setData(result)
-    } catch (e: any) {
-      setError(e?.message || 'Failed to load EDHREC recommendations')
-    }
-    setLoading(false)
-  }
-
-  useEffect(() => { fetchRecs() }, [deckId, onlyOwned])
-
-  function toggleSelect(name: string) {
-    setSelectedCards(prev => {
-      const next = new Set(prev)
-      if (next.has(name)) next.delete(name)
-      else next.add(name)
-      return next
-    })
-  }
-
-  function selectAll() {
-    if (!data) return
-    setSelectedCards(new Set(data.recommendations.map(r => r.name)))
-  }
-
-  function selectNone() { setSelectedCards(new Set()) }
-
-  function selectOwned() {
-    if (!data) return
-    setSelectedCards(new Set(data.recommendations.filter(r => r.owned).map(r => r.name)))
-  }
-
-  async function handleAddSingle(name: string) {
-    setAddingCards(prev => new Set(prev).add(name))
-    try {
-      await decksApi.bulkAddRecommended(deckId, [name])
-      onAddedCards()
-      // Remove from list
-      if (data) {
-        setData({
-          ...data,
-          recommendations: data.recommendations.filter(r => r.name !== name),
-          total: data.total - 1,
-        })
-      }
-      selectedCards.delete(name)
-      setSelectedCards(new Set(selectedCards))
-    } catch { /* ignore */ }
-    setAddingCards(prev => { const n = new Set(prev); n.delete(name); return n })
-  }
-
-  async function handleBulkAdd() {
-    if (selectedCards.size === 0) return
-    setBulkAdding(true)
-    try {
-      await decksApi.bulkAddRecommended(deckId, Array.from(selectedCards))
-      onAddedCards()
-      if (data) {
-        setData({
-          ...data,
-          recommendations: data.recommendations.filter(r => !selectedCards.has(r.name)),
-          total: data.total - selectedCards.size,
-        })
-      }
-      setSelectedCards(new Set())
-    } catch { /* ignore */ }
-    setBulkAdding(false)
-  }
-
-  function toggleGroup(groupName: string) {
-    setCollapsedGroups(prev => {
-      const next = new Set(prev)
-      if (next.has(groupName)) next.delete(groupName)
-      else next.add(groupName)
-      return next
-    })
-  }
-
-  // Group recommendations by role
-  function groupByRole(recs: EdhRecCard[]): Record<string, EdhRecCard[]> {
-    const groups: Record<string, EdhRecCard[]> = {}
-    for (const rec of recs) {
-      const role = rec.role || 'Other'
-      if (!groups[role]) groups[role] = []
-      groups[role].push(rec)
-    }
-    return groups
-  }
-
-  if (loading) {
-    return <div className="flex items-center justify-center h-40"><Spinner size="lg" className="text-accent-blue" /></div>
-  }
-
-  if (error) {
-    return (
-      <div className="bg-accent-red/10 border border-accent-red/20 rounded-xl p-5 text-center">
-        <XCircle className="w-6 h-6 text-accent-red mx-auto mb-2" />
-        <p className="text-sm text-accent-red font-medium">{error}</p>
-        <button onClick={fetchRecs} className="mt-3 px-4 py-2 text-xs font-medium bg-bg-tertiary text-text-secondary rounded-lg hover:bg-bg-hover border border-border-primary transition-colors">
-          Retry
-        </button>
-      </div>
-    )
-  }
-
-  if (!data || data.recommendations.length === 0) {
-    return <EmptyState icon={Globe} title="No EDHREC data" description="No recommendations found for this commander on EDHREC." />
-  }
-
-  const grouped = groupByRole(data.recommendations)
-  const roleOrder = ['Ramp', 'Draw', 'Removal', 'BoardWipe', 'Tutor', 'Protection', 'Finisher', 'Recursion', 'Other']
-  const sortedRoles = Object.keys(grouped).sort((a, b) => {
-    const ia = roleOrder.indexOf(a)
-    const ib = roleOrder.indexOf(b)
-    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib)
-  })
-
-  const ownedCount = data.recommendations.filter(r => r.owned).length
-  const missingCount = data.recommendations.length - ownedCount
-
-  return (
-    <div className="space-y-4">
-      {/* Header bar */}
-      <div className="flex items-center justify-between flex-wrap gap-3">
-        <div className="flex items-center gap-3">
-          <div className="flex items-center gap-2 text-sm">
-            <Sparkles className="w-4 h-4 text-accent-blue" />
-            <span className="text-text-primary font-medium">{data.commander}</span>
-            <span className="text-text-tertiary">via {data.source}</span>
-          </div>
-          <span className="text-xs px-2 py-0.5 rounded bg-accent-green/15 text-accent-green">{ownedCount} owned</span>
-          <span className="text-xs px-2 py-0.5 rounded bg-bg-tertiary text-text-tertiary">{missingCount} missing</span>
-        </div>
-        <label className="flex items-center gap-2 text-xs text-text-secondary cursor-pointer select-none">
-          <input
-            type="checkbox"
-            checked={onlyOwned}
-            onChange={e => setOnlyOwned(e.target.checked)}
-            className="rounded border-border-primary bg-bg-tertiary text-accent-blue focus:ring-accent-blue/30 w-3.5 h-3.5"
-          />
-          Show only owned
-        </label>
-      </div>
-
-      {/* Selection toolbar */}
-      <div className="flex items-center justify-between bg-bg-secondary rounded-xl border border-border-primary px-4 py-3">
-        <div className="flex items-center gap-2">
-          <span className="text-xs text-text-tertiary">Select:</span>
-          <button onClick={selectAll} className="text-xs text-accent-blue hover:underline">All</button>
-          <span className="text-text-tertiary">/</span>
-          <button onClick={selectNone} className="text-xs text-accent-blue hover:underline">None</button>
-          <span className="text-text-tertiary">/</span>
-          <button onClick={selectOwned} className="text-xs text-accent-blue hover:underline">Owned</button>
-          {selectedCards.size > 0 && (
-            <span className="text-xs text-text-secondary ml-2">({selectedCards.size} selected)</span>
-          )}
-        </div>
-        <button
-          onClick={handleBulkAdd}
-          disabled={selectedCards.size === 0 || bulkAdding}
-          className="flex items-center gap-2 px-3 py-1.5 text-xs font-medium bg-accent-blue text-white rounded-lg hover:bg-accent-blue-hover transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
-        >
-          {bulkAdding ? <Spinner size="sm" /> : <ShoppingCart className="w-3.5 h-3.5" />}
-          Add {selectedCards.size > 0 ? selectedCards.size : ''} to Deck
-        </button>
-      </div>
-
-      {/* Grouped cards */}
-      {sortedRoles.map(role => {
-        const cards = grouped[role]
-        const isCollapsed = collapsedGroups.has(role)
-        return (
-          <div key={role} className="bg-bg-secondary rounded-xl border border-border-primary overflow-hidden">
-            {/* Group header */}
-            <button
-              onClick={() => toggleGroup(role)}
-              className="w-full flex items-center justify-between px-4 py-3 hover:bg-bg-hover transition-colors"
-            >
-              <div className="flex items-center gap-2">
-                <RoleBadge role={role} />
-                <span className="text-xs text-text-tertiary">({cards.length})</span>
-              </div>
-              {isCollapsed ? <ChevronDown className="w-4 h-4 text-text-tertiary" /> : <ChevronUp className="w-4 h-4 text-text-tertiary" />}
-            </button>
-            {/* Card list */}
-            {!isCollapsed && (
-              <div className="border-t border-border-primary divide-y divide-border-primary">
-                {cards.map(rec => (
-                  <div
-                    key={rec.name}
-                    className="flex items-center gap-3 px-4 py-2.5 hover:bg-bg-hover transition-colors group relative"
-                    onMouseEnter={() => setHoveredCard(rec)}
-                    onMouseLeave={() => setHoveredCard(null)}
-                  >
-                    {/* Checkbox */}
-                    <input
-                      type="checkbox"
-                      checked={selectedCards.has(rec.name)}
-                      onChange={() => toggleSelect(rec.name)}
-                      className="rounded border-border-primary bg-bg-tertiary text-accent-blue focus:ring-accent-blue/30 w-3.5 h-3.5 flex-shrink-0"
-                    />
-                    {/* Card image mini */}
-                    {rec.image_url && (
-                      <div className="w-8 h-11 rounded overflow-hidden bg-bg-tertiary flex-shrink-0">
-                        <img src={rec.image_url} alt={rec.name} className="w-full h-full object-cover" loading="lazy" />
-                      </div>
-                    )}
-                    {/* Card info */}
-                    <div className="flex-1 min-w-0">
-                      <p className="text-sm font-medium text-text-primary truncate">{rec.name}</p>
-                      <div className="flex items-center gap-1.5 mt-0.5">
-                        <span className="text-[10px] text-text-tertiary truncate">{rec.type_line}</span>
-                        {rec.roles.length > 0 && rec.roles.map(r => <RoleBadge key={r} role={r} />)}
-                      </div>
-                    </div>
-                    {/* Owned badge */}
-                    <span className={'text-xs px-2 py-0.5 rounded flex-shrink-0 ' + (rec.owned ? 'bg-accent-green/15 text-accent-green' : 'bg-bg-tertiary text-text-tertiary')}>
-                      {rec.owned ? (rec.owned_qty + 'x owned') : 'Missing'}
-                    </span>
-                    {/* Add button */}
-                    <button
-                      onClick={e => { e.stopPropagation(); handleAddSingle(rec.name) }}
-                      disabled={addingCards.has(rec.name)}
-                      className="opacity-0 group-hover:opacity-100 px-2.5 py-1 text-xs font-medium bg-accent-blue text-white rounded-lg hover:bg-accent-blue-hover transition-all disabled:opacity-50 flex-shrink-0"
-                    >
-                      {addingCards.has(rec.name) ? <Spinner size="sm" /> : '+ Add'}
-                    </button>
-                  </div>
-                ))}
-              </div>
-            )}
-          </div>
-        )
-      })}
-
-      {/* Hover preview */}
-      {hoveredCard && hoveredCard.image_url && (
-        <div className="fixed top-20 right-8 z-50 pointer-events-none animate-fade-in">
-          <img
-            src={hoveredCard.image_url}
-            alt={hoveredCard.name}
-            className="w-[244px] rounded-xl shadow-2xl shadow-black/60 border border-border-primary"
-          />
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ── Collection Recommendations Sub-tab ──────────────────────
-function CollectionRecTab({ deckId, onAddedCards }: { deckId: number; onAddedCards: () => void }) {
-  const [data, setData] = useState<CollectionRecsResponse | null>(null)
-  const [loading, setLoading] = useState(true)
-  const [error, setError] = useState<string | null>(null)
-  const [selectedCards, setSelectedCards] = useState<Set<string>>(new Set())
-  const [addingCards, setAddingCards] = useState<Set<string>>(new Set())
-  const [bulkAdding, setBulkAdding] = useState(false)
-  const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(new Set())
-
-  async function fetchRecs() {
-    setLoading(true)
-    setError(null)
-    try {
-      const result = await decksApi.getCollectionRecs(deckId)
-      setData(result)
-    } catch (e: any) {
-      setError(e?.message || 'Failed to load collection recommendations')
-    }
-    setLoading(false)
-  }
-
-  useEffect(() => { fetchRecs() }, [deckId])
-
-  function toggleSelect(name: string) {
-    setSelectedCards(prev => {
-      const next = new Set(prev)
-      if (next.has(name)) next.delete(name)
-      else next.add(name)
-      return next
-    })
-  }
-
-  function selectAll() {
-    if (!data) return
-    const all = new Set<string>()
-    Object.values(data.grouped).flat().forEach(c => all.add(c.name))
-    setSelectedCards(all)
-  }
-
-  function selectNone() { setSelectedCards(new Set()) }
-
-  async function handleAddSingle(name: string) {
-    setAddingCards(prev => new Set(prev).add(name))
-    try {
-      await decksApi.bulkAddRecommended(deckId, [name])
-      onAddedCards()
-      // Remove from groupings
-      if (data) {
-        const newGrouped = { ...data.grouped }
-        for (const key of Object.keys(newGrouped)) {
-          newGrouped[key] = newGrouped[key].filter(c => c.name !== name)
-          if (newGrouped[key].length === 0) delete newGrouped[key]
-        }
-        setData({ ...data, grouped: newGrouped, total: data.total - 1 })
-      }
-      selectedCards.delete(name)
-      setSelectedCards(new Set(selectedCards))
-    } catch { /* ignore */ }
-    setAddingCards(prev => { const n = new Set(prev); n.delete(name); return n })
-  }
-
-  async function handleBulkAdd() {
-    if (selectedCards.size === 0) return
-    setBulkAdding(true)
-    try {
-      await decksApi.bulkAddRecommended(deckId, Array.from(selectedCards))
-      onAddedCards()
-      if (data) {
-        const newGrouped = { ...data.grouped }
-        for (const key of Object.keys(newGrouped)) {
-          newGrouped[key] = newGrouped[key].filter(c => !selectedCards.has(c.name))
-          if (newGrouped[key].length === 0) delete newGrouped[key]
-        }
-        setData({ ...data, grouped: newGrouped, total: data.total - selectedCards.size })
-      }
-      setSelectedCards(new Set())
-    } catch { /* ignore */ }
-    setBulkAdding(false)
-  }
-
-  function toggleGroup(groupName: string) {
-    setCollapsedGroups(prev => {
-      const next = new Set(prev)
-      if (next.has(groupName)) next.delete(groupName)
-      else next.add(groupName)
-      return next
-    })
-  }
-
-  if (loading) {
-    return <div className="flex items-center justify-center h-40"><Spinner size="lg" className="text-accent-blue" /></div>
-  }
-
-  if (error) {
-    return (
-      <div className="bg-accent-red/10 border border-accent-red/20 rounded-xl p-5 text-center">
-        <XCircle className="w-6 h-6 text-accent-red mx-auto mb-2" />
-        <p className="text-sm text-accent-red font-medium">{error}</p>
-        <button onClick={fetchRecs} className="mt-3 px-4 py-2 text-xs font-medium bg-bg-tertiary text-text-secondary rounded-lg hover:bg-bg-hover border border-border-primary transition-colors">
-          Retry
-        </button>
-      </div>
-    )
-  }
-
-  if (!data || data.total === 0) {
-    return <EmptyState icon={Library} title="No collection matches" description="No cards in your collection match this deck's needs." />
-  }
-
-  const typeOrder = ['Creature', 'Instant', 'Sorcery', 'Artifact', 'Enchantment', 'Planeswalker', 'Land', 'Other']
-  const sortedTypes = Object.keys(data.grouped).sort((a, b) => {
-    const ia = typeOrder.indexOf(a)
-    const ib = typeOrder.indexOf(b)
-    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib)
-  })
-
-  return (
-    <div className="space-y-4">
-      {/* Shortfall alert */}
-      {data.shortfall_types.length > 0 && (
-        <div className="flex items-start gap-3 bg-accent-blue/8 border border-accent-blue/20 rounded-xl px-4 py-3">
-          <Lightbulb className="w-4 h-4 text-accent-blue mt-0.5 flex-shrink-0" />
-          <div>
-            <p className="text-xs font-medium text-accent-blue">Deck needs more:</p>
-            <div className="flex flex-wrap gap-1.5 mt-1">
-              {data.shortfall_types.map(t => (
-                <span key={t} className="text-[10px] font-medium px-2 py-0.5 rounded bg-accent-blue/15 text-accent-blue border border-accent-blue/25">{t}</span>
-              ))}
-            </div>
-          </div>
-        </div>
-      )}
-
-      {/* Selection toolbar */}
-      <div className="flex items-center justify-between bg-bg-secondary rounded-xl border border-border-primary px-4 py-3">
-        <div className="flex items-center gap-2">
-          <span className="text-xs text-text-tertiary">Select:</span>
-          <button onClick={selectAll} className="text-xs text-accent-blue hover:underline">All</button>
-          <span className="text-text-tertiary">/</span>
-          <button onClick={selectNone} className="text-xs text-accent-blue hover:underline">None</button>
-          {selectedCards.size > 0 && (
-            <span className="text-xs text-text-secondary ml-2">({selectedCards.size} selected)</span>
-          )}
-        </div>
-        <button
-          onClick={handleBulkAdd}
-          disabled={selectedCards.size === 0 || bulkAdding}
-          className="flex items-center gap-2 px-3 py-1.5 text-xs font-medium bg-accent-blue text-white rounded-lg hover:bg-accent-blue-hover transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
-        >
-          {bulkAdding ? <Spinner size="sm" /> : <ShoppingCart className="w-3.5 h-3.5" />}
-          Add {selectedCards.size > 0 ? selectedCards.size : ''} to Deck
-        </button>
-      </div>
-
-      {/* Grouped cards */}
-      {sortedTypes.map(type => {
-        const cards = data.grouped[type]
-        const isCollapsed = collapsedGroups.has(type)
-        const isShortfall = data.shortfall_types.includes(type)
-        return (
-          <div key={type} className={'bg-bg-secondary rounded-xl border overflow-hidden ' + (isShortfall ? 'border-accent-blue/30' : 'border-border-primary')}>
-            {/* Group header */}
-            <button
-              onClick={() => toggleGroup(type)}
-              className="w-full flex items-center justify-between px-4 py-3 hover:bg-bg-hover transition-colors"
-            >
-              <div className="flex items-center gap-2">
-                <span className="text-xs font-semibold text-text-primary uppercase tracking-wider">{type}</span>
-                <span className="text-xs text-text-tertiary">({cards.length})</span>
-                {isShortfall && <span className="text-[10px] font-medium px-1.5 py-0.5 rounded bg-accent-blue/15 text-accent-blue border border-accent-blue/25">Shortfall</span>}
-              </div>
-              {isCollapsed ? <ChevronDown className="w-4 h-4 text-text-tertiary" /> : <ChevronUp className="w-4 h-4 text-text-tertiary" />}
-            </button>
-            {/* Card list */}
-            {!isCollapsed && (
-              <div className="border-t border-border-primary divide-y divide-border-primary">
-                {cards.map(rec => (
-                  <div key={rec.scryfall_id} className="flex items-center gap-3 px-4 py-2.5 hover:bg-bg-hover transition-colors group">
-                    {/* Checkbox */}
-                    <input
-                      type="checkbox"
-                      checked={selectedCards.has(rec.name)}
-                      onChange={() => toggleSelect(rec.name)}
-                      className="rounded border-border-primary bg-bg-tertiary text-accent-blue focus:ring-accent-blue/30 w-3.5 h-3.5 flex-shrink-0"
-                    />
-                    {/* Card image mini */}
-                    {rec.image_url && (
-                      <div className="w-8 h-11 rounded overflow-hidden bg-bg-tertiary flex-shrink-0">
-                        <img src={rec.image_url} alt={rec.name} className="w-full h-full object-cover" loading="lazy" />
-                      </div>
-                    )}
-                    {/* Card info */}
-                    <div className="flex-1 min-w-0">
-                      <p className="text-sm font-medium text-text-primary truncate">{rec.name}</p>
-                      <div className="flex items-center gap-1.5 mt-0.5">
-                        <span className="text-[10px] text-text-tertiary">{rec.cmc} CMC</span>
-                        {rec.roles.length > 0 && rec.roles.map(r => <RoleBadge key={r} role={r} />)}
-                      </div>
-                    </div>
-                    {/* Score */}
-                    <span className="text-xs text-accent-teal font-medium flex-shrink-0">Score: {rec.score}</span>
-                    {/* Owned qty */}
-                    <span className="text-xs px-2 py-0.5 rounded bg-accent-green/15 text-accent-green flex-shrink-0">{rec.owned_qty}x</span>
-                    {/* Add button */}
-                    <button
-                      onClick={e => { e.stopPropagation(); handleAddSingle(rec.name) }}
-                      disabled={addingCards.has(rec.name)}
-                      className="opacity-0 group-hover:opacity-100 px-2.5 py-1 text-xs font-medium bg-accent-blue text-white rounded-lg hover:bg-accent-blue-hover transition-all disabled:opacity-50 flex-shrink-0"
-                    >
-                      {addingCards.has(rec.name) ? <Spinner size="sm" /> : '+ Add'}
-                    </button>
-                  </div>
-                ))}
-              </div>
-            )}
-          </div>
-        )
-      })}
-    </div>
-  )
-}
-
-// ── Deck Detail View ──────────────────────────────────────────
-function DeckDetail({ deck, onBack }: { deck: Deck; onBack: () => void }) {
-  const [cards, setCards] = useState<DeckCard[]>([])
-  const [analysis, setAnalysis] = useState<DeckAnalysis | null>(null)
-  const [loading, setLoading] = useState(true)
-  const [tab, setTab] = useState<'cards' | 'analysis' | 'recs'>('cards')
-  const [recSource, setRecSource] = useState<'edhrec' | 'collection'>('edhrec')
-  const [addingCard, setAddingCard] = useState('')
-  const [bulkText, setBulkText] = useState('')
-  const [showBulk, setShowBulk] = useState(false)
-
-  async function fetchAll() {
-    setLoading(true)
-    try {
-      const [c, a] = await Promise.all([
-        decksApi.getDeckCards(deck.id),
-        decksApi.getDeckAnalysis(deck.id),
-      ])
-      setCards(c)
-      setAnalysis(a)
-    } catch { /* ignore */ }
-    setLoading(false)
-  }
-
-  useEffect(() => { fetchAll() }, [deck.id])
-
-  async function handleAddCard() {
-    if (!addingCard.trim()) return
-    try {
-      await decksApi.addCardToDeck(deck.id, { name: addingCard.trim() })
-      setAddingCard('')
-      fetchAll()
-    } catch { /* ignore */ }
-  }
-
-  async function handleBulkAdd() {
-    if (!bulkText.trim()) return
-    const cardLines = bulkText.split('\n').filter(l => l.trim())
-    const cardParsed = cardLines.map(l => {
-      const match = l.match(/^(\d+)x?\s+(.+)$/)
-      return match ? { name: match[2].trim(), quantity: Number(match[1]) } : { name: l.trim() }
-    })
-    try {
-      await decksApi.bulkAddCards(deck.id, cardParsed)
-      setBulkText('')
-      setShowBulk(false)
-      fetchAll()
-    } catch { /* ignore */ }
-  }
-
-  async function handleExportToSim() {
-    try {
-      await decksApi.exportDeckToSim(deck.id)
-    } catch { /* ignore */ }
-  }
-
-  return (
-    <div className="space-y-5">
-      {/* Header */}
-      <div className="flex items-center gap-4">
-        <button onClick={onBack} className="p-2 rounded-lg hover:bg-bg-hover text-text-secondary transition-colors">
-          <ChevronRight className="w-5 h-5 rotate-180" />
-        </button>
-        <div className="flex-1">
-          <h2 className="text-xl font-bold text-text-primary">{deck.name}</h2>
-          <div className="flex items-center gap-3 mt-1">
-            <span className="text-sm text-text-secondary">{deck.commander}</span>
-            <ColorDots colors={deck.color_identity} />
-            <span className="text-xs text-text-tertiary">{deck.card_count} cards</span>
-            <span className="text-xs text-accent-teal">${deck.total_price.toFixed(2)}</span>
-          </div>
-        </div>
-        <button onClick={handleExportToSim}
-          className="flex items-center gap-2 px-3 py-2 text-xs font-medium bg-bg-tertiary text-text-secondary rounded-lg hover:bg-bg-hover border border-border-primary transition-colors">
-          <Download className="w-3.5 h-3.5" />
-          Export to Sim
-        </button>
-      </div>
-
-      {/* Tabs */}
-      <div className="flex gap-1 border-b border-border-primary">
-        {(['cards', 'analysis', 'recs'] as const).map(t => (
-          <button
-            key={t}
-            onClick={() => setTab(t)}
-            className={`px-4 py-2.5 text-sm font-medium border-b-2 transition-colors capitalize ${
-              tab === t
-                ? 'border-accent-blue text-accent-blue'
-                : 'border-transparent text-text-tertiary hover:text-text-secondary'
-            }`}
-          >
-            {t === 'recs' ? 'Recommendations' : t}
-          </button>
-        ))}
-      </div>
-
-      {loading ? (
-        <div className="flex items-center justify-center h-40"><Spinner size="lg" className="text-accent-blue" /></div>
-      ) : tab === 'cards' ? (
-        <div className="space-y-4">
-          {/* Add card */}
-          <div className="flex items-center gap-2">
-            <input
-              type="text"
-              placeholder="Add card by name..."
-              value={addingCard}
-              onChange={e => setAddingCard(e.target.value)}
-              onKeyDown={e => e.key === 'Enter' && handleAddCard()}
-              className="flex-1 px-4 py-2.5 bg-bg-secondary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-            />
-            <button onClick={handleAddCard}
-              className="px-4 py-2.5 bg-accent-blue text-white text-sm font-medium rounded-lg hover:bg-accent-blue-hover transition-colors">
-              Add
-            </button>
-            <button onClick={() => setShowBulk(!showBulk)}
-              className="px-3 py-2.5 bg-bg-tertiary text-text-secondary text-sm rounded-lg hover:bg-bg-hover border border-border-primary transition-colors">
-              <Layers className="w-4 h-4" />
-            </button>
-          </div>
-          {showBulk && (
-            <div className="bg-bg-secondary rounded-xl border border-border-primary p-4 animate-fade-in space-y-3">
-              <textarea
-                placeholder={"1x Sol Ring\n1x Command Tower\n2x Counterspell"}
-                value={bulkText}
-                onChange={e => setBulkText(e.target.value)}
-                rows={6}
-                className="w-full px-4 py-3 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary font-mono focus:outline-none focus:border-accent-blue/50 transition-all resize-none"
-              />
-              <button onClick={handleBulkAdd}
-                className="px-4 py-2 bg-accent-blue text-white text-sm font-medium rounded-lg hover:bg-accent-blue-hover transition-colors">
-                Bulk Add
-              </button>
-            </div>
-          )}
-          <DeckCardList deckId={deck.id} cards={cards} onUpdate={fetchAll} />
-        </div>
-      ) : tab === 'analysis' && analysis ? (
-        <div className="grid grid-cols-1 md:grid-cols-2 gap-5">
-          {/* Stats */}
-          <div className="bg-bg-secondary rounded-xl border border-border-primary p-5 space-y-4">
-            <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
-              <BarChart3 className="w-4 h-4 text-accent-blue" />
-              Deck Stats
-            </h3>
-            <div className="grid grid-cols-2 gap-3">
-              {[
-                { label: 'Cards', value: analysis.card_count },
-                { label: 'Lands', value: analysis.land_count },
-                { label: 'Creatures', value: analysis.creature_count },
-                { label: 'Non-Creature', value: analysis.noncreature_count },
-                { label: 'Avg CMC', value: analysis.avg_cmc.toFixed(2) },
-                { label: 'Owned', value: `${analysis.owned_count} / ${analysis.card_count}` },
-              ].map(stat => (
-                <div key={stat.label} className="px-3 py-2 rounded-lg bg-bg-tertiary">
-                  <p className="text-xs text-text-tertiary">{stat.label}</p>
-                  <p className="text-lg font-bold text-text-primary">{stat.value}</p>
-                </div>
-              ))}
-            </div>
-          </div>
-          {/* Mana Curve */}
-          <div className="bg-bg-secondary rounded-xl border border-border-primary p-5 space-y-4">
-            <h3 className="text-sm font-semibold text-text-primary">Mana Curve</h3>
-            <ManaCurveChart analysis={analysis} />
-          </div>
-          {/* Type Distribution */}
-          <div className="bg-bg-secondary rounded-xl border border-border-primary p-5 space-y-3 md:col-span-2">
-            <h3 className="text-sm font-semibold text-text-primary">Type Distribution</h3>
-            <div className="flex flex-wrap gap-2">
-              {Object.entries(analysis.type_distribution).map(([type, count]) => (
-                <span key={type} className="px-3 py-1.5 bg-bg-tertiary rounded-lg text-xs text-text-secondary">
-                  {type}: <span className="font-semibold text-text-primary">{count}</span>
-                </span>
-              ))}
-            </div>
-          </div>
-        </div>
-      ) : tab === 'recs' ? (
-        <div className="space-y-4">
-          {/* Sub-tab toggle */}
-          <div className="flex items-center gap-1 bg-bg-tertiary rounded-lg p-1 w-fit">
-            <button
-              onClick={() => setRecSource('edhrec')}
-              className={'flex items-center gap-1.5 px-3.5 py-2 text-xs font-medium rounded-md transition-all ' +
-                (recSource === 'edhrec'
-                  ? 'bg-accent-blue text-white shadow-sm'
-                  : 'text-text-tertiary hover:text-text-secondary')}
-            >
-              <Globe className="w-3.5 h-3.5" />
-              EDHREC
-            </button>
-            <button
-              onClick={() => setRecSource('collection')}
-              className={'flex items-center gap-1.5 px-3.5 py-2 text-xs font-medium rounded-md transition-all ' +
-                (recSource === 'collection'
-                  ? 'bg-accent-blue text-white shadow-sm'
-                  : 'text-text-tertiary hover:text-text-secondary')}
-            >
-              <Library className="w-3.5 h-3.5" />
-              From Collection
-            </button>
-          </div>
-
-          {/* Sub-tab content */}
-          {recSource === 'edhrec' ? (
-            <EdhRecTab deckId={deck.id} onAddedCards={fetchAll} />
-          ) : (
-            <CollectionRecTab deckId={deck.id} onAddedCards={fetchAll} />
-          )}
-        </div>
-      ) : null}
-    </div>
-  )
-}
-
-// ── Main Decks Page ───────────────────────────────────────────
-export function DecksPage() {
-  const [decks, setDecks] = useState<Deck[]>([])
-  const [loading, setLoading] = useState(true)
-  const [selectedDeck, setSelectedDeck] = useState<Deck | null>(null)
-  const [showCreate, setShowCreate] = useState(false)
-  const [newDeckName, setNewDeckName] = useState('')
-  const [newCommander, setNewCommander] = useState('')
-  const [creating, setCreating] = useState(false)
-
-  async function fetchDecks() {
-    setLoading(true)
-    try {
-      const d = await decksApi.listDecks()
-      setDecks(d)
-    } catch { /* ignore */ }
-    setLoading(false)
-  }
-
-  useEffect(() => { fetchDecks() }, [])
-
-  async function handleCreate() {
-    if (!newDeckName.trim()) return
-    setCreating(true)
-    try {
-      const deck = await decksApi.createDeck({ name: newDeckName.trim(), commander: newCommander.trim() || undefined })
-      setNewDeckName('')
-      setNewCommander('')
-      setShowCreate(false)
-      setSelectedDeck(deck)
-      fetchDecks()
-    } catch { /* ignore */ }
-    setCreating(false)
-  }
-
-  async function handleDelete(deckId: number) {
-    try {
-      await decksApi.deleteDeck(deckId)
-      fetchDecks()
-    } catch { /* ignore */ }
-  }
-
-  if (selectedDeck) {
-    return (
-      <div className="p-6">
-        <DeckDetail deck={selectedDeck} onBack={() => { setSelectedDeck(null); fetchDecks() }} />
-      </div>
-    )
-  }
-
-  return (
-    <div className="p-6 space-y-5">
-      {/* Header */}
-      <div className="flex items-center justify-between">
-        <div>
-          <h1 className="text-2xl font-bold text-text-primary">Decks</h1>
-          <p className="text-sm text-text-secondary mt-0.5">{decks.length} deck{decks.length !== 1 ? 's' : ''}</p>
-        </div>
-        <button
-          onClick={() => setShowCreate(true)}
-          className="flex items-center gap-2 px-4 py-2.5 bg-accent-blue text-white text-sm font-medium rounded-lg hover:bg-accent-blue-hover transition-colors"
-        >
-          <Plus className="w-4 h-4" />
-          New Deck
-        </button>
-      </div>
-
-      {/* Create form */}
-      {showCreate && (
-        <div className="bg-bg-secondary rounded-xl border border-border-primary p-5 animate-fade-in space-y-3">
-          <div className="flex items-center justify-between">
-            <h3 className="text-sm font-semibold text-text-primary">Create New Deck</h3>
-            <button onClick={() => setShowCreate(false)} className="text-text-tertiary hover:text-text-secondary">
-              <X className="w-4 h-4" />
-            </button>
-          </div>
-          <div className="grid grid-cols-2 gap-3">
-            <input
-              type="text"
-              placeholder="Deck name"
-              value={newDeckName}
-              onChange={e => setNewDeckName(e.target.value)}
-              className="px-4 py-2.5 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-            />
-            <input
-              type="text"
-              placeholder="Commander (optional)"
-              value={newCommander}
-              onChange={e => setNewCommander(e.target.value)}
-              className="px-4 py-2.5 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-            />
-          </div>
-          <button onClick={handleCreate} disabled={creating}
-            className="px-4 py-2 bg-accent-blue text-white text-sm font-medium rounded-lg hover:bg-accent-blue-hover transition-colors disabled:opacity-50">
-            {creating ? <Spinner size="sm" /> : 'Create'}
-          </button>
-        </div>
-      )}
-
-      {/* Deck list */}
-      {loading ? (
-        <div className="flex items-center justify-center h-40"><Spinner size="lg" className="text-accent-blue" /></div>
-      ) : decks.length === 0 ? (
-        <EmptyState icon={Layers} title="No decks yet" description="Create your first deck to get started." />
-      ) : (
-        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-          {decks.map(deck => (
-            <div
-              key={deck.id}
-              className="bg-bg-secondary rounded-xl border border-border-primary hover:border-border-secondary p-5 cursor-pointer transition-all group"
-              onClick={() => setSelectedDeck(deck)}
-            >
-              <div className="flex items-start justify-between mb-3">
-                <div className="min-w-0 flex-1">
-                  <h3 className="text-base font-semibold text-text-primary truncate group-hover:text-accent-blue transition-colors">{deck.name}</h3>
-                  <p className="text-sm text-text-secondary mt-0.5 truncate">{deck.commander}</p>
-                </div>
-                <button
-                  onClick={e => { e.stopPropagation(); handleDelete(deck.id) }}
-                  className="opacity-0 group-hover:opacity-100 p-1.5 text-text-tertiary hover:text-accent-red transition-all"
-                >
-                  <Trash2 className="w-3.5 h-3.5" />
-                </button>
-              </div>
-              <div className="flex items-center justify-between">
-                <div className="flex items-center gap-3">
-                  <ColorDots colors={deck.color_identity} />
-                  <span className="text-xs text-text-tertiary">{deck.card_count} cards</span>
-                </div>
-                <span className="text-xs font-medium text-accent-teal">${deck.total_price.toFixed(2)}</span>
-              </div>
-            </div>
-          ))}
-        </div>
-      )}
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/pages/SimulatorPage.tsx

@@ -1,284 +0,0 @@
-import { useState, useEffect } from 'react'
-import {
-  Gamepad2, Play, Wifi, WifiOff, Settings,
-  AlertCircle, Trophy, Clock, Brain
-} from 'lucide-react'
-import { Spinner, StatusBadge } from '../components/common'
-import { simApi, labApi } from '../api'
-import { usePolling } from '../hooks/usePolling'
-import type { SimStatus, SimResult, DeepSeekStatus, LabDeck } from '../types'
-import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer, Cell } from 'recharts'
-
-export function SimulatorPage() {
-  const [decks, setDecks] = useState<LabDeck[]>([])
-  const [deckA, setDeckA] = useState('')
-  const [deckB, setDeckB] = useState('')
-  const [games, setGames] = useState(50)
-  const [useDeepSeek, setUseDeepSeek] = useState(false)
-  const [deepSeekDeck, setDeepSeekDeck] = useState('')
-  const [dsStatus, setDsStatus] = useState<DeepSeekStatus | null>(null)
-  const [running, setRunning] = useState(false)
-  const [simId, setSimId] = useState<string | null>(null)
-  const [simStatus, setSimStatus] = useState<SimStatus | null>(null)
-  const [result, setResult] = useState<SimResult | null>(null)
-  const [error, setError] = useState<string | null>(null)
-  const [starting, setStarting] = useState(false)
-
-  // DS config
-  const [showDsConfig, setShowDsConfig] = useState(false)
-  const [dsModel, setDsModel] = useState('')
-  const [dsUrl, setDsUrl] = useState('')
-
-  useEffect(() => {
-    labApi.getLabDecks().then(setDecks).catch(() => {})
-    simApi.getDeepSeekStatus().then(s => {
-      setDsStatus(s)
-      if (s.model) setDsModel(s.model)
-      if (s.base_url) setDsUrl(s.base_url)
-    }).catch(() => {})
-  }, [])
-
-  // Poll while running
-  usePolling(async () => {
-    if (!simId) return
-    try {
-      const s = await simApi.getSimStatus(simId)
-      setSimStatus(s)
-      if (!s.running) {
-        const r = await simApi.getSimResult(simId)
-        setResult(r)
-        setRunning(false)
-      }
-    } catch { /* ignore */ }
-  }, 2000, running)
-
-  async function handleStart() {
-    if (!deckA || !deckB) { setError('Select both decks'); return }
-    setStarting(true)
-    setError(null)
-    setResult(null)
-    try {
-      let res
-      if (useDeepSeek && deepSeekDeck) {
-        res = await simApi.runDeepSeekSim({ deck_a: deckA, deck_b: deckB, games, deepseek_deck: deepSeekDeck })
-      } else {
-        res = await simApi.runSim({ deck_a: deckA, deck_b: deckB, games })
-      }
-      setSimId(res.sim_id)
-      setRunning(true)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Failed to start')
-    }
-    setStarting(false)
-  }
-
-  async function handleDsConnect() {
-    try {
-      const s = await simApi.connectDeepSeek()
-      setDsStatus(s)
-    } catch { /* ignore */ }
-  }
-
-  async function handleDsConfigure() {
-    try {
-      const s = await simApi.configureDeepSeek({
-        model: dsModel || undefined,
-        base_url: dsUrl || undefined,
-      })
-      setDsStatus(s)
-      setShowDsConfig(false)
-    } catch { /* ignore */ }
-  }
-
-  return (
-    <div className="p-6 space-y-5">
-      <div>
-        <h1 className="text-2xl font-bold text-text-primary flex items-center gap-3">
-          <Gamepad2 className="w-6 h-6 text-accent-purple" />
-          Simulator
-        </h1>
-        <p className="text-sm text-text-secondary mt-0.5">Run head-to-head deck simulations</p>
-      </div>
-
-      {/* DeepSeek status */}
-      <div className="flex items-center gap-3">
-        <StatusBadge
-          variant={dsStatus?.connected ? 'success' : 'warning'}
-          label={dsStatus?.connected ? `DeepSeek: ${dsStatus.model}` : 'DeepSeek: Disconnected'}
-        />
-        <button onClick={handleDsConnect}
-          className="flex items-center gap-1.5 text-xs text-text-tertiary hover:text-text-secondary transition-colors">
-          {dsStatus?.connected ? <Wifi className="w-3 h-3" /> : <WifiOff className="w-3 h-3" />}
-          {dsStatus?.connected ? 'Reconnect' : 'Connect'}
-        </button>
-        <button onClick={() => setShowDsConfig(!showDsConfig)}
-          className="flex items-center gap-1.5 text-xs text-text-tertiary hover:text-text-secondary transition-colors">
-          <Settings className="w-3 h-3" />
-          Configure
-        </button>
-      </div>
-
-      {showDsConfig && (
-        <div className="bg-bg-secondary rounded-xl border border-border-primary p-4 max-w-md animate-fade-in space-y-3">
-          <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
-            <Brain className="w-4 h-4 text-accent-purple" />
-            DeepSeek Configuration
-          </h3>
-          <input
-            type="text"
-            placeholder="Model name"
-            value={dsModel}
-            onChange={e => setDsModel(e.target.value)}
-            className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-          />
-          <input
-            type="text"
-            placeholder="Base URL (e.g. http://192.168.0.122:1234)"
-            value={dsUrl}
-            onChange={e => setDsUrl(e.target.value)}
-            className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:border-accent-blue/50 transition-all"
-          />
-          <button onClick={handleDsConfigure}
-            className="px-4 py-2 bg-accent-blue text-white text-sm font-medium rounded-lg hover:bg-accent-blue-hover transition-colors">
-            Save
-          </button>
-        </div>
-      )}
-
-      {/* Sim config */}
-      <div className="bg-bg-secondary rounded-xl border border-border-primary p-5 space-y-4 max-w-2xl">
-        <div className="grid grid-cols-2 gap-4">
-          <div>
-            <label className="text-xs text-text-tertiary uppercase tracking-wider">Deck A</label>
-            <select
-              value={deckA}
-              onChange={e => setDeckA(e.target.value)}
-              className="mt-1 w-full px-3 py-2.5 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all"
-            >
-              <option value="">Select deck...</option>
-              {decks.map(d => <option key={d.name} value={d.name}>{d.name}</option>)}
-            </select>
-          </div>
-          <div>
-            <label className="text-xs text-text-tertiary uppercase tracking-wider">Deck B</label>
-            <select
-              value={deckB}
-              onChange={e => setDeckB(e.target.value)}
-              className="mt-1 w-full px-3 py-2.5 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all"
-            >
-              <option value="">Select deck...</option>
-              {decks.map(d => <option key={d.name} value={d.name}>{d.name}</option>)}
-            </select>
-          </div>
-        </div>
-
-        <div className="flex items-center gap-6">
-          <div>
-            <label className="text-xs text-text-tertiary uppercase tracking-wider">Games</label>
-            <input
-              type="number" min={1} max={1000}
-              value={games}
-              onChange={e => setGames(Number(e.target.value))}
-              className="mt-1 w-24 px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all"
-            />
-          </div>
-          <label className="flex items-center gap-2 cursor-pointer mt-5">
-            <input type="checkbox" checked={useDeepSeek} onChange={e => setUseDeepSeek(e.target.checked)}
-              className="w-4 h-4 rounded border-border-primary bg-bg-tertiary text-accent-purple focus:ring-accent-purple/30" />
-            <span className="text-sm text-text-secondary">Use DeepSeek AI pilot</span>
-          </label>
-          {useDeepSeek && (
-            <div className="mt-5">
-              <select
-                value={deepSeekDeck}
-                onChange={e => setDeepSeekDeck(e.target.value)}
-                className="px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all"
-              >
-                <option value="">AI pilots which deck?</option>
-                {[deckA, deckB].filter(Boolean).map(d => <option key={d} value={d}>{d}</option>)}
-              </select>
-            </div>
-          )}
-        </div>
-
-        {error && (
-          <div className="flex items-center gap-2 px-4 py-2 bg-status-error/10 border border-status-error/30 rounded-lg text-sm text-status-error">
-            <AlertCircle className="w-4 h-4" />{error}
-          </div>
-        )}
-
-        {running ? (
-          <div className="flex items-center gap-3">
-            <Spinner size="md" className="text-accent-blue" />
-            <div>
-              <p className="text-sm text-text-primary">Simulation running...</p>
-              {simStatus && (
-                <p className="text-xs text-text-tertiary">
-                  {simStatus.games_completed ?? 0} / {simStatus.total_games ?? games} games
-                </p>
-              )}
-            </div>
-          </div>
-        ) : (
-          <button onClick={handleStart} disabled={starting || !deckA || !deckB}
-            className="flex items-center gap-2 px-5 py-2.5 bg-accent-purple/15 text-accent-purple text-sm font-semibold rounded-lg hover:bg-accent-purple/25 border border-accent-purple/30 transition-colors disabled:opacity-50">
-            {starting ? <Spinner size="sm" /> : <Play className="w-4 h-4" />}
-            Run Simulation
-          </button>
-        )}
-      </div>
-
-      {/* Results */}
-      {result && (
-        <div className="bg-bg-secondary rounded-xl border border-border-primary p-5 space-y-4 animate-fade-in">
-          <div className="flex items-center justify-between">
-            <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
-              <Trophy className="w-4 h-4 text-accent-amber" />
-              Results
-            </h3>
-            <span className="text-xs text-text-tertiary flex items-center gap-1.5">
-              <Clock className="w-3 h-3" />
-              {(result.duration_ms / 1000).toFixed(1)}s · {result.total_games} games
-            </span>
-          </div>
-          <div className="h-48">
-            <ResponsiveContainer width="100%" height="100%">
-              <BarChart data={result.decks.map(d => ({ name: d.name, win_rate: Math.round(d.win_rate * 100) }))} barSize={40}>
-                <XAxis dataKey="name" tick={{ fill: '#9ba1b8', fontSize: 12 }} axisLine={false} tickLine={false} />
-                <YAxis domain={[0, 100]} tick={{ fill: '#6b7190', fontSize: 11 }} axisLine={false} tickLine={false} />
-                <Tooltip contentStyle={{ backgroundColor: '#1c2030', border: '1px solid #2a2f42', borderRadius: 8, fontSize: 12 }}
-                  formatter={(value: unknown) => [`${value}%`, 'Win Rate']} />
-                <Bar dataKey="win_rate" radius={[4, 4, 0, 0]}>
-                  {result.decks.map((d, i) => (
-                    <Cell key={i} fill={d.win_rate === Math.max(...result.decks.map(x => x.win_rate)) ? '#4ade80' : '#4f6ef7'} />
-                  ))}
-                </Bar>
-              </BarChart>
-            </ResponsiveContainer>
-          </div>
-          <div className="grid grid-cols-2 gap-4">
-            {result.decks.map(d => (
-              <div key={d.name} className="px-4 py-3 rounded-lg bg-bg-tertiary">
-                <p className="text-sm font-semibold text-text-primary">{d.name}</p>
-                <div className="grid grid-cols-3 gap-2 mt-2">
-                  <div>
-                    <p className="text-[10px] text-text-tertiary uppercase">Wins</p>
-                    <p className="text-lg font-bold text-accent-green">{d.wins}</p>
-                  </div>
-                  <div>
-                    <p className="text-[10px] text-text-tertiary uppercase">Win Rate</p>
-                    <p className="text-lg font-bold text-accent-blue">{(d.win_rate * 100).toFixed(1)}%</p>
-                  </div>
-                  <div>
-                    <p className="text-[10px] text-text-tertiary uppercase">Avg Turn</p>
-                    <p className="text-lg font-bold text-text-primary">{d.avg_turn.toFixed(1)}</p>
-                  </div>
-                </div>
-              </div>
-            ))}
-          </div>
-        </div>
-      )}
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/pages/TrainingPage.tsx

@@ -1,822 +0,0 @@
-import { useState, useEffect, useCallback } from 'react'
-import {
-  Brain, Play, RotateCw, Database, Trophy, AlertCircle,
-  Activity, Zap, Swords, FileText, Cpu, CheckCircle,
-  ChevronDown, ChevronUp, Settings
-} from 'lucide-react'
-import { Spinner, StatusBadge } from '../components/common'
-import { trainingApi } from '../api'
-import { usePolling } from '../hooks/usePolling'
-import type {
-  MLStatus, MLDataStatus, MLTrainStatus, PPOTrainStatus,
-  TournamentStatus, MLModelInfo
-} from '../types'
-
-// ── Progress Bar ──────────────────────────────────────────────
-function ProgressBar({ value, max, label, color = 'bg-accent-blue' }: { value: number; max: number; label: string; color?: string }) {
-  const pct = max > 0 ? Math.min((value / max) * 100, 100) : 0
-  return (
-    <div>
-      <div className="flex items-center justify-between text-xs mb-1">
-        <span className="text-text-secondary">{label}</span>
-        <span className="text-text-tertiary">{value} / {max} ({pct.toFixed(0)}%)</span>
-      </div>
-      <div className="w-full h-2 bg-bg-tertiary rounded-full overflow-hidden">
-        <div className={'h-full rounded-full transition-all duration-500 ' + color} style={{ width: `${pct}%` }} />
-      </div>
-    </div>
-  )
-}
-
-// ── Phase Badge ──────────────────────────────────────────────
-const PHASE_STYLES: Record<string, string> = {
-  idle: 'bg-bg-tertiary text-text-tertiary',
-  starting: 'bg-accent-blue/15 text-accent-blue animate-pulse',
-  building: 'bg-accent-purple/15 text-accent-purple animate-pulse',
-  training: 'bg-accent-blue/15 text-accent-blue animate-pulse',
-  evaluating: 'bg-accent-teal/15 text-accent-teal animate-pulse',
-  running: 'bg-accent-amber/15 text-accent-amber animate-pulse',
-  done: 'bg-accent-green/15 text-accent-green',
-  error: 'bg-accent-red/15 text-accent-red',
-}
-
-function PhaseBadge({ phase }: { phase: string }) {
-  const cls = PHASE_STYLES[phase] || PHASE_STYLES.idle
-  return (
-    <span className={'text-[10px] font-semibold uppercase tracking-wider px-2 py-0.5 rounded ' + cls}>
-      {phase}
-    </span>
-  )
-}
-
-// ── Metric Card ──────────────────────────────────────────────
-function MetricCard({ label, value, accent }: { label: string; value: string | number; accent?: string }) {
-  return (
-    <div className="px-3 py-2 bg-bg-tertiary rounded-lg">
-      <p className="text-[10px] text-text-tertiary">{label}</p>
-      <p className={'text-sm font-bold ' + (accent || 'text-text-primary')}>{value}</p>
-    </div>
-  )
-}
-
-// ── Collapsible Section ─────────────────────────────────────
-function Section({ title, icon, children, defaultOpen = true, color = 'text-accent-blue' }: {
-  title: string; icon: React.ReactNode; children: React.ReactNode; defaultOpen?: boolean; color?: string
-}) {
-  const [open, setOpen] = useState(defaultOpen)
-  return (
-    <div className="bg-bg-secondary rounded-xl border border-border-primary overflow-hidden">
-      <button
-        onClick={() => setOpen(!open)}
-        className="w-full flex items-center justify-between px-5 py-4 hover:bg-bg-hover transition-colors"
-      >
-        <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
-          <span className={color}>{icon}</span>
-          {title}
-        </h3>
-        {open ? <ChevronUp className="w-4 h-4 text-text-tertiary" /> : <ChevronDown className="w-4 h-4 text-text-tertiary" />}
-      </button>
-      {open && <div className="px-5 pb-5 space-y-4 border-t border-border-primary pt-4">{children}</div>}
-    </div>
-  )
-}
-
-// ══════════════════════════════════════════════════════════════
-// Main Training Page
-// ══════════════════════════════════════════════════════════════
-export function TrainingPage() {
-  // Status states
-  const [mlStatus, setMlStatus] = useState<MLStatus | null>(null)
-  const [dataStatus, setDataStatus] = useState<MLDataStatus | null>(null)
-  const [modelInfo, setModelInfo] = useState<MLModelInfo | null>(null)
-  const [trainStatus, setTrainStatus] = useState<MLTrainStatus | null>(null)
-  const [ppoStatus, setPpoStatus] = useState<PPOTrainStatus | null>(null)
-  const [tournStatus, setTournStatus] = useState<TournamentStatus | null>(null)
-  const [loading, setLoading] = useState(true)
-  const [error, setError] = useState<string | null>(null)
-
-  // Supervised training config
-  const [epochs, setEpochs] = useState(50)
-  const [lr, setLr] = useState(0.001)
-  const [batchSize, setBatchSize] = useState(256)
-  const [patience, setPatience] = useState(10)
-  const [rebuildDataset, setRebuildDataset] = useState(true)
-
-  // PPO config
-  const [ppoIterations, setPpoIterations] = useState(100)
-  const [ppoEpisodes, setPpoEpisodes] = useState(64)
-  const [ppoEpochs, setPpoEpochs] = useState(4)
-  const [ppoBatchSize, setPpoBatchSize] = useState(256)
-  const [ppoLr, setPpoLr] = useState(0.0003)
-  const [ppoClipEps, setPpoClipEps] = useState(0.2)
-  const [ppoEntropy, setPpoEntropy] = useState(0.01)
-  const [ppoOpponent, setPpoOpponent] = useState('heuristic')
-  const [ppoPlaystyle, _setPpoPlaystyle] = useState('midrange') // eslint-disable-line
-
-  // Tournament config
-  const [tournEpisodes, setTournEpisodes] = useState(50)
-  const [tournPlaystyle, setTournPlaystyle] = useState('midrange')
-
-  // Action states
-  const [startingTrain, setStartingTrain] = useState(false)
-  const [startingPpo, setStartingPpo] = useState(false)
-  const [startingTourn, setStartingTourn] = useState(false)
-  const [reloading, setReloading] = useState(false)
-  const [showSupAdvanced, setShowSupAdvanced] = useState(false)
-  const [showPpoAdvanced, setShowPpoAdvanced] = useState(false)
-
-  // ── Initial Load ──────────────────────────────────────────
-  const loadAll = useCallback(async () => {
-    try {
-      const [ml, data, model, train, ppo, tourn] = await Promise.all([
-        trainingApi.getMLStatus().catch(() => null),
-        trainingApi.getDataStatus().catch(() => null),
-        trainingApi.getModelInfo().catch(() => null),
-        trainingApi.getTrainStatus().catch(() => null),
-        trainingApi.getPPOStatus().catch(() => null),
-        trainingApi.getTournamentStatus().catch(() => null),
-      ])
-      if (ml) setMlStatus(ml)
-      if (data) setDataStatus(data)
-      if (model) setModelInfo(model)
-      if (train) setTrainStatus(train)
-      if (ppo) setPpoStatus(ppo)
-      if (tourn) setTournStatus(tourn)
-    } catch { /* ignore */ }
-    setLoading(false)
-  }, [])
-
-  useEffect(() => { loadAll() }, [loadAll])
-
-  // ── Polling ───────────────────────────────────────────────
-  const isTraining = trainStatus?.running || false
-  const isPpo = ppoStatus?.running || false
-  const isTourn = tournStatus?.running || false
-  const anyRunning = isTraining || isPpo || isTourn
-
-  usePolling(async () => {
-    try {
-      const s = await trainingApi.getTrainStatus()
-      setTrainStatus(s)
-      if (!s.running && s.phase === 'done') {
-        // Refresh model info + data when training completes
-        const [model, data] = await Promise.all([
-          trainingApi.getModelInfo().catch(() => null),
-          trainingApi.getDataStatus().catch(() => null),
-        ])
-        if (model) setModelInfo(model)
-        if (data) setDataStatus(data)
-      }
-    } catch { /* ignore */ }
-  }, 2000, isTraining)
-
-  usePolling(async () => {
-    try {
-      const s = await trainingApi.getPPOStatus()
-      setPpoStatus(s)
-      if (!s.running && s.phase === 'done') {
-        const [model, data] = await Promise.all([
-          trainingApi.getModelInfo().catch(() => null),
-          trainingApi.getDataStatus().catch(() => null),
-        ])
-        if (model) setModelInfo(model)
-        if (data) setDataStatus(data)
-      }
-    } catch { /* ignore */ }
-  }, 2000, isPpo)
-
-  usePolling(async () => {
-    try {
-      const s = await trainingApi.getTournamentStatus()
-      setTournStatus(s)
-    } catch { /* ignore */ }
-  }, 2000, isTourn)
-
-  // ── Actions ───────────────────────────────────────────────
-  async function handleToggleLogging() {
-    try {
-      const newState = !(mlStatus?.ml_logging_enabled ?? false)
-      await trainingApi.toggleML(newState)
-      const ml = await trainingApi.getMLStatus()
-      setMlStatus(ml)
-    } catch { /* ignore */ }
-  }
-
-  async function handleReloadModel() {
-    setReloading(true)
-    try {
-      const res = await trainingApi.reloadModel()
-      setModelInfo(res.status)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Failed to reload model')
-    }
-    setReloading(false)
-  }
-
-  async function handleStartTrain() {
-    setStartingTrain(true)
-    setError(null)
-    try {
-      await trainingApi.startTraining({ epochs, lr, batchSize, patience, rebuildDataset })
-      const s = await trainingApi.getTrainStatus()
-      setTrainStatus(s)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Failed to start training')
-    }
-    setStartingTrain(false)
-  }
-
-  async function handleStartPpo() {
-    setStartingPpo(true)
-    setError(null)
-    try {
-      await trainingApi.startPPOTraining({
-        iterations: ppoIterations,
-        episodesPerIter: ppoEpisodes,
-        ppoEpochs,
-        batchSize: ppoBatchSize,
-        lr: ppoLr,
-        clipEpsilon: ppoClipEps,
-        entropyCoeff: ppoEntropy,
-        opponent: ppoOpponent,
-        playstyle: ppoPlaystyle,
-      })
-      const s = await trainingApi.getPPOStatus()
-      setPpoStatus(s)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Failed to start PPO training')
-    }
-    setStartingPpo(false)
-  }
-
-  async function handleStartTournament() {
-    setStartingTourn(true)
-    setError(null)
-    try {
-      await trainingApi.startTournament({ episodes: tournEpisodes, playstyle: tournPlaystyle })
-      const s = await trainingApi.getTournamentStatus()
-      setTournStatus(s)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Failed to start tournament')
-    }
-    setStartingTourn(false)
-  }
-
-  // ── Render ────────────────────────────────────────────────
-  if (loading) {
-    return <div className="p-6 flex items-center justify-center h-64"><Spinner size="lg" className="text-accent-blue" /></div>
-  }
-
-  const trainDataset = dataStatus?.datasets?.['train']
-  const hasDecisions = (mlStatus?.total_decisions ?? 0) > 0
-  const hasModel = modelInfo?.loaded === true
-
-  return (
-    <div className="p-6 space-y-5">
-      {/* Page Header */}
-      <div>
-        <h1 className="text-2xl font-bold text-text-primary flex items-center gap-3">
-          <Brain className="w-6 h-6 text-accent-green" />
-          ML Training Pipeline
-        </h1>
-        <p className="text-sm text-text-secondary mt-0.5">Collect data, train models, and evaluate performance</p>
-      </div>
-
-      {/* Error banner */}
-      {error && (
-        <div className="flex items-center gap-2 px-4 py-2 bg-accent-red/10 border border-accent-red/30 rounded-lg text-sm text-accent-red">
-          <AlertCircle className="w-4 h-4 flex-shrink-0" />
-          <span className="flex-1">{error}</span>
-          <button onClick={() => setError(null)} className="text-accent-red/60 hover:text-accent-red text-xs">dismiss</button>
-        </div>
-      )}
-
-      {/* Pipeline overview bar */}
-      <div className="flex flex-wrap items-center gap-3 bg-bg-secondary rounded-xl border border-border-primary px-5 py-3">
-        <div className="flex items-center gap-2">
-          <div className={'w-2 h-2 rounded-full ' + (mlStatus?.ml_logging_enabled ? 'bg-accent-green' : 'bg-text-tertiary')} />
-          <span className="text-xs text-text-secondary">Logging {mlStatus?.ml_logging_enabled ? 'On' : 'Off'}</span>
-        </div>
-        <span className="text-border-primary">|</span>
-        <span className="text-xs text-text-secondary">{mlStatus?.total_decisions ?? 0} decisions</span>
-        <span className="text-border-primary">|</span>
-        <span className="text-xs text-text-secondary">{trainDataset ? `${trainDataset.samples.toLocaleString()} training samples` : 'No dataset'}</span>
-        <span className="text-border-primary">|</span>
-        <span className="text-xs text-text-secondary">{(dataStatus?.checkpoints?.length ?? 0)} checkpoints</span>
-        <span className="text-border-primary">|</span>
-        <StatusBadge
-          variant={hasModel ? 'success' : 'neutral'}
-          label={hasModel ? `Model on ${modelInfo?.device ?? '?'}` : 'No model'}
-        />
-        {anyRunning && (
-          <>
-            <span className="text-border-primary">|</span>
-            <span className="text-xs font-medium text-accent-blue animate-pulse">Pipeline running...</span>
-          </>
-        )}
-      </div>
-
-      {/* ═══ Phase 1: Data Collection ═══ */}
-      <Section title="Phase 1 — Data Collection" icon={<FileText className="w-4 h-4" />} color="text-accent-teal">
-        <div className="flex items-center justify-between">
-          <p className="text-xs text-text-secondary">
-            Run batch simulations with ML logging enabled to collect decision data.
-          </p>
-          <button
-            onClick={handleToggleLogging}
-            className={'flex items-center gap-2 px-3 py-1.5 text-xs font-medium rounded-lg border transition-colors ' +
-              (mlStatus?.ml_logging_enabled
-                ? 'bg-accent-green/15 text-accent-green border-accent-green/30 hover:bg-accent-green/25'
-                : 'bg-bg-tertiary text-text-secondary border-border-primary hover:bg-bg-hover'
-              )}
-          >
-            <div className={'w-2 h-2 rounded-full ' + (mlStatus?.ml_logging_enabled ? 'bg-accent-green' : 'bg-text-tertiary')} />
-            {mlStatus?.ml_logging_enabled ? 'Logging Enabled' : 'Enable Logging'}
-          </button>
-        </div>
-
-        {/* Decision files */}
-        {(dataStatus?.decisionFiles?.length ?? 0) > 0 ? (
-          <div className="space-y-1">
-            <h4 className="text-xs font-semibold text-text-tertiary uppercase tracking-wider">Decision Files</h4>
-            <div className="max-h-36 overflow-y-auto space-y-1">
-              {dataStatus!.decisionFiles.map(f => (
-                <div key={f.name} className="flex items-center justify-between px-3 py-1.5 bg-bg-tertiary rounded-lg text-xs">
-                  <span className="text-text-secondary font-mono truncate">{f.name}</span>
-                  <div className="flex items-center gap-3 text-text-tertiary">
-                    <span>{f.decisions.toLocaleString()} decisions</span>
-                    <span>{(f.size / 1024).toFixed(0)} KB</span>
-                  </div>
-                </div>
-              ))}
-            </div>
-          </div>
-        ) : (
-          <div className="text-xs text-text-tertiary italic">No decision files yet. Run batch sims with logging enabled.</div>
-        )}
-      </Section>
-
-      {/* ═══ Phase 2: Dataset & Checkpoints ═══ */}
-      <Section title="Phase 2 — Dataset & Model Artifacts" icon={<Database className="w-4 h-4" />} color="text-accent-purple">
-        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-          {/* Dataset splits */}
-          <div className="space-y-2">
-            <h4 className="text-xs font-semibold text-text-tertiary uppercase tracking-wider">Dataset Splits</h4>
-            {Object.keys(dataStatus?.datasets ?? {}).length > 0 ? (
-              <div className="grid grid-cols-3 gap-2">
-                {(['train', 'val', 'test'] as const).map(split => {
-                  const ds = dataStatus?.datasets?.[split]
-                  return (
-                    <div key={split} className="px-3 py-2 bg-bg-tertiary rounded-lg">
-                      <p className="text-[10px] text-text-tertiary uppercase">{split}</p>
-                      {ds ? (
-                        <>
-                          <p className="text-sm font-bold text-text-primary">{ds.samples.toLocaleString()}</p>
-                          <p className="text-[10px] text-text-tertiary">{ds.features} features</p>
-                        </>
-                      ) : (
-                        <p className="text-xs text-text-tertiary italic">Not built</p>
-                      )}
-                    </div>
-                  )
-                })}
-              </div>
-            ) : (
-              <p className="text-xs text-text-tertiary italic">No dataset built yet. Training will build it automatically.</p>
-            )}
-          </div>
-
-          {/* Checkpoints */}
-          <div className="space-y-2">
-            <h4 className="text-xs font-semibold text-text-tertiary uppercase tracking-wider">Checkpoints</h4>
-            {(dataStatus?.checkpoints?.length ?? 0) > 0 ? (
-              <div className="max-h-28 overflow-y-auto space-y-1">
-                {dataStatus!.checkpoints.map(ckpt => (
-                  <div key={ckpt.name} className="flex items-center justify-between px-3 py-1.5 bg-bg-tertiary rounded-lg text-xs">
-                    <span className="text-text-secondary font-mono truncate">{ckpt.name}</span>
-                    <span className="text-text-tertiary">{(ckpt.size / 1024 / 1024).toFixed(1)} MB</span>
-                  </div>
-                ))}
-              </div>
-            ) : (
-              <p className="text-xs text-text-tertiary italic">No checkpoints yet. Train a model to generate them.</p>
-            )}
-          </div>
-        </div>
-
-        {/* Model info + reload */}
-        <div className="flex items-center justify-between pt-2 border-t border-border-primary">
-          <div className="flex items-center gap-3">
-            <Cpu className="w-4 h-4 text-text-tertiary" />
-            <div className="text-xs">
-              {hasModel ? (
-                <span className="text-accent-green font-medium">
-                  Model loaded on {modelInfo?.device} | {modelInfo?.input_dim} features | {modelInfo?.num_actions} actions
-                </span>
-              ) : (
-                <span className="text-text-tertiary">No model loaded{modelInfo?.error ? ` — ${modelInfo.error}` : ''}</span>
-              )}
-            </div>
-          </div>
-          <button
-            onClick={handleReloadModel}
-            disabled={reloading}
-            className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium bg-bg-tertiary text-text-secondary rounded-lg hover:bg-bg-hover border border-border-primary transition-colors disabled:opacity-50"
-          >
-            {reloading ? <Spinner size="sm" /> : <RotateCw className="w-3 h-3" />}
-            Reload Model
-          </button>
-        </div>
-
-        {/* Eval results */}
-        {dataStatus?.evalResults && (
-          <div className="pt-2 border-t border-border-primary space-y-2">
-            <h4 className="text-xs font-semibold text-text-tertiary uppercase tracking-wider flex items-center gap-2">
-              <CheckCircle className="w-3.5 h-3.5 text-accent-green" />
-              Latest Evaluation
-            </h4>
-            <div className="grid grid-cols-2 md:grid-cols-4 gap-2">
-              {Object.entries(dataStatus.evalResults).map(([k, v]) => (
-                <MetricCard
-                  key={k}
-                  label={k.replace(/_/g, ' ')}
-                  value={typeof v === 'number' ? (k.includes('accuracy') || k.includes('rate') ? `${(v * 100).toFixed(1)}%` : v.toFixed(4)) : String(v)}
-                  accent={k.includes('accuracy') ? 'text-accent-green' : undefined}
-                />
-              ))}
-            </div>
-          </div>
-        )}
-      </Section>
-
-      {/* ═══ Phase 3: Supervised Training ═══ */}
-      <Section title="Phase 3 — Supervised Training" icon={<Activity className="w-4 h-4" />}>
-        {/* Config */}
-        <div className="space-y-3">
-          <div className="grid grid-cols-2 gap-3">
-            <div>
-              <label className="text-xs text-text-tertiary block mb-1">Epochs</label>
-              <input type="number" min={1} max={1000} value={epochs} onChange={e => setEpochs(Number(e.target.value))}
-                disabled={isTraining}
-                className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-            </div>
-            <div>
-              <label className="text-xs text-text-tertiary block mb-1">Learning Rate</label>
-              <input type="number" min={0.00001} max={1} step={0.0001} value={lr} onChange={e => setLr(Number(e.target.value))}
-                disabled={isTraining}
-                className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-            </div>
-          </div>
-
-          {/* Advanced toggle */}
-          <button onClick={() => setShowSupAdvanced(!showSupAdvanced)} className="flex items-center gap-1 text-xs text-text-tertiary hover:text-text-secondary transition-colors">
-            <Settings className="w-3 h-3" />
-            {showSupAdvanced ? 'Hide' : 'Show'} advanced options
-          </button>
-          {showSupAdvanced && (
-            <div className="grid grid-cols-3 gap-3 animate-fade-in">
-              <div>
-                <label className="text-xs text-text-tertiary block mb-1">Batch Size</label>
-                <input type="number" min={16} max={2048} value={batchSize} onChange={e => setBatchSize(Number(e.target.value))}
-                  disabled={isTraining}
-                  className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-              </div>
-              <div>
-                <label className="text-xs text-text-tertiary block mb-1">Early Stop Patience</label>
-                <input type="number" min={1} max={100} value={patience} onChange={e => setPatience(Number(e.target.value))}
-                  disabled={isTraining}
-                  className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-              </div>
-              <div className="flex items-end pb-1">
-                <label className="flex items-center gap-2 text-xs text-text-secondary cursor-pointer select-none">
-                  <input type="checkbox" checked={rebuildDataset} onChange={e => setRebuildDataset(e.target.checked)}
-                    disabled={isTraining}
-                    className="rounded border-border-primary bg-bg-tertiary text-accent-blue focus:ring-accent-blue/30 w-3.5 h-3.5" />
-                  Rebuild dataset
-                </label>
-              </div>
-            </div>
-          )}
-        </div>
-
-        {/* Training status / start button */}
-        {isTraining || (trainStatus?.phase && trainStatus.phase !== 'idle') ? (
-          <div className="space-y-3 bg-bg-tertiary/50 rounded-xl p-4 border border-border-primary">
-            <div className="flex items-center justify-between">
-              <div className="flex items-center gap-2">
-                <PhaseBadge phase={trainStatus!.phase} />
-                <span className="text-xs text-text-secondary">{trainStatus!.message}</span>
-              </div>
-              {trainStatus!.started_at && (
-                <span className="text-[10px] text-text-tertiary">Started: {new Date(trainStatus!.started_at).toLocaleTimeString()}</span>
-              )}
-            </div>
-
-            {/* Progress bar — only in training phase */}
-            {(trainStatus!.phase === 'training' || trainStatus!.phase === 'done') && trainStatus!.total_epochs > 0 && (
-              <ProgressBar
-                value={trainStatus!.current_epoch}
-                max={trainStatus!.total_epochs}
-                label="Epoch progress"
-              />
-            )}
-
-            {/* Live metrics during training */}
-            {trainStatus!.metrics && (
-              <div className="grid grid-cols-2 md:grid-cols-4 gap-2">
-                {Object.entries(trainStatus!.metrics).map(([k, v]) => {
-                  if (typeof v !== 'number') return null
-                  const isAcc = k.includes('accuracy') || k.includes('acc')
-                  const isLoss = k.includes('loss')
-                  return (
-                    <MetricCard
-                      key={k}
-                      label={k.replace(/_/g, ' ')}
-                      value={isAcc ? `${(v * 100).toFixed(1)}%` : v.toFixed(4)}
-                      accent={isAcc ? 'text-accent-green' : isLoss ? 'text-accent-amber' : undefined}
-                    />
-                  )
-                })}
-              </div>
-            )}
-
-            {/* Final result */}
-            {trainStatus!.phase === 'done' && trainStatus!.result && (
-              <div className="pt-2 border-t border-border-primary space-y-2">
-                <h4 className="text-xs font-semibold text-accent-green flex items-center gap-1.5">
-                  <CheckCircle className="w-3.5 h-3.5" /> Training Complete
-                </h4>
-                <div className="grid grid-cols-2 md:grid-cols-4 gap-2">
-                  <MetricCard label="Device" value={trainStatus!.result.device} />
-                  <MetricCard label="Checkpoint" value={trainStatus!.result.checkpoint.split('/').pop() || '—'} />
-                  {trainStatus!.result.evaluation && Object.entries(trainStatus!.result.evaluation).map(([k, v]) => (
-                    typeof v === 'number' ? (
-                      <MetricCard key={k} label={k.replace(/_/g, ' ')}
-                        value={k.includes('accuracy') ? `${(v * 100).toFixed(1)}%` : v.toFixed(4)}
-                        accent={k.includes('accuracy') ? 'text-accent-green' : undefined} />
-                    ) : null
-                  ))}
-                </div>
-              </div>
-            )}
-
-            {/* Error state */}
-            {trainStatus!.phase === 'error' && trainStatus!.error && (
-              <div className="flex items-start gap-2 bg-accent-red/10 border border-accent-red/20 rounded-lg px-3 py-2">
-                <AlertCircle className="w-4 h-4 text-accent-red mt-0.5 flex-shrink-0" />
-                <span className="text-xs text-accent-red">{trainStatus!.error}</span>
-              </div>
-            )}
-          </div>
-        ) : (
-          <div className="flex items-center gap-3">
-            <button
-              onClick={handleStartTrain}
-              disabled={startingTrain || !hasDecisions || isPpo}
-              className="flex items-center gap-2 px-4 py-2.5 bg-accent-blue/15 text-accent-blue text-sm font-medium rounded-lg hover:bg-accent-blue/25 border border-accent-blue/30 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
-            >
-              {startingTrain ? <Spinner size="sm" /> : <Play className="w-4 h-4" />}
-              Start Training
-            </button>
-            {!hasDecisions && (
-              <span className="text-xs text-text-tertiary italic">Enable logging and run batch sims first to generate decision data.</span>
-            )}
-          </div>
-        )}
-      </Section>
-
-      {/* ═══ Phase 4: PPO Reinforcement Learning ═══ */}
-      <Section title="Phase 4 — PPO Reinforcement Learning" icon={<Zap className="w-4 h-4" />} color="text-accent-purple" defaultOpen={false}>
-        <p className="text-xs text-text-secondary">
-          Fine-tune the supervised model using PPO self-play against an opponent policy.
-        </p>
-
-        {/* Config */}
-        <div className="grid grid-cols-2 gap-3">
-          <div>
-            <label className="text-xs text-text-tertiary block mb-1">Iterations</label>
-            <input type="number" min={1} max={1000} value={ppoIterations} onChange={e => setPpoIterations(Number(e.target.value))}
-              disabled={isPpo}
-              className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-          </div>
-          <div>
-            <label className="text-xs text-text-tertiary block mb-1">Opponent</label>
-            <select value={ppoOpponent} onChange={e => setPpoOpponent(e.target.value)}
-              disabled={isPpo}
-              className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50">
-              <option value="heuristic">Heuristic</option>
-              <option value="random">Random</option>
-              <option value="self">Self-Play</option>
-            </select>
-          </div>
-        </div>
-
-        <button onClick={() => setShowPpoAdvanced(!showPpoAdvanced)} className="flex items-center gap-1 text-xs text-text-tertiary hover:text-text-secondary transition-colors">
-          <Settings className="w-3 h-3" />
-          {showPpoAdvanced ? 'Hide' : 'Show'} advanced options
-        </button>
-        {showPpoAdvanced && (
-          <div className="grid grid-cols-3 gap-3 animate-fade-in">
-            <div>
-              <label className="text-xs text-text-tertiary block mb-1">Episodes / Iter</label>
-              <input type="number" min={1} max={512} value={ppoEpisodes} onChange={e => setPpoEpisodes(Number(e.target.value))}
-                disabled={isPpo}
-                className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-            </div>
-            <div>
-              <label className="text-xs text-text-tertiary block mb-1">PPO Epochs</label>
-              <input type="number" min={1} max={20} value={ppoEpochs} onChange={e => setPpoEpochs(Number(e.target.value))}
-                disabled={isPpo}
-                className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-            </div>
-            <div>
-              <label className="text-xs text-text-tertiary block mb-1">Batch Size</label>
-              <input type="number" min={16} max={2048} value={ppoBatchSize} onChange={e => setPpoBatchSize(Number(e.target.value))}
-                disabled={isPpo}
-                className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-            </div>
-            <div>
-              <label className="text-xs text-text-tertiary block mb-1">Learning Rate</label>
-              <input type="number" min={0.000001} max={0.01} step={0.0001} value={ppoLr} onChange={e => setPpoLr(Number(e.target.value))}
-                disabled={isPpo}
-                className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-            </div>
-            <div>
-              <label className="text-xs text-text-tertiary block mb-1">Clip Epsilon</label>
-              <input type="number" min={0.05} max={0.5} step={0.05} value={ppoClipEps} onChange={e => setPpoClipEps(Number(e.target.value))}
-                disabled={isPpo}
-                className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-            </div>
-            <div>
-              <label className="text-xs text-text-tertiary block mb-1">Entropy Coeff</label>
-              <input type="number" min={0} max={0.1} step={0.005} value={ppoEntropy} onChange={e => setPpoEntropy(Number(e.target.value))}
-                disabled={isPpo}
-                className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-            </div>
-          </div>
-        )}
-
-        {/* PPO running status */}
-        {isPpo || (ppoStatus?.phase && ppoStatus.phase !== 'idle') ? (
-          <div className="space-y-3 bg-bg-tertiary/50 rounded-xl p-4 border border-border-primary">
-            <div className="flex items-center gap-2">
-              <PhaseBadge phase={ppoStatus!.phase} />
-              <span className="text-xs text-text-secondary">{ppoStatus!.message}</span>
-            </div>
-
-            {(ppoStatus!.phase === 'training' || ppoStatus!.phase === 'done') && ppoStatus!.total_iterations > 0 && (
-              <ProgressBar
-                value={ppoStatus!.iteration}
-                max={ppoStatus!.total_iterations}
-                label="PPO iteration"
-                color="bg-accent-purple"
-              />
-            )}
-
-            {ppoStatus!.metrics && (
-              <div className="grid grid-cols-2 md:grid-cols-4 gap-2">
-                {ppoStatus!.metrics.win_rate != null && (
-                  <MetricCard label="Win Rate" value={`${(ppoStatus!.metrics.win_rate * 100).toFixed(1)}%`} accent="text-accent-green" />
-                )}
-                {ppoStatus!.metrics.avg_reward != null && (
-                  <MetricCard label="Avg Reward" value={ppoStatus!.metrics.avg_reward.toFixed(3)} accent="text-accent-amber" />
-                )}
-                {ppoStatus!.metrics.policy_loss != null && (
-                  <MetricCard label="Policy Loss" value={ppoStatus!.metrics.policy_loss.toFixed(4)} />
-                )}
-                {ppoStatus!.metrics.entropy != null && (
-                  <MetricCard label="Entropy" value={ppoStatus!.metrics.entropy.toFixed(4)} />
-                )}
-              </div>
-            )}
-
-            {ppoStatus!.phase === 'done' && ppoStatus!.result && (
-              <div className="flex items-center gap-2 pt-2 border-t border-border-primary">
-                <CheckCircle className="w-3.5 h-3.5 text-accent-green" />
-                <span className="text-xs text-accent-green font-medium">
-                  PPO Training Complete — Best Win Rate: {
-                    typeof ppoStatus!.result.best_win_rate === 'number'
-                      ? `${(ppoStatus!.result.best_win_rate as number * 100).toFixed(1)}%`
-                      : '—'
-                  }
-                </span>
-              </div>
-            )}
-
-            {ppoStatus!.phase === 'error' && ppoStatus!.error && (
-              <div className="flex items-start gap-2 bg-accent-red/10 border border-accent-red/20 rounded-lg px-3 py-2">
-                <AlertCircle className="w-4 h-4 text-accent-red mt-0.5 flex-shrink-0" />
-                <span className="text-xs text-accent-red">{ppoStatus!.error}</span>
-              </div>
-            )}
-          </div>
-        ) : (
-          <button
-            onClick={handleStartPpo}
-            disabled={startingPpo || isTraining || !hasModel}
-            className="flex items-center gap-2 px-4 py-2.5 bg-accent-purple/15 text-accent-purple text-sm font-medium rounded-lg hover:bg-accent-purple/25 border border-accent-purple/30 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
-          >
-            {startingPpo ? <Spinner size="sm" /> : <Play className="w-4 h-4" />}
-            Start PPO Training
-          </button>
-        )}
-        {!hasModel && !(isPpo || (ppoStatus?.phase && ppoStatus.phase !== 'idle')) && (
-          <p className="text-xs text-text-tertiary italic">Train a supervised model first (Phase 3) before running PPO.</p>
-        )}
-      </Section>
-
-      {/* ═══ Phase 5: Tournament Evaluation ═══ */}
-      <Section title="Phase 5 — Tournament Evaluation" icon={<Swords className="w-4 h-4" />} color="text-accent-amber" defaultOpen={false}>
-        <p className="text-xs text-text-secondary">
-          Pit the trained model against heuristic, random, and other policy variants.
-        </p>
-
-        <div className="grid grid-cols-2 gap-3">
-          <div>
-            <label className="text-xs text-text-tertiary block mb-1">Episodes per Matchup</label>
-            <input type="number" min={10} max={1000} value={tournEpisodes} onChange={e => setTournEpisodes(Number(e.target.value))}
-              disabled={isTourn}
-              className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50" />
-          </div>
-          <div>
-            <label className="text-xs text-text-tertiary block mb-1">Playstyle</label>
-            <select value={tournPlaystyle} onChange={e => setTournPlaystyle(e.target.value)}
-              disabled={isTourn}
-              className="w-full px-3 py-2 bg-bg-tertiary border border-border-primary rounded-lg text-sm text-text-primary focus:outline-none focus:border-accent-blue/50 transition-all disabled:opacity-50">
-              <option value="midrange">Midrange</option>
-              <option value="aggro">Aggro</option>
-              <option value="control">Control</option>
-              <option value="combo">Combo</option>
-            </select>
-          </div>
-        </div>
-
-        {/* Tournament status */}
-        {isTourn || (tournStatus?.phase && tournStatus.phase !== 'idle') ? (
-          <div className="space-y-3 bg-bg-tertiary/50 rounded-xl p-4 border border-border-primary">
-            <div className="flex items-center gap-2">
-              <PhaseBadge phase={tournStatus!.phase} />
-              <span className="text-xs text-text-secondary">{tournStatus!.message}</span>
-            </div>
-
-            {tournStatus!.phase === 'error' && tournStatus!.error && (
-              <div className="flex items-start gap-2 bg-accent-red/10 border border-accent-red/20 rounded-lg px-3 py-2">
-                <AlertCircle className="w-4 h-4 text-accent-red mt-0.5 flex-shrink-0" />
-                <span className="text-xs text-accent-red">{tournStatus!.error}</span>
-              </div>
-            )}
-          </div>
-        ) : (
-          <button
-            onClick={handleStartTournament}
-            disabled={startingTourn || isTraining || isPpo}
-            className="flex items-center gap-2 px-4 py-2.5 bg-accent-amber/15 text-accent-amber text-sm font-medium rounded-lg hover:bg-accent-amber/25 border border-accent-amber/30 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
-          >
-            {startingTourn ? <Spinner size="sm" /> : <Trophy className="w-4 h-4" />}
-            Start Tournament
-          </button>
-        )}
-
-        {/* Tournament results */}
-        {(tournStatus?.result?.players?.length ?? 0) > 0 && (
-          <div className="pt-2 border-t border-border-primary space-y-2">
-            <h4 className="text-xs font-semibold text-text-tertiary uppercase tracking-wider flex items-center gap-2">
-              <Trophy className="w-3.5 h-3.5 text-accent-amber" />
-              Leaderboard
-            </h4>
-            <table className="w-full text-sm">
-              <thead>
-                <tr className="border-b border-border-primary">
-                  <th className="px-3 py-2 text-left text-xs text-text-tertiary font-medium w-8">#</th>
-                  <th className="px-3 py-2 text-left text-xs text-text-tertiary font-medium">Policy</th>
-                  <th className="px-3 py-2 text-right text-xs text-text-tertiary font-medium">Wins</th>
-                  <th className="px-3 py-2 text-right text-xs text-text-tertiary font-medium">Games</th>
-                  <th className="px-3 py-2 text-right text-xs text-text-tertiary font-medium">Win Rate</th>
-                </tr>
-              </thead>
-              <tbody className="divide-y divide-border-primary">
-                {tournStatus!.result!.players
-                  .sort((a, b) => b.win_rate - a.win_rate)
-                  .map((p, i) => (
-                    <tr key={p.name} className="hover:bg-bg-hover transition-colors">
-                      <td className="px-3 py-2 text-text-tertiary text-xs">
-                        {i === 0 ? <Trophy className="w-3.5 h-3.5 text-accent-amber" /> : i + 1}
-                      </td>
-                      <td className="px-3 py-2">
-                        <span className="text-text-primary font-medium capitalize">{p.name}</span>
-                      </td>
-                      <td className="px-3 py-2 text-right text-text-secondary">{p.wins}</td>
-                      <td className="px-3 py-2 text-right text-text-secondary">{p.games}</td>
-                      <td className={'px-3 py-2 text-right font-semibold ' + (i === 0 ? 'text-accent-green' : 'text-accent-blue')}>
-                        {(p.win_rate * 100).toFixed(1)}%
-                      </td>
-                    </tr>
-                  ))}
-              </tbody>
-            </table>
-          </div>
-        )}
-      </Section>
-    </div>
-  )
-}

frontend/commander-ai-lab-ui/src/types/index.ts

@@ -1,563 +0,0 @@
-// ═══════════════════════════════════════════════════════════
-// Commander AI Lab — TypeScript Type Definitions
-// Derived from the FastAPI backend's Pydantic models + SQLite schema
-// ═══════════════════════════════════════════════════════════
-
-// ── Cards & Collection ──────────────────────────────────────
-
-export interface CollectionCard {
-  id: number
-  name: string
-  scryfall_id: string
-  set_code: string
-  set_name: string
-  collector_number: string
-  rarity: string
-  type_line: string
-  mana_cost: string
-  cmc: number
-  oracle_text: string
-  color_identity: string[]
-  quantity: number
-  foil_quantity: number
-  condition: string
-  tcg_price: number | null
-  foil_price: number | null
-  image_url: string
-  edhrec_rank: number | null
-  keywords: string
-  added_date: string
-  updated_date: string
-}
-
-export interface CollectionFilters {
-  q?: string
-  type_line?: string
-  color?: string
-  rarity?: string
-  set_code?: string
-  cmc_min?: number
-  cmc_max?: number
-  price_min?: number
-  price_max?: number
-  owned_only?: boolean
-  sort_by?: string
-  sort_dir?: 'asc' | 'desc'
-  page?: number
-  page_size?: number
-}
-
-export interface CollectionStats {
-  total_cards: number
-  total_unique: number
-  total_value: number
-  sets_count: number
-}
-
-export interface SetInfo {
-  code: string
-  name: string
-  card_count?: number
-}
-
-// ── Scan ─────────────────────────────────────────────────────
-
-export interface ScanResult {
-  matches: ScanMatch[]
-  image_url?: string
-}
-
-export interface ScanMatch {
-  name: string
-  set_code: string
-  set_name: string
-  collector_number: string
-  scryfall_id: string
-  confidence: number
-  image_url: string
-  type_line: string
-  oracle_text: string
-  mana_cost: string
-  tcg_price: number | null
-}
-
-// ── Decks ────────────────────────────────────────────────────
-
-export interface Deck {
-  id: number
-  name: string
-  commander: string
-  commander_scryfall_id?: string
-  commander_image_url?: string
-  color_identity: string[]
-  format: string
-  card_count: number
-  total_price: number
-  created_date: string
-  updated_date: string
-}
-
-export interface DeckCard {
-  id: number
-  deck_id: number
-  name: string
-  scryfall_id: string
-  quantity: number
-  is_commander: boolean
-  category: string
-  type_line: string
-  mana_cost: string
-  cmc: number
-  oracle_text: string
-  tcg_price: number | null
-  image_url: string
-  owned_qty: number
-  set_code: string
-}
-
-export interface DeckAnalysis {
-  card_count: number
-  land_count: number
-  creature_count: number
-  noncreature_count: number
-  avg_cmc: number
-  mana_curve: Record<number, number>
-  color_distribution: Record<string, number>
-  type_distribution: Record<string, number>
-  total_price: number
-  owned_count: number
-  missing_count: number
-}
-
-export interface DeckRecommendation {
-  name: string
-  scryfall_id: string
-  type_line: string
-  mana_cost: string
-  oracle_text: string
-  image_url: string
-  tcg_price: number | null
-  reason: string
-  score: number
-  owned: boolean
-}
-
-// ── EDHREC Recommendations ──────────────────────────────────
-
-export interface EdhRecCard {
-  name: string
-  type_line: string
-  role: string
-  roles: string[]
-  inclusion_pct: number | null
-  synergy_score: number | null
-  owned: boolean
-  owned_qty: number
-  scryfall_id: string
-  image_url: string | null
-}
-
-export interface EdhRecsResponse {
-  commander: string
-  source: string
-  total: number
-  recommendations: EdhRecCard[]
-}
-
-// ── Collection Recommendations ──────────────────────────────
-
-export interface CollectionRecCard {
-  id: number
-  scryfall_id: string
-  name: string
-  type_line: string
-  card_type: string
-  cmc: number
-  color_identity: string[]
-  owned_qty: number
-  roles: string[]
-  score: number
-  image_url: string | null
-}
-
-export interface CollectionRecsResponse {
-  shortfall_types: string[]
-  role_filter: string[]
-  grouped: Record<string, CollectionRecCard[]>
-  total: number
-}
-
-// ── V3 Deck Generator ────────────────────────────────────────
-
-export interface DeckGenV3Request {
-  commander_name: string
-  strategy?: string
-  target_bracket: number
-  budget_usd?: number
-  budget_mode?: 'total' | 'per_card'
-  omit_cards?: string[]
-  use_collection?: boolean
-  run_substitution?: boolean
-  model?: string
-  deck_name?: string
-}
-
-export interface DeckGenV3Status {
-  initialized: boolean
-  pplx_configured: boolean
-  model: string | null
-  embeddings_loaded: boolean
-  embedding_cards: number
-  error: string | null
-}
-
-export interface DeckGenV3Card {
-  name: string
-  quantity: number
-  category: string
-  type_line: string
-  mana_cost: string
-  cmc: number
-  role: string
-  reason: string
-  tcg_price: number | null
-  image_url: string
-  owned: boolean
-  owned_qty: number
-  scryfall_id: string
-  is_substitute: boolean
-  original_name: string | null
-  substitution_reason: string | null
-  similarity_score: number | null
-}
-
-export interface DeckGenV3Result {
-  commander: {
-    name: string
-    image_url: string
-    type_line: string
-    color_identity: string[]
-    mana_cost: string
-    oracle_text: string
-  }
-  cards: DeckGenV3Card[]
-  stats: DeckAnalysis
-  strategy: string
-  bracket: number
-  model: string
-  substitution?: {
-    owned: number
-    substituted: number
-    missing: number
-  }
-}
-
-// ── Simulation ───────────────────────────────────────────────
-
-export interface SimConfig {
-  deck_names: string[]
-  num_games: number
-  threads: number
-  use_deepseek?: boolean
-}
-
-export interface SimStatus {
-  running: boolean
-  sim_id: string
-  progress?: number
-  games_completed?: number
-  total_games?: number
-}
-
-export interface SimResult {
-  sim_id: string
-  decks: SimDeckResult[]
-  total_games: number
-  duration_ms: number
-  timestamp: string
-}
-
-export interface SimDeckResult {
-  name: string
-  wins: number
-  losses: number
-  win_rate: number
-  avg_turn: number
-}
-
-// ── Batch Sim (Lab) ──────────────────────────────────────────
-
-export interface LabDeck {
-  name: string
-  source: string
-  path: string
-  card_count: number
-}
-
-export interface LabStartRequest {
-  decks: string[]
-  games: number
-  threads?: number
-  use_deepseek?: boolean
-  deepseek_deck?: string
-}
-
-export interface LabStatus {
-  running: boolean
-  run_id: string
-  games_completed: number
-  total_games: number
-  current_decks: string[]
-  error: string | null
-}
-
-export interface LabResult {
-  run_id: string
-  decks: LabDeckResult[]
-  total_games: number
-  timestamp: string
-}
-
-export interface LabDeckResult {
-  name: string
-  wins: number
-  games: number
-  win_rate: number
-  avg_turns: number
-  avg_life_remaining: number
-}
-
-export interface LabHistoryEntry {
-  run_id: string
-  timestamp: string
-  decks: string[]
-  total_games: number
-}
-
-export interface PreconDeck {
-  name: string
-  filename: string
-  release_date?: string
-  set_name?: string
-  installed: boolean
-}
-
-// ── Coach ────────────────────────────────────────────────────
-
-export interface CoachStatus {
-  llmConnected: boolean
-  llmModel: string | null
-  llmModels: string[]
-  embeddingsLoaded: boolean
-  embeddingCards: number
-  deckReportsAvailable: number
-  error: string | null
-}
-
-export interface CoachDeck {
-  deck_id: number
-  deck_name: string
-  commander: string
-  card_count: number
-  has_report: boolean
-  report_count: number
-  last_report_date: string | null
-}
-
-export interface CoachGoals {
-  targetPowerLevel?: number | null
-  metaFocus?: string | null
-  budget?: string | null
-  focusAreas?: string[]
-}
-
-export interface CoachMessage {
-  role: 'user' | 'assistant'
-  content: string
-}
-
-export interface CoachChatResponse {
-  content: string
-  model: string
-  prompt_tokens: number
-  completion_tokens: number
-}
-
-export interface CoachSession {
-  sessionId: string
-  deckId: string
-  timestamp: string
-  summary: string
-  suggestedCuts: CoachSuggestedCut[]
-  suggestedAdds: CoachSuggestedAdd[]
-  heuristicHints: string[]
-  manaBaseAdvice: string | null
-  rawTextExplanation: string
-  modelUsed: string
-  promptTokens: number
-  completionTokens: number
-  goals: CoachGoals | null
-}
-
-export interface CoachSuggestedCut {
-  cardName: string
-  reason: string
-  replacementOptions: string[]
-  currentImpactScore: number
-}
-
-export interface CoachSuggestedAdd {
-  cardName: string
-  role: string
-  reason: string
-  synergyWith: string[]
-  estimatedManaValue: number | null
-}
-
-export interface CoachSessionSummary {
-  sessionId: string
-  deckId: string
-  timestamp: string
-  summary: string
-  cutsCount: number
-  addsCount: number
-}
-
-export interface CoachApplyResult {
-  cuts: { name: string; status: string }[]
-  adds: { name: string; scryfall_id?: string; status: string }[]
-  errors: { name: string; error: string }[]
-  total_cuts: number
-  total_adds: number
-}
-
-export interface CoachCardLikeResult {
-  name: string
-  similarity: number
-  types: string
-  mana_value: number
-  mana_cost: string
-  text: string
-  owned_qty: number
-  image_url: string | null
-  tcg_price: number | null
-}
-
-// ── ML Training ──────────────────────────────────────────────
-
-/** GET /api/ml/status */
-export interface MLStatus {
-  ml_logging_enabled: boolean
-  training_files: { file: string; decisions: number; size_kb: number }[]
-  total_decisions: number
-  total_files: number
-}
-
-/** GET /api/ml/data/status */
-export interface MLDataStatus {
-  decisionFiles: { name: string; size: number; decisions: number }[]
-  totalDecisions: number
-  datasets: Record<string, { samples: number; features: number; size: number }>
-  checkpoints: { name: string; size: number; modified: string }[]
-  evalResults: Record<string, unknown> | null
-  policyLoaded: boolean
-}
-
-/** GET /api/ml/train/status */
-export interface MLTrainStatus {
-  running: boolean
-  progress: number
-  total_epochs: number
-  current_epoch: number
-  phase: 'idle' | 'starting' | 'building' | 'training' | 'evaluating' | 'done' | 'error'
-  message: string
-  metrics: Record<string, unknown> | null
-  result: {
-    training: Record<string, unknown>
-    evaluation: Record<string, unknown> | null
-    checkpoint: string
-    device: string
-  } | null
-  error: string | null
-  started_at: string | null
-}
-
-/** GET /api/ml/train/ppo/status */
-export interface PPOTrainStatus {
-  running: boolean
-  iteration: number
-  total_iterations: number
-  phase: 'idle' | 'starting' | 'training' | 'done' | 'error'
-  message: string
-  metrics: {
-    avg_reward?: number
-    win_rate?: number
-    policy_loss?: number
-    value_loss?: number
-    entropy?: number
-    [key: string]: unknown
-  } | null
-  result: Record<string, unknown> | null
-  error: string | null
-}
-
-/** GET /api/ml/tournament/status */
-export interface TournamentStatus {
-  running: boolean
-  phase: 'idle' | 'starting' | 'running' | 'done' | 'error'
-  message: string
-  result: TournamentResults | null
-  error: string | null
-}
-
-export interface TournamentResults {
-  players: TournamentPlayer[]
-  total_matches: number
-  matchups?: Record<string, unknown>
-}
-
-export interface TournamentPlayer {
-  name: string
-  wins: number
-  games: number
-  win_rate: number
-}
-
-/** GET /api/ml/model */
-export interface MLModelInfo {
-  loaded: boolean
-  device?: string
-  input_dim?: number
-  num_actions?: number
-  checkpoint_path?: string
-  error?: string
-  torch_available?: boolean
-}
-
-// ── DeepSeek ─────────────────────────────────────────────────
-
-export interface DeepSeekStatus {
-  connected: boolean
-  model: string | null
-  base_url: string
-}
-
-// ── Commander Search ─────────────────────────────────────────
-
-export interface CommanderSearchResult {
-  name: string
-  type_line: string
-  color_identity: string[]
-  mana_cost: string
-  image_url: string
-  oracle_text: string
-  scryfall_id: string
-  in_collection: boolean
-}
-
-// ── Perplexity ───────────────────────────────────────────────
-
-export interface PplxStatus {
-  configured: boolean
-  key_prefix: string
-}

frontend/commander-ai-lab-ui/tsconfig.app.json

@@ -1,28 +0,0 @@
-{
-  "compilerOptions": {
-    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
-    "target": "ES2022",
-    "useDefineForClassFields": true,
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "types": ["vite/client"],
-    "skipLibCheck": true,
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "moduleDetection": "force",
-    "noEmit": true,
-    "jsx": "react-jsx",
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "erasableSyntaxOnly": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true
-  },
-  "include": ["src"]
-}

frontend/commander-ai-lab-ui/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "files": [],
-  "references": [
-    { "path": "./tsconfig.app.json" },
-    { "path": "./tsconfig.node.json" }
-  ]
-}

frontend/commander-ai-lab-ui/tsconfig.node.json

@@ -1,26 +0,0 @@
-{
-  "compilerOptions": {
-    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
-    "target": "ES2023",
-    "lib": ["ES2023"],
-    "module": "ESNext",
-    "types": ["node"],
-    "skipLibCheck": true,
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "moduleDetection": "force",
-    "noEmit": true,
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "erasableSyntaxOnly": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true
-  },
-  "include": ["vite.config.ts"]
-}

frontend/commander-ai-lab-ui/vite.config.ts

@@ -1,28 +0,0 @@
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-  server: {
-    port: 5173,
-    proxy: {
-      '/api': {
-        target: 'http://localhost:8080',
-        changeOrigin: true,
-      },
-    },
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: false,
-    rollupOptions: {
-      output: {
-        manualChunks: {
-          recharts: ['recharts'],
-          react: ['react', 'react-dom', 'react-router-dom'],
-        },
-      },
-    },
-  },
-})

ml/actions/labeler.py

@@ -240,12 +240,12 @@ def print_label_distribution(labels: np.ndarray) -> Dict[str, int]:
         dist[action.value] = count
 
     total = len(labels)
-    log.info(f"\n{'Action':<25} {'Count':>8} {'Pct':>8}")
-    log.info("─" * 43)
+    logger.info(f"\n{'Action':<25} {'Count':>8} {'Pct':>8}")
+    logger.info("─" * 43)
     for action_name, count in sorted(dist.items(), key=lambda x: -x[1]):
         pct = (count / total * 100) if total > 0 else 0
-        log.info(f"  {action_name:<23} {count:>8} {pct:>7.1f}%")
-    log.info(f"{'─' * 43}")
-    log.info(f"  {'TOTAL':<23} {total:>8}")
+        logger.info(f"  {action_name:<23} {count:>8} {pct:>7.1f}%")
+    logger.info(f"{'─' * 43}")
+    logger.info(f"  {'TOTAL':<23} {total:>8}")
 
     return dist

ml/config/scope.py

@@ -155,15 +155,25 @@ class StateDimensions:
     2 players = 28 global features
     + turn_number = 1
     Total global = 29
+
+    Zone embedding boundary (architectural decision — Phase 5 follow-up):
+      Zone dims are **always** 768 per zone slot, zero-padded when a zone
+      is empty (no cards).  The fixed 6144-dim zone block is the contract
+      between ForgeEpisodeGenerator (upstream) and the policy network
+      (downstream).  All downstream consumers (PolicyNetwork, PPOTrainer,
+      dataset builder) depend on this shape.  If a future change adds
+      attention pooling or variable-length zone representations, the
+      boundary must be updated here *and* in StateEncoder._encode_zones.
     """
     card_embedding_dim: int = 768       # From mtg-embeddings
-    zone_pool_dim: int = 768            # Mean-pooled per zone
+    zone_pool_dim: int = 768            # Mean-pooled per zone (zero-vec when empty)
 
     # Zones per player: hand, battlefield, graveyard, command_zone
     zones_per_player: int = 4
     num_players: int = 2                # 1v1
 
     # Zone vectors: 4 zones × 2 players × 768 = 6144
+    # This is a fixed-size block; empty zones produce zero vectors.
     total_zone_dim: int = 4 * 2 * 768  # 6144
 
     # Global scalar features
@@ -256,3 +266,85 @@ class TrainingConfig:
     log_every: int = 100               # Log every N batches
 
 TRAINING_CONFIG = TrainingConfig()
+
+
+# ══════════════════════════════════════════════════════════
+# Distillation Loop Defaults (Phase 4)
+# ══════════════════════════════════════════════════════════
+
+@dataclass
+class DistillationDefaults:
+    """Default hyperparameters for the closed-loop distillation pipeline.
+
+    These are consumed by ml.training.distillation_loop.DistillationConfig
+    when no explicit override is provided.
+
+    Default weights: Forge-only (forge_weight=1.0, ppo_weight=0.0).
+    The baseline trains exclusively on Forge simulation data.  Use
+    ``MIXED_MODE_PRESETS`` below for blended Forge+PPO configurations.
+    """
+    max_iterations: int = 10
+    convergence_window: int = 3
+    convergence_threshold: float = 0.01
+
+    # PPO self-play per generation
+    ppo_iterations: int = 50
+    ppo_episodes_per_iter: int = 64
+    ppo_lr: float = 3e-4
+    ppo_clip_epsilon: float = 0.2
+    ppo_entropy_coeff: float = 0.01
+    ppo_eval_episodes: int = 100
+
+    # Dataset mixing — Forge-only by default (Phase 5 follow-up decision)
+    forge_weight: float = 1.0
+    ppo_weight: float = 0.0
+    min_reward_threshold: float = 0.0
+
+    # Quality gate thresholds
+    min_forge_accuracy: float = 0.35
+    max_accuracy_drop: float = 0.03
+    min_ppo_win_rate: float = 0.30
+
+    # Retry behaviour on gate failure
+    max_retries_per_generation: int = 2
+    retry_lr_factor: float = 0.5
+    retry_entropy_boost: float = 0.005
+
+    # Output paths
+    results_dir: str = "data/results"
+    history_dir: str = "data/results/distillation-history"
+
+
+DISTILLATION_DEFAULTS = DistillationDefaults()
+
+
+# ══════════════════════════════════════════════════════════
+# Mixed-Mode Presets (Phase 5 follow-up)
+# ══════════════════════════════════════════════════════════
+
+# Pre-defined Forge/PPO weight combinations for common scenarios.
+# Select a preset by name when starting a distillation run to
+# override the Forge-only defaults without specifying raw weights.
+#
+# "forge_only"  — baseline: 100% Forge data, ignore PPO
+# "forge_90_10" — light PPO blending: 90% Forge, 10% PPO
+# "forge_80_20" — heavier PPO blending: 80% Forge, 20% PPO
+MIXED_MODE_PRESETS: Dict[str, Dict[str, float]] = {
+    "forge_only": {"forge_weight": 1.0, "ppo_weight": 0.0},
+    "forge_90_10": {"forge_weight": 1.0, "ppo_weight": 0.11},  # ~10% PPO
+    "forge_80_20": {"forge_weight": 1.0, "ppo_weight": 0.25},  # ~20% PPO
+}
+
+
+def get_preset_weights(preset_name: str) -> Dict[str, float]:
+    """Look up a mixed-mode preset by name.
+
+    Returns a dict with ``forge_weight`` and ``ppo_weight`` keys.
+    Raises ``KeyError`` if the preset name is unknown.
+    """
+    if preset_name not in MIXED_MODE_PRESETS:
+        raise KeyError(
+            f"Unknown preset '{preset_name}'. "
+            f"Available: {list(MIXED_MODE_PRESETS.keys())}"
+        )
+    return dict(MIXED_MODE_PRESETS[preset_name])

ml/data/dataset_builder.py

@@ -1,9 +1,17 @@
 """
 Commander AI Lab — Training Dataset Builder
 ════════════════════════════════════════════
+
 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)
+  - Configurable source_weights for sampling ratios
+  - min_reward_threshold filter for PPO data quality
+  - Each sample tagged with source for downstream analysis
+
 Usage:
     python -m ml.data.dataset_builder --results-dir results/ --output ml/models/dataset.npz
 
@@ -13,6 +21,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")
 """
 
 import argparse
@@ -20,8 +29,9 @@ import json
 import logging
 import os
 import sys
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Dict, List, Tuple
+from typing import Dict, List, Optional, Tuple
 
 import numpy as np
 
@@ -40,22 +50,167 @@ logging.basicConfig(level=logging.INFO, format="[%(name)s] %(message)s")
 logger = logging.getLogger("ml.dataset")
 
 
+# ---------------------------------------------------------------------------
+# Configuration (Phase 2)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class DatasetConfig:
+    """Configuration for dataset building with source awareness."""
+
+    results_dir: str = "results"
+    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: Dict[str, float] = field(
+        default_factory=lambda: {"forge": 1.0, "ppo": 0.0}
+    )
+
+    # Minimum reward threshold for PPO data — only include decisions
+    # from games where the episode return exceeds this value.
+    # Set to None to disable filtering.
+    min_reward_threshold: Optional[float] = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Source-aware file discovery (Phase 2 — Task 1)
+# ---------------------------------------------------------------------------
+
+def _discover_jsonl_files(results_dir: str) -> Dict[str, List[Path]]:
+    """
+    Scan results directory for both Forge sim and PPO 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
+    """
+    results_path = Path(results_dir)
+    sources = {}
+
+    # Forge batch sim files
+    forge_files = sorted(results_path.glob("ml-decisions-sim-*.jsonl"))
+    if forge_files:
+        sources["forge"] = forge_files
+
+    # PPO self-play files (from Phase 1 DecisionExporter)
+    ppo_files = sorted(results_path.glob("ml-decisions-ppo-*.jsonl"))
+    if ppo_files:
+        sources["ppo"] = ppo_files
+
+    # Also pick up legacy files that don't have sim/ppo prefix
+    legacy_files = sorted(
+        f for f in results_path.glob("ml-decisions-*.jsonl")
+        if f not in set(forge_files + ppo_files)
+    )
+    if legacy_files:
+        sources.setdefault("forge", []).extend(legacy_files)
+
+    return sources
+
+
+# ---------------------------------------------------------------------------
+# PPO reward filter (Phase 2 — Task 3)
+# ---------------------------------------------------------------------------
+
+def _passes_reward_filter(
+    decision: dict,
+    source: str,
+    min_reward_threshold: Optional[float],
+) -> bool:
+    """
+    Filter PPO decisions by reward threshold.
+    Forge data always passes. PPO data must meet the threshold.
+    """
+    if source != "ppo":
+        return True
+    if min_reward_threshold is None:
+        return True
+    episode_return = decision.get("episode_return", 0.0)
+    return episode_return >= min_reward_threshold
+
+
+# ---------------------------------------------------------------------------
+# Source-aware sampling (Phase 2 — Task 2)
+# ---------------------------------------------------------------------------
+
+def _apply_source_weights(
+    samples_by_source: Dict[str, List[dict]],
+    source_weights: Dict[str, float],
+    rng: np.random.Generator,
+) -> List[dict]:
+    """
+    Apply source weights to control the mixing ratio.
+
+    A weight of 1.0 keeps all samples from that source.
+    A weight of 0.5 randomly keeps ~50% of samples.
+    A weight > 1.0 oversamples (with replacement).
+    """
+    combined = []
+    for source, samples in samples_by_source.items():
+        weight = source_weights.get(source, 1.0)
+        if weight <= 0:
+            logger.info("  Skipping %d %s samples (weight=0)", len(samples), source)
+            continue
+        if weight >= 1.0 and weight == 1.0:
+            combined.extend(samples)
+        elif weight < 1.0:
+            # Subsample
+            n_keep = max(1, int(len(samples) * weight))
+            indices = rng.choice(len(samples), size=n_keep, replace=False)
+            combined.extend(samples[i] for i in indices)
+            logger.info(
+                "  Subsampled %s: %d → %d (weight=%.2f)",
+                source, len(samples), n_keep, weight,
+            )
+        else:
+            # Oversample (weight > 1.0)
+            n_target = int(len(samples) * weight)
+            indices = rng.choice(len(samples), size=n_target, replace=True)
+            combined.extend(samples[i] for i in indices)
+            logger.info(
+                "  Oversampled %s: %d → %d (weight=%.2f)",
+                source, len(samples), n_target, weight,
+            )
+    return combined
+
+
+# ---------------------------------------------------------------------------
+# Main dataset builder (updated for Phase 2)
+# ---------------------------------------------------------------------------
+
 def build_dataset(
     results_dir: str,
     embeddings_dir: str = None,
     max_samples: int = None,
+    source_weights: Dict[str, float] = None,
+    min_reward_threshold: float = 0.0,
 ) -> Dict[str, np.ndarray]:
     """
     Build complete training dataset from all ML decision files.
 
+    Phase 2 additions:
+      - Scans both Forge and PPO JSONL files
+      - Applies source_weights for configurable mixing
+      - Filters PPO data by min_reward_threshold
+      - Tags each sample with its source
+
     Args:
-        results_dir: Path to results/ directory containing ml-decisions-*.jsonl
+        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)
+        min_reward_threshold: Min episode_return for PPO data (default: 0.0)
 
     Returns:
-        Dict with keys: states, labels, game_ids, outcomes, playstyles
+        Dict with keys: states, labels, game_ids, outcomes, playstyles, sources
     """
+    if source_weights is None:
+        source_weights = {"forge": 1.0, "ppo": 0.0}
+
     # Load card embeddings
     card_index = CardEmbeddingIndex(embeddings_dir)
     if not card_index.load():
@@ -70,10 +225,9 @@ def build_dataset(
 
     encoder = StateEncoder(card_index)
 
-    # Find all JSONL files
-    results_path = Path(results_dir)
-    jsonl_files = sorted(results_path.glob("ml-decisions-*.jsonl"))
-    if not jsonl_files:
+    # --- Phase 2 Task 1: Discover files from both sources ---
+    source_files = _discover_jsonl_files(results_dir)
+    if not source_files:
         logger.error("No ML decision files found in %s", results_dir)
         logger.error("Run batch simulations with --ml-log or enable ML logging in the UI first.")
         raise RuntimeError(
@@ -81,60 +235,114 @@ def build_dataset(
             "Run batch simulations with ML logging enabled first."
         )
 
-    logger.info("Found %d ML decision files", len(jsonl_files))
+    total_files = sum(len(files) for files in source_files.values())
+    logger.info(
+        "Found %d ML decision files across %d sources: %s",
+        total_files,
+        len(source_files),
+        {src: len(files) for src, files in source_files.items()},
+    )
 
+    # --- Read and filter all decisions, grouped by source ---
+    rng = np.random.default_rng(42)
+    samples_by_source: Dict[str, List[dict]] = {}
+    total_skipped = 0
+    total_filtered = 0
+
+    for source, jsonl_files in source_files.items():
+        source_samples = []
+
+        for jsonl_file in jsonl_files:
+            logger.info("Processing %s [%s] ...", jsonl_file.name, source)
+            file_count = 0
+
+            with open(jsonl_file, "r") as f:
+                for line_num, line in enumerate(f):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        decision = json.loads(line)
+
+                        # --- Phase 2 Task 3: PPO reward filter ---
+                        if not _passes_reward_filter(
+                            decision, source, min_reward_threshold
+                        ):
+                            total_filtered += 1
+                            continue
+
+                        # --- Phase 2 Task 4: Tag with source ---
+                        decision["_source"] = source
+
+                        source_samples.append(decision)
+                        file_count += 1
+
+                    except Exception as e:
+                        total_skipped += 1
+                        if total_skipped <= 10:
+                            logger.warning(
+                                "Skipping %s line %d: %s", jsonl_file.name, line_num, e
+                            )
+
+            logger.info("  → %d samples from %s", file_count, jsonl_file.name)
+
+        if source_samples:
+            samples_by_source[source] = source_samples
+
+    if not samples_by_source:
+        logger.error("No valid samples found.")
+        return {}
+
+    # Log per-source counts before weighting
+    for src, samples in samples_by_source.items():
+        logger.info("Source '%s': %d raw samples", src, len(samples))
+    if total_filtered > 0:
+        logger.info("PPO reward filter removed %d samples (threshold=%.2f)",
+                     total_filtered, min_reward_threshold or 0.0)
+
+    # --- Phase 2 Task 2: Apply source weights ---
+    combined_decisions = _apply_source_weights(
+        samples_by_source, source_weights, rng
+    )
+
+    # Apply max_samples cap after weighting
+    if max_samples and len(combined_decisions) > max_samples:
+        rng.shuffle(combined_decisions)
+        combined_decisions = combined_decisions[:max_samples]
+        logger.info("Capped to %d samples", max_samples)
+
+    # --- Encode all decisions ---
     all_states = []
     all_labels = []
     all_game_ids = []
     all_outcomes = []
     all_playstyles = []
-    total_skipped = 0
+    all_sources = []
+    encode_errors = 0
 
-    for jsonl_file in jsonl_files:
-        logger.info("Processing %s ...", jsonl_file.name)
-        file_count = 0
+    for decision in combined_decisions:
+        try:
+            playstyle = decision.get("archetype", "midrange")
+            state_vec = encoder.encode(decision, playstyle)
+            action_idx = label_action(decision)
+            game_id = decision.get("game_id", "unknown")
+            outcome = decision.get("game_outcome", "unknown")
+            source = decision.get("_source", "forge")
 
-        with open(jsonl_file, "r") as f:
-            for line_num, line in enumerate(f):
-                if max_samples and len(all_states) >= max_samples:
-                    break
+            all_states.append(state_vec)
+            all_labels.append(action_idx)
+            all_game_ids.append(game_id)
+            all_outcomes.append(outcome)
+            all_playstyles.append(playstyle)
+            all_sources.append(source)
 
-                line = line.strip()
-                if not line:
-                    continue
-
-                try:
-                    decision = json.loads(line)
-
-                    # Encode state
-                    playstyle = decision.get("archetype", "midrange")
-                    state_vec = encoder.encode(decision, playstyle)
-
-                    # Label action
-                    action_idx = label_action(decision)
-
-                    # Metadata
-                    game_id = decision.get("game_id", f"unknown-{line_num}")
-                    outcome = decision.get("game_outcome", "unknown")
-
-                    all_states.append(state_vec)
-                    all_labels.append(action_idx)
-                    all_game_ids.append(game_id)
-                    all_outcomes.append(outcome)
-                    all_playstyles.append(playstyle)
-                    file_count += 1
-
-                except Exception as e:
-                    total_skipped += 1
-                    if total_skipped <= 10:
-                        logger.warning(
-                            "Skipping %s line %d: %s", jsonl_file.name, line_num, e
-                        )
-
-        logger.info("  → %d samples from %s", file_count, jsonl_file.name)
+        except Exception as e:
+            encode_errors += 1
+            if encode_errors <= 5:
+                logger.warning("Encode error: %s", e)
 
     if not all_states:
-        logger.error("No valid samples found.")
+        logger.error("No valid samples after encoding.")
         return {}
 
     # Convert to arrays
@@ -143,10 +351,11 @@ def build_dataset(
     game_ids = np.array(all_game_ids, dtype=object)
     outcomes = np.array(all_outcomes, dtype=object)
     playstyles = np.array(all_playstyles, dtype=object)
+    sources = np.array(all_sources, dtype=object)
 
     logger.info(
-        "Dataset built: %d samples, %d features, %d actions, %d skipped",
-        len(states), states.shape[1], NUM_ACTIONS, total_skipped,
+        "Dataset built: %d samples, %d features, %d actions, %d skipped, %d encode errors",
+        len(states), states.shape[1], NUM_ACTIONS, total_skipped, encode_errors,
     )
 
     # Print label distribution
@@ -154,17 +363,25 @@ def build_dataset(
 
     # Print game outcome distribution
     unique_outcomes, outcome_counts = np.unique(outcomes, return_counts=True)
-    log.info(f"\n{'Outcome':<25} {'Count':>8}")
-    log.info("─" * 35)
+    logger.info(f"\n{'Outcome':<25} {'Count':>8}")
+    logger.info("─" * 35)
     for o, c in sorted(zip(unique_outcomes, outcome_counts), key=lambda x: -x[1]):
-        log.info(f"  {str(o):<23} {c:>8}")
+        logger.info(f"  {str(o):<23} {c:>8}")
 
     # Print playstyle distribution
     unique_styles, style_counts = np.unique(playstyles, return_counts=True)
-    log.info(f"\n{'Playstyle':<25} {'Count':>8}")
-    log.info("─" * 35)
+    logger.info(f"\n{'Playstyle':<25} {'Count':>8}")
+    logger.info("─" * 35)
     for s, c in sorted(zip(unique_styles, style_counts), key=lambda x: -x[1]):
-        log.info(f"  {str(s):<23} {c:>8}")
+        logger.info(f"  {str(s):<23} {c:>8}")
+
+    # --- Phase 2 Task 4: Print source distribution ---
+    unique_sources, source_counts = np.unique(sources, return_counts=True)
+    logger.info(f"\n{'Source':<25} {'Count':>8} {'%':>7}")
+    logger.info("─" * 42)
+    for s, c in sorted(zip(unique_sources, source_counts), key=lambda x: -x[1]):
+        pct = 100.0 * c / len(sources)
+        logger.info(f"  {str(s):<23} {c:>8} {pct:>6.1f}%")
 
     return {
         "states": states,
@@ -172,6 +389,7 @@ def build_dataset(
         "game_ids": game_ids,
         "outcomes": outcomes,
         "playstyles": playstyles,
+        "sources": sources,
     }
 
 
@@ -240,7 +458,6 @@ def split_dataset(
         len(train["states"]), len(val["states"]), len(test["states"]),
         split_by_game,
     )
-
     return train, val, test
 
 
@@ -279,16 +496,38 @@ def main():
         "--no-split", action="store_true",
         help="Don't split into train/val/test (save single file)",
     )
+    # Phase 2 CLI arguments
+    parser.add_argument(
+        "--forge-weight", type=float, default=1.0,
+        help="Sampling weight for Forge sim data (default: 1.0)",
+    )
+    parser.add_argument(
+        "--ppo-weight", type=float, default=0.0,
+        help="Sampling weight for PPO self-play data (default: 0.0, Forge-only)",
+    )
+    parser.add_argument(
+        "--min-reward", type=float, default=0.0,
+        help="Minimum episode_return for PPO data (default: 0.0)",
+    )
+
     args = parser.parse_args()
 
+    source_weights = {
+        "forge": args.forge_weight,
+        "ppo": args.ppo_weight,
+    }
+
     # Build dataset
     dataset = build_dataset(
         results_dir=args.results_dir,
         embeddings_dir=args.embeddings_dir,
         max_samples=args.max_samples,
+        source_weights=source_weights,
+        min_reward_threshold=args.min_reward,
     )
+
     if not dataset:
-        log.info("\nNo data to save. Run simulations with --ml-log first.")
+        logger.info("\nNo data to save. Run simulations with --ml-log first.")
         sys.exit(1)
 
     if args.no_split:
@@ -300,7 +539,7 @@ def main():
         save_dataset(val, f"{base}-val.npz")
         save_dataset(test, f"{base}-test.npz")
 
-    log.info("\nDataset build complete.")
+    logger.info("\nDataset build complete.")
 
 
 if __name__ == "__main__":

ml/data/quality_gate.py

@@ -0,0 +1,587 @@
+"""
+Commander AI Lab — Quality Gate & Validation
+═════════════════════════════════════════════
+
+Phase 3 (Issue #67): Prevents bad PPO data from degrading the
+supervised model by enforcing quality gates at multiple levels:
+
+1. Forge Validation Holdout — fixed eval set from Forge-only data
+2. Accuracy Gate — reject PPO batch if model accuracy drops on Forge eval
+3. Win Rate Gate — only export PPO decisions above a win rate threshold
+4. Data Quality Metrics — entropy, reward distribution logging
+
+Usage:
+    from ml.data.quality_gate import QualityGate, QualityGateConfig
+
+    gate = QualityGate(QualityGateConfig(
+        min_forge_accuracy=0.40,
+        min_ppo_win_rate=0.30,
+    ))
+
+    # Check if PPO batch should be accepted
+    verdict = gate.evaluate_ppo_batch(
+        forge_eval_accuracy=0.42,
+        ppo_win_rate=0.35,
+        ppo_decisions=decisions_list,
+        baseline_accuracy=0.41,
+    )
+    if verdict.accepted:
+        # merge PPO data into training set
+        ...
+
+Ref: docs/CLOSED-LOOP-DISTILLATION.md — Phase 3
+Issue: #67
+"""
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger("ml.quality_gate")
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+@dataclass
+class QualityGateConfig:
+    """Configuration for the quality gate system."""
+
+    # --- Forge validation holdout (Task 1) ---
+    forge_holdout_ratio: float = 0.12  # 12% of Forge data held out
+    forge_holdout_seed: int = 99       # Fixed seed for reproducibility
+
+    # --- Accuracy gate (Task 2) ---
+    # If model accuracy on Forge eval drops below this absolute floor,
+    # the PPO batch is rejected regardless.
+    min_forge_accuracy: float = 0.35
+
+    # If model accuracy drops by more than this relative amount compared
+    # to the baseline (pre-PPO model), reject the batch.
+    max_accuracy_drop: float = 0.03  # e.g., 41% → 38% = 3% drop → reject
+
+    # --- Win rate gate (Task 3) ---
+    # PPO agent must exceed this win rate before its decisions are exported.
+    # In a 4-player pod, random baseline is 25%.
+    min_ppo_win_rate: float = 0.30
+
+    # --- Quality metrics (Task 4) ---
+    # Directory to write quality reports
+    reports_dir: str = "data/results/quality-reports"
+
+
+# ---------------------------------------------------------------------------
+# Verdict dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class GateVerdict:
+    """Result of a quality gate evaluation."""
+    accepted: bool
+    reason: str
+    metrics: Dict = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def to_dict(self) -> dict:
+        return {
+            "accepted": self.accepted,
+            "reason": self.reason,
+            "metrics": self.metrics,
+            "timestamp": self.timestamp,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Forge Validation Holdout (Task 1)
+# ---------------------------------------------------------------------------
+
+def create_forge_holdout(
+    states: np.ndarray,
+    labels: np.ndarray,
+    sources: np.ndarray,
+    game_ids: np.ndarray,
+    holdout_ratio: float = 0.12,
+    seed: int = 99,
+) -> Tuple[Dict[str, np.ndarray], Dict[str, np.ndarray]]:
+    """
+    Split Forge-only data into training and holdout validation sets.
+
+    The holdout set is a fixed eval set used to detect accuracy regression
+    when PPO data is mixed in. Split is done by game_id to prevent leakage.
+
+    Args:
+        states, labels, sources, game_ids: Dataset arrays
+        holdout_ratio: Fraction of Forge games to hold out
+        seed: Fixed random seed for reproducibility
+
+    Returns:
+        (train_data, holdout_data) — each a dict with states, labels, sources, game_ids
+    """
+    # Identify Forge-only samples
+    forge_mask = np.array([s == "forge" for s in sources])
+    ppo_mask = ~forge_mask
+
+    forge_game_ids = game_ids[forge_mask]
+    unique_forge_games = np.unique(forge_game_ids)
+
+    # Deterministic split by game_id
+    rng = np.random.default_rng(seed)
+    rng.shuffle(unique_forge_games)
+
+    n_holdout = max(1, int(len(unique_forge_games) * holdout_ratio))
+    holdout_games = set(unique_forge_games[:n_holdout])
+    train_games = set(unique_forge_games[n_holdout:])
+
+    # Build masks
+    forge_holdout_mask = np.array([
+        (s == "forge" and gid in holdout_games)
+        for s, gid in zip(sources, game_ids)
+    ])
+    forge_train_mask = np.array([
+        (s == "forge" and gid in train_games)
+        for s, gid in zip(sources, game_ids)
+    ])
+
+    # Training set = Forge train + all PPO data
+    train_mask = forge_train_mask | ppo_mask
+
+    def _subset(mask):
+        return {
+            "states": states[mask],
+            "labels": labels[mask],
+            "sources": sources[mask],
+            "game_ids": game_ids[mask],
+        }
+
+    holdout = _subset(forge_holdout_mask)
+    train = _subset(train_mask)
+
+    logger.info(
+        "Forge holdout: %d samples (%d games) held out, %d train samples remaining",
+        forge_holdout_mask.sum(), n_holdout, train_mask.sum(),
+    )
+
+    return train, holdout
+
+
+# ---------------------------------------------------------------------------
+# Accuracy Gate (Task 2)
+# ---------------------------------------------------------------------------
+
+def check_accuracy_gate(
+    current_accuracy: float,
+    baseline_accuracy: float,
+    config: QualityGateConfig,
+) -> GateVerdict:
+    """
+    Check if the current model accuracy on the Forge holdout set
+    is acceptable after training with PPO data mixed in.
+
+    Args:
+        current_accuracy: Accuracy on Forge holdout after training with PPO data
+        baseline_accuracy: Accuracy on Forge holdout from previous model (no PPO)
+        config: Quality gate configuration
+
+    Returns:
+        GateVerdict — accepted=True if accuracy is acceptable
+    """
+    metrics = {
+        "current_accuracy": round(current_accuracy, 4),
+        "baseline_accuracy": round(baseline_accuracy, 4),
+        "accuracy_drop": round(baseline_accuracy - current_accuracy, 4),
+        "min_forge_accuracy": config.min_forge_accuracy,
+        "max_accuracy_drop": config.max_accuracy_drop,
+    }
+
+    # Check absolute floor
+    if current_accuracy < config.min_forge_accuracy:
+        return GateVerdict(
+            accepted=False,
+            reason=(
+                f"Forge eval accuracy ({current_accuracy:.1%}) below absolute "
+                f"minimum ({config.min_forge_accuracy:.1%}). PPO batch rejected."
+            ),
+            metrics=metrics,
+        )
+
+    # Check relative drop
+    drop = baseline_accuracy - current_accuracy
+    if drop > config.max_accuracy_drop:
+        return GateVerdict(
+            accepted=False,
+            reason=(
+                f"Forge eval accuracy dropped {drop:.1%} "
+                f"(from {baseline_accuracy:.1%} to {current_accuracy:.1%}), "
+                f"exceeding max allowed drop of {config.max_accuracy_drop:.1%}. "
+                f"PPO batch rejected."
+            ),
+            metrics=metrics,
+        )
+
+    return GateVerdict(
+        accepted=True,
+        reason=(
+            f"Forge eval accuracy {current_accuracy:.1%} is acceptable "
+            f"(baseline={baseline_accuracy:.1%}, drop={drop:.1%}). "
+            f"PPO batch accepted."
+        ),
+        metrics=metrics,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Win Rate Gate (Task 3)
+# ---------------------------------------------------------------------------
+
+def check_win_rate_gate(
+    ppo_win_rate: float,
+    config: QualityGateConfig,
+    total_episodes: int = 0,
+    min_episodes: int = 20,
+) -> GateVerdict:
+    """
+    Check if the PPO agent's win rate exceeds the minimum threshold
+    before allowing its decisions to be exported.
+
+    Args:
+        ppo_win_rate: Win rate of PPO agent (0.0 to 1.0)
+        config: Quality gate configuration
+        total_episodes: Number of episodes played
+        min_episodes: Minimum episodes required for statistical significance
+
+    Returns:
+        GateVerdict — accepted=True if win rate is sufficient
+    """
+    metrics = {
+        "ppo_win_rate": round(ppo_win_rate, 4),
+        "min_ppo_win_rate": config.min_ppo_win_rate,
+        "total_episodes": total_episodes,
+        "min_episodes": min_episodes,
+    }
+
+    # Check minimum episode count
+    if total_episodes < min_episodes:
+        return GateVerdict(
+            accepted=False,
+            reason=(
+                f"Insufficient episodes ({total_episodes}/{min_episodes}). "
+                f"Need at least {min_episodes} episodes for reliable win rate."
+            ),
+            metrics=metrics,
+        )
+
+    # Check win rate threshold
+    if ppo_win_rate < config.min_ppo_win_rate:
+        return GateVerdict(
+            accepted=False,
+            reason=(
+                f"PPO win rate ({ppo_win_rate:.1%}) below minimum "
+                f"threshold ({config.min_ppo_win_rate:.1%}). "
+                f"Agent not strong enough — decisions not exported."
+            ),
+            metrics=metrics,
+        )
+
+    return GateVerdict(
+        accepted=True,
+        reason=(
+            f"PPO win rate ({ppo_win_rate:.1%}) exceeds minimum "
+            f"({config.min_ppo_win_rate:.1%}) over {total_episodes} episodes. "
+            f"Decisions approved for export."
+        ),
+        metrics=metrics,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Data Quality Metrics (Task 4)
+# ---------------------------------------------------------------------------
+
+def compute_action_entropy(action_indices: np.ndarray, num_actions: int = 8) -> float:
+    """
+    Compute Shannon entropy of the action distribution.
+
+    High entropy = diverse actions (good).
+    Low entropy = collapsed to few actions (bad — possible mode collapse).
+    Max entropy for 8 actions = log2(8) = 3.0 bits.
+    """
+    counts = np.bincount(action_indices, minlength=num_actions).astype(np.float64)
+    probs = counts / max(counts.sum(), 1)
+    # Filter zero probabilities for log
+    probs = probs[probs > 0]
+    entropy = -np.sum(probs * np.log2(probs))
+    return float(entropy)
+
+
+def compute_reward_stats(rewards: np.ndarray) -> Dict[str, float]:
+    """Compute summary statistics for reward/episode_return distribution."""
+    if len(rewards) == 0:
+        return {"mean": 0.0, "std": 0.0, "min": 0.0, "max": 0.0,
+                "median": 0.0, "p25": 0.0, "p75": 0.0}
+    return {
+        "mean": float(np.mean(rewards)),
+        "std": float(np.std(rewards)),
+        "min": float(np.min(rewards)),
+        "max": float(np.max(rewards)),
+        "median": float(np.median(rewards)),
+        "p25": float(np.percentile(rewards, 25)),
+        "p75": float(np.percentile(rewards, 75)),
+    }
+
+
+def compute_quality_metrics(
+    decisions: List[dict],
+    num_actions: int = 8,
+) -> Dict:
+    """
+    Compute comprehensive data quality metrics for a batch of decisions.
+
+    Metrics:
+      - action_entropy: Shannon entropy of action distribution
+      - action_distribution: count per action
+      - reward_stats: mean, std, min, max, median, p25, p75
+      - source_breakdown: count per source
+      - total_decisions: number of decisions
+      - unique_games: number of unique game IDs
+
+    Args:
+        decisions: List of decision dicts (from JSONL records)
+        num_actions: Total number of possible actions
+
+    Returns:
+        Dict of quality metrics
+    """
+    if not decisions:
+        return {"total_decisions": 0, "error": "empty batch"}
+
+    # Extract action indices
+    action_indices = np.array([
+        d.get("action", {}).get("action_idx", d.get("action_idx", 0))
+        for d in decisions
+    ])
+
+    # Extract rewards/episode returns
+    rewards = np.array([
+        d.get("episode_return", d.get("reward", 0.0))
+        for d in decisions
+    ])
+
+    # Action distribution
+    action_counts = np.bincount(action_indices, minlength=num_actions)
+    action_distribution = {
+        str(i): int(c) for i, c in enumerate(action_counts)
+    }
+
+    # Source breakdown
+    sources = [d.get("source", d.get("_source", "unknown")) for d in decisions]
+    source_counts = {}
+    for s in sources:
+        source_counts[s] = source_counts.get(s, 0) + 1
+
+    # Unique games
+    game_ids = set(d.get("game_id", "?") for d in decisions)
+
+    # Entropy
+    entropy = compute_action_entropy(action_indices, num_actions)
+    max_entropy = np.log2(num_actions)
+
+    return {
+        "total_decisions": len(decisions),
+        "unique_games": len(game_ids),
+        "action_entropy": round(entropy, 4),
+        "max_entropy": round(max_entropy, 4),
+        "entropy_ratio": round(entropy / max(max_entropy, 1e-8), 4),
+        "action_distribution": action_distribution,
+        "reward_stats": compute_reward_stats(rewards),
+        "source_breakdown": source_counts,
+    }
+
+
+def log_quality_metrics(metrics: Dict):
+    """Pretty-print quality metrics to the logger."""
+    logger.info("")
+    logger.info("=" * 55)
+    logger.info("  Data Quality Report")
+    logger.info("=" * 55)
+    logger.info("  Total decisions:   %d", metrics.get("total_decisions", 0))
+    logger.info("  Unique games:      %d", metrics.get("unique_games", 0))
+    logger.info("  Action entropy:    %.3f / %.3f (%.0f%%)",
+                metrics.get("action_entropy", 0),
+                metrics.get("max_entropy", 0),
+                metrics.get("entropy_ratio", 0) * 100)
+    logger.info("")
+
+    # Action distribution
+    dist = metrics.get("action_distribution", {})
+    if dist:
+        total = sum(dist.values())
+        logger.info("  %-20s %8s %7s", "Action", "Count", "%")
+        logger.info("  " + "-" * 37)
+        for action_idx, count in sorted(dist.items(), key=lambda x: -x[1]):
+            pct = 100.0 * count / max(total, 1)
+            logger.info("  %-20s %8d %6.1f%%", f"action_{action_idx}", count, pct)
+
+    # Reward stats
+    rstats = metrics.get("reward_stats", {})
+    if rstats:
+        logger.info("")
+        logger.info("  Reward distribution:")
+        logger.info("    mean=%.3f  std=%.3f  min=%.3f  max=%.3f",
+                    rstats.get("mean", 0), rstats.get("std", 0),
+                    rstats.get("min", 0), rstats.get("max", 0))
+        logger.info("    p25=%.3f  median=%.3f  p75=%.3f",
+                    rstats.get("p25", 0), rstats.get("median", 0),
+                    rstats.get("p75", 0))
+
+    # Source breakdown
+    sources = metrics.get("source_breakdown", {})
+    if sources:
+        logger.info("")
+        logger.info("  Source breakdown:")
+        for src, cnt in sorted(sources.items(), key=lambda x: -x[1]):
+            logger.info("    %-12s %d", src, cnt)
+
+    logger.info("=" * 55)
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator — QualityGate class
+# ---------------------------------------------------------------------------
+
+class QualityGate:
+    """
+    Orchestrates all quality checks for the closed-loop distillation pipeline.
+
+    Usage:
+        gate = QualityGate(config)
+
+        # Before exporting PPO decisions:
+        win_verdict = gate.check_win_rate(ppo_win_rate=0.35, total_episodes=100)
+
+        # After training with mixed data:
+        acc_verdict = gate.check_accuracy(
+            current_accuracy=0.42,
+            baseline_accuracy=0.41,
+        )
+
+        # Log quality metrics for a batch:
+        gate.report_batch_quality(decisions)
+    """
+
+    def __init__(self, config: QualityGateConfig = None):
+        self.config = config or QualityGateConfig()
+        self.verdicts: List[GateVerdict] = []
+
+    def check_win_rate(
+        self,
+        ppo_win_rate: float,
+        total_episodes: int = 0,
+        min_episodes: int = 20,
+    ) -> GateVerdict:
+        """Check if PPO agent meets win rate threshold for export."""
+        verdict = check_win_rate_gate(
+            ppo_win_rate, self.config, total_episodes, min_episodes
+        )
+        self.verdicts.append(verdict)
+        if verdict.accepted:
+            logger.info("WIN RATE GATE: PASS — %s", verdict.reason)
+        else:
+            logger.warning("WIN RATE GATE: FAIL — %s", verdict.reason)
+        return verdict
+
+    def check_accuracy(
+        self,
+        current_accuracy: float,
+        baseline_accuracy: float,
+    ) -> GateVerdict:
+        """Check if model accuracy on Forge holdout is acceptable."""
+        verdict = check_accuracy_gate(
+            current_accuracy, baseline_accuracy, self.config
+        )
+        self.verdicts.append(verdict)
+        if verdict.accepted:
+            logger.info("ACCURACY GATE: PASS — %s", verdict.reason)
+        else:
+            logger.warning("ACCURACY GATE: FAIL — %s", verdict.reason)
+        return verdict
+
+    def report_batch_quality(self, decisions: List[dict]) -> Dict:
+        """Compute and log quality metrics for a decision batch."""
+        metrics = compute_quality_metrics(decisions)
+        log_quality_metrics(metrics)
+
+        # Save report to disk
+        os.makedirs(self.config.reports_dir, exist_ok=True)
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+        report_path = os.path.join(
+            self.config.reports_dir, f"quality_{timestamp}.json"
+        )
+        with open(report_path, "w") as f:
+            json.dump(metrics, f, indent=2)
+        logger.info("Quality report saved: %s", report_path)
+
+        return metrics
+
+    def evaluate_ppo_batch(
+        self,
+        forge_eval_accuracy: float,
+        ppo_win_rate: float,
+        ppo_decisions: List[dict],
+        baseline_accuracy: float,
+        total_episodes: int = 0,
+    ) -> GateVerdict:
+        """
+        Run all quality gates on a PPO batch. Returns a combined verdict.
+
+        This is the main entry point for the distillation pipeline to decide
+        whether to accept or reject a batch of PPO-generated training data.
+        """
+        # 1. Win rate gate
+        win_verdict = self.check_win_rate(ppo_win_rate, total_episodes)
+        if not win_verdict.accepted:
+            return win_verdict
+
+        # 2. Accuracy gate
+        acc_verdict = self.check_accuracy(forge_eval_accuracy, baseline_accuracy)
+        if not acc_verdict.accepted:
+            return acc_verdict
+
+        # 3. Log quality metrics (informational, doesn't block)
+        quality_metrics = self.report_batch_quality(ppo_decisions)
+
+        # 4. Check for extreme entropy collapse (soft warning)
+        entropy_ratio = quality_metrics.get("entropy_ratio", 1.0)
+        if entropy_ratio < 0.3:
+            logger.warning(
+                "LOW ENTROPY WARNING: action entropy ratio %.2f — "
+                "possible mode collapse in PPO agent",
+                entropy_ratio,
+            )
+
+        return GateVerdict(
+            accepted=True,
+            reason="All quality gates passed.",
+            metrics={
+                "win_rate": win_verdict.metrics,
+                "accuracy": acc_verdict.metrics,
+                "quality": quality_metrics,
+            },
+        )
+
+    def save_verdict_history(self, path: str = None):
+        """Save all verdict history to a JSON file."""
+        if path is None:
+            os.makedirs(self.config.reports_dir, exist_ok=True)
+            path = os.path.join(self.config.reports_dir, "verdict_history.json")
+
+        history = [v.to_dict() for v in self.verdicts]
+        with open(path, "w") as f:
+            json.dump(history, f, indent=2)
+        logger.info("Verdict history saved: %s (%d entries)", path, len(history))

ml/encoder/state_encoder.py

@@ -276,6 +276,13 @@ class StateEncoder:
         """
         Encode zone contents as mean-pooled card embeddings.
         Shape: (4 zones × 2 players × 768) = (6144,)
+
+        Zone embedding boundary: each zone slot is exactly ``zone_pool_dim``
+        (768) floats.  Empty zones produce a zero vector of that size.  This
+        fixed-size contract is relied upon by every downstream consumer
+        (PolicyNetwork, PPOTrainer, dataset builder).  See
+        ``StateDimensions`` in ``ml/config/scope.py`` for the canonical
+        definition.
         """
         zone_keys = ["hand", "battlefield", "graveyard", "command_zone"]
         vectors = []
@@ -283,6 +290,8 @@ class StateEncoder:
         for p in players[:2]:
             for zone_key in zone_keys:
                 cards = p.get(zone_key, [])
+                # mean_pool_zone returns a zero vector when cards is empty,
+                # preserving the fixed 768-dim slot size.
                 pooled = self.card_index.mean_pool_zone(cards)
                 vectors.append(pooled)
 

ml/eval/elo_tracker.py

@@ -0,0 +1,407 @@
+"""
+Commander AI Lab — ELO Tracker & Cross-Generation Tournament
+═══════════════════════════════════════════════════════════════
+Phase 6 (Issue #70): Quantify improvement across distillation
+generations using ELO ratings.
+
+- Runs round-robin tournaments between generation checkpoints
+  and baselines (heuristic, random)
+- Computes ELO ratings using the standard formula
+- Persists ELO history to `data/elo_history.json`
+- Provides ELO delta for convergence detection
+
+Reuses `run_match`, `LearnedPolicy`, `HeuristicPolicy`,
+`RandomPolicy` from `ml/eval/tournament.py`.
+
+Usage:
+    python -m ml.eval.elo_tracker
+    python -m ml.eval.elo_tracker --episodes 50 --output data/elo_history.json
+"""
+
+import json
+import logging
+import math
+import os
+import sys
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from itertools import combinations
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+project_root = str(Path(__file__).parent.parent.parent)
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+
+from ml.eval.tournament import (
+    run_match, LearnedPolicy, HeuristicPolicy, RandomPolicy,
+)
+
+logger = logging.getLogger("ml.eval.elo")
+
+
+# ═══════════════════════════════════════════════════════════
+# ELO Rating Engine
+# ═══════════════════════════════════════════════════════════
+
+DEFAULT_K = 32
+DEFAULT_START_ELO = 1200.0
+
+
+class EloTracker:
+    """Standard ELO rating tracker."""
+
+    def __init__(self, k_factor: float = DEFAULT_K, start_elo: float = DEFAULT_START_ELO):
+        self.k = k_factor
+        self.start_elo = start_elo
+        self.ratings: Dict[str, float] = {}
+
+    def ensure_player(self, name: str):
+        if name not in self.ratings:
+            self.ratings[name] = self.start_elo
+
+    def expected_score(self, rating_a: float, rating_b: float) -> float:
+        return 1.0 / (1.0 + math.pow(10, (rating_b - rating_a) / 400.0))
+
+    def update(self, winner: str, loser: str):
+        """Update ratings after a decisive match."""
+        self.ensure_player(winner)
+        self.ensure_player(loser)
+
+        e_win = self.expected_score(self.ratings[winner], self.ratings[loser])
+        e_lose = self.expected_score(self.ratings[loser], self.ratings[winner])
+
+        self.ratings[winner] += self.k * (1.0 - e_win)
+        self.ratings[loser] += self.k * (0.0 - e_lose)
+
+    def update_draw(self, player_a: str, player_b: str):
+        """Update ratings after a draw."""
+        self.ensure_player(player_a)
+        self.ensure_player(player_b)
+
+        e_a = self.expected_score(self.ratings[player_a], self.ratings[player_b])
+        e_b = self.expected_score(self.ratings[player_b], self.ratings[player_a])
+
+        self.ratings[player_a] += self.k * (0.5 - e_a)
+        self.ratings[player_b] += self.k * (0.5 - e_b)
+
+    def get_ratings(self) -> Dict[str, float]:
+        """Return a copy of current ratings, rounded to 1 decimal."""
+        return {k: round(v, 1) for k, v in self.ratings.items()}
+
+
+# ═══════════════════════════════════════════════════════════
+# ELO Result
+# ═══════════════════════════════════════════════════════════
+
+@dataclass
+class EloResult:
+    """Result of an ELO-rated tournament."""
+    ratings: Dict[str, float] = field(default_factory=dict)
+    match_count: int = 0
+    total_time_s: float = 0.0
+    policies: List[str] = field(default_factory=list)
+    rating_progression: List[Dict[str, float]] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "ratings": self.ratings,
+            "match_count": self.match_count,
+            "total_time_s": round(self.total_time_s, 1),
+            "policies": self.policies,
+            "rating_progression": self.rating_progression,
+        }
+
+
+# ═══════════════════════════════════════════════════════════
+# ELO History (persistence)
+# ═══════════════════════════════════════════════════════════
+
+class EloHistory:
+    """Persists ELO ratings across tournament runs."""
+
+    def __init__(self, path: str = "data/elo_history.json"):
+        self.path = path
+        self.entries: List[dict] = []
+        self._load()
+
+    def _load(self):
+        if os.path.exists(self.path):
+            try:
+                with open(self.path, "r") as f:
+                    data = json.load(f)
+                self.entries = data.get("entries", [])
+            except Exception:
+                self.entries = []
+
+    def save(self):
+        os.makedirs(os.path.dirname(self.path) or ".", exist_ok=True)
+        with open(self.path, "w") as f:
+            json.dump({"entries": self.entries}, f, indent=2)
+
+    def append(self, generation: int, ratings: Dict[str, float]):
+        """Add a new ELO snapshot after a tournament."""
+        self.entries.append({
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "generation": generation,
+            "ratings": {k: round(v, 1) for k, v in ratings.items()},
+        })
+        self.save()
+
+    def get_elo_delta(self, window: int = 2) -> Optional[float]:
+        """
+        Compute average ELO gain of the latest generation model
+        over the last `window` entries.
+
+        Returns None if insufficient data.
+        """
+        if len(self.entries) < window:
+            return None
+
+        recent = self.entries[-window:]
+        deltas = []
+
+        for i in range(1, len(recent)):
+            prev_ratings = recent[i - 1]["ratings"]
+            curr_ratings = recent[i]["ratings"]
+
+            # Find the latest generation model name in current entry
+            gen_models = [k for k in curr_ratings if k.startswith("gen-")]
+            if not gen_models:
+                continue
+
+            latest_gen = sorted(gen_models)[-1]
+            curr_elo = curr_ratings.get(latest_gen, DEFAULT_START_ELO)
+
+            # Compare to previous entry's latest gen model, or heuristic
+            prev_gen_models = [k for k in prev_ratings if k.startswith("gen-")]
+            if prev_gen_models:
+                prev_latest = sorted(prev_gen_models)[-1]
+                prev_elo = prev_ratings.get(prev_latest, DEFAULT_START_ELO)
+            else:
+                prev_elo = prev_ratings.get("heuristic", DEFAULT_START_ELO)
+
+            deltas.append(curr_elo - prev_elo)
+
+        if not deltas:
+            return None
+
+        return sum(deltas) / len(deltas)
+
+    def to_dict(self) -> dict:
+        return {"entries": self.entries}
+
+    @classmethod
+    def from_dict(cls, data: dict, path: str = "data/elo_history.json") -> "EloHistory":
+        h = cls.__new__(cls)
+        h.path = path
+        h.entries = data.get("entries", [])
+        return h
+
+
+# ═══════════════════════════════════════════════════════════
+# Tournament Functions
+# ═══════════════════════════════════════════════════════════
+
+def run_elo_tournament(
+    policies: Dict[str, object],
+    episodes_per_matchup: int = 50,
+    playstyle: str = "midrange",
+    k_factor: float = DEFAULT_K,
+) -> EloResult:
+    """
+    Run a round-robin ELO-rated tournament.
+
+    Uses `run_match` from tournament.py for match execution.
+
+    Args:
+        policies: Dict mapping name → policy object (with select_action method)
+        episodes_per_matchup: Games per pair (played both sides)
+        playstyle: Game playstyle
+        k_factor: ELO K-factor
+
+    Returns:
+        EloResult with final ratings, match count, and progression
+    """
+    t_start = time.time()
+    names = list(policies.keys())
+    tracker = EloTracker(k_factor=k_factor)
+
+    # Initialize all players
+    for name in names:
+        tracker.ensure_player(name)
+
+    progression = [tracker.get_ratings().copy()]
+    total_matches = 0
+
+    logger.info("ELO Tournament: %d policies, %d games/matchup", len(names), episodes_per_matchup)
+
+    for name_a, name_b in combinations(names, 2):
+        policy_a = policies[name_a]
+        policy_b = policies[name_b]
+
+        for ep in range(episodes_per_matchup):
+            # Game 1: A as seat 0
+            m1 = run_match(policy_a, name_a, policy_b, name_b, playstyle=playstyle)
+            total_matches += 1
+            if m1.winner == name_a:
+                tracker.update(name_a, name_b)
+            elif m1.winner == name_b:
+                tracker.update(name_b, name_a)
+            else:
+                tracker.update_draw(name_a, name_b)
+
+            # Game 2: B as seat 0
+            m2 = run_match(policy_b, name_b, policy_a, name_a, playstyle=playstyle)
+            total_matches += 1
+            if m2.winner == name_a:
+                tracker.update(name_a, name_b)
+            elif m2.winner == name_b:
+                tracker.update(name_b, name_a)
+            else:
+                tracker.update_draw(name_a, name_b)
+
+        # Record progression after each matchup
+        progression.append(tracker.get_ratings().copy())
+
+        logger.info(
+            "  %s (%.0f) vs %s (%.0f)",
+            name_a, tracker.ratings[name_a],
+            name_b, tracker.ratings[name_b],
+        )
+
+    return EloResult(
+        ratings=tracker.get_ratings(),
+        match_count=total_matches,
+        total_time_s=time.time() - t_start,
+        policies=names,
+        rating_progression=progression,
+    )
+
+
+def run_generation_tournament(
+    checkpoint_dir: str = "ml/models/checkpoints",
+    episodes_per_matchup: int = 50,
+    playstyle: str = "midrange",
+    k_factor: float = DEFAULT_K,
+) -> EloResult:
+    """
+    Discover generation checkpoints and run an ELO tournament.
+
+    Looks for `gen-*/best_policy.pt` under checkpoint_dir.
+    Also includes heuristic and random baselines.
+    """
+    policies: Dict[str, object] = {
+        "heuristic": HeuristicPolicy(),
+        "random": RandomPolicy(),
+    }
+
+    ckpt_path = Path(checkpoint_dir)
+    if ckpt_path.exists():
+        for gen_dir in sorted(ckpt_path.glob("gen-*")):
+            model_path = gen_dir / "best_policy.pt"
+            if model_path.exists():
+                name = gen_dir.name  # e.g., "gen-001"
+                policies[name] = LearnedPolicy(str(model_path))
+                logger.info("Loaded %s: %s", name, model_path)
+
+        # Also check standard checkpoints
+        sup_path = ckpt_path / "best_policy.pt"
+        if sup_path.exists() and "supervised" not in policies:
+            policies["supervised"] = LearnedPolicy(str(sup_path))
+
+        ppo_path = ckpt_path / "best_ppo.pt"
+        if ppo_path.exists() and "ppo" not in policies:
+            policies["ppo"] = LearnedPolicy(str(ppo_path))
+
+    if len(policies) < 2:
+        logger.warning("Need at least 2 policies for ELO tournament")
+        return EloResult(
+            ratings={k: DEFAULT_START_ELO for k in policies},
+            policies=list(policies.keys()),
+        )
+
+    logger.info("Running ELO tournament with %d policies: %s", len(policies), list(policies.keys()))
+
+    return run_elo_tournament(
+        policies=policies,
+        episodes_per_matchup=episodes_per_matchup,
+        playstyle=playstyle,
+        k_factor=k_factor,
+    )
+
+
+# ═══════════════════════════════════════════════════════════
+# CLI
+# ═══════════════════════════════════════════════════════════
+
+def main():
+    """CLI entry point for ELO tournament."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Commander AI Lab — ELO Tournament"
+    )
+    parser.add_argument(
+        "--episodes", type=int, default=50,
+        help="Episodes per matchup (default: 50)",
+    )
+    parser.add_argument(
+        "--checkpoint-dir", default="ml/models/checkpoints",
+        help="Checkpoint directory (default: ml/models/checkpoints)",
+    )
+    parser.add_argument(
+        "--playstyle", default="midrange",
+        help="Playstyle (default: midrange)",
+    )
+    parser.add_argument(
+        "--output", default="data/elo_history.json",
+        help="Output path for ELO history (default: data/elo_history.json)",
+    )
+    parser.add_argument(
+        "--k-factor", type=float, default=32,
+        help="ELO K-factor (default: 32)",
+    )
+
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    result = run_generation_tournament(
+        checkpoint_dir=args.checkpoint_dir,
+        episodes_per_matchup=args.episodes,
+        playstyle=args.playstyle,
+        k_factor=args.k_factor,
+    )
+
+    # Print results
+    logger.info("")
+    logger.info("=" * 50)
+    logger.info("  ELO RATINGS")
+    logger.info("=" * 50)
+    sorted_ratings = sorted(result.ratings.items(), key=lambda x: x[1], reverse=True)
+    for name, elo in sorted_ratings:
+        logger.info("  %-20s %7.1f", name, elo)
+    logger.info("")
+    logger.info("  %d matches in %.1f s", result.match_count, result.total_time_s)
+    logger.info("=" * 50)
+
+    # Save to history
+    history = EloHistory(path=args.output)
+    # Use the latest generation number, or 0 if no gen models
+    gen_models = [k for k in result.ratings if k.startswith("gen-")]
+    gen_num = 0
+    if gen_models:
+        try:
+            gen_num = max(int(g.split("-")[1]) for g in gen_models)
+        except (ValueError, IndexError):
+            pass
+    history.append(gen_num, result.ratings)
+    logger.info("ELO history saved: %s", args.output)
+
+    print(json.dumps(result.to_dict(), indent=2))
+
+
+if __name__ == "__main__":
+    main()

ml/scripts/update_weights.py

@@ -0,0 +1,344 @@
+"""
+update_weights.py
+=================
+Outcome-weighted reinforcement learning for Commander AI card weights.
+
+Reads all decisions_*.jsonl files produced by DeepSeekBrain.flush_log(),
+applies a gradient-free reward nudge to each weight key based on the
+normalised reward signal (-1.0 to +1.0) stamped on every decision entry,
+then saves the updated weights to learned_weights.json via save_weights().
+
+Usage
+-----
+    # Basic run (reads logs/decisions/, updates learned_weights.json)
+    python -m ml.scripts.update_weights
+
+    # Custom paths
+    python -m ml.scripts.update_weights \\
+        --log-dir logs/decisions \\
+        --weights-out src/commander_ai_lab/sim/learned_weights.json \\
+        --lr 0.05 \\
+        --min-games 10
+
+    # Dry-run (print proposed changes, don't write)
+    python -m ml.scripts.update_weights --dry-run
+
+    # Reset to defaults then exit
+    python -m ml.scripts.update_weights --reset
+
+Algorithm
+---------
+For each decision entry that has a non-null game_result:
+
+    delta = learning_rate * reward * action_weight_for(action)
+
+Each weight key is nudged by the mean delta across all decisions that
+touched that key.  Keys with no decisions are left unchanged.
+All values are clamped to [-20.0, 20.0] by save_weights().
+
+Reward is the normalised life-delta from flush_log():
+    reward = (my_final_life - avg_opp_final_life) / 40.0  in [-1.0, 1.0]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Iterator
+
+# ---------------------------------------------------------------------------
+# Allow running as a script without installing the package
+# ---------------------------------------------------------------------------
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT / "src") not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT / "src"))
+
+from commander_ai_lab.sim.rules import (
+    AI_DEFAULT_WEIGHTS,
+    load_weights,
+    reset_weights,
+    save_weights,
+)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger("update_weights")
+
+# ---------------------------------------------------------------------------
+# Action → weight key mapping
+# Maps each VALID_ACTION to the weight(s) it most directly influences.
+# A single action may touch multiple keys (listed as a tuple).
+# ---------------------------------------------------------------------------
+ACTION_WEIGHT_MAP: dict[str, tuple[str, ...]] = {
+    "play_land":       (),                                    # no weight key — always correct
+    "cast_ramp":       ("spell_ramp",),
+    "cast_removal":    ("spell_destroy",),
+    "cast_board_wipe": ("spell_counter",),                   # reuse counter as board-control proxy
+    "cast_creature":   ("card_ptBonus",),
+    "cast_spell":      ("spell_enchantment", "spell_draw"),
+    "attack_all":      ("kw_haste", "kw_flying"),            # aggression / evasion proxy
+    "attack_safe":     ("kw_flying", "kw_trample"),
+    "hold":            (),                                    # no weight key — passing is neutral
+}
+
+
+# ---------------------------------------------------------------------------
+# JSONL helpers
+# ---------------------------------------------------------------------------
+
+def _iter_log_entries(log_dir: str) -> Iterator[dict]:
+    """Yield every entry from all decisions_*.jsonl files in log_dir."""
+    log_path = Path(log_dir)
+    if not log_path.exists():
+        logger.warning("Log directory not found: %s", log_dir)
+        return
+
+    files = sorted(log_path.glob("decisions_*.jsonl"))
+    if not files:
+        logger.warning("No decisions_*.jsonl files found in %s", log_dir)
+        return
+
+    logger.info("Found %d log file(s) in %s", len(files), log_dir)
+    for fpath in files:
+        with open(fpath, encoding="utf-8") as f:
+            for lineno, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    yield json.loads(line)
+                except json.JSONDecodeError as exc:
+                    logger.warning("Skipping malformed line %d in %s: %s", lineno, fpath.name, exc)
+
+
+# ---------------------------------------------------------------------------
+# Core learning loop
+# ---------------------------------------------------------------------------
+
+def compute_weight_updates(
+    log_dir: str,
+    current_weights: dict[str, float],
+    learning_rate: float = 0.05,
+    min_games: int = 1,
+) -> tuple[dict[str, float], dict]:
+    """
+    Read decision logs and compute updated weights.
+
+    Returns
+    -------
+    updated_weights : dict[str, float]
+        New weight dict after applying mean reward nudges.
+    stats : dict
+        Diagnostic info (games seen, decisions processed, keys changed, etc.)
+    """
+    # Accumulators: key → list of (reward * lr) deltas
+    key_deltas: dict[str, list[float]] = defaultdict(list)
+
+    total_entries = 0
+    labelled_entries = 0  # entries with non-null game_result
+    game_ids_seen: set[str] = set()
+    action_counts: dict[str, int] = defaultdict(int)
+
+    for entry in _iter_log_entries(log_dir):
+        total_entries += 1
+
+        game_result = entry.get("game_result")
+        if not game_result:
+            continue  # no outcome stamped — skip (pre-flush or incomplete game)
+
+        labelled_entries += 1
+        game_ids_seen.add(entry.get("game_id", "unknown"))
+
+        reward: float = float(game_result.get("reward", 0.0))
+        action: str = entry.get("decision", {}).get("action", "hold")
+        action_counts[action] += 1
+
+        weight_keys = ACTION_WEIGHT_MAP.get(action, ())
+        for key in weight_keys:
+            if key in current_weights:
+                key_deltas[key].append(learning_rate * reward)
+
+    num_games = len(game_ids_seen)
+    logger.info(
+        "Processed %d entries | %d labelled | %d unique games",
+        total_entries, labelled_entries, num_games,
+    )
+
+    if num_games < min_games:
+        logger.warning(
+            "Only %d game(s) found — minimum is %d.  Skipping update.",
+            num_games, min_games,
+        )
+        return dict(current_weights), {
+            "skipped": True,
+            "reason": f"need {min_games} games, have {num_games}",
+            "total_entries": total_entries,
+            "labelled_entries": labelled_entries,
+            "games": num_games,
+        }
+
+    # Apply mean delta per key
+    updated = dict(current_weights)
+    changed_keys: dict[str, tuple[float, float]] = {}  # key → (old, new)
+
+    for key, deltas in key_deltas.items():
+        if not deltas:
+            continue
+        mean_delta = sum(deltas) / len(deltas)
+        old_val = updated[key]
+        new_val = round(old_val + mean_delta, 6)
+        updated[key] = new_val
+        if abs(new_val - old_val) >= 0.0001:
+            changed_keys[key] = (old_val, new_val)
+
+    stats = {
+        "skipped": False,
+        "total_entries": total_entries,
+        "labelled_entries": labelled_entries,
+        "games": num_games,
+        "keys_changed": len(changed_keys),
+        "changes": changed_keys,
+        "action_counts": dict(action_counts),
+    }
+    return updated, stats
+
+
+def print_diff(stats: dict, current: dict, updated: dict) -> None:
+    """Pretty-print weight changes to stdout."""
+    changes = stats.get("changes", {})
+    if not changes:
+        print("  (no weight changes above threshold)")
+        return
+
+    col_w = max(len(k) for k in changes) + 2
+    print(f"  {'Key':<{col_w}}  {'Before':>10}  {'After':>10}  {'Delta':>10}")
+    print("  " + "-" * (col_w + 36))
+    for key, (old, new) in sorted(changes.items(), key=lambda x: abs(x[1][1] - x[1][0]), reverse=True):
+        delta = new - old
+        arrow = "▲" if delta > 0 else "▼"
+        print(f"  {key:<{col_w}}  {old:>10.4f}  {new:>10.4f}  {arrow} {abs(delta):>8.4f}")
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def _default_log_dir() -> str:
+    return str(_REPO_ROOT / "logs" / "decisions")
+
+
+def _default_weights_out() -> str:
+    return str(_REPO_ROOT / "src" / "commander_ai_lab" / "sim" / "learned_weights.json")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Update AI card weights from simulation decision logs."
+    )
+    parser.add_argument(
+        "--log-dir",
+        default=_default_log_dir(),
+        help="Directory containing decisions_*.jsonl files (default: logs/decisions/)",
+    )
+    parser.add_argument(
+        "--weights-out",
+        default=_default_weights_out(),
+        help="Path to write learned_weights.json (default: src/.../sim/learned_weights.json)",
+    )
+    parser.add_argument(
+        "--lr",
+        type=float,
+        default=0.05,
+        help="Learning rate — how much each game nudges a weight (default: 0.05)",
+    )
+    parser.add_argument(
+        "--min-games",
+        type=int,
+        default=10,
+        help="Minimum number of completed games required before updating (default: 10)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print proposed changes without writing learned_weights.json",
+    )
+    parser.add_argument(
+        "--reset",
+        action="store_true",
+        help="Delete learned_weights.json and restore AI_DEFAULT_WEIGHTS, then exit",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show action distribution and per-key delta counts",
+    )
+    args = parser.parse_args(argv)
+
+    # ── Reset mode ──────────────────────────────────────────────
+    if args.reset:
+        reset_weights(args.weights_out)
+        print(f"Reset: deleted {args.weights_out} (if it existed). Defaults restored.")
+        return 0
+
+    # ── Load current weights ─────────────────────────────────────
+    current = load_weights(args.weights_out)
+    logger.info("Loaded %d weight keys from %s", len(current), args.weights_out)
+
+    # ── Compute updates ──────────────────────────────────────────
+    updated, stats = compute_weight_updates(
+        log_dir=args.log_dir,
+        current_weights=current,
+        learning_rate=args.lr,
+        min_games=args.min_games,
+    )
+
+    # ── Report ───────────────────────────────────────────────────
+    print()
+    print("=" * 60)
+    print("  Commander AI — Weight Update Report")
+    print("=" * 60)
+    print(f"  Log dir    : {args.log_dir}")
+    print(f"  Weights out: {args.weights_out}")
+    print(f"  Games      : {stats['games']}")
+    print(f"  Entries    : {stats['total_entries']}  ({stats['labelled_entries']} labelled)")
+    print(f"  LR         : {args.lr}")
+    print()
+
+    if stats.get("skipped"):
+        print(f"  SKIPPED — {stats['reason']}")
+        print()
+        return 0
+
+    print(f"  Keys changed: {stats['keys_changed']}")
+    print()
+    print_diff(stats, current, updated)
+    print()
+
+    if args.verbose:
+        print("  Action distribution:")
+        for action, count in sorted(stats["action_counts"].items(), key=lambda x: -x[1]):
+            print(f"    {action:<20} {count:>6} decisions")
+        print()
+
+    # ── Write ────────────────────────────────────────────────────
+    if args.dry_run:
+        print("  DRY RUN — no file written.")
+    else:
+        out_path = save_weights(updated, args.weights_out)
+        print(f"  Saved updated weights to: {out_path}")
+
+    print("=" * 60)
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ml/serving/online_learning_store.py

@@ -0,0 +1,210 @@
+"""
+Commander AI Lab — Online Learning Store (SQLite WAL)
+═════════════════════════════════════════════════════
+
+Single-machine backing store for online learning data collected during
+policy inference (``/api/ml/predict`` and ``/api/policy/decide``).
+
+Each prediction request can optionally log the state snapshot and the
+chosen action so that future training runs can incorporate online
+decision data alongside Forge and PPO batches.
+
+Design decisions (Phase 5 architecture follow-up):
+  - SQLite in WAL mode for concurrent readers + single writer, which is
+    the right fit for a single-machine baseline (one API server process).
+  - Separate DB file (``online_learning.db``) to avoid contention with
+    the collection database.
+  - Append-only writes; reads are batched by the dataset builder.
+  - Thread-safe via the Python sqlite3 module's ``check_same_thread=False``
+    and WAL's built-in reader/writer concurrency.
+
+Usage::
+
+    store = OnlineLearningStore()   # uses default path
+    store.init_db()
+
+    # At prediction time:
+    store.record_decision(snapshot_json, action_index, confidence, playstyle)
+
+    # At training time:
+    decisions = store.fetch_decisions(since_rowid=last_seen, limit=10000)
+    store.mark_exported(max_rowid)
+"""
+
+import json
+import logging
+import os
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Dict, List, Optional
+
+logger = logging.getLogger("ml.serving.online_store")
+
+_DEFAULT_DB_PATH = str(
+    Path(__file__).parent.parent.parent / "online_learning.db"
+)
+
+
+class OnlineLearningStore:
+    """SQLite WAL-backed store for online policy decision collection."""
+
+    def __init__(self, db_path: str = None):
+        self.db_path = db_path or _DEFAULT_DB_PATH
+        self._local = threading.local()
+
+    # ------------------------------------------------------------------
+    # Connection management
+    # ------------------------------------------------------------------
+
+    def _get_conn(self) -> sqlite3.Connection:
+        """Return a thread-local connection with WAL mode enabled."""
+        if not hasattr(self._local, "conn") or self._local.conn is None:
+            conn = sqlite3.connect(self.db_path, check_same_thread=False)
+            conn.row_factory = sqlite3.Row
+            # Enable WAL for concurrent read/write on single machine.
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.execute("PRAGMA synchronous=NORMAL")
+            self._local.conn = conn
+        return self._local.conn
+
+    def close(self) -> None:
+        """Close the thread-local connection."""
+        conn = getattr(self._local, "conn", None)
+        if conn is not None:
+            try:
+                conn.close()
+            except Exception:
+                pass
+            self._local.conn = None
+
+    # ------------------------------------------------------------------
+    # Schema
+    # ------------------------------------------------------------------
+
+    def init_db(self) -> None:
+        """Create the decisions table if it doesn't exist."""
+        conn = self._get_conn()
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS online_decisions (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                snapshot    TEXT    NOT NULL,
+                action_idx  INTEGER NOT NULL,
+                confidence  REAL    NOT NULL DEFAULT 0.0,
+                playstyle   TEXT    NOT NULL DEFAULT 'midrange',
+                temperature REAL    NOT NULL DEFAULT 1.0,
+                greedy      INTEGER NOT NULL DEFAULT 0,
+                exported    INTEGER NOT NULL DEFAULT 0,
+                created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_od_exported
+                ON online_decisions(exported);
+            CREATE INDEX IF NOT EXISTS idx_od_created
+                ON online_decisions(created_at);
+        """)
+        conn.commit()
+        logger.info("Online learning store ready: %s (WAL mode)", self.db_path)
+
+    # ------------------------------------------------------------------
+    # Write path (called during prediction)
+    # ------------------------------------------------------------------
+
+    def record_decision(
+        self,
+        snapshot: Dict,
+        action_idx: int,
+        confidence: float,
+        playstyle: str = "midrange",
+        temperature: float = 1.0,
+        greedy: bool = False,
+    ) -> int:
+        """Append a policy decision for future training.
+
+        Returns the row id of the inserted record.
+        """
+        conn = self._get_conn()
+        cur = conn.execute(
+            """
+            INSERT INTO online_decisions
+                (snapshot, action_idx, confidence, playstyle, temperature, greedy)
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            (
+                json.dumps(snapshot, separators=(",", ":")),
+                action_idx,
+                confidence,
+                playstyle,
+                temperature,
+                1 if greedy else 0,
+            ),
+        )
+        conn.commit()
+        return cur.lastrowid
+
+    # ------------------------------------------------------------------
+    # Read path (called by dataset builder / training pipeline)
+    # ------------------------------------------------------------------
+
+    def fetch_decisions(
+        self,
+        since_rowid: int = 0,
+        limit: int = 50000,
+        only_unexported: bool = True,
+    ) -> List[Dict]:
+        """Fetch collected decisions for training.
+
+        Args:
+            since_rowid: Only return rows with id > this value.
+            limit: Max rows to return.
+            only_unexported: If True, skip rows already marked exported.
+
+        Returns:
+            List of dicts with keys: id, snapshot (parsed), action_idx,
+            confidence, playstyle, temperature, greedy, created_at.
+        """
+        conn = self._get_conn()
+        clauses = ["id > ?"]
+        params: list = [since_rowid]
+        if only_unexported:
+            clauses.append("exported = 0")
+        where = " AND ".join(clauses)
+        rows = conn.execute(
+            f"SELECT * FROM online_decisions WHERE {where} ORDER BY id LIMIT ?",
+            (*params, limit),
+        ).fetchall()
+        results = []
+        for row in rows:
+            d = dict(row)
+            try:
+                d["snapshot"] = json.loads(d["snapshot"])
+            except (json.JSONDecodeError, TypeError):
+                pass
+            results.append(d)
+        return results
+
+    def mark_exported(self, up_to_rowid: int) -> int:
+        """Mark decisions as exported so they aren't fetched again.
+
+        Returns the number of rows updated.
+        """
+        conn = self._get_conn()
+        cur = conn.execute(
+            "UPDATE online_decisions SET exported = 1 WHERE id <= ? AND exported = 0",
+            (up_to_rowid,),
+        )
+        conn.commit()
+        return cur.rowcount
+
+    def count(self, only_unexported: bool = False) -> int:
+        """Return the total number of stored decisions."""
+        conn = self._get_conn()
+        if only_unexported:
+            row = conn.execute(
+                "SELECT COUNT(*) FROM online_decisions WHERE exported = 0"
+            ).fetchone()
+        else:
+            row = conn.execute(
+                "SELECT COUNT(*) FROM online_decisions"
+            ).fetchone()
+        return row[0]

ml/training/decision_exporter.py

@@ -0,0 +1,286 @@
+"""
+Commander AI Lab — PPO Decision Exporter
+════════════════════════════════════════
+
+Exports PPO self-play decisions as JSONL files in the same schema
+as Forge DecisionSnapshot records. This enables the closed-loop
+distillation pipeline where PPO-discovered strategies flow back
+into the supervised training dataset.
+
+Output files: data/results/ml-decisions-ppo-{batch_id}.jsonl
+
+Each line is a JSON object compatible with the dataset_builder.py
+ingestion pipeline, tagged with source="ppo" metadata.
+
+Ref: docs/CLOSED-LOOP-DISTILLATION.md — Phase 1
+Issue: #65
+"""
+
+import json
+import logging
+import os
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import sys
+
+project_root = str(Path(__file__).parent.parent.parent)
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+
+from ml.config.scope import IDX_TO_ACTION, MacroAction
+
+logger = logging.getLogger("ml.decision_exporter")
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ExporterConfig:
+    """Configuration for the PPO decision exporter."""
+
+    output_dir: str = "data/results"
+    only_wins: bool = True          # Only export decisions from winning games
+    model_version: str = "unknown"
+    min_episode_steps: int = 3      # Skip very short episodes (likely noise)
+
+
+# ---------------------------------------------------------------------------
+# Decision Record Builder
+# ---------------------------------------------------------------------------
+
+def _macro_action_to_forge_type(action: MacroAction) -> str:
+    """Map a MacroAction enum to the closest Forge action type string."""
+    mapping = {
+        MacroAction.CAST_CREATURE: "cast_spell",
+        MacroAction.CAST_REMOVAL: "cast_spell",
+        MacroAction.CAST_DRAW: "cast_spell",
+        MacroAction.CAST_RAMP: "cast_spell",
+        MacroAction.CAST_COMMANDER: "cast_spell",
+        MacroAction.ATTACK_OPPONENT: "attack",
+        MacroAction.HOLD_MANA: "pass_priority",
+        MacroAction.PASS: "pass_priority",
+    }
+    return mapping.get(action, "pass_priority")
+
+
+def build_decision_record(
+    game_state_snapshot: dict,
+    action_idx: int,
+    reward: float,
+    agent_seat: int,
+    game_id: str,
+    game_outcome: str,
+    archetype: str = "midrange",
+    source: str = "ppo",
+    model_version: str = "unknown",
+    episode_return: float = 0.0,
+) -> dict:
+    """
+    Build a single decision record in Forge-compatible JSONL format.
+
+    The record mirrors the schema consumed by dataset_builder.py so that
+    PPO-generated data can be mixed into the supervised training set.
+    """
+    action = IDX_TO_ACTION[action_idx]
+    players = game_state_snapshot.get("players", [])
+
+    # Build per-player state matching Forge snapshot layout
+    player_snapshots = []
+    for i, p in enumerate(players):
+        player_snapshots.append({
+            "seat": i,
+            "life": p.get("life_total", 40),
+            "handSize": p.get("cards_in_hand", 0),
+            "permanentCount": p.get("creatures_on_battlefield", 0),
+            "graveyardSize": p.get("cards_in_graveyard", 0),
+            "manaAvailable": p.get("mana_available", 0),
+            "commanderDamageTaken": p.get("commander_damage_taken", 0),
+            "totalPowerOnBoard": p.get("total_power_on_board", 0),
+            "commanderTax": p.get("commander_tax", 0),
+        })
+
+    return {
+        # --- Core fields consumed by dataset_builder / labeler ---
+        "game_id": game_id,
+        "game_outcome": game_outcome,
+        "archetype": archetype,
+
+        # Action info (used by ml.actions.labeler)
+        "action": {
+            "type": _macro_action_to_forge_type(action),
+            "macro_action": action.value,
+            "action_idx": action_idx,
+            "seat": agent_seat,
+        },
+
+        # Board / game state
+        "turn": game_state_snapshot.get("turn", 1),
+        "phase": game_state_snapshot.get("phase", "main_1"),
+        "active_seat": game_state_snapshot.get("active_seat", 0),
+        "players": player_snapshots,
+
+        # --- PPO-specific metadata (distinguishes from Forge data) ---
+        "source": source,
+        "model_version": model_version,
+        "reward": round(reward, 6),
+        "episode_return": round(episode_return, 6),
+    }
+
+
+# ---------------------------------------------------------------------------
+# DecisionExporter — accumulates episode decisions and flushes to JSONL
+# ---------------------------------------------------------------------------
+
+class DecisionExporter:
+    """
+    Collects decisions from PPO self-play episodes and writes them
+    to JSONL files compatible with the supervised training pipeline.
+
+    Usage::
+
+        exporter = DecisionExporter(ExporterConfig(model_version="gen-0"))
+
+        for ep in range(num_episodes):
+            exporter.begin_episode(agent_seat=0, playstyle="midrange")
+            for step in episode_steps:
+                exporter.record_step(state_snapshot, action_idx, reward)
+            exporter.end_episode(won=True, episode_return=3.14)
+
+        exporter.flush()   # writes JSONL to disk
+        print(exporter.stats)
+    """
+
+    def __init__(self, config: ExporterConfig = None):
+        self.config = config or ExporterConfig()
+        self._batch_id = str(uuid.uuid4())[:8]
+        self._records: List[dict] = []
+        self._episode_buffer: List[dict] = []
+        self._current_game_id: Optional[str] = None
+        self._current_seat: int = 0
+        self._current_playstyle: str = "midrange"
+
+        # Stats
+        self._total_episodes = 0
+        self._exported_episodes = 0
+        self._exported_decisions = 0
+        self._skipped_losses = 0
+        self._skipped_short = 0
+
+    # -- Episode lifecycle ---------------------------------------------------
+
+    def begin_episode(self, agent_seat: int = 0, playstyle: str = "midrange"):
+        """Start tracking a new episode."""
+        self._episode_buffer = []
+        self._current_game_id = f"ppo-{self._batch_id}-{self._total_episodes}"
+        self._current_seat = agent_seat
+        self._current_playstyle = playstyle
+
+    def record_step(
+        self,
+        game_state_snapshot: dict,
+        action_idx: int,
+        reward: float,
+    ):
+        """Record a single decision step within the current episode."""
+        self._episode_buffer.append({
+            "snapshot": game_state_snapshot,
+            "action_idx": action_idx,
+            "reward": reward,
+        })
+
+    def end_episode(self, won: bool, episode_return: float = 0.0):
+        """
+        Finalize the current episode.
+
+        If config.only_wins is True, decisions from losing episodes
+        are discarded (higher signal-to-noise for distillation).
+        """
+        self._total_episodes += 1
+
+        # Gate: skip losses if configured
+        if self.config.only_wins and not won:
+            self._skipped_losses += 1
+            self._episode_buffer = []
+            return
+
+        # Gate: skip very short episodes
+        if len(self._episode_buffer) < self.config.min_episode_steps:
+            self._skipped_short += 1
+            self._episode_buffer = []
+            return
+
+        game_outcome = "win" if won else "loss"
+
+        for step in self._episode_buffer:
+            record = build_decision_record(
+                game_state_snapshot=step["snapshot"],
+                action_idx=step["action_idx"],
+                reward=step["reward"],
+                agent_seat=self._current_seat,
+                game_id=self._current_game_id,
+                game_outcome=game_outcome,
+                archetype=self._current_playstyle,
+                source="ppo",
+                model_version=self.config.model_version,
+                episode_return=episode_return,
+            )
+            self._records.append(record)
+
+        self._exported_episodes += 1
+        self._exported_decisions += len(self._episode_buffer)
+        self._episode_buffer = []
+
+    # -- Persistence ---------------------------------------------------------
+
+    def flush(self) -> Optional[str]:
+        """
+        Write all accumulated records to a JSONL file.
+
+        Returns:
+            Path to the written file, or None if no records to write.
+        """
+        if not self._records:
+            logger.info("No PPO decisions to export (0 records).")
+            return None
+
+        os.makedirs(self.config.output_dir, exist_ok=True)
+        filename = f"ml-decisions-ppo-{self._batch_id}.jsonl"
+        filepath = os.path.join(self.config.output_dir, filename)
+
+        with open(filepath, "w") as f:
+            for record in self._records:
+                f.write(json.dumps(record) + "\n")
+
+        logger.info(
+            "Exported %d PPO decisions (%d episodes) to %s",
+            len(self._records),
+            self._exported_episodes,
+            filepath,
+        )
+        self._records = []
+        return filepath
+
+    # -- Reporting -----------------------------------------------------------
+
+    @property
+    def stats(self) -> dict:
+        """Return export statistics."""
+        return {
+            "batch_id": self._batch_id,
+            "total_episodes": self._total_episodes,
+            "exported_episodes": self._exported_episodes,
+            "exported_decisions": self._exported_decisions,
+            "skipped_losses": self._skipped_losses,
+            "skipped_short": self._skipped_short,
+            "pending_records": len(self._records),
+        }
+
+    @property
+    def batch_id(self) -> str:
+        return self._batch_id

ml/training/distillation_loop.py

@@ -0,0 +1,908 @@
+"""
+Commander AI Lab — Distillation Loop Orchestrator
+═══════════════════════════════════════════════════
+
+Phase 4 (Issue #68): Automates the full closed-loop distillation cycle:
+
+    1. Supervised train on current dataset (Forge + any existing PPO data)
+    2. Run N episodes of PPO self-play using the supervised model as starting policy
+    3. Export winning PPO decisions to JSONL
+    4. Quality gate check
+    5. If passed → merge into dataset and repeat from step 1
+    6. If failed → discard PPO batch, adjust hyperparameters, retry
+
+Each iteration is a "generation" — data and models are tagged with generation
+number for traceability.
+
+Convergence detection:
+  - Stops if win rate plateaus across `convergence_window` generations
+  - Hard stop at `max_iterations`
+
+Ref: docs/CLOSED-LOOP-DISTILLATION.md — Phase 4
+Issue: #68
+"""
+
+import json
+import logging
+import os
+import shutil
+import sys
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import numpy as np
+
+project_root = str(Path(__file__).parent.parent.parent)
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+
+from ml.config.scope import (
+    NUM_ACTIONS, STATE_DIMS, TRAINING_CONFIG,
+)
+from ml.data.quality_gate import QualityGate, QualityGateConfig, GateVerdict
+from ml.training.decision_exporter import DecisionExporter, ExporterConfig
+
+logger = logging.getLogger("ml.distillation")
+
+
+# ═══════════════════════════════════════════════════════════
+# Configuration
+# ═══════════════════════════════════════════════════════════
+
+@dataclass
+class DistillationConfig:
+    """Configuration for the distillation loop orchestrator."""
+
+    # --- Loop control ---
+    max_iterations: int = 10
+    convergence_window: int = 3       # Check last N generations for plateau
+    convergence_threshold: float = 0.01  # Min win-rate improvement to not plateau
+
+    # --- Paths ---
+    results_dir: str = "results"
+    models_dir: str = "ml/models"
+    checkpoint_dir: str = "ml/models/checkpoints"
+    history_dir: str = "results/distillation-history"
+
+    # --- Supervised training ---
+    supervised_epochs: int = 30
+    supervised_lr: float = 1e-3
+    supervised_batch_size: int = 64
+    supervised_patience: int = 5
+
+    # --- PPO self-play ---
+    ppo_iterations: int = 50
+    ppo_episodes_per_iter: int = 64
+    ppo_batch_size: int = 256
+    ppo_lr: float = 3e-4
+    ppo_clip_epsilon: float = 0.2
+    ppo_entropy_coeff: float = 0.01
+    ppo_eval_episodes: int = 100
+    opponent: str = "heuristic"
+    playstyle: str = "midrange"
+
+    # --- Dataset building (Forge-only default; see MIXED_MODE_PRESETS) ---
+    forge_weight: float = 1.0
+    ppo_weight: float = 0.0
+    min_reward_threshold: float = 0.0
+
+    # --- Quality gate ---
+    min_forge_accuracy: float = 0.35
+    max_accuracy_drop: float = 0.03
+    min_ppo_win_rate: float = 0.30
+
+    # --- Retry on gate failure ---
+    max_retries_per_generation: int = 2
+    retry_lr_factor: float = 0.5       # Halve PPO LR on retry
+    retry_entropy_boost: float = 0.005  # Increase entropy coeff on retry
+
+    # --- ELO convergence (Phase 6) ---
+    elo_convergence_enabled: bool = False   # Off by default
+    elo_convergence_threshold: float = 20.0 # Stop if ELO gain < this
+    elo_tournament_episodes: int = 30       # Games per matchup for ELO mini-tournament
+
+
+# ═══════════════════════════════════════════════════════════
+# Generation metadata
+# ═══════════════════════════════════════════════════════════
+
+@dataclass
+class GenerationRecord:
+    """Tracks metadata for a single distillation generation."""
+    generation: int
+    started_at: str = ""
+    completed_at: str = ""
+    status: str = "pending"  # pending | running | passed | failed | skipped
+
+    # Supervised training results
+    supervised_val_acc: float = 0.0
+    supervised_best_epoch: int = 0
+    supervised_checkpoint: str = ""
+
+    # PPO self-play results
+    ppo_win_rate: float = 0.0
+    ppo_best_win_rate: float = 0.0
+    ppo_episodes: int = 0
+    ppo_decisions_exported: int = 0
+    ppo_export_path: str = ""
+
+    # Quality gate
+    gate_accepted: bool = False
+    gate_reason: str = ""
+    baseline_accuracy: float = 0.0
+    post_merge_accuracy: float = 0.0
+
+    # Dataset stats
+    dataset_size: int = 0
+    forge_samples: int = 0
+    ppo_samples: int = 0
+
+    retries: int = 0
+    error: str = ""
+    elo_rating: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {k: v for k, v in self.__dict__.items()}
+
+
+# ═══════════════════════════════════════════════════════════
+# Distillation Loop Orchestrator
+# ═══════════════════════════════════════════════════════════
+
+class DistillationLoop:
+    """
+    Orchestrates the full closed-loop distillation pipeline.
+
+    Each "generation" runs the complete cycle:
+      supervised train → PPO self-play → export → quality gate → merge
+
+    The loop tracks convergence by monitoring PPO win rate across
+    generations and stops when improvement plateaus or max_iterations
+    is reached.
+
+    Usage::
+
+        config = DistillationConfig(max_iterations=5, ppo_iterations=30)
+        loop = DistillationLoop(config)
+        summary = loop.run()
+    """
+
+    def __init__(self, config: DistillationConfig = None):
+        self.config = config or DistillationConfig()
+        self.generations: List[GenerationRecord] = []
+        self.quality_gate = QualityGate(QualityGateConfig(
+            min_forge_accuracy=self.config.min_forge_accuracy,
+            max_accuracy_drop=self.config.max_accuracy_drop,
+            min_ppo_win_rate=self.config.min_ppo_win_rate,
+        ))
+        self._baseline_accuracy: Optional[float] = None
+        self._device: Optional[str] = None
+        self._stopped = False
+
+        # Ensure output directories exist
+        os.makedirs(self.config.history_dir, exist_ok=True)
+        os.makedirs(self.config.checkpoint_dir, exist_ok=True)
+        os.makedirs(self.config.results_dir, exist_ok=True)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def run(self, progress_callback=None) -> Dict:
+        """
+        Run the full distillation loop.
+
+        Args:
+            progress_callback: Optional callable(generation, record) for
+                               progress reporting (e.g. to a web UI).
+
+        Returns:
+            Summary dict with per-generation metrics and convergence info.
+        """
+        cfg = self.config
+        self._device = self._detect_device()
+
+        logger.info("=" * 65)
+        logger.info("  Commander AI Lab — Distillation Loop")
+        logger.info("=" * 65)
+        logger.info("  Max iterations:     %d", cfg.max_iterations)
+        logger.info("  Convergence window: %d", cfg.convergence_window)
+        logger.info("  PPO iters/gen:      %d", cfg.ppo_iterations)
+        logger.info("  PPO episodes/iter:  %d", cfg.ppo_episodes_per_iter)
+        logger.info("  Supervised epochs:  %d", cfg.supervised_epochs)
+        logger.info("  Device:             %s", self._device)
+        logger.info("  Results dir:        %s", cfg.results_dir)
+        logger.info("=" * 65)
+
+        loop_start = time.time()
+
+        for gen_num in range(1, cfg.max_iterations + 1):
+            if self._stopped:
+                logger.info("Loop stopped by external signal.")
+                break
+
+            logger.info("")
+            logger.info("─" * 65)
+            logger.info("  GENERATION %d / %d", gen_num, cfg.max_iterations)
+            logger.info("─" * 65)
+
+            record = self._run_generation(gen_num)
+            self.generations.append(record)
+
+            # Save generation history to disk after each round
+            self._save_history()
+
+            if progress_callback:
+                progress_callback(gen_num, record)
+
+            # Check convergence
+            if self._check_convergence():
+                logger.info(
+                    "Convergence detected — win rate plateaued over "
+                    "last %d generations. Stopping.",
+                    cfg.convergence_window,
+                )
+                break
+
+        total_time = time.time() - loop_start
+
+        summary = self._build_summary(total_time)
+        self._save_summary(summary)
+
+        logger.info("")
+        logger.info("=" * 65)
+        logger.info("  Distillation Loop Complete")
+        logger.info("=" * 65)
+        logger.info("  Generations run:  %d", summary["generations_run"])
+        logger.info("  Generations passed: %d", summary["generations_passed"])
+        logger.info("  Best win rate:    %.1f%%", summary["best_win_rate"] * 100)
+        logger.info("  Converged:        %s", summary["converged"])
+        logger.info("  Total time:       %.1f s", total_time)
+        logger.info("=" * 65)
+
+        return summary
+
+    def stop(self):
+        """Signal the loop to stop after the current generation."""
+        self._stopped = True
+        logger.info("Stop signal received — will halt after current generation.")
+
+    # ------------------------------------------------------------------
+    # Single generation execution
+    # ------------------------------------------------------------------
+
+    def _run_generation(self, gen_num: int) -> GenerationRecord:
+        """Execute a single distillation generation (steps 1-6)."""
+        record = GenerationRecord(
+            generation=gen_num,
+            started_at=datetime.now(timezone.utc).isoformat(),
+            status="running",
+        )
+
+        cfg = self.config
+        gen_tag = f"gen-{gen_num:03d}"
+        gen_checkpoint_dir = os.path.join(cfg.checkpoint_dir, gen_tag)
+        os.makedirs(gen_checkpoint_dir, exist_ok=True)
+
+        try:
+            # ─── Step 1: Supervised Train ───────────────────────────
+            logger.info("  [Step 1] Supervised training on current dataset...")
+            sup_result = self._supervised_train(gen_checkpoint_dir, gen_tag)
+
+            if sup_result is None:
+                record.status = "failed"
+                record.error = "Supervised training failed — no dataset found"
+                record.completed_at = datetime.now(timezone.utc).isoformat()
+                return record
+
+            record.supervised_val_acc = sup_result["best_val_acc"]
+            record.supervised_best_epoch = sup_result["best_epoch"]
+            record.supervised_checkpoint = sup_result["checkpoint_path"]
+
+            # Set baseline accuracy on first generation
+            if self._baseline_accuracy is None:
+                self._baseline_accuracy = sup_result["best_val_acc"]
+                logger.info(
+                    "  Baseline accuracy set: %.3f (generation 1)",
+                    self._baseline_accuracy,
+                )
+
+            # ─── Step 2-3: PPO Self-Play + Export ───────────────────
+            retries = 0
+            ppo_lr = cfg.ppo_lr
+            entropy_coeff = cfg.ppo_entropy_coeff
+            gate_passed = False
+
+            while retries <= cfg.max_retries_per_generation and not gate_passed:
+                if retries > 0:
+                    logger.info(
+                        "  [Retry %d/%d] Adjusting hyperparameters: "
+                        "lr=%.2e → %.2e, entropy=%.4f → %.4f",
+                        retries, cfg.max_retries_per_generation,
+                        ppo_lr, ppo_lr * cfg.retry_lr_factor,
+                        entropy_coeff, entropy_coeff + cfg.retry_entropy_boost,
+                    )
+                    ppo_lr *= cfg.retry_lr_factor
+                    entropy_coeff += cfg.retry_entropy_boost
+
+                logger.info(
+                    "  [Step 2] PPO self-play (%d iters × %d episodes)...",
+                    cfg.ppo_iterations, cfg.ppo_episodes_per_iter,
+                )
+                ppo_result, exporter = self._ppo_self_play(
+                    supervised_checkpoint=sup_result["checkpoint_path"],
+                    gen_tag=gen_tag,
+                    gen_checkpoint_dir=gen_checkpoint_dir,
+                    learning_rate=ppo_lr,
+                    entropy_coeff=entropy_coeff,
+                )
+
+                record.ppo_win_rate = ppo_result["final_win_rate"]
+                record.ppo_best_win_rate = ppo_result["best_win_rate"]
+                record.ppo_episodes = (
+                    cfg.ppo_iterations * cfg.ppo_episodes_per_iter
+                )
+
+                logger.info(
+                    "  [Step 3] Exporting PPO decisions (win rate: %.1f%%)...",
+                    ppo_result["best_win_rate"] * 100,
+                )
+                export_path = exporter.flush()
+                record.ppo_decisions_exported = exporter.stats["exported_decisions"]
+                record.ppo_export_path = export_path or ""
+
+                # ─── Step 4: Quality Gate ───────────────────────────
+                logger.info("  [Step 4] Quality gate check...")
+                verdict = self._quality_gate_check(
+                    ppo_win_rate=ppo_result["best_win_rate"],
+                    total_episodes=record.ppo_episodes,
+                    exporter=exporter,
+                )
+
+                if verdict.accepted:
+                    gate_passed = True
+                    record.gate_accepted = True
+                    record.gate_reason = verdict.reason
+                    logger.info("  QUALITY GATE: PASSED — %s", verdict.reason)
+                else:
+                    retries += 1
+                    record.retries = retries
+                    logger.warning(
+                        "  QUALITY GATE: FAILED — %s", verdict.reason,
+                    )
+
+                    if retries > cfg.max_retries_per_generation:
+                        # ─── Step 6: Discard PPO batch ──────────────
+                        logger.warning(
+                            "  [Step 6] Max retries exceeded — "
+                            "discarding PPO batch for generation %d.",
+                            gen_num,
+                        )
+                        if export_path and os.path.exists(export_path):
+                            os.remove(export_path)
+                            logger.info(
+                                "  Deleted rejected PPO data: %s", export_path
+                            )
+                        record.gate_accepted = False
+                        record.gate_reason = (
+                            f"Failed after {retries - 1} retries: "
+                            f"{verdict.reason}"
+                        )
+
+            # ─── Step 5: Merge into dataset (if passed) ─────────────
+            if gate_passed:
+                logger.info(
+                    "  [Step 5] PPO data accepted — will be included "
+                    "in next generation's dataset build."
+                )
+                record.status = "passed"
+
+                # ─── ELO mini-tournament (Phase 6) ────────────────
+                if cfg.elo_convergence_enabled and gen_num > 1:
+                    elo = self._run_elo_mini_tournament(
+                        gen_checkpoint_dir, gen_num
+                    )
+                    if elo is not None:
+                        record.elo_rating = elo
+                        logger.info("  ELO rating: %.1f", elo)
+            else:
+                record.status = "failed"
+
+        except Exception as e:
+            logger.exception("  Generation %d failed with error: %s", gen_num, e)
+            record.status = "failed"
+            record.error = str(e)
+
+        record.completed_at = datetime.now(timezone.utc).isoformat()
+        return record
+
+    # ------------------------------------------------------------------
+    # Step 1: Supervised Training
+    # ------------------------------------------------------------------
+
+    def _supervised_train(
+        self,
+        gen_checkpoint_dir: str,
+        gen_tag: str,
+    ) -> Optional[Dict]:
+        """
+        Build dataset from all available data and train supervised model.
+
+        Returns training summary dict or None on failure.
+        """
+        try:
+            import torch
+        except ImportError:
+            raise RuntimeError("PyTorch required for distillation loop")
+
+        cfg = self.config
+
+        # Build dataset (picks up both Forge + any PPO JSONL files in results_dir)
+        from ml.data.dataset_builder import build_dataset, split_dataset, save_dataset
+
+        try:
+            dataset = build_dataset(
+                results_dir=cfg.results_dir,
+                max_samples=None,
+                source_weights={
+                    "forge": cfg.forge_weight,
+                    "ppo": cfg.ppo_weight,
+                },
+                min_reward_threshold=cfg.min_reward_threshold,
+            )
+        except RuntimeError as e:
+            logger.warning("Dataset build failed: %s", e)
+            return None
+
+        if not dataset or len(dataset.get("states", [])) == 0:
+            logger.warning("No training data available.")
+            return None
+
+        # Split
+        train_data, val_data, test_data = split_dataset(dataset)
+
+        # Save splits (overwrite each generation — latest always at standard path)
+        data_dir = cfg.models_dir
+        os.makedirs(data_dir, exist_ok=True)
+        save_dataset(train_data, os.path.join(data_dir, "dataset-train.npz"))
+        save_dataset(val_data, os.path.join(data_dir, "dataset-val.npz"))
+        save_dataset(test_data, os.path.join(data_dir, "dataset-test.npz"))
+
+        # Create model
+        from ml.training.policy_network import PolicyNetwork
+        actual_dim = train_data["states"].shape[1]
+        model = PolicyNetwork(input_dim=actual_dim)
+
+        # Train
+        from ml.training.trainer import SupervisedTrainer, get_best_device
+        device = self._device or get_best_device()
+        trainer = SupervisedTrainer(
+            model=model,
+            device=device,
+            learning_rate=cfg.supervised_lr,
+            batch_size=cfg.supervised_batch_size,
+            epochs=cfg.supervised_epochs,
+            patience=cfg.supervised_patience,
+            checkpoint_dir=gen_checkpoint_dir,
+        )
+
+        summary = trainer.train(
+            train_states=train_data["states"],
+            train_labels=train_data["labels"],
+            val_states=val_data["states"],
+            val_labels=val_data["labels"],
+        )
+
+        # Also copy best checkpoint to the standard location
+        best_src = os.path.join(gen_checkpoint_dir, "best_policy.pt")
+        best_dst = os.path.join(cfg.checkpoint_dir, "best_policy.pt")
+        if os.path.exists(best_src):
+            shutil.copy2(best_src, best_dst)
+
+        return summary
+
+    # ------------------------------------------------------------------
+    # Steps 2-3: PPO Self-Play + Decision Export
+    # ------------------------------------------------------------------
+
+    def _ppo_self_play(
+        self,
+        supervised_checkpoint: str,
+        gen_tag: str,
+        gen_checkpoint_dir: str,
+        learning_rate: float = None,
+        entropy_coeff: float = None,
+    ) -> tuple:
+        """
+        Run PPO self-play initialized from the supervised checkpoint.
+
+        Returns (ppo_summary, exporter) tuple.
+        """
+        cfg = self.config
+
+        from ml.training.ppo_trainer import PPOTrainer, PPOConfig
+        from ml.training.decision_exporter import DecisionExporter, ExporterConfig
+
+        # Set up decision exporter for this generation
+        exporter = DecisionExporter(ExporterConfig(
+            output_dir=cfg.results_dir,
+            only_wins=True,
+            model_version=gen_tag,
+        ))
+
+        ppo_config = PPOConfig(
+            iterations=cfg.ppo_iterations,
+            episodes_per_iter=cfg.ppo_episodes_per_iter,
+            ppo_epochs=4,
+            batch_size=cfg.ppo_batch_size,
+            clip_epsilon=cfg.ppo_clip_epsilon,
+            entropy_coeff=entropy_coeff or cfg.ppo_entropy_coeff,
+            learning_rate=learning_rate or cfg.ppo_lr,
+            lr_schedule="cosine",
+            min_lr=1e-5,
+            opponent=cfg.opponent,
+            playstyle=cfg.playstyle,
+            checkpoint_dir=gen_checkpoint_dir,
+            save_every=max(1, cfg.ppo_iterations // 5),
+            eval_every=max(1, cfg.ppo_iterations // 10),
+            eval_episodes=cfg.ppo_eval_episodes,
+            load_supervised=supervised_checkpoint,
+        )
+
+        ppo_trainer = PPOTrainer(ppo_config)
+
+        # Monkey-patch collect_rollouts to include exporter
+        # The exporter is already wired into self_play.collect_rollouts
+        # via the exporter parameter, so we wrap the train loop.
+        original_collect = None
+
+        from ml.training import self_play as sp_module
+
+        _original_collect_rollouts = sp_module.collect_rollouts
+
+        def _instrumented_collect_rollouts(
+            agent_model, opponent_policy, buffer,
+            num_episodes=64, playstyle="midrange",
+            reward_config=None, **kwargs
+        ):
+            return _original_collect_rollouts(
+                agent_model=agent_model,
+                opponent_policy=opponent_policy,
+                buffer=buffer,
+                num_episodes=num_episodes,
+                playstyle=playstyle,
+                reward_config=reward_config,
+                exporter=exporter,
+            )
+
+        # Temporarily replace module-level function
+        sp_module.collect_rollouts = _instrumented_collect_rollouts
+        try:
+            summary = ppo_trainer.train()
+        finally:
+            # Restore original
+            sp_module.collect_rollouts = _original_collect_rollouts
+
+        return summary, exporter
+
+    # ------------------------------------------------------------------
+    # Step 4: Quality Gate
+    # ------------------------------------------------------------------
+
+    def _quality_gate_check(
+        self,
+        ppo_win_rate: float,
+        total_episodes: int,
+        exporter: DecisionExporter,
+    ) -> GateVerdict:
+        """Run quality gate checks on the PPO output."""
+        # Win rate gate
+        win_verdict = self.quality_gate.check_win_rate(
+            ppo_win_rate=ppo_win_rate,
+            total_episodes=total_episodes,
+        )
+        if not win_verdict.accepted:
+            return win_verdict
+
+        # If we have baseline accuracy and this isn't the first generation,
+        # we could run a post-merge accuracy check here. For now, the win
+        # rate gate is the primary gatekeeper during the loop. The accuracy
+        # gate will be checked on the next generation's supervised training
+        # by comparing against self._baseline_accuracy.
+        return GateVerdict(
+            accepted=True,
+            reason=(
+                f"Win rate gate passed ({ppo_win_rate:.1%} >= "
+                f"{self.config.min_ppo_win_rate:.1%}). "
+                f"PPO data accepted for merge."
+            ),
+            metrics={
+                "ppo_win_rate": ppo_win_rate,
+                "total_episodes": total_episodes,
+                "exported_decisions": exporter.stats["exported_decisions"],
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # ELO mini-tournament (Phase 6)
+    # ------------------------------------------------------------------
+
+    def _run_elo_mini_tournament(
+        self, gen_checkpoint_dir: str, gen_num: int
+    ) -> Optional[float]:
+        """
+        Run a small ELO tournament between current gen, previous gen,
+        and heuristic baseline. Returns the current gen's ELO rating.
+        """
+        cfg = self.config
+        try:
+            from ml.eval.elo_tracker import (
+                run_elo_tournament, EloHistory, HeuristicPolicy, LearnedPolicy,
+            )
+
+            policies = {"heuristic": HeuristicPolicy()}
+
+            # Current generation checkpoint
+            curr_path = os.path.join(gen_checkpoint_dir, "best_policy.pt")
+            curr_name = f"gen-{gen_num:03d}"
+            if os.path.exists(curr_path):
+                policies[curr_name] = LearnedPolicy(curr_path)
+            else:
+                logger.warning("  ELO: current gen checkpoint not found: %s", curr_path)
+                return None
+
+            # Previous generation checkpoint
+            if gen_num > 1:
+                prev_tag = f"gen-{gen_num - 1:03d}"
+                prev_dir = os.path.join(cfg.checkpoint_dir, prev_tag)
+                prev_path = os.path.join(prev_dir, "best_policy.pt")
+                if os.path.exists(prev_path):
+                    policies[prev_tag] = LearnedPolicy(prev_path)
+
+            logger.info(
+                "  [ELO] Running mini-tournament: %s (%d episodes/matchup)",
+                list(policies.keys()), cfg.elo_tournament_episodes,
+            )
+
+            result = run_elo_tournament(
+                policies=policies,
+                episodes_per_matchup=cfg.elo_tournament_episodes,
+                playstyle=cfg.playstyle,
+            )
+
+            # Save to ELO history
+            history_path = os.path.join(
+                os.path.dirname(cfg.history_dir), "elo_history.json"
+            ) if cfg.history_dir else "data/elo_history.json"
+            history = EloHistory(path=history_path)
+            history.append(gen_num, result.ratings)
+
+            return result.ratings.get(curr_name, 0.0)
+
+        except Exception as e:
+            logger.warning("  ELO mini-tournament failed: %s", e)
+            return None
+
+    # ------------------------------------------------------------------
+    # Convergence detection
+    # ------------------------------------------------------------------
+
+    def _check_convergence(self) -> bool:
+        """
+        Check if win rate has plateaued over recent generations.
+        Also checks ELO delta when elo_convergence_enabled is True.
+
+        Returns True if the loop should stop.
+        """
+        cfg = self.config
+        passed = [g for g in self.generations if g.status == "passed"]
+
+        if len(passed) < cfg.convergence_window:
+            return False
+
+        recent = passed[-cfg.convergence_window:]
+        win_rates = [g.ppo_best_win_rate for g in recent]
+
+        # Check if max improvement across the window is below threshold
+        improvement = max(win_rates) - min(win_rates)
+
+        logger.info(
+            "  Convergence check: last %d win rates = %s, "
+            "spread = %.4f (threshold = %.4f)",
+            cfg.convergence_window,
+            [f"{wr:.3f}" for wr in win_rates],
+            improvement,
+            cfg.convergence_threshold,
+        )
+
+        win_rate_converged = improvement < cfg.convergence_threshold
+
+        # ELO convergence check (Phase 6)
+        if cfg.elo_convergence_enabled and len(passed) >= 2:
+            elo_ratings = [g.elo_rating for g in passed[-2:] if g.elo_rating > 0]
+            if len(elo_ratings) >= 2:
+                elo_delta = elo_ratings[-1] - elo_ratings[-2]
+                logger.info(
+                    "  ELO convergence check: delta = %.1f (threshold = %.1f)",
+                    elo_delta, cfg.elo_convergence_threshold,
+                )
+                if elo_delta < cfg.elo_convergence_threshold:
+                    logger.info("  ELO delta below threshold — converged.")
+                    return True
+
+        return win_rate_converged
+
+    # ------------------------------------------------------------------
+    # Device detection
+    # ------------------------------------------------------------------
+
+    def _detect_device(self) -> str:
+        """Auto-detect best compute device."""
+        try:
+            import torch
+            if torch.cuda.is_available():
+                return "cuda"
+            if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+                return "mps"
+        except ImportError:
+            pass
+        return "cpu"
+
+    # ------------------------------------------------------------------
+    # History & summary persistence
+    # ------------------------------------------------------------------
+
+    def _save_history(self):
+        """Save generation history to JSON."""
+        path = os.path.join(self.config.history_dir, "generations.json")
+        history = [g.to_dict() for g in self.generations]
+        with open(path, "w") as f:
+            json.dump(history, f, indent=2)
+        logger.info("  Generation history saved: %s", path)
+
+    def _build_summary(self, total_time: float) -> Dict:
+        """Build final summary dict."""
+        passed = [g for g in self.generations if g.status == "passed"]
+        failed = [g for g in self.generations if g.status == "failed"]
+
+        best_wr = max(
+            (g.ppo_best_win_rate for g in self.generations), default=0.0
+        )
+
+        return {
+            "generations_run": len(self.generations),
+            "generations_passed": len(passed),
+            "generations_failed": len(failed),
+            "best_win_rate": best_wr,
+            "converged": self._check_convergence() if len(passed) >= self.config.convergence_window else False,
+            "total_time_s": round(total_time, 1),
+            "device": self._device,
+            "config": {
+                "max_iterations": self.config.max_iterations,
+                "convergence_window": self.config.convergence_window,
+                "convergence_threshold": self.config.convergence_threshold,
+                "ppo_iterations": self.config.ppo_iterations,
+                "supervised_epochs": self.config.supervised_epochs,
+            },
+            "generations": [g.to_dict() for g in self.generations],
+        }
+
+    def _save_summary(self, summary: Dict):
+        """Save final summary to JSON."""
+        path = os.path.join(self.config.history_dir, "summary.json")
+        with open(path, "w") as f:
+            json.dump(summary, f, indent=2, default=str)
+        logger.info("  Summary saved: %s", path)
+
+
+# ═══════════════════════════════════════════════════════════
+# CLI Entry Point
+# ═══════════════════════════════════════════════════════════
+
+def main():
+    """CLI entry point for the distillation loop."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Commander AI Lab — Closed-Loop Distillation"
+    )
+
+    # Loop control
+    parser.add_argument(
+        "--max-iterations", type=int, default=10,
+        help="Maximum number of distillation generations (default: 10)",
+    )
+    parser.add_argument(
+        "--convergence-window", type=int, default=3,
+        help="Number of generations to check for win-rate plateau (default: 3)",
+    )
+    parser.add_argument(
+        "--convergence-threshold", type=float, default=0.01,
+        help="Min win-rate spread to not be considered converged (default: 0.01)",
+    )
+
+    # Paths
+    parser.add_argument(
+        "--results-dir", default="data/results",
+        help="Directory containing JSONL decision files (default: data/results)",
+    )
+    parser.add_argument(
+        "--models-dir", default="ml/models",
+        help="Directory for dataset NPZ files (default: ml/models)",
+    )
+    parser.add_argument(
+        "--checkpoint-dir", default="ml/models/checkpoints",
+        help="Directory for model checkpoints (default: ml/models/checkpoints)",
+    )
+
+    # Supervised training
+    parser.add_argument("--sup-epochs", type=int, default=30)
+    parser.add_argument("--sup-lr", type=float, default=1e-3)
+    parser.add_argument("--sup-batch-size", type=int, default=64)
+    parser.add_argument("--sup-patience", type=int, default=5)
+
+    # PPO self-play
+    parser.add_argument("--ppo-iterations", type=int, default=50)
+    parser.add_argument("--ppo-episodes", type=int, default=64)
+    parser.add_argument("--ppo-lr", type=float, default=3e-4)
+    parser.add_argument("--ppo-batch-size", type=int, default=256)
+    parser.add_argument("--ppo-eval-episodes", type=int, default=100)
+    parser.add_argument(
+        "--opponent", default="heuristic",
+        choices=["heuristic", "random", "self"],
+    )
+    parser.add_argument("--playstyle", default="midrange")
+
+    # Dataset
+    parser.add_argument("--forge-weight", type=float, default=1.0)
+    parser.add_argument("--ppo-weight", type=float, default=0.0)
+    parser.add_argument("--min-reward", type=float, default=0.0)
+
+    # Quality gate
+    parser.add_argument("--min-win-rate", type=float, default=0.30)
+    parser.add_argument("--min-forge-accuracy", type=float, default=0.35)
+    parser.add_argument("--max-accuracy-drop", type=float, default=0.03)
+
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(message)s",
+    )
+
+    config = DistillationConfig(
+        max_iterations=args.max_iterations,
+        convergence_window=args.convergence_window,
+        convergence_threshold=args.convergence_threshold,
+        results_dir=args.results_dir,
+        models_dir=args.models_dir,
+        checkpoint_dir=args.checkpoint_dir,
+        supervised_epochs=args.sup_epochs,
+        supervised_lr=args.sup_lr,
+        supervised_batch_size=args.sup_batch_size,
+        supervised_patience=args.sup_patience,
+        ppo_iterations=args.ppo_iterations,
+        ppo_episodes_per_iter=args.ppo_episodes,
+        ppo_batch_size=args.ppo_batch_size,
+        ppo_lr=args.ppo_lr,
+        ppo_eval_episodes=args.ppo_eval_episodes,
+        opponent=args.opponent,
+        playstyle=args.playstyle,
+        forge_weight=args.forge_weight,
+        ppo_weight=args.ppo_weight,
+        min_reward_threshold=args.min_reward,
+        min_ppo_win_rate=args.min_win_rate,
+        min_forge_accuracy=args.min_forge_accuracy,
+        max_accuracy_drop=args.max_accuracy_drop,
+    )
+
+    loop = DistillationLoop(config)
+    summary = loop.run()
+    print(json.dumps(summary, indent=2, default=str))
+
+
+if __name__ == "__main__":
+    main()

ml/training/self_play.py

@@ -38,6 +38,7 @@ from ml.config.scope import (
     Playstyle, PLAYSTYLE_TO_IDX, STATE_DIMS, GamePhase, PHASE_TO_IDX,
 )
 from ml.training.reward import compute_intermediate_reward, compute_terminal_reward, RewardConfig
+from ml.training.decision_exporter import DecisionExporter
 
 logger = logging.getLogger("ml.self_play")
 
@@ -384,6 +385,7 @@ def run_self_play_episode(
     playstyle: str = "midrange",
     max_steps: int = 50,
     reward_config: RewardConfig = None,
+    exporter: DecisionExporter = None,
 ) -> List[dict]:
     """Run a single self-play episode and return the trajectory.
 
@@ -395,6 +397,7 @@ def run_self_play_episode(
         playstyle: Playstyle for state encoding
         max_steps: Maximum decision steps per episode
         reward_config: Reward configuration
+        exporter: Optional DecisionExporter to record steps for distillation
 
     Returns:
         List of step dicts: [{state, action, reward, value, log_prob, done}, ...]
@@ -458,6 +461,12 @@ def run_self_play_episode(
                 "log_prob": log_prob_scalar,
                 "done": True,
             })
+            if exporter is not None:
+                exporter.record_step(
+                    game_state_snapshot=prev_snapshot,
+                    action_idx=action_idx,
+                    reward=reward,
+                )
             break
 
         # Opponent's turn
@@ -483,6 +492,12 @@ def run_self_play_episode(
                 "log_prob": log_prob_scalar,
                 "done": True,
             })
+            if exporter is not None:
+                exporter.record_step(
+                    game_state_snapshot=prev_snapshot,
+                    action_idx=action_idx,
+                    reward=reward,
+                )
             break
 
         # Intermediate reward
@@ -499,6 +514,12 @@ def run_self_play_episode(
             "log_prob": log_prob_scalar,
             "done": False,
         })
+        if exporter is not None:
+            exporter.record_step(
+                game_state_snapshot=prev_snapshot,
+                action_idx=action_idx,
+                reward=reward,
+            )
 
         # Advance turn
         state = advance_turn(state)
@@ -513,6 +534,7 @@ def collect_rollouts(
     num_episodes: int = 64,
     playstyle: str = "midrange",
     reward_config: RewardConfig = None,
+    exporter: DecisionExporter = None,
 ) -> dict:
     """Collect multiple self-play episodes into a rollout buffer.
 
@@ -523,6 +545,7 @@ def collect_rollouts(
         num_episodes: Number of episodes to collect
         playstyle: Agent playstyle
         reward_config: Reward configuration
+        exporter: Optional DecisionExporter to record decisions for distillation
 
     Returns:
         Collection statistics dict
@@ -538,12 +561,16 @@ def collect_rollouts(
         # Alternate agent seat for balanced training
         agent_seat = ep % 2
 
+        if exporter is not None:
+            exporter.begin_episode(agent_seat=agent_seat, playstyle=playstyle)
+
         trajectory = run_self_play_episode(
             agent_model=agent_model,
             opponent_policy=opponent_policy,
             agent_seat=agent_seat,
             playstyle=playstyle,
             reward_config=reward_config,
+            exporter=exporter,
         )
 
         for step in trajectory:
@@ -569,6 +596,11 @@ def collect_rollouts(
             else:
                 total_draws += 1
 
+        if exporter is not None:
+            won = trajectory and trajectory[-1]["done"] and trajectory[-1]["reward"] > 0.5
+            ep_return = sum(s["reward"] for s in trajectory)
+            exporter.end_episode(won=won, episode_return=ep_return)
+
     # Compute GAE after collection
     buffer.compute_returns_and_advantages(last_value=0.0)
 

models/__init__.py

@@ -0,0 +1,47 @@
+"""Pydantic models for Commander AI Lab API."""
+
+from models.requests import (
+    StartRequest,
+    ImportUrlRequest,
+    ImportTextRequest,
+    MetaFetchRequest,
+    CreateDeckRequest,
+    UpdateDeckRequest,
+    AddDeckCardRequest,
+    PatchDeckCardRequest,
+    BulkAddRequest,
+    BulkAddRecommendedRequest,
+    DeckGenerationSourceConfig,
+    DeckGenerationRequest,
+    DeckGenV3Request,
+    DeckGenV3SubstituteRequest,
+)
+from models.responses import (
+    StartResponse,
+    StatusResponse,
+    DeckInfo,
+    GeneratedDeckCard,
+)
+
+__all__ = [
+    # Requests
+    "StartRequest",
+    "ImportUrlRequest",
+    "ImportTextRequest",
+    "MetaFetchRequest",
+    "CreateDeckRequest",
+    "UpdateDeckRequest",
+    "AddDeckCardRequest",
+    "PatchDeckCardRequest",
+    "BulkAddRequest",
+    "BulkAddRecommendedRequest",
+    "DeckGenerationSourceConfig",
+    "DeckGenerationRequest",
+    "DeckGenV3Request",
+    "DeckGenV3SubstituteRequest",
+    # Responses
+    "StartResponse",
+    "StatusResponse",
+    "DeckInfo",
+    "GeneratedDeckCard",
+]

models/requests.py

@@ -0,0 +1,175 @@
+"""Pydantic request models for Commander AI Lab API."""
+from __future__ import annotations
+from typing import Optional
+from pydantic import BaseModel
+
+
+class StartRequest(BaseModel):
+    decks: list[str]
+    numGames: int = 100
+    threads: int = 4
+    seed: Optional[int] = None
+    clock: int = 300
+    deckSources: Optional[list[Optional[dict]]] = None
+    useLearnedPolicy: bool = False
+    policyStyle: str = "midrange"
+    policyGreedy: bool = False
+    aiSimplified: bool = False
+    aiThinkTimeMs: int = -1
+    maxQueueDepth: int = -1
+
+
+class ImportUrlRequest(BaseModel):
+    url: str
+
+
+class ImportTextRequest(BaseModel):
+    text: str
+    commander: Optional[str] = None
+
+
+class MetaFetchRequest(BaseModel):
+    commander: str
+
+
+class CreateDeckRequest(BaseModel):
+    name: str
+    commander_scryfall_id: Optional[str] = ""
+    commander_name: Optional[str] = ""
+    color_identity: Optional[list] = []
+    strategy_tag: Optional[str] = ""
+
+
+class UpdateDeckRequest(BaseModel):
+    name: Optional[str] = None
+    commander_scryfall_id: Optional[str] = None
+    commander_name: Optional[str] = None
+    color_identity: Optional[list] = None
+    strategy_tag: Optional[str] = None
+
+
+class AddDeckCardRequest(BaseModel):
+    scryfall_id: str
+    card_name: Optional[str] = ""
+    quantity: Optional[int] = 1
+    is_commander: Optional[int] = 0
+    role_tag: Optional[str] = ""
+
+
+class PatchDeckCardRequest(BaseModel):
+    quantity: Optional[int] = None
+    role_tag: Optional[str] = None
+
+
+class BulkAddRequest(BaseModel):
+    cards: list[dict]
+    respect_ratios: Optional[bool] = False
+
+
+class BulkAddRecommendedRequest(BaseModel):
+    source: str = "collection"
+    only_owned: Optional[bool] = True
+    respect_ratios: Optional[bool] = False
+    types: Optional[list[str]] = None
+    roles: Optional[list[str]] = None
+
+
+class DeckGenerationSourceConfig(BaseModel):
+    use_archidekt: bool = True
+    use_edhrec: bool = True
+    use_moxfield: bool = False
+    use_mtggoldfish: bool = False
+    archidekt_url: Optional[str] = ""
+    moxfield_url: Optional[str] = ""
+    mtggoldfish_url: Optional[str] = ""
+
+
+class DeckGenerationRequest(BaseModel):
+    commander_name: Optional[str] = ""
+    commander_scryfall_id: Optional[str] = ""
+    color_identity: Optional[list[str]] = None
+    sources: Optional[DeckGenerationSourceConfig] = None
+    target_land_count: int = 37
+    target_instant_count: int = 10
+    target_sorcery_count: int = 8
+    target_artifact_count: int = 10
+    target_enchantment_count: int = 8
+    target_creature_count: int = 25
+    target_planeswalker_count: int = 2
+    only_cards_in_collection: bool = False
+    allow_proxies: bool = True
+    deck_name: Optional[str] = ""
+
+
+class DeckGenV3Request(BaseModel):
+    commander_name: str = ""
+    strategy: str = ""
+    target_bracket: int = 3
+    budget_usd: Optional[float] = None
+    budget_mode: str = "total"
+    omit_cards: list[str] = []
+    use_collection: bool = True
+    run_substitution: bool = True
+    model: Optional[str] = None
+    deck_name: Optional[str] = ""
+
+
+
+
+# ══════════════════════════════════════════════════════════════
+# Deckgen requests (moved from routes/deckgen.py)
+# ══════════════════════════════════════════════════════════════
+
+
+class DeckResearchRequest(BaseModel):
+    deck_id: int  # Deck to research
+    goal: Optional[str] = "Identify weaknesses and suggest upgrades"
+    budget_usd: Optional[float] = None
+    omit_cards: Optional[list[str]] = []
+    use_collection: bool = True
+
+
+class DeckGenerateAIRequest(BaseModel):
+    commander: str
+    budget_usd: Optional[float] = None
+    budget_mode: str = "total"  # "total" or "per_card"
+    omit_cards: Optional[list[str]] = []
+    use_collection: bool = True
+
+
+# ══════════════════════════════════════════════════════════════
+# Coach requests (moved from routes/coach.py)
+# ══════════════════════════════════════════════════════════════
+
+
+class CoachRequestBody(BaseModel):
+    goals: Optional[dict] = None
+
+
+class CoachChatMessage(BaseModel):
+    role: str  # "user" or "assistant"
+    content: str
+
+
+class CoachChatRequest(BaseModel):
+    deck_id: str
+    messages: list[dict]  # conversation history [{role, content}]
+    goals: Optional[dict] = None
+    stream: Optional[bool] = False
+
+
+class CoachApplyRequest(BaseModel):
+    session_id: str
+    deck_id: int  # numeric deck ID in the DB
+    accepted_cuts: list[str] = []  # card names to remove
+    accepted_adds: list[str] = []  # card names to add
+
+
+class CoachGoalsRequest(BaseModel):
+    target_power_level: Optional[int] = None  # 1-10
+    meta_focus: Optional[str] = None  # aggro, control, combo, midrange, stax
+    budget: Optional[str] = None  # budget, medium, no-limit
+    focus_areas: list[str] = []  # e.g., ["ramp", "card draw"]
+class DeckGenV3SubstituteRequest(BaseModel):
+    card_name: str
+    substitute_name: str

models/responses.py

@@ -0,0 +1,45 @@
+"""Pydantic response models for Commander AI Lab API."""
+from __future__ import annotations
+from typing import Optional
+from pydantic import BaseModel
+
+
+class StartResponse(BaseModel):
+    batchId: str
+    status: str = "started"
+    message: str = ""
+
+
+class StatusResponse(BaseModel):
+    batchId: str = ""
+    running: bool = False
+    completed: int = 0
+    total: int = 0
+    threads: int = 0
+    elapsedMs: int = 0
+    error: Optional[str] = None
+    simsPerSec: float = 0.0
+    run_id: str = ""
+    games_completed: int = 0
+    total_games: int = 0
+    current_decks: list = []
+
+
+class DeckInfo(BaseModel):
+    name: str
+    filename: str
+
+
+class GeneratedDeckCard(BaseModel):
+    scryfall_id: str = ""
+    name: str = ""
+    type_line: str = ""
+    mana_cost: str = ""
+    cmc: float = 0
+    card_type: str = ""
+    roles: list[str] = []
+    source: str = "collection"
+    quantity: int = 1
+    image_url: str = ""
+    owned_qty: int = 0
+    is_proxy: bool = False

models/state.py

@@ -0,0 +1,102 @@
+"""Runtime configuration, state classes, and static data for Commander AI Lab."""
+from __future__ import annotations
+import json
+import logging
+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 = ""
+
+
+CFG = Config()
+
+
+# ══════════════════════════════════════════════════════════════
+# 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
+
+
+active_batches: dict[str, BatchState] = {}
+
+
+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},
+}

pom.xml

@@ -67,6 +67,13 @@
             <version>3.45.1.0</version>
         </dependency>
 
+        <!-- WebSocket server for Unity/Godot client -->
+        <dependency>
+            <groupId>org.java-websocket</groupId>
+            <artifactId>Java-WebSocket</artifactId>
+            <version>1.5.6</version>
+        </dependency>
+
         <!-- Testing -->
         <dependency>
             <groupId>org.junit.jupiter</groupId>

pyproject.toml

@@ -14,6 +14,8 @@ dependencies = [
     "fastapi>=0.100.0",
     "uvicorn[standard]>=0.23.0",
     "pydantic>=2.0.0",
+    "httpx>=0.24.0",
+    "websockets>=11.0",
 ]
 
 [project.optional-dependencies]

pytest.ini

@@ -0,0 +1,24 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test* Bench*
+python_functions = test_*
+
+# Asyncio mode for pytest-asyncio
+asyncio_mode = auto
+
+# Markers
+markers =
+    slow: marks tests as slow (deselect with -m "not slow")
+    integration: marks integration tests
+    benchmark: marks benchmark tests
+    unit: marks fast unit tests
+
+# Output
+addopts =
+    --tb=short
+    -q
+
+# Coverage (used when running: pytest --cov)
+# pip install pytest-cov
+# pytest --cov=src/commander_ai_lab --cov-report=term-missing

requirements-web.txt

@@ -0,0 +1,11 @@
+# Commander AI Lab — Web server dependencies (Phase 5)
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+httpx>=0.27.0          # async Scryfall art proxy
+websockets>=12.0       # used by uvicorn WebSocket transport
+pydantic>=2.6.0
+
+# Dev / test
+pytest>=8.0
+pytest-asyncio>=0.23
+httpx>=0.27.0          # TestClient uses httpx transport

requirements.txt

@@ -5,3 +5,11 @@
 fastapi>=0.100.0
 uvicorn[standard]>=0.23.0
 pydantic>=2.0.0
+httpx>=0.24.0
+websockets>=11.0
+
+# Deck Builder dependencies
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+ollama>=0.2.0
+scrython>=2.0.0

routes/__init__.py

@@ -0,0 +1,6 @@
+"""
+routes package — API routers for Commander AI Lab.
+
+Each module defines a FastAPI APIRouter with real endpoint implementations.
+All shared helpers, models, and state live in routes.shared.
+"""

routes/coach.py

@@ -0,0 +1,671 @@
+"""
+routes/coach.py
+===============
+LLM-powered deck coaching endpoints:
+  GET  /api/coach/status
+  GET  /api/coach/decks
+  GET  /api/coach/decks/{deck_id}/report
+  POST /api/coach/decks/{deck_id}
+  GET  /api/coach/sessions
+  GET  /api/coach/sessions/{session_id}
+  POST /api/coach/embeddings/download
+  GET  /api/coach/embeddings/search
+  POST /api/coach/chat
+  POST /api/coach/apply
+  GET  /api/coach/cards-like
+  POST /api/coach/reports/generate
+
+Globals:
+  _coach_service, _coach_embeddings, _coach_llm
+  _deck_gen_v3, _deck_gen_v3_error
+  init_coach_service(), _build_deck_report_from_db()
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import traceback
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+from models.requests import CoachRequestBody, CoachChatMessage, CoachChatRequest, CoachApplyRequest, CoachGoalsRequest
+
+from routes.shared import (
+    CFG,
+    log_coach, log_deckgen,
+    _get_db_conn,
+    _compute_deck_analysis,
+)
+
+router = APIRouter(tags=["coach"])
+
+
+# ══════════════════════════════════════════════════════════════
+# Coach Service (LLM-powered deck coaching)
+# ══════════════════════════════════════════════════════════════
+
+# Global coach instances (initialized at startup)
+_coach_service = None
+_coach_embeddings = None
+_coach_llm = None
+_deck_gen_v3 = None  # V3 Deck Generator (Perplexity structured output)
+_deck_gen_v3_error = None  # Error message if V3 init failed
+
+
+def init_coach_service():
+    """Initialize the coach service with LLM client and embeddings."""
+    global _coach_service, _coach_embeddings, _coach_llm, _deck_gen_v3, _deck_gen_v3_error
+    try:
+        from coach.llm_client import LLMClient
+        from coach.embeddings import MTGEmbeddingIndex
+        from coach.coach_service import CoachService
+        from coach.config import ensure_dirs
+
+        ensure_dirs()
+
+        _coach_llm = LLMClient()
+        _coach_embeddings = MTGEmbeddingIndex()
+
+        # Try to load embeddings (non-blocking — download happens on first use)
+        try:
+            from coach.config import EMBEDDINGS_NPZ
+            if EMBEDDINGS_NPZ.exists():
+                _coach_embeddings.load()
+                log_coach.info(f"  Coach:        Embeddings loaded ({_coach_embeddings.card_count} cards)")
+            else:
+                log_coach.warning("  Coach:        Embeddings not yet downloaded (will download on first use)")
+        except Exception as e:
+            log_coach.error(f"  Coach:        Embeddings load failed: {e}")
+
+        _coach_service = CoachService(_coach_llm, _coach_embeddings)
+
+        # Check LLM connection
+        llm_status = _coach_llm.check_connection()
+        if llm_status.get("connected"):
+            log_coach.info(f"  Coach LLM:    Connected ({llm_status.get('active_model', 'unknown')})")
+        else:
+            log_coach.warning(f"  Coach LLM:    Not connected (start Ollama on 192.168.0.240:11434)")
+
+        # Initialize V3 Deck Generator (Ollama-based)
+        _deck_gen_v3_error = None
+        try:
+            from src.commander_ai_lab.deck_builder.adapter import DeckBuilderAdapter
+            _deck_gen_v3 = DeckBuilderAdapter(
+                db_conn_factory=_get_db_conn,
+                model="gpt-oss:20b",
+            )
+            log_deckgen.info("  Deck Gen V3:  Initialized (Ollama DeckBuilderAdapter)")
+        except ImportError as e:
+            _deck_gen_v3_error = f"Missing dependency: {e}"
+            log_deckgen.error(f"  Deck Gen V3:  {_deck_gen_v3_error}")
+            _deck_gen_v3 = None
+        except Exception as e:
+            _deck_gen_v3_error = str(e)
+            log_deckgen.error(f"  Deck Gen V3:  Failed to initialize: {e}")
+            _deck_gen_v3 = None
+
+    except Exception as e:
+        log_coach.error(f"  Coach:        Failed to initialize: {e}\n{traceback.format_exc()}")
+        _coach_service = None
+
+
+@router.get("/api/coach/status")
+async def coach_status():
+    """Check coach subsystem health."""
+    if _coach_service is None:
+        return {"llmConnected": False, "embeddingsLoaded": False,
+                "embeddingCards": 0, "deckReportsAvailable": 0,
+                "error": "Coach service not initialized"}
+    status = _coach_service.get_status()
+    return status.model_dump()
+
+
+@router.get("/api/coach/decks")
+async def coach_list_decks():
+    """List all decks available for coaching (from deck builder DB)."""
+    conn = _get_db_conn()
+    rows = conn.execute(
+        """SELECT d.id as deck_id, d.name as deck_name, d.commander_name,
+                  COUNT(dc.id) as card_count
+           FROM decks d
+           LEFT JOIN deck_cards dc ON dc.deck_id = d.id
+           GROUP BY d.id
+           ORDER BY d.name"""
+    ).fetchall()
+
+    # Also get report availability from coach service
+    report_ids = set()
+    if _coach_service:
+        report_ids = set(_coach_service.list_deck_reports())
+
+    decks = []
+    for r in rows:
+        deck_name = r["deck_name"]
+        # Check if a report exists (by deck name slug match)
+        has_report = any(
+            deck_name.lower().replace(" ", "-") == rid.lower() or
+            deck_name.lower() == rid.lower()
+            for rid in report_ids
+        )
+        decks.append({
+            "deck_id": r["deck_id"],
+            "deck_name": r["deck_name"],
+            "commander": r["commander_name"] or "",
+            "card_count": r["card_count"],
+            "has_report": has_report,
+            "report_count": 1 if has_report else 0,
+            "last_report_date": None,
+        })
+    return decks
+
+
+@router.get("/api/coach/decks/{deck_id}/report")
+async def coach_get_report(deck_id: str):
+    """Get the latest DeckReport for a deck."""
+    if _coach_service is None:
+        raise HTTPException(500, "Coach service not initialized")
+    report = _coach_service.load_deck_report(deck_id)
+    if report is None:
+        raise HTTPException(404, f"Deck report not found: {deck_id}")
+    return report.model_dump()
+
+
+@router.post("/api/coach/decks/{deck_id}")
+async def coach_run_session(deck_id: str, body: CoachRequestBody = None):
+    """Trigger a coaching session for a deck."""
+    if _coach_service is None:
+        raise HTTPException(500, "Coach service not initialized")
+
+    # Load embeddings on first use if not loaded
+    if _coach_embeddings and not _coach_embeddings.loaded:
+        try:
+            _coach_embeddings.load(force_download=True)
+        except Exception as e:
+            log_coach.error(f"  Coach: Embeddings download failed: {e}")
+
+    goals = None
+    if body and body.goals:
+        from coach.models import CoachGoals
+        try:
+            goals = CoachGoals(**body.goals)
+        except Exception:
+            goals = None
+
+    # Build a fallback DeckReport from the DB if no simulation report exists
+    fallback_report = None
+    try:
+        fallback_report = _build_deck_report_from_db(deck_id)
+    except Exception as e:
+        log_coach.error(f"  Coach: Fallback report build failed for '{deck_id}': {e}")
+
+    try:
+        session = await _coach_service.run_coaching_session(deck_id, goals, fallback_report=fallback_report)
+        return session.model_dump()
+    except ValueError as e:
+        raise HTTPException(404, str(e))
+    except ConnectionError as e:
+        raise HTTPException(503, f"LLM connection failed: {e}")
+    except Exception as e:
+        raise HTTPException(500, f"Coach session failed: {e}")
+
+
+def _build_deck_report_from_db(deck_slug: str):
+    """
+    Build a lightweight DeckReport from the deck builder DB when no
+    simulation report exists. Allows the coach to analyze deck composition
+    even without simulation data.
+    """
+    from coach.models import DeckReport, CardPerformance, DeckStructure
+    conn = _get_db_conn()
+
+    # --- Input validation ---
+    import re
+    if not deck_slug or len(deck_slug) > 200:
+        return None
+    deck_slug = re.sub(r'[^a-zA-Z0-9 _-]', '', deck_slug)
+    if not deck_slug:
+        return None
+
+    # Find the deck by parameterized query instead of full-table scan
+    slug_lower = deck_slug.lower()
+    slug_hyphenated = slug_lower.replace(' ', '-')
+    clean_slug = re.sub(r'[^a-z0-9]+', '-', slug_lower).strip('-')
+
+    if slug_lower.isdigit():
+        # Numeric slug -- match by ID directly
+        matched_deck = conn.execute(
+            "SELECT id, name, commander_name, color_identity FROM decks WHERE id = ?",
+            (int(slug_lower),)
+        ).fetchone()
+    else:
+        # Try exact name match, hyphenated match, or clean-slug match
+        matched_deck = conn.execute(
+            """SELECT id, name, commander_name, color_identity FROM decks
+               WHERE LOWER(name) = ?
+                  OR LOWER(REPLACE(name, ' ', '-')) = ?
+                  OR LOWER(REPLACE(name, ' ', '-')) = ?
+               LIMIT 1""",
+            (slug_lower, slug_hyphenated, clean_slug)
+        ).fetchone()
+
+    if matched_deck is None:
+        return None
+
+    deck_id = matched_deck["id"]
+    deck_name = matched_deck["name"]
+    commander = matched_deck["commander_name"] or ""
+
+    # Parse color identity
+    ci_raw = matched_deck["color_identity"] or "[]"
+    try:
+        color_identity = json.loads(ci_raw) if isinstance(ci_raw, str) else ci_raw
+    except Exception:
+        color_identity = []
+
+    # Load all cards in this deck
+    card_rows = conn.execute(
+        """SELECT dc.card_name, dc.quantity, dc.is_commander, dc.role_tag,
+                  ce.type_line, ce.cmc, ce.oracle_text
+           FROM deck_cards dc
+           LEFT JOIN collection_entries ce ON LOWER(dc.card_name) = LOWER(ce.name)
+           WHERE dc.deck_id = ?""",
+        (deck_id,)
+    ).fetchall()
+
+    cards = []
+    type_counts = {}
+    cmc_buckets = [0] * 8
+    land_count = 0
+
+    for cr in card_rows:
+        card_name = cr["card_name"] or ""
+        type_line = cr["type_line"] or ""
+        cmc = cr["cmc"] or 0
+        qty = cr["quantity"] or 1
+        role_tag = cr["role_tag"] or ""
+
+        # Build tags from type_line and role_tag
+        tags = []
+        if role_tag:
+            tags.append(role_tag)
+        if "Land" in type_line:
+            tags.append("land")
+            land_count += qty
+        elif "Creature" in type_line:
+            tags.append("creature")
+        elif "Instant" in type_line:
+            tags.append("instant")
+        elif "Sorcery" in type_line:
+            tags.append("sorcery")
+        elif "Artifact" in type_line:
+            tags.append("artifact")
+        elif "Enchantment" in type_line:
+            tags.append("enchantment")
+        elif "Planeswalker" in type_line:
+            tags.append("planeswalker")
+
+        # Type count
+        for t in ["Creature", "Instant", "Sorcery", "Artifact", "Enchantment", "Planeswalker", "Land"]:
+            if t in type_line:
+                type_counts[t] = type_counts.get(t, 0) + qty
+
+        # CMC bucket
+        bucket = min(int(cmc), 7)
+        cmc_buckets[bucket] += qty
+
+        # CardPerformance with zeroed-out sim stats
+        cards.append(CardPerformance(
+            name=card_name,
+            drawnRate=0.0,
+            castRate=0.0,
+            impactScore=0.0,
+            tags=tags,
+        ))
+
+    slug = deck_slug
+    return DeckReport(
+        deckId=slug,
+        commander=commander,
+        colorIdentity=color_identity,
+        cards=cards,
+        structure=DeckStructure(
+            landCount=land_count,
+            curveBuckets=cmc_buckets,
+            cardTypeCounts=type_counts,
+        ),
+    )
+
+
+@router.get("/api/coach/sessions")
+async def coach_list_sessions(deck_id: str = None):
+    """List all coaching sessions, optionally filtered by deck."""
+    if _coach_service is None:
+        raise HTTPException(500, "Coach service not initialized")
+    return {"sessions": _coach_service.list_sessions(deck_id)}
+
+
+@router.get("/api/coach/sessions/{session_id}")
+async def coach_get_session(session_id: str):
+    """Get a specific coaching session."""
+    if _coach_service is None:
+        raise HTTPException(500, "Coach service not initialized")
+    session = _coach_service.load_session(session_id)
+    if session is None:
+        raise HTTPException(404, f"Session not found: {session_id}")
+    return session.model_dump()
+
+
+@router.post("/api/coach/embeddings/download")
+async def coach_download_embeddings():
+    """Download and convert MTG card embeddings from HuggingFace."""
+    if _coach_embeddings is None:
+        raise HTTPException(500, "Coach service not initialized")
+    try:
+        _coach_embeddings.load(force_download=True)
+        return {
+            "success": True,
+            "cards": _coach_embeddings.card_count,
+            "message": f"Loaded {_coach_embeddings.card_count} card embeddings"
+        }
+    except Exception as e:
+        raise HTTPException(500, f"Failed to download embeddings: {e}")
+
+
+@router.get("/api/coach/embeddings/search")
+async def coach_search_similar(card: str, colors: str = None, top_n: int = 10):
+    """Search for similar cards by name."""
+    if _coach_embeddings is None or not _coach_embeddings.loaded:
+        raise HTTPException(503, "Embeddings not loaded")
+    color_filter = list(colors.upper()) if colors else None
+    matches = _coach_embeddings.search_similar(
+        query_card=card, color_filter=color_filter, top_n=top_n
+    )
+    return {"query": card, "matches": [m.to_dict() for m in matches]}
+
+
+@router.post("/api/coach/chat")
+async def coach_chat(body: CoachChatRequest):
+    """Multi-turn coaching chat. Sends conversation history to LLM and returns response."""
+    if _coach_service is None:
+        raise HTTPException(500, "Coach service not initialized")
+
+    # Load deck report for context
+    report = _coach_service.load_deck_report(body.deck_id)
+
+    # Build system prompt with report context
+    from coach.prompt_template import build_system_prompt
+    from coach.models import CoachGoals
+
+    goals = None
+    if body.goals:
+        try:
+            goals = CoachGoals(**body.goals)
+        except Exception:
+            goals = None
+
+    system_prompt = ""
+    if report:
+        system_prompt = build_system_prompt(report, goals)
+    else:
+        system_prompt = (
+            "You are an expert Magic: The Gathering Commander deck coach. "
+            "Answer questions about deck building, strategy, card choices, and game theory. "
+            "Be specific and actionable in your advice."
+        )
+
+    # Build messages array for LLM
+    messages = [{"role": "system", "content": system_prompt}]
+    for msg in body.messages:
+        messages.append({"role": msg.get("role", "user"), "content": msg.get("content", "")})
+
+    # Call LLM with multi-turn messages
+    try:
+        import json
+        from urllib.request import urlopen, Request as UrlRequest
+        from coach.config import LLM_URL, LLM_TIMEOUT
+
+        model_name = _coach_llm._resolve_model()
+        llm_body = {
+            "model": model_name,
+            "messages": messages,
+            "temperature": 0.7,
+            "max_tokens": 4096,
+        }
+
+        if body.stream:
+            # SSE streaming response
+            llm_body["stream"] = True
+
+            async def generate():
+                import asyncio
+                def _stream():
+                    req = UrlRequest(
+                        f"{_coach_llm.base_url}/chat/completions",
+                        data=json.dumps(llm_body).encode("utf-8"),
+                        headers={"Content-Type": "application/json"},
+                        method="POST",
+                    )
+                    import http.client
+                    import urllib.parse
+                    parsed = urllib.parse.urlparse(f"{_coach_llm.base_url}/chat/completions")
+                    conn = http.client.HTTPConnection(parsed.hostname, parsed.port, timeout=LLM_TIMEOUT)
+                    conn.request("POST", parsed.path, body=json.dumps(llm_body).encode("utf-8"),
+                                 headers={"Content-Type": "application/json"})
+                    resp = conn.getresponse()
+                    chunks = []
+                    while True:
+                        line = resp.readline()
+                        if not line:
+                            break
+                        line = line.decode("utf-8").strip()
+                        if line.startswith("data: "):
+                            data = line[6:]
+                            if data == "[DONE]":
+                                chunks.append("[DONE]")
+                                break
+                            chunks.append(data)
+                    conn.close()
+                    return chunks
+
+                loop = asyncio.get_event_loop()
+                chunks = await loop.run_in_executor(None, _stream)
+
+                for chunk_str in chunks:
+                    if chunk_str == "[DONE]":
+                        yield f"data: [DONE]\n\n"
+                        break
+                    try:
+                        chunk = json.loads(chunk_str)
+                        delta = chunk.get("choices", [{}])[0].get("delta", {})
+                        content = delta.get("content", "")
+                        if content:
+                            # Strip think tags from streaming chunks
+                            yield f"data: {json.dumps({'content': content})}\n\n"
+                    except json.JSONDecodeError:
+                        continue
+
+            return StreamingResponse(generate(), media_type="text/event-stream")
+        else:
+            # Non-streaming: regular call
+            req = UrlRequest(
+                f"{_coach_llm.base_url}/chat/completions",
+                data=json.dumps(llm_body).encode("utf-8"),
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+
+            import asyncio
+            loop = asyncio.get_event_loop()
+            def _call():
+                with urlopen(req, timeout=LLM_TIMEOUT) as resp:
+                    return json.loads(resp.read().decode("utf-8"))
+
+            raw = await loop.run_in_executor(None, _call)
+
+            content = raw.get("choices", [{}])[0].get("message", {}).get("content", "")
+            # Strip think tags
+            content = _coach_llm._strip_think_tags(content)
+            usage = raw.get("usage", {})
+
+            return {
+                "content": content,
+                "model": raw.get("model", ""),
+                "prompt_tokens": usage.get("prompt_tokens", 0),
+                "completion_tokens": usage.get("completion_tokens", 0),
+            }
+
+    except Exception as e:
+        raise HTTPException(500, f"Chat failed: {e}")
+
+
+@router.post("/api/coach/apply")
+async def coach_apply_suggestions(body: CoachApplyRequest):
+    """Apply accepted coaching suggestions to a deck — remove cuts, add adds."""
+    conn = _get_db_conn()
+
+    # Verify deck exists
+    deck = conn.execute("SELECT * FROM decks WHERE id = ?", (body.deck_id,)).fetchone()
+    if not deck:
+        raise HTTPException(404, f"Deck {body.deck_id} not found")
+
+    results = {"cuts": [], "adds": [], "errors": []}
+
+    # Process cuts: remove cards by name
+    for card_name in body.accepted_cuts:
+        row = conn.execute(
+            "SELECT id FROM deck_cards WHERE deck_id = ? AND card_name = ? LIMIT 1",
+            (body.deck_id, card_name)
+        ).fetchone()
+        if row:
+            conn.execute("DELETE FROM deck_cards WHERE id = ?", (row["id"],))
+            results["cuts"].append({"name": card_name, "status": "removed"})
+        else:
+            # Try case-insensitive
+            row = conn.execute(
+                "SELECT id, card_name FROM deck_cards WHERE deck_id = ? AND LOWER(card_name) = LOWER(?) LIMIT 1",
+                (body.deck_id, card_name)
+            ).fetchone()
+            if row:
+                conn.execute("DELETE FROM deck_cards WHERE id = ?", (row["id"],))
+                results["cuts"].append({"name": row["card_name"], "status": "removed"})
+            else:
+                results["errors"].append({"name": card_name, "error": "Card not found in deck"})
+
+    # Process adds: look up in collection first, then Scryfall
+    for card_name in body.accepted_adds:
+        # Try to find in collection
+        ce = conn.execute(
+            "SELECT scryfall_id, name FROM collection_entries WHERE LOWER(name) = LOWER(?) LIMIT 1",
+            (card_name,)
+        ).fetchone()
+
+        scryfall_id = None
+        resolved_name = card_name
+
+        if ce:
+            scryfall_id = ce["scryfall_id"]
+            resolved_name = ce["name"]
+        else:
+            # Try Scryfall API lookup
+            try:
+                import urllib.parse
+                from urllib.request import urlopen, Request as UrlRequest
+                encoded = urllib.parse.quote(card_name)
+                scry_req = UrlRequest(
+                    f"https://api.scryfall.com/cards/named?fuzzy={encoded}",
+                    headers={"User-Agent": "commander-ai-lab/1.0"}
+                )
+                with urlopen(scry_req, timeout=10) as resp:
+                    card_data = json.loads(resp.read().decode("utf-8"))
+                    scryfall_id = card_data.get("id")
+                    resolved_name = card_data.get("name", card_name)
+            except Exception:
+                pass
+
+        if scryfall_id:
+            # Check if already in deck
+            existing = conn.execute(
+                "SELECT id FROM deck_cards WHERE deck_id = ? AND scryfall_id = ?",
+                (body.deck_id, scryfall_id)
+            ).fetchone()
+            if not existing:
+                conn.execute(
+                    "INSERT INTO deck_cards (deck_id, scryfall_id, card_name, quantity) VALUES (?, ?, ?, 1)",
+                    (body.deck_id, scryfall_id, resolved_name)
+                )
+                results["adds"].append({"name": resolved_name, "scryfall_id": scryfall_id, "status": "added"})
+            else:
+                results["adds"].append({"name": resolved_name, "status": "already_in_deck"})
+        else:
+            results["errors"].append({"name": card_name, "error": "Could not resolve card"})
+
+    conn.execute("UPDATE decks SET updated_at = datetime('now') WHERE id = ?", (body.deck_id,))
+    conn.commit()
+
+    results["total_cuts"] = len(results["cuts"])
+    results["total_adds"] = len([a for a in results["adds"] if a["status"] == "added"])
+    return results
+
+
+@router.get("/api/coach/cards-like")
+async def coach_cards_like(card: str, colors: str = None, top_n: int = 10):
+    """Find cards similar to a given card using embeddings. UI-friendly version."""
+    if _coach_embeddings is None or not _coach_embeddings.loaded:
+        raise HTTPException(503, "Embeddings not loaded")
+
+    color_filter = list(colors.upper()) if colors else None
+    matches = _coach_embeddings.search_similar(
+        query_card=card, color_filter=color_filter, top_n=top_n
+    )
+
+    conn = _get_db_conn()
+    results = []
+    for m in matches:
+        # Check if card is in collection
+        owned = conn.execute(
+            "SELECT SUM(quantity) as qty FROM collection_entries WHERE LOWER(name) = LOWER(?)",
+            (m.name,)
+        ).fetchone()
+        owned_qty = (owned["qty"] or 0) if owned else 0
+
+        # Get image URL and price
+        ce = conn.execute(
+            "SELECT scryfall_id, tcg_price FROM collection_entries WHERE LOWER(name) = LOWER(?) LIMIT 1",
+            (m.name,)
+        ).fetchone()
+
+        results.append({
+            "name": m.name,
+            "similarity": round(m.similarity, 4),
+            "types": m.types,
+            "mana_value": m.mana_value,
+            "mana_cost": m.mana_cost,
+            "text": m.text[:200] if m.text else "",
+            "owned_qty": owned_qty,
+            "image_url": f"https://api.scryfall.com/cards/{ce['scryfall_id']}?format=image&version=normal" if ce and ce["scryfall_id"] else None,
+            "tcg_price": ce["tcg_price"] if ce else None,
+        })
+
+    return {"query": card, "results": results}
+
+
+@router.post("/api/coach/reports/generate")
+async def coach_generate_reports():
+    """Rebuild all deck reports from batch result JSONs in results/."""
+    try:
+        from coach.report_generator import generate_deck_reports
+        lab_root = Path(__file__).parent.parent
+        results_dir = str(lab_root / CFG.results_dir)
+        reports_dir = str(lab_root / "deck-reports")
+        updated = generate_deck_reports(results_dir, reports_dir)
+        return {
+            "status": "ok",
+            "decksUpdated": updated,
+            "count": len(updated),
+            "message": f"Generated reports for {len(updated)} decks" if updated else "No batch results found",
+        }
+    except Exception as e:
+        raise HTTPException(500, f"Report generation failed: {e}")

routes/collection.py

@@ -0,0 +1,487 @@
+"""
+routes/collection.py
+====================
+Collection management endpoints:
+  GET    /api/collection
+  GET    /api/collection/export
+  GET    /api/collection/sets
+  GET    /api/collection/keywords
+  POST   /api/collection/import
+  GET    /api/collection/{cardId}
+  PATCH  /api/collection/{cardId}
+  GET    /api/cache/scryfall
+  DELETE /api/cache/scryfall
+  POST   /api/cache/scryfall/evict
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import re
+from datetime import datetime
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from routes.shared import (
+    CFG,
+    _get_db_conn,
+    _row_to_dict,
+    _add_image_url,
+    _build_collection_filters,
+    _detect_card_roles,
+    _classify_card_type,
+    _enrich_from_scryfall,
+    _fetch_scryfall_api,
+    _parse_finish,
+    _parse_text_line,
+    _parse_csv_content,
+    _auto_infer_mapping,
+    _scryfall_cache,
+    _scryfall_rate_limit,
+    _snake_to_camel,
+    VALID_SORT_FIELDS,
+    _JSON_FIELDS,
+    SCRYFALL_CACHE_DB_PATH,
+    SCRYFALL_CACHE_TTL_SECONDS,
+    _API_HEADERS,
+    log_collect,
+    log_cache,
+)
+
+router = APIRouter(tags=["collection"])
+
+
+@router.get("/api/collection/export")
+async def export_collection(
+    format: str = "INTERNAL_CSV",
+    q: Optional[str] = None,
+    colors: Optional[str] = None,
+    types: Optional[str] = None,
+    isLegendary: Optional[bool] = None,
+    isBasic: Optional[bool] = None,
+    isGameChanger: Optional[bool] = None,
+    highSalt: Optional[bool] = None,
+    finish: Optional[str] = None,
+    cmcMin: Optional[float] = None,
+    cmcMax: Optional[float] = None,
+    priceMin: Optional[float] = None,
+    priceMax: Optional[float] = None,
+    category: Optional[str] = None,
+):
+    """Export collection in various formats with optional filters."""
+    where_str, params = _build_collection_filters(
+        q=q, colors=colors, types=types, isLegendary=isLegendary,
+        isBasic=isBasic, isGameChanger=isGameChanger, highSalt=highSalt,
+        finish=finish, cmcMin=cmcMin, cmcMax=cmcMax,
+        priceMin=priceMin, priceMax=priceMax, category=category,
+    )
+
+    sql = f"SELECT * FROM collection_entries {where_str} ORDER BY name ASC"
+    conn = _get_db_conn()
+    rows = [_row_to_dict(r) for r in conn.execute(sql, params).fetchall()]
+
+    fmt = format.upper()
+    output = io.StringIO()
+
+    if fmt == "INTERNAL_CSV":
+        if rows:
+            fieldnames = list(rows[0].keys())
+        else:
+            fieldnames = [
+                "id", "name", "type_line", "subtypes", "is_legendary", "is_basic",
+                "color_identity", "cmc", "oracle_text", "keywords", "tcg_price",
+                "salt_score", "is_game_changer", "category", "scryfall_id", "tcgplayer_id",
+                "quantity", "finish", "condition", "language", "notes", "tags",
+                "set_code", "collector_number", "created_at", "updated_at",
+            ]
+        writer = csv.DictWriter(output, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(rows)
+        filename = "collection_export.csv"
+        media_type = "text/csv"
+
+    elif fmt == "MOXFIELD_CSV":
+        fieldnames = ["Count", "Name", "Edition", "Condition", "Language", "Foil", "Collector Number"]
+        writer = csv.DictWriter(output, fieldnames=fieldnames)
+        writer.writeheader()
+        for row in rows:
+            finish_val = row.get("finish", "NORMAL").upper()
+            foil_val = "foil" if finish_val == "FOIL" else ("etched" if finish_val == "ETCHED" else "")
+            writer.writerow({
+                "Count": row.get("quantity", 1),
+                "Name": row.get("name", ""),
+                "Edition": row.get("set_code", "").upper(),
+                "Condition": row.get("condition", ""),
+                "Language": row.get("language", ""),
+                "Foil": foil_val,
+                "Collector Number": row.get("collector_number", ""),
+            })
+        filename = "collection_moxfield.csv"
+        media_type = "text/csv"
+
+    elif fmt == "TEXT":
+        lines = []
+        for row in rows:
+            qty = row.get("quantity", 1)
+            name = row.get("name", "")
+            set_code = row.get("set_code", "").upper()
+            coll_num = row.get("collector_number", "")
+            if set_code and coll_num:
+                lines.append(f"{qty} {name} ({set_code}) {coll_num}")
+            elif set_code:
+                lines.append(f"{qty} {name} ({set_code})")
+            else:
+                lines.append(f"{qty} {name}")
+        output.write("\n".join(lines))
+        filename = "collection_export.txt"
+        media_type = "text/plain"
+
+    else:
+        raise HTTPException(400, f"Unknown format: {format}. Use INTERNAL_CSV, MOXFIELD_CSV, or TEXT.")
+
+    content = output.getvalue()
+
+    def iter_content():
+        yield content.encode("utf-8")
+
+    return StreamingResponse(
+        iter_content(),
+        media_type=media_type,
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+@router.get("/api/collection/sets")
+async def collection_sets():
+    """Return distinct set codes + names in the collection (for filter autocomplete)."""
+    conn = _get_db_conn()
+    rows = conn.execute(
+        "SELECT DISTINCT UPPER(set_code) as code, set_name as name FROM collection_entries WHERE set_code != '' ORDER BY set_name ASC"
+    ).fetchall()
+    result = []
+    for r in rows:
+        code = r["code"] if "code" in r.keys() else r[0]
+        name = r["name"] if "name" in r.keys() else r[1]
+        if code:
+            result.append({"code": code, "name": name or code})
+    return JSONResponse(result)
+
+
+@router.get("/api/collection/keywords")
+async def collection_keywords():
+    """Return distinct keywords found in the collection."""
+    conn = _get_db_conn()
+    rows = conn.execute("SELECT keywords FROM collection_entries WHERE keywords != '' AND keywords != '[]'").fetchall()
+    kw_set = set()
+    for r in rows:
+        try:
+            kws = json.loads(r["keywords"]) if isinstance(r["keywords"], str) else r["keywords"]
+            if isinstance(kws, list):
+                for k in kws:
+                    if k:
+                        kw_set.add(k)
+        except (json.JSONDecodeError, TypeError):
+            pass
+    return JSONResponse(sorted(kw_set))
+
+
+@router.get("/api/collection")
+async def list_collection(
+    page: int = 1,
+    pageSize: int = 50,
+    q: Optional[str] = None,
+    sortField: Optional[str] = None,
+    sortDir: Optional[str] = None,
+    colors: Optional[str] = None,
+    types: Optional[str] = None,
+    isLegendary: Optional[bool] = None,
+    isBasic: Optional[bool] = None,
+    isGameChanger: Optional[bool] = None,
+    highSalt: Optional[bool] = None,
+    finish: Optional[str] = None,
+    cmcMin: Optional[float] = None,
+    cmcMax: Optional[float] = None,
+    priceMin: Optional[float] = None,
+    priceMax: Optional[float] = None,
+    category: Optional[str] = None,
+    deck_id: Optional[int] = None,
+    rarity: Optional[str] = None,
+    setCode: Optional[str] = None,
+    powerMin: Optional[str] = None,
+    powerMax: Optional[str] = None,
+    toughMin: Optional[str] = None,
+    toughMax: Optional[str] = None,
+    keyword: Optional[str] = None,
+    edhrecMin: Optional[int] = None,
+    edhrecMax: Optional[int] = None,
+    qtyMin: Optional[int] = None,
+    qtyMax: Optional[int] = None,
+):
+    """List collection entries with search, sort, and filter.
+    Optional deck_id: when provided, includes in_deck_quantity for each result.
+    """
+    where_str, params = _build_collection_filters(
+        q=q, colors=colors, types=types, isLegendary=isLegendary,
+        isBasic=isBasic, isGameChanger=isGameChanger, highSalt=highSalt,
+        finish=finish, cmcMin=cmcMin, cmcMax=cmcMax,
+        priceMin=priceMin, priceMax=priceMax, category=category,
+        rarity=rarity, setCode=setCode, powerMin=powerMin, powerMax=powerMax,
+        toughMin=toughMin, toughMax=toughMax, keyword=keyword,
+        edhrecMin=edhrecMin, edhrecMax=edhrecMax, qtyMin=qtyMin, qtyMax=qtyMax,
+    )
+
+    # Validate sort
+    sort_field = sortField if sortField in VALID_SORT_FIELDS else "name"
+    sort_dir = "DESC" if (sortDir or "").upper() == "DESC" else "ASC"
+
+    conn = _get_db_conn()
+
+    # Count total
+    count_sql = f"SELECT COUNT(*) FROM collection_entries {where_str}"
+    total = conn.execute(count_sql, params).fetchone()[0]
+
+    # Paginate
+    offset = (max(1, page) - 1) * pageSize
+    data_sql = f"""
+        SELECT * FROM collection_entries {where_str}
+        ORDER BY {sort_field} {sort_dir}
+        LIMIT ? OFFSET ?
+    """
+    rows = conn.execute(data_sql, params + [pageSize, offset]).fetchall()
+    items = [_add_image_url(_row_to_dict(r)) for r in rows]
+
+    # If deck_id provided, annotate each item with how many copies are already in that deck
+    if deck_id is not None:
+        # Build a map of scryfall_id -> quantity in deck
+        deck_card_rows = conn.execute(
+            "SELECT scryfall_id, SUM(quantity) as qty FROM deck_cards WHERE deck_id = ? GROUP BY scryfall_id",
+            (deck_id,)
+        ).fetchall()
+        in_deck_map = {row["scryfall_id"]: row["qty"] for row in deck_card_rows}
+        for item in items:
+            item["in_deck_quantity"] = in_deck_map.get(item.get("scryfall_id", ""), 0)
+
+    return {"items": items, "page": page, "pageSize": pageSize, "total": total}
+
+
+@router.get("/api/collection/{cardId}")
+async def get_collection_card(cardId: int):
+    """Get a single collection entry by ID."""
+    conn = _get_db_conn()
+    row = conn.execute("SELECT * FROM collection_entries WHERE id = ?", (cardId,)).fetchone()
+    if not row:
+        raise HTTPException(404, f"Card with id {cardId} not found")
+    return _add_image_url(_row_to_dict(row))
+
+
+@router.patch("/api/collection/{cardId}")
+async def update_collection_card(cardId: int, body: dict):
+    """Update mutable fields of a collection entry."""
+    conn = _get_db_conn()
+    row = conn.execute("SELECT * FROM collection_entries WHERE id = ?", (cardId,)).fetchone()
+    if not row:
+        raise HTTPException(404, f"Card with id {cardId} not found")
+
+    updates = {}
+    if "category" in body:
+        cat = body["category"]
+        if isinstance(cat, list):
+            updates["category"] = json.dumps(cat)
+        else:
+            updates["category"] = cat
+    if "tags" in body:
+        updates["tags"] = str(body["tags"])
+    if "notes" in body:
+        updates["notes"] = str(body["notes"])
+    if "finish" in body:
+        finish_val = str(body["finish"]).upper()
+        if finish_val not in ("NORMAL", "FOIL", "ETCHED"):
+            raise HTTPException(400, "finish must be NORMAL, FOIL, or ETCHED")
+        updates["finish"] = finish_val
+
+    if not updates:
+        return _add_image_url(_row_to_dict(row))
+
+    updates["updated_at"] = datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S")
+    set_clause = ", ".join(f"{k} = ?" for k in updates)
+    values = list(updates.values()) + [cardId]
+    conn.execute(f"UPDATE collection_entries SET {set_clause} WHERE id = ?", values)
+    conn.commit()
+
+    updated_row = conn.execute("SELECT * FROM collection_entries WHERE id = ?", (cardId,)).fetchone()
+    return _add_image_url(_row_to_dict(updated_row))
+
+
+# ══════════════════════════════════════════════════════════════
+# Collection Import Endpoint
+# ══════════════════════════════════════════════════════════════
+
+@router.post("/api/collection/import")
+async def import_collection(body: dict):
+    """
+    Import cards into the collection from CSV, Moxfield, Archidekt, or plain text.
+
+    Body:
+      {
+        "source": "CSV" | "MOXFIELD" | "ARCHIDEKT" | "TEXT",
+        "mode": "MERGE" | "REPLACE",
+        "content": "...csv or text content...",
+        "mapping": { ... optional column mapping ... }
+      }
+    """
+    source = str(body.get("source", "CSV")).upper()
+    mode = str(body.get("mode", "MERGE")).upper()
+    content = str(body.get("content", ""))
+    mapping = body.get("mapping", {})
+
+    if not content.strip():
+        raise HTTPException(400, "content is required")
+
+    imported_count = 0
+    updated_count = 0
+    failed_count = 0
+    errors = []
+
+    conn = _get_db_conn()
+
+    # REPLACE mode: clear existing entries
+    if mode == "REPLACE":
+        conn.execute("DELETE FROM collection_entries")
+        conn.commit()
+
+    # Parse the content into raw rows
+    try:
+        raw_rows = _parse_csv_content(content, source, mapping if mapping else None)
+    except Exception as e:
+        raise HTTPException(400, f"Failed to parse content: {str(e)}")
+
+    for raw in raw_rows:
+        name = raw.get("name", "").strip()
+        if not name:
+            continue
+
+        quantity = int(raw.get("quantity", 1))
+        set_code = raw.get("set_code", "").lower()
+        collector_number = raw.get("collector_number", "")
+        finish = _parse_finish(raw.get("finish", ""))
+        condition = raw.get("condition", "")
+        language = raw.get("language", "")
+        notes = raw.get("notes", "")
+        tags = raw.get("tags", "")
+
+        # Scryfall enrichment
+        try:
+            enriched = _enrich_from_scryfall(name, set_code, collector_number)
+        except Exception as e:
+            errors.append(f"Scryfall error for '{name}': {str(e)}")
+            failed_count += 1
+            continue
+
+        if not enriched or "_error" in enriched:
+            err_msg = enriched.get("_error", f"Card not found on Scryfall: '{name}'") if enriched else f"Card not found on Scryfall: '{name}'"
+            errors.append(err_msg)
+            failed_count += 1
+            continue
+
+        # Use Scryfall-resolved name if available
+        resolved_name = enriched.get("name", name)
+
+        # Check for existing entry (identity key)
+        existing = conn.execute(
+            """SELECT id, quantity FROM collection_entries
+               WHERE name = ? AND set_code = ? AND collector_number = ? AND finish = ?""",
+            (resolved_name, set_code, collector_number, finish),
+        ).fetchone()
+
+        if existing and mode == "MERGE":
+            # Update quantity
+            new_qty = existing["quantity"] + quantity
+            conn.execute(
+                "UPDATE collection_entries SET quantity = ?, updated_at = datetime('now') WHERE id = ?",
+                (new_qty, existing["id"]),
+            )
+            conn.commit()
+            updated_count += 1
+        else:
+            # Insert new row
+            conn.execute(
+                """INSERT INTO collection_entries
+                   (name, type_line, subtypes, is_legendary, is_basic, color_identity,
+                    cmc, mana_cost, oracle_text, keywords,
+                    power, toughness, rarity, set_name, edhrec_rank,
+                    tcg_price, salt_score, is_game_changer,
+                    category, scryfall_id, tcgplayer_id,
+                    quantity, finish, condition, language, notes, tags,
+                    set_code, collector_number)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                (
+                    resolved_name,
+                    enriched.get("type_line", ""),
+                    enriched.get("subtypes", "[]"),
+                    enriched.get("is_legendary", 0),
+                    enriched.get("is_basic", 0),
+                    enriched.get("color_identity", "[]"),
+                    enriched.get("cmc", 0.0),
+                    enriched.get("mana_cost", ""),
+                    enriched.get("oracle_text", ""),
+                    enriched.get("keywords", "[]"),
+                    enriched.get("power", ""),
+                    enriched.get("toughness", ""),
+                    enriched.get("rarity", ""),
+                    enriched.get("set_name", ""),
+                    enriched.get("edhrec_rank", 0),
+                    enriched.get("tcg_price", 0.0),
+                    enriched.get("salt_score", 0.0),
+                    enriched.get("is_game_changer", 0),
+                    enriched.get("category", "[]"),
+                    enriched.get("scryfall_id", ""),
+                    enriched.get("tcgplayer_id", ""),
+                    quantity,
+                    finish,
+                    condition,
+                    language,
+                    notes,
+                    tags,
+                    set_code,
+                    collector_number,
+                ),
+            )
+            conn.commit()
+            imported_count += 1
+
+    return {
+        "importedCount": imported_count,
+        "updatedCount": updated_count,
+        "failedCount": failed_count,
+        "errors": errors,
+    }
+
+
+# ══════════════════════════════════════════════════════════════
+# Scryfall Cache Management Endpoints
+# ══════════════════════════════════════════════════════════════
+
+
+@router.get("/api/cache/scryfall")
+async def scryfall_cache_stats():
+    """Return Scryfall response cache statistics."""
+    return _scryfall_cache.stats()
+
+
+@router.delete("/api/cache/scryfall")
+async def scryfall_cache_clear():
+    """Clear all cached Scryfall responses."""
+    deleted = _scryfall_cache.clear()
+    return {"cleared": deleted, "message": f"Deleted {deleted} cached entries"}
+
+
+@router.post("/api/cache/scryfall/evict")
+async def scryfall_cache_evict_expired():
+    """Remove only expired entries (older than TTL) from the cache."""
+    evicted = _scryfall_cache.evict_expired()
+    return {"evicted": evicted, "message": f"Evicted {evicted} expired entries"}
+
+

routes/deepseek.py

@@ -0,0 +1,811 @@
+"""
+routes/deepseek.py
+==================
+Python simulator & DeepSeek AI opponent endpoints:
+  POST /api/sim/run
+  GET  /api/sim/status
+  GET  /api/sim/result
+  POST /api/sim/run-from-deck
+  POST /api/sim/run-deepseek
+  POST /api/deepseek/connect
+  GET  /api/deepseek/status
+  POST /api/deepseek/configure
+  GET  /api/deepseek/logs
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import time
+import threading as _threading
+import traceback
+import uuid as _uuid
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+from fastapi import Request as FastAPIRequest
+from fastapi.responses import JSONResponse
+
+from routes.shared import (
+    CFG, log_sim,
+    _get_db_conn,
+    _get_deepseek_brain,
+    _ml_logging_enabled,
+)
+from commander_ai_lab.sim.validator_brain import ValidatorBrain, ValidatorConfig
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["deepseek"])
+
+# In-memory store for simulation runs
+_sim_runs = {}  # sim_id -> { status, result, error }
+_sim_lock = _threading.Lock()
+
+# ── Validator singleton ──
+_validator_brain: ValidatorBrain | None = None
+_validator_lock = _threading.Lock()
+
+
+def _get_validator_brain() -> ValidatorBrain | None:
+    global _validator_brain
+    if os.environ.get("VALIDATOR_ENABLED", "false").lower() != "true":
+        return None
+    with _validator_lock:
+        if _validator_brain is None:
+            cfg = ValidatorConfig(
+                api_base=os.environ.get("VALIDATOR_API_BASE", "http://localhost:11434"),
+                model=os.environ.get("VALIDATOR_MODEL", "deepseek-r1:14b"),
+                max_tokens=int(os.environ.get("VALIDATOR_MAX_TOKENS", "2048")),
+                request_timeout=float(os.environ.get("VALIDATOR_TIMEOUT", "120.0")),
+            )
+            _validator_brain = ValidatorBrain(cfg)
+    return _validator_brain
+
+# ══════════════════════════════════════════════════════════════
+# Shared Helpers (extracted to deduplicate sim threads — #42)
+# ══════════════════════════════════════════════════════════════
+
+_SRC_PATH_ADDED = False
+
+
+def _ensure_src_path():
+    """Add project src/ to sys.path once."""
+    global _SRC_PATH_ADDED
+    if not _SRC_PATH_ADDED:
+        src_dir = str(Path(__file__).resolve().parent.parent / 'src')
+        if src_dir not in sys.path:
+            sys.path.insert(0, src_dir)
+        _SRC_PATH_ADDED = True
+
+
+def _build_deck_from_card_data(card_data: list[dict]) -> list:
+    """Build a list of Card objects from DB card dicts. Used by v2 + deepseek threads."""
+    _ensure_src_path()
+    from commander_ai_lab.sim.models import Card
+    from commander_ai_lab.sim.rules import enrich_card
+
+    deck = []
+    for cd in card_data:
+        c = Card(name=cd['name'])
+        if cd.get('type_line'):
+            c.type_line = cd['type_line']
+        if cd.get('cmc'):
+            c.cmc = float(cd['cmc'])
+        if cd.get('power') and cd.get('toughness'):
+            c.power = str(cd['power'])
+            c.toughness = str(cd['toughness'])
+            c.pt = c.power + '/' + c.toughness
+        if cd.get('oracle_text'):
+            c.oracle_text = cd['oracle_text']
+        if cd.get('mana_cost'):
+            c.mana_cost = cd['mana_cost']
+        if cd.get('keywords'):
+            kw = cd['keywords']
+            if isinstance(kw, str):
+                try:
+                    kw = json.loads(kw)
+                except Exception:
+                    kw = []
+            if isinstance(kw, list):
+                c.keywords = kw
+        enrich_card(c)
+        deck.append(c)
+    return deck
+
+
+def _run_game_loop(engine, deck_a, deck_b, deck_name, opponent_name,
+                   num_games, sim_id, **run_kwargs):
+    """Run *num_games* and accumulate stats. Returns (game_results, stats, elapsed)."""
+    start = time.time()
+    wins = losses = total_turns = 0
+    total_damage_dealt = total_damage_received = 0
+    total_spells_cast = total_creatures_played = 0
+    total_removal_used = total_ramp_played = 0
+    total_cards_drawn = total_max_board = 0
+    game_results = []
+
+    for i in range(num_games):
+        kw = dict(run_kwargs)
+        # DeepSeek engine needs per-game IDs
+        if 'game_id_prefix' in kw:
+            prefix = kw.pop('game_id_prefix')
+            kw['game_id'] = f'{prefix}-g{i+1}'
+        result = engine.run(deck_a, deck_b, name_a=deck_name,
+                            name_b=opponent_name, **kw)
+        game_data = result.to_dict()
+        game_data['gameNumber'] = i + 1
+              # Phase 8: Surface player_explanation from validation in turn log
+        for turn_entry in game_data.get('log', []):
+            v = turn_entry.get('validation')
+            if isinstance(v, dict) and v.get('player_explanation'):
+                turn_entry['player_explanation'] = v['player_explanation']
+        game_results.append(game_data)
+
+        if result.winner == 0:
+            wins += 1
+        else:
+            losses += 1
+        total_turns += result.turns
+
+        if result.player_a_stats:
+            s = result.player_a_stats
+            total_damage_dealt += s.damage_dealt
+            total_damage_received += s.damage_received
+            total_spells_cast += s.spells_cast
+            total_creatures_played += s.creatures_played
+            total_removal_used += s.removal_used
+            total_ramp_played += s.ramp_played
+            total_cards_drawn += s.cards_drawn
+            total_max_board += s.max_board_size
+
+        with _sim_lock:
+            _sim_runs[sim_id]['completed'] = i + 1
+
+    elapsed = time.time() - start
+    stats = dict(
+        wins=wins, losses=losses, total_turns=total_turns,
+        total_damage_dealt=total_damage_dealt,
+        total_damage_received=total_damage_received,
+        total_spells_cast=total_spells_cast,
+        total_creatures_played=total_creatures_played,
+        total_removal_used=total_removal_used,
+        total_ramp_played=total_ramp_played,
+        total_cards_drawn=total_cards_drawn,
+        total_max_board=total_max_board,
+    )
+    return game_results, stats, elapsed
+
+
+def _build_summary(stats: dict, deck_name: str, opponent_name: str,
+                   num_games: int, elapsed: float, **extra) -> dict:
+    """Build the JSON-serialisable summary dict from accumulated stats."""
+    n = num_games
+    summary = {
+        'deckName': deck_name,
+        'opponentName': opponent_name,
+        'totalGames': n,
+        'wins': stats['wins'],
+        'losses': stats['losses'],
+        'winRate': round(stats['wins'] / n * 100, 1) if n > 0 else 0.0,
+        'avgTurns': round(stats['total_turns'] / n, 1) if n > 0 else 0.0,
+        'avgDamageDealt': round(stats['total_damage_dealt'] / n, 1) if n > 0 else 0.0,
+        'avgDamageReceived': round(stats['total_damage_received'] / n, 1) if n > 0 else 0.0,
+        'avgSpellsCast': round(stats['total_spells_cast'] / n, 1) if n > 0 else 0.0,
+        'avgCreaturesPlayed': round(stats['total_creatures_played'] / n, 1) if n > 0 else 0.0,
+        'avgRemovalUsed': round(stats['total_removal_used'] / n, 1) if n > 0 else 0.0,
+        'avgRampPlayed': round(stats['total_ramp_played'] / n, 1) if n > 0 else 0.0,
+        'avgCardsDrawn': round(stats['total_cards_drawn'] / n, 1) if n > 0 else 0.0,
+        'avgMaxBoardSize': round(stats['total_max_board'] / n, 1) if n > 0 else 0.0,
+        'elapsedSeconds': round(elapsed, 3),
+    }
+    summary.update(extra)
+    return summary
+
+
+def _finish_sim(sim_id, summary, game_results, engine=None):
+    """Mark a sim run as complete."""
+    with _sim_lock:
+        _sim_runs[sim_id]['status'] = 'complete'
+        _sim_runs[sim_id]['result'] = {'summary': summary, 'games': game_results}
+
+          # --- Persist batch-*.json for coach / training dashboard ---
+    try:
+        deck_name = summary.get('deckName', 'Unknown')
+        opponent_name = summary.get('opponentName', 'Training Deck')
+        batch_data = {
+            'format': 'python-sim',
+            'timestamp': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),
+            'simId': sim_id,
+            'decks': [
+                {
+                    'deckName': deck_name,
+                    'seatIndex': 0,
+                    'commanderName': summary.get('commanderName', ''),
+                    'colorIdentity': summary.get('colorIdentity', []),
+                    'games': game_results,
+                },
+                {
+                    'deckName': opponent_name,
+                    'seatIndex': 1,
+                    'commanderName': '',
+                    'colorIdentity': [],
+                },
+            ],
+            'summary': summary,
+        }
+        results_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'results')
+        os.makedirs(results_dir, exist_ok=True)
+        batch_path = os.path.join(results_dir, f'batch-sim-{sim_id}.json')
+        with open(batch_path, 'w') as f:
+            json.dump(batch_data, f, indent=2, default=str)
+        logger.info(f'Saved batch results to {batch_path}')
+
+        # Auto-generate deck report for training dashboard / coach
+        try:
+            from coach.report_generator import generate_deck_reports
+            reports_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'deck-reports')
+            os.makedirs(reports_dir, exist_ok=True)
+            generate_deck_reports(str(results_dir), str(reports_dir))
+            logger.info(f'Generated deck reports after sim {sim_id}')
+        except ImportError:
+            logger.warning('reports module not available; skipping deck report generation')
+        except Exception as e:
+            logger.warning(f'Could not generate deck report: {e}')
+    except Exception as e:
+        logger.error(f'Failed to persist sim results: {e}')
+
+    # --- Flush ML decisions JSONL for training pipeline ---
+    if engine is not None and hasattr(engine, 'flush_ml_decisions'):
+        ml_decisions = engine.flush_ml_decisions()
+        if ml_decisions:
+            ml_path = os.path.join('results', f'ml-decisions-sim-{sim_id[:8]}.jsonl')
+            os.makedirs('results', exist_ok=True)
+            with open(ml_path, 'w', encoding='utf-8') as mf:
+                for dec in ml_decisions:
+                    mf.write(json.dumps(dec) + '\n')
+            logger.info(f'Wrote {len(ml_decisions)} ML decisions to {ml_path}')
+        
+def _fail_sim(sim_id, error):
+    """Mark a sim run as errored."""
+    with _sim_lock:
+        _sim_runs[sim_id]['status'] = 'error'
+        _sim_runs[sim_id]['error'] = str(error)
+
+# ══════════════════════════════════════════════════════════════
+# Background Sim Threads (now thin wrappers around shared helpers)
+# ══════════════════════════════════════════════════════════════
+
+def _run_sim_thread(sim_id: str, decklist: list, num_games: int,
+                    deck_name: str, record_logs: bool):
+    """Background thread: basic Monte Carlo sim from a raw decklist."""
+    try:
+        _ensure_src_path()
+        from commander_ai_lab.sim.engine import GameEngine
+        from commander_ai_lab.lab.experiments import build_deck, _generate_training_deck
+
+        with _sim_lock:
+            _sim_runs[sim_id]['status'] = 'running'
+
+        deck_a = build_deck(decklist)
+        deck_b = _generate_training_deck()
+        engine = GameEngine(max_turns=25, record_log=record_logs, ml_log=True)
+
+        game_results, stats, elapsed = _run_game_loop(
+            engine, deck_a, deck_b, deck_name, 'Training Deck',
+            num_games, sim_id)
+
+        summary = _build_summary(stats, deck_name, 'Training Deck',
+                                 num_games, elapsed)
+        _finish_sim(sim_id, summary, game_results, engine=engine)
+    except Exception as e:
+        _fail_sim(sim_id, e)
+        traceback.print_exc()
+
+
+def _run_sim_thread_v2(sim_id: str, card_data: list[dict], num_games: int,
+                       deck_name: str, record_logs: bool):
+    """Background thread: sim with full card data from the DB."""
+    try:
+        _ensure_src_path()
+        from commander_ai_lab.sim.engine import GameEngine
+        from commander_ai_lab.lab.experiments import _generate_training_deck
+
+        with _sim_lock:
+            _sim_runs[sim_id]['status'] = 'running'
+
+        deck_a = _build_deck_from_card_data(card_data)
+        deck_b = _generate_training_deck()
+        engine = GameEngine(max_turns=25, record_log=record_logs, ml_log=True)
+
+        game_results, stats, elapsed = _run_game_loop(
+            engine, deck_a, deck_b, deck_name, 'Training Deck',
+            num_games, sim_id)
+
+        summary = _build_summary(stats, deck_name, 'Training Deck',
+                                 num_games, elapsed)
+        _finish_sim(sim_id, summary, game_results, engine=engine)
+    except Exception as e:
+        _fail_sim(sim_id, e)
+        traceback.print_exc()
+
+
+def _run_sim_thread_deepseek(sim_id: str, card_data: list[dict],
+                             num_games: int, deck_name: str,
+                             record_logs: bool):
+    """Background thread: sim using DeepSeek AI opponent."""
+    try:
+        _ensure_src_path()
+        from commander_ai_lab.sim.deepseek_engine import DeepSeekGameEngine
+        from commander_ai_lab.lab.experiments import _generate_training_deck
+
+        with _sim_lock:
+            _sim_runs[sim_id]['status'] = 'running'
+
+        deck_a = _build_deck_from_card_data(card_data)
+        deck_b = _generate_training_deck()
+
+        brain = _get_deepseek_brain()
+        if brain and not brain._connected:
+            brain.check_connection()
+
+        validator = _get_validator_brain()  # None if disabled
+        engine = DeepSeekGameEngine(
+            brain=brain, ai_player_index=1,
+            max_turns=25, record_log=record_logs, ml_log=True,
+            validator=validator)
+
+        game_results, stats, elapsed = _run_game_loop(
+            engine, deck_a, deck_b, deck_name, 'DeepSeek AI',
+            num_games, sim_id,
+            game_id_prefix=f'ds-sim-{sim_id[:8]}',
+            archetype='midrange')
+
+        # Write ML decision JSONL for training pipeline
+        ml_decisions = engine.flush_ml_decisions()
+        if ml_decisions:
+            ml_path = os.path.join('results',
+                                   f'ml-decisions-sim-{sim_id[:8]}.jsonl')
+            os.makedirs('results', exist_ok=True)
+            with open(ml_path, 'w', encoding='utf-8') as mf:
+                for dec in ml_decisions:
+                    mf.write(json.dumps(dec) + '\n')
+
+        ds_stats = brain.get_stats() if brain else {}
+        summary = _build_summary(
+            stats, deck_name, 'DeepSeek AI', num_games, elapsed,
+            opponentType='deepseek', deepseekStats=ds_stats)
+        _finish_sim(sim_id, summary, game_results, engine=engine)
+    except Exception as e:
+        _fail_sim(sim_id, e)
+        traceback.print_exc()
+
+# ══════════════════════════════════════════════════════════════
+# N-Player Sim Thread
+# ══════════════════════════════════════════════════════════════
+
+
+def _run_sim_thread_n_player(sim_id: str, decks_data: list[list[dict]],
+                              deck_names: list[str], num_games: int,
+                              record_logs: bool, engine_type: str):
+    """Background thread: N-player (2-4) batch simulation."""
+    try:
+        _ensure_src_path()
+        from commander_ai_lab.sim.engine import GameEngine
+        from commander_ai_lab.sim.deepseek_engine import DeepSeekGameEngine
+
+        with _sim_lock:
+            _sim_runs[sim_id]['status'] = 'running'
+
+        n_players = len(decks_data)
+        built_decks = [_build_deck_from_card_data(cd) for cd in decks_data]
+
+        if engine_type == 'deepseek':
+            brain = _get_deepseek_brain()
+            if brain and not brain._connected:
+                brain.check_connection()
+            engine = DeepSeekGameEngine(
+                brain=brain, ai_player_index=1,
+                max_turns=25, record_log=record_logs, ml_log=True)
+        else:
+            engine = GameEngine(max_turns=25, record_log=record_logs, ml_log=True)
+
+        # Per-seat accumulators
+        seat_wins = [0] * n_players
+        seat_turns = [0] * n_players
+        seat_damage_dealt = [0] * n_players
+        seat_spells_cast = [0] * n_players
+        seat_creatures_played = [0] * n_players
+        seat_removal_used = [0] * n_players
+        seat_ramp_played = [0] * n_players
+        seat_cards_drawn = [0] * n_players
+        seat_max_board = [0] * n_players
+
+        game_results = []
+        start = time.time()
+
+        for i in range(num_games):
+            result = engine.run_n(decks=built_decks, names=deck_names)
+            game_data = result.to_dict()
+            game_data['gameNumber'] = i + 1
+            game_results.append(game_data)
+
+            if 0 <= result.winner_seat < n_players:
+                seat_wins[result.winner_seat] += 1
+
+            for pr in result.players:
+                si = pr.seat_index
+                seat_turns[si] += result.turns
+                if pr.stats:
+                    seat_damage_dealt[si] += pr.stats.damage_dealt
+                    seat_spells_cast[si] += pr.stats.spells_cast
+                    seat_creatures_played[si] += pr.stats.creatures_played
+                    seat_removal_used[si] += pr.stats.removal_used
+                    seat_ramp_played[si] += pr.stats.ramp_played
+                    seat_cards_drawn[si] += pr.stats.cards_drawn
+                    seat_max_board[si] += pr.stats.max_board_size
+
+            with _sim_lock:
+                _sim_runs[sim_id]['completed'] = i + 1
+
+        elapsed = time.time() - start
+        n = num_games if num_games > 0 else 1
+
+        players_summary = []
+        for si in range(n_players):
+            players_summary.append({
+                'seat': si,
+                'deckName': deck_names[si],
+                'wins': seat_wins[si],
+                'winRate': round(seat_wins[si] / n * 100, 1),
+                'avgTurns': round(seat_turns[si] / n, 1),
+                'avgDamageDealt': round(seat_damage_dealt[si] / n, 1),
+                'avgSpellsCast': round(seat_spells_cast[si] / n, 1),
+                'avgCreaturesPlayed': round(seat_creatures_played[si] / n, 1),
+                'avgRemovalUsed': round(seat_removal_used[si] / n, 1),
+                'avgRampPlayed': round(seat_ramp_played[si] / n, 1),
+                'avgCardsDrawn': round(seat_cards_drawn[si] / n, 1),
+                'avgMaxBoardSize': round(seat_max_board[si] / n, 1),
+            })
+
+        summary = {
+            'playerCount': n_players,
+            'totalGames': num_games,
+            'players': players_summary,
+            'elapsedSeconds': round(elapsed, 3),
+        }
+        _finish_sim(sim_id, summary, game_results, engine=engine)
+    except Exception as e:
+        _fail_sim(sim_id, e)
+        traceback.print_exc()
+
+
+# ══════════════════════════════════════════════════════════════
+# Simulation API Endpoints
+# ══════════════════════════════════════════════════════════════
+
+
+def _create_sim_run(num_games, deck_name):
+    """Create a queued sim run entry and return its ID."""
+    sim_id = str(_uuid.uuid4())[:8]
+    with _sim_lock:
+        _sim_runs[sim_id] = {
+            'status': 'queued', 'completed': 0,
+            'total': num_games, 'deckName': deck_name,
+            'result': None, 'error': None,
+        }
+    return sim_id
+
+
+def _fetch_deck_card_data(deck_id):
+    """Load card data from the DB for a given deck ID. Returns (deck_name, card_data) or raises."""
+    conn = _get_db_conn()
+    cur = conn.cursor()
+    cur.execute('SELECT name FROM decks WHERE id = ?', (deck_id,))
+    row = cur.fetchone()
+    if not row:
+        return None, None
+    deck_name = row[0]
+    cur.execute("""
+        SELECT dc.card_name, dc.quantity,
+               ce.type_line, ce.cmc, ce.power, ce.toughness,
+               ce.oracle_text, ce.keywords, ce.mana_cost
+        FROM deck_cards dc
+        LEFT JOIN (
+            SELECT scryfall_id, type_line, cmc, power, toughness,
+                   oracle_text, keywords, mana_cost
+            FROM collection_entries GROUP BY scryfall_id
+        ) ce ON ce.scryfall_id = dc.scryfall_id
+        WHERE dc.deck_id = ?
+    """, (deck_id,))
+    card_data = []
+    for r in cur.fetchall():
+        for _ in range(r[1] or 1):
+            card_data.append({
+                'name': r[0], 'type_line': r[2] or '',
+                'cmc': r[3] or 0, 'power': r[4] or '',
+                'toughness': r[5] or '', 'oracle_text': r[6] or '',
+                'keywords': r[7] or '', 'mana_cost': r[8] or '',
+            })
+    return deck_name, card_data
+
+
+@router.post('/api/sim/run')
+async def sim_run(request: FastAPIRequest):
+    """Start a Monte Carlo simulation with the Python engine."""
+    body = await request.json()
+    decklist = body.get('decklist', [])
+    num_games = body.get('numGames', 10)
+    deck_name = body.get('deckName', 'My Deck')
+    record_logs = body.get('recordLogs', True)
+
+    if not decklist:
+        return JSONResponse({'error': 'decklist is required'}, status_code=400)
+    if num_games < 1 or num_games > 1000:
+        return JSONResponse({'error': 'numGames must be 1-1000'}, status_code=400)
+
+    sim_id = _create_sim_run(num_games, deck_name)
+    _threading.Thread(target=_run_sim_thread,
+                      args=(sim_id, decklist, num_games, deck_name, record_logs),
+                      daemon=True).start()
+    return JSONResponse({'simId': sim_id, 'status': 'queued', 'total': num_games})
+
+
+@router.get('/api/sim/status')
+async def sim_status(simId: str):
+    """Poll simulation progress."""
+    with _sim_lock:
+        run = _sim_runs.get(simId)
+    if not run:
+        return JSONResponse({'error': 'sim not found'}, status_code=404)
+    return JSONResponse({
+        'simId': simId, 'status': run['status'],
+        'completed': run['completed'], 'total': run['total'],
+        'deckName': run.get('deckName', ''), 'error': run.get('error'),
+    })
+
+
+@router.get('/api/sim/result')
+async def sim_result(simId: str):
+    """Get completed simulation results."""
+    with _sim_lock:
+        run = _sim_runs.get(simId)
+    if not run:
+        return JSONResponse({'error': 'sim not found'}, status_code=404)
+    if run['status'] != 'complete':
+        return JSONResponse({'error': 'sim not complete', 'status': run['status']},
+                            status_code=400)
+    return JSONResponse(run['result'])
+
+
+@router.post('/api/sim/run-from-deck')
+async def sim_run_from_deck(request: FastAPIRequest):
+    """Start simulation using a deck from the Deck Builder (by deck ID)."""
+    body = await request.json()
+    deck_id = body.get('deckId')
+    num_games = body.get('numGames', 10)
+    record_logs = body.get('recordLogs', True)
+
+    if not deck_id:
+        return JSONResponse({'error': 'deckId required'}, status_code=400)
+
+    deck_name, card_data = _fetch_deck_card_data(deck_id)
+    if deck_name is None:
+        return JSONResponse({'error': 'deck not found'}, status_code=404)
+    if not card_data:
+        return JSONResponse({'error': 'deck has no cards'}, status_code=400)
+
+    sim_id = _create_sim_run(num_games, deck_name)
+    _threading.Thread(target=_run_sim_thread_v2,
+                      args=(sim_id, card_data, num_games, deck_name, record_logs),
+                      daemon=True).start()
+    return JSONResponse({'simId': sim_id, 'status': 'queued',
+                         'total': num_games, 'deckName': deck_name})
+
+
+@router.post('/api/sim/run-deepseek')
+async def sim_run_deepseek(request: FastAPIRequest):
+    """Start simulation using DeepSeek AI as the opponent brain."""
+    body = await request.json()
+    deck_id = body.get('deckId')
+    num_games = body.get('numGames', 5)
+    record_logs = body.get('recordLogs', True)
+
+    if not deck_id:
+        return JSONResponse({'error': 'deckId required'}, status_code=400)
+    if num_games < 1 or num_games > 50:
+        return JSONResponse({'error': 'numGames must be 1-50 for DeepSeek mode'},
+                            status_code=400)
+
+    deck_name, card_data = _fetch_deck_card_data(deck_id)
+    if deck_name is None:
+        return JSONResponse({'error': 'deck not found'}, status_code=404)
+    if not card_data:
+        return JSONResponse({'error': 'deck has no cards'}, status_code=400)
+
+    sim_id = _create_sim_run(num_games, deck_name)
+    _threading.Thread(target=_run_sim_thread_deepseek,
+                      args=(sim_id, card_data, num_games, deck_name, record_logs),
+                      daemon=True).start()
+    return JSONResponse({'simId': sim_id, 'status': 'queued',
+                         'total': num_games, 'deckName': deck_name,
+                         'opponentType': 'deepseek'})
+
+
+@router.post('/api/sim/run-n-player')
+async def sim_run_n_player(request: FastAPIRequest):
+    """Start an N-player (2-4) batch simulation."""
+    body = await request.json()
+    deck_ids = body.get('deckIds', [])
+    num_games = body.get('numGames', 10)
+    record_logs = body.get('recordLogs', True)
+    engine_type = body.get('engineType', 'heuristic')
+
+    if len(deck_ids) < 2 or len(deck_ids) > 4:
+        return JSONResponse({'error': '2-4 decks required'}, status_code=400)
+    if num_games < 1 or num_games > 1000:
+        return JSONResponse({'error': 'numGames must be 1-1000'}, status_code=400)
+
+    decks_data = []
+    deck_names = []
+    for did in deck_ids:
+        name, cards = _fetch_deck_card_data(did)
+        if name is None:
+            return JSONResponse({'error': f'Deck {did} not found'}, status_code=404)
+        if not cards:
+            return JSONResponse({'error': f'Deck {did} has no cards'}, status_code=400)
+        deck_names.append(name)
+        decks_data.append(cards)
+
+    sim_id = _create_sim_run(num_games, ' vs '.join(deck_names))
+    _threading.Thread(target=_run_sim_thread_n_player,
+                      args=(sim_id, decks_data, deck_names, num_games,
+                            record_logs, engine_type),
+                      daemon=True).start()
+    return JSONResponse({
+        'simId': sim_id, 'status': 'queued', 'total': num_games,
+        'deckNames': deck_names, 'playerCount': len(deck_ids),
+    })
+
+
+# ══════════════════════════════════════════════════════════════
+# DeepSeek AI Brain Endpoints
+# ══════════════════════════════════════════════════════════════
+
+
+@router.post('/api/deepseek/connect')
+async def deepseek_connect(request: FastAPIRequest):
+    """Test connection to the DeepSeek LLM endpoint and auto-detect model."""
+    body = await request.json() if await request.body() else {}
+    api_base = body.get('apiBase', None)
+    model = body.get('model', None)
+
+    brain = _get_deepseek_brain()
+    if brain is None:
+        return JSONResponse({'error': 'DeepSeek brain failed to initialize'},
+                            status_code=500)
+
+    if api_base:
+        brain.config.api_base = api_base
+    if model:
+        brain.config.model = model
+
+    connected = brain.check_connection()
+    return JSONResponse({
+        'connected': connected,
+        'apiBase': brain.config.api_base,
+        'model': brain.config.model,
+        'stats': brain.get_stats(),
+    })
+
+
+@router.get('/api/deepseek/status')
+async def deepseek_status():
+    """Get DeepSeek brain status and performance stats."""
+    brain = _get_deepseek_brain()
+    if brain is None:
+        return JSONResponse({'connected': False, 'error': 'Brain not initialized'})
+    return JSONResponse(brain.get_stats())
+
+
+@router.post('/api/deepseek/configure')
+async def deepseek_configure(request: FastAPIRequest):
+    """Update DeepSeek configuration at runtime."""
+    body = await request.json()
+    brain = _get_deepseek_brain()
+    if brain is None:
+        return JSONResponse({'error': 'Brain not initialized'}, status_code=500)
+
+    if 'apiBase' in body:
+        brain.config.api_base = body['apiBase']
+    if 'model' in body:
+        brain.config.model = body['model']
+    if 'temperature' in body:
+        brain.config.temperature = float(body['temperature'])
+    if 'maxTokens' in body:
+        brain.config.max_tokens = int(body['maxTokens'])
+    if 'timeout' in body:
+        brain.config.request_timeout = float(body['timeout'])
+    if 'cacheEnabled' in body:
+        brain.config.cache_enabled = bool(body['cacheEnabled'])
+    if 'logDecisions' in body:
+        brain.config.log_decisions = bool(body['logDecisions'])
+    if 'fallbackOnTimeout' in body:
+        brain.config.fallback_on_timeout = bool(body['fallbackOnTimeout'])
+
+    connected = brain.check_connection()
+    return JSONResponse({
+        'connected': connected,
+        'config': {
+            'apiBase': brain.config.api_base,
+            'model': brain.config.model,
+            'temperature': brain.config.temperature,
+            'maxTokens': brain.config.max_tokens,
+            'timeout': brain.config.request_timeout,
+            'cacheEnabled': brain.config.cache_enabled,
+            'logDecisions': brain.config.log_decisions,
+            'fallbackOnTimeout': brain.config.fallback_on_timeout,
+        },
+    })
+
+
+@router.get('/api/deepseek/logs')
+async def deepseek_logs():
+    """Get decision log stats and flush pending entries."""
+    brain = _get_deepseek_brain()
+    if brain is None:
+        return JSONResponse({'error': 'Brain not initialized'}, status_code=500)
+
+    pending = len(brain._decision_log)
+    flushed_path = None
+    if pending > 0:
+        try:
+            flushed_path = brain.flush_log()
+        except Exception as e:
+            return JSONResponse({'error': f'Failed to flush: {e}'},
+                                status_code=500)
+
+    import glob as _glob
+    log_dir = brain.config.log_dir
+    log_files = []
+    if log_dir and os.path.isdir(log_dir):
+        for f in sorted(_glob.glob(os.path.join(log_dir, 'decisions_*.jsonl'))):
+            stat = os.stat(f)
+            log_files.append({
+                'filename': os.path.basename(f),
+                'size_bytes': stat.st_size,
+                'modified': stat.st_mtime,
+            })
+
+    return JSONResponse({
+        'flushed': pending,
+        'flushedPath': flushed_path,
+        'logFiles': log_files[-20:],
+    })
+  
+
+@router.get("/api/validator/status")
+async def validator_status():
+    """Get DeepSeek-R1-14B validator brain status."""
+    v = _get_validator_brain()
+    if v is None:
+        return JSONResponse({"enabled": False,
+                             "reason": "VALIDATOR_ENABLED is not true"})
+    return JSONResponse({"enabled": True, **v.get_stats()})
+
+
+@router.post("/api/validator/configure")
+async def validator_configure(request: FastAPIRequest):
+    """Update validator configuration at runtime."""
+    body = await request.json()
+    v = _get_validator_brain()
+    if v is None:
+        return JSONResponse({"error": "Validator not enabled"}, status_code=400)
+    if "model" in body:
+        v.config.model = body["model"]
+    if "timeout" in body:
+        v.config.request_timeout = float(body["timeout"])
+    if "enabled" in body:
+        v.config.enabled = bool(body["enabled"])
+    return JSONResponse(v.get_stats())

routes/import_routes.py

@@ -0,0 +1,127 @@
+"""
+routes/import_routes.py
+=======================
+Deck import & commander meta endpoints:
+  POST /api/lab/import/url
+  POST /api/lab/import/text
+  GET  /api/lab/meta/commanders
+  GET  /api/lab/meta/search
+  POST /api/lab/meta/fetch
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+from fastapi.responses import JSONResponse
+
+import routes.shared as _shared
+from routes.shared import (
+    ImportUrlRequest,
+    ImportTextRequest,
+    MetaFetchRequest,
+    _import_from_url,
+    _parse_text_decklist,
+    _save_profile_to_dck,
+    _fetch_edhrec_average,
+    log,
+)
+
+router = APIRouter(tags=["import"])
+
+
+@router.post("/api/lab/import/url")
+async def import_from_url(req: ImportUrlRequest):
+    """Import a deck from Archidekt or EDHREC URL. Returns parsed DeckProfile + saves .dck file."""
+    url = req.url.strip()
+    try:
+        profile = _import_from_url(url)
+        dck_path = _save_profile_to_dck(profile)
+        return {
+            "success": True,
+            "deckName": profile["name"],
+            "commander": profile["commander"],
+            "source": profile["source"],
+            "sourceUrl": profile["sourceUrl"],
+            "totalCards": profile["totalCards"],
+            "dckFile": dck_path.stem,
+            "colorIdentity": profile.get("colorIdentity", []),
+            "archetype": profile.get("archetype"),
+        }
+    except Exception as e:
+        raise HTTPException(400, str(e))
+
+
+@router.post("/api/lab/import/text")
+async def import_from_text(req: ImportTextRequest):
+    """Import a deck from plain text card list."""
+    try:
+        profile = _parse_text_decklist(req.text, req.commander)
+        dck_path = _save_profile_to_dck(profile)
+        return {
+            "success": True,
+            "deckName": profile["name"],
+            "commander": profile["commander"],
+            "source": "Text Import",
+            "totalCards": profile["totalCards"],
+            "dckFile": dck_path.stem,
+        }
+    except Exception as e:
+        raise HTTPException(400, str(e))
+
+
+@router.get("/api/lab/meta/commanders")
+async def list_meta_commanders():
+    """List available commanders in the meta mapping."""
+    commanders = []
+    for name, entries in _shared.COMMANDER_META.items():
+        entry = entries[0] if entries else {}
+        commanders.append({
+            "name": name,
+            "archetype": entry.get("archetype", ""),
+            "colorIdentity": entry.get("colorIdentity", []),
+            "source": entry.get("source", "edhrec"),
+        })
+    return {"commanders": commanders}
+
+
+@router.get("/api/lab/meta/search")
+async def search_meta_commanders(q: str = ""):
+    """Search commanders by partial name match."""
+    query = q.lower()
+    matches = []
+    for name, entries in _shared.COMMANDER_META.items():
+        if query in name.lower():
+            entry = entries[0] if entries else {}
+            matches.append({
+                "name": name,
+                "archetype": entry.get("archetype", ""),
+                "colorIdentity": entry.get("colorIdentity", []),
+            })
+    return {"results": matches}
+
+
+@router.post("/api/lab/meta/fetch")
+async def fetch_meta_deck(req: MetaFetchRequest):
+    """Fetch EDHREC average deck for a commander and save as .dck file."""
+    try:
+        profile = _fetch_edhrec_average(req.commander)
+        dck_path = _save_profile_to_dck(profile)
+        return {
+            "success": True,
+            "deckName": profile["name"],
+            "commander": profile["commander"],
+            "source": "EDHREC Average",
+            "sourceUrl": profile.get("sourceUrl", ""),
+            "totalCards": profile["totalCards"],
+            "dckFile": dck_path.stem,
+            "colorIdentity": profile.get("colorIdentity", []),
+            "sampleSize": profile.get("sampleSize"),
+        }
+    except Exception as e:
+        raise HTTPException(400, f"Failed to fetch meta deck for '{req.commander}': {str(e)}")
+
+
+# ══════════════════════════════════════════════════════════════
+# Existing Endpoints (v1/v2)
+# ══════════════════════════════════════════════════════════════

routes/lab.py

@@ -0,0 +1,481 @@
+"""
+routes/lab.py
+=============
+Batch simulation & lab management endpoints:
+  POST /api/lab/start
+  POST /api/lab/start-deepseek
+  GET  /api/lab/status
+  GET  /api/lab/result
+  GET  /api/lab/decks
+  GET  /api/lab/history
+  GET  /api/lab/profiles
+  GET  /api/lab/profiles/{name}
+  GET  /api/lab/analytics/{deck_name}
+  GET  /api/lab/trends/{deck_name}
+  GET  /api/lab/log
+  GET  /api/lab/debug-log
+"""
+from __future__ import annotations
+
+import glob
+import json
+import math
+import os
+import re
+import threading
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Request as FastAPIRequest
+from fastapi.responses import JSONResponse
+
+from routes.shared import (
+    CFG,
+    active_batches,
+    BatchState,
+    StartRequest,
+    StartResponse,
+    StatusResponse,
+    AI_PROFILES,
+    build_java_command,
+    run_batch_subprocess,
+    _run_deepseek_batch_thread,
+    parse_dck_file,
+    _get_db_conn,
+    _load_deck_cards_by_name,
+    log,
+    log_batch,
+)
+
+router = APIRouter(tags=["lab"])
+
+
+def _sanitize_floats(obj):
+    """Replace NaN/Infinity with None so JSONResponse (allow_nan=False) won't crash."""
+    if isinstance(obj, float):
+        if math.isnan(obj) or math.isinf(obj):
+            return None
+        return obj
+    if isinstance(obj, dict):
+        return {k: _sanitize_floats(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_sanitize_floats(v) for v in obj]
+    return obj
+
+
+@router.post("/api/lab/start", response_model=StartResponse)
+async def start_batch(req: StartRequest, background_tasks: BackgroundTasks):
+    """Start a new batch simulation run."""
+    if len(req.decks) < 2 or len(req.decks) > 4:
+        raise HTTPException(400, "2-4 decks required")
+    if not all(req.decks):
+        raise HTTPException(400, f"All {len(req.decks)} deck slots must be filled")
+    if req.numGames < 1 or req.numGames > 10000:
+        raise HTTPException(400, "numGames must be 1-10000")
+    if req.threads < 1 or req.threads > 16:
+        raise HTTPException(400, "threads must be 1-16")
+
+    if not os.path.exists(CFG.forge_jar):
+        raise HTTPException(500, f"Forge JAR not found: {CFG.forge_jar}")
+    if not os.path.isdir(CFG.forge_dir):
+        raise HTTPException(500, f"Forge dir not found: {CFG.forge_dir}")
+
+    batch_id = str(uuid.uuid4())[:12]
+    state = BatchState(batch_id, req.numGames, req.threads)
+    active_batches[batch_id] = state
+
+    os.makedirs(CFG.results_dir, exist_ok=True)
+    output_path = os.path.join(CFG.results_dir, f"batch-{batch_id}.json")
+    state.result_path = output_path
+
+      # Auto-export deckbuilder decks to .dck if not already exported
+    resolved_decks = []
+    for deck_name in req.decks:
+      dck_path = os.path.join(CFG.forge_decks_dir, deck_name + ".dck")
+      if os.path.exists(dck_path):
+        resolved_decks.append(deck_name)
+      else:
+        # Check if it's a deckbuilder deck and auto-export
+        try:
+          conn = _get_db_conn()
+          row = conn.execute(
+            "SELECT id FROM decks WHERE name = ? LIMIT 1", (deck_name,)
+          ).fetchone()
+          if row:
+            from routes.deckbuilder import export_deck_to_sim
+            result = await export_deck_to_sim(row["id"])
+            resolved_decks.append(result["deckName"])
+            log.info(f"Auto-exported deckbuilder deck '{deck_name}' to .dck")
+          else:
+            resolved_decks.append(deck_name)
+        except Exception as e:
+          log.warning(f"Failed to auto-export deck '{deck_name}': {e}")
+          resolved_decks.append(deck_name)
+
+    background_tasks.add_task(
+        run_batch_subprocess,
+        state,
+        resolved_decks,
+        req.numGames,
+        req.threads,
+        req.seed,
+        req.clock,
+        output_path,
+        req.useLearnedPolicy,
+        req.policyStyle,
+        req.policyGreedy,
+        req.aiSimplified,
+        req.aiThinkTimeMs,
+        req.maxQueueDepth,
+    )
+
+    policy_msg = ""
+    if req.useLearnedPolicy:
+        policy_msg = f" [Learned Policy: {req.policyStyle}]"
+    return StartResponse(
+        batchId=batch_id,
+        status="started",
+        message=f"Running {req.numGames} games with {req.threads} threads{policy_msg}",
+    )
+
+
+@router.get("/api/lab/status", response_model=StatusResponse)
+async def get_status(batchId: Optional[str] = None):
+    # If no batchId given, find the most recent active (or last) batch
+    state = None
+    if batchId:
+        state = active_batches.get(batchId)
+    else:
+        # Return the most recently active batch, or any batch
+        for s in active_batches.values():
+            if s.running:
+                state = s
+                break
+        if state is None and active_batches:
+            state = list(active_batches.values())[-1]
+    if not state:
+        return StatusResponse(
+            batchId="", running=False, completed=0, total=0,
+            threads=0, elapsedMs=0, error=None, simsPerSec=0.0,
+            run_id="", games_completed=0, total_games=0, current_decks=[],
+        )
+    elapsed = int((datetime.now() - state.start_time).total_seconds() * 1000)
+    deck_names = getattr(state, 'deck_names', []) if hasattr(state, 'deck_names') else []
+    return StatusResponse(
+        batchId=state.batch_id,
+        running=state.running,
+        completed=state.completed_games,
+        total=state.total_games,
+        threads=state.threads,
+        elapsedMs=elapsed if state.running else state.elapsed_ms,
+        error=state.error,
+        simsPerSec=state.sims_per_sec,
+        # React SPA fields
+        run_id=state.batch_id,
+        games_completed=state.completed_games,
+        total_games=state.total_games,
+        current_decks=deck_names,
+    )
+
+
+@router.get("/api/lab/result")
+async def get_result(batchId: Optional[str] = None):
+    state = None
+    if batchId:
+        state = active_batches.get(batchId)
+    else:
+        # Find most recent completed batch
+        for s in reversed(list(active_batches.values())):
+            if not s.running and s.result_path:
+                state = s
+                break
+    if not state:
+        raise HTTPException(404, "No batch result available")
+    if state.running:
+        raise HTTPException(409, "Batch still running")
+    if state.error:
+        raise HTTPException(500, state.error)
+    if not state.result_path or not os.path.exists(state.result_path):
+        raise HTTPException(500, "Result file not found")
+    try:
+        with open(state.result_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        raise HTTPException(500, f"Failed to read result file: {e}")
+    data = _sanitize_floats(data)
+    return JSONResponse(content=data)
+
+
+@router.get("/api/lab/decks")
+async def list_decks():
+    decks = []
+    seen_names = set()
+
+    # 1. Forge .dck files from decks directory
+    decks_dir = CFG.forge_decks_dir
+    if decks_dir and os.path.isdir(decks_dir):
+        for f in sorted(Path(decks_dir).glob("*.dck")):
+            deck_name = f.stem
+            decks.append({"name": deck_name, "filename": f.name, "source": "forge"})
+            seen_names.add(deck_name.lower())
+
+    # 2. Decks from the Deck Builder database
+    try:
+        conn = _get_db_conn()
+        rows = conn.execute(
+            "SELECT id, name, commander_name FROM decks ORDER BY id DESC"
+        ).fetchall()
+        for row in rows:
+            db_name = row["name"]
+            if db_name.lower() not in seen_names:
+                decks.append({
+                    "name": db_name,
+                    "filename": "",
+                    "source": "deckbuilder",
+                    "deck_id": row["id"],
+                    "commander": row["commander_name"] or "",
+                })
+                seen_names.add(db_name.lower())
+    except Exception as e:
+        log.warning(f"  WARNING: Failed to load DB decks for /api/lab/decks: {e}")
+
+    return {"decks": decks}
+
+
+@router.get("/api/lab/history")
+async def list_history():
+    results_dir = Path(CFG.results_dir)
+    if not results_dir.exists():
+        return {"results": []}
+    results = []
+    for f in sorted(results_dir.glob("batch-*.json"), reverse=True):
+        try:
+            with open(f, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+            meta = data.get("metadata", {})
+            decks = data.get("decks", [])
+            results.append({
+                "filename": f.name,
+                "batchId": meta.get("batchId", ""),
+                "timestamp": meta.get("timestamp", ""),
+                "totalGames": meta.get("completedGames", 0),
+                "threads": meta.get("threads", 1),
+                "elapsedMs": meta.get("elapsedMs", 0),
+                "decks": [{"name": d.get("deckName", ""), "source": d.get("source", "")} for d in decks],
+            })
+        except Exception:
+            continue
+    return {"results": results[:50]}
+
+
+# ════════════════════════════════════════════════════════════
+# 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,
+    },
+}
+
+@router.get("/api/lab/profiles")
+async def list_profiles():
+    return {"profiles": list(AI_PROFILES.values())}
+
+@router.get("/api/lab/profiles/{name}")
+async def get_profile(name: str):
+    profile = AI_PROFILES.get(name.lower())
+    if not profile:
+        raise HTTPException(404, f"Profile '{name}' not found. Available: {list(AI_PROFILES.keys())}")
+    return profile
+
+
+@router.get("/api/lab/analytics/{deck_name}")
+async def analyze_deck(deck_name: str):
+    decks_dir = CFG.forge_decks_dir
+    if not decks_dir or not os.path.isdir(decks_dir):
+        raise HTTPException(500, f"Decks directory not found: {decks_dir}")
+    deck_path = os.path.join(decks_dir, deck_name + ".dck")
+    if not os.path.exists(deck_path):
+        for f in os.listdir(decks_dir):
+            if f.lower() == deck_name.lower() + ".dck":
+                deck_path = os.path.join(decks_dir, f)
+                break
+        else:
+            raise HTTPException(404, f"Deck not found: {deck_name}")
+    try:
+        analysis = parse_dck_file(deck_path)
+        return analysis
+    except Exception as e:
+        raise HTTPException(500, f"Analysis failed: {str(e)}")
+
+
+def parse_dck_file(deck_path: str) -> dict:
+    cards = []
+    commander = None
+    section = "Main"
+    deck_name = Path(deck_path).stem
+    with open(deck_path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("//"):
+                continue
+            if line.startswith("[") and line.endswith("]"):
+                section = line[1:-1]
+                continue
+            if line.startswith("Name="):
+                deck_name = line[5:].strip()
+                continue
+            m = re.match(r"^(\d+)\s+(.+?)(?:\|(.+))?$", line)
+            if m:
+                qty = int(m.group(1))
+                name = m.group(2).strip()
+                set_code = m.group(3).strip() if m.group(3) else ""
+                cards.append({
+                    "quantity": qty, "name": name, "set": set_code,
+                    "section": section,
+                    "is_commander": 1 if section == "Commander" else 0,
+                })
+                if section == "Commander":
+                    commander = name
+    total = sum(c["quantity"] for c in cards)
+    return {
+        "deckName": deck_name,
+        "commanderName": commander,
+        "totalCards": total,
+        "cardCount": len(cards),
+        "cards": cards[:200],
+    }
+
+
+@router.get("/api/lab/trends/{deck_name}")
+async def get_deck_trends(deck_name: str):
+    results_dir = Path(CFG.results_dir)
+    if not results_dir.exists():
+        return {"deckName": deck_name, "history": []}
+    history = []
+    for f in sorted(results_dir.glob("batch-*.json")):
+        try:
+            with open(f, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+            summary = data.get("summary", {})
+            meta = data.get("metadata", {})
+            per_deck = summary.get("perDeck", [])
+            for ds in per_deck:
+                if ds.get("deckName", "").lower() == deck_name.lower():
+                    history.append({
+                        "batchId": meta.get("batchId"),
+                        "timestamp": meta.get("timestamp"),
+                        "winRate": ds.get("winRate", 0),
+                        "wins": ds.get("wins", 0),
+                        "losses": ds.get("losses", 0),
+                        "draws": ds.get("draws", 0),
+                        "totalGames": meta.get("completedGames", 0),
+                    })
+                    break
+        except Exception:
+            continue
+    return {"deckName": deck_name, "history": history}
+
+
+@router.get("/api/lab/log")
+async def get_log(batchId: str):
+    state = active_batches.get(batchId)
+    if not state:
+        raise HTTPException(404, f"Batch {batchId} not found")
+    return {"lines": state.log_lines[-200:]}
+
+
+@router.get("/api/lab/debug-log")
+async def get_debug_log():
+    """Return the raw Forge subprocess debug log for diagnosing simulation issues."""
+    # Check multiple possible locations for the debug log
+    candidates = []
+    if CFG.forge_dir:
+        candidates.append(Path(CFG.forge_dir).parent / "forge-sim-debug.log")
+        candidates.append(Path(CFG.forge_dir) / "forge-sim-debug.log")
+    candidates.append(Path("forge-sim-debug.log"))
+
+    for log_path in candidates:
+        if log_path.exists():
+            text = log_path.read_text(encoding="utf-8", errors="replace")
+            # Return last 50KB to avoid huge responses
+            if len(text) > 50000:
+                text = "... (truncated) ...\n" + text[-50000:]
+            return {"path": str(log_path), "content": text}
+
+    return {"path": None, "content": "No debug log found. Run a simulation first."}
+
+
+
+@router.post('/api/lab/start-deepseek')
+async def start_batch_deepseek(request: FastAPIRequest, background_tasks: BackgroundTasks):
+    """Start a batch simulation using the Python sim engine + DeepSeek LLM opponent."""
+    body = await request.json()
+    decks = body.get('decks', [])
+    num_games = body.get('numGames', 30)
+    # Note: threads not applicable for Python sim (single-threaded LLM calls)
+
+    if not decks or len(decks) < 1:
+        raise HTTPException(400, 'At least 1 deck required')
+    if num_games < 1 or num_games > 500:
+        raise HTTPException(400, 'numGames must be 1-500')
+
+    # Filter empty deck slots
+    decks = [d for d in decks if d]
+    if not decks:
+        raise HTTPException(400, 'No valid decks provided')
+
+    batch_id = str(uuid.uuid4())[:12]
+    state = BatchState(batch_id, num_games, 1)
+    active_batches[batch_id] = state
+
+    os.makedirs(CFG.results_dir, exist_ok=True)
+    output_path = os.path.join(CFG.results_dir, f'batch-{batch_id}.json')
+    state.result_path = output_path
+
+    # Use threading instead of BackgroundTasks to avoid async issues with DB
+    t = threading.Thread(
+        target=_run_deepseek_batch_thread,
+        args=(state, decks, num_games, output_path),
+        daemon=True,
+    )
+    t.start()
+
+    return JSONResponse({
+        'batchId': batch_id,
+        'status': 'started',
+        'message': f'Running {num_games} games across {len(decks)} decks with DeepSeek AI',
+        'engine': 'deepseek',
+    })
+
+

routes/precon.py

@@ -0,0 +1,96 @@
+"""
+routes/precon.py
+================
+Precon deck management endpoints:
+  GET  /api/lab/precons
+  POST /api/lab/precons/install
+  POST /api/lab/precons/install-batch
+  POST /api/lab/precons/refresh
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+
+import routes.shared as _shared                    # module reference, not value import
+from routes.shared import CFG, download_precon_database, log
+from services.precon_service import _get_precon_dir
+
+router = APIRouter(tags=["precon"])
+
+
+@router.get("/api/lab/precons")
+async def list_precons():
+    """List all available precon decks."""
+    return {"precons": _shared.PRECON_INDEX}        # reads current value every call
+
+
+@router.post("/api/lab/precons/install")
+async def install_precon(req: dict):
+    """Install a precon deck to the Forge decks directory.
+    Body: {"fileName": "Elven_Empire.dck"} or {"name": "Elven_Empire.dck"}
+    """
+    file_name = req.get("fileName", "") or req.get("name", "")
+    if not file_name:
+        raise HTTPException(400, "fileName is required")
+
+    src = _get_precon_dir() / file_name
+    if not src.exists():
+        raise HTTPException(404, f"Precon not found: {file_name}")
+
+    decks_dir = CFG.forge_decks_dir
+    if not decks_dir or not os.path.isdir(decks_dir):
+        raise HTTPException(500, f"Forge decks directory not found: {decks_dir}")
+
+    dst = Path(decks_dir) / file_name
+    shutil.copy2(str(src), str(dst))
+
+    deck_name = file_name.replace(".dck", "")
+    return {
+        "installed": True,
+        "deckName": deck_name,
+        "destination": str(dst),
+        "message": f"Installed {deck_name} to Forge decks",
+    }
+
+
+@router.post("/api/lab/precons/install-batch")
+async def install_precons_batch(req: dict):
+    """Install multiple precon decks at once.
+    Body: {"fileNames": ["Elven_Empire.dck", ...]} or {"names": ["Elven_Empire.dck", ...]}
+    """
+    file_names = req.get("fileNames", []) or req.get("names", [])
+    if not file_names:
+        raise HTTPException(400, "fileNames list is required")
+
+    decks_dir = CFG.forge_decks_dir
+    if not decks_dir or not os.path.isdir(decks_dir):
+        raise HTTPException(500, f"Forge decks directory not found: {decks_dir}")
+
+    results = []
+    for file_name in file_names:
+        src = _get_precon_dir() / file_name
+        if not src.exists():
+            results.append({"fileName": file_name, "installed": False, "error": "not found"})
+            continue
+        dst = Path(decks_dir) / file_name
+        shutil.copy2(str(src), str(dst))
+        deck_name = file_name.replace(".dck", "")
+        results.append({"fileName": file_name, "installed": True, "deckName": deck_name})
+
+    return {"results": results}
+
+
+@router.post("/api/lab/precons/refresh")
+async def refresh_precons():
+    """Force re-download of all Commander precon decks from GitHub."""
+    result = download_precon_database(force=True)
+    if result.get("error"):
+        raise HTTPException(502, result["error"])
+    return {
+        "message": f"Downloaded {result['downloaded']} Commander precon decks",
+        "total": result.get("total", 0),
+    }

routes/scanner.py

@@ -0,0 +1,481 @@
+"""
+routes/scanner.py
+=================
+Card scanner & collection enrichment endpoints:
+  POST /api/collection/scan
+  POST /api/collection/scan/add
+  POST /api/collection/re-enrich
+  POST /api/collection/auto-classify
+  POST /api/collection/auto-classify-all
+  GET  /api/collection/{cardId}/edhrec
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from pathlib import Path
+from urllib.request import urlopen, Request
+from urllib.error import URLError
+
+from fastapi import APIRouter, HTTPException
+from fastapi import Request as FastAPIRequest
+
+from routes.shared import (
+    CFG, log_scan, log_deckgen,
+    _get_db_conn, _row_to_dict, _enrich_from_scryfall,
+    _scryfall_fuzzy_lookup, _detect_card_roles,
+    _to_edhrec_slug, _API_HEADERS,
+    _edhrec_cache_get, _edhrec_cache_set,
+)
+
+router = APIRouter(tags=["scanner"])
+
+
+@router.post("/api/collection/scan")
+async def scan_card_image(request: FastAPIRequest):
+    """
+    Scan a card image and return recognized card name(s).
+
+    Uses Ximilar Visual AI for card recognition.
+
+    Accepts multipart/form-data with:
+      - file: image file (JPEG/PNG)
+      - mode: "single" (default) or "multi"
+
+    Returns:
+      { "results": [ { raw_ocr, matched_name, set_code, scryfall_id, confidence, image_uri, error, collector_number, rarity, tcgplayer_url }, ... ] }
+    """
+    try:
+        from scanner.pipeline import scan_single, scan_multi
+    except ImportError as e:
+        raise HTTPException(500, f"Scanner module not available: {e}")
+
+    # Try CFG first, then fall back to env var
+    api_key = CFG.ximilar_api_key or os.environ.get("XIMILAR_API_KEY", "")
+    if not api_key:
+        raise HTTPException(500, "Card scanner not configured. Start the server with --ximilar-key YOUR_KEY or set XIMILAR_API_KEY env var.")
+
+    # Parse multipart form
+    form = await request.form()
+    upload = form.get("file")
+    if upload is None:
+        raise HTTPException(400, "No file uploaded. Send an image as 'file' in multipart/form-data.")
+
+    mode = str(form.get("mode", "single")).lower()
+    image_bytes = await upload.read()
+
+    if len(image_bytes) == 0:
+        raise HTTPException(400, "Uploaded file is empty")
+
+    # Limit file size (20 MB)
+    if len(image_bytes) > 20 * 1024 * 1024:
+        raise HTTPException(400, "Image file too large (max 20 MB)")
+
+    log_scan.info(f"  Processing {len(image_bytes)} bytes, mode={mode} (Ximilar AI)")
+
+    if mode == "multi":
+        results = scan_multi(image_bytes, _scryfall_fuzzy_lookup, ximilar_api_key=api_key)
+    else:
+        result = scan_single(image_bytes, _scryfall_fuzzy_lookup, ximilar_api_key=api_key)
+        results = [result]
+
+    return {
+        "results": [r.to_dict() for r in results]
+    }
+
+
+@router.post("/api/collection/scan/add")
+async def scan_add_cards(body: dict):
+    """
+    Add scanned cards to the collection.
+
+    Body:
+      {
+        "cards": [
+          { "name": "Lightning Bolt", "set_code": "m11", "quantity": 1 },
+          ...
+        ]
+      }
+    """
+    cards = body.get("cards", [])
+    if not cards:
+        raise HTTPException(400, "No cards provided")
+
+    conn = _get_db_conn()
+    imported = 0
+    updated = 0
+    errors = []
+
+    for card_req in cards:
+        name = str(card_req.get("name", "")).strip()
+        if not name:
+            continue
+
+        quantity = int(card_req.get("quantity", 1))
+        set_code = str(card_req.get("set_code", "")).lower()
+        collector_number = str(card_req.get("collector_number", ""))
+        finish = "NORMAL"
+
+        try:
+            enriched = _enrich_from_scryfall(name, set_code, collector_number)
+        except Exception as e:
+            errors.append(f"Scryfall error for '{name}': {e}")
+            continue
+
+        if not enriched or "_error" in enriched:
+            err_msg = enriched.get("_error", f"Not found: '{name}'") if enriched else f"Not found: '{name}'"
+            errors.append(err_msg)
+            continue
+
+        resolved_name = enriched.get("name", name)
+
+        # Check for existing entry
+        existing = conn.execute(
+            """SELECT id, quantity FROM collection_entries
+               WHERE name = ? AND set_code = ? AND collector_number = ? AND finish = ?""",
+            (resolved_name, set_code, collector_number, finish),
+        ).fetchone()
+
+        if existing:
+            new_qty = existing["quantity"] + quantity
+            conn.execute(
+                "UPDATE collection_entries SET quantity = ?, updated_at = datetime('now') WHERE id = ?",
+                (new_qty, existing["id"]),
+            )
+            conn.commit()
+            updated += 1
+        else:
+            conn.execute(
+                """INSERT INTO collection_entries
+                   (name, type_line, subtypes, is_legendary, is_basic, color_identity,
+                    cmc, mana_cost, oracle_text, keywords,
+                    power, toughness, rarity, set_name, edhrec_rank,
+                    tcg_price, salt_score, is_game_changer,
+                    category, scryfall_id, tcgplayer_id,
+                    quantity, finish, condition, language, notes, tags,
+                    set_code, collector_number)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                (
+                    resolved_name,
+                    enriched.get("type_line", ""),
+                    enriched.get("subtypes", "[]"),
+                    enriched.get("is_legendary", 0),
+                    enriched.get("is_basic", 0),
+                    enriched.get("color_identity", "[]"),
+                    enriched.get("cmc", 0.0),
+                    enriched.get("mana_cost", ""),
+                    enriched.get("oracle_text", ""),
+                    enriched.get("keywords", "[]"),
+                    enriched.get("power", ""),
+                    enriched.get("toughness", ""),
+                    enriched.get("rarity", ""),
+                    enriched.get("set_name", ""),
+                    enriched.get("edhrec_rank", 0),
+                    enriched.get("tcg_price", 0.0),
+                    enriched.get("salt_score", 0.0),
+                    enriched.get("is_game_changer", 0),
+                    enriched.get("category", "[]"),
+                    enriched.get("scryfall_id", ""),
+                    enriched.get("tcgplayer_id", ""),
+                    quantity,
+                    finish,
+                    "",  # condition
+                    "",  # language
+                    "",  # notes
+                    "",  # tags
+                    set_code,
+                    collector_number,
+                ),
+            )
+            conn.commit()
+            imported += 1
+
+    return {
+        "importedCount": imported,
+        "updatedCount": updated,
+        "failedCount": len(errors),
+        "errors": errors,
+    }
+
+
+# ══════════════════════════════════════════════════════════════
+# Re-enrich Collection from Scryfall
+# ══════════════════════════════════════════════════════════════
+
+@router.post("/api/collection/re-enrich")
+async def re_enrich_collection():
+    """
+    Re-fetch Scryfall data for all collection entries to backfill
+    missing fields (mana_cost, power, toughness, rarity, set_name, edhrec_rank).
+    Also refreshes: type_line, oracle_text, keywords, cmc, color_identity, prices.
+    Runs synchronously — may take a while for large collections.
+    """
+    conn = _get_db_conn()
+    rows = conn.execute(
+        "SELECT id, name, set_code, collector_number FROM collection_entries ORDER BY id"
+    ).fetchall()
+
+    total = len(rows)
+    enriched_count = 0
+    skipped_count = 0
+    errors = []
+
+    for row in rows:
+        card_id = row["id"]
+        name = row["name"]
+        set_code = row["set_code"] or ""
+        collector_number = row["collector_number"] or ""
+
+        try:
+            data = _enrich_from_scryfall(name, set_code, collector_number)
+        except Exception as e:
+            errors.append(f"Error for '{name}': {e}")
+            skipped_count += 1
+            continue
+
+        if not data or "_error" in data:
+            err_msg = data.get("_error", f"Not found: '{name}'") if data else f"Not found: '{name}'"
+            errors.append(err_msg)
+            skipped_count += 1
+            continue
+
+        conn.execute(
+            """UPDATE collection_entries SET
+                type_line = ?, subtypes = ?, is_legendary = ?, is_basic = ?,
+                color_identity = ?, cmc = ?, mana_cost = ?,
+                oracle_text = ?, keywords = ?,
+                power = ?, toughness = ?,
+                rarity = ?, set_name = ?, edhrec_rank = ?,
+                tcg_price = ?, scryfall_id = ?, tcgplayer_id = ?,
+                category = ?,
+                updated_at = datetime('now')
+            WHERE id = ?""",
+            (
+                data.get("type_line", ""),
+                data.get("subtypes", "[]"),
+                data.get("is_legendary", 0),
+                data.get("is_basic", 0),
+                data.get("color_identity", "[]"),
+                data.get("cmc", 0.0),
+                data.get("mana_cost", ""),
+                data.get("oracle_text", ""),
+                data.get("keywords", "[]"),
+                data.get("power", ""),
+                data.get("toughness", ""),
+                data.get("rarity", ""),
+                data.get("set_name", ""),
+                data.get("edhrec_rank", 0),
+                data.get("tcg_price", 0.0),
+                data.get("scryfall_id", ""),
+                data.get("tcgplayer_id", ""),
+                data.get("category", "[]"),
+                card_id,
+            ),
+        )
+        conn.commit()
+        enriched_count += 1
+
+    return {
+        "total": total,
+        "enrichedCount": enriched_count,
+        "skippedCount": skipped_count,
+        "errors": errors[:50],  # cap error list
+    }
+
+
+# ══════════════════════════════════════════════════════════════
+# Auto-Classify Collection
+# ══════════════════════════════════════════════════════════════
+
+@router.post("/api/collection/auto-classify")
+async def auto_classify_collection():
+    """
+    Run auto-classification on all collection entries.
+    Uses oracle_text, type_line, and keywords to detect functional roles
+    (Ramp, Draw, Removal, Board Wipe, Anthem, Stax, etc.).
+    Only updates cards whose current category is empty or '[]'.
+    """
+    conn = _get_db_conn()
+    rows = conn.execute(
+        "SELECT id, oracle_text, type_line, keywords, category FROM collection_entries ORDER BY id"
+    ).fetchall()
+
+    total = len(rows)
+    classified_count = 0
+    skipped_count = 0
+
+    for row in rows:
+        card_id = row["id"]
+        existing_cats = row["category"] or "[]"
+
+        # Parse existing categories
+        try:
+            cats = json.loads(existing_cats)
+        except Exception:
+            cats = []
+
+        # Skip cards that already have manually-set categories
+        if cats:
+            skipped_count += 1
+            continue
+
+        oracle_text = row["oracle_text"] or ""
+        type_line = row["type_line"] or ""
+        keywords = row["keywords"] or "[]"
+
+        roles = _detect_card_roles(oracle_text, type_line, keywords)
+
+        if roles:
+            conn.execute(
+                "UPDATE collection_entries SET category = ?, updated_at = datetime('now') WHERE id = ?",
+                (json.dumps(roles), card_id),
+            )
+            classified_count += 1
+
+    conn.commit()
+
+    return {
+        "total": total,
+        "classifiedCount": classified_count,
+        "skippedCount": skipped_count,
+        "message": f"Classified {classified_count} cards, skipped {skipped_count} (already had categories)",
+    }
+
+
+@router.post("/api/collection/auto-classify-all")
+async def auto_classify_all_collection():
+    """
+    Force re-classify ALL collection entries, overwriting existing categories.
+    """
+    conn = _get_db_conn()
+    rows = conn.execute(
+        "SELECT id, oracle_text, type_line, keywords FROM collection_entries ORDER BY id"
+    ).fetchall()
+
+    total = len(rows)
+    classified_count = 0
+
+    for row in rows:
+        card_id = row["id"]
+        oracle_text = row["oracle_text"] or ""
+        type_line = row["type_line"] or ""
+        keywords = row["keywords"] or "[]"
+
+        roles = _detect_card_roles(oracle_text, type_line, keywords)
+        conn.execute(
+            "UPDATE collection_entries SET category = ?, updated_at = datetime('now') WHERE id = ?",
+            (json.dumps(roles), card_id),
+        )
+        classified_count += 1
+
+    conn.commit()
+
+    return {
+        "total": total,
+        "classifiedCount": classified_count,
+        "message": f"Re-classified all {classified_count} cards",
+    }
+
+
+# ══════════════════════════════════════════════════════════════
+# EDHREC Recommendations Cache + Endpoint
+# ══════════════════════════════════════════════════════════════
+
+@router.get("/api/collection/{cardId}/edhrec")
+async def get_card_edhrec(cardId: int):
+    """
+    Get EDHREC recommendations for a collection card.
+    For legendary creatures (potential commanders): fetch commander synergy data.
+    For other cards: fetch 'also played with' data.
+    """
+    conn = _get_db_conn()
+    row = conn.execute("SELECT * FROM collection_entries WHERE id = ?", (cardId,)).fetchone()
+    if not row:
+        raise HTTPException(404, f"Card with id {cardId} not found")
+
+    card = _row_to_dict(row)
+    name = card["name"]
+    type_line = card.get("type_line", "")
+    is_legendary = card.get("is_legendary", 0)
+
+    # Determine if it's a legendary creature (potential commander)
+    is_commander = bool(
+        is_legendary and
+        re.search(r"\bCreature\b", type_line, re.IGNORECASE)
+    )
+
+    slug = _to_edhrec_slug(name)
+    cache_key = f"edhrec:{'cmd' if is_commander else 'card'}:{slug}"
+
+    cached = _edhrec_cache_get(cache_key)
+    if cached:
+        return cached
+
+    recommendations = []
+    links = {
+        "edhrecPage": (
+            f"https://edhrec.com/commanders/{slug}"
+            if is_commander
+            else f"https://edhrec.com/cards/{slug}"
+        ),
+        "archidektSearch": f"https://archidekt.com/search/cards?q={name.replace(' ', '+')}",
+        "moxfieldSearch": f"https://www.moxfield.com/search?q={name.replace(' ', '+')}",
+    }
+
+    try:
+        if is_commander:
+            url = f"https://json.edhrec.com/pages/commanders/{slug}.json"
+        else:
+            url = f"https://json.edhrec.com/pages/cards/{slug}.json"
+
+        req = Request(url, headers=_API_HEADERS)
+        with urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+
+        if is_commander:
+            # Extract top cards from cardlists
+            container = data.get("container", {})
+            json_dict = container.get("json_dict", {})
+            for cardlist in json_dict.get("cardlists", []):
+                tag = cardlist.get("tag", "")
+                for cv in cardlist.get("cardviews", [])[:10]:
+                    rec_name = cv.get("name", "")
+                    if not rec_name:
+                        continue
+                    synergy = cv.get("synergy", 0.0)
+                    recommendations.append({
+                        "name": rec_name,
+                        "synergy": synergy,
+                        "role": tag or "Recommended",
+                    })
+        else:
+            # Extract "also played with" cards
+            container = data.get("container", {})
+            json_dict = container.get("json_dict", {})
+            for cardlist in json_dict.get("cardlists", []):
+                tag = cardlist.get("tag", "")
+                for cv in cardlist.get("cardviews", [])[:10]:
+                    rec_name = cv.get("name", "")
+                    if not rec_name:
+                        continue
+                    synergy = cv.get("synergy", 0.0)
+                    recommendations.append({
+                        "name": rec_name,
+                        "synergy": synergy,
+                        "role": tag or "Also Played With",
+                    })
+
+    except Exception as e:
+        log_deckgen.error(f"  Error fetching data for '{name}': {e}")
+        # Graceful degradation — return empty results
+
+    result = {
+        "recommendations": recommendations[:30],
+        "links": links,
+    }
+    _edhrec_cache_set(cache_key, result)
+    return result
+
+

routes/shared.py

@@ -0,0 +1,204 @@
+"""
+routes/shared.py
+================
+Single source of truth for everything every router needs.
+
+Contains:
+  - Config class + CFG singleton
+  - Logging setup + all named loggers
+  - FastAPI app instance
+  - In-memory state (active_batches, COMMANDER_META, PRECON_INDEX, AI_PROFILES)
+  - All Pydantic request/response models
+  - SQLite DB helpers (_get_db_conn, init_collection_db)
+  - Scryfall cache + enrichment helpers
+  - Collection helpers (_detect_card_roles, _classify_card_type,
+      _build_collection_filters, _parse_finish, _parse_csv_content,
+      _parse_text_line, _auto_infer_mapping, _row_to_dict, _add_image_url,
+      _snake_to_camel, VALID_SORT_FIELDS, _JSON_FIELDS)
+  - Deck helpers (_get_deck_or_404, _compute_deck_analysis, _check_ratio_limit,
+      _TYPE_TARGETS, _TYPE_PRIORITY, _classify_card_type)
+  - Import helpers (_import_from_url, _fetch_archidekt_deck,
+      _fetch_edhrec_average, _parse_text_decklist, _save_profile_to_dck,
+      _to_edhrec_slug, _http_get, _API_HEADERS, _edhrec_cache_get,
+      _edhrec_cache_set)
+  - Precon helpers (PRECON_DIR, PRECON_INDEX, download_precon_database,
+      load_precon_index, GITHUB_PRECON_URL, PRECON_CACHE_HOURS)
+  - Sim helpers (build_java_command, get_java17, BatchState, parse_dck_file,
+      AI_PROFILES, run_batch_subprocess, _run_process_blocking,
+      _run_deepseek_batch_thread, _load_deck_cards_by_name, _get_deepseek_brain)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import csv
+import io
+import json
+import logging
+import logging.handlers
+import os
+import re
+import sqlite3
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from collections import Counter
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from urllib.request import urlopen, Request
+from urllib.error import URLError
+
+try:
+    from fastapi import FastAPI, HTTPException, BackgroundTasks, Request as FastAPIRequest
+    from fastapi.middleware.cors import CORSMiddleware
+    from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
+    from fastapi.staticfiles import StaticFiles
+    from pydantic import BaseModel
+except ImportError:
+    print("ERROR: FastAPI not installed. Run: pip install fastapi uvicorn")
+    sys.exit(1)
+
+
+# ══════════════════════════════════════════════════════════════
+# Configuration
+# ══════════════════════════════════════════════════════════════
+
+# Configuration (imported from models/state)
+from models.state import Config, CFG
+
+
+# ══════════════════════════════════════════════════════════════
+# Logging Setup
+# ══════════════════════════════════════════════════════════════
+
+_LOG_FORMAT = "%(asctime)s %(levelname)-5s [%(name)s] %(message)s"
+_LOG_DATE_FMT = "%Y-%m-%d %H:%M:%S"
+_LOG_DIR = Path(os.environ.get("CAL_LOG_DIR", "logs"))
+_LOG_MAX_BYTES = int(os.environ.get("CAL_LOG_MAX_MB", "25")) * 1024 * 1024
+_LOG_BACKUP_COUNT = int(os.environ.get("CAL_LOG_BACKUP_COUNT", "5"))
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    _LOG_DIR.mkdir(parents=True, exist_ok=True)
+    root_logger = logging.getLogger("commander_ai_lab")
+    root_logger.setLevel(level)
+    if root_logger.handlers:
+        return
+    formatter = logging.Formatter(_LOG_FORMAT, datefmt=_LOG_DATE_FMT)
+    console = logging.StreamHandler(sys.stdout)
+    console.setLevel(level)
+    console.setFormatter(formatter)
+    root_logger.addHandler(console)
+    file_handler = logging.handlers.RotatingFileHandler(
+        _LOG_DIR / "commander-ai-lab.log",
+        maxBytes=_LOG_MAX_BYTES,
+        backupCount=_LOG_BACKUP_COUNT,
+        encoding="utf-8",
+    )
+    file_handler.setLevel(level)
+    file_handler.setFormatter(formatter)
+    root_logger.addHandler(file_handler)
+
+
+log          = logging.getLogger("commander_ai_lab.api")
+log_batch    = logging.getLogger("commander_ai_lab.batch")
+log_sim      = logging.getLogger("commander_ai_lab.sim")
+log_coach    = logging.getLogger("commander_ai_lab.coach")
+log_deckgen  = logging.getLogger("commander_ai_lab.deckgen")
+log_collect  = logging.getLogger("commander_ai_lab.collection")
+log_scan     = logging.getLogger("commander_ai_lab.scanner")
+log_ml       = logging.getLogger("commander_ai_lab.ml")
+log_cache    = logging.getLogger("commander_ai_lab.cache")
+log_pplx     = logging.getLogger("commander_ai_lab.pplx")
+
+
+# ══════════════════════════════════════════════════════════════
+# In-Memory State
+# ══════════════════════════════════════════════════════════════
+
+# In-Memory State (imported from models/state)
+from models.state import (
+    BatchState, active_batches, COMMANDER_META,
+    BUILTIN_COMMANDERS, load_commander_meta,
+)
+
+
+# Pydantic Models (imported from models/)
+from models.requests import (
+    StartRequest, ImportUrlRequest, ImportTextRequest, MetaFetchRequest,
+    CreateDeckRequest, UpdateDeckRequest, AddDeckCardRequest,
+    PatchDeckCardRequest, BulkAddRequest, BulkAddRecommendedRequest,
+    DeckGenerationSourceConfig, DeckGenerationRequest,
+    DeckGenV3Request, DeckGenV3SubstituteRequest,
+)
+from models.responses import (
+    StartResponse, StatusResponse, DeckInfo, GeneratedDeckCard,
+)
+
+
+# Collection Database (imported from services/database.py)
+from services.database import (
+    COLLECTION_DB_PATH, _get_db_conn, init_collection_db,
+    _JSON_FIELDS, VALID_SORT_FIELDS,
+    _row_to_dict, _snake_to_camel, _add_image_url, _build_collection_filters,
+)
+# Card Role Detection (imported from services/card_analysis.py)
+from services.card_analysis import _detect_card_roles
+
+
+# ══════════════════════════════════════════════════════════════
+# Deck Helpers (imported from services/deck_service.py)
+from services.deck_service import (
+    _TYPE_PRIORITY, _TYPE_TARGETS, _classify_card_type, _get_deck_or_404,
+    _compute_deck_analysis, _check_ratio_limit, _to_edhrec_slug,
+    parse_dck_file, _save_profile_to_dck, _load_deck_cards_by_name,
+)
+
+
+# ══════════════════════════════════════════════════════════════
+# Scryfall Cache (imported from services/scryfall.py)
+from services.scryfall import (
+    SCRYFALL_CACHE_DB_PATH, SCRYFALL_CACHE_TTL_SECONDS, _API_HEADERS,
+    _ScryfallCache, _scryfall_cache, _scryfall_lock, _scryfall_last_call,
+    _scryfall_rate_limit, _fetch_scryfall_api, _enrich_from_scryfall, _scryfall_fuzzy_lookup,
+)
+
+# ══════════════════════════════════════════════════════════════
+# Import Helpers (extracted to services/import_helpers.py)
+from services.import_helpers import (
+    _http_get, _fetch_archidekt_deck, _fetch_edhrec_average,
+    _import_from_url, _parse_text_decklist, _save_profile_to_dck,
+    _edhrec_cache, _EDHREC_CACHE_TTL, _edhrec_cache_get, _edhrec_cache_set,
+)
+
+# ══════════════════════════════════════════════════════════════
+# Collection Import Helpers (extracted to services/import_service.py)
+from services.import_service import (
+    _parse_finish, _parse_text_line, _auto_infer_mapping, _parse_csv_content,
+)
+
+# ══════════════════════════════════════════════════════════════
+# Precon Helpers (extracted to services/precon_service.py)
+from services.precon_service import (
+    PRECON_DIR, PRECON_INDEX, GITHUB_PRECON_URL, PRECON_CACHE_HOURS,
+    load_precon_index, _sanitize_filename, _deck_to_dck, download_precon_database,
+    _get_precon_dir,
+)
+
+# ══════════════════════════════════════════════════════════════
+# AI Profiles (imported from models/state)
+from models.state import AI_PROFILES
+
+# ══════════════════════════════════════════════════════════════
+# Java / Sim Helpers (extracted to services/forge_runner.py)
+from services.forge_runner import (
+    _find_java17, get_java17, build_java_command,
+    run_batch_subprocess, _run_process_blocking,
+    _run_deepseek_batch_thread, _get_deepseek_brain,
+)
+
+_ml_logging_enabled = True

scripts/bench_deckgen.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+scripts/bench_deckgen.py
+========================
+Benchmark for _get_collection_for_colors() and _build_collection_summary().
+
+Seeds an in-memory SQLite DB with randomised collection_entries rows,
+then times the SQL-filtered query for various commander colour identities.
+
+Usage:
+    python scripts/bench_deckgen.py [--rows 1000]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import random
+import sqlite3
+import time
+from typing import List
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+ALL_COLORS = ["W", "U", "B", "R", "G"]
+
+CARD_TYPE_LINES = [
+    "Creature - Human Soldier",
+    "Creature - Elf Druid",
+    "Instant",
+    "Sorcery",
+    "Artifact",
+    "Enchantment",
+    "Land",
+    "Artifact Creature - Golem",
+    "Legendary Creature - Dragon",
+    "Planeswalker - Jace",
+]
+
+
+def _random_color_identity() -> list:
+    """Return a random colour identity (including ~15% chance of colorless)."""
+    if random.random() < 0.15:
+        return []
+    n = random.randint(1, 3)
+    return sorted(random.sample(ALL_COLORS, n))
+
+
+def _seed_db(conn: sqlite3.Connection, num_rows: int):
+    """Create collection_entries table and insert random rows."""
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS collection_entries (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            type_line TEXT DEFAULT '',
+            color_identity TEXT DEFAULT '[]',
+            cmc REAL DEFAULT 0,
+            mana_cost TEXT DEFAULT '',
+            oracle_text TEXT DEFAULT '',
+            keywords TEXT DEFAULT '[]',
+            quantity INTEGER DEFAULT 1,
+            edhrec_rank INTEGER DEFAULT 0,
+            scryfall_id TEXT DEFAULT '',
+            tcg_price REAL DEFAULT 0,
+            salt_score REAL DEFAULT 0,
+            is_game_changer INTEGER DEFAULT 0,
+            category TEXT DEFAULT ''
+        )
+    """)
+    conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_ce_quantity
+            ON collection_entries (quantity) WHERE quantity > 0
+    """)
+
+    rows = []
+    for i in range(num_rows):
+        ci = _random_color_identity()
+        qty = random.choice([0, 1, 1, 1, 2, 3])  # ~17% zero quantity
+        rows.append((
+            f"Card_{i:05d}",
+            random.choice(CARD_TYPE_LINES),
+            json.dumps(ci),
+            round(random.uniform(0, 8), 1),
+            "",
+            f"Sample oracle text for card {i}",
+            json.dumps([]),
+            qty,
+            random.randint(1, 20000),
+            f"scryfall-{i:05d}" if random.random() > 0.02 else "",
+            round(random.uniform(0, 50), 2),
+            round(random.uniform(0, 5), 2),
+            1 if random.random() < 0.05 else 0,
+            random.choice(["", "ramp", "draw", "removal", ""]),
+        ))
+
+    conn.executemany("""
+        INSERT INTO collection_entries
+            (name, type_line, color_identity, cmc, mana_cost, oracle_text,
+             keywords, quantity, edhrec_rank, scryfall_id, tcg_price,
+             salt_score, is_game_changer, category)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    """, rows)
+    conn.commit()
+    print(f"  Seeded {num_rows} rows ({sum(1 for r in rows if r[7] > 0)} with qty > 0)")
+
+
+# ── Query under test (same as routes/deckgen.py) ────────────────────────────
+
+def get_collection_for_colors(conn: sqlite3.Connection, color_identity: list) -> list:
+    """Mirrors the new SQL-filtered implementation."""
+    allowed_json = json.dumps([c.upper() for c in color_identity]) if color_identity else '[]'
+
+    rows = conn.execute("""
+        SELECT scryfall_id, name, type_line, mana_cost, cmc,
+               oracle_text, keywords, quantity, edhrec_rank, color_identity
+        FROM collection_entries
+        WHERE quantity > 0
+          AND scryfall_id != ''
+          AND NOT EXISTS (
+              SELECT 1 FROM json_each(
+                  CASE WHEN collection_entries.color_identity IS NULL
+                            OR collection_entries.color_identity = ''
+                       THEN '[]'
+                       ELSE collection_entries.color_identity
+                  END
+              ) AS jc
+              WHERE jc.value NOT IN (
+                  SELECT value FROM json_each(?)
+              )
+          )
+    """, (allowed_json,)).fetchall()
+
+    valid = []
+    for row in rows:
+        card = dict(row)
+        ci = card.get("color_identity", "[]")
+        try:
+            card["color_identity"] = json.loads(ci) if isinstance(ci, str) else ci
+        except Exception:
+            card["color_identity"] = []
+        valid.append(card)
+    return valid
+
+
+def get_collection_for_colors_old(conn: sqlite3.Connection, color_identity: list) -> list:
+    """Old implementation: SELECT * + Python-side filter."""
+    rows = conn.execute(
+        "SELECT * FROM collection_entries WHERE quantity > 0"
+    ).fetchall()
+    valid = []
+    for row in rows:
+        card = dict(row)
+        card_ci = card.get("color_identity", "[]")
+        if isinstance(card_ci, str):
+            try:
+                card_ci = json.loads(card_ci)
+            except Exception:
+                card_ci = []
+        if color_identity and card_ci:
+            if not all(c in color_identity for c in card_ci):
+                continue
+        if not card.get("scryfall_id"):
+            continue
+        card["color_identity"] = card_ci
+        valid.append(card)
+    return valid
+
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+COMMANDERS = [
+    ("Mono-W",    ["W"]),
+    ("WUB",       ["W", "U", "B"]),
+    ("WUBRG",     ["W", "U", "B", "R", "G"]),
+    ("Colorless", []),
+    ("Mono-G",    ["G"]),
+]
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--rows", type=int, default=1000)
+    args = parser.parse_args()
+
+    conn = sqlite3.connect(":memory:")
+    conn.row_factory = sqlite3.Row
+    _seed_db(conn, args.rows)
+
+    print(f"\n{'Commander':<14} {'Old ms':>8} {'New ms':>8} {'Old#':>6} {'New#':>6} {'Match':>6}")
+    print("-" * 60)
+
+    for label, ci in COMMANDERS:
+        # Old
+        t0 = time.perf_counter()
+        old_result = get_collection_for_colors_old(conn, ci)
+        old_ms = (time.perf_counter() - t0) * 1000
+
+        # New
+        t0 = time.perf_counter()
+        new_result = get_collection_for_colors(conn, ci)
+        new_ms = (time.perf_counter() - t0) * 1000
+
+        match = len(old_result) == len(new_result)
+        # NOTE: Colorless ([]) intentionally differs — old code had a bug that
+        # skipped the colour check entirely when color_identity was empty,
+        # returning ALL cards.  The new SQL correctly restricts to colourless.
+        if not ci:  # colorless commander
+            marker = "FIX" if len(new_result) < len(old_result) else "OK"
+        else:
+            marker = "OK" if match else "FAIL"
+        print(f"  {label:<12} {old_ms:>7.2f} {new_ms:>7.2f} {len(old_result):>6} {len(new_result):>6} {marker:>6}")
+
+        if not match and ci:  # only flag non-colorless mismatches
+            old_names = {c["name"] for c in old_result}
+            new_names = {c["name"] for c in new_result}
+            print(f"    Only in old: {len(old_names - new_names)} cards")
+            print(f"    Only in new: {len(new_names - old_names)} cards")
+
+    print()
+
+
+if __name__ == "__main__":
+    main()

scripts/overnight-batch.py

@@ -0,0 +1,275 @@
+"""
+Commander AI Lab — Overnight Batch Sim Runner
+═══════════════════════════════════════════════
+Runs sequential batch simulations across the top precon decks,
+rotating playstyles each batch. Generates ML decision data for
+training.
+
+Usage:
+    python scripts/overnight-batch.py
+    python scripts/overnight-batch.py --hours 8 --games-per-batch 200
+    python scripts/overnight-batch.py --port 8080 --threads 4
+
+Estimated throughput (varies by hardware):
+    ~3-5 sims/sec typical → ~200 games in ~40-70 sec
+    8 hours ≈ 400-600 batches ≈ 80K-120K games ≈ 200K-400K decisions
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+from datetime import datetime, timedelta
+from itertools import combinations
+
+# ── Configuration ────────────────────────────────────────────
+
+PRECON_DECKS = [
+    "Undead_Unleashed.dck",    # Wilhelt — Zombie tribal (UB)
+    "Elven_Empire.dck",         # Lathril — Elf tribal (BG)
+    "Planar_Portal.dck",        # Prosper — Exile/Treasure (BR)
+    "Necron_Dynasties.dck",     # Szarekh — Artifact recursion (B)
+    "Creative_Energy.dck",      # Satya — Energy/Artifacts (WUR)
+    "Veloci-Ramp-Tor.dck",      # Pantlaza — Dinosaur tribal (RGW)
+    "Mutant_Menace.dck",        # Wise Mothman — Rad/Proliferate (UBG)
+    "Scrappy_Survivors.dck",    # Dogmeat — Aura/Equipment (WRG)
+    "Explorers_of_the_Deep.dck", # Hakbal — Merfolk/Explore (UG)
+    "Science.dck",              # Dr. Madison Li — Artifact synergies (WUR)
+]
+
+PLAYSTYLES = ["midrange", "aggro", "control", "combo"]
+
+
+def api_call(base_url, path, method="GET", body=None):
+    """Make an API call to the local server."""
+    url = f"{base_url}{path}"
+    headers = {"Content-Type": "application/json"} if body else {}
+    data = json.dumps(body).encode() if body else None
+
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode() if e.fp else str(e)
+        print(f"  API Error {e.code}: {error_body}")
+        return None
+    except Exception as e:
+        print(f"  Connection error: {e}")
+        return None
+
+
+def ensure_ml_logging(base_url):
+    """Make sure ML logging is enabled."""
+    result = api_call(base_url, "/api/ml/toggle?enable=true", method="POST")
+    if result:
+        print(f"  ML logging: {'enabled' if result.get('ml_logging_enabled') else 'DISABLED'}")
+    return result
+
+
+def start_batch(base_url, decks, num_games, playstyle, threads):
+    """Start a batch simulation."""
+    body = {
+        "decks": decks,
+        "numGames": num_games,
+        "threads": threads,
+        "policyStyle": playstyle,
+        "clock": 6000,
+    }
+    return api_call(base_url, "/api/lab/start", method="POST", body=body)
+
+
+def poll_batch(base_url, batch_id, poll_interval=5):
+    """Poll batch status until complete. Returns final status."""
+    while True:
+        result = api_call(base_url, f"/api/lab/status/{batch_id}")
+        if result is None:
+            time.sleep(poll_interval)
+            continue
+
+        completed = result.get("completedGames", 0)
+        total = result.get("totalGames", 0)
+        running = result.get("running", False)
+        sps = result.get("simsPerSec", 0)
+        error = result.get("error")
+
+        if error:
+            print(f"  ERROR: {error}")
+            return result
+
+        if not running and completed >= total and total > 0:
+            return result
+
+        if not running and total == 0:
+            # Still starting up
+            time.sleep(poll_interval)
+            continue
+
+        pct = (completed / total * 100) if total > 0 else 0
+        speed = f" ({sps:.1f} sims/sec)" if sps > 0 else ""
+        print(f"  Progress: {completed}/{total} ({pct:.0f}%){speed}", end="\r")
+
+        time.sleep(poll_interval)
+
+
+def generate_matchups(decks, pod_size=4):
+    """Generate 4-player pods from deck list, cycling through all combos."""
+    combos = list(combinations(decks, pod_size))
+    return combos
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Commander AI Lab — Overnight Batch Runner"
+    )
+    parser.add_argument(
+        "--hours", type=float, default=8,
+        help="Maximum hours to run (default: 8)",
+    )
+    parser.add_argument(
+        "--games-per-batch", type=int, default=200,
+        help="Games per batch (default: 200)",
+    )
+    parser.add_argument(
+        "--threads", type=int, default=4,
+        help="Simulation threads (default: 4)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=8080,
+        help="Lab server port (default: 8080)",
+    )
+    parser.add_argument(
+        "--pod-size", type=int, default=4, choices=[2, 3, 4],
+        help="Players per pod (default: 4)",
+    )
+
+    args = parser.parse_args()
+    base_url = f"http://localhost:{args.port}"
+
+    print()
+    print("=" * 60)
+    print("  Commander AI Lab — Overnight Batch Runner")
+    print("=" * 60)
+    print(f"  Duration:     {args.hours} hours")
+    print(f"  Games/batch:  {args.games_per_batch}")
+    print(f"  Threads:      {args.threads}")
+    print(f"  Pod size:     {args.pod_size}")
+    print(f"  Decks:        {len(PRECON_DECKS)}")
+    print(f"  Playstyles:   {', '.join(PLAYSTYLES)}")
+    print(f"  Server:       {base_url}")
+    print("=" * 60)
+    print()
+
+    # Check server is up
+    print("Checking server connectivity...")
+    status = api_call(base_url, "/api/ml/status")
+    if status is None:
+        print("ERROR: Cannot reach the lab server. Is it running?")
+        print(f"  Expected at: {base_url}")
+        sys.exit(1)
+    print(f"  Server OK — {status.get('total_decisions', 0):,} existing decisions")
+
+    # Enable ML logging
+    print("Enabling ML logging...")
+    ensure_ml_logging(base_url)
+
+    # Generate matchups
+    matchups = generate_matchups(PRECON_DECKS, args.pod_size)
+    print(f"  Generated {len(matchups)} unique {args.pod_size}-player matchups")
+    print()
+
+    # Calculate stop time
+    stop_time = datetime.now() + timedelta(hours=args.hours)
+    print(f"  Will run until: {stop_time.strftime('%I:%M %p')}")
+    print()
+
+    # ── Main Loop ────────────────────────────────────────────
+    batch_count = 0
+    total_games = 0
+    total_decisions_start = status.get("total_decisions", 0)
+    matchup_idx = 0
+    playstyle_idx = 0
+
+    try:
+        while datetime.now() < stop_time:
+            # Pick next matchup and playstyle
+            matchup = matchups[matchup_idx % len(matchups)]
+            playstyle = PLAYSTYLES[playstyle_idx % len(PLAYSTYLES)]
+
+            deck_names = [os.path.splitext(d)[0].replace("_", " ") for d in matchup]
+            batch_count += 1
+
+            remaining = stop_time - datetime.now()
+            hrs_left = remaining.total_seconds() / 3600
+
+            print(f"─── Batch {batch_count} ({hrs_left:.1f}h remaining) ───")
+            print(f"  Playstyle: {playstyle}")
+            print(f"  Decks: {', '.join(deck_names)}")
+
+            # Start batch
+            result = start_batch(
+                base_url,
+                list(matchup),
+                args.games_per_batch,
+                playstyle,
+                args.threads,
+            )
+
+            if result is None or "batchId" not in result:
+                print("  Failed to start batch — waiting 30s and retrying...")
+                time.sleep(30)
+                continue
+
+            batch_id = result["batchId"]
+            print(f"  Batch ID: {batch_id}")
+
+            # Poll until complete
+            final = poll_batch(base_url, batch_id)
+            print()  # Clear progress line
+
+            if final:
+                games = final.get("completedGames", 0)
+                elapsed_s = final.get("elapsedMs", 0) / 1000
+                total_games += games
+                print(f"  Done: {games} games in {elapsed_s:.0f}s")
+            else:
+                print("  Batch completed (no status)")
+
+            # Rotate
+            matchup_idx += 1
+            playstyle_idx += 1
+
+            # Brief pause between batches
+            time.sleep(2)
+            print()
+
+    except KeyboardInterrupt:
+        print("\n\nStopped by user (Ctrl+C)")
+
+    # ── Summary ──────────────────────────────────────────────
+    # Check final decision count
+    final_status = api_call(base_url, "/api/ml/status")
+    total_decisions_end = final_status.get("total_decisions", 0) if final_status else 0
+    new_decisions = total_decisions_end - total_decisions_start
+
+    print()
+    print("=" * 60)
+    print("  OVERNIGHT BATCH COMPLETE")
+    print("=" * 60)
+    print(f"  Batches run:      {batch_count}")
+    print(f"  Total games:      {total_games:,}")
+    print(f"  New decisions:    {new_decisions:,}")
+    print(f"  Total decisions:  {total_decisions_end:,}")
+    print(f"  Decision files:   {final_status.get('total_files', '?')}")
+    print("=" * 60)
+    print()
+    print("  Next step: Run Closed-Loop Distillation from the Distill tab")
+    print("  to train on this expanded dataset.")
+    print()
+
+
+if __name__ == "__main__":
+    main()

services/__init__.py

@@ -0,0 +1 @@
+"""Services for Commander AI Lab."""

services/card_analysis.py

@@ -0,0 +1,81 @@
+"""Card role detection, type classification, and deck composition analysis."""
+import json
+import re
+
+
+def _detect_card_roles(oracle_text: str, type_line: str, keywords) -> list:
+    roles = []
+    ot = (oracle_text or "").lower()
+    tl = (type_line or "").lower()
+    kw_raw = keywords or []
+    if isinstance(kw_raw, str):
+        try:
+            kw_raw = json.loads(kw_raw)
+        except Exception:
+            kw_raw = []
+    kw = " ".join(str(k).lower() for k in kw_raw)
+
+    if ("add {" in ot or "add one mana" in ot
+            or ("search your library for a" in ot and "land" in ot)
+            or "treasure token" in ot or "add mana" in ot):
+        roles.append("Ramp")
+    if ("draw a card" in ot or "draw cards" in ot or "draws a card" in ot
+            or "draw two cards" in ot or "draw three cards" in ot
+            or re.search(r"draw \d+ cards?", ot)
+            or ("whenever" in ot and "draw" in ot)):
+        roles.append("Draw")
+    if ("destroy target" in ot or "exile target" in ot
+            or re.search(r"deals? \d+ damage to (target|any target)", ot)
+            or re.search(r"deals? x damage to (target|any target)", ot)
+            or "target creature gets -" in ot or "fights target" in ot):
+        roles.append("Removal")
+    if ("destroy all" in ot or "exile all" in ot
+            or re.search(r"all creatures get -\d+/-\d+", ot)
+            or re.search(r"each creature gets -\d+/-\d+", ot)
+            or ("deals" in ot and "to each creature" in ot)):
+        roles.append("Board Wipe")
+    if "search your library" in ot and "land" not in ot:
+        roles.append("Tutor")
+    if ("counter target" in ot or "counter that" in ot
+            or "counters" in kw):
+        roles.append("Counter")
+    if ("create" in ot and ("token" in ot or "tokens" in ot)):
+        roles.append("Token")
+    if ("each creature you control gets" in ot or "creatures you control get" in ot
+            or "all creatures you control" in ot or "anthem" in tl.lower()):
+        roles.append("Anthem")
+    if ("target creature gains" in ot and ("hexproof" in ot or "indestructible" in ot or "shroud" in ot))\
+            or ("protection" in kw):
+        roles.append("Protection")
+    if ("sacrifice" in ot and ("whenever" in ot or "you may" in ot)):
+        roles.append("Sacrifice")
+    if ("return" in ot and ("from your graveyard" in ot and "onto the battlefield" in ot)
+            or ("put" in ot and "from a graveyard" in ot and "onto the battlefield" in ot)):
+        roles.append("Recursion")
+    if (("graveyard" in ot and ("mill" in ot or "put" in ot and "into" in ot and "graveyard" in ot))
+            or "mill" in kw):
+        roles.append("Graveyard")
+    if ("gain" in ot and "life" in ot) or "lifelink" in ot or "lifelink" in kw:
+        roles.append("Lifegain")
+    if (re.search(r"deals? \d+ damage to (each|any|target) (opponent|player)", ot)
+            or "each opponent loses" in ot and "life" in ot
+            or "deals damage to each opponent" in ot):
+        roles.append("Burn")
+    if ("can't cast" in ot or "can't attack" in ot or "can't activate" in ot
+            or ("enters the battlefield tapped" in ot and "opponents" in ot)
+            or "each player can't" in ot or "players can't" in ot
+            or ("cost {" in ot and "more to cast" in ot)):
+        roles.append("Stax")
+    if ("flying" in kw or "trample" in kw or "menace" in kw or "shadow" in kw
+            or "fear" in kw or "intimidate" in kw
+            or "can't be blocked" in ot or "unblockable" in ot):
+        roles.append("Evasion")
+    if ("you win the game" in ot or "extra turn" in ot or "infinite" in ot
+            or "loses the game" in ot
+            or ("damage equal to" in ot and ("number" in ot or "total" in ot))):
+        roles.append("Finisher")
+    if ("untap all" in ot or ("copy" in ot and "spell" in ot)
+            or "take an extra" in ot
+            or ("double" in ot and ("damage" in ot or "counters" in ot or "tokens" in ot))):
+        roles.append("Combo")
+    return roles

services/database.py

@@ -0,0 +1,304 @@
+"""SQLite database management and collection utility helpers."""
+from __future__ import annotations
+import io
+import json
+import logging
+import re
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Optional
+
+log_collect = logging.getLogger("commander_ai_lab.collection")
+
+# ══════════════════════════════════════════════════════════════
+# Collection Database
+# ══════════════════════════════════════════════════════════════
+COLLECTION_DB_PATH = Path(__file__).parent.parent / "collection.db"
+_db_local = threading.local()
+
+
+def _get_db_conn() -> sqlite3.Connection:
+    """Return the thread-local SQLite connection, creating it on first use."""
+    if not hasattr(_db_local, "conn") or _db_local.conn is None:
+        conn = sqlite3.connect(str(COLLECTION_DB_PATH), check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        _db_local.conn = conn
+    return _db_local.conn
+
+
+def _close_db_conn() -> None:
+    """Close and discard the thread-local connection (call on thread teardown)."""
+    conn = getattr(_db_local, "conn", None)
+    if conn is not None:
+        try:
+            conn.close()
+        except Exception:
+            pass
+        _db_local.conn = None
+
+
+def init_collection_db() -> None:
+    """Create tables, indexes, and run column migrations.
+
+    Uses _get_db_conn() so the same thread-local connection that route
+    handlers will use is warmed up and fully migrated before any request
+    arrives.  No separate connection is opened or closed here.
+    """
+    conn = _get_db_conn()
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS card_records (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            type_line TEXT DEFAULT '',
+            subtypes TEXT DEFAULT '',
+            is_legendary INTEGER DEFAULT 0,
+            is_basic INTEGER DEFAULT 0,
+            color_identity TEXT DEFAULT '',
+            cmc REAL DEFAULT 0,
+            oracle_text TEXT DEFAULT '',
+            keywords TEXT DEFAULT '',
+            tcg_price REAL DEFAULT 0,
+            salt_score REAL DEFAULT 0,
+            is_game_changer INTEGER DEFAULT 0,
+            category TEXT DEFAULT '',
+            scryfall_id TEXT DEFAULT '',
+            tcgplayer_id TEXT DEFAULT ''
+        );
+
+        CREATE TABLE IF NOT EXISTS collection_entries (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            type_line TEXT DEFAULT '',
+            subtypes TEXT DEFAULT '',
+            is_legendary INTEGER DEFAULT 0,
+            is_basic INTEGER DEFAULT 0,
+            color_identity TEXT DEFAULT '',
+            cmc REAL DEFAULT 0,
+            mana_cost TEXT DEFAULT '',
+            oracle_text TEXT DEFAULT '',
+            keywords TEXT DEFAULT '',
+            power TEXT DEFAULT '',
+            toughness TEXT DEFAULT '',
+            rarity TEXT DEFAULT '',
+            set_name TEXT DEFAULT '',
+            edhrec_rank INTEGER DEFAULT 0,
+            tcg_price REAL DEFAULT 0,
+            salt_score REAL DEFAULT 0,
+            is_game_changer INTEGER DEFAULT 0,
+            category TEXT DEFAULT '',
+            scryfall_id TEXT DEFAULT '',
+            tcgplayer_id TEXT DEFAULT '',
+            quantity INTEGER DEFAULT 1,
+            finish TEXT DEFAULT 'NORMAL',
+            condition TEXT DEFAULT '',
+            language TEXT DEFAULT '',
+            notes TEXT DEFAULT '',
+            tags TEXT DEFAULT '',
+            set_code TEXT DEFAULT '',
+            collector_number TEXT DEFAULT '',
+            created_at TEXT DEFAULT (datetime('now')),
+            updated_at TEXT DEFAULT (datetime('now'))
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_ce_name ON collection_entries(name);
+        CREATE INDEX IF NOT EXISTS idx_ce_color_identity ON collection_entries(color_identity);
+        CREATE INDEX IF NOT EXISTS idx_ce_type_line ON collection_entries(type_line);
+        CREATE INDEX IF NOT EXISTS idx_ce_is_legendary ON collection_entries(is_legendary);
+        CREATE INDEX IF NOT EXISTS idx_ce_cmc ON collection_entries(cmc);
+        CREATE INDEX IF NOT EXISTS idx_ce_category ON collection_entries(category);
+        CREATE INDEX IF NOT EXISTS idx_ce_set_code ON collection_entries(set_code);
+        CREATE INDEX IF NOT EXISTS idx_ce_collector_number ON collection_entries(collector_number);
+        CREATE INDEX IF NOT EXISTS idx_ce_finish ON collection_entries(finish);
+        CREATE INDEX IF NOT EXISTS idx_ce_quantity ON collection_entries(quantity)
+            WHERE quantity > 0;
+        CREATE INDEX IF NOT EXISTS idx_cr_name ON card_records(name);
+
+        CREATE TABLE IF NOT EXISTS decks (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            commander_scryfall_id TEXT DEFAULT '',
+            commander_name TEXT DEFAULT '',
+            color_identity TEXT DEFAULT '[]',
+            strategy_tag TEXT DEFAULT '',
+            created_at TEXT DEFAULT (datetime('now')),
+            updated_at TEXT DEFAULT (datetime('now'))
+        );
+
+        CREATE TABLE IF NOT EXISTS deck_cards (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            deck_id INTEGER NOT NULL,
+            scryfall_id TEXT NOT NULL,
+            card_name TEXT DEFAULT '',
+            quantity INTEGER DEFAULT 1,
+            is_commander INTEGER DEFAULT 0,
+            role_tag TEXT DEFAULT '',
+            FOREIGN KEY (deck_id) REFERENCES decks(id) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_dc_deck_id ON deck_cards(deck_id);
+        CREATE INDEX IF NOT EXISTS idx_dc_scryfall_id ON deck_cards(scryfall_id);
+        CREATE INDEX IF NOT EXISTS idx_dk_commander ON decks(commander_scryfall_id);
+    """)
+    conn.commit()
+
+    # ── Column migrations (additive only) ─────────────────────────────────
+    _migrate_columns = [
+        ("mana_cost",    "TEXT DEFAULT ''"),
+        ("power",        "TEXT DEFAULT ''"),
+        ("toughness",    "TEXT DEFAULT ''"),
+        ("rarity",       "TEXT DEFAULT ''"),
+        ("set_name",     "TEXT DEFAULT ''"),
+        ("edhrec_rank",  "INTEGER DEFAULT 0"),
+    ]
+    existing_cols = {
+        row[1] for row in conn.execute("PRAGMA table_info(collection_entries)").fetchall()
+    }
+    for col_name, col_def in _migrate_columns:
+        if col_name not in existing_cols:
+            conn.execute(f"ALTER TABLE collection_entries ADD COLUMN {col_name} {col_def}")
+            log_collect.info(f"  Migration: added column '{col_name}' to collection_entries")
+    conn.commit()
+
+    log_collect.info(f"  Collection DB ready: {COLLECTION_DB_PATH}")
+
+
+# ══════════════════════════════════════════════════════════════
+# Collection Utility Helpers
+# ══════════════════════════════════════════════════════════════
+_JSON_FIELDS = ("category", "color_identity", "subtypes", "keywords")
+VALID_SORT_FIELDS = {
+    "name", "cmc", "tcg_price", "salt_score", "category", "color_identity",
+    "quantity", "type_line", "finish", "rarity", "set_code", "power",
+    "toughness", "edhrec_rank",
+}
+
+
+def _row_to_dict(row) -> dict:
+    if row is None:
+        return None
+    d = dict(row)
+    for f in _JSON_FIELDS:
+        if f in d and isinstance(d[f], str):
+            try:
+                d[f] = json.loads(d[f])
+            except (json.JSONDecodeError, TypeError):
+                d[f] = []
+    return d
+
+
+def _snake_to_camel(s: str) -> str:
+    parts = s.split("_")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def _add_image_url(card: dict) -> dict:
+    scryfall_id = card.get("scryfall_id", "")
+    if scryfall_id:
+        card["imageUrl"] = f"https://api.scryfall.com/cards/{scryfall_id}?format=image&version=normal"
+    else:
+        card["imageUrl"] = None
+    for key in list(card.keys()):
+        if "_" in key:
+            camel = _snake_to_camel(key)
+            if camel not in card:
+                card[camel] = card[key]
+    return card
+
+
+def _build_collection_filters(
+    q=None,
+    colors=None,
+    types=None,
+    isLegendary=None,
+    isBasic=None,
+    isGameChanger=None,
+    highSalt=None,
+    finish=None,
+    cmcMin=None,
+    cmcMax=None,
+    priceMin=None,
+    priceMax=None,
+    category=None,
+    rarity=None,
+    setCode=None,
+    powerMin=None,
+    powerMax=None,
+    toughMin=None,
+    toughMax=None,
+    keyword=None,
+    edhrecMin=None,
+    edhrecMax=None,
+    qtyMin=None,
+    qtyMax=None,
+) -> tuple:
+    conditions = []
+    params = []
+    if q:
+        like_q = f"%{q}%"
+        conditions.append("(name LIKE ? OR type_line LIKE ? OR oracle_text LIKE ?)")
+        params.extend([like_q, like_q, like_q])
+    if colors:
+        for color in [c.strip().upper() for c in colors.split(",") if c.strip()]:
+            conditions.append("color_identity LIKE ?")
+            params.append(f"%{color}%")
+    if types:
+        tc = []
+        for t in [t.strip() for t in types.split(",") if t.strip()]:
+            tc.append("type_line LIKE ?")
+            params.append(f"%{t}%")
+        if tc:
+            conditions.append(f"({' OR '.join(tc)})")
+    if isLegendary is not None:
+        conditions.append("is_legendary = ?"); params.append(1 if isLegendary else 0)
+    if isBasic is not None:
+        conditions.append("is_basic = ?"); params.append(1 if isBasic else 0)
+    if isGameChanger is not None:
+        conditions.append("is_game_changer = ?"); params.append(1 if isGameChanger else 0)
+    if highSalt:
+        conditions.append("salt_score > 2.0")
+    if finish:
+        conditions.append("finish = ?"); params.append(finish.upper())
+    if cmcMin is not None:
+        conditions.append("cmc >= ?"); params.append(cmcMin)
+    if cmcMax is not None:
+        conditions.append("cmc <= ?"); params.append(cmcMax)
+    if priceMin is not None:
+        conditions.append("tcg_price >= ?"); params.append(priceMin)
+    if priceMax is not None:
+        conditions.append("tcg_price <= ?"); params.append(priceMax)
+    if category:
+        cc = []
+        for c in [c.strip() for c in category.split(",") if c.strip()]:
+            cc.append("category LIKE ?"); params.append(f"%{c}%")
+        if cc:
+            conditions.append(f"({' OR '.join(cc)})")
+    if rarity:
+        rl = [r.strip().lower() for r in rarity.split(",") if r.strip()]
+        if rl:
+            conditions.append(f"LOWER(rarity) IN ({','.join(['?']*len(rl))})"); params.extend(rl)
+    if setCode:
+        sl = [s.strip().upper() for s in setCode.split(",") if s.strip()]
+        if sl:
+            conditions.append(f"UPPER(set_code) IN ({','.join(['?']*len(sl))})"); params.extend(sl)
+    if powerMin is not None:
+        conditions.append("CAST(power AS REAL) >= ?"); params.append(float(powerMin))
+    if powerMax is not None:
+        conditions.append("CAST(power AS REAL) <= ?"); params.append(float(powerMax))
+    if toughMin is not None:
+        conditions.append("CAST(toughness AS REAL) >= ?"); params.append(float(toughMin))
+    if toughMax is not None:
+        conditions.append("CAST(toughness AS REAL) <= ?"); params.append(float(toughMax))
+    if keyword:
+        for kw in [k.strip() for k in keyword.split(",") if k.strip()]:
+            conditions.append("keywords LIKE ?"); params.append(f"%{kw}%")
+    if edhrecMin is not None:
+        conditions.append("edhrec_rank >= ?"); params.append(edhrecMin)
+    if edhrecMax is not None:
+        conditions.append("edhrec_rank <= ?"); params.append(edhrecMax)
+    if qtyMin is not None:
+        conditions.append("quantity >= ?"); params.append(qtyMin)
+    if qtyMax is not None:
+        conditions.append("quantity <= ?"); params.append(qtyMax)
+    where_str = ("WHERE " + " AND ".join(conditions)) if conditions else ""
+    return where_str, params

services/deck_service.py

@@ -0,0 +1,266 @@
+"""Deck service: .dck parsing, deck profile saving, deck loading."""
+import json
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+from fastapi import HTTPException
+
+from models.state import CFG
+from services.database import _get_db_conn, _row_to_dict
+
+log_collect = logging.getLogger("lab.collection")
+
+
+_TYPE_PRIORITY = ["Land", "Instant", "Sorcery", "Artifact", "Enchantment", "Planeswalker", "Creature"]
+_TYPE_TARGETS = {
+    "Land":         [36, 38],
+    "Instant":      [9, 11],
+    "Sorcery":      [7, 9],
+    "Artifact":     [9, 11],
+    "Creature":     [20, 30],
+    "Enchantment":  [5, 10],
+    "Planeswalker": [0, 5],
+}
+
+
+def _classify_card_type(type_line: str) -> str:
+    tl = type_line or ""
+    for t in _TYPE_PRIORITY:
+        if t in tl:
+            return t
+    return "Other"
+
+
+def _get_deck_or_404(deck_id: int):
+    conn = _get_db_conn()
+    row = conn.execute("SELECT * FROM decks WHERE id = ?", (deck_id,)).fetchone()
+    if not row:
+        raise HTTPException(404, f"Deck {deck_id} not found")
+    d = dict(row)
+    try:
+        d["color_identity"] = json.loads(d.get("color_identity", "[]"))
+    except Exception:
+        d["color_identity"] = []
+    return d
+
+
+def _compute_deck_analysis(deck_id: int) -> dict:
+    conn = _get_db_conn()
+    rows = conn.execute("""
+        SELECT dc.id, dc.scryfall_id, dc.card_name, dc.quantity, dc.is_commander, dc.role_tag,
+               ce.type_line, ce.oracle_text, ce.keywords, ce.cmc, ce.color_identity
+        FROM deck_cards dc
+        LEFT JOIN (
+            SELECT scryfall_id, type_line, oracle_text, keywords, cmc, color_identity
+            FROM collection_entries GROUP BY scryfall_id
+        ) ce ON ce.scryfall_id = dc.scryfall_id
+        WHERE dc.deck_id = ?
+    """, (deck_id,)).fetchall()
+    counts_by_type = {t: 0 for t in _TYPE_PRIORITY}
+    counts_by_type["Other"] = 0
+    mana_curve = {"0": 0, "1": 0, "2": 0, "3": 0, "4": 0, "5": 0, "6+": 0}
+    color_pips = {"W": 0, "U": 0, "B": 0, "R": 0, "G": 0, "C": 0}
+    total_cards = 0
+    roles_count = {}
+    for row in rows:
+        r = dict(row)
+        qty = r.get("quantity", 1)
+        total_cards += qty
+        card_type = _classify_card_type(r.get("type_line", ""))
+        counts_by_type[card_type] = counts_by_type.get(card_type, 0) + qty
+        cmc = int(r.get("cmc", 0) or 0)
+        if card_type != "Land":
+            key = str(min(cmc, 6)) if cmc < 6 else "6+"
+            mana_curve[key] = mana_curve.get(key, 0) + qty
+        ci_raw = r.get("color_identity", "[]")
+        if isinstance(ci_raw, str):
+            try:
+                ci_raw = json.loads(ci_raw)
+            except Exception:
+                ci_raw = []
+        for c in (ci_raw or []):
+            if c in color_pips:
+                color_pips[c] += qty
+        role = r.get("role_tag") or "Unknown"
+        roles_count[role] = roles_count.get(role, 0) + qty
+    return {
+        "total_cards": total_cards,
+        "counts_by_type": counts_by_type,
+        "mana_curve": mana_curve,
+        "color_pips": color_pips,
+        "total_cards": total_cards,
+        "roles": roles_count,
+    }
+
+
+def _check_ratio_limit(deck_id: int, card_type: str, count_to_add: int = 1) -> bool:
+    analysis = _compute_deck_analysis(deck_id)
+    current = analysis["counts_by_type"].get(card_type, 0)
+    target_max = _TYPE_TARGETS.get(card_type, [0, 9999])[1]
+    return (current + count_to_add) <= target_max
+
+
+def _to_edhrec_slug(name: str) -> str:
+    slug = name.lower()
+    slug = re.sub(r"[',.]" , "", slug)
+    slug = re.sub(r"[^a-z0-9]+", "-", slug)
+    return slug.strip("-")
+
+
+def parse_dck_file(deck_path: str) -> dict:
+    """Parse a Forge .dck file into {name, commanders, mainboard, colorIdentity, totalCards}."""
+    path = Path(deck_path)
+    if not path.exists():
+        return {"error": f"File not found: {deck_path}"}
+    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    name = path.stem
+    section = "main"
+    commanders: dict = {}
+    mainboard: dict = {}
+    commander_name = None
+    for line in lines:
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line == "[metadata]":
+            section = "metadata"; continue
+        if line.startswith("Name="):
+            name = line.split("=", 1)[1].strip(); continue
+        if line == "[Commander]":
+            section = "commander"; continue
+        if line == "[Main]":
+            section = "main"; continue
+        if line.lower().startswith("sideboard") or line == "[Sideboard]":
+            section = "sideboard"; continue
+        clean = re.sub(r"\(\w+\)\s*\d*$", "", line).strip()
+        clean = re.sub(r"\s*\*\.\*$", "", clean).strip()
+        m = re.match(r"^(\d+)x?\s+(.+)$", clean)
+        qty, card_name = (int(m.group(1)), m.group(2).strip()) if m else (1, clean)
+        if not card_name:
+            continue
+        if section == "commander":
+            commanders[card_name] = qty
+            if not commander_name:
+                commander_name = card_name
+        elif section != "sideboard":
+            mainboard[card_name] = qty
+    if commander_name:
+        name = f"{commander_name} - Text Import"
+    total = sum(commanders.values()) + sum(mainboard.values())
+    return {"name": name, "commander": commander_name, "commanders": commanders, "mainboard": mainboard, "colorIdentity": [], "totalCards": total}
+
+
+def _save_profile_to_dck(profile: dict) -> Path:
+    lines = ["[metadata]", f"Name={profile.get('name', 'Imported Deck')}", "", "[Commander]"]
+    for name, qty in profile.get("commanders", {}).items():
+        lines.append(f"{qty} {name}")
+    lines += ["", "[Main]"]
+    for name, qty in profile.get("mainboard", {}).items():
+        lines.append(f"{qty} {name}")
+    content = "\n".join(lines)
+    safe_name = re.sub(r"[^a-zA-Z0-9 _-]", "", profile.get("name", "imported")).replace(" ", "_").strip()
+    if not safe_name:
+        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")
+        os.makedirs(save_dir, exist_ok=True)
+    out_path = Path(save_dir) / f"{safe_name}.dck"
+    out_path.write_text(content, encoding="utf-8")
+    log_collect.info(f" Saved .dck: {out_path}")
+    return out_path
+
+
+def _load_deck_cards_by_name(deck_name: str) -> list:
+    """Load cards from a deck by name, returning list of card dicts."""
+    conn = _get_db_conn()
+    deck_row = conn.execute("SELECT id FROM decks WHERE name = ?", (deck_name,)).fetchone()
+    if not deck_row:
+        return []
+    deck_id = deck_row[0]
+    rows = conn.execute("""
+        SELECT dc.card_name, dc.quantity, dc.is_commander, dc.role_tag, dc.scryfall_id,
+               COALESCE(ce.type_line, cr.type_line, '') as type_line,
+               COALESCE(ce.oracle_text, cr.oracle_text, '') as oracle_text,
+               COALESCE(ce.cmc, cr.cmc, 0) as cmc,
+               COALESCE(ce.color_identity, cr.color_identity, '[]') as color_identity,
+               COALESCE(ce.mana_cost, '', '') as mana_cost,
+               COALESCE(ce.power, '', '') as power,
+               COALESCE(ce.toughness, '', '') as toughness,
+               COALESCE(ce.keywords, cr.keywords, '[]') as keywords
+        FROM deck_cards dc
+        LEFT JOIN (
+            SELECT scryfall_id, type_line, oracle_text, cmc, color_identity, mana_cost, power, toughness, keywords
+            FROM collection_entries GROUP BY scryfall_id
+        ) ce ON ce.scryfall_id = dc.scryfall_id
+        LEFT JOIN (
+            SELECT name, type_line, oracle_text, cmc, color_identity, keywords
+            FROM card_records GROUP BY name
+        ) cr ON cr.name = dc.card_name
+        WHERE dc.deck_id = ?
+    """, (deck_id,)).fetchall()
+    return [_row_to_dict(r) for r in rows]
+
+
+log_deckgen = logging.getLogger("commander_ai_lab.deckgen")
+
+
+def _build_dck_lines(
+    deck_name: str,
+    commander_name: str,
+    cards: list[dict],
+    *,
+    resolve_substitutes: bool = False,
+) -> list[str]:
+    """Build Forge .dck file lines from deck name, commander, and card list."""
+    lines: list[str] = [
+        "[metadata]",
+        f"Name={deck_name}",
+        "",
+        "[Commander]",
+        f"1 {commander_name}",
+        "",
+        "[Main]",
+    ]
+    for card in cards:
+        cname = card.get("name", "")
+        if resolve_substitutes:
+            if card.get("status") == "substituted" and card.get("selected_substitute"):
+                cname = card["selected_substitute"]
+        if cname and cname != commander_name:
+            lines.append(f"{card.get('count', card.get('quantity', 1))} {cname}")
+    return lines
+
+
+def _write_dck_file(
+    deck_name: str,
+    commander_name: str,
+    cards: list[dict],
+    decks_dir: str | None = None,
+    *,
+    fallback_id: int | str = 0,
+    resolve_substitutes: bool = False,
+) -> str | None:
+    """Write a Forge .dck file to decks_dir. Returns path on success, None otherwise."""
+    if not decks_dir:
+        decks_dir = CFG.forge_decks_dir
+    if not decks_dir or not os.path.isdir(decks_dir):
+        return None
+
+    safe_name = re.sub(r"[^a-zA-Z0-9_\-\s]", "", deck_name).strip().replace(" ", "_")
+    if not safe_name:
+        safe_name = f"Deck_{fallback_id}"
+
+    dck_path = os.path.join(decks_dir, f"{safe_name}.dck")
+    lines = _build_dck_lines(
+        deck_name, commander_name, cards,
+        resolve_substitutes=resolve_substitutes,
+    )
+    with open(dck_path, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines))
+
+    log_deckgen.info(f" Exported .dck: {dck_path}")
+    return dck_path

services/forge_runner.py

@@ -0,0 +1,591 @@
+"""Forge batch simulation runner: Java discovery, command building, process management."""
+import asyncio
+import json
+import logging
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+from datetime import datetime as _datetime
+from pathlib import Path
+from typing import Optional
+
+from models.state import CFG, BatchState
+from services.deck_service import parse_dck_file, _load_deck_cards_by_name
+
+log = logging.getLogger("lab.batch")
+log_sim = logging.getLogger("commander_ai_lab.sim")
+
+# Global DeepSeek brain instance (lazy-initialized)
+_deepseek_brain = None
+_deepseek_lock = threading.Lock()
+
+# ── Global watchdog: single thread monitors all active batches ──
+_watchdog_registry: dict[str, dict] = {}   # batch_id -> {state, proc, last_activity}
+_watchdog_lock = threading.Lock()
+_watchdog_started = False
+_STALL_LIMIT = 600  # 10 min
+
+def _global_watchdog_loop():
+    """Single daemon thread that checks all active batches for stalls."""
+    while True:
+        time.sleep(5)
+        with _watchdog_lock:
+            finished = []
+            for bid, entry in _watchdog_registry.items():
+                proc = entry["proc"]
+                if proc.poll() is not None:
+                    finished.append(bid)
+                    continue
+                if (time.monotonic() - entry["last_activity"]) > _STALL_LIMIT:
+                    log.warning(f"Stall detected for batch {bid}, killing process")
+                    entry["state"].log_lines.append("[WATCHDOG] Process stalled. Killed.")
+                    proc.kill()
+                    entry["state"].running = False
+                    entry["state"].error = "Stall detected (10 min no output)"
+                    finished.append(bid)
+            for bid in finished:
+                del _watchdog_registry[bid]
+
+def _ensure_watchdog_started():
+    global _watchdog_started
+    if not _watchdog_started:
+        with _watchdog_lock:
+            if not _watchdog_started:
+                t = threading.Thread(target=_global_watchdog_loop, daemon=True)
+                t.start()
+                _watchdog_started = True
+
+def _register_batch(batch_id: str, state, proc):
+    _ensure_watchdog_started()
+    with _watchdog_lock:
+        _watchdog_registry[batch_id] = {
+            "state": state, "proc": proc, "last_activity": time.monotonic()
+        }
+
+def _touch_batch(batch_id: str):
+    with _watchdog_lock:
+        if batch_id in _watchdog_registry:
+            _watchdog_registry[batch_id]["last_activity"] = time.monotonic()
+
+def _unregister_batch(batch_id: str):
+    with _watchdog_lock:
+        _watchdog_registry.pop(batch_id, None)
+
+
+# ── Java 17 Discovery ───────────────────────────────────────────────
+
+# Ordered list of directories to scan for JDK 17 installations.
+# Covers: Eclipse Temurin, Oracle, Amazon Corretto, Microsoft, Azul Zulu, SAP.
+_JAVA17_SEARCH_DIRS = [
+    r'C:\Program Files\Eclipse Adoptium',
+    r'C:\Program Files\Java',
+    r'C:\Program Files\Amazon Corretto',
+    r'C:\Program Files\Microsoft',
+    r'C:\Program Files\Zulu',
+    r'C:\Program Files\BellSoft',
+    r'C:\Program Files\SapMachine',
+]
+
+
+def _find_java17() -> str:
+    """
+    Search well-known JDK install directories for a Java 17 binary.
+    Falls back to JAVA17_HOME env var, then JAVA_HOME, then warns and returns 'java'.
+    Returns the absolute path to java.exe if found, otherwise 'java'.
+    """
+    # 1. Explicit override via env var
+    env_override = os.environ.get('JAVA17_HOME', '').strip()
+    if env_override:
+        candidate = os.path.join(env_override, 'bin', 'java.exe')
+        if os.path.isfile(candidate):
+            log.info(f"Java 17 found via JAVA17_HOME: {candidate}")
+            return candidate
+        log.warning(f"JAVA17_HOME set to '{env_override}' but java.exe not found there.")
+
+    # 2. Scan vendor directories
+    for d in _JAVA17_SEARCH_DIRS:
+        if not os.path.isdir(d):
+            continue
+        try:
+            children = os.listdir(d)
+        except OSError:
+            continue
+        for child in sorted(children):  # sorted = deterministic, picks lowest 17.x
+            if re.match(r'jdk-?17', child, re.IGNORECASE) or re.match(r'temurin-17', child, re.IGNORECASE):
+                candidate = os.path.join(d, child, 'bin', 'java.exe')
+                if os.path.isfile(candidate):
+                    log.info(f"Java 17 found: {candidate}")
+                    return candidate
+
+    # 3. JAVA_HOME fallback — only accept if it IS version 17
+    java_home = os.environ.get('JAVA_HOME', '').strip()
+    if java_home:
+        candidate = os.path.join(java_home, 'bin', 'java.exe')
+        if os.path.isfile(candidate):
+            try:
+                result = subprocess.run(
+                    [candidate, '-version'],
+                    capture_output=True, text=True, timeout=5
+                )
+                version_output = result.stderr or result.stdout
+                if 'version "17' in version_output:
+                    log.info(f"Java 17 found via JAVA_HOME: {candidate}")
+                    return candidate
+                else:
+                    log.warning(
+                        f"JAVA_HOME points to '{java_home}' but it is not Java 17. "
+                        f"Version output: {version_output.strip()!r}"
+                    )
+            except Exception as e:
+                log.warning(f"Could not probe JAVA_HOME java version: {e}")
+
+    # 4. Nothing found — warn loudly so the log surfaces the issue
+    log.error(
+        "Java 17 not found! Forge simulation requires Java 17. "
+        "Install Eclipse Temurin 17 (winget install EclipseAdoptium.Temurin.17.JDK) "
+        "or set the JAVA17_HOME environment variable to your JDK 17 install directory. "
+        "Falling back to system 'java' which may be the wrong version."
+    )
+    return 'java'
+
+
+_JAVA17_PATH = None
+
+
+def get_java17() -> str:
+    global _JAVA17_PATH
+    if _JAVA17_PATH is None:
+        _JAVA17_PATH = _find_java17()
+    return _JAVA17_PATH
+
+
+def reset_java17_cache():
+    """Force re-discovery of Java 17 path (useful after installing JDK at runtime)."""
+    global _JAVA17_PATH
+    _JAVA17_PATH = None
+
+
+def build_java_command(
+    decks: list, num_games: int, threads: int, seed: Optional[int],
+    clock: int, output_path: str, use_learned_policy: bool = False,
+    policy_server: str = "http://localhost:8080", policy_style: str = "midrange",
+    policy_greedy: bool = False, ai_simplified: bool = False,
+    ai_think_time_ms: int = -1, max_queue_depth: int = -1,
+) -> list:
+    java17 = get_java17()
+    lab_jar = CFG.lab_jar
+    forge_jar = CFG.forge_jar
+    forge_dir = CFG.forge_dir
+    if not lab_jar or not os.path.isfile(lab_jar):
+        log.error(f"Lab JAR not found at '{lab_jar}'. Run 'mvn package' first.")
+        raise FileNotFoundError(f"Lab JAR not found: {lab_jar}")
+    cmd = [
+        java17, '-jar', lab_jar,
+        '--forge-jar', forge_jar,
+        '--forge-dir', forge_dir,
+        '--games', str(num_games),
+        '--threads', str(threads),
+        '--clock', str(clock),
+        '--output', output_path,
+    ]
+    # Map deck list to --deck1 .. --deck4
+    for i, d in enumerate(decks[:4], start=1):
+        cmd += [f'--deck{i}', str(d)]
+    if seed is not None:
+        cmd += ['--seed', str(seed)]
+    if use_learned_policy:
+        cmd += ['--policy', policy_style, '--policyServer', policy_server]
+        if policy_greedy:
+            cmd += ['--policyGreedy']
+    if ai_simplified:
+        cmd += ['--aiSimplified']
+    if ai_think_time_ms > 0:
+        cmd += ['--aiThinkTimeMs', str(ai_think_time_ms)]
+    if max_queue_depth > 0:
+        cmd += ['--maxQueueDepth', str(max_queue_depth)]
+    return cmd
+
+
+def _run_process_blocking(state: BatchState, cmd: list):
+    """Run Forge subprocess, parse progress, generate deck reports."""
+    log.info(f"Running: {' '.join(cmd)}")
+
+    # Ensure Forge subprocesses use Java 17
+    env = os.environ.copy()
+    java17 = get_java17()
+    if java17 != 'java':
+        java17_bin = os.path.dirname(java17)
+        java17_home = os.path.dirname(java17_bin)
+        env['JAVA_HOME'] = java17_home
+        env['PATH'] = java17_bin + os.pathsep + env.get('PATH', '')
+
+    try:
+        proc = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            text=True, bufsize=1, env=env,
+        )
+        state.process = proc
+    except Exception as e:
+        state.running = False
+        state.error = str(e)
+        log.error(f"Failed to start subprocess: {e}")
+        return
+
+    _register_batch(state.batch_id, state, proc)
+
+    for line in proc.stdout:
+        _touch_batch(state.batch_id)
+        line = line.rstrip()
+        state.log_lines.append(line)
+        gm = re.match(r'\[Game (\d+)/(\d+)\]', line)
+        if gm:
+            state.completed_games = int(gm.group(1))
+            state.total_games = int(gm.group(2))
+        pm = re.match(r'\[PROGRESS\].*?(\d+\.?\d*)\s*sims/sec', line)
+        if pm:
+            state.sims_per_sec = float(pm.group(1))
+
+    proc.wait()
+    _unregister_batch(state.batch_id)
+    elapsed = (_datetime.now() - state.start_time).total_seconds() * 1000
+    state.elapsed_ms = int(elapsed)
+    if proc.returncode != 0:
+        state.running = False
+        # Include last few log lines in error for easier diagnosis
+        tail = '  |  '.join(state.log_lines[-5:]) if state.log_lines else '(no output)'
+        state.error = f"Exit code {proc.returncode} — last output: {tail}"
+    else:
+        state.running = False
+        state.completed_games = state.total_games
+
+
+async def run_batch_subprocess(
+    state: BatchState,
+    decks: list,
+    num_games: int,
+    threads: int,
+    seed: Optional[int] = None,
+    clock: int = 6000,
+    output_path: str = "results",
+    use_learned_policy: bool = False,
+    policy_style: str = "midrange",
+    policy_greedy: bool = False,
+    ai_simplified: bool = False,
+    ai_think_time_ms: int = -1,
+    max_queue_depth: int = -1,
+):
+    """Async wrapper that runs Forge subprocess in executor."""
+    try:
+        policy_server = f"http://localhost:{CFG.port}"
+        cmd = build_java_command(
+            decks, num_games, threads, seed, clock, output_path,
+            use_learned_policy=use_learned_policy,
+            policy_server=policy_server,
+            policy_style=policy_style,
+            policy_greedy=policy_greedy,
+            ai_simplified=ai_simplified,
+            ai_think_time_ms=ai_think_time_ms,
+            max_queue_depth=max_queue_depth,
+        )
+        log.info(f"Starting batch {state.batch_id}: {' '.join(cmd[:6])}...")
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, _run_process_blocking, state, cmd)
+    except Exception as e:
+        state.error = str(e)
+        state.running = False
+        log.error(f"Batch {state.batch_id} ERROR: {e}")
+
+
+def _get_deepseek_brain():
+    """Get or create the global DeepSeek brain instance."""
+    global _deepseek_brain
+    if _deepseek_brain is None:
+        with _deepseek_lock:
+            if _deepseek_brain is None:
+                try:
+                    src_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'src')
+                    src_dir = os.path.normpath(src_dir)
+                    if src_dir not in sys.path:
+                        sys.path.insert(0, src_dir)
+                    from commander_ai_lab.sim.deepseek_brain import DeepSeekBrain, DeepSeekConfig
+                    cfg = DeepSeekConfig(
+                        api_base=os.environ.get("BRAIN_API_BASE", "http://localhost:11434"),
+                        model=os.environ.get("BRAIN_MODEL", "gpt-oss:20b"),
+                        temperature=float(os.environ.get("BRAIN_TEMPERATURE", "0.3")),
+                        max_tokens=int(os.environ.get("BRAIN_MAX_TOKENS", "1024")),
+                        request_timeout=float(os.environ.get("BRAIN_TIMEOUT", "120.0")),
+                    )
+                    cfg.log_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'logs', 'decisions')
+                    cfg.log_dir = os.path.normpath(cfg.log_dir)
+                    _deepseek_brain = DeepSeekBrain(cfg)
+                except Exception as e:
+                    log_sim.error(f'Failed to initialize brain: {e}')
+                    return None
+    return _deepseek_brain
+
+
+def _run_deepseek_batch_thread(
+    state: BatchState,
+    deck_names: list,
+    num_games: int,
+    output_path: str,
+):
+    """Run batch simulation using Python sim engine + DeepSeek AI opponent."""
+    try:
+        src_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'src')
+        src_dir = os.path.normpath(src_dir)
+        if src_dir not in sys.path:
+            sys.path.insert(0, src_dir)
+
+        from commander_ai_lab.sim.models import Card
+        from commander_ai_lab.sim.deepseek_engine import DeepSeekGameEngine
+        from commander_ai_lab.sim.rules import enrich_card
+
+        state.log_lines.append('[DeepSeek Batch] Initializing DeepSeek brain...')
+        brain = _get_deepseek_brain()
+        if brain and not brain._connected:
+            brain.check_connection()
+        if not brain or not brain._connected:
+            state.error = 'DeepSeek LLM not connected. Go to Simulator > DeepSeek and connect first.'
+            state.running = False
+            return
+
+        state.log_lines.append(f'[DeepSeek Batch] Connected to {brain.config.model}')
+
+        deck_win_rates = {}
+        try:
+            results_dir = CFG.results_dir
+            if os.path.isdir(results_dir):
+                for fname in sorted(os.listdir(results_dir), reverse=True):
+                    if fname.startswith('batch-') and fname.endswith('.json'):
+                        try:
+                            with open(os.path.join(results_dir, fname), 'r') as rf:
+                                past = json.loads(rf.read())
+                            for dd in past.get('decks', []):
+                                dname = dd.get('deckName', '')
+                                wr = dd.get('winRate')
+                                if dname and wr is not None and dname not in deck_win_rates:
+                                    deck_win_rates[dname] = float(wr)
+                        except Exception:
+                            pass
+        except Exception:
+            pass
+
+        loaded_decks = {}
+        deck_meta = {}
+        for dn in deck_names:
+            raw_cards = _load_deck_cards_by_name(dn)
+            if not raw_cards:
+                state.log_lines.append(f'[DeepSeek Batch] WARNING: Could not load deck "{dn}", skipping.')
+                continue
+
+            commander_name = ''
+            color_identity_set = set()
+            deck_objs = []
+            for cd in raw_cards:
+                c = Card(name=(cd.get('card_name') or cd.get('name', '')))
+                if cd.get('type_line'): c.type_line = cd['type_line']
+                if cd.get('cmc'): c.cmc = float(cd['cmc'])
+                if cd.get('power') and cd.get('toughness'):
+                    c.power = str(cd['power'])
+                    c.toughness = str(cd['toughness'])
+                    c.pt = c.power + '/' + c.toughness
+                if cd.get('oracle_text'): c.oracle_text = cd['oracle_text']
+                if cd.get('mana_cost'): c.mana_cost = cd['mana_cost']
+                if cd.get('keywords'):
+                    kw = cd['keywords']
+                    if isinstance(kw, str):
+                        try: kw = json.loads(kw)
+                        except Exception: kw = []
+                    if isinstance(kw, list): c.keywords = kw
+                if cd.get('is_commander'):
+                    c.is_commander = True
+                    commander_name = (cd.get('card_name') or cd.get('name', ''))
+                ci_str = cd.get('color_identity', '')
+                if ci_str:
+                    try:
+                        ci_parsed = json.loads(ci_str) if isinstance(ci_str, str) else ci_str
+                        if isinstance(ci_parsed, list):
+                            for color in ci_parsed:
+                                color_identity_set.add(color)
+                    except Exception:
+                        pass
+                enrich_card(c)
+                deck_objs.append(c)
+
+            creature_count = sum(1 for c in deck_objs if c.is_creature())
+            removal_count = sum(1 for c in deck_objs if c.is_removal)
+            ramp_count = sum(1 for c in deck_objs if c.is_ramp)
+            avg_cmc = sum(c.cmc or 0 for c in deck_objs if not c.is_land()) / max(sum(1 for c in deck_objs if not c.is_land()), 1)
+            oracle_all = ' '.join((c.oracle_text or '').lower() for c in deck_objs)
+            has_combo_text = any(kw in oracle_all for kw in ['you win the game', 'infinite', 'extra turn'])
+
+            if has_combo_text:
+                archetype = 'combo'
+            elif creature_count >= 30 and avg_cmc <= 2.8:
+                archetype = 'aggro'
+            elif removal_count >= 10 or (creature_count <= 18 and avg_cmc >= 3.2):
+                archetype = 'control'
+            else:
+                archetype = 'midrange'
+
+            color_identity_list = sorted(list(color_identity_set))
+            deck_meta[dn] = {
+                'commander_name': commander_name,
+                'color_identity': color_identity_list,
+                'archetype': archetype,
+                'win_rate': deck_win_rates.get(dn),
+            }
+
+            loaded_decks[dn] = deck_objs
+            cmdr_info = f' (Commander: {commander_name})' if commander_name else ''
+            wr_info = f' [History: {deck_win_rates[dn]:.0f}% WR]' if dn in deck_win_rates else ''
+            state.log_lines.append(f'[DeepSeek Batch] Loaded deck "{dn}" ({len(deck_objs)} cards, {archetype}){cmdr_info}{wr_info}')
+
+        if not loaded_decks:
+            state.error = 'No decks could be loaded.'
+            state.running = False
+            return
+
+        deck_list = list(loaded_decks.keys())
+        games_per_deck = max(1, num_games // len(deck_list))
+        total_games = games_per_deck * len(deck_list)
+        state.total_games = total_games
+
+        state.log_lines.append(f'[DeepSeek Batch] Running {games_per_deck} games per deck \u00d7 {len(deck_list)} decks = {total_games} total')
+
+        engine = DeepSeekGameEngine(
+            brain=brain,
+            ai_player_index=0,
+            max_turns=25,
+            record_log=True,
+            ml_log=True,
+        )
+
+        start_time = time.time()
+        all_deck_results = []
+        completed = 0
+
+        for deck_name in deck_list:
+            deck_a = loaded_decks[deck_name]
+            from commander_ai_lab.lab.experiments import _generate_training_deck
+
+            deck_stats = {
+                'deckName': deck_name,
+                'wins': 0, 'losses': 0, 'totalGames': games_per_deck,
+                'totalTurns': 0, 'totalDamageDealt': 0, 'totalDamageReceived': 0,
+                'totalSpellsCast': 0, 'totalCreaturesPlayed': 0,
+                'games': [],
+            }
+
+            meta = deck_meta.get(deck_name, {})
+            dk_archetype = meta.get('archetype', 'midrange')
+            dk_commander = meta.get('commander_name', '')
+            dk_colors = meta.get('color_identity', [])
+            dk_win_rate = meta.get('win_rate')
+
+            for g in range(games_per_deck):
+                try:
+                    deck_b = _generate_training_deck()
+                    game_id = f'ds-{state.batch_id}-{deck_name[:12]}-g{g+1}'
+                    result = engine.run(
+                        deck_a, deck_b,
+                        name_a=deck_name + ' (AI)',
+                        name_b='Training Opponent',
+                        game_id=game_id, archetype=dk_archetype,
+                        commander_name=dk_commander,
+                        color_identity=dk_colors,
+                        win_rate=dk_win_rate,
+                    )
+                    gd = result.to_dict()
+                    gd['gameNumber'] = g + 1
+                    deck_stats['games'].append(gd)
+
+                    if result.winner == 0:
+                        deck_stats['wins'] += 1
+                    else:
+                        deck_stats['losses'] += 1
+                    deck_stats['totalTurns'] += result.turns
+                    if result.player_a_stats:
+                        deck_stats['totalDamageDealt'] += result.player_a_stats.damage_dealt
+                        deck_stats['totalDamageReceived'] += result.player_a_stats.damage_received
+                        deck_stats['totalSpellsCast'] += result.player_a_stats.spells_cast
+                        deck_stats['totalCreaturesPlayed'] += result.player_a_stats.creatures_played
+
+                    state.log_lines.append(
+                        f'[Game {completed + 1}/{total_games}] {deck_name} (AI-piloted) \u2192 '
+                        f'{"WIN" if result.winner == 0 else "LOSS"} (turn {result.turns})'
+                    )
+                except Exception as ge:
+                    state.log_lines.append(f'[Game {completed + 1}/{total_games}] ERROR: {ge}')
+                    deck_stats['games'].append({'error': str(ge), 'gameNumber': g + 1})
+
+                completed += 1
+                state.completed_games = completed
+
+            n = deck_stats['totalGames']
+            deck_stats['winRate'] = round(deck_stats['wins'] / n * 100, 1) if n > 0 else 0.0
+            deck_stats['avgTurns'] = round(deck_stats['totalTurns'] / n, 1) if n > 0 else 0.0
+            deck_stats['avgDamageDealt'] = round(deck_stats['totalDamageDealt'] / n, 1) if n > 0 else 0.0
+            deck_stats['avgDamageReceived'] = round(deck_stats['totalDamageReceived'] / n, 1) if n > 0 else 0.0
+            deck_stats['avgSpellsCast'] = round(deck_stats['totalSpellsCast'] / n, 1) if n > 0 else 0.0
+            deck_stats['avgCreaturesPlayed'] = round(deck_stats['totalCreaturesPlayed'] / n, 1) if n > 0 else 0.0
+            deck_stats['archetype'] = dk_archetype
+            deck_stats['commander'] = dk_commander
+            deck_stats['colorIdentity'] = dk_colors
+            if dk_win_rate is not None:
+                deck_stats['priorWinRate'] = dk_win_rate
+            all_deck_results.append(deck_stats)
+
+        elapsed = time.time() - start_time
+        ds_stats = brain.get_stats() if brain else {}
+
+        batch_result = {
+            'metadata': {
+                'batchId': state.batch_id,
+                'timestamp': _datetime.now().isoformat(),
+                'completedGames': completed,
+                'threads': 1,
+                'elapsedMs': int(elapsed * 1000),
+                'engine': 'deepseek',
+                'model': brain.config.model if brain else 'unknown',
+            },
+            'decks': all_deck_results,
+            'deepseekStats': ds_stats,
+        }
+
+        ml_decisions = engine.flush_ml_decisions()
+        if ml_decisions:
+            ml_jsonl_path = os.path.join(CFG.results_dir, f'ml-decisions-ds-{state.batch_id}.jsonl')
+            os.makedirs(os.path.dirname(ml_jsonl_path) or '.', exist_ok=True)
+            with open(ml_jsonl_path, 'w', encoding='utf-8') as mf:
+                for dec in ml_decisions:
+                    mf.write(json.dumps(dec) + '\n')
+            state.log_lines.append(f'[ML Data] Wrote {len(ml_decisions)} decision snapshots to {os.path.basename(ml_jsonl_path)}')
+        else:
+            state.log_lines.append('[ML Data] No decision snapshots captured (0 decisions)')
+
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+        with open(output_path, 'w', encoding='utf-8') as f:
+            json.dump(batch_result, f, indent=2, default=str)
+
+        state.result_path = output_path
+        state.elapsed_ms = int(elapsed * 1000)
+        state.running = False
+        state.completed_games = total_games
+
+        state.log_lines.append(f'[DeepSeek Batch] Complete: {completed} games in {elapsed:.1f}s')
+        for ds in all_deck_results:
+            state.log_lines.append(f'  {ds["deckName"]}: {ds["wins"]}W-{ds["losses"]}L ({ds["winRate"]}% WR)')
+
+        log_sim.info(f'Batch {state.batch_id} complete: {completed} games in {elapsed:.1f}s')
+
+    except Exception as e:
+        import traceback
+        state.error = str(e)
+        state.running = False
+        state.log_lines.append(f'[DeepSeek Batch] FATAL: {e}')
+        traceback.print_exc()

services/import_helpers.py

@@ -0,0 +1,193 @@
+"""URL-based deck import helpers: Archidekt, EDHREC, text decklist parsing."""
+import json
+import logging
+import os
+import re
+import time
+from pathlib import Path
+from urllib.request import urlopen, Request
+
+from models.state import CFG
+from services.deck_service import _to_edhrec_slug
+from services.scryfall import _API_HEADERS
+
+log_collect = logging.getLogger("commander_ai_lab.collection")
+
+
+def _http_get(url: str) -> str:
+    with urlopen(Request(url, headers=_API_HEADERS), timeout=30) as resp:
+        return resp.read().decode("utf-8")
+
+
+def _fetch_archidekt_deck(deck_id: str) -> dict:
+    url = f"https://archidekt.com/api/decks/{deck_id}/"
+    data = json.loads(_http_get(url))
+    profile = {
+        "name": data.get("name", f"Archidekt {deck_id}"),
+        "commander": None,
+        "source": "Archidekt",
+        "sourceUrl": f"https://archidekt.com/decks/{deck_id}",
+        "commanders": {},
+        "mainboard": {},
+        "colorIdentity": [],
+        "totalCards": 0,
+    }
+    for card_entry in data.get("cards", []):
+        qty = card_entry.get("quantity", 1)
+        oracle = card_entry.get("card", {}).get("oracleCard", {})
+        card_name = oracle.get("name", "Unknown")
+        is_commander = any(c.lower() == "commander" for c in card_entry.get("categories", []))
+        if is_commander:
+            profile["commanders"][card_name] = qty
+            if not profile["commander"]:
+                profile["commander"] = card_name
+                if oracle.get("colorIdentity"):
+                    profile["colorIdentity"] = oracle["colorIdentity"]
+        else:
+            profile["mainboard"][card_name] = qty
+    profile["totalCards"] = sum(profile["commanders"].values()) + sum(profile["mainboard"].values())
+    if not profile["name"] or profile["name"] == f"Archidekt {deck_id}":
+        profile["name"] = f"{profile['commander']} \u2014 Archidekt"
+    return profile
+
+
+def _fetch_edhrec_average(commander_name: str) -> dict:
+    slug = _to_edhrec_slug(commander_name)
+    url = f"https://json.edhrec.com/pages/average-decks/{slug}.json"
+    data = json.loads(_http_get(url))
+    container = data.get("container", {})
+    json_dict = container.get("json_dict", {})
+    card_info = json_dict.get("card", {})
+    real_name = card_info.get("name", commander_name.title())
+    profile = {
+        "name": f"{real_name} \u2014 EDHREC Average",
+        "commander": real_name,
+        "source": "EDHREC Average",
+        "sourceUrl": f"https://edhrec.com/average-decks/{slug}",
+        "commanders": {real_name: 1},
+        "mainboard": {},
+        "colorIdentity": card_info.get("color_identity", []),
+        "sampleSize": data.get("num_decks_avg"),
+        "totalCards": 0,
+    }
+    for cl in json_dict.get("cardlists", []):
+        for cv in cl.get("cardviews", []):
+            card_name = cv.get("name", "")
+            if card_name:
+                profile["mainboard"][card_name] = 1
+    archidekt_data = data.get("archidekt", [])
+    if archidekt_data:
+        basic_names = []
+        for cl in json_dict.get("cardlists", []):
+            if cl.get("tag") == "basics":
+                for cv in cl.get("cardviews", []):
+                    basic_names.append(cv.get("name", ""))
+        basic_quantities = [e["q"] for e in archidekt_data if e.get("q", 1) > 1]
+        for i, name in enumerate(basic_names):
+            if i < len(basic_quantities):
+                profile["mainboard"][name] = basic_quantities[i]
+    profile["totalCards"] = sum(profile["commanders"].values()) + sum(profile["mainboard"].values())
+    return profile
+
+
+def _import_from_url(url: str) -> dict:
+    url = url.strip()
+    if "archidekt.com/decks/" in url:
+        m = re.search(r"/decks/(\d+)", url)
+        if not m:
+            raise ValueError("Could not parse Archidekt deck ID from URL")
+        return _fetch_archidekt_deck(m.group(1))
+    if "edhrec.com/average-decks/" in url:
+        slug = re.search(r"/average-decks/([^/?#]+)", url).group(1)
+        return _fetch_edhrec_average(slug.replace("-", " "))
+    if "edhrec.com/commanders/" in url:
+        slug = re.search(r"/commanders/([^/?#]+)", url).group(1)
+        return _fetch_edhrec_average(slug.replace("-", " "))
+    raise ValueError(f"Unsupported URL: {url}. Supported: archidekt.com/decks/..., edhrec.com/average-decks/..., edhrec.com/commanders/...")
+
+
+def _parse_text_decklist(text: str, commander_override: str = None) -> dict:
+    profile = {
+        "name": "Text Import",
+        "commander": None,
+        "source": "Text Import",
+        "sourceUrl": None,
+        "commanders": {},
+        "mainboard": {},
+        "totalCards": 0,
+    }
+    section = "main"
+    for line in text.strip().split("\n"):
+        line = line.strip()
+        if not line or line.startswith("//") or line.startswith("#"):
+            continue
+        if line.lower().startswith("commander") or line == "[Commander]":
+            section = "commander"; continue
+        if line.lower().startswith("main") or line.lower().startswith("deck") or line == "[Main]":
+            section = "main"; continue
+        if line.lower().startswith("sideboard") or line == "[Sideboard]":
+            section = "sideboard"; continue
+        clean = re.sub(r"\(\w+\)\s*\d*$", "", line).strip()
+        clean = re.sub(r"\s*\*.*$", "", clean).strip()
+        m = re.match(r"^(\d+)x?\s+(.+)$", clean)
+        qty, card_name = (int(m.group(1)), m.group(2).strip()) if m else (1, clean)
+        if not card_name:
+            continue
+        if section == "commander":
+            profile["commanders"][card_name] = qty
+            if not profile["commander"]:
+                profile["commander"] = card_name
+        elif section != "sideboard":
+            profile["mainboard"][card_name] = qty
+    if commander_override:
+        profile["commander"] = commander_override
+        if not profile["commanders"]:
+            if commander_override in profile["mainboard"]:
+                qty = profile["mainboard"].pop(commander_override)
+                profile["commanders"][commander_override] = qty
+            else:
+                profile["commanders"][commander_override] = 1
+    if profile["commander"]:
+        profile["name"] = f"{profile['commander']} \u2014 Text Import"
+    profile["totalCards"] = sum(profile["commanders"].values()) + sum(profile["mainboard"].values())
+    return profile
+
+
+def _save_profile_to_dck(profile: dict) -> Path:
+    lines = ["[metadata]", f"Name={profile.get('name', 'Imported Deck')}", "", "[Commander]"]
+    for name, qty in profile.get("commanders", {}).items():
+        lines.append(f"{qty} {name}")
+    lines += ["", "[Main]"]
+    for name, qty in profile.get("mainboard", {}).items():
+        lines.append(f"{qty} {name}")
+    content = "\n".join(lines)
+    safe_name = re.sub(r"[^a-zA-Z0-9 _-]", "", profile.get("name", "imported")).replace(" ", "_").strip()
+    if not safe_name:
+        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")
+        os.makedirs(save_dir, exist_ok=True)
+    out_path = Path(save_dir) / f"{safe_name}.dck"
+    out_path.write_text(content, encoding="utf-8")
+    log_collect.info(f" Saved .dck: {out_path}")
+    return out_path
+
+
+# EDHREC in-memory cache
+_edhrec_cache: dict = {}
+_EDHREC_CACHE_TTL = 3600
+
+
+def _edhrec_cache_get(key: str):
+    entry = _edhrec_cache.get(key)
+    if not entry:
+        return None
+    if time.time() - entry["ts"] > _EDHREC_CACHE_TTL:
+        del _edhrec_cache[key]
+        return None
+    return entry["data"]
+
+
+def _edhrec_cache_set(key: str, data):
+    _edhrec_cache[key] = {"data": data, "ts": time.time()}

services/import_service.py

@@ -0,0 +1,110 @@
+"""Collection import service: CSV/text parsing helpers."""
+import csv
+import io
+import re
+from typing import Optional
+
+
+def _parse_finish(raw: str) -> str:
+    if not raw:
+        return "NORMAL"
+    r = raw.strip().lower()
+    if r in ("etched", "foil etched", "foil_etched", "etched foil"):
+        return "ETCHED"
+    if r in ("yes", "foil", "true", "1"):
+        return "FOIL"
+    return "NORMAL"
+
+
+def _parse_text_line(line: str) -> dict:
+    line = line.strip()
+    if not line or line.startswith("#") or line.startswith("//"):
+        return {}
+    result = {"name": "", "quantity": 1, "set_code": "", "collector_number": ""}
+    qty_match = re.match(r"^(\d+)x?\s+", line)
+    if qty_match:
+        result["quantity"] = int(qty_match.group(1))
+        line = line[qty_match.end():]
+    bracket_match = re.search(r"\[([A-Za-z0-9]+):(\S+)\]\s*$", line)
+    if bracket_match:
+        result["set_code"] = bracket_match.group(1).lower()
+        result["collector_number"] = bracket_match.group(2)
+        result["name"] = line[:bracket_match.start()].strip()
+        return result
+    paren_coll_match = re.search(r"\(([A-Za-z0-9]+)\)\s+(\S+)\s*$", line)
+    if paren_coll_match:
+        result["set_code"] = paren_coll_match.group(1).lower()
+        result["collector_number"] = paren_coll_match.group(2)
+        result["name"] = line[:paren_coll_match.start()].strip()
+        return result
+    paren_match = re.search(r"\(([A-Za-z0-9]+)\)\s*$", line)
+    if paren_match:
+        result["set_code"] = paren_match.group(1).lower()
+        result["name"] = line[:paren_match.start()].strip()
+        return result
+    result["name"] = line.strip()
+    return result
+
+
+def _auto_infer_mapping(headers: list) -> dict:
+    mapping = {}
+    header_lower = {h: h.lower().strip() for h in headers}
+    field_patterns = {
+        "name": ["name", "card name", "card_name", "cardname", "title"],
+        "quantity": ["quantity", "qty", "count", "amount", "number", "#"],
+        "set_code": ["set", "set code", "set_code", "edition", "set_name", "edition code"],
+        "collector_number": ["collector number", "collector_number", "collectornumber", "col #", "col#", "number", "card number"],
+        "finish": ["finish", "foil", "printing", "treatment"],
+        "condition": ["condition", "cond", "grade"],
+        "language": ["language", "lang", "locale"],
+        "notes": ["notes", "note", "comments", "comment"],
+        "tags": ["tags", "tag", "labels", "label"],
+    }
+    for header, lower_h in header_lower.items():
+        for field, patterns in field_patterns.items():
+            if lower_h in patterns:
+                mapping[header] = field
+                break
+    return mapping
+
+
+def _parse_csv_content(content: str, source: str, mapping: Optional[dict]) -> list:
+    rows = []
+    if (source or "").upper() == "TEXT":
+        for line in content.splitlines():
+            parsed = _parse_text_line(line)
+            if parsed.get("name"):
+                rows.append(parsed)
+        return rows
+    reader = csv.DictReader(io.StringIO(content))
+    headers = reader.fieldnames or []
+    col_map = {h: (mapping.get(h, "") if mapping else "") for h in headers}
+    if not mapping:
+        col_map = _auto_infer_mapping(headers)
+    col_map = {h: (v.lower() if isinstance(v, str) else v) for h, v in col_map.items()}
+    for csv_row in reader:
+        row = {"name": "", "quantity": 1, "set_code": "", "collector_number": "",
+               "finish": "NORMAL", "condition": "", "language": "", "notes": "", "tags": ""}
+        for header, field in col_map.items():
+            val = csv_row.get(header, "").strip()
+            if not val or field == "ignore" or not field:
+                continue
+            if field == "name":
+                val = re.sub(r"\s*\(foil(?: etched)?\)\s*$", "", val, flags=re.IGNORECASE).strip()
+                row["name"] = val
+            elif field == "quantity":
+                try:
+                    row["quantity"] = int(float(val))
+                except ValueError:
+                    row["quantity"] = 1
+            elif field in ("set_code", "set_code_secondary"):
+                row["set_code"] = val.lower()
+            elif field in ("collector_number", "collector_number_secondary"):
+                row["collector_number"] = val
+            elif field == "finish":
+                row["finish"] = _parse_finish(val)
+            elif field in ("condition", "language", "notes", "tags"):
+                row[field] = val
+        if row["name"]:
+            rows.append(row)
+    return rows

services/precon_service.py

@@ -0,0 +1,230 @@
+"""Precon deck download, caching, and conversion logic."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import time
+from collections import Counter
+from pathlib import Path
+from urllib.request import urlopen, Request
+
+log = logging.getLogger("commander_ai_lab.api")
+
+# Fallback default — used only when CFG.precon_dir has not been resolved yet.
+_DEFAULT_PRECON_DIR = Path(__file__).parent.parent / "precon-decks"
+
+PRECON_INDEX: list[dict] = []
+GITHUB_PRECON_URL = (
+    "https://raw.githubusercontent.com/taw/magic-preconstructed-decks-data/"
+    "master/decks_v2.json"
+)
+PRECON_CACHE_HOURS = 168
+_SCRYFALL_COLLECTION_URL = "https://api.scryfall.com/cards/collection"
+
+
+def _get_precon_dir() -> Path:
+    """Return the active precon-decks directory from CFG, with fallback."""
+    from models.state import CFG
+    if CFG.precon_dir:
+        return Path(CFG.precon_dir)
+    return _DEFAULT_PRECON_DIR
+
+
+# Re-export for backwards compat — callers that import PRECON_DIR at module
+# level will get the default.  Runtime code should call _get_precon_dir().
+PRECON_DIR = _DEFAULT_PRECON_DIR
+
+
+def load_precon_index():
+    """Load precon index from disk into the shared PRECON_INDEX list.
+
+    We mutate the list in-place (clear + extend) so that any module that
+    captured a reference via ``from precon_service import PRECON_INDEX``
+    will see the updated contents.
+    """
+    precon_dir = _get_precon_dir()
+    idx_path = precon_dir / "precon-index.json"
+    if idx_path.exists():
+        with open(idx_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        PRECON_INDEX.clear()
+        PRECON_INDEX.extend(data)
+        log.info(f"  Precons: {len(PRECON_INDEX)} precon decks loaded")
+    else:
+        PRECON_INDEX.clear()
+        log.info(f"  Precons: index not found at {idx_path}")
+
+
+def _sanitize_filename(name: str) -> str:
+    safe = re.sub(r'[<>:"/\\|?*]', '', name)
+    safe = safe.replace(' ', '_').replace("'", '').replace('!', '')
+    return re.sub(r'_+', '_', safe).strip('_')
+
+
+def _deck_to_dck(deck_data: dict) -> str:
+    lines = ["[metadata]", f"Name={deck_data['name']}"]
+    commanders = deck_data.get('commander', [])
+    if commanders:
+        lines.append("[Commander]")
+        for card in commanders:
+            lines.append(f"{card.get('count', 1)} {card['name']}")
+    cards = deck_data.get('cards', [])
+    if cards:
+        lines.append("[Main]")
+        for card in cards:
+            lines.append(f"{card.get('count', 1)} {card['name']}")
+    sideboard = deck_data.get('sideboard', [])
+    if sideboard:
+        lines.append("[Sideboard]")
+        for card in sideboard:
+            lines.append(f"{card.get('count', 1)} {card['name']}")
+    return "\n".join(lines) + "\n"
+
+
+def download_precon_database(force: bool = False) -> dict:
+    """Download precon database from GitHub and populate PRECON_INDEX.
+
+    We mutate the list in-place (clear + extend) so that any module that
+    captured a reference via ``from precon_service import PRECON_INDEX``
+    will see the updated contents.
+    """
+    precon_dir = _get_precon_dir()
+    idx_path = precon_dir / "precon-index.json"
+    if not force and idx_path.exists():
+        try:
+            with open(idx_path, "r", encoding="utf-8") as f:
+                existing = json.load(f)
+            if len(existing) > 50:
+                # Invalidate cache if missing enrichment fields (imageUrl, colors)
+                has_enrichment = existing[0].get("imageUrl") or existing[0].get("colors")
+                age_hours = (time.time() - idx_path.stat().st_mtime) / 3600
+                if has_enrichment and age_hours < PRECON_CACHE_HOURS:
+                    log.info(f"  Precons: {len(existing)} decks cached ({age_hours:.0f}h old)")
+                    PRECON_INDEX.clear()
+                    PRECON_INDEX.extend(existing)
+                    return {"downloaded": 0, "skipped": True, "total": len(existing), "error": None}
+                if not has_enrichment:
+                    log.info("  Precons: Cache missing enrichment data, re-downloading...")
+        except Exception:
+            pass
+    log.info("  Precons: Downloading full precon database from GitHub...")
+    try:
+        req = Request(GITHUB_PRECON_URL, headers={"User-Agent": "CommanderAILab/3.0"})
+        with urlopen(req, timeout=120) as resp:
+            all_decks = json.loads(resp.read())
+    except Exception as e:
+        msg = f"Failed to download precon database: {e}"
+        log.error(f"  Precons: ERROR - {msg}")
+        if idx_path.exists():
+            load_precon_index()
+        return {"downloaded": 0, "skipped": False, "error": msg}
+    commander_decks = [
+        d for d in all_decks
+        if d.get('type') == 'Commander Deck'
+        and (d.get('format') or '').lower() == 'commander'
+    ]
+    log.info(f"  Precons: Found {len(commander_decks)} Commander precon decks")
+    precon_dir.mkdir(parents=True, exist_ok=True)
+    name_counts = Counter(_sanitize_filename(d['name']) for d in commander_decks)
+    dup_names = {n for n, c in name_counts.items() if c > 1}
+    index = []
+    written = 0
+    for deck in sorted(commander_decks, key=lambda d: (d.get('release_date', ''), d.get('name', ''))):
+        safe_name = _sanitize_filename(deck['name'])
+        if safe_name in dup_names:
+            sc = (deck.get('set_code') or 'unk').upper()
+            safe_name = f"{safe_name}_{sc}"
+        file_name = f"{safe_name}.dck"
+        dck_path = precon_dir / file_name
+        commanders = deck.get('commander', [])
+        cmdr_names = [c['name'] for c in commanders] if commanders else []
+        # Build Scryfall art_crop image URL from first commander's set/number
+        image_url = ""
+        if commanders:
+            c0 = commanders[0]
+            sc = (c0.get('set_code') or '').lower()
+            num = c0.get('number', '')
+            if sc and num:
+                image_url = f"https://api.scryfall.com/cards/{sc}/{num}?format=image&version=art_crop"
+        total_cards = sum(c.get('count', 1) for c in deck.get('cards', [])) + sum(c.get('count', 1) for c in commanders)
+        with open(dck_path, "w", encoding="utf-8") as f:
+            f.write(_deck_to_dck(deck))
+        written += 1
+        release = deck.get('release_date', '')
+        year = int(release[:4]) if release and len(release) >= 4 else 0
+        index.append({
+            "name": deck['name'], "commander": cmdr_names[0] if cmdr_names else "Unknown",
+            "commanders": cmdr_names, "colors": [],
+            "set": deck.get('set_name', ''), "setCode": deck.get('set_code', ''),
+            "year": year, "releaseDate": release, "theme": "",
+            "fileName": file_name, "cardCount": total_cards,
+            "imageUrl": image_url,
+        })
+    # Enrich with color identity from Scryfall (best-effort)
+    _enrich_colors(index)
+    with open(idx_path, "w", encoding="utf-8") as f:
+        json.dump(index, f, indent=2, ensure_ascii=False)
+    PRECON_INDEX.clear()
+    PRECON_INDEX.extend(index)
+    log.info(f"  Precons: {written} .dck files written, index saved")
+    return {"downloaded": written, "skipped": False, "total": written, "error": None}
+
+
+def _enrich_colors(index: list[dict]) -> None:
+    """Batch-fetch color_identity for commanders via Scryfall /cards/collection.
+
+    Scryfall accepts up to 75 identifiers per request.  We look up each unique
+    commander name once, then propagate the result to every index entry.
+    """
+    # Build unique commander -> identifiers map
+    cmdr_lookup: dict[str, dict] = {}   # name -> {"name": ...}
+    for entry in index:
+        name = entry.get("commander", "")
+        if name and name != "Unknown" and name not in cmdr_lookup:
+            cmdr_lookup[name] = {"name": name}
+    if not cmdr_lookup:
+        return
+
+    names = list(cmdr_lookup.keys())
+    color_map: dict[str, list[str]] = {}  # commander name -> ["W","U",...]
+
+    # Batch in chunks of 75
+    for i in range(0, len(names), 75):
+        batch = [{"name": n} for n in names[i:i + 75]]
+        try:
+            payload = json.dumps({"identifiers": batch}).encode("utf-8")
+            req = Request(
+                _SCRYFALL_COLLECTION_URL,
+                data=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "User-Agent": "CommanderAILab/3.0",
+                },
+                method="POST",
+            )
+            with urlopen(req, timeout=30) as resp:
+                result = json.loads(resp.read())
+            for card in result.get("data", []):
+                cname = card.get("name", "")
+                ci = card.get("color_identity", [])
+                if cname and ci:
+                    color_map[cname] = ci
+                    # Handle double-faced names: "A // B" -> also store "A"
+                    if " // " in cname:
+                        front = cname.split(" // ")[0]
+                        color_map[front] = ci
+            # Respect Scryfall rate limit (100ms between requests)
+            time.sleep(0.15)
+        except Exception as e:
+            log.warning(f"  Precons: Scryfall color lookup failed for batch {i}: {e}")
+
+    # Apply colors to index entries
+    enriched = 0
+    for entry in index:
+        name = entry.get("commander", "")
+        if name in color_map:
+            entry["colors"] = color_map[name]
+            enriched += 1
+    log.info(f"  Precons: Enriched {enriched}/{len(index)} decks with color identity")

services/scryfall.py

@@ -0,0 +1,216 @@
+"""Scryfall API client and cache service."""
+import json
+import os
+import sqlite3
+import threading
+import time
+import datetime
+from pathlib import Path
+from typing import Optional
+from urllib.request import Request, urlopen
+
+# Lazy import to avoid circular dependency
+def _detect_card_roles(oracle_text, type_line, keywords):
+    from services.card_analysis import _detect_card_roles as _dcr
+    return _dcr(oracle_text, type_line, keywords)
+
+
+SCRYFALL_CACHE_DB_PATH = Path(__file__).parent.parent / "scryfall_cache.db"
+SCRYFALL_CACHE_TTL_SECONDS = int(os.environ.get("SCRYFALL_CACHE_TTL", 7 * 24 * 3600))
+
+_API_HEADERS = {"User-Agent": "CommanderAILab/3.0", "Accept": "application/json"}
+
+
+class _ScryfallCache:
+    def __init__(self, db_path: Path = None, ttl_seconds: int = None):
+        self._db_path = db_path or SCRYFALL_CACHE_DB_PATH
+        self._ttl = ttl_seconds or SCRYFALL_CACHE_TTL_SECONDS
+        self._lock = threading.Lock()
+        self._conn: Optional[sqlite3.Connection] = None
+        self._hits = 0
+        self._misses = 0
+        self._init_db()
+
+    def _init_db(self):
+        self._conn = sqlite3.connect(str(self._db_path), check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS scryfall_cache (
+                cache_key  TEXT PRIMARY KEY,
+                json_blob  TEXT    NOT NULL,
+                fetched_at TEXT    NOT NULL DEFAULT (datetime('now'))
+            )
+        """)
+        self._conn.commit()
+
+    @staticmethod
+    def _make_key(name: str, set_code: str, collector_number: str) -> str:
+        return f"{name.strip().lower()}|{(set_code or '').strip().lower()}|{(collector_number or '').strip()}"
+
+    def get(self, name: str, set_code: str = "", collector_number: str = "") -> Optional[dict]:
+        key = self._make_key(name, set_code, collector_number)
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT json_blob FROM scryfall_cache WHERE cache_key = ?", (key,)
+            ).fetchone()
+        if row:
+            self._hits += 1
+            return json.loads(row[0])
+        self._misses += 1
+        return None
+
+    def put(self, name: str, set_code: str, collector_number: str, data: dict):
+        key = self._make_key(name, set_code, collector_number)
+        blob = json.dumps(data)
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO scryfall_cache (cache_key, json_blob) VALUES (?, ?)",
+                (key, blob),
+            )
+            self._conn.commit()
+
+    def stats(self) -> dict:
+        with self._lock:
+            count = self._conn.execute("SELECT COUNT(*) FROM scryfall_cache").fetchone()[0]
+        return {"cached": count, "hits": self._hits, "misses": self._misses}
+
+    def clear(self) -> int:
+        with self._lock:
+            count = self._conn.execute("SELECT COUNT(*) FROM scryfall_cache").fetchone()[0]
+            self._conn.execute("DELETE FROM scryfall_cache")
+            self._conn.commit()
+            self._conn.execute("VACUUM")
+            self._hits = 0; self._misses = 0
+        return count
+
+    def evict_expired(self) -> int:
+        cutoff = datetime.datetime.utcnow().isoformat()
+        with self._lock:
+            self._conn.execute(
+                "DELETE FROM scryfall_cache WHERE (julianday(?) - julianday(fetched_at)) * 86400 > ?",
+                (cutoff, self._ttl),
+            )
+            deleted = self._conn.total_changes
+            self._conn.commit()
+        return deleted
+
+
+_scryfall_cache = _ScryfallCache()
+_scryfall_lock = threading.Lock()
+_scryfall_last_call = 0.0
+
+
+def _scryfall_rate_limit():
+    global _scryfall_last_call
+    with _scryfall_lock:
+        now = time.monotonic()
+        elapsed = now - _scryfall_last_call
+        if elapsed < 0.1:
+            time.sleep(0.1 - elapsed)
+        _scryfall_last_call = time.monotonic()
+
+
+def _fetch_scryfall_api(name: str, set_code: str = "", collector_number: str = "") -> dict:
+    from urllib.parse import quote
+    cached = _scryfall_cache.get(name, set_code, collector_number)
+    if cached is not None:
+        return cached
+    card_data = None
+    last_error = ""
+    if set_code and collector_number:
+        _scryfall_rate_limit()
+        try:
+            url = f"https://api.scryfall.com/cards/{set_code.lower()}/{collector_number}"
+            with urlopen(Request(url, headers=_API_HEADERS), timeout=10) as resp:
+                card_data = json.loads(resp.read().decode("utf-8"))
+        except Exception as e:
+            last_error = str(e); card_data = None
+    if not card_data:
+        _scryfall_rate_limit()
+        try:
+            url = f"https://api.scryfall.com/cards/named?exact={quote(name)}"
+            with urlopen(Request(url, headers=_API_HEADERS), timeout=10) as resp:
+                card_data = json.loads(resp.read().decode("utf-8"))
+        except Exception as e:
+            last_error = str(e)
+    if not card_data or card_data.get("object") == "error":
+        err_detail = card_data.get("details", "unknown error") if card_data else last_error
+        return {"_error": f"Scryfall returned error for '{name}': {err_detail}"}
+    _scryfall_cache.put(name, set_code, collector_number, card_data)
+    resolved_name = card_data.get("name", "")
+    if resolved_name and resolved_name.lower() != name.strip().lower():
+        _scryfall_cache.put(resolved_name, set_code, collector_number, card_data)
+    return card_data
+
+
+def _enrich_from_scryfall(name: str, set_code: str = "", collector_number: str = "") -> dict:
+    card_data = _fetch_scryfall_api(name, set_code, collector_number)
+    if not card_data or "_error" in card_data:
+        return card_data or {}
+    type_line = card_data.get("type_line", "")
+    color_identity = card_data.get("color_identity", [])
+    keywords = card_data.get("keywords", [])
+    subtypes = []
+    for sep in [" \u2014 ", " - "]:
+        if sep in type_line:
+            subtypes = [s.strip() for s in type_line.split(sep, 1)[1].split() if s.strip()]
+            break
+    is_legendary = 1 if "Legendary" in type_line else 0
+    is_basic = 1 if "Basic" in type_line else 0
+    prices = card_data.get("prices", {})
+    try:
+        tcg_price = float(prices.get("usd") or prices.get("usd_foil") or "0") or 0.0
+    except (ValueError, TypeError):
+        tcg_price = 0.0
+    oracle_text = card_data.get("oracle_text", "")
+    if not oracle_text and card_data.get("card_faces"):
+        oracle_text = "\n//\n".join(f.get("oracle_text", "") for f in card_data["card_faces"] if f.get("oracle_text"))
+    power = card_data.get("power", "")
+    toughness = card_data.get("toughness", "")
+    if not power and card_data.get("card_faces"):
+        power = card_data["card_faces"][0].get("power", "")
+        toughness = card_data["card_faces"][0].get("toughness", "")
+    mana_cost = card_data.get("mana_cost", "")
+    if not mana_cost and card_data.get("card_faces"):
+        mana_cost = card_data["card_faces"][0].get("mana_cost", "")
+    auto_roles = _detect_card_roles(oracle_text, type_line, keywords)
+    return {
+        "name": card_data.get("name", name),
+        "type_line": type_line,
+        "subtypes": json.dumps(subtypes),
+        "is_legendary": is_legendary,
+        "is_basic": is_basic,
+        "color_identity": json.dumps(color_identity),
+        "cmc": card_data.get("cmc", 0.0),
+        "mana_cost": mana_cost,
+        "oracle_text": oracle_text,
+        "keywords": json.dumps(keywords),
+        "power": power or "",
+        "toughness": toughness or "",
+        "rarity": card_data.get("rarity", ""),
+        "set_name": card_data.get("set_name", ""),
+        "edhrec_rank": card_data.get("edhrec_rank", 0) or 0,
+        "tcg_price": tcg_price,
+        "salt_score": 0.0,
+        "is_game_changer": 0,
+        "category": json.dumps(auto_roles),
+        "scryfall_id": card_data.get("id", ""),
+        "tcgplayer_id": str(card_data.get("tcgplayer_id", "")),
+    }
+
+
+def _scryfall_fuzzy_lookup(name: str) -> Optional[dict]:
+    """Fuzzy-search Scryfall for a card name. Returns raw Scryfall JSON dict, or None on failure."""
+    from urllib.parse import quote
+    _scryfall_rate_limit()
+    try:
+        encoded = quote(name)
+        url = f"https://api.scryfall.com/cards/named?fuzzy={encoded}"
+        req = Request(url, headers=_API_HEADERS)
+        with urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            if data.get("object") == "error":
+                return None
+            return data
+    except Exception:
+        return None