From 0c8f98c3f31e0d5c0f440fab72b5a1eb79cecdc8 Mon Sep 17 00:00:00 2001
From: Tuan-Dat Tran <tuan-dat.tran@tudattr.dev>
Date: Thu, 19 Feb 2026 23:51:46 +0100
Subject: [PATCH] Add design doc for auto-updating documentation

---
 docs/plans/2026-02-19-auto-docs-design.md | 73 +++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 docs/plans/2026-02-19-auto-docs-design.md

diff --git a/docs/plans/2026-02-19-auto-docs-design.md b/docs/plans/2026-02-19-auto-docs-design.md
new file mode 100644
index 0000000..96e6d64
--- /dev/null
+++ b/docs/plans/2026-02-19-auto-docs-design.md
@@ -0,0 +1,73 @@
+# 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