From 2322e198bfe42910ce3f81ffd9df0558d4dcf958 Mon Sep 17 00:00:00 2001
From: "Sana (OpenClaw)" <sana@openclaw.local>
Date: Sun, 8 Feb 2026 15:31:34 +0000
Subject: [PATCH] docs: document NEXT_PUBLIC_API_URL requirement

---
 .env.example          |  4 +++-
 README.md             | 13 ++++++++++++-
 frontend/.env.example |  2 ++
 3 files changed, 17 insertions(+), 2 deletions(-)

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 4498e820..6b9f0e6a 100644
--- a/README.md
+++ b/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`).
diff --git a/frontend/.env.example b/frontend/.env.example
index cd49a500..05c37014 100644
--- a/frontend/.env.example
+++ b/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