diff --git a/.env.example b/.env.example
index 03da5e7d..5dd671a2 100644
--- a/.env.example
+++ b/.env.example
@@ -19,5 +19,7 @@ CORS_ORIGINS=http://localhost:3000
 DB_AUTO_MIGRATE=true
 
 # --- frontend settings ---
-# Public URL used by the browser to reach the API
+# REQUIRED: Public URL used by the browser to reach the API.
+# If this is missing/blank, frontend API calls (e.g. Activity feed) will break.
+# Example (local dev / compose on your machine):
 NEXT_PUBLIC_API_URL=http://localhost:8000
diff --git a/README.md b/README.md
index ab40db53..c5b86ac2 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,11 @@ OpenClaw Mission Control is under active development. Expect breaking changes an
 ```bash
 cp .env.example .env
 
+# REQUIRED: ensure the browser can reach the backend API.
+# NEXT_PUBLIC_API_URL must be reachable from the *browser* (host), not an internal Docker network name.
+# If you change ports/hosts, update NEXT_PUBLIC_API_URL in .env accordingly.
+# (Missing/blank NEXT_PUBLIC_API_URL will break frontend API calls like Activity feed.)
+
 # IMPORTANT: if you are not configuring Clerk, disable it by ensuring
 # NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is NOT set.
 # (The default `frontend/.env.example` contains placeholders that you should delete/blank.)
@@ -112,15 +117,22 @@ Notes:
 ```bash
 cd frontend
 
-# Configure API URL (and optionally disable Clerk for local dev by removing/blanking Clerk env vars)
+# Configure API URL (REQUIRED) and optionally disable Clerk for local dev by removing/blanking Clerk env vars
 cp .env.example .env.local
 
+# If you run the backend locally on :8000, this should be:
+# NEXT_PUBLIC_API_URL=http://localhost:8000
+
 npm install
 npm run dev
 ```
 
 Open http://localhost:3000.
 
+### Cypress E2E (local)
+
+When running Cypress (`cd frontend && npm run e2e`), make sure `NEXT_PUBLIC_API_URL` is set (either in `frontend/.env.local` or your shell env). In CI we run the frontend on `http://localhost:3000`, so `NEXT_PUBLIC_API_URL` is set to `http://localhost:3000` for the E2E job.
+
 ## Key concepts / high-level architecture
 
 - **Mission Control backend** exposes a REST API at `/api/v1/*` and also hosts health endpoints (`/healthz`, `/readyz`).
@@ -151,6 +163,8 @@ make check
 
 ## Troubleshooting
 
+More: [`docs/troubleshooting/README.md`](./docs/troubleshooting/README.md)
+
 ### Frontend keeps redirecting / Clerk errors
 
 You likely have `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` set (even to a placeholder). To run without Clerk:
diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md
new file mode 100644
index 00000000..49baac8a
--- /dev/null
+++ b/docs/troubleshooting/README.md
@@ -0,0 +1,17 @@
+# Troubleshooting
+
+## Activity feed is blank / frontend API calls fail
+
+**Symptoms**
+- Activity feed shows no items.
+- The browser console/network tab shows failed requests to `/api/v1/*`.
+
+**Cause**
+- `NEXT_PUBLIC_API_URL` is missing/blank/incorrect. The frontend uses this variable to build API URLs.
+
+**Fix**
+- Local dev: set `NEXT_PUBLIC_API_URL=http://localhost:8000` in `frontend/.env.local`.
+- Docker Compose (self-host): set `NEXT_PUBLIC_API_URL=http://localhost:8000` in the root `.env` used by compose (or update it to match your actual backend host/port).
+
+Notes:
+- `NEXT_PUBLIC_API_URL` must be reachable from the browser. If you're using Docker Compose, don't set it to an internal service name like `http://backend:8000` unless the browser can resolve it.
diff --git a/frontend/.env.example b/frontend/.env.example
index cd49a500..9c4a3f7a 100644
--- a/frontend/.env.example
+++ b/frontend/.env.example
@@ -1,4 +1,7 @@
+# REQUIRED: base URL for frontend -> backend calls (must be set for Activity feed and other API calls).
+# Must be reachable from the browser (host).
 NEXT_PUBLIC_API_URL=http://localhost:8000
+
 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
 CLERK_SECRET_KEY=YOUR_SECRET_KEY
 NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL=/boards