mtg_python_deckbuilder/docs/commander_catalog.md

# Commander Catalog Onboarding

The Commander Browser and deck builder both read from `csv_files/commander_cards.csv`. This file is generated during setup and must stay in sync with the fields the web UI expects. Use this guide whenever you need to add a new commander, refresh the dataset, or troubleshoot missing entries.

## Where the file lives

- Default path: `csv_files/commander_cards.csv`
- Override: set `CSV_FILES_DIR` (env var) before launching the app; the loader resolves `commander_cards.csv` inside that directory.
- Caching: the web layer caches the parsed file in process. Restart the app or call `clear_commander_catalog_cache()` in a shell if you edit the CSV while the server is running.

## Required columns

The loader normalizes these columns; keep the header names exact. Optional fields can be blank but should still be present.

| Column | Notes |
| --- | --- |
| `name` | Printed front name. Used as the fallback display label.
| `faceName` | Front face name for MDFCs/split cards. Defaults to `name` when empty.
| `side` | Leave blank or `A` for the primary face. Secondary faces become distinct slugs.
| `colorIdentity` | WUBRG characters (any casing). `C` marks colorless identities.
| `colors` | Printed colors; mainly used for ordering badges.
| `manaCost` | Optional but keeps rows sortable in the UI.
| `manaValue` | Numeric converted mana cost.
| `type` | Full type line (e.g., `Legendary Creature — Phyrexian Angel`).
| `creatureTypes` | Python/JSON list or comma-separated string of creature subtypes.
| `text` | Oracle text. Enables partner/background detection and hover tooltips.
| `power` / `toughness` | Optional stats. Leave blank for non-creatures.
| `keywords` | Comma-separated keywords (Flying, Vigilance, …).
| `themeTags` | Python/JSON list of curated themes (e.g., `['Angels', 'Life Gain']`).
| `edhrecRank` | Optional EDHREC popularity rank (integer).
| `layout` | Layout string from MTGJSON (`normal`, `modal_dfc`, etc.).

Additional columns are preserved but ignored by the browser; feel free to keep upstream metadata.

## Recommended refresh workflow

1. Ensure dependencies are installed: `pip install -r requirements.txt`.
2. Regenerate the commander catalog with the MDFC-aware helper (multi-face merge always on):
   ```powershell
   python -m code.scripts.refresh_commander_catalog
   ```
   - Pass `--compat-snapshot` when you need both `csv_files/commander_cards.csv` and `csv_files/compat_faces/commander_cards_unmerged.csv` so downstream consumers can diff the historical row-per-face layout.
   - The legacy `--mode` argument is deprecated; it no longer disables the merge but still maps `--mode compat` to `--compat-snapshot` for older automation. Use `--skip-setup` if `determine_commanders()` has already been run and you simply need to reapply tagging.
   - When running the web service during staging, set `DFC_COMPAT_SNAPSHOT=1` if you need the compatibility snapshot written on each rebuild. The merge itself no longer requires a feature flag.
   - Use the staging QA checklist (`docs/qa/mdfc_staging_checklist.md`) to validate commander flows and downstream consumers before promoting the flag in production.
3. Restart the web server (or your desktop app) so the cache reloads the new file.
4. Validate with the targeted test:
   ```powershell
   python -m pytest -q code/tests/test_commander_catalog_loader.py
   ```
   The test confirms required columns exist, normalization still works, and caching invalidates correctly.

## Manual edits (quick fixes)

If you need to hotfix a single row before a full regeneration:

1. Open the CSV in a UTF-8 aware editor (Excel can re-save with a UTF-8 BOM — prefer a text editor when possible).
2. Add or edit the row, ensuring the slug-worthy fields (`name`, `faceName`, `side`) are unique.
3. Keep the `themeTags` value as a Python/JSON list (e.g., `['Artifacts']`), or a comma-delimited list without stray quotes.
4. Save the file and restart the server so the cache refreshes.
5. Backfill the curated themes in `config/themes/` if the new commander should surface dedicated tags.

> Manual edits are acceptable for emergency fixes but commit regenerated data as soon as possible so automation stays trustworthy.

## Troubleshooting

- **`Commander catalog is unavailable` error**: The app could not find the CSV. Verify the file exists under `CSV_FILES_DIR` and has a header row.
- **Row missing in the browser**: Ensure the commander passed eligibility (legendary rules) and the row’s `layout`/`side` data is correct. Slug collisions are auto-deduped (`-2`, `-3`, …) but rely on unique `name`+`side` combos.
- **Theme chips absent**: Confirm `themeTags` contains at least one value and that the theme slug exists in the theme catalog; otherwise the UI hides the chips.

For deeper issues, enable verbose logs with `SHOW_LOGS=1` before restarting the web process.