diff --git a/deploy/compose/.env.example b/deploy/compose/.env.example
index cebe879da0..0c18761812 100644
--- a/deploy/compose/.env.example
+++ b/deploy/compose/.env.example
@@ -10,6 +10,18 @@ BUZZ_DOMAIN=buzz.example.com
 RELAY_URL=wss://buzz.example.com
 BUZZ_MEDIA_BASE_URL=https://buzz.example.com/media
 BUZZ_MEDIA_SERVER_DOMAIN=buzz.example.com
+
+# Comma-separated origins allowed to make cross-origin HTTP requests (e.g. the
+# desktop/mobile client's community-connect flow calling GET /api/join-policy).
+# IMPORTANT: this must match the *client's* origin, not this relay's own
+# BUZZ_DOMAIN. Setting it to your relay's own domain — the intuitive-looking
+# default below — makes the browser reject the response with a generic
+# "Load failed" error even though the relay itself answers 200, because the
+# client's Origin header (typically `tauri://localhost` for the production
+# desktop app, or `http://localhost:<port>` for a dev build) never matches.
+# Leave empty for permissive CORS (all origins), which the relay treats as
+# "dev mode" and is safe once BUZZ_REQUIRE_AUTH_TOKEN / BUZZ_REQUIRE_RELAY_MEMBERSHIP
+# are already gating real data access.
 BUZZ_CORS_ORIGINS=https://buzz.example.com
 
 # Production defaults. Closed relay mode requires RELAY_OWNER_PUBKEY and a stable relay key.
diff --git a/deploy/compose/README.md b/deploy/compose/README.md
index 0de524fb5b..61b511d1ab 100644
--- a/deploy/compose/README.md
+++ b/deploy/compose/README.md
@@ -38,6 +38,12 @@ keypair.
   migrations.
 - The stack uses Postgres, Redis, MinIO, and a git data volume because
   those are real Buzz dependencies today. Minimal mode can simplify this later.
+- `BUZZ_CORS_ORIGINS` must match the *client's* origin, not `BUZZ_DOMAIN`. If
+  the desktop/mobile app's "join a community" flow fails with a generic
+  browser "Load failed" while `curl`ing the relay directly works fine, this is
+  almost always why — see the comment above `BUZZ_CORS_ORIGINS` in
+  `.env.example`. Leaving it empty (permissive CORS) is the simplest fix for
+  a single-operator or closed-relay deployment.
 
 Run `./run.sh backup-hint` for the backup checklist.