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):

   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:

   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.