diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml
index 7f975f6..5e15291 100644
--- a/.github/workflows/android.yml
+++ b/.github/workflows/android.yml
@@ -63,10 +63,22 @@ jobs:
           if [ -f apps/mobile/.env.production ]; then
             set -a; . apps/mobile/.env.production; set +a
           fi
+          if [ -z "$VITE_API_BASE" ]; then
+            echo "::error::VITE_API_BASE is unset. Set it as a repo variable in" \
+                 "Settings -> Secrets and variables -> Actions -> Variables, or" \
+                 "edit apps/mobile/.env.production. Without it the APK has no" \
+                 "API URL and login will fail with a 404 on /auth/start_login."
+            exit 1
+          fi
           echo "VITE_API_BASE=$VITE_API_BASE" >> "$GITHUB_ENV"
           echo "VITE_GATEWAY_URL=$VITE_GATEWAY_URL" >> "$GITHUB_ENV"
           echo "TEMPEST_WEB_URL=$TEMPEST_WEB_URL" >> "$GITHUB_ENV"
-          echo "Building web bundle against API=$VITE_API_BASE GW=$VITE_GATEWAY_URL WEB=$TEMPEST_WEB_URL"
+          if [ -z "$TEMPEST_WEB_URL" ]; then
+            echo "::warning::TEMPEST_WEB_URL is unset. The APK will fall back to" \
+                 "the bundled web/dist; passkey login will be unavailable until" \
+                 "you point it at your live tempest-web origin."
+          fi
+          echo "Building APK with API=$VITE_API_BASE GW=$VITE_GATEWAY_URL WEB=$TEMPEST_WEB_URL"
 
       - name: Build web bundle
         env:
diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index 4c95f54..9e861b3 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -43,10 +43,20 @@ jobs:
           if [ -f apps/mobile/.env.production ]; then
             set -a; . apps/mobile/.env.production; set +a
           fi
+          if [ -z "$VITE_API_BASE" ]; then
+            echo "::error::VITE_API_BASE is unset. Set it as a repo variable" \
+                 "or in apps/mobile/.env.production."
+            exit 1
+          fi
           echo "VITE_API_BASE=$VITE_API_BASE" >> "$GITHUB_ENV"
           echo "VITE_GATEWAY_URL=$VITE_GATEWAY_URL" >> "$GITHUB_ENV"
           echo "TEMPEST_WEB_URL=$TEMPEST_WEB_URL" >> "$GITHUB_ENV"
-          echo "Building web bundle against API=$VITE_API_BASE GW=$VITE_GATEWAY_URL WEB=$TEMPEST_WEB_URL"
+          if [ -z "$TEMPEST_WEB_URL" ]; then
+            echo "::warning::TEMPEST_WEB_URL is unset. The IPA will fall back" \
+                 "to the bundled web/dist; passkey login will be unavailable" \
+                 "until you point it at your live tempest-web origin."
+          fi
+          echo "Building IPA with API=$VITE_API_BASE GW=$VITE_GATEWAY_URL WEB=$TEMPEST_WEB_URL"
 
       - name: Build web bundle
         env:
diff --git a/apps/mobile/.env.production b/apps/mobile/.env.production
index 80a5463..32c0905 100644
--- a/apps/mobile/.env.production
+++ b/apps/mobile/.env.production
@@ -1,18 +1,17 @@
-# Default API + Gateway URLs the mobile build embeds when the workflow has
-# no repo vars set. Override per-deploy by setting VITE_API_BASE /
-# VITE_GATEWAY_URL as repository variables in GitHub
+# Default URLs the mobile build embeds. Override per-deploy by setting them
+# as repository variables in GitHub
 # (Settings -> Secrets and variables -> Actions -> Variables), or by
 # editing this file before tagging a release.
 #
-# Example (replace with the URLs printed by `railway up`):
-#   VITE_API_BASE=https://tempest-api-production-2899.up.railway.app
-#   VITE_GATEWAY_URL=wss://tempest-gateway-production-1213ce.up.railway.app/gateway
-#
-# TEMPEST_WEB_URL controls whether Capacitor loads the live deployment as
-# the initial page (recommended; passkeys / WebAuthn work over the real
-# HTTPS origin) or falls back to the bundled web/dist (faster first paint,
-# but passkeys refuse to run on https://localhost).
+# VITE_API_BASE     - absolute URL of the deployed tempest-api (REST).
+# VITE_GATEWAY_URL  - absolute wss:// URL of the deployed tempest-gateway,
+#                     including the /gateway path.
+# TEMPEST_WEB_URL   - absolute URL of the deployed tempest-web. When set,
+#                     the Capacitor app loads this URL as its initial page
+#                     so WebAuthn / passkeys see a real HTTPS origin and
+#                     work. When unset, the app uses the bundled web/dist
+#                     and passkey login is unavailable.
 
 VITE_API_BASE=https://tempest-api-production-2899.up.railway.app
-VITE_GATEWAY_URL=wss://tempest-gateway-production-1213ce.up.railway.app/gateway
-TEMPEST_WEB_URL=https://tempest-web-production-1213ce.up.railway.app
+VITE_GATEWAY_URL=wss://tempest-gateway-production.up.railway.app/gateway
+TEMPEST_WEB_URL=https://web-production-1213ce.up.railway.app
diff --git a/docs/MOBILE.md b/docs/MOBILE.md
index c0ff667..ab031f3 100644
--- a/docs/MOBILE.md
+++ b/docs/MOBILE.md
@@ -66,6 +66,23 @@ The CI workflow patches the generated Xcode project to keep iPad
 support universal even if the Capacitor template ever regresses, and
 forces `UIRequiresFullScreen=NO` so iPad multitasking works.
 
+## Configuring URLs
+
+Three values control where the mobile build talks to:
+
+| Var                | Purpose                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------- |
+| `VITE_API_BASE`    | Absolute URL of the deployed `tempest-api`. Required.                                    |
+| `VITE_GATEWAY_URL` | Absolute `wss://` URL of the deployed `tempest-gateway`, including `/gateway` path.      |
+| `TEMPEST_WEB_URL`  | Absolute URL of the deployed `tempest-web`. Optional. Set it to enable passkey login.    |
+
+Set them either as repo variables in GitHub
+(`Settings` → `Secrets and variables` → `Actions` → `Variables`) or by
+editing `apps/mobile/.env.production`. The CI workflow refuses to build
+without `VITE_API_BASE` and emits a warning if `TEMPEST_WEB_URL` is
+unset (the APK still builds, but passkey login is unavailable - see
+below).
+
 ## Passkeys / WebAuthn on mobile
 
 WebAuthn refuses to run on the synthetic `https://localhost` origin