diff --git a/.env.example b/.env.example
index 79bc536..b0de4f9 100644
--- a/.env.example
+++ b/.env.example
@@ -29,16 +29,23 @@ DAV_SKIP_INIT=1
 # Prod only: Cloudflare R2 (overrides S3_* vars in non-dev builds).
 # Local dev uses the S3_* vars above (from .env). Not needed for local builds.
 R2_ENDPOINT=
-# R2_ACCESS_KEY=<your-access-key>
-# R2_SECRET_KEY=<your-secret-key>
-# R2_BUCKET=crussell
-# R2_PUBLIC_URL=https://pub-<your-domain>.r2.dev
+# Required for production object storage — the prod S3 client (backend/internal/s3/s3.go,
+# via getEnv) reads all four below; not needed for local dev builds.
+R2_ACCESS_KEY=
+R2_SECRET_KEY=
+R2_BUCKET=crussell
+R2_PUBLIC_URL=
 
 # Square Payment Gateway
 SQUARE_ACCESS_TOKEN=
 SQUARE_LOCATION_ID=
 SQUARE_TERMINAL_DEVICE_ID=
 SQUARE_ENVIRONMENT=mock
+# Webhook config MUST exactly match the Square Dashboard webhook subscription
+# (URL + signature key). If SQUARE_WEBHOOK_NOTIFICATION_URL is left unset it
+# defaults to http://localhost:8080/webhooks/square, which is fail-closed (503
+# without the signing key, 403 on missing/bad signature). Leave both empty if
+# you do not use webhooks.
 SQUARE_WEBHOOK_SIGNATURE_KEY=
 SQUARE_WEBHOOK_NOTIFICATION_URL=
 
diff --git a/compose.yml b/compose.yml
index f7b125e..cbe5524 100644
--- a/compose.yml
+++ b/compose.yml
@@ -22,7 +22,7 @@ services:
     container_name: backend
     restart: always
     env_file:
-      - ./backend/.env
+      - ./.env # created via `cp .env.example .env` (see README Getting Started)
     volumes:
       - ./backend/bin:/app/bin # Mount your compiled binary
     depends_on: