Andreas/mtg_python_deckbuilder
1
0
Fork 0
mirror of https://github.com/mwisnowski/mtg_python_deckbuilder.git synced 2026-04-04 12:17:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: documentation overhaul - archive, user guides, env parity (#62)
Some checks failed
CI / build (push) Has been cancelled
Details

Browse source 
* 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
This commit is contained in:
mwisnowski 2026-03-23 22:00:50 -07:00 • committed by GitHub
parent 537f5d3834
commit ac6c9f4daa
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
21 changed files with 1074 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

4
.env.example
View file

@ -44,6 +44,8 @@ THEME=system # system|light|dark (initial default; user p
SHOW_SETUP=1 # dockerhub: SHOW_SETUP="1"
SHOW_LOGS=1 # dockerhub: SHOW_LOGS="1"
SHOW_DIAGNOSTICS=1 # dockerhub: SHOW_DIAGNOSTICS="1"
SHOW_COMMANDERS=1 # 1=show the commander browser tile and pages; 0=hide
# SHOW_MISC_POOL=0 # 1=expose the misc pool debug view (developer/diagnostics)
ENABLE_THEMES=1 # dockerhub: ENABLE_THEMES="1"
ENABLE_CUSTOM_THEMES=1 # dockerhub: ENABLE_CUSTOM_THEMES="1"
USER_THEME_LIMIT=8 # dockerhub: USER_THEME_LIMIT="8"
@ -132,6 +134,8 @@ TAG_METADATA_SPLIT=1 # dockerhub: TAG_METADATA_SPLIT="1" #
# Theme Catalog Settings
# THEME_MIN_CARDS=5 # Minimum cards required for a theme to be kept in the system (default: 5). Themes with fewer cards are stripped during setup/tagging. Set to 1 to keep all themes, 0 to only strip orphaned themes.
# THEME_CATALOG_MODE=merge # merge|legacy|build|phaseb. Controls catalog builder strategy; 'merge' (default) uses Phase B merged YAML builder.
# THEME_YAML_FAST_SKIP=0 # 1=allow skipping per-theme YAML export on fast code path (development only; default is always export)
# DFC_COMPAT_SNAPSHOT=0 # 1=write legacy unmerged MDFC snapshots alongside merged catalogs (deprecated compatibility workflow)
# WEB_CUSTOM_EXPORT_BASE= # Custom basename for exports (optional).

27
DOCKER.md
View file

@ -2,6 +2,8 @@
Spin up the MTG Python Deckbuilder inside containers. The image defaults to the Web UI; switch to the CLI/headless runner by flipping environment variables. All commands assume Windows PowerShell.
> **Windows note**: PowerShell uses `${PWD}` for the current directory in volume mounts; CMD uses `%cd%`. The commands below use PowerShell syntax. If you are on Linux/macOS, replace `${PWD}` with `$(pwd)` and backtick line continuations with backslashes.
## Build a Deck (Web UI)
- Build the image (first run only) and start the `web` service in detached mode:
@ -181,6 +183,25 @@ The Finished Decks page reads the `deck_files/` volume for completed builds:
Ensure the deck exports volume remains mounted so these artifacts survive container restarts.
## Budget Mode
Enable cost-aware deck building with `ENABLE_BUDGET_MODE=1` (default). A per-card budget ceiling is entered in the New Deck modal.
- **Soft enforcement only**: cards above the ceiling are filtered from the selection pool, but no card is hard-rejected from the final result. The build summary flags over-budget cards for review and provides a per-category price breakdown.
- `BUDGET_POOL_TOLERANCE` (default `0.15`) sets fractional headroom above the ceiling before exclusion (e.g. `0.15` = 15% overhead). Read at build time; not surfaced in the diagnostics panel.
- Price data comes from Scryfall bulk data cached locally. `PRICE_LAZY_REFRESH=1` (default) refreshes stale per-card prices in the background. `PRICE_AUTO_REFRESH=1` rebuilds the full cache daily at 01:00 UTC.
- `PRICE_STALE_WARNING_HOURS` (default `24`) controls when a cached price shows a stale indicator. Set to `0` to disable.
- Price breakdown is included in build summary panels and exported summary JSON.
## Include / Exclude Lists
Set `ALLOW_MUST_HAVES=1` (default) to enable include/exclude enforcement.
- `SHOW_MUST_HAVE_BUTTONS=1` surfaces the Must Include and Must Exclude buttons and quick-add UI in Step 5 (hidden by default).
- Cards in Must Include are always added first. Cards in Must Exclude are never selected.
- Lists can also be supplied in JSON configs via the `must_include` and `must_exclude` keys.
- Priority: exclude > include > budget filter > bracket filter.
## Browse Themes
The Themes browser exposes the merged theme catalog with search, filters, and diagnostics.
@ -257,9 +278,11 @@ See `.env.example` for the full catalog. Common knobs:
| `WEB_VIRTUALIZE` | `1` | Opt-in to virtualized lists/grids for large result sets. |
| `ALLOW_MUST_HAVES` | `1` | Enable include/exclude enforcement in Step 5. |
| `SHOW_MUST_HAVE_BUTTONS` | `0` | Surface the must include/exclude buttons and quick-add UI (requires `ALLOW_MUST_HAVES=1`). |
| `ENABLE_BUDGET_MODE` | `1` | Enable budget mode controls (total cap, per-card ceiling, soft/hard enforcement) and price display throughout the builder. |
| `ENABLE_BUDGET_MODE` | `1` | Enable budget mode controls (per-card ceiling, soft enforcement) and price display throughout the builder. |
| `BUDGET_POOL_TOLERANCE` | `0.15` | Fractional overhead above the per-card ceiling before a card is excluded from the selection pool (e.g. `0.15` = 15%). |
| `PRICE_AUTO_REFRESH` | `0` | Rebuild the price cache automatically once daily at 01:00 UTC. |
| `PRICE_LAZY_REFRESH` | `1` | Refresh per-card prices in the background when they are more than 7 days old (uses Scryfall named-card API with rate-limit delay). |
| `PRICE_STALE_WARNING_HOURS` | `24` | Hours before a cached price is marked stale with a visual indicator. Set to `0` to disable. |
| `THEME` | `dark` | Initial UI theme (`system`, `light`, or `dark`). |
| `WEB_STAGE_ORDER` | `new` | Build stage execution order: `new` (creatures→spells→lands) or `legacy` (lands→creatures→spells). |
| `WEB_IDEALS_UI` | `slider` | Ideal counts interface: `slider` (range inputs with live validation) or `input` (text boxes with placeholders). |
@ -290,7 +313,7 @@ See `.env.example` for the full catalog. Common knobs:
| `WEB_AUTO_REFRESH_DAYS` | `7` | Refresh `cards.csv` if older than N days. |
| `WEB_TAG_PARALLEL` | `1` | Use parallel workers during tagging. |
| `WEB_TAG_WORKERS` | `4` | Worker count for parallel tagging. |
| `CACHE_CARD_IMAGES` | `0` | Download card images to `card_files/images/` (1=enable, 0=fetch from API on demand). See [Image Caching](docs/IMAGE_CACHING.md). |
| `CACHE_CARD_IMAGES` | `0` | Download card images to `card_files/images/` (1=enable, 0=fetch from API on demand). Requires ~3-6 GB. |
| `WEB_AUTO_ENFORCE` | `0` | Re-export decks after auto-applying compliance fixes. |
| `WEB_THEME_PICKER_DIAGNOSTICS` | `1` | Enable theme diagnostics endpoints. |
| `THEME_MIN_CARDS` | `5` | Minimum card count threshold for themes. Themes with fewer cards are stripped from YAML catalogs, JSON picker files, and parquet metadata during setup/tagging. Set to 1 to keep all themes. |

