diff --git a/.env.example b/.env.example
index ab83449..5da8bc8 100644
--- a/.env.example
+++ b/.env.example
@@ -1,28 +1,148 @@
-# AI Provider Configuration
-# Options: openai, stability, replicate, mock
-# - openai: DALL-E 2 (low quality, not recommended)
-# - stability: Stability AI SDXL (good quality, ~$0.04/image)
-# - replicate: Multiple models (best value, ~$0.002-0.025/image)
-# - mock: No AI, returns original (for testing)
-AI_PROVIDER=mock
+# =============================================================================
+# AI Photo Edit - Environment Configuration
+# =============================================================================
+#
+# SETUP INSTRUCTIONS:
+#   1. Copy this file to .env:  cp .env.example .env
+#   2. Get API key from Replicate (see below)
+#   3. Paste your key in the REPLICATE_API_KEY line
+#   4. Rebuild: docker-compose up -d --build
+#
+# =============================================================================
 
-# API Keys
-OPENAI_API_KEY=
-STABILITY_API_KEY=
-REPLICATE_API_KEY=
 
-# Model Selection (optional, provider-specific)
-# Stability AI models: sdxl (default), sd15, sd21
-STABILITY_MODEL=sdxl
+# =============================================================================
+# STEP 1: Choose AI Provider
+# =============================================================================
+# Options: mock, openai, stability, replicate
+#
+#   mock      = Free, but returns original image unchanged (for testing UI)
+#   openai    = DALL-E 2 inpainting (~$0.02/image) - lower quality
+#   stability = Stability AI SDXL (~$0.01/image) - good quality
+#   replicate = Multiple models (~$0.002-0.03/image) - RECOMMENDED
+#
+# RECOMMENDED: Use "replicate" for best quality and model variety
+# =============================================================================
 
-# Replicate models: sdxl-inpaint (default), lama, realistic-vision
-# - sdxl-inpaint: Best general purpose (~$0.025/image)
-# - lama: Best for object removal (~$0.002/image)
-# - realistic-vision: Best for humans/faces/hands (~$0.020/image)
-REPLICATE_MODEL=sdxl-inpaint
+AI_PROVIDER=replicate
 
-# Allow per-edit model override (true/false)
+
+# =============================================================================
+# STEP 2: Get Your API Key
+# =============================================================================
+#
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  REPLICATE (RECOMMENDED)                                                  ║
+# ╠═══════════════════════════════════════════════════════════════════════════╣
+# ║                                                                           ║
+# ║  1. Go to: https://replicate.com                                         ║
+# ║  2. Click "Sign in" (use GitHub, Google, or email)                       ║
+# ║  3. Go to: https://replicate.com/account/api-tokens                      ║
+# ║  4. Click "Create token"                                                  ║
+# ║  5. Copy the token (starts with "r8_")                                   ║
+# ║  6. Paste it below after REPLICATE_API_KEY=                              ║
+# ║                                                                           ║
+# ║  FREE TIER: New accounts get some free credits to try models!            ║
+# ║  PRICING: ~$0.002-0.03 per image depending on model                      ║
+# ║                                                                           ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+
+REPLICATE_API_KEY=r8_PASTE_YOUR_KEY_HERE
+
+# ───────────────────────────────────────────────────────────────────────────
+# OPENAI (Alternative - not recommended, lower quality)
+# Get key at: https://platform.openai.com/api-keys
+# ───────────────────────────────────────────────────────────────────────────
+#OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# ───────────────────────────────────────────────────────────────────────────
+# STABILITY AI (Alternative)
+# Get key at: https://platform.stability.ai/account/keys
+# ───────────────────────────────────────────────────────────────────────────
+#STABILITY_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+
+# =============================================================================
+# STEP 3: Model Selection (OPTIONAL - for advanced users)
+# =============================================================================
+#
+# By default, the system AUTO-SELECTS the best model based on your prompt:
+#   - Prompt contains "remove/erase/delete" → Uses LaMa (fast removal)
+#   - Prompt contains "face/hands/person"   → Uses Realistic Vision
+#   - Everything else                       → Uses SDXL Inpaint
+#
+# To FORCE a specific model, uncomment ONE line below:
+# ───────────────────────────────────────────────────────────────────────────
+
+# REPLICATE_MODEL=sdxl-inpaint      # General purpose, good quality (~$0.01)
+# REPLICATE_MODEL=lama              # Object removal ONLY (~$0.002, fastest)
+# REPLICATE_MODEL=realistic-vision  # Faces, hands, skin (~$0.02)
+
+# ───────────────────────────────────────────────────────────────────────────
+# IMPORTANT: About Flux and other text-to-image models
+# ───────────────────────────────────────────────────────────────────────────
+#
+# Models like "black-forest-labs/flux-kontext-pro" are TEXT-TO-IMAGE models.
+# They generate NEW images from text, they DON'T edit existing images.
+#
+# For EDITING (inpainting), you need models that accept:
+#   - An existing image
+#   - A mask showing what to change
+#   - A prompt describing the change
+#
+# WORKS for editing:        DOESN'T work for editing:
+#   ✓ sdxl-inpaint           ✗ flux-kontext-pro (text-to-image)
+#   ✓ lama                   ✗ flux-dev (text-to-image)
+#   ✓ realistic-vision       ✗ ideogram (text-to-image)
+#
+# ───────────────────────────────────────────────────────────────────────────
+
+# Stability AI model selection (if using AI_PROVIDER=stability)
+#STABILITY_MODEL=sdxl   # Options: sdxl, sd15, sd21
+
+
+# =============================================================================
+# SECURITY (Change this in production!)
+# =============================================================================
+
+SECRET_KEY=change-this-to-a-long-random-string-in-production
+
+
+# =============================================================================
+# ADVANCED SETTINGS (Usually don't need to change)
+# =============================================================================
+
+# CORS origins (comma-separated)
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000,http://localhost:3080,http://localhost
+
+# Database path
+DATABASE_URL=sqlite:///./data/photoedit.db
+
+# Allow users to select model per-edit
 ALLOW_MODEL_OVERRIDE=true
 
