# Design: Auto-updating README.md and AGENTS.md

## Overview

Create documentation files (README.md, AGENTS.md) that auto-update on every commit via a git pre-commit hook.

## Requirements

- README.md with: full usage docs, deck summaries, workflow guide
- AGENTS.md with: build/verify commands, code style guide, extension guide, project structure
- Pre-commit hook triggers on all file changes
- Template-based generation for maintainability

## Architecture

```
├── README.md              # Generated (do not edit directly)
├── AGENTS.md              # Generated (do not edit directly)
├── docs/
│   └── templates/
│       ├── README.template.md
│       └── AGENTS.template.md
├── scripts/
│   └── update_docs.py     # Generator script
└── .git/hooks/
    └── pre-commit         # Runs update_docs.py
```

## Components

### 1. Template Files

Markdown templates with placeholders:
- `{{DECK_SUMMARIES}}` - Dynamic deck table from decks/*.json
- `{{COLLECTION_STATS}}` - Card counts from collection_hydrated/
- Static content for usage, workflow, conventions

### 2. Generator Script (`scripts/update_docs.py`)

- Reads `decks/*.json` for commander, colors, card counts
- Reads `collection_hydrated/` for collection statistics
- Fills template placeholders
- Writes README.md and AGENTS.md

### 3. Pre-commit Hook

Simple bash script that:
1. Runs `python scripts/update_docs.py`
2. Stages updated docs with `git add README.md AGENTS.md`

## Data Flow

```
decks/*.json ──┐
               ├──> update_docs.py ──> README.md
collection/ ───┤                       AGENTS.md
templates/ ────┘
```

## Implementation Steps

1. Create template files in `docs/templates/`
2. Create `scripts/update_docs.py` generator
3. Create `.git/hooks/pre-commit` hook
4. Run initial generation
5. Commit all files

## Success Criteria

- README.md contains current deck summaries
- AGENTS.md documents project conventions
- Running `git commit` updates docs automatically
- Templates are easy to edit for future changes