diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b2efd72
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,42 @@
+# Paper Dynasty Database API
+
+FastAPI backend for baseball card game data. Peewee ORM with SQLite (WAL mode).
+
+## Commands
+
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000  # Dev server
+python main.py                                              # Alt start
+python db_migrations.py                                     # Run migrations
+docker build -t paper-dynasty-db .                          # Build image
+```
+
+## Architecture
+
+- **Routers**: Domain-based in `app/routers_v2/` (cards, players, teams, packs, stats, gauntlets, scouting)
+- **ORM**: Peewee with SQLite (`storage/pd_master.db`, WAL journaling)
+- **Card images**: Playwright/Chromium renders HTML templates → screenshots (see `routers_v2/players.py`)
+- **Logging**: Rotating files in `logs/database/{date}.log`
+
+## Key Constants
+
+- `LIVE_CARDSET_ID`: 24 (current active cardset, in `db_engine.py`)
+- `ranked_cardsets`: Legal cardsets for ranked play
+- `CARDSETS`: Configuration for game modes and card availability
+
+## Environments
+
+| Env | URL | SSH | Container | Port |
+|-----|-----|-----|-----------|------|
+| **Prod** | pd.manticorum.com | `akamai` | `pd_api` | 815 |
+| **Dev** | pddev.manticorum.com | `pd-database` | `dev_pd_database` | 816 |
+
+**Prod compose path**: `ssh akamai` → `/root/container-data/paper-dynasty`
+**Dev PostgreSQL**: `sba_postgres` on `10.10.0.42:5432`, user `sba_admin`, db `paperdynasty_dev`
+
+## Important
+
+- Docker image installs only Playwright Chromium (not all browsers) to optimize size
+- Teams have dynamic card pricing based on market activity
+- Supports both human players and AI teams
+- Gauntlet events use special reward structures and card pools