Add update_docs.py and generate initial documentation

AGENTS.md

@@ -0,0 +1,105 @@
+# 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
+├── card_cache.json         # Local cache of Scryfall card data
+├── deck_analysis.json      # Analysis output
+├── collection/             # Raw decklist text files
+├── collection_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
+├── 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 (`decks/*.json`)
+
+```json
+{
+  "name": "Deck Name",
+  "commander": "Commander Name",
+  "colors": ["U", "G", "W"],
+  "archetype": "Theme Description",
+  "cards": {
+    "Card Name": count,
+    ...
+  }
+}
+```
+
+### Card Data (`collection_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 `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 |
+|------|--------|-----------|-----------|
+| 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 |

README.md

@@ -0,0 +1,91 @@
+# MTG EDH Deck Manager
+
+Command-line toolkit for managing Magic: The Gathering Commander (EDH) decks using the Scryfall API.
+
+## Installation
+
+```bash
+git clone <repo-url>
+cd Decks
+```
+
+No dependencies required - pure Python 3 standard library.
+
+## Usage
+
+### Hydrate a Collection
+
+Fetch card data from Scryfall for a decklist:
+
+```bash
+python hydrate.py hydrate collection/decklist.txt -o collection_hydrated/ -c card_cache.json
+```
+
+### Create a New Deck
+
+```bash
+python hydrate.py new my_deck
+```
+
+### Analyze Decks
+
+Find upgrade options from your collection:
+
+```bash
+python scripts/analyze_decks.py --collection collection_hydrated/deck.json --deck-dir decks/
+```
+
+### Find Synergies
+
+Search for cards by keywords, colors, and type:
+
+```bash
+# Find landfall cards in Simic colors
+python scripts/find_synergies.py --collection collection_hydrated/deck.json --colors U G --keywords landfall
+
+# Find Bird creatures in Bant colors
+python scripts/find_synergies.py --collection collection_hydrated/deck.json --colors U G W --creature-type Bird
+
+# Find instants with CMC 2 or less
+python scripts/find_synergies.py --collection collection_hydrated/deck.json --type instant --cmc-max 2
+```
+
+### Generate Reports
+
+```bash
+python scripts/deck_report.py --collection collection_hydrated/deck.json --decks-dir decks/ --output report.md
+```
+
+## Decks
+
+| Deck | Colors | Commander | Archetype |
+|------|--------|-----------|-----------|
+| 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 |
+
+## Workflow
+
+1. **Import** - Place text decklists in `collection/`
+2. **Hydrate** - Run `hydrate.py` to fetch Scryfall data → `collection_hydrated/`
+3. **Define** - Create deck JSON files in `decks/`
+4. **Analyze** - Run `analyze_decks.py` to find upgrade options
+5. **Report** - Use `deck_report.py` for markdown summaries
+
+## Collection Stats
+
+- **Total cards:** 1209
+- **Unique cards:** 866
+- **By type:**
+  - Artifacts: 84
+  - Creatures: 390
+  - Enchantments: 63
+  - Instants: 124
+  - Lands: 97
+  - Planeswalkers: 2
+  - Sorceries: 105
+
+---
+
+*This file is auto-generated. Edit `docs/templates/README.template.md` instead.*

scripts/update_docs.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Generate README.md and AGENTS.md from templates.
+Usage:
+    python scripts/update_docs.py
+"""
+
+import json
+import os
+from pathlib import Path
+
+
+SCRIPT_DIR = Path(__file__).parent
+PROJECT_ROOT = SCRIPT_DIR.parent
+TEMPLATES_DIR = PROJECT_ROOT / "docs" / "templates"
+DECKS_DIR = PROJECT_ROOT / "decks"
+COLLECTION_DIR = PROJECT_ROOT / "collection_hydrated"
+
+
+def load_decks() -> list[dict]:
+    """Load all deck JSON files."""
+    decks = []
+    if DECKS_DIR.exists():
+        for path in sorted(DECKS_DIR.glob("*.json")):
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                data["filename"] = path.stem
+                decks.append(data)
+    return decks
+
+
+def load_collection_stats() -> dict:
+    """Get collection statistics."""
+    stats = {
+        "total_cards": 0,
+        "unique_cards": 0,
+        "by_type": {}
+    }
+    deck_file = COLLECTION_DIR / "deck.json"
+    if deck_file.exists():
+        with open(deck_file, "r", encoding="utf-8") as f:
+            cards = json.load(f)
+            stats["unique_cards"] = len(cards)
+            stats["total_cards"] = sum(c.get("count", 1) for c in cards)
+    for category in ["creatures", "instants", "sorceries", "artifacts", "enchantments", "lands", "planeswalkers"]:
+        cat_file = COLLECTION_DIR / f"{category}.json"
+        if cat_file.exists():
+            with open(cat_file, "r", encoding="utf-8") as f:
+                cards = json.load(f)
+                stats["by_type"][category] = len(cards)
+    return stats
+
+
+def generate_deck_table(decks: list[dict]) -> str:
+    """Generate markdown table of decks."""
+    if not decks:
+        return "*No decks defined yet.*"
+    lines = ["| Deck | Colors | Commander | Archetype |", "|------|--------|-----------|-----------|"]
+    color_map = {"W": "White", "U": "Blue", "B": "Black", "R": "Red", "G": "Green"}
+    for deck in decks:
+        name = deck.get("name", deck.get("filename", "Unknown"))
+        colors = deck.get("colors", [])
+        color_str = "".join(colors) if colors else "Colorless"
+        commander = deck.get("commander", "Unknown")
+        archetype = deck.get("archetype", "-")
+        lines.append(f"| {name} | {color_str} | {commander} | {archetype} |")
+    return "\n".join(lines)
+
+
+def generate_collection_stats(stats: dict) -> str:
+    """Generate collection statistics section."""
+    lines = [f"- **Total cards:** {stats['total_cards']}", f"- **Unique cards:** {stats['unique_cards']}"]
+    if stats["by_type"]:
+        lines.append("- **By type:**")
+        for category, count in sorted(stats["by_type"].items()):
+            lines.append(f"  - {category.title()}: {count}")
+    return "\n".join(lines)
+
+
+def generate_docs() -> None:
+    """Generate README.md and AGENTS.md from templates."""
+    decks = load_decks()
+    stats = load_collection_stats()
+    deck_table = generate_deck_table(decks)
+    collection_stats = generate_collection_stats(stats)
+    
+    for template_name in ["README.template.md", "AGENTS.template.md"]:
+        template_path = TEMPLATES_DIR / template_name
+        if not template_path.exists():
+            print(f"Template not found: {template_path}")
+            continue
+        with open(template_path, "r", encoding="utf-8") as f:
+            content = f.read()
+        content = content.replace("{{DECK_TABLE}}", deck_table)
+        content = content.replace("{{COLLECTION_STATS}}", collection_stats)
+        output_name = template_name.replace(".template", "")
+        output_path = PROJECT_ROOT / output_name
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(content)
+        print(f"Generated: {output_path}")
+
+
+if __name__ == "__main__":
+    generate_docs()