arenamcp 2.8.0__tar.gz

arenamcp-2.8.0/.env.example

@@ -0,0 +1,28 @@
+# mtgacoach Configuration
+# Copy this file to .env and configure as needed
+
+# License key for online mode (mtgacoach.com)
+# Get yours at https://mtgacoach.com/subscribe
+# Can also be set via the TUI with: /key YOUR_LICENSE_KEY
+# MTGACOACH_LICENSE_KEY=
+
+# Local model configuration (vLLM by default; Ollama / LM Studio also supported)
+# These can also be set via the TUI with: /local
+# Default vLLM chat endpoint:
+# LOCAL_URL=http://localhost:8000/v1
+# LOCAL_MODEL=gemma4:e2b
+# To fall back to Ollama, point LOCAL_URL at port 11434 instead:
+# LOCAL_URL=http://localhost:11434/v1
+# LOCAL_MODEL=llama3.2
+
+# Optional embeddings endpoint (vLLM container at :8001 serving nomic-embed-text)
+# EMBEDDING_URL=http://localhost:8001/v1
+# EMBEDDING_MODEL=nomic-embed-text
+
+# Launcher maintenance
+# Automatically trim Player.log before launch when MTGA is not already running.
+ARENAMCP_TRIM_PLAYER_LOG=1
+# Trim when Player.log exceeds this size in MB.
+ARENAMCP_PLAYER_LOG_MAX_MB=64
+# Keep the newest tail of Player.log at this size in MB.
+ARENAMCP_PLAYER_LOG_KEEP_MB=8

arenamcp-2.8.0/.github/workflows/installer.yml

