Fixing how uv is being used in the base image, adding Poe the Poet to everything.

Signed-off-by: Cliff Hill <xlorep@darkhelm.org>

docs/DEVELOPMENT.md

@@ -6,14 +6,16 @@ This document outlines how to set up your development environment and work with
 
 1. [Quick Start](#quick-start)
 2. [Development Environment Setup](#development-environment-setup)
-3. [Git Workflow](#git-workflow)
-4. [Pre-commit Hooks](#pre-commit-hooks)
-5. [Manual Tool Usage](#manual-tool-usage)
-6. [CI/CD Pipeline](#cicd-pipeline)
-7. [Branch Protection and Merge Requirements](#branch-protection-and-merge-requirements)
+3. [Poe the Poet Task Runner](#poe-the-poet-task-runner)
+4. [Git Workflow](#git-workflow)
+5. [Pre-commit Hooks](#pre-commit-hooks)
+6. [Manual Tool Usage](#manual-tool-usage)
+7. [CI/CD Pipeline](#cicd-pipeline)
+8. [Branch Protection and Merge Requirements](#branch-protection-and-merge-requirements)
 
 ## Related Documentation
 
+- **[Poe Task Reference](POE_TASK_REFERENCE.md)** - Complete guide to unified development tasks
 - **[CI/CD Multi-Stage Build Architecture](CICD_MULTI_STAGE_BUILD.md)** - Technical details of the optimized build system
 - **[CI/CD Troubleshooting](GITEA_ACTIONS_TROUBLESHOOTING.md)** - Common issues and solutions
 - **[Secure Docker CI/CD](SECURE_DOCKER_CICD.md)** - Security considerations and practices
@@ -25,15 +27,19 @@ This document outlines how to set up your development environment and work with
 git clone ssh://git@dogar.darkhelm.org:2222/DarkHelm.org/plex-playlist.git
 cd plex-playlist
 
-# Start development environment
-docker compose -f compose.dev.yml up -d
+# Complete setup with Poe the Poet (recommended)
+cd backend && uv sync --dev && cd ..
+poe setup
 
-# Set up pre-commit (recommended)
-pip install pre-commit
-pre-commit install
+# OR manual setup
+docker compose -f compose.dev.yml up -d
+pip install pre-commit && pre-commit install
 
 # Create a feature branch and start developing
 git checkout -b feature/your-feature-name
+
+# Use Poe for all development tasks
+poe format lint type-check test-unit
 ```
 
 ## Development Environment Setup
@@ -68,6 +74,55 @@ docker compose -f compose.dev.yml up -d --build
 - **API Documentation**: http://localhost:8000/docs
 - **Database**: localhost:5432 (user: `plex`, password: see `secrets/postgres_password`)
 
+## Poe the Poet Task Runner
+
+This project uses **Poe the Poet** as a unified task runner to simplify and standardize development workflows. Instead of remembering different commands for backend and frontend, you can use consistent `poe` commands from anywhere in the project.
+
+### Quick Start with Poe
+
+```bash
+# Complete development setup (new developers)
+poe setup
+
+# Start development environment
+poe dev
+
+# Run all quality checks (format, lint, type-check)
+poe ci-quick
+
+# Run all tests
+poe test-all
+
+# See all available tasks
+poe --help
+```
+
+### Key Benefits
+
+- **Unified Interface**: Same commands work for backend (Python) and frontend (TypeScript)
+- **Parallel Execution**: Tasks run in parallel for better performance
+- **Smart Workflows**: Conditional and chained task execution
+- **Developer Friendly**: Interactive task selection and helpful descriptions
+- **CI Integration**: Local simulation of CI/CD pipeline
+
+### Common Workflows
+
+```bash
+# Daily development workflow
+poe format lint type-check test-unit
+
+# Pre-commit workflow (faster than full CI)
+poe ci-quick
+
+# Complete quality gate (like CI pipeline)
+poe quality-gate
+
+# Build and test Docker images locally
+poe build-cicd
+```
+
+For the complete list of tasks and detailed usage, see **[Poe Task Reference](POE_TASK_REFERENCE.md)**.
+
 ## Git Workflow
 
 ### Branch Strategy

docs/POE_TASK_REFERENCE.md

@@ -0,0 +1,178 @@
+# Poe the Poet Task Reference
+
+This project uses **Poe the Poet** as a unified task runner to simplify development workflows. All tasks are defined in `backend/pyproject.toml` and can be run from the project root.
+
+## 🚀 Quick Start
+
+```bash
+# Install dependencies and set up development environment
+poe setup
+
+# See all available tasks
+poe --help
+
+# Interactive task selection
+poe
+```
+
+## 📋 Essential Tasks
+
+### Development Environment
+```bash
+poe dev              # Start development environment (Docker Compose)
+poe dev-down         # Stop development environment
+poe dev-logs         # Follow development logs
+poe dev-restart      # Restart development environment
+```
+
+### Code Quality (Unified Backend + Frontend)
+```bash
+poe format           # Format all code (Python + TypeScript)
+poe lint             # Lint all code (Python + TypeScript)
+poe type-check       # Type check all code (Python + TypeScript)
+```
+
+### Testing
+```bash
+poe test-unit        # Run all unit tests (backend + frontend)
+poe test-all         # Run all tests including integration
+poe test-full        # Run all tests with coverage + E2E
+poe test-e2e         # Run end-to-end tests only
+```
+
+### CI/CD Pipeline
+```bash
+poe ci-quick         # Fast quality checks (format, lint, type-check)
+poe ci-full          # Complete CI pipeline simulation
+poe quality-gate     # All quality checks (like CI)
+```
+
+### Docker Images
+```bash
+poe build-cicd       # Build both base and complete CI/CD images
+poe build-cicd-base  # Build only base image (cached dependencies)
+poe build-cicd-complete  # Build only complete image (fast)
+```
+
+## 🏃‍♂️ Performance Tasks (Parallel Execution)
+
+```bash
+poe lint-parallel         # Run linting in parallel for speed
+poe type-check-parallel   # Run type checking in parallel
+poe test-parallel         # Run tests in parallel
+```
+
+## 🧠 Smart Tasks (Conditional Execution)
+
+```bash
+poe test-if-changed       # Only test if code changed
+poe build-if-dockerfile-changed  # Only build if Dockerfiles changed
+```
+
+## 🛠 Utility Tasks
+
+```bash
+poe deps-install     # Install all dependencies (backend + frontend)
+poe deps-update      # Update all dependencies
+poe clean            # Clean build artifacts and caches
+poe reset            # Complete reset (clean + reinstall)
+```
+
+## 🔧 Individual Component Tasks
+
+### Backend Only
+```bash
+poe format-backend       # Format Python code only
+poe lint-backend         # Lint Python code only
+poe type-check-backend   # Type check Python only
+poe test-backend         # Run backend tests only
+poe test-backend-cov     # Backend tests with coverage
+```
+
+### Frontend Only
+```bash
+poe format-frontend      # Format TypeScript code only
+poe lint-frontend        # Lint TypeScript code only
+poe type-check-frontend  # Type check TypeScript only
+poe test-frontend        # Run frontend tests only
+poe test-frontend-cov    # Frontend tests with coverage
+```
+
+## 📚 Documentation Tasks
+
+```bash
+poe docs-backend     # Run docstring tests
+poe docs-check       # Check docstring quality
+```
+
+## 🎣 Pre-commit Integration
+
+```bash
+poe pre-commit-install   # Install pre-commit hooks
+poe pre-commit-run       # Run all pre-commit hooks
+poe pre-commit-update    # Update hook versions
+```
+
+## 💡 Tips & Tricks
+
+### Task Discovery
+```bash
+poe --help           # List all tasks with descriptions
+poe <task> --help    # Get help for specific task
+poe                  # Interactive task picker
+```
+
+### Chaining Tasks
+```bash
+# Run multiple tasks in sequence
+poe format lint type-check test-unit
+
+# Custom workflows
+poe clean deps-install ci-quick
+```
+
+### Environment Context
+- All tasks run from project root
+- Backend tasks automatically use `uv run` in correct environment
+- Frontend tasks automatically use `yarn` in correct directory
+- Docker tasks use the optimized multi-stage CI/CD setup
+
+### Performance Tips
+- Use parallel tasks (`*-parallel`) for faster feedback
+- Use conditional tasks (`*-if-changed`) to save time
+- `poe setup` configures everything for new developers
+- `poe quality-gate` runs full CI checks locally
+
+## 🔄 Migration from Manual Commands
+
+### Before (Manual)
+```bash
+cd backend && uv run ruff format .
+cd frontend && yarn prettier --write src/
+cd backend && uv run pytest
+cd frontend && yarn test
+./scripts/build-cicd-local.sh
+```
+
+### After (Poe)
+```bash
+poe format
+poe test-unit
+poe build-cicd
+```
+
+## 🏗 Integration with Existing Workflows
+
+- **Pre-commit hooks**: Still work as before, Poe complements them
+- **CI/CD pipeline**: Uses same tools, Poe provides local simulation
+- **Docker development**: `poe dev` replaces manual docker-compose commands
+- **Scripts**: Existing scripts still work, Poe provides unified interface
+
+## 🎯 Next Steps
+
+1. **Try it out**: `poe setup` to get started
+2. **Explore tasks**: `poe --help` to see all options
+3. **Customize**: Add project-specific tasks to `backend/pyproject.toml`
+4. **Share**: Team members can use same unified interface
+
+This unified task system makes development faster, more consistent, and easier for new team members to learn!