docs: clarify Clerk is required (remove optional wording)

README.md

@@ -32,10 +32,13 @@ Operational deep dives:
 
 ## Authentication (Clerk)
 
-Clerk is **optional for local/self-host**.
+**Clerk is currently required**.
 
-- The frontend enables Clerk only when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set.
+You must configure Clerk keys for:
-- If you’re not configuring Clerk locally, keep Clerk env vars **unset/blank**.
+- the frontend (`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`)
+- the backend (`CLERK_SECRET_KEY`)
+
+See: [`docs/deployment/README.md`](./docs/deployment/README.md#clerk-auth-notes).
 
 ## Deployment modes
 
@@ -50,6 +53,9 @@ cp .env.example .env
 # NEXT_PUBLIC_API_URL must be reachable from the *browser* (host), not an internal Docker network name.
 # Missing/blank NEXT_PUBLIC_API_URL will break frontend API calls (e.g. Activity feed).
 
+# REQUIRED: Clerk config.
+# Provide real Clerk values via frontend/.env (recommended) and backend/.env.
+
 docker compose -f compose.yml --env-file .env up -d --build
 ```
 

docs/02-quickstart.md

@@ -11,4 +11,4 @@ After `docker compose up`:
 
 ## Common gotchas
 - `NEXT_PUBLIC_API_URL` must be reachable from your browser (host), not just from inside Docker.
-- If you are not configuring Clerk locally, ensure Clerk env vars are **unset/blank** so Clerk stays gated off.
+- Clerk auth is required; ensure Clerk keys are configured (see `docs/deployment/README.md`).

docs/06-configuration.md

@@ -88,8 +88,8 @@ This table is based on `backend/app/core/config.py`, `.env.example`, `backend/.e
 | Variable | Required? | Purpose | Default / example | Footguns |
 |---|---:|---|---|---|
 | `NEXT_PUBLIC_API_URL` | **yes** | Backend base URL used by the browser | `http://localhost:8000` | Must be browser-reachable |
-| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | optional | Enables Clerk in the frontend when set | (none) | Placeholder values can unintentionally enable Clerk |
+| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | **yes** | Enables Clerk in the frontend | (none) | Must be a real publishable key |
-| `CLERK_SECRET_KEY` | depends | Used for Clerk flows (e.g. E2E) | (none) | Don’t commit; required for some testing setups |
+| `CLERK_SECRET_KEY` | **yes** | Clerk secret key used by the frontend (server-side) and E2E | (none) | Do not commit; required for Clerk-enabled operation |
 | `NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL` | optional | Post-login redirect | `/boards` | — |
 | `NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL` | optional | Post-signup redirect | `/boards` | — |
 | `NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL` | optional | Fallback redirect | `/boards` | — |

docs/07-api-reference.md

@@ -12,7 +12,7 @@ It is derived from `backend/app/main.py` (router registration) and `backend/app/
 - API prefix: `/api/v1/*` (see `backend/app/main.py`)
 
 ## Auth model (recap)
-- **Clerk (user auth)**: used by the human web UI; frontend enables Clerk when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set; backend verifies JWTs when `CLERK_JWKS_URL` is configured (see `backend/app/core/auth.py`).
+- **Clerk (user auth)**: used by the human web UI; frontend enables Clerk when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set; backend verifies requests using `CLERK_SECRET_KEY` via the Clerk SDK (see `backend/app/core/auth.py`).
 - **X-Agent-Token (agent auth)**: used by automation/agents; send header `X-Agent-Token: <token>` to `/api/v1/agent/*` endpoints (see `backend/app/core/agent_auth.py`).
 
 ## Route groups (modules)

docs/10-troubleshooting.md

@@ -13,8 +13,8 @@ This is the “quick triage” page. For detailed playbooks and diagnostics, use
 - Check backend `/healthz`.
 
 ### Frontend keeps redirecting / Clerk errors
-- If you’re running locally without Clerk, keep `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` unset/blank.
+- Verify your Clerk keys are set correctly in the frontend environment.
-- See: [repo README Clerk note](../README.md#note-on-auth-clerk).
+- See: `docs/deployment/README.md` (Clerk auth notes).
 
 ### Backend returns 5xx
 - Check DB connectivity (`DATABASE_URL`) and migrations.

docs/architecture/README.md

@@ -29,9 +29,11 @@ flowchart LR
 - Routes/pages: `frontend/src/app/*` (Next.js App Router)
 - API utilities: `frontend/src/lib/*` and `frontend/src/api/*`
 
-**Auth (Clerk, required for now)**
+**Auth (Clerk, required)**
-- The codebase includes gating so CI/local can run without secrets, but real deployments should configure Clerk.
+- Clerk is required for real deployments and currently required by backend config (see `backend/app/core/config.py`).
-- See `frontend/src/auth/clerkKey.ts`, `frontend/src/auth/clerk.tsx`, and `frontend/src/proxy.ts`.
+- Frontend uses Clerk when keys are configured; see `frontend/src/auth/clerkKey.ts` and `frontend/src/auth/clerk.tsx`.
+- Backend authenticates requests using the Clerk SDK and `CLERK_SECRET_KEY`; see `backend/app/core/auth.py`.
+
 
 ### Backend (FastAPI)
 - Location: `backend/`
@@ -62,11 +64,9 @@ Mission Control can call into an OpenClaw Gateway over WebSockets.
 2. Frontend calls backend endpoints under `/api/v1/*`.
 3. Backend reads/writes Postgres.
 
-### Auth (Clerk — required for now)
+### Auth (Clerk — required)
-- **Frontend** enables Clerk when a publishable key is present/valid.
+- **Frontend** uses Clerk when keys are configured (see `frontend/src/auth/*`).
-- **Backend** uses `fastapi-clerk-auth` when `CLERK_JWKS_URL` is configured.
+- **Backend** authenticates requests using the Clerk SDK and `CLERK_SECRET_KEY` (see `backend/app/core/auth.py`).
-  - See `backend/app/core/auth.py`.
-
 ### Agent access (X-Agent-Token)
 Automation/agents can use the “agent” API surface:
 - Endpoints under `/api/v1/agent/*` (router: `backend/app/api/agent.py`).

docs/deployment/README.md

@@ -15,7 +15,7 @@ When running Compose, you get:
   - Health check: `GET /healthz`
 - **Frontend UI** (Next.js) on `http://localhost:${FRONTEND_PORT:-3000}`
 
-Auth (Clerk) is **required** right now. You must configure Clerk keys for the frontend, and configure `CLERK_JWKS_URL` for the backend so protected API routes can verify JWTs.
+Auth (Clerk) is **required** right now. You must configure Clerk keys for the frontend and backend (`CLERK_SECRET_KEY`).
 
 ## Requirements
 
@@ -133,18 +133,24 @@ NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/boards
 NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/boards
 ```
 
-### Backend (JWT verification)
+### Backend (auth)
 
-The backend verifies Clerk JWTs using **`CLERK_JWKS_URL`**.
+The backend authenticates requests using the Clerk SDK and **`CLERK_SECRET_KEY`** (see `backend/app/core/auth.py`).
 
-- Compose loads `backend/.env.example` by default, where `CLERK_JWKS_URL` is empty.
+Create `backend/.env` (this file is **not** committed) with at least:
-- For a real deployment, provide a real value either by:
-  1) creating `backend/.env` and updating `compose.yml` to load it (preferred), **or**
-  2) adding `CLERK_JWKS_URL: ${CLERK_JWKS_URL}` under `backend.environment` and setting it in root `.env`.
 
-Related backend env vars (optional tuning):
+```env
-- `CLERK_VERIFY_IAT` (default: true)
+CLERK_SECRET_KEY=sk_test_your_real_key
-- `CLERK_LEEWAY` (default: 10.0)
+
+# Optional tuning
+CLERK_API_URL=https://api.clerk.com
+CLERK_VERIFY_IAT=true
+CLERK_LEEWAY=10.0
+```
+
+Then either:
+1) update `compose.yml` to load `backend/.env` (recommended), or
+2) pass the values via `services.backend.environment`.
 
 **Security:** treat `CLERK_SECRET_KEY` like a password. Do not commit it.