41
README.md
View file

@ -186,6 +186,11 @@ Search and explore all 29,839 Magic cards.
### Browse Themes
Investigate theme synergies and diagnostics.
- `ENABLE_THEMES=1` keeps the tile visible (default).
- Theme cards display three badge types:
- **Quality** (Excellent/Good/Fair/Poor) — editorial score based on synergy depth and card count. Toggle with `SHOW_THEME_QUALITY_BADGES`.
- **Pool size** (Vast/Large/Moderate/Small/Tiny) — number of on-theme cards in the catalog. Toggle with `SHOW_THEME_POOL_BADGES`.
- **Popularity** — how often the theme appears in builds. Toggle with `SHOW_THEME_POPULARITY_BADGES`.
- Filter chips let you narrow the catalog by any badge combination. Toggle with `SHOW_THEME_FILTERS`.
- Extra tooling (`/themes/metrics`, uncapped synergies, editorial quality) is gated by `WEB_THEME_PICKER_DIAGNOSTICS=1`.
- Rebuild the merged catalog as needed:
```powershell
@ -214,6 +219,7 @@ Spin up surprise decks with deterministic fallbacks.
Peek at health & performance.
- Enabled via `SHOW_DIAGNOSTICS=1`.
- `/diagnostics` summarizes system status, feature flags, and theme metrics.
- `/diagnostics/quality` shows the theme quality dashboard: catalog health overview, badge distribution, and editorial scoring breakdown.
- `/healthz` offers a lightweight probe (`{status, version, uptime_seconds}`).
- Press `v` inside virtualized lists (when `WEB_VIRTUALIZE=1`) to view grid diagnostics.
@ -236,6 +242,17 @@ The CLI and headless runners share the builder core.
---
## Budget Mode
Control per-card cost to build within a price target.
- Enable with `ENABLE_BUDGET_MODE=1` (default: on). Adds budget controls and a price summary panel to the builder.
- Set a **per-card price ceiling** in the New Deck modal (UI input — not an env var).
- **Soft enforcement only**: cards exceeding the ceiling are filtered from the selection pool, but no cards are hard-rejected from the final result. A budget summary shows total cost and flags over-budget cards for review.
- Pool tolerance (`BUDGET_POOL_TOLERANCE`, default `0.15`): fractional headroom above the ceiling before exclusion (e.g. `0.15` = 15%). Smooths results for borderline-priced cards.
- Price data is sourced from Scryfall bulk data and cached locally. `PRICE_LAZY_REFRESH=1` refreshes stale entries in the background.
- See [`docs/user_guides/budget_mode.md`](docs/user_guides/budget_mode.md) for the full guide, FAQ, and export details. _(guide coming in Tier 2 docs)_
---
## Data, exports, and volumes
| Host path | Container path | Purpose |
| --- | --- | --- |
@ -279,11 +296,21 @@ Most defaults are defined in `docker-compose.yml` and documented in `.env.exampl
| `SHOW_THEME_POOL_BADGES` | `1` | Show pool size badges in theme catalog (total available cards). |
| `SHOW_THEME_POPULARITY_BADGES` | `1` | Show popularity badges in theme catalog (usage frequency). |
| `SHOW_THEME_FILTERS` | `1` | Show filter dropdowns and quick chips in theme catalog. |
| `THEME_POOL_SECTIONS` | `1` | Group themes by pool size sections (Vast/Large/Moderate/Small/Tiny). Set to `0` for a flat sorted list. |
| `WEB_VIRTUALIZE` | `1` | Opt into virtualized lists for large datasets. |
| `ALLOW_MUST_HAVES` | `1` | Enforce include/exclude (must-have) lists. |
| `SHOW_MUST_HAVE_BUTTONS` | `0` | Reveal the must include/exclude buttons and quick-add UI (requires `ALLOW_MUST_HAVES=1`). |
| `THEME` | `dark` | Default UI theme (`system`, `light`, or `dark`). |
### Budget Mode
| Variable | Default | Purpose |
| --- | --- | --- |
| `ENABLE_BUDGET_MODE` | `1` | Enable budget controls and price display throughout the builder. |
| `BUDGET_POOL_TOLERANCE` | `0.15` | Fractional overhead above the per-card ceiling before a card is excluded from the selection pool (e.g. `0.15` = 15%). |
| `PRICE_AUTO_REFRESH` | `0` | Rebuild price cache automatically once daily at 01:00 UTC. |
| `PRICE_LAZY_REFRESH` | `1` | Refresh stale per-card prices in the background (7-day TTL). |
| `PRICE_STALE_WARNING_HOURS` | `24` | Hours before a cached price is marked stale with a visual indicator. Set to `0` to disable. |
### Random build tuning
| Variable | Default | Purpose |
| --- | --- | --- |
@ -314,7 +341,7 @@ Most defaults are defined in `docker-compose.yml` and documented in `.env.exampl
| `WEB_AUTO_REFRESH_DAYS` | `7` | Refresh `cards.csv` if older than N days. |
| `WEB_TAG_PARALLEL` | `1` | Enable parallel tagging workers. |
| `WEB_TAG_WORKERS` | `4` | Worker count for tagging (compose default). |
| `CACHE_CARD_IMAGES` | `0` | Download card images to `card_files/images/` (1=enable, 0=fetch from API on demand). Requires ~3-6 GB. See [Image Caching](docs/IMAGE_CACHING.md). |
| `CACHE_CARD_IMAGES` | `0` | Download card images to `card_files/images/` (1=enable, 0=fetch from API on demand). Requires ~3-6 GB. |
| `WEB_AUTO_ENFORCE` | `0` | Auto-apply bracket enforcement after builds. |
| `WEB_THEME_PICKER_DIAGNOSTICS` | `1` | Enable theme diagnostics endpoints. |
| `THEME_MIN_CARDS` | `5` | Minimum card count for themes. Themes with fewer cards are stripped from catalogs, JSON files, and parquet metadata during setup/tagging. Set to 1 to keep all themes. |
@ -406,10 +433,8 @@ Licensed under the [MIT License](LICENSE). Card data and imagery are provided by
---
## Further reading
- [Web UI deep dive](docs/web_ui_deep_dive.md) – advanced Stage 5 tooling, multi-copy packages, virtualization tips, and diagnostics overlays.
- [Theme catalog advanced guide](docs/theme_catalog_advanced.md) – API endpoints, governance policies, editorial tooling, and validation scripts.
- [Theme editorial workflow guide](docs/theme_editorial_guide.md) – quality scoring, curation best practices, and linter usage for maintaining theme catalog standards.
- [Headless & CLI guide](docs/headless_cli_guide.md) – automation entry points, environment overrides, and argument walkthroughs.
- [Commander catalog handbook](docs/commander_catalog.md) – required columns, refresh workflow, and staging toggles.
- [Random theme exclusions reference](docs/random_theme_exclusions.md) – curation guidance for curated pools.
- [Theme taxonomy rationale](docs/theme_taxonomy_rationale.md) – roadmap and philosophy behind theme governance.
- [Random mode developer guide](docs/random_mode/developer_guide.md) – architecture, seed infrastructure, and diagnostic tooling for the random build system.
- [Random mode diagnostics](docs/random_mode/diagnostics.md) – runtime metrics, telemetry flags, and structured log formats.
- [Web backend: error handling](docs/web_backend/error_handling.md) – structured error responses, request IDs, and logging conventions.
- [Web backend: route patterns](docs/web_backend/route_patterns.md) – HTMX conventions, partial templates, and routing standards.
- [Node dependencies](docs/NODE_DEPENDENCIES.md) – why Node/npm is present (Tailwind CSS build only; no runtime JS framework).

3
code/web/utils/responses.py
View file

@ -190,7 +190,10 @@ _EXCEPTION_STATUS_MAP: list[tuple[str, int]] = [
# Price
("PriceLimitError", 400),
("PriceValidationError", 400),
("PriceConfigurationError", 400),
("BudgetHardCapExceeded", 400),
("PriceAPIError", 503),
("PriceTimeoutError", 503),
("PriceError", 400),
# CSV / setup data unavailable
("CSVFileNotFoundError", 503),

11
docs/archive/README.md Normal file
View file

@ -0,0 +1,11 @@
# docs/archive/
Historical snapshots of removed or replaced files. Kept for reference; not part of active documentation.
| File | Archived | Reason |
|------|----------|--------|
| `README_2025-10-02.md` | 2025-10-02 | Replaced by full README rewrite |
| `DOCKER_2025-10-02.md` | 2025-10-02 | Replaced by DOCKER.md rewrite |
| `WINDOWS_DOCKER_GUIDE_2026-03-23.md` | 2026-03-23 | Removed — ~70% overlap with DOCKER.md. PowerShell quick-start is now covered in the main README and a callout in DOCKER.md. The Docker Desktop GUI walkthrough section was outdated and unmaintainable. |
| `run-from-dockerhub_2026-03-23.bat` | 2026-03-23 | Removed — launched the interactive CLI mode, which is secondary to the web UI. New users should use `run-web-from-dockerhub.bat` instead. A one-liner covers the CLI case and doesn't need a dedicated script. |
| `run-from-dockerhub_2026-03-23.sh` | 2026-03-23 | Same reason as the .bat equivalent above. |

0
WINDOWS_DOCKER_GUIDE.md → docs/archive/WINDOWS_DOCKER_GUIDE_2026-03-23.md
View file

0
run-from-dockerhub.bat → docs/archive/run-from-dockerhub_2026-03-23.bat
View file

0
run-from-dockerhub.sh → docs/archive/run-from-dockerhub_2026-03-23.sh
View file

69
docs/user_guides/batch_build_compare.md Normal file
View file

@ -0,0 +1,69 @@
# Build X and Compare
Generate multiple deck variants from the same configuration and compare them side by side.
---
## Overview
Build X and Compare lets you run 1–10 deck builds with the same commander, themes, and settings in parallel. Use it to explore variance across builds, find the most consistent card inclusions, and produce an optimized "best-of" deck via the Synergy Builder.
Enable with `ENABLE_BATCH_BUILD=1` (default: on).
---
## Starting a Batch Build
1. In the **New Deck modal**, increase the **Build count** slider from 1 to your desired number (max 10).
2. Configure the rest of the build (commander, themes, bracket, budget) as normal.
3. Click **Build**. Builds run in parallel (max 5 concurrent) with a real-time progress bar and dynamic time estimates.
---
## Results View
After all builds complete, the results page shows:
- Individual build cards, each with a summary (card count, estimated cost, theme coverage).
- **Card overlap statistics**: how many cards appeared in N of N builds, sorted by frequency.
- A **Rebuild** button to re-run with the same configuration (locks and include/exclude lists are preserved).
- A **ZIP export** button to download all builds (CSV, TXT, and summary JSON for each).
---
## Synergy Builder
The Synergy Builder analyzes all builds in the batch and produces an optimized single deck scored by three factors:
| Factor | Description |
|--------|-------------|
| Frequency | Cards that appeared in more builds score higher |
| EDHREC rank | Lower EDHREC rank (more popular) scores higher |
| Theme tags | Cards matching more of the selected themes score higher |
### How to Use
1. From the batch results view, click **Synergy Builder**.
2. Review the scored card list. The top candidates per category are pre-selected.
3. Adjust selections if needed, then click **Build Synergy Deck**.
4. The result is a standard deck that can be exported, locked, and permalinked like any other build.
---
## Compare View
Access the compare view from **Finished Decks** to diff any two completed builds:
- Card overlap count and percentage.
- Cards unique to Build A, cards unique to Build B, cards in both.
- Individual build summaries side by side.
- **Copy summary** button for plain-text export of the diff.
- **Swap A/B** to reverse the comparison direction.
- **Latest two** quick action selects the two most recent builds automatically.
---
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `ENABLE_BATCH_BUILD` | `1` | Show the build count slider in the New Deck modal. Set to `0` to hide and restrict to single builds. |

109
docs/user_guides/bracket_compliance.md Normal file
View file

@ -0,0 +1,109 @@
# Bracket Compliance
Select a power level for your deck and get a detailed compliance report against the official Commander bracket rules.
---
## Overview
Commander brackets define five power tiers from Exhibition (casual) to cEDH (competitive). The builder checks your finished deck against the rules for your selected bracket and surfaces a PASS / WARN / FAIL report per category.
Bracket selection lives in the **New Deck modal**. The compliance report appears in Step 5 and is exported to the compliance JSON sidecar (`deck_files/*_compliance.json`).
---
## Bracket Tiers
| Bracket | Name | Key restrictions |
|---------|------|-----------------|
| 1 | Exhibition | No Game Changers; no two-card infinite combos; no mass land denial; extra turns discouraged; tutors sparse |
| 2 | Core | No Game Changers; no two-card infinite combos; no mass land denial; extra turns not chained; tutors sparse |
| 3 | Upgraded | Up to 3 Game Changers; no mass land denial; no early/cheap two-card combos; extra turns not chained |
| 4 | Optimized | No bracket restrictions (banned list still applies) |
| 5 | cEDH | No bracket restrictions (banned list still applies; competitive mindset) |
Bracket rules follow the official Wizards of the Coast Commander bracket definitions. The card lists used for compliance checks are stored in `config/card_lists/` and can be updated as WotC revises the lists.
---
## Compliance Categories
For each build, the compliance report checks:
| Category | What is checked |
|----------|----------------|
| **Game Changers** | Cards on the official Game Changers list (`config/card_lists/game_changers.json`) |
| **Extra turns** | Cards that grant extra turns (`extra_turns.json`) |
| **Mass land denial** | Cards that destroy, exile, or bounce many lands (`mass_land_denial.json`) |
| **Non-land tutors** | Cards that search the library for non-land cards |
| **Two-card combos** | Known two-card infinite combos (`combos.json`), with a flag for early/cheap combos |
Each category returns a PASS / WARN / FAIL verdict and lists the flagged cards with links.
If the **commander itself** is on the Game Changers list, it is surfaced separately at the top of the report.
---
## Enforcement Mode
Set `enforcement_mode` in your JSON config to control how the builder handles bracket violations:
| Mode | Behavior |
|------|----------|
| `validate` | Build freely, then report violations. No cards are blocked. _(default)_ |
| `prefer` | During selection, avoid adding disallowed categories; cap Game Changers for Bracket 3. |
| `strict` | Block additions that would violate the bracket. Build fails with a clear message if unavoidable. |
```json
{
"bracket": "core",
"enforcement_mode": "prefer"
}
```
---
## Rule Zero Notes
The `rule_zero_notes` field in the JSON config lets you document table agreements that override standard bracket rules:
```json
{
"bracket": "upgraded",
"rule_zero_notes": "Mass land denial allowed by table agreement. Two-card combos capped at 1."
}
```
Rule zero notes appear in the compliance report header and are exported to the compliance JSON.
---
## Web UI
- The bracket dropdown in the New Deck modal defaults to **Core (Bracket 2)** when no bracket is set.
- The compliance banner in Step 5 shows a color-coded overall verdict (green=PASS, yellow=WARN, red=FAIL) and expandable per-category details.
- `WEB_AUTO_ENFORCE=1` re-runs compliance export automatically after each completed build.
---
## Maintaining the Card Lists
The Game Changers list and companion lists are static JSON files in `config/card_lists/`. Each file includes `source_url` and `generated_at` metadata. Update them manually when WotC publishes revisions. Unknown cards in lookups are skipped with a note in the compliance report — they do not cause a hard failure.
---
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `WEB_AUTO_ENFORCE` | `0` | Auto-run compliance export after every build. |
---
## JSON Config Keys
| Key | Values | Purpose |
|-----|--------|---------|
| `bracket` | `exhibition` \| `core` \| `upgraded` \| `optimized` \| `cedh` | Bracket selection. Defaults to `core` if unset. |
| `enforcement_mode` | `validate` \| `prefer` \| `strict` | How violations are handled during building. |
| `rule_zero_notes` | string | Optional table agreement notes included in the compliance report. |

89
docs/user_guides/budget_mode.md Normal file
View file

@ -0,0 +1,89 @@
# Budget Mode
Build decks within a price target using per-card cost filtering and a soft-review summary.
---
## Overview
Budget Mode filters the card selection pool to cards at or near a per-card price ceiling you set. Cards that exceed the ceiling are excluded from the randomized pool, but the final deck is never hard-rejected — over-budget cards that slip through are flagged for your review in the build summary.
Enable with `ENABLE_BUDGET_MODE=1` (default: on).
---
## Setting a Budget
In the **New Deck modal**, enter a per-card price ceiling in the Budget field. This ceiling is a UI input — it is not set via an environment variable.
- Leave the field blank or set it to `0` to disable per-card filtering for that build.
- The ceiling applies to all non-land cards drawn from the selection pool.
---
## How Filtering Works
1. Price data is loaded from a local cache sourced from Scryfall bulk data.
2. Cards whose price exceeds `ceiling * (1 + BUDGET_POOL_TOLERANCE)` are excluded from the pool before selection begins.
3. `BUDGET_POOL_TOLERANCE` (default `0.15`) adds a 15% headroom above the ceiling. This smooths results for borderline-priced cards and avoids over-aggressive filtering.
4. Selection then runs normally on the filtered pool — locked cards and Must Include cards are inserted before filtering.
**Example:** Ceiling = $2.00, tolerance = 0.15 → cards priced above $2.30 are excluded from the pool.
---
## Build Summary
After a build completes, the budget summary panel shows:
- Total estimated deck cost
- Per-category cost breakdown (creatures, spells, lands, etc.)
- Cards flagged as over-budget (above the ceiling, not the tolerance threshold)
- Price badges on individual card rows: green (under ceiling), yellow (at ceiling), red (over ceiling)
- A stale price indicator (clock icon) when a cached price is older than `PRICE_STALE_WARNING_HOURS`
The summary JSON export (`deck_files/*.summary.json`) includes the price breakdown per category.
---
## Price Data & Caching
Prices are sourced from the Scryfall bulk data API and cached locally.
| Behavior | Setting |
|----------|---------|
| Background per-card refresh (7-day TTL) | `PRICE_LAZY_REFRESH=1` (default) |
| Full cache rebuild daily at 01:00 UTC | `PRICE_AUTO_REFRESH=1` |
| Stale indicator threshold | `PRICE_STALE_WARNING_HOURS=24` (set to `0` to disable) |
If a card has no price data, it is treated as free (fail-open) and selected normally. No card is hard-rejected due to a missing price.
To manually check cache status: `/api/price/stats` (when `SHOW_DIAGNOSTICS=1`).
---
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `ENABLE_BUDGET_MODE` | `1` | Enable budget controls and price display. Set to `0` to hide all budget UI. |
| `BUDGET_POOL_TOLERANCE` | `0.15` | Fractional overhead above the per-card ceiling before exclusion. |
| `PRICE_AUTO_REFRESH` | `0` | Rebuild the full price cache daily at 01:00 UTC. |
| `PRICE_LAZY_REFRESH` | `1` | Refresh stale per-card prices in the background. |
| `PRICE_STALE_WARNING_HOURS` | `24` | Hours before a cached price shows a stale indicator. `0` = disable. |
---
## FAQ
**Why is a card over my ceiling still in the deck?**
The pool tolerance allows cards slightly above the ceiling into the selection pool to avoid overly thin pools. Cards that land in your deck despite being over ceiling are flagged in red in the budget summary. You can swap them using the Replace feature in Step 5.
**Prices look stale — how do I refresh?**
Set `PRICE_LAZY_REFRESH=1` (default) to refresh automatically in the background. For an immediate full refresh, set `PRICE_AUTO_REFRESH=1` and restart the container, or trigger a manual refresh via the price stats API.
**Does budget mode affect the commander?**
No. The commander is never filtered by price — only cards drawn from the selection pool are subject to the ceiling.
**Can I use budget mode with Must Include cards?**
Yes. Must Include cards bypass the pool filter and are always added. They may appear as over-budget in the summary if they exceed the ceiling.

89
docs/user_guides/include_exclude.md Normal file
View file

@ -0,0 +1,89 @@
# Include / Exclude Lists
Pin specific cards into every build or permanently block them from selection.
---
## Overview
The Include / Exclude feature (also called "Must-Haves") lets you control card selection at the individual card level, outside the normal theme and pool logic.
- **Must Include**: cards are always added to the deck, before pool selection runs.
- **Must Exclude**: cards are never added, regardless of theme, bracket, or pool filtering.
Requires `ALLOW_MUST_HAVES=1` (default: on).
---
## Enabling the UI Controls
The include/exclude buttons are hidden by default to keep the Step 5 interface clean. To show them:
```
SHOW_MUST_HAVE_BUTTONS=1
```
When enabled, each card row in Step 5 gains a Must Include (+) and Must Exclude (−) button. You can also manage lists via the quick-add input at the top of the section.
---
## Adding Cards
### Via Step 5 UI
1. Enable `SHOW_MUST_HAVE_BUTTONS=1`.
2. In Step 5, click **+** on a card to add it to Must Include, or **−** to add it to Must Exclude.
3. Use the quick-add input at the top to add cards by name without scrolling.
### Via JSON Config
Supply lists in your deck config file:
```json
{
"must_include": ["Sol Ring", "Arcane Signet"],
"must_exclude": ["Thassa's Oracle"]
}
```
Both keys accept an array of card names. Names are matched case-insensitively.
---
## Priority Order
When include/exclude interacts with other filters, this order applies:
1. **Must Exclude** — always wins; card is never selected.
2. **Must Include** — card is always added, before pool selection.
3. **Budget filter** — applied to the remaining pool after Must Include cards are inserted.
4. **Bracket filter** — applied after budget.
Must Include cards are inserted directly and are not subject to budget pool filtering. They may appear as over-budget in the summary if they exceed the ceiling, and they may trigger bracket warnings if they violate bracket rules.
---
## Multi-Copy Archetypes
If a card is in Must Include and the builder detects it supports multi-copy (e.g., Relentless Rats), a count picker dialog appears. Set the desired copy count before confirming.
---
## Conflict Resolution
| Scenario | Behavior |
|----------|----------|
| Card is in both Must Include and Must Exclude | A conflict dialog prompts you to resolve before building. Exclude wins if unresolved. |
| Must Include card not in color identity | Build silently skips the card (does not hard-fail). Verify color identity before including. |
| Must Include card violates bracket rule | Card is added; bracket compliance report flags it. Resolve in Step 5 or adjust bracket. |
---
## Headless / CLI
Set include and exclude lists in the JSON config. Environment variable overrides are not supported for per-card lists; use the config file.
```json
{
"must_include": ["Swiftfoot Boots"],
"must_exclude": ["Demonic Tutor"]
}
```

73
docs/user_guides/locks_replace_permalinks.md Normal file
View file

@ -0,0 +1,73 @@
# Locks, Replace & Permalinks
Core Step 5 tools for refining, sharing, and restoring deck builds.
---
## Locks
Lock cards to pin them in place across reruns. Locked cards are always kept in the deck regardless of theme changes, pool reshuffles, or bracket adjustments.
### How to Lock
- In Step 5, click the lock icon on any card row. The card is immediately locked and visually marked.
- Alternatively, click the card name to open its detail panel, then toggle the lock there.
### Behavior
- Locked cards persist when you click **Rebuild** (re-runs the build with the same settings).
- Locks are stored in the session and exported to the summary JSON sidecar (`*.summary.json`).
- When restoring a deck via permalink, locks are restored alongside the rest of the build state.
- Locking has no interaction with Must Include/Exclude lists — a locked card and a must-include card are both always present. Avoid locking a card that is also in Must Exclude.
### Unlocking
Click the lock icon again to unlock. The card re-enters the pool on the next rebuild.
---
## Replace
Swap any card in the current deck for an alternative from the same category pool.
### How to Use
1. In Step 5, enable **Replace mode** (toggle at the top of the card list).
2. Click any card to open the **Alternatives panel**.
3. Browse or filter alternatives. Toggle **Owned only** to restrict candidates to your uploaded library.
4. Click a card in the alternatives panel to swap it in. The replaced card moves out of the deck.
5. The replacement is locked automatically to prevent it from being displaced on the next rebuild.
### Notes
- Replace respects category boundaries: land replacements come from the land pool, creature replacements from the creature pool, etc.
- Combo-paired cards (flagged in the Combos section of Step 5) will surface a warning if you replace one half of a known combo pair.
- Replace history is included in the summary JSON.
---
## Permalinks
Permalinks encode the full build state into a shareable URL so you or anyone else can restore that exact deck later.
### What a Permalink Encodes
- Commander (and partner/background if applicable)
- Primary, secondary, and tertiary themes
- Bracket selection
- Locked cards
- Must Include / Must Exclude lists
- Budget ceiling (if set)
- Build name (if set)
### Creating a Permalink
- In Step 5, click **Copy Permalink**.
- From the Finished Decks page, click the permalink icon on any completed build.
### Restoring from a Permalink
1. Click **Open Permalink…** on the homepage or Build a Deck modal.
2. Paste the permalink URL or token.
3. The builder restores the commander, themes, bracket, locks, and lists, then lands in Step 5 with the saved state ready to rebuild or export.
### Sharing
Permalink URLs are self-contained — no server state is required. Anyone with the URL can restore the build as long as the card data in the application is compatible (same catalog version or later).
---
## Combos (Step 5 Panel)
The Combos section in Step 5 lists known two-card combo pairs detected in the current deck. This is informational — no cards are added or removed automatically. Use locks to preserve combo pairs across rebuilds, or add individual combo cards to Must Include if you want them guaranteed.

79
docs/user_guides/owned_cards.md Normal file
View file

@ -0,0 +1,79 @@
# Owned Cards
Upload your card collection and build decks using only — or preferring — cards you already own.
---
## Overview
The Owned Cards feature lets you upload lists of cards you own. Once uploaded, these lists integrate into the build pipeline so the builder can filter or bias card selection toward your collection.
---
## Uploading Your Library
Go to `/owned` in the web UI to manage your owned card library.
### Supported Formats
| Format | Notes |
|--------|-------|
| `.txt` | One card name per line. Optionally prefix with a count: `4x Sol Ring` or `4 Sol Ring`. |
| `.csv` | Must include at minimum a `name` column. A `count` column is optional. |
Cards are enriched and deduplicated automatically on upload. Near-duplicate names (e.g., different printings) are resolved against the card catalog.
### Multiple Files
You can upload multiple files. All are merged into a single owned library for the session. To replace the library, delete existing files and re-upload.
---
## Build Modes
Select the owned card mode in the **New Deck modal**:
| Mode | Behavior |
|------|----------|
| **No filter** (default) | Owned cards have no special weight; all on-theme cards are eligible. |
| **Prefer owned** | Cards you own are weighted higher in the selection pool. Non-owned cards are still eligible if the pool would otherwise be too thin. |
| **Owned only** | Only cards in your owned library are eligible for selection. Builds may be thinner if your library doesn't cover a theme well. |
---
## Alternatives Panel (Replace)
When using **Replace** in Step 5, toggle **Owned only** in the Alternatives panel to restrict replacement candidates to cards in your library.
---
## Performance
For large libraries (1,000+ cards), enable list virtualization to improve scroll performance in the Owned Library page:
```
WEB_VIRTUALIZE=1
```
---
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `OWNED_CARDS_DIR` / `CARD_LIBRARY_DIR` | `/app/owned_cards` | Override the directory where owned card files are stored. Mount this volume to persist across container restarts. |
| `WEB_VIRTUALIZE` | `1` | Enable virtualized lists for large owned libraries and Step 5 card grids. |
---
## Headless / CLI
In headless mode, set the owned card mode via JSON config:
```json
{
"owned_only": true,
"prefer_owned": false
}
```
Use `"prefer_owned": true` for soft weighting, `"owned_only": true` for hard filtering. The two are mutually exclusive; `owned_only` takes precedence if both are set.

105
docs/user_guides/partner_mechanics.md Normal file
View file

@ -0,0 +1,105 @@
# Partner Mechanics
Build with dual-commander configurations: Partners, Partner With, Doctor/Doctor's Companion, and Backgrounds.
---
## Overview
Partner mechanics allow you to pair two commanders into a single deck, combining their color identities and theme tags. The builder auto-detects which partner type applies to a selected commander and adjusts Step 2 accordingly.
Enable with `ENABLE_PARTNER_MECHANICS=1` (default: on in Docker Compose; disabled by default in headless/CLI).
---
## Partner Types
| Type | How it works |
|------|-------------|
| **Partner** | Both commanders have the Partner keyword. Any two Partner commanders can be paired. |
| **Partner With** | One commander specifically names their partner (e.g., "Partner with Cazur"). The canonical partner is pre-filled; you can opt out and swap. |
| **Doctor / Doctor's Companion** | Doctors list legal companions and vice versa. Role labels are shown beside each option. |
| **Background** | Choose a Background enchantment instead of a second commander. The Background picker replaces the partner selector when applicable. |
---
## Selecting a Partner in the Web UI
1. In the **New Deck modal** or **Step 2**, select a commander that supports a partner type.
2. The appropriate partner input appears automatically:
- A filtered partner dropdown (Partner)
- A pre-filled name with an opt-out chip (Partner With, Doctor)
- A Background dropdown (Background)
3. For **Partner With** and **Doctor** pairings, an opt-out chip lets you keep the canonical suggestion or clear it and choose a different partner.
4. Previews, color identity warnings, and theme chips update in real time as you make partner selections.
### Partner Suggestions
With `ENABLE_PARTNER_SUGGESTIONS=1`, ranked suggestion chips appear beside the partner selector. These are backed by the partner synergy analytics dataset (`config/analytics/partner_synergy.json`, auto-generated when missing). Selecting a chip populates the partner field.
---
## Color Identity
The combined color identity of both commanders is used for all card pool filtering. Cards outside the combined identity are excluded, just as they would be for a single commander.
---
## Theme Tags
Theme tags from both commanders are merged. This means a partner pair may unlock themes neither commander could access individually.
---
## Headless / CLI
Supply partner settings in the JSON config or as CLI flags:
```json
{
"commander": "Halana, Kessig Ranger",
"secondary_commander": "Alena, Kessig Trapper",
"enable_partner_mechanics": true
}
```
CLI flags:
```
--secondary-commander "Alena, Kessig Trapper" --enable-partner-mechanics true
```
For Background pairings, use `background` instead of `secondary_commander`:
```json
{
"commander": "Raised by Giants",
"background": "Acolyte of Bahamut",
"enable_partner_mechanics": true
}
```
`secondary_commander` and `background` are mutually exclusive. `background` takes precedence if both are set.
### Dry Run
Add `--dry-run` to the CLI command to echo the resolved pairing (names, color identity, partner mode) without running a full build:
```powershell
python code/main.py --dry-run --secondary-commander "Alena, Kessig Trapper" --enable-partner-mechanics true
```
---
## Headless JSON Export
Exported configs (`HEADLESS_EXPORT_JSON=1`) include the resolved partner fields:
- `secondary_commander` or `background`
- `combined_color_identity`
- `partner_mode` (partner | partner_with | doctor | background)
---
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `ENABLE_PARTNER_MECHANICS` | `0` | Unlock partner/background inputs in the web builder and headless runner. |
| `ENABLE_PARTNER_SUGGESTIONS` | `0` | Show ranked partner suggestion chips in the web builder. |
| `PARTNER_SUGGESTIONS_DATASET` | _(auto)_ | Override path to `partner_synergy.json` inside the container. |

108
docs/user_guides/quick_build_skip_controls.md Normal file
View file

@ -0,0 +1,108 @@
# Quick Build & Skip Controls
Speed up the build workflow with one-click automation or granular per-stage skipping.
---
## Overview
The Step-by-Step builder presents each stage for your approval before moving on. Two tools let you bypass this:
- **Quick Build** — one click from the New Deck modal runs all stages automatically and lands in Step 5 with a complete deck ready to review.
- **Skip Controls** — per-stage toggles in Step 5 let you auto-accept any combination of the 21 granular build stages while still stepping through the others manually.
---
## Quick Build
Click **Quick Build** in the New Deck modal (next to the standard **Build** button) to run the full workflow without any approval prompts. Progress is shown in real time as each stage completes.
Use Quick Build when:
- You want to iterate quickly and refine in Step 5 rather than stepping through each stage.
- You are running Batch Build and want all variants generated without interruption.
- You already know what you want and just need a starting point to lock and tweak.
Quick Build respects all normal build settings (bracket, budget, include/exclude, owned filters) and honors any locks from a previous build.
---
## Stage Order
The default build order (`WEB_STAGE_ORDER=new`) runs creatures and spells before lands. This allows the builder to see what pip costs are needed before finalizing the mana base.
| Mode | Order |
|------|-------|
| `new` (default) | Multi-Copy → Creatures → Spells → Lands → Theme Fill → Adjustments |
| `legacy` | Multi-Copy → Lands → Creatures → Spells → Theme Fill → Adjustments |
Set `WEB_STAGE_ORDER=legacy` to restore the original lands-first order.
---
## Skip Controls
In Step 5, the **Skip Controls** section shows 21 per-stage toggles. Enabling a toggle for a stage causes that stage to be auto-accepted on the next build (or rebuild), skipping the approval prompt.
### Land Stages
| Stage | What it auto-accepts |
|-------|---------------------|
| Basic land fill | Automatically approve the basic land distribution |
| Nonbasic fill | Automatically approve nonbasic land selection |
| Land count adjustment | Automatically approve the final land count tuning |
### Creature Stages
| Stage | What it auto-accepts |
|-------|---------------------|
| Early-game creatures | Auto-approve 1–2 CMC creatures |
| Mid-game creatures | Auto-approve 3–4 CMC creatures |
| Late-game creatures | Auto-approve 5+ CMC creatures |
| Synergy creatures | Auto-approve creatures selected for synergy with themes |
| Creature theme fill | Auto-approve remaining creature theme fill |
### Spell Stages
| Stage | What it auto-accepts |
|-------|---------------------|
| Ramp | Auto-approve ramp spells |
| Removal | Auto-approve single-target removal |
| Board wipes | Auto-approve mass removal |
| Card draw | Auto-approve draw spells |
| Protection | Auto-approve protection/counterspell package |
| Spell theme fill | Auto-approve remaining spell theme fill |
Additional adjustment and fill stages are also individually toggleable in the UI.
---
## Combining Quick Build and Skip Controls
You can use skip controls as a "remembered preference" that persists for the session:
- Enable skip controls for stages you never want to review (e.g., basic land fill, ramp).
- Use **Build** (not Quick Build) to still step through the remaining stages manually.
Quick Build always auto-accepts all stages regardless of skip control settings — it is the equivalent of all 21 toggles enabled at once.
---
## Session Persistence
Skip control settings are stored in the browser session. They persist across multiple builds in the same browser tab but reset when the session ends (tab close, browser restart, or session timeout).
---
## Ideal Counts UI
The stage tuning interface (where you set target counts for each category before a stage runs) uses range sliders by default. Switch to numeric text inputs with:
```
WEB_IDEALS_UI=input
```
---
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `WEB_STAGE_ORDER` | `new` | Build stage execution order: `new` (creatures→spells→lands) or `legacy` (lands→creatures→spells). |
| `WEB_IDEALS_UI` | `slider` | Stage tuning interface: `slider` (range inputs) or `input` (text boxes). |

89
docs/user_guides/random_build.md Normal file
View file

@ -0,0 +1,89 @@
# Random Build
Generate surprise Commander decks with a single click — deterministic when you need repeatability.
---
## Overview
The Random Build tile spins up a fully randomized deck: a random commander is picked, then themes are assigned randomly from the catalog and matched to that commander's color identity and tag profile. All normal build rules (bracket, budget, owned filters, include/exclude) still apply.
Enable:
- `RANDOM_MODES=1` — expose backend random endpoints
- `RANDOM_UI=1` — show the Random Build tile on the homepage
---
## Using Random Build
1. Click the **Random Build** tile on the homepage.
2. Optionally set a theme override in the tile's inputs (primary, secondary, tertiary). Leave blank for fully random.
3. Click **Surprise me**. The builder picks a commander and fills theme slots automatically.
4. Use the **Reroll** button to generate a fresh random combination without leaving the tile.
5. Confirm to proceed through the normal build stages (or use Quick Build for one-click automation).
---
## Theme Auto-Fill
When theme slots are left blank, `RANDOM_AUTO_FILL=1` (default) fills them automatically from themes compatible with the randomly selected commander. Set `RANDOM_AUTO_FILL_SECONDARY` or `RANDOM_AUTO_FILL_TERTIARY` to override auto-fill behavior for individual slots while leaving others random.
If a specific theme combination cannot be satisfied (too few on-theme cards for the selected commander), the builder tries alternative themes up to `RANDOM_MAX_ATTEMPTS` times before surfacing an error.
---
## Reproducible Builds (Seeds)
Set `RANDOM_SEED` to any integer or string to produce the same commander + theme combination every time:
```
RANDOM_SEED=my_deck_seed_2026
```
Seeds are also shareable — include the seed in the permalink or pass it via the UI seed input to reproduce a specific random outcome.
---
## Reroll Throttle
To prevent accidental rapid-fire rerolls, a minimum interval of `RANDOM_REROLL_THROTTLE_MS` (default: `350` ms) is enforced client-side between reroll requests.
---
## Constraints
Theme and commander constraints can be passed as inline JSON or a JSON file for headless random builds:
```
RANDOM_CONSTRAINTS='{"colors": ["G","W"], "max_cmc": 4}'
RANDOM_CONSTRAINTS_PATH=/app/config/random_constraints.json
```
File path takes precedence over the inline `RANDOM_CONSTRAINTS` value.
---
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `RANDOM_MODES` | _(unset)_ | Enable random build endpoints. |
| `RANDOM_UI` | _(unset)_ | Show the Random Build tile. |
| `RANDOM_MAX_ATTEMPTS` | `5` | Retry budget when theme constraints cannot be satisfied. |
| `RANDOM_TIMEOUT_MS` | `5000` | Per-attempt timeout in milliseconds. |
| `RANDOM_REROLL_THROTTLE_MS` | `350` | Minimum ms between reroll requests (client guard). |
| `RANDOM_SEED` | _(blank)_ | Deterministic seed for reproducible builds. |
| `RANDOM_AUTO_FILL` | `1` | Auto-fill missing theme slots. |
| `RANDOM_AUTO_FILL_SECONDARY` | _(blank)_ | Override secondary slot auto-fill behavior. |
| `RANDOM_AUTO_FILL_TERTIARY` | _(blank)_ | Override tertiary slot auto-fill behavior. |
| `RANDOM_PRIMARY_THEME` | _(blank)_ | Fix the primary theme (random commander still selected). |
| `RANDOM_SECONDARY_THEME` | _(blank)_ | Fix the secondary theme. |
| `RANDOM_TERTIARY_THEME` | _(blank)_ | Fix the tertiary theme. |
| `RANDOM_STRICT_THEME_MATCH` | `0` | Require strict theme matching for commanders (1=strict). |
| `RANDOM_CONSTRAINTS` | _(blank)_ | Inline JSON constraints (e.g., color limits). |
| `RANDOM_CONSTRAINTS_PATH` | _(blank)_ | Path to a JSON constraints file (takes precedence). |
| `RANDOM_OUTPUT_JSON` | _(blank)_ | Path or directory for outputting the random build payload (headless). |
| `RANDOM_STRUCTURED_LOGS` | `0` | Emit structured JSON logs for random builds. |
| `RANDOM_TELEMETRY` | `0` | Enable lightweight timing and attempt count metrics. |
For rate limiting random endpoints see the [Docker guide](../../DOCKER.md) — Random rate limiting section.

104
docs/user_guides/theme_browser.md Normal file
View file

@ -0,0 +1,104 @@
# 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:
```powershell
# 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
```

3
docs/web_backend/error_handling.md
View file

@ -27,7 +27,10 @@ All custom exceptions inherit from `DeckBuilderError` (base) in `code/exceptions
| `ThemeSelectionError` | 400 | Invalid theme selection |
| `ThemeError` | 400 | General theme failure |
| `PriceLimitError`, `PriceValidationError` | 400 | Bad price constraint |
| `PriceConfigurationError` | 400 | Invalid budget/price configuration in `determine_ideals()` |
| `BudgetHardCapExceeded` | 400 | Deck total exceeds hard budget cap after all replacements |
| `PriceAPIError` | 503 | External price API down |
| `PriceTimeoutError` | 503 | External price API timed out |
| `CSVFileNotFoundError` | 503 | Card data files missing |
| `MTGJSONDownloadError` | 503 | Data download failure |
| `EmptyDataFrameError` | 503 | No card data available |

49
run-web-from-dockerhub.bat
View file

@ -1,6 +1,11 @@
@echo off
setlocal ENABLEDELAYEDEXPANSION
REM Primary entry point for the MTG Python Deckbuilder Web UI from Docker Hub.
REM Override any flag by setting it as an environment variable before running:
REM set THEME=light
REM set ENABLE_BUDGET_MODE=0
echo MTG Python Deckbuilder - Web UI (Docker Hub)
echo ============================================
@ -11,22 +16,45 @@ if not exist "csv_files" mkdir csv_files
if not exist "config" mkdir config
if not exist "owned_cards" mkdir owned_cards
REM Flags (override by setting env vars before running)
REM --- Core UI flags ---
if "%SHOW_LOGS%"=="" set SHOW_LOGS=1
if "%SHOW_DIAGNOSTICS%"=="" set SHOW_DIAGNOSTICS=1
if "%WEB_VIRTUALIZE%"=="" set WEB_VIRTUALIZE=0
if "%WEB_VIRTUALIZE%"=="" set WEB_VIRTUALIZE=1
REM --- Theming (system|light|dark) ---
if "%ENABLE_THEMES%"=="" set ENABLE_THEMES=1
if "%THEME%"=="" set THEME=dark
REM --- Budget Mode ---
if "%ENABLE_BUDGET_MODE%"=="" set ENABLE_BUDGET_MODE=1
if "%PRICE_LAZY_REFRESH%"=="" set PRICE_LAZY_REFRESH=1
REM --- Builder features ---
if "%ENABLE_BATCH_BUILD%"=="" set ENABLE_BATCH_BUILD=1
if "%WEB_STAGE_ORDER%"=="" set WEB_STAGE_ORDER=new
if "%WEB_IDEALS_UI%"=="" set WEB_IDEALS_UI=slider
if "%ALLOW_MUST_HAVES%"=="" set ALLOW_MUST_HAVES=1
if "%ENABLE_PARTNER_MECHANICS%"=="" set ENABLE_PARTNER_MECHANICS=1
REM --- Theme catalog badges ---
if "%SHOW_THEME_QUALITY_BADGES%"=="" set SHOW_THEME_QUALITY_BADGES=1
if "%SHOW_THEME_POOL_BADGES%"=="" set SHOW_THEME_POOL_BADGES=1
if "%SHOW_THEME_POPULARITY_BADGES%"=="" set SHOW_THEME_POPULARITY_BADGES=1
if "%SHOW_THEME_FILTERS%"=="" set SHOW_THEME_FILTERS=1
echo Starting Web UI on http://localhost:8080
echo Flags: SHOW_LOGS=%SHOW_LOGS% SHOW_DIAGNOSTICS=%SHOW_DIAGNOSTICS% WEB_VIRTUALIZE=%WEB_VIRTUALIZE% THEME=%THEME% ENABLE_THEMES=%ENABLE_THEMES%
REM Optional theme flags (set before running):
REM set THEME=system|light|dark
REM set ENABLE_THEMES=1
echo Flags: SHOW_LOGS=%SHOW_LOGS% SHOW_DIAGNOSTICS=%SHOW_DIAGNOSTICS% WEB_VIRTUALIZE=%WEB_VIRTUALIZE% THEME=%THEME%
echo ENABLE_BUDGET_MODE=%ENABLE_BUDGET_MODE% ENABLE_BATCH_BUILD=%ENABLE_BATCH_BUILD% WEB_STAGE_ORDER=%WEB_STAGE_ORDER%
docker run --rm ^
-p 8080:8080 ^
-e SHOW_LOGS=%SHOW_LOGS% -e SHOW_DIAGNOSTICS=%SHOW_DIAGNOSTICS% -e WEB_VIRTUALIZE=%WEB_VIRTUALIZE% ^
-e THEME=%THEME% -e ENABLE_THEMES=%ENABLE_THEMES% ^
-e ENABLE_THEMES=%ENABLE_THEMES% -e THEME=%THEME% ^
-e ENABLE_BUDGET_MODE=%ENABLE_BUDGET_MODE% -e PRICE_LAZY_REFRESH=%PRICE_LAZY_REFRESH% ^
-e ENABLE_BATCH_BUILD=%ENABLE_BATCH_BUILD% -e WEB_STAGE_ORDER=%WEB_STAGE_ORDER% -e WEB_IDEALS_UI=%WEB_IDEALS_UI% ^
-e ALLOW_MUST_HAVES=%ALLOW_MUST_HAVES% -e ENABLE_PARTNER_MECHANICS=%ENABLE_PARTNER_MECHANICS% ^
-e SHOW_THEME_QUALITY_BADGES=%SHOW_THEME_QUALITY_BADGES% -e SHOW_THEME_POOL_BADGES=%SHOW_THEME_POOL_BADGES% ^
-e SHOW_THEME_POPULARITY_BADGES=%SHOW_THEME_POPULARITY_BADGES% -e SHOW_THEME_FILTERS=%SHOW_THEME_FILTERS% ^
-v "%cd%\deck_files:/app/deck_files" ^
-v "%cd%\logs:/app/logs" ^
-v "%cd%\csv_files:/app/csv_files" ^
@ -37,5 +65,8 @@ docker run --rm ^
echo.
echo Open: http://localhost:8080
echo Tip: set SHOW_LOGS=0 or SHOW_DIAGNOSTICS=0 before running to hide those pages.
echo Tips:
echo set THEME=light^|dark^|system before running to change the theme
echo set ENABLE_BUDGET_MODE=0 to disable budget controls
echo set SHOW_LOGS=0 or SHOW_DIAGNOSTICS=0 to hide those pages
endlocal

45
run-web-from-dockerhub.sh
View file

@ -1,22 +1,56 @@
#!/bin/bash
set -euo pipefail
# Primary entry point for the MTG Python Deckbuilder Web UI from Docker Hub.
# Override any flag by exporting it before running:
# export THEME=light
# export ENABLE_BUDGET_MODE=0
echo "MTG Python Deckbuilder - Web UI (Docker Hub)"
echo "==========================================="
# Create directories if they don't exist
mkdir -p deck_files logs csv_files config owned_cards
# Flags (override by exporting before running)
# --- Core UI flags ---
: "${SHOW_LOGS:=1}"
: "${SHOW_DIAGNOSTICS:=1}"
: "${WEB_VIRTUALIZE:=1}"
# --- Theming (system|light|dark) ---
: "${ENABLE_THEMES:=1}"
: "${THEME:=dark}"
# --- Budget Mode ---
: "${ENABLE_BUDGET_MODE:=1}"
: "${PRICE_LAZY_REFRESH:=1}"
# --- Builder features ---
: "${ENABLE_BATCH_BUILD:=1}"
: "${WEB_STAGE_ORDER:=new}"
: "${WEB_IDEALS_UI:=slider}"
: "${ALLOW_MUST_HAVES:=1}"
: "${ENABLE_PARTNER_MECHANICS:=1}"
# --- Theme catalog badges ---
: "${SHOW_THEME_QUALITY_BADGES:=1}"
: "${SHOW_THEME_POOL_BADGES:=1}"
: "${SHOW_THEME_POPULARITY_BADGES:=1}"
: "${SHOW_THEME_FILTERS:=1}"
echo "Starting Web UI on http://localhost:8080"
echo "Flags: SHOW_LOGS=${SHOW_LOGS} SHOW_DIAGNOSTICS=${SHOW_DIAGNOSTICS}"
echo "Flags: SHOW_LOGS=${SHOW_LOGS} SHOW_DIAGNOSTICS=${SHOW_DIAGNOSTICS} WEB_VIRTUALIZE=${WEB_VIRTUALIZE} THEME=${THEME}"
echo " ENABLE_BUDGET_MODE=${ENABLE_BUDGET_MODE} ENABLE_BATCH_BUILD=${ENABLE_BATCH_BUILD} WEB_STAGE_ORDER=${WEB_STAGE_ORDER}"
docker run --rm \
-p 8080:8080 \
-e SHOW_LOGS=${SHOW_LOGS} -e SHOW_DIAGNOSTICS=${SHOW_DIAGNOSTICS} \
-e SHOW_LOGS="${SHOW_LOGS}" -e SHOW_DIAGNOSTICS="${SHOW_DIAGNOSTICS}" -e WEB_VIRTUALIZE="${WEB_VIRTUALIZE}" \
-e ENABLE_THEMES="${ENABLE_THEMES}" -e THEME="${THEME}" \
-e ENABLE_BUDGET_MODE="${ENABLE_BUDGET_MODE}" -e PRICE_LAZY_REFRESH="${PRICE_LAZY_REFRESH}" \
-e ENABLE_BATCH_BUILD="${ENABLE_BATCH_BUILD}" -e WEB_STAGE_ORDER="${WEB_STAGE_ORDER}" -e WEB_IDEALS_UI="${WEB_IDEALS_UI}" \
-e ALLOW_MUST_HAVES="${ALLOW_MUST_HAVES}" -e ENABLE_PARTNER_MECHANICS="${ENABLE_PARTNER_MECHANICS}" \
-e SHOW_THEME_QUALITY_BADGES="${SHOW_THEME_QUALITY_BADGES}" -e SHOW_THEME_POOL_BADGES="${SHOW_THEME_POOL_BADGES}" \
-e SHOW_THEME_POPULARITY_BADGES="${SHOW_THEME_POPULARITY_BADGES}" -e SHOW_THEME_FILTERS="${SHOW_THEME_FILTERS}" \
-v "$(pwd)/deck_files:/app/deck_files" \
-v "$(pwd)/logs:/app/logs" \
-v "$(pwd)/csv_files:/app/csv_files" \
@ -27,4 +61,7 @@ docker run --rm \
echo
echo "Open: http://localhost:8080"
echo "Tip: export SHOW_LOGS=0 or SHOW_DIAGNOSTICS=0 to hide those pages."
echo "Tips:"
echo " export THEME=light|dark|system before running to change the theme"
echo " export ENABLE_BUDGET_MODE=0 to disable budget controls"
echo " export SHOW_LOGS=0 or SHOW_DIAGNOSTICS=0 to hide those pages"