From 909531b577a6a9724d4c2f8fd7e0e157be33d696 Mon Sep 17 00:00:00 2001
From: Cal Corum <calcorum@users.noreply.github.com>
Date: Tue, 4 Nov 2025 09:25:44 -0600
Subject: [PATCH] CLAUDE: Update project documentation for UV migration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updated all developer-facing documentation to reflect UV package management.

## Changes

### README.md (root)
- Updated Python version: 3.11+ → 3.13+
- Added UV as package manager in tech stack
- Updated backend setup: pip → uv sync
- Updated all command examples to use `uv run`
- Updated virtual environment path: venv/ → .venv/
- Added UV installation instructions

### QUICKSTART.md
- Updated last modified date to 2025-11-04
- Updated backend setup to use UV installation
- Replaced pip install with `uv sync`
- Updated all development commands to use `uv run`
- Updated troubleshooting for UV-specific issues
- Updated virtual environment references: venv → .venv

## Documentation Status

✅ **Complete for new developers**:
- Root README.md - comprehensive setup guide
- QUICKSTART.md - fast onboarding path
- backend/CLAUDE.md - detailed backend guide
- backend/README.md - quick reference
- backend/.env.example - all required variables
- .claude/ directory - implementation guides

## New Developer Onboarding Path

1. Read root README.md - understand project structure
2. Follow QUICKSTART.md - get running in <15 minutes
3. Reference backend/CLAUDE.md - deep dive into backend
4. Check .claude/implementation/ - architecture details

All documentation now consistent with UV migration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 QUICKSTART.md | 33 +++++++++++++++++----------------
 README.md     | 23 ++++++++++++-----------
 2 files changed, 29 insertions(+), 27 deletions(-)

diff --git a/QUICKSTART.md b/QUICKSTART.md
index 2457455..d39046f 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -1,6 +1,6 @@
 # Paper Dynasty - Quick Start Guide
 
-**Last Updated**: 2025-10-21
+**Last Updated**: 2025-11-04
 
 ## Prerequisites
 
@@ -22,12 +22,11 @@ cd /mnt/NV2/Development/strat-gameplay-webapp
 ```bash
 cd backend
 
-# Create virtual environment
-python3 -m venv venv
-source venv/bin/activate
+# Install UV (modern Python package manager)
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
 # Install dependencies
-pip install -r requirements-dev.txt
+uv sync
 
 # Configure environment
 cp .env.example .env
@@ -37,7 +36,7 @@ cp .env.example .env
 docker compose up -d
 
 # Verify setup
-python -m app.main
+uv run python -m app.main
 # Server should start at http://localhost:8000
 ```
 
@@ -69,8 +68,8 @@ docker compose up -d
 
 # Terminal 2: Run Backend
 cd backend
-source venv/bin/activate
-python -m app.main
+uv run python -m app.main
+# Or: source .venv/bin/activate && python -m app.main
 ```
 
 Backend will be available at:
@@ -99,14 +98,13 @@ npm run dev
 ```bash
 # Run tests
 cd backend
-source venv/bin/activate
-pytest tests/ -v
+uv run pytest tests/ -v
 
 # Format code
-black app/ tests/
+uv run black app/ tests/
 
 # Type checking
-mypy app/
+uv run mypy app/
 
 # Check logs
 tail -f backend/logs/app_*.log
@@ -142,15 +140,18 @@ psql postgresql://paperdynasty:PASSWORD@10.10.0.42:5432/paperdynasty_dev
 Use `docker compose` (with space) not `docker-compose`
 
 ### "greenlet library required"
+This should not happen with UV. If it does, run:
 ```bash
-pip install greenlet
+uv sync  # Reinstall all dependencies
 ```
 
 ### Import errors / Module not found
-Ensure virtual environment is activated:
+Ensure dependencies are installed:
 ```bash
-source venv/bin/activate
-which python  # Should show path to venv/bin/python
+uv sync  # Install/sync dependencies
+# Or check virtual environment
+source .venv/bin/activate
+which python  # Should show path to .venv/bin/python
 ```
 
 ### Database connection errors
diff --git a/README.md b/README.md
index e633df6..c9b8260 100644
--- a/README.md
+++ b/README.md
@@ -44,8 +44,8 @@ strat-gameplay-webapp/
 3. **Start Backend** (in another terminal)
    ```bash
    cd backend
-   source venv/bin/activate  # or 'venv\Scripts\activate' on Windows
-   python -m app.main
+   uv run python -m app.main
+   # Or manually activate: source .venv/bin/activate && python -m app.main
    ```
    Backend will be available at http://localhost:8000
 
@@ -130,26 +130,26 @@ strat-gameplay-webapp/
 ```bash
 cd backend
 
-# Activate virtual environment
-source venv/bin/activate
+# Install UV (one-time setup)
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
 # Install dependencies
-pip install -r requirements-dev.txt
+uv sync
 
 # Run server
-python -m app.main
+uv run python -m app.main
 
 # Run tests
-pytest tests/ -v
+uv run pytest tests/ -v
 
 # Code formatting
-black app/ tests/
+uv run black app/ tests/
 
 # Linting
-flake8 app/ tests/
+uv run flake8 app/ tests/
 
 # Type checking
-mypy app/
+uv run mypy app/
 ```
 
 ### Frontend
@@ -265,7 +265,8 @@ open http://localhost:8000/api/health
 ## Tech Stack
 
 ### Backend
-- **Framework**: FastAPI (Python 3.11+)
+- **Framework**: FastAPI (Python 3.13+)
+- **Package Manager**: UV (modern Python package management)
 - **WebSocket**: Socket.io
 - **Database**: PostgreSQL 14+ with SQLAlchemy
 - **Cache**: Redis 7