-# Secret key for JWT tokens (change in production)
-SECRET_KEY=change-this-secret-key-in-production
+
+# =============================================================================
+# TROUBLESHOOTING
+# =============================================================================
+#
+# PROBLEM: "405 Method Not Allowed" errors
+# FIX:     Rebuild container: docker-compose build --no-cache && docker-compose up -d
+#
+# PROBLEM: "REPLICATE_API_KEY not configured"
+# FIX:     1. Make sure .env file exists (not just .env.example)
+#          2. Make sure REPLICATE_API_KEY has your actual key
+#          3. Restart: docker-compose down && docker-compose up -d
+#
+# PROBLEM: Edits don't change the image
+# FIX:     Check AI_PROVIDER isn't set to "mock"
+#
+# PROBLEM: "rembg not installed"
+# FIX:     Rebuild: docker-compose build --no-cache backend
+#
+# PROBLEM: Smart Select uses flood-fill instead of AI
+# FIX:     Smart Select needs REPLICATE_API_KEY for SAM model
+#
+# CHECK LOGS: docker-compose logs -f backend
+#
+# =============================================================================
diff --git a/backend/Dockerfile b/backend/Dockerfile
index 6f85f98..280416c 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -25,11 +25,15 @@ RUN python -c "from rembg import remove; print('rembg model downloaded')" || tru
 # Copy application
 COPY . .
 
+# Copy entrypoint script and make it executable
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
 # Create data directories
 RUN mkdir -p /app/data/projects /app/data/patches /app/data/models
 
 # Expose port
 EXPOSE 8000
 
-# Run the application
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+# Use entrypoint script (auto-populates eyes on first run, then starts server)
+ENTRYPOINT ["/entrypoint.sh"]
diff --git a/backend/entrypoint.sh b/backend/entrypoint.sh
new file mode 100644
index 0000000..ab2fa5b
--- /dev/null
+++ b/backend/entrypoint.sh
@@ -0,0 +1,38 @@
+#!/bin/bash
+# =============================================================================
+# AI Photo Edit - Container Startup Script
+# =============================================================================
+# This script runs when the container starts. It:
+# 1. Downloads sample eye images if the catalog is empty
+# 2. Ensures all directories exist
+# 3. Starts the FastAPI server
+# =============================================================================
+
+set -e
+
+echo "=========================================="
+echo "AI Photo Edit - Starting Up"
+echo "=========================================="
+
+# Ensure data directories exist
+mkdir -p /app/data/projects
+mkdir -p /app/data/patches
+mkdir -p /app/data/models
+
+# Check if eye catalog needs to be populated
+echo "Checking eye catalog..."
+PATCHES_COUNT=$(find /app/data/patches -maxdepth 1 -type d | wc -l)
+
+if [ "$PATCHES_COUNT" -le 1 ]; then
+    echo "Eye catalog is empty. Downloading sample eyes..."
+    python /scripts/download_sample_eyes.py || echo "Warning: Could not download sample eyes (non-fatal)"
+else
+    echo "Eye catalog has content, skipping download."
+fi
+
+echo "=========================================="
+echo "Starting FastAPI server..."
+echo "=========================================="
+
+# Start the server
+exec uvicorn app.main:app --host 0.0.0.0 --port 8000