diff --git a/docker/.env.example b/docker/.env.example
index 8257a80d6..d3598f16a 100644
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -43,76 +43,52 @@ ETL_SERVICE=DOCLING
 EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 
 # ------------------------------------------------------------------------------
-# Public proxy ports (change to avoid conflicts with other services on your machine)
+# How You Access SurfSense
 # ------------------------------------------------------------------------------
-
-# LISTEN_HTTP_PORT maps the bundled Caddy proxy's container port 80 to the host.
-# The default preserves the familiar http://localhost:3929 URL.
-# LISTEN_HTTP_PORT=3929
-#
-# LISTEN_HTTPS_PORT is used when SURFSENSE_SITE_ADDRESS is a domain.
-# LISTEN_HTTPS_PORT=443
-# SEARXNG_PORT=8888
-
-# ==============================================================================
-# DEV COMPOSE ONLY (docker-compose.dev.yml)
-# You only need them only if you are running `docker-compose.dev.yml`.
-# ==============================================================================
-
-# -- pgAdmin (database GUI) --
-# PGADMIN_PORT=5050
-# PGADMIN_DEFAULT_EMAIL=admin@surfsense.com
-# PGADMIN_DEFAULT_PASSWORD=surfsense
-
-# -- Redis exposed port (dev only; Redis is internal-only in prod) --
-# REDIS_PORT=6379
-
-# -- WhatsApp bridge exposed port (dev/hybrid only; prod keeps it Docker-internal) --
-# WHATSAPP_BRIDGE_PORT=9929
-#
-# -- Raw app ports (dev/deps-only compose only; prod exposes Caddy instead) --
-# BACKEND_PORT=8000
-# FRONTEND_PORT=3000
-# ZERO_CACHE_PORT=4848
-
-# -- Frontend Build Args --
-# In dev, the frontend is built from source and these are passed as build args.
-# In prod, they are automatically derived from AUTH_TYPE, ETL_SERVICE, and the port settings above.
-# NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE=LOCAL
-# NEXT_PUBLIC_ETL_SERVICE=DOCLING
-# NEXT_PUBLIC_DEPLOYMENT_MODE=self-hosted
-
-# ------------------------------------------------------------------------------
-# Public URL / Reverse Proxy
-# ------------------------------------------------------------------------------
-# SurfSense includes Caddy as the default single public entry point.
-# Localhost defaults require no changes:
-#   SURFSENSE_SITE_ADDRESS=:80
-#   LISTEN_HTTP_PORT=3929
-#   SURFSENSE_PUBLIC_URL=http://localhost:3929
-#
-# For a real domain, point DNS at this host and set:
-#   SURFSENSE_SITE_ADDRESS=surf.example.com
-#   LISTEN_HTTP_PORT=80
-#   LISTEN_HTTPS_PORT=443
-#   CERT_EMAIL=you@example.com
-#   SURFSENSE_PUBLIC_URL=https://surf.example.com
-#
-# SURFSENSE_SITE_ADDRESS=:80
+# Default local URL: http://localhost:3929
+# Most local installs can leave this unchanged.
 # SURFSENSE_PUBLIC_URL=http://localhost:3929
+
+# ------------------------------------------------------------------------------
+# Public Ports
+# ------------------------------------------------------------------------------
+# Production Docker exposes only Caddy to your machine. Caddy then routes
+# frontend, backend, and zero-cache traffic internally.
+#
+# Local default: LISTEN_HTTP_PORT=3929
+# Domain default: LISTEN_HTTP_PORT=80 and LISTEN_HTTPS_PORT=443
+# LISTEN_HTTP_PORT=3929
+# LISTEN_HTTPS_PORT=443
+
+# ------------------------------------------------------------------------------
+# Custom Domain / HTTPS
+# ------------------------------------------------------------------------------
+# Leave SURFSENSE_SITE_ADDRESS as :80 for local HTTP.
+# Set it to your domain to enable automatic HTTPS:
+# SURFSENSE_SITE_ADDRESS=surf.example.com
+# CERT_EMAIL=you@example.com
+# SURFSENSE_SITE_ADDRESS=:80
 # CERT_EMAIL=
+
+# ------------------------------------------------------------------------------
+# Advanced Reverse Proxy Settings
+# ------------------------------------------------------------------------------
+# Usually do not change these. They are for custom certificate setup, CDNs/load
+# balancers, trusted proxy IPs, or changing upload limits.
+#
 # CERT_ACME_CA=https://acme-v02.api.letsencrypt.org/directory
 # CERT_ACME_DNS=
 # TRUSTED_PROXIES=0.0.0.0/0
 # SURFSENSE_MAX_BODY_SIZE=5GB
 #
-# The compose file derives the browser-facing URLs from SURFSENSE_PUBLIC_URL:
+# These browser-facing URLs are derived from SURFSENSE_PUBLIC_URL in
+# docker-compose.yml:
 # NEXT_FRONTEND_URL=${SURFSENSE_PUBLIC_URL}
 # BACKEND_URL=${SURFSENSE_PUBLIC_URL}
 # NEXT_PUBLIC_FASTAPI_BACKEND_URL=${SURFSENSE_PUBLIC_URL}
 # NEXT_PUBLIC_ZERO_CACHE_URL=${SURFSENSE_PUBLIC_URL}/zero
 #
