mirror of
https://github.com/mwisnowski/mtg_python_deckbuilder.git
synced 2026-04-05 20:57:16 +02:00
feat: web documentation portal with contextual help links and consistent page headers (#67)
This commit is contained in:
mwisnowski
GitHub
parent
46637cf27f
commit
13f6fa5dbf
44 changed files with 2232 additions and 140 deletions
|
|
@ -67,3 +67,10 @@ Access the compare view from **Finished Decks** to diff any two completed builds
|
|||
| 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. |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — step-by-step walkthrough of a single build
|
||||
- [Quick Build & Skip Controls](quick_build_skip_controls.md) — automate individual stages to speed up batch runs
|
||||
|
|
|
|||
|
|
@ -61,6 +61,15 @@ Set `enforcement_mode` in your JSON config to control how the builder handles br
|
|||
}
|
||||
```
|
||||
|
||||
### Enforcement Examples (Bracket 3 — Upgraded)
|
||||
|
||||
| Scenario | `validate` | `prefer` | `strict` |
|
||||
|----------|------------|----------|---------|
|
||||
| 1–3 Game Changers in pool | Proceeds; each flagged in report | Proceeds; included within 3-card cap | Proceeds; included within 3-card cap |
|
||||
| 4+ Game Changers in pool | All flagged FAIL in report | Caps selection at 3; extras skipped | Build fails listing the violating cards |
|
||||
| Mass land denial card | Flagged WARN/FAIL in report | Avoided if alternatives exist in pool | Build fails if card cannot be excluded |
|
||||
| Must Include card violates bracket | Flagged in report; card stays | Flagged in report; card stays | Flagged in report; card stays (Must Include always wins) |
|
||||
|
||||
---
|
||||
|
||||
## Rule Zero Notes
|
||||
|
|
@ -107,3 +116,27 @@ The Game Changers list and companion lists are static JSON files in `config/card
|
|||
| `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. |
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**My deck passed Bracket 2 but the table says it feels more like Bracket 3 — why?**
|
||||
The compliance check runs against the official card lists (Game Changers, extra turns, tutors, combos). Cards not on those lists are not flagged even if they're powerful in context. Use the compliance report as a starting point, then discuss with your table.
|
||||
|
||||
**I set `enforcement_mode: strict` but my Must Include card still violates the bracket.**
|
||||
Must Include cards always bypass enforcement filtering — they are inserted directly before pool selection runs. The compliance report will still flag the violation. Adjust the Must Include list or the bracket to resolve it.
|
||||
|
||||
**Why does the compliance check flag a two-card combo I didn't intend?**
|
||||
Combo detection runs against a known list of two-card infinite combinations. If your synergies happen to match a known combo pattern, they'll be flagged. The report is informational — no cards are removed automatically.
|
||||
|
||||
**Can I update the Game Changers list when WotC publishes new cards?**
|
||||
Yes. Edit the JSON files in `config/card_lists/` (e.g., `game_changers.json`). Each file has a `source_url` field pointing to the canonical source. Restart the server after editing.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — step-by-step guide covering bracket selection in context
|
||||
- [Include / Exclude Lists](include_exclude.md) — how Must Include cards interact with bracket enforcement
|
||||
- [Partner Mechanics](partner_mechanics.md) — bracket implications when the commander is on the Game Changers list
|
||||
|
|
|
|||
|
|
@ -87,3 +87,17 @@ No. The commander is never filtered by price — only cards drawn from the selec
|
|||
|
||||
**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.
|
||||
|
||||
**Why is the price shown different from what I see on a store site?**
|
||||
Prices are sourced from Scryfall bulk data and cached locally. They reflect a recent market median, not real-time retail or buylist prices. Check the stale indicator (clock icon) in the summary for cache age.
|
||||
|
||||
**Can I set separate ceilings for different card types?**
|
||||
Not directly — the per-card ceiling applies to the full pool. To approximate type-specific limits, use Must Exclude to block expensive cards in a category before the build runs.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — budget step in context of the full build workflow
|
||||
- [Locks, Replace & Permalinks](locks_replace_permalinks.md) — use Replace to swap out over-budget cards after building
|
||||
- [Land Bases](land_bases.md) — land counts and profile choices that affect overall deck cost
|
||||
|
|
|
|||
255
docs/user_guides/build_wizard.md
Normal file
255
docs/user_guides/build_wizard.md
Normal file
|
|
@ -0,0 +1,255 @@
|
|||
# Build a Deck - Step-by-Step Guide
|
||||
|
||||
Walk through the deck building wizard to create a Commander deck.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The deck builder guides you through a multi-step modal wizard that helps you configure and build a complete Commander deck. Each step lets you customize your deck's strategy, budget, and power level before generating the final list.
|
||||
|
||||
Access the builder at `/build` or click **Build** in the sidebar.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Choose a Commander
|
||||
|
||||
Select your commander from the search field in the modal. Type the commander's name to see matches.
|
||||
|
||||
**Partner Commanders**: If your commander has Partner, Choose a Partner, or has a Background, you'll be prompted to select a second commander in a follow-up step.
|
||||
|
||||
**Learn more**: [Partner Mechanics Guide](partner_mechanics.md)
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Select Primary Themes
|
||||
|
||||
Choose 1–3 core themes that define your deck's strategy by clicking theme chips in the modal. Themes are organized by pool size:
|
||||
|
||||
- **Recommended**: Themes that work well with your commander (marked with ★)
|
||||
- **Pool Size Sections**: Themes grouped by available card count (Vast, Large, Moderate, Small, Tiny)
|
||||
|
||||
Each theme displays a badge showing the approximate number of cards available for that theme in your commander's colors.
|
||||
|
||||
**Tips**:
|
||||
- Start with 2–3 themes for focused strategies
|
||||
- Mix creature-tribal and mechanical themes for depth
|
||||
- Larger pool sizes give the builder more card options
|
||||
- Use AND mode for tighter synergy (cards match multiple themes)
|
||||
- Use OR mode for broader pools (cards match any theme)
|
||||
|
||||
**Learn more**: [Theme Browser & Quality System](theme_browser.md)
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Add Secondary/Synergy Themes (Optional)
|
||||
|
||||
After selecting your primary themes, you can add additional themes using the "Additional Themes" textbox:
|
||||
|
||||
- Enter theme names separated by commas
|
||||
- Add utility packages (e.g., card draw, removal)
|
||||
- Incorporate combo pieces or win conditions
|
||||
|
||||
**Multi-Theme Fallback**: If you select multiple themes, the builder uses a fallback cascade to find cards that synergize across themes. If no exact matches exist, it expands to broader combinations.
|
||||
|
||||
**Learn more**: [Random Build (Multi-Theme Cascade)](random_build.md#multi-theme-fallback-cascade)
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Bracket Compliance
|
||||
|
||||
Set power-level restrictions with bracket policies (required, defaults to Bracket 3):
|
||||
|
||||
- **Bracket 1–4**: WOTC-defined power tiers
|
||||
- **Enforcement Modes**: Advisory, Strict, or Custom
|
||||
- **Banned Lists**: Automatically enforced per format rules
|
||||
|
||||
Enable bracket enforcement with `ENABLE_BRACKETS=1` (default: on).
|
||||
|
||||
**Learn more**: [Bracket Compliance Guide](bracket_compliance.md)
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Preferences
|
||||
|
||||
Configure optional build behaviors and card priorities:
|
||||
|
||||
### Combo Preferences
|
||||
- **Prioritize combos**: Automatically include combo pieces near the end of the build
|
||||
- **Combo count**: How many combos to include (default: 2)
|
||||
- **Balance**: Early game, late game, or mix
|
||||
|
||||
### Multi-Copy Package
|
||||
- **Enable Multi-Copy package**: Include multiple copies of cards for token/tribal strategies
|
||||
- Works with archetypes like Rat Colony, Relentless Rats, Dragon's Approach
|
||||
- Automatically suggests Thrumming Stone synergy when applicable
|
||||
- **Learn more**: [Multi-Copy Package](multi_copy.md)
|
||||
|
||||
### Owned Card Preferences
|
||||
- **Use only owned cards**: Limit the pool to cards you already own
|
||||
- **Prefer owned cards**: Still allow unowned cards, but rank owned cards higher
|
||||
|
||||
Upload your collection at `/owned` or before starting a build.
|
||||
|
||||
**Learn more**: [Owned Cards Guide](owned_cards.md)
|
||||
|
||||
### Land Base Options
|
||||
- **Swap basics for MDFC lands**: Modal DFC lands replace matching basic lands automatically
|
||||
- **Smart Land Bases**: Auto-adjust land count and mana curve based on commander speed and color complexity
|
||||
|
||||
**Learn more**: [Land Bases Guide](land_bases.md)
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Ideal Counts
|
||||
|
||||
Set target counts for key card categories using sliders or number inputs:
|
||||
|
||||
- **Ramp**: 0–30 cards (default varies by commander)
|
||||
- **Lands**: 25–45 cards (default varies by commander speed)
|
||||
- **Basic Lands**: 0–40 cards (subset of total lands)
|
||||
- **Creatures**: 0–70 cards
|
||||
- **Removal**: 0–30 cards (spot removal)
|
||||
- **Wipes**: 0–15 cards (board wipes)
|
||||
- **Card Advantage**: 0–30 cards (draw/recursion)
|
||||
- **Protection**: 0–20 cards (counterspells, indestructible effects)
|
||||
|
||||
**Warning**: The builder validates your totals. If ideal counts exceed 99 cards, reduce totals to avoid build issues.
|
||||
|
||||
**Tips**:
|
||||
- Start with default recommendations
|
||||
- Adjust based on your deck's strategy
|
||||
- Category totals may overlap (e.g., a creature that ramps counts in both)
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Include/Exclude Specific Cards (Optional)
|
||||
|
||||
Fine-tune your deck with must-have or must-avoid lists:
|
||||
|
||||
- **Include List**: Guarantee specific cards in the deck (max 10)
|
||||
- **Exclude List**: Prevent certain cards from being chosen (max 15)
|
||||
- **File Upload**: Upload .txt files with one card name per line
|
||||
- **Fuzzy Matching**: Card names are validated with approximate matching
|
||||
|
||||
Enable with `ALLOW_MUST_HAVES=true`.
|
||||
|
||||
**Learn more**: [Include/Exclude Cards Guide](include_exclude.md)
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Budget Constraints (Optional)
|
||||
|
||||
Control deck cost with budget limits:
|
||||
|
||||
- **Total Budget ($)**: Set a deck cost ceiling — cards over budget will be flagged
|
||||
- **Per-Card Ceiling ($)**: Flag individual cards above this price
|
||||
- **Pool Filter Tolerance (%)**: Cards exceeding the per-card ceiling by more than this % are excluded from the card pool (default: 15%)
|
||||
- Set to 0 to hard-cap at the ceiling exactly
|
||||
|
||||
Budget filtering uses cached Scryfall prices and respects owned card preferences.
|
||||
|
||||
Enable with `ENABLE_BUDGET_MODE=1`.
|
||||
|
||||
**Learn more**: [Budget Mode Guide](budget_mode.md)
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Advanced Build Options
|
||||
|
||||
### Quick Build / Skip Controls
|
||||
Skip building specific card types to speed up the process:
|
||||
- Skip lands (use with external manabase tools)
|
||||
- Skip ramp/removal/draw
|
||||
- Customize card type distribution
|
||||
|
||||
**Learn more**: [Quick Build & Skip Controls](quick_build_skip_controls.md)
|
||||
|
||||
### Batch Build Mode
|
||||
Generate multiple deck variations at once:
|
||||
- Build 1–10 decks with the same configuration
|
||||
- Compare results to see variance in card selection
|
||||
|
||||
Enable with `ENABLE_BATCH_BUILD=1`.
|
||||
|
||||
**Learn more**: [Batch Build & Compare](batch_build_compare.md)
|
||||
|
||||
---
|
||||
|
||||
## Step 10: Build & Review
|
||||
|
||||
Once configured, click **Build Deck** to generate your decklist. The builder will:
|
||||
|
||||
1. Select cards based on your themes and synergies
|
||||
2. Apply budget and bracket constraints
|
||||
3. Optimize the manabase for your color identity
|
||||
4. Balance card types (creatures, spells, lands)
|
||||
|
||||
### After Building
|
||||
|
||||
The results page shows:
|
||||
|
||||
- **Full Decklist**: All 100 cards with images and prices
|
||||
- **Summary Stats**: Mana curve, color distribution, card types
|
||||
- **Export Options**: CSV, TXT, JSON, or Arena format
|
||||
- **Deck Actions**: Lock cards, replace specific cards, rebuild with changes
|
||||
|
||||
**Lock & Replace**: Found a card you want to keep? Lock it, then replace others without losing your favorites.
|
||||
|
||||
**Learn more**: [Locks, Replace & Permalinks](locks_replace_permalinks.md)
|
||||
|
||||
---
|
||||
|
||||
## Alternative Build Modes
|
||||
|
||||
### Random Build Mode
|
||||
Let the builder choose themes, budget, and configuration automatically with seeded randomization.
|
||||
|
||||
**Learn more**: [Random Build Guide](random_build.md)
|
||||
|
||||
### Batch Build & Compare
|
||||
Generate multiple deck variations at once and compare strategies side-by-side.
|
||||
|
||||
**Learn more**: [Batch Build & Compare](batch_build_compare.md)
|
||||
|
||||
---
|
||||
|
||||
## Tips for Success
|
||||
|
||||
1. **Start Simple**: Choose 2–3 strong themes for your first build
|
||||
2. **Check Quality Badges**: Higher quality themes have better curation
|
||||
3. **Review Theme Pool Sizes**: Larger pools give the builder more options
|
||||
4. **Use Permalinks**: Save your deck configurations for tweaking later
|
||||
5. **Iterate**: Lock good cards and rebuild to refine your strategy
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key settings for the build wizard:
|
||||
|
||||
- `ENABLE_THEMES=1` - Enable theme selection (default: on)
|
||||
- `ENABLE_BUDGET_MODE=1` - Enable budget constraints
|
||||
- `ENABLE_BRACKETS=1` - Enable bracket compliance (default: on)
|
||||
- `ALLOW_MUST_HAVES=true` - Enable include/exclude lists
|
||||
- `THEME_MIN_CARDS=5` - Minimum cards per theme
|
||||
|
||||
---
|
||||
|
||||
## Need More Help?
|
||||
|
||||
- Browse other guides for detailed feature documentation
|
||||
- Check diagnostics at `/diagnostics` for system status
|
||||
- Visit the theme browser at `/themes` to explore available strategies
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Theme Browser](theme_browser.md) — explore and evaluate available themes before building
|
||||
- [Partner Mechanics](partner_mechanics.md) — two-commander builds and color identity rules
|
||||
- [Bracket Compliance](bracket_compliance.md) — power level tiers and enforcement modes
|
||||
- [Budget Mode](budget_mode.md) — filter the card pool by per-card price ceiling
|
||||
- [Multi-Copy Package](multi_copy.md) — build with many copies of a single archetype card
|
||||
- [Random Build](random_build.md) — spin up a randomized deck with one click
|
||||
- [Batch Build & Compare](batch_build_compare.md) — generate and compare multiple builds at once
|
||||
|
|
@ -63,7 +63,9 @@ Must Include cards are inserted directly and are not subject to budget pool filt
|
|||
|
||||
## 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.
|
||||
Some cards have a printed exception allowing any number of copies in a Commander deck. When you add one of these cards to Must Include, a count picker dialog appears to set the desired copy count.
|
||||
|
||||
For the full list of supported archetypes, count caps, and detailed guidance see the [Multi-Copy Package](multi_copy.md) guide.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -87,3 +89,25 @@ Set include and exclude lists in the JSON config. Environment variable overrides
|
|||
"must_exclude": ["Demonic Tutor"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Can I include a card that isn't in my commander's color identity?**
|
||||
The builder will attempt to add it but will silently skip it if the card is outside the commander's color identity. Check the build summary for skipped cards.
|
||||
|
||||
**What happens if my Must Include list makes the deck exceed 100 cards?**
|
||||
Must Include cards are inserted before pool selection fills the remaining slots. The total is always capped at 100 cards, with Must Includes taking priority over pool-selected cards.
|
||||
|
||||
**Do Must Include cards count against bracket compliance?**
|
||||
Yes. A Must Include card that violates your bracket (e.g., a Game Changer at Bracket 2) will be flagged in the compliance report. The card stays in the deck regardless of enforcement mode.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — where Include/Exclude fits in the overall build flow
|
||||
- [Multi-Copy Package](multi_copy.md) — dedicated guide for multi-copy archetype builds
|
||||
- [Bracket Compliance](bracket_compliance.md) — how Must Include cards interact with bracket enforcement
|
||||
- [Locks, Replace & Permalinks](locks_replace_permalinks.md) — lock cards in place and swap alternatives after building
|
||||
|
|
|
|||
|
|
@ -113,3 +113,11 @@ A **backfill** step at the end of all land phases adds basics from the color ide
|
|||
- Smart Lands only adjusts **counts** — the existing land-selection steps (duals, fetches, triples, ETB optimization, etc.) run unchanged on the updated targets.
|
||||
- Colorless commanders fall back to `mid` profile with 35 lands (no color identity to analyze).
|
||||
- If the analysis fails for any reason, it silently falls back to `mid` profile and fixed 35-land target — builds are never blocked.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — land base options in the context of the full build workflow
|
||||
- [Budget Mode](budget_mode.md) — price filtering that affects which lands are available in the pool
|
||||
- [Quick Build & Skip Controls](quick_build_skip_controls.md) — skip specific land stages if you want to handle lands manually
|
||||
|
|
|
|||
|
|
@ -71,3 +71,24 @@ Permalink URLs are self-contained — no server state is required. Anyone with t
|
|||
## 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.
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Can I share a permalink with someone who has a different card catalog version?**
|
||||
Permalinks encode names and settings, not card data. As long as the commander and theme names are still valid in the recipient's catalog, the build will restore correctly. Cards that no longer exist in the catalog will be skipped.
|
||||
|
||||
**Are locks preserved when I export to CSV or TXT?**
|
||||
Locks are session metadata and are stored in the summary JSON sidecar (`*.summary.json`) alongside the export. The CSV/TXT card list itself does not include lock state.
|
||||
|
||||
**What if I accidentally replace a card I wanted to keep?**
|
||||
Replaced cards move out of the deck immediately. If you haven't rebuilt, you can replace again to bring a similar card back in. For guaranteed cards, use Must Include so they aren't displaced by Replace or Rebuild.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — locks and replace in the context of the Step 5 review
|
||||
- [Include / Exclude Lists](include_exclude.md) — guarantee specific cards before the build runs instead of after
|
||||
- [Owned Cards](owned_cards.md) — restrict Replace alternatives to your owned card library
|
||||
|
|
|
|||
102
docs/user_guides/multi_copy.md
Normal file
102
docs/user_guides/multi_copy.md
Normal file
|
|
@ -0,0 +1,102 @@
|
|||
# Multi-Copy Package
|
||||
|
||||
Build decks that run many copies of a single card-type — Relentless Rats, Shadowborn Apostles, and more.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Some Magic cards have a printed exception allowing any number of copies in a Commander deck. The Multi-Copy Package feature lets you include a chosen archetype card at a configured count and builds the rest of the deck around it.
|
||||
|
||||
Enable with `ALLOW_MUST_HAVES=1` (default: on). The **Enable Multi-Copy package** checkbox appears in the New Deck modal preferences section.
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Check **Enable Multi-Copy package** in the New Deck modal.
|
||||
2. When you add an eligible card to Must Include, a **count picker dialog** appears. Set the number of copies.
|
||||
3. The builder reserves those slots for the archetype card before filling the rest of the deck from the theme pool.
|
||||
4. The multi-copy card is locked automatically and appears in Step 5 alongside the rest of the build.
|
||||
|
||||
The builder auto-suggests the dialog when your commander's theme tags match the archetype's trigger conditions. You can also manually add any eligible card via the quick-add input and set a count freely.
|
||||
|
||||
---
|
||||
|
||||
## Supported Archetypes
|
||||
|
||||
| Card | Color | Cap | Theme triggers |
|
||||
|------|-------|-----|----------------|
|
||||
| Cid, Timeless Artificer | W/U | None (20–30 suggested) | artificer kindred, artifacts matter |
|
||||
| Dragon's Approach | R | None (20–30 suggested) | burn, spellslinger, storm, copy |
|
||||
| Hare Apparent | W | None (20–30 suggested) | rabbit kindred, tokens matter |
|
||||
| Nazgûl | B | **9** (printed cap) | wraith kindred, ring, amass |
|
||||
| Persistent Petitioners | U | None (20–30 suggested) | mill, advisor kindred, control |
|
||||
| Rat Colony | B | None (20–30 suggested) | rats, swarm, aristocrats |
|
||||
| Relentless Rats | B | None (20–30 suggested) | rats, swarm, aristocrats |
|
||||
| Seven Dwarves | R | **7** (printed cap) | dwarf kindred, treasure, equipment |
|
||||
| Shadowborn Apostle | B | None (20–30 suggested) | demon kindred, aristocrats, sacrifice |
|
||||
| Slime Against Humanity | G | None (20–30 suggested) | tokens, mill, graveyard, domain |
|
||||
| Tempest Hawk | W | None (20–30 suggested) | bird kindred, aggro |
|
||||
| Templar Knight | W | None (20–30 suggested) | human kindred, knight kindred |
|
||||
|
||||
Cards with a **printed cap** (Nazgûl: 9, Seven Dwarves: 7) cannot exceed their cap — the count picker enforces the maximum.
|
||||
|
||||
---
|
||||
|
||||
## Exclusive Groups
|
||||
|
||||
Rat Colony and Relentless Rats are mutually exclusive — they share the `rats` exclusive group. If both are added, a dialog will prompt you to choose one. Only one rat archetype can be active per build.
|
||||
|
||||
---
|
||||
|
||||
## Count Recommendations
|
||||
|
||||
For uncapped archetypes, the suggested range is **20–30 copies**. This leaves room for a commander, support spells, and lands in a 100-card deck. The sweet spot is often 20–25 copies, which allows ~15–20 support cards and ~35 lands.
|
||||
|
||||
Archetypes with many synergy triggers (Shadowborn Apostle, Relentless Rats) can push toward 30 when the commander specifically supports the archetype.
|
||||
|
||||
---
|
||||
|
||||
## Bracket Interaction
|
||||
|
||||
High copy counts of powerful archetypes can affect bracket compliance:
|
||||
|
||||
- **Thrumming Stone** (which many of these archetypes synergise with) is a Game Changer — using it in Bracket 2 or below will trigger a compliance warning.
|
||||
- The archetype cards themselves are generally not on the Game Changers list, but check the compliance report in Step 5 after building.
|
||||
|
||||
---
|
||||
|
||||
## Headless / CLI
|
||||
|
||||
Set the multi-copy card and count in your JSON config via the `must_include` list. The count picker is a UI affordance — in headless mode, add the card name the desired number of times:
|
||||
|
||||
```json
|
||||
{
|
||||
"must_include": [
|
||||
"Relentless Rats", "Relentless Rats", "Relentless Rats",
|
||||
"Relentless Rats", "Relentless Rats"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Why doesn't the count picker appear when I add a multi-copy card?**
|
||||
The auto-suggest only triggers when your commander's theme tags match the archetype's trigger conditions. If you don't see the dialog, try adding the card manually via the quick-add input — the dialog will appear for recognized archetype names regardless of commander.
|
||||
|
||||
**Can I run a multi-copy package with `owned_only` mode?**
|
||||
Yes, but you need that many copies of the card in your owned card library. The builder will include the configured count regardless of owned status for Must Include cards — they bypass the owned filter.
|
||||
|
||||
**Will the multi-copy card count toward my ideal creature or spell count?**
|
||||
Yes. Multi-copy creature archetypes (e.g., Relentless Rats) count toward the creature ideal, and non-creature archetypes (e.g., Dragon's Approach) count toward the spell ideal. Adjust your ideal counts in Step 6 accordingly.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Include / Exclude Lists](include_exclude.md) — must-include and must-exclude cards in general
|
||||
- [Bracket Compliance](bracket_compliance.md) — Thrumming Stone and archetype interaction with brackets
|
||||
- [Build Wizard](build_wizard.md) — multi-copy package in the context of the full build flow
|
||||
|
|
@ -77,3 +77,27 @@ In headless mode, set the owned card mode via JSON config:
|
|||
```
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**My owned card file uploaded but no cards are being filtered — what's wrong?**
|
||||
Check that the file is in a supported format (plain text, one card per line, or a standard CSV export). Card names must match the Scryfall canonical name exactly (e.g., "Sol Ring" not "sol ring"). Check the diagnostics page for parse errors.
|
||||
|
||||
**Can I use multiple owned card files?**
|
||||
Yes. All files in the `owned_cards/` directory are merged automatically. If the same card appears in multiple files, it is counted once.
|
||||
|
||||
**Does `prefer_owned` guarantee my owned cards appear in the deck?**
|
||||
No — `prefer_owned` adds a weight boost during pool selection, but owned cards compete with the rest of the pool. If you need a specific card guaranteed, add it to Must Include instead.
|
||||
|
||||
**What happens if I'm in `owned_only` mode and there aren't enough owned cards in a category?**
|
||||
The builder fills the category with the cards available and may produce a deck with fewer cards than the ideal count for that slot. The build summary will note any under-filled categories.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — owned card preferences in the context of the full build flow
|
||||
- [Locks, Replace & Permalinks](locks_replace_permalinks.md) — toggle owned-only filtering in the Replace alternatives panel
|
||||
- [Budget Mode](budget_mode.md) — combine price limits with owned card filtering for tighter constraints
|
||||
|
|
|
|||
|
|
@ -103,3 +103,11 @@ Exported configs (`HEADLESS_EXPORT_JSON=1`) include the resolved partner fields:
|
|||
| `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. |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — partner selection in the context of the full build flow
|
||||
- [Bracket Compliance](bracket_compliance.md) — bracket implications when a commander is on the Game Changers list
|
||||
- [Theme Browser](theme_browser.md) — find themes compatible with both commanders' color identity
|
||||
|
|
|
|||
|
|
@ -106,3 +106,10 @@ WEB_IDEALS_UI=input
|
|||
|----------|---------|---------|
|
||||
| `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). |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — full walkthrough covering Quick Build and Skip Controls in context
|
||||
- [Batch Build & Compare](batch_build_compare.md) — run multiple full builds in one session using Quick Build
|
||||
|
|
|
|||
|
|
@ -32,6 +32,30 @@ If a specific theme combination cannot be satisfied (too few on-theme cards for
|
|||
|
||||
---
|
||||
|
||||
## Multi-Theme Fallback Cascade
|
||||
|
||||
When you specify multiple themes (Primary + Secondary + Tertiary), the builder attempts to find commanders matching all themes using a **fallback cascade**. This ensures you get a valid commander even when exact combinations don't exist:
|
||||
|
||||
**Fallback Order** (AND logic):
|
||||
1. **Primary + Secondary + Tertiary** — Exact match (all 3 themes)
|
||||
2. **Primary + Secondary** — Drop tertiary theme
|
||||
3. **Primary + Tertiary** — Drop secondary theme (treat tertiary as secondary)
|
||||
4. **Primary only** — Use only the primary theme
|
||||
5. **Synergy fallback** — Find commanders with theme tag overlap/token substring matches with Primary
|
||||
6. **Full pool fallback** — Any commander (last resort)
|
||||
|
||||
**Fallback Notices:**
|
||||
- **Combo Fallback** (blue/info): One or more themes were dropped (combinations 2-4). The builder found a commander but couldn't match all requested themes.
|
||||
- **Synergy Fallback** (amber/warning): Exact theme match failed; using commanders with overlapping keywords/tokens from your primary theme.
|
||||
- **Full Pool Fallback** (strong warning): No theme matches found; falling back to the entire commander pool. Your theme inputs were too restrictive.
|
||||
|
||||
**Example:**
|
||||
- Request: `Primary: Aggro`, `Secondary: Tokens`, `Tertiary: Goblins`
|
||||
- If no commander has all three tags, the builder tries `Aggro + Tokens`, then `Aggro + Goblins`, then `Aggro` only
|
||||
- Fallback reason is displayed clearly in the result, explaining which combination was used
|
||||
|
||||
---
|
||||
|
||||
## Reproducible Builds (Seeds)
|
||||
|
||||
Set `RANDOM_SEED` to any integer or string to produce the same commander + theme combination every time:
|
||||
|
|
@ -87,3 +111,11 @@ File path takes precedence over the inline `RANDOM_CONSTRAINTS` value.
|
|||
| `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.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Theme Browser](theme_browser.md) — explore and evaluate themes before using them as random constraints
|
||||
- [Quick Build & Skip Controls](quick_build_skip_controls.md) — combine with Quick Build for fully automated random decks
|
||||
- [Build Wizard](build_wizard.md) — the standard build flow if you want more control over selections
|
||||
|
|
|
|||
|
|
@ -17,14 +17,21 @@ Enable the theme selector and browser with `ENABLE_THEMES=1` (default: on).
|
|||
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.
|
||||
Automatically computed score based on four factors, normalized to 0–100:
|
||||
|
||||
| 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 |
|
||||
| Factor | Max points | What it measures |
|
||||
|--------|-----------|------------------|
|
||||
| Card synergy quality | 30 | EDHREC rank and synergy data richness for the theme's example cards |
|
||||
| Uniqueness ratio | 40 | Fraction of theme cards that appear in fewer than 25% of all themes |
|
||||
| Description quality | 20 | Manual editorial description (10 pts), auto-generated rule (5 pts), generic (0 pts) |
|
||||
| Curation bonus | 10 | Theme has hand-curated synergy data |
|
||||
|
||||
| Badge | Score threshold | Meaning |
|
||||
|-------|----------------|---------|
|
||||
| Excellent | ≥ 75 / 100 | Strong synergy, distinctive card pool, well-curated |
|
||||
| Good | 60–74 | Solid theme with reasonable card support |
|
||||
| Fair | 40–59 | Usable but limited pool or marginal synergy |
|
||||
| Poor | < 40 | Sparse pool or weak theme coherence |
|
||||
|
||||
### Pool Size Badge (`SHOW_THEME_POOL_BADGES=1`)
|
||||
Number of on-theme cards available in the catalog.
|
||||
|
|
@ -102,3 +109,11 @@ docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.build_
|
|||
# Local:
|
||||
python -m code.scripts.build_theme_catalog
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Build Wizard](build_wizard.md) — how themes are selected and used during the build workflow
|
||||
- [Random Build](random_build.md) — use themes as constraints for randomized commander selection
|
||||
- [Partner Mechanics](partner_mechanics.md) — finding themes that work across both commanders' color identity
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue