feat: add deck builder with multiple collection support

- Add build_deck.py script for automated deck building
- Support multiple collection files for comprehensive deck building
- Rename main collection file to full_collection.json
- Add comprehensive documentation and usage examples
- Include design and implementation plans
- Enhance synergy detection and commander suggestion

docs/plans/2026-03-03-deck-builder-design.md

@@ -0,0 +1,107 @@
+# Deck Builder Design
+
+## Overview
+Semi-automated tool to build Commander decks from existing card collections.
+
+## Architecture
+- Script: `scripts/build_deck.py`
+- Input: Hydrated collection JSON (`output/hydrated/deck.json`)
+- Output: Deck JSON file in `data/decks/`
+
+## Components
+
+### 1. Collection Analyzer
+- Analyzes color distribution across collection
+- Identifies card type distribution (creatures, spells, lands)
+- Calculates CMC distribution
+- Finds potential synergies (keywords, creature types)
+
+### 2. Commander Suggester
+- Identifies legendary creatures and planeswalkers in collection
+- Scores commanders based on:
+  - Color support in collection
+  - Number of cards matching color identity
+  - Synergistic mechanics present
+- Provides top 3-5 commander recommendations
+
+### 3. Deck Generator
+- Creates starter decklist based on chosen commander
+- Includes:
+  - Commander (1 card)
+  - Lands (35-40 cards matching color identity)
+  - Creatures, spells, and artifacts matching color identity
+  - Balanced mana curve
+- Ensures deck meets Commander format requirements
+
+### 4. Refinement Tools
+- Functions to add/remove specific cards
+- Balance mana curve
+- Adjust land count
+- Filter by card type or CMC
+
+## Data Flow
+
+1. Load hydrated collection from `output/hydrated/deck.json`
+2. Analyze collection statistics
+3. Identify potential commanders
+4. User selects commander
+5. Generate starter decklist
+6. Save deck JSON file
+7. Provide analysis report
+
+## Error Handling
+
+- Validate input file exists and is properly formatted
+- Handle cases where no suitable commanders are found
+- Provide fallback options for incomplete collections
+- Validate generated deck meets format requirements
+
+## Testing Strategy
+
+1. Test with existing collection files
+2. Verify generated decks meet Commander format requirements
+3. Check color identity matching works correctly
+4. Validate mana curve balancing
+5. Test edge cases (small collections, mono-color, multi-color)
+
+## Usage Documentation
+
+Add to README.md:
+
+```markdown
+### Build a Deck From Your Collection
+
+```bash
+# Analyze your collection and build a deck
+python scripts/build_deck.py --collection output/hydrated/deck.json --name my_new_deck
+
+# View suggested commanders
+python scripts/build_deck.py --collection output/hydrated/deck.json --list-commanders
+
+# Build deck with specific commander
+python scripts/build_deck.py --collection output/hydrated/deck.json --name my_deck --commander "Choco, Seeker of Paradise"
+```
+
+The script will:
+1. Analyze your collection for color distribution and card types
+2. Suggest potential commanders from your collection
+3. Generate a starter decklist matching the commander's color identity
+4. Save the deck to `data/decks/<name>.json`
+5. Provide a summary report with suggestions for improvements
+
+After building, you can:
+- Manually edit the deck file
+- Run analysis to find upgrades: `python scripts/analyze_decks.py --collection output/hydrated/deck.json --deck-dir data/decks/`
+- Generate a report: `python scripts/deck_report.py --collection output/hydrated/deck.json --decks-dir data/decks/`
+```
+
+## Implementation Plan
+
+1. Create `scripts/build_deck.py` with argparse CLI
+2. Implement collection analysis functions
+3. Build commander suggestion algorithm
+4. Create deck generation logic
+5. Add refinement tools
+6. Write comprehensive tests
+7. Update README documentation
+8. Add to pre-commit hook for auto-docs