@@ -0,0 +1,88 @@
+name: build-installer
+
+# Builds mtgacoach-Setup.exe on a Windows runner and attaches it to the
+# release for the pushed tag, alongside the Python wheel (.whl) artifact.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Existing release tag to attach the installer to (e.g. v2.4.0)"
+        required: false
+        default: ""
+
+jobs:
+  installer:
+    runs-on: windows-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build hatchling pyinstaller
+          pip install -e .[desktop,full]
+
+      - name: Build Python wheel
+        run: python -m build --wheel
+
+      - name: Build standalone executable (PyInstaller)
+        run: pyinstaller mtgacoach.spec --noconfirm
+
+      - name: Install Inno Setup
+        run: choco install innosetup --no-progress -y
+
+      - name: Build installer
+        shell: pwsh
+        run: |
+          # Version source of truth: src/arenamcp/__init__.py. pyproject.toml
+          # uses hatch dynamic versioning and has no literal `version = "..."`
+          # line, so the old fallback could never resolve a version.
+          $versionMatch = Select-String -Path "src\arenamcp\__init__.py" -Pattern '^\s*__version__\s*=\s*"([^"]+)"' | Select-Object -First 1
+          if (-not $versionMatch) { throw "Could not read __version__ from src/arenamcp/__init__.py" }
+          $packageVersion = $versionMatch.Matches[0].Groups[1].Value
+
+          $version = "${{ inputs.release_tag || github.ref_name }}".TrimStart("v")
+          if ($version -notmatch '^\d') { $version = $packageVersion }
+          if ($version -ne $packageVersion) {
+            Write-Host "::warning::Release tag version '$version' does not match package __version__ '$packageVersion' - the installer asset will be stamped '$version'."
+          }
+
+          & "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" /DAppVersion=$version installer\mtgacoach.iss
+          if (-not (Test-Path dist\installer\mtgacoach-Setup.exe)) { throw "installer not produced" }
+
+      - name: Attach to release
+        if: startsWith(github.ref, 'refs/tags/') || inputs.release_tag != ''
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          $tag = "${{ inputs.release_tag }}"
+          if (-not $tag) { $tag = "${{ github.ref_name }}" }
+          gh release upload "$tag" dist/installer/mtgacoach-Setup.exe --clobber
+          Get-ChildItem -Path dist\*.whl | ForEach-Object {
+            gh release upload "$tag" $_.FullName --clobber
+          }
+
+      - name: Upload installer artifact (non-tag runs)
+        if: ${{ !startsWith(github.ref, 'refs/tags/') && inputs.release_tag == '' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: mtgacoach-Setup
+          path: dist/installer/mtgacoach-Setup.exe
+
+      - name: Upload wheel artifact (non-tag runs)
+        if: ${{ !startsWith(github.ref, 'refs/tags/') && inputs.release_tag == '' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: mtgacoach-wheel
+          path: dist/*.whl
+

arenamcp-2.8.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,46 @@
+name: publish-pypi
+
+# Publishes arenamcp to PyPI when a GitHub Release is published, using PyPI
+# Trusted Publishing (OIDC) — no API token is stored anywhere.
+#
+# ONE-TIME SETUP (pypi.org web UI): Account → Publishing → "Add a new
+# pending publisher":
+#   PyPI project name: arenamcp
+#   Owner:            josharmour
+#   Repository:       mtgacoach
+#   Workflow name:    publish-pypi.yml
+#   Environment:      pypi
+# After the first successful publish the pending publisher becomes permanent.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

arenamcp-2.8.0/.github/workflows/tests.yml

@@ -0,0 +1,67 @@
+name: tests
+
+# The single CI workflow: one pytest run, one ruff run, per push/PR.
+#
+# 2026-07-24 consolidation: this ran alongside ci.yml, and BOTH executed the
+# full ~700-test suite on every push to master with divergent configs
+# (ci.yml: Python 3.11 + .[dev,full]; tests.yml: Python 3.12 + .[dev]).
+# That doubled CI cost and, worse, meant a change could be green in one
+# environment and red in the other. ci.yml has been removed; its
+# dev+full extras (which match the local dev environment the test baseline
+# is measured in) were folded in here.
+#
+# Platform-specific tests (Windows/macOS-only) rely on their own skip guards.
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      # sounddevice -> portaudio, soundfile -> libsndfile, PySide6 offscreen -> GL/xkb
+      - name: System dependencies (Qt offscreen + audio libs)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libportaudio2 libsndfile1 \
+            libgl1 libegl1 libxkbcommon0 libdbus-1-3 libfontconfig1
+
+      - name: Install package with dev + full extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,full]"
+
+      - name: Run tests
+        env:
+          ARENAMCP_LOG_FILE: /tmp/arenamcp-pytest.log
+          QT_QPA_PLATFORM: offscreen
+        run: python -m pytest tests -q --tb=short
+
+  ruff:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      # Pinned: the repo is formatted with 0.15.22. Older pins format
+      # differently (0.15.2) or cannot parse [tool.ruff.lint] at all (0.6.9
+      # rejects the UP045 selector), so an unpinned/stale ruff fails CI on
+      # correctly-formatted code.
+      - uses: astral-sh/ruff-action@v3
+        with:
+          version: "0.15.22"
+      - run: ruff check src tests
+      - run: ruff format --check src tests

arenamcp-2.8.0/.gitignore

@@ -0,0 +1,69 @@
+.env
+.env.*
+!.env.example
+tmpclaude-*
+__pycache__/
+.venv/
+tools/training/wp3/scryfall_cache.json
+tools/training/data/wp3/
+*.pyc
+debug_log.txt
+log_tail.txt
+last_match_event.txt
+build/
+dist/
+*.egg-info/
+.codex/
+.claude/
+re-output/
+nul
+@eaDir/
+*.planning/
+bug_reports/
+# Synology/deployment configs
+docker-compose.yml
+config.yaml
+*.db
+data/
+# ...except tracked infra-as-code (no secrets; env refs only)
+!gateway/config.yaml
+!gateway/docker-compose.yml
+!website/config.yaml
+!website/docker-compose.yml
+# Dev-only (not for public repo)
+rl-pipeline-fix.md
+tools/*
+!tools/training/
+!tools/monitoring/
+tools/monitoring/*
+!tools/monitoring/grafana/
+tools/training/checkpoints/
+tools/training/data/
+!tools/eval/
+tools/eval/data/
+!tools/monitoring/
+docs/
+CLAUDE.md
+*.spec
+venv/
+.venv/
+.venv_*/
+test_env/
+# BepInEx plugin build artifacts
+bepinex-plugin/**/bin/
+bepinex-plugin/**/obj/
+.DS_Store
+stage0v2_31b_train.log
+*_train.log
+models/
+
+# Dev-machine scratch, deliberately untracked (2026-07-27):
+#   launch.sh     — hardcodes the old WSL path /home/joshu/repos/mtgacoach
+#   run_update.py — one-shot regex migration that REWRITES src/arenamcp/server.py
+#                   in place; its edits are already merged. Keeping it runnable
+#                   in the repo is a footgun, not history.
+launch.sh
+run_update.py
+
+# Local grading worksheet (contains replay-derived game states; not for the public repo)
+tripwire_review_v2.md

arenamcp-2.8.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+# Pre-commit hooks — install with: pre-commit install
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.22
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # mypy is advisory-only until the baseline is cleaned up module-by-module.
+  # Enable locally with: pre-commit run mypy --all-files
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        pass_filenames: false
+        args: [--config-file=pyproject.toml]
+        # Not wired to block commits yet — run manually.
+        stages: [manual]

arenamcp-2.8.0/AGENTS.md

@@ -0,0 +1,87 @@
+# ArenaMCP — Agent Guidance
+
+## Project
+Real-time AI coaching for MTG Arena with in-game overlay (BepInEx-driven ground-truth card positions).  
+Python package `arenamcp` under `src/arenamcp/`, desktop PySide6 GUI at `src/arenamcp/desktop/`, BepInEx C# plugin at `bepinex-plugin/MtgaCoachBridge/`.
+
+## Key Architecture
+- **`launcher.py`** — internal TUI runtime launcher (subprocess-based, restarts on exit code 42)
+- **`windows_integration.py`** — Windows install/repair helpers (stdlib-only)
+- **`src/arenamcp/desktop/app.py`** — PySide6 desktop app entrypoint (main entry for users)
+- **`src/arenamcp/server.py`** — FastMCP server bridging MTGA logs to LLM
+- **`src/arenamcp/coach.py`** — Coach engine with pluggable LLM backends
+- **`src/arenamcp/standalone.py`** — TUI/"standalone" client (voice + MCP client)
+- **`src/arenamcp/autopilot.py`** — AI autoplay engine
+- **`tests/`** — pytest test suite (600+ tests)
+
+## Sister Repository: MageZero RL Training (`~/repos/magezero`)
+`mtgacoach` is paired with **`magezero`**, an AlphaZero-style MCTS reinforcement learning engine running inside an instrumented XMage simulator on `blackwell` (`10.0.0.10`).
+- **Role Split**: `mtgacoach` handles live MTG Arena coaching, GRE state extraction, and HUD overlay. `magezero` trains deck-specific policy/value neural networks via distributed self-play.
+- **Canonical RL Docs**: For RL architecture, hardware topology (R9700 vs RTX 6000s), live training status, and strategy, refer directly to `~/repos/magezero/AGENTS.md` and `~/repos/magezero/docs/PLAN_OF_RECORD.md`.
+- **Telemetry Command**: Inspect the live training run on blackwell via:
+  ```bash
+  ssh joshu@10.0.0.10 'python3 -c "import json, pathlib; runs=sorted(pathlib.Path(\"/home/joshu/repos/magezero/runs\").glob(\"*/run.json\")); d=json.loads(runs[-1].read_text()); print(f\"Run {runs[-1].parent.name} | Gen {d.get(\"current_gen\")} | Stage: {d.get(\"stage\")}\")"'
+  ```
+
+## Developer Commands
+```bash
+# Install (editable, with all extras)
+pip install -e .[dev,full]
+
+# Run tests (isolated log file via ARENAMCP_LOG_FILE env var)
+pytest tests -q
+
+# Run diagnostics
+python -m arenamcp.diagnose
+
+# Launch desktop app (Linux dev)
+PYTHONPATH=src python -m arenamcp.desktop
+
+# Launch standalone TUI
+python -m arenamcp.standalone --backend online
+```
+
+## Local venvs (macOS dev machine)
+- `.venv_mac_311/` — Python 3.11, the working macOS venv (pip, pytest, editable arenamcp). Use this on mac.
+- `.venv/` — Linux/WSL-era venv; pip shebang broken on macOS (points at old ArenaMCP path).
+- Deleted 2026-07-22: `.venv_mac/`, `test_env/` (Python 3.9 — below requires-python >=3.10).
+
+## Tooling (added 2026-07-22)
+- **ruff** (lint + format) and **mypy** (advisory) — configs in `pyproject.toml`.
+- **pre-commit** — `.pre-commit-config.yaml`; `pre-commit install` to enable.
+- **CI** — `.github/workflows/tests.yml` runs ruff + pytest on push/PR (installer.yml unchanged).
+- Version single-sourced in `src/arenamcp/__init__.py` (`__version__`); pyproject reads it via hatch dynamic versioning.
+
+## BepInEx C# Plugin (Linux dev)
+- **Do NOT** use Wine's `csc` — too old for C# 9.0.
+- Use `dotnet` (`.NET 10 SDK` installed).
+- Override `MtgaDir` for Flatpak Steam:
+  ```bash
+  cd bepinex-plugin/MtgaCoachBridge
+  dotnet build -p:MtgaDir="/home/joshu/.var/app/com.valvesoftware.Steam/.local/share/Steam/steamapps/common/MTGA"
+  ```
+- Deploy: copy `bin/Debug/net472/MtgaCoachBridge.dll` to MTGA's `BepInEx/plugins/`.
+
+## Testing Quirks
+- `conftest.py` redirects `ARENAMCP_LOG_FILE` to `/tmp/arenamcp-pytest.log` so test noise doesn't pollute `~/.arenamcp/standalone.log`.
+- No linter/formatter config in `pyproject.toml` (only pytest dependency). No pre-commit, no typechecker configured.
+- CI only builds Windows installer via GitHub Actions (`.github/workflows/installer.yml`).
+
+## Packaging
+- **`hatchling`** build backend, single package `src/arenamcp`
+- GUI entrypoint: `mtgacoach-desktop = "arenamcp.desktop.app:main"`
+- Installer: Inno Setup script at `installer/mtgacoach.iss`, built only on `windows-latest` runner (tag push `v*` or `workflow_dispatch`).
+
+## Log Locations (Windows)
+| Log | Path |
+|-----|------|
+| Desktop UI | `%LOCALAPPDATA%\mtgacoach\desktop.log` |
+| Launcher | `%LOCALAPPDATA%\mtgacoach\desktop-launch.log` |
+| Coach runtime | `%USERPROFILE%\.arenamcp\standalone.log` |
+| Bug reports | `%USERPROFILE%\.arenamcp\bug_reports\bug_*.json` |
+| BepInEx | `<MTGA>\BepInEx\LogOutput.log` |
+
+## Development Flow
+- Edits under `src/arenamcp/` take effect on next launch (no C# rebuild needed).
+- `launch.bat` is the canonical Windows entrypoint for repo/manual installs.
+- The coaching engine runs as a subprocess over a JSON pipe protocol (separate from the UI process).

arenamcp-2.8.0/DEV.md

@@ -0,0 +1,85 @@
+# Development Workflow
+
+Use exactly one desktop app during development: the PySide6 app in this repo.
+
+## One-Time Setup
+
+Run this command on Windows:
+
+```powershell
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe -m pip install -e Z:\mtgacoach[desktop]
+```
+
+`pip install -e` is important: the desktop app runs directly from the repo source tree.
+`[desktop]` now includes the PySide app plus Kokoro desktop-worker dependencies.
+
+This repo already contains a Linux `.venv` for WSL work. Do not try to use `Z:\mtgacoach\.venv` as the Windows launch environment.
+
+## Launch
+
+Use exactly one launch target:
+
+```powershell
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\pythonw.exe Z:\mtgacoach\scripts\launch_desktop.py
+```
+
+Recommended shortcut target:
+
+- `C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\pythonw.exe`
+
+Recommended shortcut arguments:
+
+- `Z:\mtgacoach\scripts\launch_desktop.py`
+
+Recommended shortcut "Start in":
+
+- `Z:\mtgacoach`
+
+## What Updates On Next Launch
+
+- Any edit under `src\arenamcp\` takes effect on the next app launch.
+- Any edit under `src\arenamcp\desktop\` takes effect on the next app launch.
+- No C# rebuild is part of the normal dev loop anymore.
+- Launch does not depend on the package being importable from an editable install; the launcher script adds `src\` directly.
+
+If you change Python dependencies or entrypoints, rerun:
+
+```powershell
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe -m pip install -e Z:\mtgacoach[desktop]
+```
+
+## Do Not Use During Development
+
+- `C:\Users\Public\Desktop\mtgacoach.lnk`
+- `C:\Program Files\mtgacoach\...`
+- `mtgacoach-dev.lnk`
+
+Those are no longer part of the source-iteration workflow.
+
+## Useful Commands
+
+Launch from a terminal without the GUI script wrapper:
+
+```powershell
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe -m arenamcp.desktop
+```
+
+Run tests:
+
+```powershell
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe -m pytest Z:\mtgacoach\tests -q
+```
+
+## Logs
+
+- Desktop UI log: `%LOCALAPPDATA%\mtgacoach\desktop.log`
+- Desktop launcher log: `%LOCALAPPDATA%\mtgacoach\desktop-launch.log`
+- Coach runtime log: `%USERPROFILE%\.arenamcp\standalone.log`
+- Saved bug reports: `%USERPROFILE%\.arenamcp\bug_reports\bug_*.json`
+- BepInEx log: `<MTGA>\BepInEx\LogOutput.log`
+
+## Notes
+
+- The PySide6 app is the full desktop app now: coach UI plus repair/install flows.
+- The coaching engine still runs as a subprocess internally over the existing JSON pipe protocol. That separation is intentional and keeps the UI responsive while preserving the current backend seam.
+- Customer releases come from the packaged PySide installer built by `installer\build-installer.ps1`.

arenamcp-2.8.0/GEMINI.md

@@ -0,0 +1,158 @@
+# GEMINI.md
+
+## Project Summary
+
+`mtgacoach` (`arenamcp`) is an MTGA coaching project with:
+- **Python Core (`src/arenamcp/`)**: Headless coaching engine driving the pipeline.
+- **Desktop UI (`src/arenamcp/desktop/`)**: PySide6-based frontend providing the dashboard, coaching log, repair tools, and transparent, click-through HUD overlay.
+- **BepInEx Plugin (`bepinex-plugin/MtgaCoachBridge/`)**: C# plugin injected into MTGA for direct GRE state access, action submission, and automation.
+- **Proxy Server (`website/`)**: FastAPI gateway at `api.mtgacoach.com` routing subscriber LLM requests, tracking usage, and providing an eval dashboard.
+- **LLM Evaluation Harness (`tools/eval/`)**: Harness for scoring local model quality (mulligans, turn-actions, replays) using real play prompts.
+- **Sister RL Engine (`~/repos/magezero/`)**: Independent AlphaZero-style MCTS self-play training pipeline running in XMage on `blackwell` (`10.0.0.10`). Refer to `~/repos/magezero/AGENTS.md` and `~/repos/magezero/docs/PLAN_OF_RECORD.md` for RL telemetry and status.
+
+## Core Direction & Architecture
+
+- **GRE Bridge is Primary**: Real-time game state tracking and action submissions run through the direct Unity GRE named pipe (`\\.\pipe\mtgacoach_bridge_v2`). Python acts as the named pipe server; BepInEx is the client.
+- **Log Parsing as Fallback**: `Player.log` is parsed via a log watcher only as a fallback and for out-of-match/metadata diagnostics.
+- **File System Separation**: Installed files live read-only under `Program Files\mtgacoach`, while mutable runtime files (venv, settings, logs) belong under `%LOCALAPPDATA%\mtgacoach` and `%USERPROFILE%\.arenamcp`.
+- **Local LLM Default**: Default local backend is **vLLM** (`http://localhost:8000/v1`) running `google/gemma-4-E2B-it` (aliased as `gemma4:e2b`), with fallback to Ollama (`localhost:11434`) or LM Studio.
+
+## LLM Evaluation Harness (`tools/eval/`)
+
+- Runs idempotent evaluation pipelines using captured prompts (`prompts.jsonl`).
+- **Replay Scorer (`tools/eval/replay/`)**: Replays prompts through backends (`run.py`) and scores them against judge models on **contested decisions** (decisions where the player had a choice, to prevent easy moves from inflating match rate).
+- **Mulligan Scorer**: Uses balanced accuracy (`balanced_higher_wr_rate`) to avoid keep-rate bias. Skips buckets within `MARGIN_THRESHOLD=0.05`.
+- **Turn-action Scorer**: Uses Mean Jaccard (set overlap) as the headline metric.
+- Supports WSL paths to allow running WSL evaluators against Windows MTGA paths.
+
+## Installer & Repair UX
+
+- Prefer a **small installer** built by `installer/build-installer.ps1` that packages the application and downloads/creates the venv post-install.
+- The repair UI must offer explicit user-visible actions for:
+  - `Create venv`
+  - `Setup environment`
+  - `Install BepInEx`
+  - `Install Plugin`
+  - Bridge repair / refresh actions
+
+## Release Rules
+
+When revving a release (currently version `2.7.3`):
+1. Bump version in:
+   - `pyproject.toml`
+   - `src/arenamcp/__init__.py`
+   - `installer/mtgacoach.iss`
+2. Commit changes.
+3. Tag `vX.Y.Z`.
+4. Build the installer (`build-installer.ps1`) and verify the output at `dist/installer/mtgacoach-Setup.exe`.
+5. Push master and tag.
+6. Create/update the GitHub release and upload `mtgacoach-Setup.exe`.
+
+## Common Commands
+
+### Setup & Run
+```powershell
+# Editable dev install (Windows)
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe -m pip install -e Z:\mtgacoach[desktop]
+
+# Run PySide6 app from source
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe -m arenamcp.desktop
+
+# Launch app using wrapper script
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\pythonw.exe Z:\mtgacoach\scripts\launch_desktop.py
+```
+
+### Build & Test
+```powershell
+# Run regression tests
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe -m pytest Z:\mtgacoach\tests -q
+
+# Build BepInEx plugin DLL (C#)
+cd bepinex-plugin/MtgaCoachBridge && dotnet build -c Release
+
+# Build Windows installer from WSL
+p=$(wslpath -w /home/joshu/repos/mtgacoach/installer) && powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "\$p='${p}'; Set-Location -LiteralPath \$p; .\build-installer.ps1"
+```
+
+### Verification & Eval
+```powershell
+# Verify local vLLM endpoint
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe tools/verify_vllm.py
+
+# Run replay evaluation harness
+C:\Users\joshu\AppData\Local\mtgacoach\venv\Scripts\python.exe tools/eval/replay/run.py
+```
+## Repository Directory & File Map
+
+### Top-Level Layout
+* **`src/`**: The core Python codebase (`arenamcp`). This is the heart of the backend coaching loop, logs, game-state logic, Named Pipe GRE bridge server, and PySide6 desktop UI.
+* **`bepinex-plugin/`**: The C# Unity plugin injected into Magic: The Gathering Arena. It intercepts internal game states and acts as a Named Pipe client connecting directly to Python.
+* **`website/`**: A FastAPI application running on `api.mtgacoach.com` (under Synology/Docker) that validates licenses, routes LLM requests to the LiteLLM gateway (self-hosted models only; the legacy Azure/OpenAI path is decommissioned), and serves the admin evaluation dashboard.
+* **`tools/`**: Diagnostic scripts, vLLM verification tools, and the comprehensive evaluation harness (`tools/eval/`) for measuring LLM output quality.
+* **`installer/`**: Inno Setup script (`mtgacoach.iss`) and build automation scripts (`build-installer.ps1`) to generate the lightweight Windows setup executable.
+* **`dist/`** *(Generated)*: Where release builds of the app and final installer packages are staged.
+* **`venv/`** / **`.venv/`** *(Gitignored)*: Local Python virtual environments used during WSL/Windows development.
+* **`.tools/`** / **`.vscode/`** *(Gitignored)*: IDE configuration and local development helper scripts.
+
+### Python Coaching Engine ([src/arenamcp/](file:///Z:/mtgacoach/src/arenamcp))
+
+#### Communication & Protocols
+* [pipe_adapter.py](file:///Z:/mtgacoach/src/arenamcp/pipe_adapter.py) — Establishes the JSON-over-stdio protocol used by the headless coaching subprocess to communicate back to the PySide6 desktop frontend.
+* [gre_bridge.py](file:///Z:/mtgacoach/src/arenamcp/gre_bridge.py) — Runs a local Named Pipe server (`\\.\pipe\mtgacoach_bridge_v2`) to exchange game snapshots and execute automation actions with the BepInEx Unity plugin.
+* [gre_serializer.py](file:///Z:/mtgacoach/src/arenamcp/gre_serializer.py) — Protobuf JSON translator for GRE events.
+* [gre_action_matcher.py](file:///Z:/mtgacoach/src/arenamcp/gre_action_matcher.py) — Maps high-level decisions from the action planner to low-level GRE action objects.
+* [parser.py](file:///Z:/mtgacoach/src/arenamcp/parser.py) & [watcher.py](file:///Z:/mtgacoach/src/arenamcp/watcher.py) — File watcher and parser for `Player.log` acting as a fallback data source.
+
+#### State & Decision Engine
+* [gamestate.py](file:///Z:/mtgacoach/src/arenamcp/gamestate.py) — Main game state management. Processes direct GRE bridge protobuf messages and log parsing.
+* [coach.py](file:///Z:/mtgacoach/src/arenamcp/coach.py) — Prompt building, LLM querying, advice post-processing, and fallback deterministic scoring logic.
+* [action_planner.py](file:///Z:/mtgacoach/src/arenamcp/action_planner.py) — Autonomous gameplay planning using LLM-generated actions.
+* [autopilot.py](file:///Z:/mtgacoach/src/arenamcp/autopilot.py) — Core executor for autonomous play, utilizing GRE bridge API and OS level inputs.
+* [combat_solver.py](file:///Z:/mtgacoach/src/arenamcp/combat_solver.py) — Solves complex combat math for planning.
+* [standalone.py](file:///Z:/mtgacoach/src/arenamcp/standalone.py) — Entry point for headless coaching loop, managing trigger states.
+
+#### Database & External APIs
+* [scryfall.py](file:///Z:/mtgacoach/src/arenamcp/scryfall.py) — Scryfall REST API client with local disk cache.
+* [draftstats.py](file:///Z:/mtgacoach/src/arenamcp/draftstats.py) & [draft_eval.py](file:///Z:/mtgacoach/src/arenamcp/draft_eval.py) — Queries and processes 17lands data to evaluate draft options.
+* [mtgadb.py](file:///Z:/mtgacoach/src/arenamcp/mtgadb.py) & [mtgjson.py](file:///Z:/mtgacoach/src/arenamcp/mtgjson.py) — Integrates local card lookup SQLite databases.
+
+#### Interaction & Desktop Integration
+* [input_controller.py](file:///Z:/mtgacoach/src/arenamcp/input_controller.py) — Coordinates direct OS clicks and key input automation.
+* [screen_mapper.py](file:///Z:/mtgacoach/src/arenamcp/screen_mapper.py) — Calculates positions on screen for card/button interactions.
+* [vision_mapper.py](file:///Z:/mtgacoach/src/arenamcp/vision_mapper.py) — VLM-based pixel-level fallback coordinate resolver.
+* [tts.py](file:///Z:/mtgacoach/src/arenamcp/tts.py) & [transcription.py](file:///Z:/mtgacoach/src/arenamcp/transcription.py) — Text-to-Speech synthesis and transcription integration.
+
+### Desktop UI Subsystem ([src/arenamcp/desktop/](file:///Z:/mtgacoach/src/arenamcp/desktop))
+* [app.py](file:///Z:/mtgacoach/src/arenamcp/desktop/app.py) — PySide6 application runtime initialization.
+* [main_window.py](file:///Z:/mtgacoach/src/arenamcp/desktop/main_window.py) — Main workspace window and tab shell.
+* [coach_tab.py](file:///Z:/mtgacoach/src/arenamcp/desktop/coach_tab.py) — Central control panel for voice settings, engine logs, and session controls.
+* [repair_tab.py](file:///Z:/mtgacoach/src/arenamcp/desktop/repair_tab.py) — Self-healing diagnostic interface (venv setup, environment settings, BepInEx installation, and bridge validation).
+* [hud.py](file:///Z:/mtgacoach/src/arenamcp/desktop/hud.py) & [card_overlay.py](file:///Z:/mtgacoach/src/arenamcp/desktop/card_overlay.py) — Transparent click-through overlay window displaying draft reviews directly on top of MTGA.
+* [coach_process.py](file:///Z:/mtgacoach/src/arenamcp/desktop/coach_process.py) — Manages standard subprocess pipes to start/stop the standalone backend process.
+
+### Unity C# Plugin ([bepinex-plugin/MtgaCoachBridge/](file:///Z:/mtgacoach/bepinex-plugin/MtgaCoachBridge))
+* [Plugin.cs](file:///Z:/mtgacoach/bepinex-plugin/MtgaCoachBridge/Plugin.cs) — Injected DLL logic. Injects into MTGA Unity lifecycle, handles connection to local Named Pipe (`\\.\pipe\mtgacoach_bridge_v2`), and executes marshaled main-thread queries/actions.
+* [BotBattleBridge.cs](file:///Z:/mtgacoach/bepinex-plugin/MtgaCoachBridge/BotBattleBridge.cs) — Intercepts and logs bot match statistics and triggers.
+
+### Proxy Server Backend ([website/](file:///Z:/mtgacoach/website))
+* [app.py](file:///Z:/mtgacoach/website/app.py) — FastAPI server routing LLM requests, validating client keys, and exposing admin portals.
+* [providers.py](file:///Z:/mtgacoach/website/providers.py) — Provider wrappers with priority-based route fallbacks and backoff logic.
+* [db.py](file:///Z:/mtgacoach/website/db.py) — SQLite wrapper tracking client license tokens and server metrics.
+* [templates/admin.html](file:///Z:/mtgacoach/website/templates/admin.html) — Cloud admin evaluation dashboard, displaying real-time latencies, charts, and metrics tables.
+
+### Evaluation Harness ([tools/eval/](file:///Z:/mtgacoach/tools/eval))
+* [run.py](file:///Z:/mtgacoach/tools/eval/run.py) & [judge.py](file:///Z:/mtgacoach/tools/eval/judge.py) — Replays prompt sets through custom backends and uses a self-hosted judge model to grade model output.
+* [report.py](file:///Z:/mtgacoach/tools/eval/report.py) — Generates accuracy tables and markdown report summaries.
+* [replay/run.py](file:///Z:/mtgacoach/tools/eval/replay/run.py) & [replay/score.py](file:///Z:/mtgacoach/tools/eval/replay/score.py) — Runs and scores model outputs on real-game replay prompts, focusing on contested decisions to filter out easy play bias.
+* [seventeenlands/score_mulligan.py](file:///Z:/mtgacoach/tools/eval/seventeenlands/score_mulligan.py) & [seventeenlands/score_turn_actions.py](file:///Z:/mtgacoach/tools/eval/seventeenlands/score_turn_actions.py) — Scores decisions against 17lands data using balanced accuracy and Jaccard metrics.
+
+## Hygiene
+
+Do not commit:
+- `.venv/` or `venv/`
+- `.tools/`
+- `bin/` or `obj/`
+- Scratch files (e.g. `.ab` files, `last_match_event.txt`, debug logs)
+- Generated `dist/` or `build/` files
+
+`tests/` may be ignored in git by default; use `git add -f tests/...` if you need to add new tests to git.