USE WHEN: analyzing a deck, running npm run analyze/dev/bracket/gamechangers, reading combined JSON analysis, presenting deck insights, answering "what bracket is this deck", generating cache. COVERS: cache generation workflow, analysis commands, combined JSON structure, AI recommendations output format, pre-generated analysis files.
Most analysis commands depend on the cache file (*-cache.json). ALWAYS generate cache first.
THE ONLY CORRECT WORKFLOW:
# Step 1: Generate cache file (REQUIRED - DO NOT SKIP)
npm run dev <deck-file>
# Step 2: Validate cache was created (optional)
npx tsx packages/mtg-validation/src/iteration/validate-cache-exists.ts <deck-file>
# Step 3: Run analysis commands (which use the cache)
npm run analyze <deck-file> # Comprehensive analysis (fast, all analyzers in parallel)
npm run bracket <deck-file> # Bracket analysis only
npm run gamechangers <deck-file> # Gamechanger analysis only
npm run validate-colors <deck-file> # Color validation only
npm run price <deck-file> # Pricing analysis only
npm run banned <deck-file> # Banned card check only
DO NOT DO THIS:
npm run analyze <deck-file> without running npm run dev firstWhy this matters:
npm run dev is the ONLY way to generate the card cache that all analyzers neednpm run analyze WILL FAIL with cryptic errors if cache doesn't existCache file location: cache/decks/<format>/<deck-name>/<variant>/<filename>-cache.json
| Command | Purpose | Requires Cache? |
|---|---|---|
npm run dev <deck-file> | Generate cache + analyzed.mtg | No (creates cache) |
npm run analyze <deck-file> | All analyzers in parallel | Yes |
npm run bracket <deck-file> | Bracket level only | Yes |
npm run gamechangers <deck-file> | Gamechanger analysis | Yes |
npm run validate-colors <deck-file> | Color identity check | Yes |
npm run price <deck-file> | Pricing analysis | Yes |
npm run banned <deck-file> | Banned card check | Yes (24hr cache) |
npm run combos <deck-file> | Infinite combo detection | No (queries API) |
npm run count <deck-file> | Card count validation | No |
npx tsx packages/mtg-validation/src/analyzers/analyze-lands.ts <deck-file> | Land composition | Yes |
After running npm run analyze, these files are generated at cache/decks/<format>/<deck-name>/<variant>/:
<deckfile>-combined.json contains:
<deckfile>-cache.json contains:
| Question | Where to Look |
|---|---|
| "What's the mana curve?" | bracketAnalysis.indicators.avgCmc |
| "Top 10 expensive cards?" | pricingAnalysis.details.mostExpensiveCards |
| "What are the gamechangers?" | gamechangerAnalysis.details.gamechangers |
| "Is it legal?" | bannedAnalysis.summary.rating |
| "What bracket?" | bracketAnalysis.summary.rating + details.reasoning |
| "How much draw/ramp?" | Read cache file oracle text, count relevant cards |
| "Deck composition?" | Run npm run dev for card type breakdown |
decks/ directoriescache/decks/<format>/<deck-name>/<variant>/npm run dev <deck-file> first, then npm run analyze <deck-file>When user runs analysis or asks about a deck, present:
## 📊 Comprehensive Deck Analysis: [Deck Name]
### Overview
- **Bracket**: X (description)
- **Legality**: ✅/❌
- **Total Value**: $X.XX USD
- **Cards**: X total (X unique)
- **Gamechangers**: X high-impact cards
### Power Level Analysis
- Tutors, value engines, combos
- Average CMC, interaction density
- Expected turns to win
### Gamechangers (X cards)
- By category with explanations
### Top 10 Most Expensive Cards
- With prices and strategic importance
### Mana Curve & Composition
- Average CMC, curve distribution, card types
### Strategic Insights
- What makes the deck work, win conditions, vulnerabilities, upgrade paths
Upgrade path recommendations MUST:
npm run price-cards "Card 1" "Card 2" ...npm run fetch "Card Name"npm run collection find "Card Name"If you encounter "Cannot read properties of undefined" errors:
rm cache/decks/<format>/<deck-name>/<file>-cache.jsonnpm run dev <deck-file>Cache Locations:
cache/scryfall.json - Global card data cachecache/pricing.json - Card pricing cache (24-hour expiration)cache/decks/<format>/<deck-name>/<variant>/<file>-cache.json - Per-deck card datacache/card-categories.json - Bracket analyzer reference data (tracked in git)cache/banned-<format>.json - Format-specific banned lists (24-hour expiration)