ac6c9f4daa
* docs: archive CLI runner scripts and Windows Docker guide, update web runner scripts * docs: overhaul README and DOCKER.md, add 10 user guides - README: Budget Mode section, corrected Further Reading links, theme badge descriptions, diagnostics expansion - DOCKER.md: Windows path note, Budget Mode + Include/Exclude sections, env table additions - docs/user_guides/: 10 new feature guides covering budget mode, include/exclude, locks/replace/permalinks, batch build, theme browser, random build, owned cards, partner mechanics, bracket compliance, quick build & skip controls * fix: map PriceTimeoutError→503, add budget exceptions to status map; update error_handling.md * docs: env var parity — add missing vars to .env.example and README table
3.6 KiB
Theme Browser & Quality System
Explore, filter, and evaluate the theme catalog before building.
Overview
The Theme Browser at /themes displays all available themes with synergy data, editorial quality scores, and pool size information. Use it to discover themes, understand what cards a theme covers, and filter by quality before selecting themes for a build.
Enable the theme selector and browser with ENABLE_THEMES=1 (default: on).
Badge System
Each theme card in the browser displays up to three badge types:
Quality Badge (SHOW_THEME_QUALITY_BADGES=1)
Editorial quality score based on synergy depth, card count, and thematic coherence. Assigned during catalog curation.
| Badge | Meaning |
|---|---|
| Excellent | Strong synergy, large pool, well-curated |
| Good | Solid theme with reasonable card support |
| Fair | Usable but limited pool or marginal synergy |
| Poor | Sparse pool or weak theme coherence |
Pool Size Badge (SHOW_THEME_POOL_BADGES=1)
Number of on-theme cards available in the catalog.
| Badge | Approximate range |
|---|---|
| Vast | 200+ cards |
| Large | 100–199 cards |
| Moderate | 50–99 cards |
| Small | 20–49 cards |
| Tiny | Under 20 cards |
Pool size is affected by THEME_MIN_CARDS: themes with fewer cards than this threshold are stripped from the catalog entirely during setup/tagging (default: 5).
Popularity Badge (SHOW_THEME_POPULARITY_BADGES=1)
How frequently the theme appears across builds in the system. Higher popularity themes have more real-world data behind their synergy rankings.
Filtering
Filter chips appear above the theme grid when SHOW_THEME_FILTERS=1 (default: on). You can combine filters:
- Filter by Quality: Excellent, Good, Fair, Poor (multi-select)
- Filter by Pool Size: Vast, Large, Moderate, Small, Tiny (multi-select)
- Filter by Popularity
Multiple active filters use AND logic — a theme must match all active badge filters to appear.
Theme Detail Pages
Click any theme card to open its detail page. Each page shows:
- The full on-theme card list with EDHREC rank, CMC, and synergy score
- Badge explanations for that theme
- Related themes (by tag overlap)
Quality Dashboard
/diagnostics/quality (requires SHOW_DIAGNOSTICS=1) provides a catalog-level health overview:
- Distribution of themes by quality tier
- Average pool size per quality tier
- Themes flagged for editorial review (e.g., very low card count, no quality score)
Environment Variables
| Variable | Default | Purpose |
|---|---|---|
ENABLE_THEMES |
1 |
Keep the theme browser and theme selector active. |
SHOW_THEME_QUALITY_BADGES |
1 |
Show quality badges in the theme catalog. |
SHOW_THEME_POOL_BADGES |
1 |
Show pool size badges in the theme catalog. |
SHOW_THEME_POPULARITY_BADGES |
1 |
Show popularity badges in the theme catalog. |
SHOW_THEME_FILTERS |
1 |
Show filter chips in the theme catalog. |
THEME_MIN_CARDS |
5 |
Minimum cards required for a theme to appear in the catalog. |
WEB_THEME_PICKER_DIAGNOSTICS |
1 |
Unlock /themes/metrics, uncapped synergies, and extra metadata. |
THEME_MATCH_MODE |
permissive |
Fuzzy match mode for supplemental themes: permissive continues on unresolved themes, strict stops the build. |
Rebuilding the Theme Catalog
If you update card data or theme YAML files, rebuild the merged catalog:
# Docker Compose:
docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.build_theme_catalog"
# Local:
python -m code.scripts.build_theme_catalog