diff --git a/.env.example b/.env.example
index 0864f24..d9b883f 100644
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,26 @@
 # libnovel scraper — environment overrides
 # Copy to .env and adjust values; do NOT commit this file with real secrets.
 
+# ── Service ports (host-side) ─────────────────────────────────────────────────
+# Port the scraper HTTP API listens on (default 8080)
+SCRAPER_PORT=8080
+
+# Port PocketBase listens on (default 8090)
+POCKETBASE_PORT=8090
+
+# Port MinIO S3 API listens on (default 9000)
+MINIO_PORT=9000
+
+# Port MinIO web console listens on (default 9001)
+MINIO_CONSOLE_PORT=9001
+
+# Port Browserless Chrome listens on (default 3030)
+BROWSERLESS_PORT=3030
+
+# Port the SvelteKit UI listens on (default 3000)
+UI_PORT=3000
+
+# ── Browserless ───────────────────────────────────────────────────────────────
 # Browserless API token (leave empty to disable auth)
 BROWSERLESS_TOKEN=
 
@@ -23,6 +43,7 @@ BROWSERLESS_STRATEGY=direct
 # Set to direct to use plain HTTP, or content/scrape/cdp for browserless.
 BROWSERLESS_URL_STRATEGY=content
 
+# ── Scraper ───────────────────────────────────────────────────────────────────
 # Chapter worker goroutines (0 = NumCPU inside the container)
 SCRAPER_WORKERS=0
 
@@ -46,14 +67,21 @@ MINIO_ROOT_PASSWORD=changeme123
 MINIO_BUCKET_CHAPTERS=libnovel-chapters
 MINIO_BUCKET_AUDIO=libnovel-audio
 
-# PocketBase admin credentials (used by scraper + UI server-side)
+# ── PocketBase ────────────────────────────────────────────────────────────────
+# Admin credentials (used by scraper + UI server-side)
 POCKETBASE_ADMIN_EMAIL=admin@libnovel.local
 POCKETBASE_ADMIN_PASSWORD=changeme123
 
 # ── SvelteKit UI ─────────────────────────────────────────────────────────────
-# Port the UI container exposes on the host
-UI_PORT=3000
+# Internal URL the SvelteKit server uses to reach the scraper API.
+# In docker-compose this is http://scraper:8080 (wired automatically).
+# Override here only if running the UI outside of docker-compose.
+SCRAPER_API_URL=http://localhost:8080
 
-# Public MinIO URL reachable from the browser (for audio/presigned URLs)
+# Internal URL the SvelteKit server uses to reach PocketBase.
+# In docker-compose this is http://pocketbase:8090 (wired automatically).
+POCKETBASE_URL=http://localhost:8090
+
+# Public MinIO URL reachable from the browser (for audio/presigned URLs).
 # In production, point this at your MinIO reverse-proxy or CDN domain.
 PUBLIC_MINIO_PUBLIC_URL=http://localhost:9000