-# Internal service-to-service URLs stay on Docker DNS:
+# Internal service-to-service URL. Usually do not change.
 # FASTAPI_BACKEND_INTERNAL_URL=http://backend:8000
 
 # ------------------------------------------------------------------------------
@@ -134,10 +110,9 @@ EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 
 # Sync worker tuning. zero-cache defaults ZERO_NUM_SYNC_WORKERS to the number
 # of CPU cores, which can exceed the connection pool limits on high-core machines.
-# Each sync worker needs at least 1 connection from both the UPSTREAM and CVR
-# pools, so these constraints must hold:
-#   ZERO_UPSTREAM_MAX_CONNS >= ZERO_NUM_SYNC_WORKERS
-#   ZERO_CVR_MAX_CONNS      >= ZERO_NUM_SYNC_WORKERS
+# Each sync worker needs at least 1 connection from both the UPSTREAM and CVR pools.
+# Keep ZERO_UPSTREAM_MAX_CONNS and ZERO_CVR_MAX_CONNS greater than or equal to
+# ZERO_NUM_SYNC_WORKERS.
 # Default of 4 workers is sufficient for self-hosted / personal use.
 # ZERO_NUM_SYNC_WORKERS=4
 # ZERO_UPSTREAM_MAX_CONNS=20
@@ -151,16 +126,16 @@ EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 
 # ZERO_QUERY_URL: where zero-cache forwards query requests for resolution.
 # ZERO_MUTATE_URL: required by zero-cache when auth tokens are used, even though
-#   SurfSense does not use Zero mutators. Setting both URLs tells zero-cache to
-#   skip its own JWT verification and let the app endpoints handle auth instead.
-#   The mutate endpoint is a no-op that returns an empty response.
+# SurfSense does not use Zero mutators. Setting both URLs tells zero-cache to
+# skip its own JWT verification and let the app endpoints handle auth instead.
+# The mutate endpoint is a no-op that returns an empty response.
 # Default: Docker service networking (http://frontend:3000/api/zero/...).
 # Override when running the frontend outside Docker:
-#   ZERO_QUERY_URL=http://host.docker.internal:3000/api/zero/query
-#   ZERO_MUTATE_URL=http://host.docker.internal:3000/api/zero/mutate
+# ZERO_QUERY_URL=http://host.docker.internal:3000/api/zero/query
+# ZERO_MUTATE_URL=http://host.docker.internal:3000/api/zero/mutate
 # Override for custom domain only when zero-cache is not in the bundled Docker network:
-#   ZERO_QUERY_URL=https://surf.example.com/api/zero/query
-#   ZERO_MUTATE_URL=https://surf.example.com/api/zero/mutate
+# ZERO_QUERY_URL=https://surf.example.com/api/zero/query
+# ZERO_MUTATE_URL=https://surf.example.com/api/zero/mutate
 # ZERO_QUERY_URL=http://frontend:3000/api/zero/query
 # ZERO_MUTATE_URL=http://frontend:3000/api/zero/mutate
 
@@ -483,3 +458,37 @@ NOLOGIN_MODE_ENABLED=FALSE
 # RESIDENTIAL_PROXY_HOSTNAME=
 # RESIDENTIAL_PROXY_LOCATION=
 # RESIDENTIAL_PROXY_TYPE=1
+
+# ==============================================================================
+# DEV / DEPS-ONLY COMPOSE OVERRIDES
+# These are only needed for docker-compose.dev.yml or docker-compose.deps-only.yml.
+# Production Docker exposes Caddy only; raw app ports below do not affect
+# docker-compose.yml.
+# ==============================================================================
+
+# -- pgAdmin (database GUI, dev/deps-only only) --
+# PGADMIN_PORT=5050
+# PGADMIN_DEFAULT_EMAIL=admin@surfsense.com
+# PGADMIN_DEFAULT_PASSWORD=surfsense
+
+# -- Redis exposed port (dev/deps-only only; Redis is internal-only in prod) --
+# REDIS_PORT=6379
+
+# -- SearXNG exposed port (dev/deps-only only; internal-only in prod) --
+# SEARXNG_PORT=8888
+
+# -- WhatsApp bridge exposed port (dev/hybrid only; prod keeps it Docker-internal) --
+# WHATSAPP_BRIDGE_PORT=9929
+
+# -- Raw app ports (dev/deps-only only; prod exposes Caddy instead) --
+# BACKEND_PORT=8000
+# FRONTEND_PORT=3000
+# ZERO_CACHE_PORT=4848
+
+# -- Frontend build args (dev compose only) --
+# In dev, the frontend is built from source and these are passed as build args.
+# In prod, runtime values are derived from AUTH_TYPE, ETL_SERVICE, and
+# SURFSENSE_PUBLIC_URL.
+# NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE=LOCAL
+# NEXT_PUBLIC_ETL_SERVICE=DOCLING
+# NEXT_PUBLIC_DEPLOYMENT_MODE=self-hosted