docs: document NEXT_PUBLIC_API_URL requirement

.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

README.md

@@ -34,6 +34,10 @@ 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.
+# 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 +116,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`).

frontend/.env.example

@@ -1,4 +1,6 @@
+# REQUIRED: base URL for frontend -> backend calls (must be set for Activity feed and other API calls)
 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