diff --git a/README.md b/README.md
index 793bdb9..d1e4aa5 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,65 @@ Magent is a friendly, AI-assisted request tracker for Jellyseerr + Arr services.
 - Local account password changes via "My profile".
 - Docker-first deployment for easy hosting.
 
-## Backend (FastAPI)
+## Quick start (Docker - primary)
+
+Docker is the recommended way to run Magent. It includes the backend and frontend with sane defaults.
+
+```bash
+docker compose up --build
+```
+
+Then open:
+
+- Frontend: http://localhost:3000
+- Backend: http://localhost:8000
+
+### Docker setup steps
+
+1) Create `.env` with your service URLs and API keys.
+2) Run `docker compose up --build`.
+3) Log in at http://localhost:3000.
+4) Visit Settings to confirm service health.
+
+### Docker environment variables (sample)
+
+```bash
+JELLYSEERR_URL="http://localhost:5055"
+JELLYSEERR_API_KEY="..."
+SONARR_URL="http://localhost:8989"
+SONARR_API_KEY="..."
+SONARR_QUALITY_PROFILE_ID="1"
+SONARR_ROOT_FOLDER="/tv"
+RADARR_URL="http://localhost:7878"
+RADARR_API_KEY="..."
+RADARR_QUALITY_PROFILE_ID="1"
+RADARR_ROOT_FOLDER="/movies"
+PROWLARR_URL="http://localhost:9696"
+PROWLARR_API_KEY="..."
+QBIT_URL="http://localhost:8080"
+QBIT_USERNAME="..."
+QBIT_PASSWORD="..."
+SQLITE_PATH="data/magent.db"
+JWT_SECRET="change-me"
+JWT_EXP_MINUTES="720"
+ADMIN_USERNAME="admin"
+ADMIN_PASSWORD="adminadmin"
+```
+
+## Screenshots
+
+Add screenshots here once available:
+
+- `docs/screenshots/home.png`
+- `docs/screenshots/request-timeline.png`
+- `docs/screenshots/settings.png`
+- `docs/screenshots/profile.png`
+
+## Local development (secondary)
+
+Use this only when you need to modify code locally.
+
+### Backend (FastAPI)
 
 ```bash
 cd backend
@@ -60,7 +118,7 @@ $env:ADMIN_USERNAME="admin"
 $env:ADMIN_PASSWORD="adminadmin"
 ```
 
-## Frontend (Next.js)
+### Frontend (Next.js)
 
 ```bash
 cd frontend
@@ -74,15 +132,6 @@ Admin panel: http://localhost:3000/admin
 
 Login uses the admin credentials above (or any other local user you create in SQLite).
 
-## Docker (Testing)
-
-```bash
-docker compose up --build
-```
-
-Backend: http://localhost:8000  
-Frontend: http://localhost:3000
-
 ## Public Hosting Notes
 
 The frontend proxies `/api/*` to the backend container. Set:
@@ -96,3 +145,25 @@ If you prefer the browser to call the backend directly, set `NEXT_PUBLIC_API_BAS
 
 - `GET /requests/{id}/history?limit=10` recent snapshots
 - `GET /requests/{id}/actions?limit=10` recent action logs
+
+## Troubleshooting
+
+### Login fails
+
+- Make sure `ADMIN_USERNAME` and `ADMIN_PASSWORD` are set in `.env`.
+- Confirm the backend is reachable: `http://localhost:8000/health` (or see container logs).
+
+### Services show as down
+
+- Check the URLs and API keys in Settings.
+- Verify containers can reach each service (network/DNS).
+
+### No recent requests
+
+- Confirm Jellyseerr credentials in Settings.
+- Run a full sync from Settings -> Requests.
+
+### Docker images not updating
+
+- Run `docker compose up --build` again.
+- If needed, run `docker compose down` first, then rebuild.