docs: documentation overhaul - archive, user guides, env parity (#62)

* docs: archive CLI runner scripts and Windows Docker guide, update web runner scripts * docs: overhaul README and DOCKER.md, add 10 user guides - README: Budget Mode section, corrected Further Reading links, theme badge descriptions, diagnostics expansion - DOCKER.md: Windows path note, Budget Mode + Include/Exclude sections, env table additions - docs/user_guides/: 10 new feature guides covering budget mode, include/exclude, locks/replace/permalinks, batch build, theme browser, random build, owned cards, partner mechanics, bracket compliance, quick build & skip controls * fix: map PriceTimeoutError→503, add budget exceptions to status map; update error_handling.md * docs: env var parity — add missing vars to .env.example and README table
2026-04-05 20:57:16 +02:00 · 2026-03-23 22:00:50 -07:00 · 2026-03-23 22:00:50 -07:00 · ac6c9f4daa
commit ac6c9f4daa
parent 537f5d3834
21 changed files with 1074 additions and 23 deletions
--- a/docs/archive/README.md
+++ b/docs/archive/README.md
@ -0,0 +1,11 @@
+# docs/archive/
+
+Historical snapshots of removed or replaced files. Kept for reference; not part of active documentation.
+
+| File | Archived | Reason |
+|------|----------|--------|
+| `README_2025-10-02.md` | 2025-10-02 | Replaced by full README rewrite |
+| `DOCKER_2025-10-02.md` | 2025-10-02 | Replaced by DOCKER.md rewrite |
+| `WINDOWS_DOCKER_GUIDE_2026-03-23.md` | 2026-03-23 | Removed — ~70% overlap with DOCKER.md. PowerShell quick-start is now covered in the main README and a callout in DOCKER.md. The Docker Desktop GUI walkthrough section was outdated and unmaintainable. |
+| `run-from-dockerhub_2026-03-23.bat` | 2026-03-23 | Removed — launched the interactive CLI mode, which is secondary to the web UI. New users should use `run-web-from-dockerhub.bat` instead. A one-liner covers the CLI case and doesn't need a dedicated script. |
+| `run-from-dockerhub_2026-03-23.sh` | 2026-03-23 | Same reason as the .bat equivalent above. |
--- a/docs/archive/WINDOWS_DOCKER_GUIDE_2026-03-23.md
+++ b/docs/archive/WINDOWS_DOCKER_GUIDE_2026-03-23.md
@ -0,0 +1,176 @@
+# MTG Python Deckbuilder - Windows Docker Desktop Guide
+
+## Prerequisites
+- [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/) installed and running
+- Windows 10/11 with WSL2 enabled (Docker Desktop will guide you through this)
+
+## ⭐ Recommended: Method 1 - PowerShell
+
+**Why PowerShell is recommended**:
+- ✅ Works consistently across all Docker Desktop versions
+- ✅ Handles interactive terminals reliably  
+- ✅ Simple copy-paste commands
+- ✅ No GUI configuration needed
+
+## Method 1: PowerShell (Recommended)
+
+### Step 1: Open PowerShell
+- Press `Win + X` and select "Windows PowerShell" or "Terminal"
+- Or search for "PowerShell" in the Start menu
+
+### Step 2: Create and Navigate to Your Workspace
+```powershell
+# Create a directory for your MTG decks
+mkdir C:\mtg-decks
+cd C:\mtg-decks
+```
+
+### Step 3: Run the Application
+```powershell
+# Option A: Use the helper script (easiest)
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/mwisnowski/mtg_python_deckbuilder/main/run-from-dockerhub.bat" -OutFile "run-from-dockerhub.bat"
+.\run-from-dockerhub.bat
+
+# Option B: Manual command
+docker run -it --rm `
+  -v "${PWD}/deck_files:/app/deck_files" `
+  -v "${PWD}/logs:/app/logs" `
+  -v "${PWD}/csv_files:/app/csv_files" `
+  -v "${PWD}/owned_cards:/app/owned_cards" `
+  -v "${PWD}/config:/app/config" `
+  mwisnowski/mtg-python-deckbuilder:latest
+```
+
+### Optional: Web UI from Docker Hub
+Run the browser UI by mapping a port and starting uvicorn:
+```powershell
+docker run --rm `
+  -p 8080:8080 `
+  -e WEB_VIRTUALIZE=1 ` # optional virtualization
+  -e ENABLE_THEMES=1 -e THEME=system ` # optional theme selector and default
+  -v "${PWD}/deck_files:/app/deck_files" `
+  -v "${PWD}/logs:/app/logs" `
+  -v "${PWD}/csv_files:/app/csv_files" `
+  -v "${PWD}/owned_cards:/app/owned_cards" `
+  -v "${PWD}/config:/app/config" `
+  mwisnowski/mtg-python-deckbuilder:latest `
+  bash -lc "cd /app && uvicorn code.web.app:app --host 0.0.0.0 --port 8080"
+```
+Then open http://localhost:8080
+
+Tip: The header includes a Reset Theme control to clear your browser’s saved preference and re-apply the server’s default (or OS when THEME=system).
+
+## Method 2: Command Prompt
+```cmd
+REM Create and navigate to workspace
+mkdir C:\mtg-decks
+cd C:\mtg-decks
+
+REM Run the application
+docker run -it --rm ^
+  -v "%cd%\deck_files:/app/deck_files" ^
+  -v "%cd%\logs:/app/logs" ^
+  -v "%cd%\csv_files:/app/csv_files" ^
+  -v "%cd%\owned_cards:/app/owned_cards" ^
+  -v "%cd%\config:/app/config" ^
+  mwisnowski/mtg-python-deckbuilder:latest
+```
+
+## Method 3: Docker Desktop GUI (Alternative)
+
+**Note**: This method can be tricky due to Docker Desktop interface changes. **Method 1 (PowerShell) is recommended** for reliability.
+
+### Step 1: Pull the Image
+1. Open Docker Desktop
+2. Go to **Images** tab
+3. Click **"Search"** and enter: `mwisnowski/mtg-python-deckbuilder`
+4. Click **"Pull"** next to the image
+
+### Step 2: Create Volume Directories
+Create these folders on your computer:
+```
+C:\mtg-decks\
+├── deck_files\
+├── logs\
+├── csv_files\
+└── owned_cards\
+└── config\
+```
+
+### Step 3: Run Container
+1. In Docker Desktop, go to **Images** tab
+2. Find `mwisnowski/mtg-python-deckbuilder:latest`
+3. Click the **"Run"** button (▶️)
+4. In the run dialog:
+   - **Container name**: `mtg-deckbuilder` (optional)
+   - **Ports**: Leave empty
+   - **Volumes**: Click "+" or "Add" to add these three mappings:
+     - Host path: `C:\mtg-decks\deck_files` → Container path: `/app/deck_files`
+     - Host path: `C:\mtg-decks\logs` → Container path: `/app/logs`
+     - Host path: `C:\mtg-decks\csv_files` → Container path: `/app/csv_files`
+   - **Environment variables**: Leave empty
+   - Look for options like:
+     - ✅ "Interactive" or "Attach STDIN" 
+     - ✅ "Allocate a pseudo-TTY" or "TTY"
+     - ✅ "Auto-remove" or "Remove container when stopped"
+     
+   **Note**: The exact wording and location of these options varies by Docker Desktop version. If you don't see these options, the PowerShell method below is recommended.
+
+5. Click **"Run"**
+
+### Alternative: Use "Optional settings" or "Advanced"
+Some Docker Desktop versions put these options under:
+- "Optional settings" dropdown
+- "Advanced" section
+- "Runtime settings"
+
+If you can't find Interactive/TTY options in the GUI, **use Method 1 (PowerShell) instead** - it's more reliable.
+
+### Step 4: Access Terminal
+1. Go to **Containers** tab in Docker Desktop
+2. Click on your running `mtg-deckbuilder` container
+3. Click **"Open in terminal"** or the terminal icon
+4. The MTG Python Deckbuilder should start automatically
+
+## Troubleshooting
+
+### Issue: "Docker daemon not running"
+**Solution**: Make sure Docker Desktop is running. Look for the Docker whale icon in your system tray.
+
+### Issue: "Permission denied" or file access errors
+**Solution**: 
+1. Make sure Docker Desktop has access to your C: drive
+2. Go to Docker Desktop → Settings → Resources → File Sharing
+3. Add your `C:\mtg-decks` folder to the shared directories
+
+### Issue: Files not persisting
+**Solution**: Double-check your volume mappings are correct:
+- Host path should be your actual Windows path (e.g., `C:\mtg-decks\deck_files`)
+- Container path should be exactly `/app/deck_files` (with forward slashes)
+
+### Issue: Can't interact with menus
+**Solution**: 
+- **Preferred**: Use PowerShell method instead of Docker Desktop GUI
+- **GUI Alternative**: Look for "Interactive", "STDIN", "TTY", or "Terminal" options in the run dialog
+- **Last resort**: After container starts, click on it in the Containers tab and look for "Open in terminal" or terminal icon
+
+### Issue: Can't find Interactive/TTY options in Docker Desktop
+**Solution**: Docker Desktop versions vary significantly. If you can't find these options:
+1. Use **Method 1 (PowerShell)** instead - it's more reliable
+2. Or try running this command in Docker Desktop's built-in terminal:
+   ```bash
+   docker run -it --rm -v "C:/mtg-decks/deck_files:/app/deck_files" -v "C:/mtg-decks/logs:/app/logs" -v "C:/mtg-decks/csv_files:/app/csv_files" mwisnowski/mtg-python-deckbuilder:latest
+   ```
+
+## Expected File Structure
+
+After running, your `C:\mtg-decks\` folder will contain:
+```
+C:\mtg-decks\
+├── deck_files\              # Your completed decks (.csv and .txt files)
+│   ├── Atraxa_Superfriends_20250821.csv
+│   ├── Atraxa_Superfriends_20250821.txt
+├── logs\\
+├── csv_files\\
+├── owned_cards\\
+└── config\\
--- a/docs/archive/run-from-dockerhub_2026-03-23.bat
+++ b/docs/archive/run-from-dockerhub_2026-03-23.bat
@ -0,0 +1,36 @@
+@echo off
+echo MTG Python Deckbuilder - Docker Hub Runner
+echo ===========================================
+
+REM Create directories if they don't exist
+if not exist "deck_files" mkdir deck_files
+if not exist "logs" mkdir logs
+if not exist "csv_files" mkdir csv_files
+if not exist "config" mkdir config
+if not exist "owned_cards" mkdir owned_cards
+
+echo Starting MTG Python Deckbuilder from Docker Hub...
+echo Your files will be saved in the current directory:
+echo   - deck_files\: Your completed decks
+echo   - logs\: Application logs
+echo   - csv_files\: Card database files
+echo   - config\: JSON configs for headless runs (e.g., deck.json)
+echo.
+
+REM Run the Docker container with proper volume mounts
+docker run -it --rm ^
+  -v "%cd%\deck_files:/app/deck_files" ^
+  -v "%cd%\logs:/app/logs" ^
+  -v "%cd%\csv_files:/app/csv_files" ^
+  -v "%cd%\owned_cards:/app/owned_cards" ^
+  -v "%cd%\config:/app/config" ^
+  mwisnowski/mtg-python-deckbuilder:latest
+
+echo.
+echo MTG Python Deckbuilder session ended.
+echo Your files are saved in: %cd%
+echo.
+echo Tips:
+echo   - For headless: set environment variables, e.g. -e DECK_MODE=headless -e DECK_CONFIG=/app/config/deck.json
+echo   - If the container seems to use an old config, mount the config folder (done above) or prune anonymous volumes.
+pause
--- a/docs/archive/run-from-dockerhub_2026-03-23.sh
+++ b/docs/archive/run-from-dockerhub_2026-03-23.sh
@ -0,0 +1,29 @@
+#!/bin/bash
+
+echo "MTG Python Deckbuilder - Docker Hub Runner"
+echo "==========================================="
+
+# Create directories if they don't exist
+mkdir -p deck_files logs csv_files
+mkdir -p config owned_cards
+
+echo "Starting MTG Python Deckbuilder from Docker Hub..."
+echo "Your files will be saved in the current directory:"
+echo "  - deck_files/: Your completed decks"
+echo "  - logs/: Application logs"  
+echo "  - csv_files/: Card database files"
+echo "  - config/: JSON configs for headless runs (e.g., deck.json)"
+echo
+
+# Run the Docker container with proper volume mounts
+docker run -it --rm \
+  -v "$(pwd)/deck_files":/app/deck_files \
+  -v "$(pwd)/logs":/app/logs \
+  -v "$(pwd)/csv_files":/app/csv_files \
+  -v "$(pwd)/owned_cards":/app/owned_cards \
+  -v "$(pwd)/config":/app/config \
+  mwisnowski/mtg-python-deckbuilder:latest
+
+echo
+echo "MTG Python Deckbuilder session ended."
+echo "Your files are saved in: $(pwd)"