diff --git a/frontend/README.md b/frontend/README.md
index e215bc4c..52ddef78 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,36 +1,164 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Mission Control Frontend (`frontend/`)
 
-## Getting Started
+This package is the **Next.js** web UI for OpenClaw Mission Control.
 
-First, run the development server:
+- Talks to the Mission Control **backend** over HTTP (typically `http://localhost:8000`).
+- Uses **React Query** for data fetching.
+- Can optionally enable **Clerk** authentication (disabled by default unless you provide a *real* Clerk publishable key).
+
+## Prerequisites
+
+- Node.js (recommend **18+**) and npm
+- Backend running locally (see `../backend/README.md` if present) **or** run the stack via Docker Compose from repo root.
+
+## Local development
+
+From `frontend/`:
 
 ```bash
+npm install
+
+# set env vars (see below)
+cp .env.example .env.local
+
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open http://localhost:3000.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+### LAN development
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+To bind Next dev server to all interfaces:
 
-## Learn More
+```bash
+npm run dev:lan
+```
 
-To learn more about Next.js, take a look at the following resources:
+## Environment variables
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+The frontend reads configuration from standard Next.js env files (`.env.local`, `.env`, etc.).
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+### Required
 
-## Deploy on Vercel
+#### `NEXT_PUBLIC_API_URL`
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+Base URL of the backend API.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+- Default for local dev: `http://localhost:8000`
+- Used by the generated API client and helpers (see `src/lib/api-base.ts` and `src/api/mutator.ts`).
+
+Example:
+
+```env
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
+
+### Optional: Clerk authentication
+
+Clerk is **optional**.
+
+The app only enables Clerk when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` looks like a real key.
+Implementation detail: we gate on a conservative regex (`pk_test_...` / `pk_live_...`) in `src/auth/clerkKey.ts`.
+
+#### Env vars
+
+- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
+  - If **unset/blank/placeholder**, Clerk is treated as **disabled**.
+- `CLERK_SECRET_KEY`
+  - Required only if you enable Clerk features that need server-side verification.
+- Redirect URLs (optional; used by Clerk UI flows):
+  - `NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL`
+  - `NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL`
+  - `NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL`
+  - `NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL`
+
+**Important:** `frontend/.env.example` contains placeholder values like `YOUR_PUBLISHABLE_KEY`.
+Those placeholders are *not* valid keys and are intentionally treated as “Clerk disabled”.
+
+## How the frontend talks to the backend
+
+### API base URL
+
+The client builds URLs using `NEXT_PUBLIC_API_URL` (normalized to remove trailing slashes).
+
+### Generated API client (Orval + React Query)
+
+We generate a typed client from the backend OpenAPI schema using **Orval**:
+
+- Config: `orval.config.ts`
+- Output: `src/api/generated/*`
+- Script: `npm run api:gen`
+
+By default, Orval reads:
+
+- `ORVAL_INPUT` (if set), otherwise
+- `http://127.0.0.1:8000/openapi.json`
+
+Example:
+
+```bash
+# from frontend/
+ORVAL_INPUT=http://localhost:8000/openapi.json npm run api:gen
+```
+
+### Auth header / Clerk token injection
+
+All Orval-generated requests go through the custom mutator (`src/api/mutator.ts`).
+It will:
+
+- set `Content-Type: application/json` when there is a body and you didn’t specify a content type
+- add `Authorization: Bearer <token>` automatically **if** Clerk is enabled and there is an active Clerk session in the browser
+- parse errors into an `ApiError` with status + parsed response body
+
+## Common commands
+
+From `frontend/`:
+
+```bash
+npm run dev        # start dev server
+npm run build      # production build
+npm run start      # run the built app
+npm run lint       # eslint
+npm run test       # vitest (with coverage)
+npm run test:watch # watch mode
+npm run api:gen    # regenerate typed API client via Orval
+```
+
+## Docker
+
+There is a `frontend/Dockerfile` used by the root `compose.yml`.
+
+If you’re working on self-hosting, prefer running compose from the repo root so the backend/db/redis are aligned with the documented ports/env.
+
+## Troubleshooting
+
+### `NEXT_PUBLIC_API_URL is not set`
+
+The API client throws if `NEXT_PUBLIC_API_URL` is missing.
+
+Fix:
+
+```bash
+cp .env.example .env.local
+# then edit .env.local if your backend URL differs
+```
+
+### Frontend loads, but API calls fail (CORS / network errors)
+
+- Confirm backend is up: http://localhost:8000/healthz
+- Confirm `NEXT_PUBLIC_API_URL` points to the correct host/port.
+- If accessing from another device (LAN), use a reachable backend URL (not `localhost`).
+
+### Clerk redirects / auth UI shows unexpectedly
+
+Clerk should be **off** unless you set a real `pk_test_...` or `pk_live_...` publishable key.
+
+- Remove/blank `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` in your `.env.local` to force Clerk off.
+
+### Dev server blocked by origin restrictions
+
+`next.config.ts` sets:
+
+- `allowedDevOrigins: ["192.168.1.101"]`
+
+If you’re developing from a different hostname/IP, you may need to update `allowedDevOrigins` (or use `npm run dev` on localhost).
\ No newline at end of file