mtg-builder/docs/plans/2026-02-19-auto-docs-design.md

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