# AGENTS.md

Guide for AI assistants working on this codebase.

## Build/Verify Commands

This project has no external dependencies or test framework.

```bash
# No lint/typecheck commands currently
# Verify scripts work by running them:
python hydrate.py --help
python scripts/analyze_decks.py --help
```

## Code Style

- **Language:** Python 3 (stdlib only, no external packages)
- **Formatting:** 4-space indent, max line length ~100
- **Imports:** Standard library only (argparse, json, pathlib, urllib, re, sys, os, time)
- **CLI:** Use `argparse` with subparsers for multi-command tools
- **Error handling:** Print to stderr, use sys.exit(1) for failures
- **Docstrings:** Triple-quoted at module and function level with usage examples
- **Type hints:** Optional but encouraged for complex functions

## Project Structure

```
├── hydrate.py              # Main CLI - fetches card data from Scryfall
├── cache/
│   └── card_cache.json     # Local cache of Scryfall card data
├── output/
│   ├── deck_analysis.json  # Analysis output
│   └── hydrated/           # Enriched card data by type
│       ├── deck.json       # All cards combined
│       ├── commander.json
│       ├── creatures.json
│       ├── instants.json
│       ├── sorceries.json
│       ├── artifacts.json
│       ├── enchantments.json
│       ├── lands.json
│       └── planeswalkers.json
├── data/
│   ├── collection/         # Raw decklist text files
│   └── decks/              # Deck definitions (JSON)
│       └── <deck_name>.json    # name, commander, colors, archetype, cards
├── scripts/
│   ├── analyze_decks.py    # Find upgrade options for decks
│   ├── find_synergies.py   # Search for synergistic cards
│   ├── parse_deck.py       # Parse text decklists to JSON
│   └── deck_report.py      # Generate markdown reports
└── docs/
    └── templates/          # Documentation templates
```

## Data Formats

### Deck JSON (`data/decks/*.json`)

```json
{
  "name": "Deck Name",
  "commander": "Commander Name",
  "colors": ["U", "G", "W"],
  "archetype": "Theme Description",
  "cards": {
    "Card Name": count,
    ...
  }
}
```

### Card Data (`output/hydrated/*.json`)

Array of card objects with Scryfall fields:
- `name`, `mana_cost`, `cmc`, `colors`, `color_identity`
- `type_line`, `oracle_text`, `power`, `toughness`, `loyalty`
- `scryfall_uri`, `count`

## Extension Guide

### Adding a New Deck

1. Create `data/decks/<name>.json` with required fields
2. Run `python scripts/update_docs.py` to regenerate documentation

### Adding a New Script

1. Create `scripts/<name>.py` with argparse CLI
2. Follow existing patterns: `load_collection()`, argparse with --help
3. Update README template with usage example
4. Run `python scripts/update_docs.py`

### Modifying Deck Analysis

- `scripts/analyze_decks.py`: Core logic for finding upgrades
- Color identity matching uses `color_identity` field from Scryfall
- Cards are categorized by `type_line`

## Current Decks

| Deck | Colors | Commander | Archetype |
|------|--------|-----------|-----------|
| my_choco_deck | BUW | G'raha Tia, Scion Reborn | Auto-generated |
| Choco | UGW | Choco, Seeker of Paradise | Bird Tribal Landfall |
| Hazel | BG | Hazel of the Rootbloom | Golgari Aristocrats |
| Palamecia | UR | The Emperor of Palamecia // The Lord Master of Hell | Izzet Self-Mill Storm |
| Yshtola | UBW | Y'shtola, Night's Blessed | Esper Stax Drain |