docs: add missing context to overview/architecture/ops/troubleshooting

docs/05-architecture.md

@@ -7,18 +7,21 @@
 
 Mission Control is the **web UI + HTTP API** for operating OpenClaw. It’s where you manage boards, tasks, agents, approvals, and (optionally) gateway connections.
 
-> Auth note: **Clerk is required for now** (current product direction). The codebase includes gating so CI/local can run with placeholders, but real deployments should configure Clerk.
+> Auth note: **Clerk is required for production**. The codebase includes gating so CI/local can run without “real” keys, but real deployments should configure Clerk.
 
 ## Components
 
 - **Frontend**: Next.js app used by humans
   - Location: `frontend/`
   - Routes/pages: `frontend/src/app/*` (Next.js App Router)
+  - API client: generated + custom fetch (see `frontend/src/api/*`, `frontend/src/lib/api-base.ts`)
 - **Backend**: FastAPI service exposing REST endpoints
   - Location: `backend/`
-  - App wiring: `backend/app/main.py`
+  - Entrypoint: `backend/app/main.py`
   - API prefix: `/api/v1/*`
-- **Database**: Postgres (from `compose.yml`)
+- **Database**: Postgres (see `compose.yml`)
+- **Gateway integration (optional)**: backend may call into OpenClaw Gateways over WebSockets
+  - Client/protocol list: `backend/app/services/openclaw/gateway_rpc.py`
 
 ## Diagram (conceptual)
 
@@ -33,24 +36,58 @@ flowchart LR
   GW --> OC[OpenClaw runtime]
 ```
 
-## Key request/data flows
+## How requests flow
 
-### UI → API
-1. Browser loads the Next.js frontend.
-2. Frontend calls backend endpoints under `/api/v1/*`.
-3. Backend reads/writes Postgres.
+### 1) A human uses the UI
 
-### Auth (Clerk)
-- Frontend enables Clerk when a publishable key is present/valid.
-- Backend verifies Clerk JWTs using **`CLERK_JWKS_URL`**.
+1. Browser loads the Next.js frontend (`frontend/`).
+2. Frontend calls backend endpoints using `NEXT_PUBLIC_API_URL`.
+3. Backend routes under `/api/v1/*` (`backend/app/main.py`) and reads/writes Postgres.
 
-See also:
-- Frontend auth gating: `frontend/src/auth/*` (notably `frontend/src/auth/clerkKey.ts`).
-- Backend auth: `backend/app/core/auth.py`.
+Common UI-driven data shapes:
+- “boards/tasks” views → board/task CRUD + streams.
+- “activity feed” → activity/events endpoints.
 
-### Agent access (X-Agent-Token)
-Automation/agents can use the “agent API surface”:
-- Endpoints under `/api/v1/agent/*`.
-- Auth via `X-Agent-Token`.
+### 2) Authentication (Clerk)
 
-See: `backend/app/api/agent.py`, `backend/app/core/agent_auth.py`.
+- **Frontend**: Clerk is enabled only when a publishable key is present/valid.
+  - Gating/wrappers: `frontend/src/auth/clerkKey.ts`, `frontend/src/auth/clerk.tsx`.
+- **Frontend → backend**: API calls attach `Authorization: Bearer <token>` when available.
+  - Token injection: `frontend/src/api/mutator.ts` (uses `window.Clerk.session.getToken()`).
+- **Backend**: validates inbound auth and resolves a user context.
+  - Implementation: `backend/app/core/auth.py` (uses `clerk_backend_api` SDK with `CLERK_SECRET_KEY`).
+
+### 3) Agent automation surface (`/api/v1/agent/*`)
+
+Agents can call a dedicated API surface:
+
+- Router: `backend/app/api/agent.py` (prefix `/agent` → mounted under `/api/v1/agent/*`).
+- Authentication: `X-Agent-Token` header (or agent-only Authorization bearer parsing).
+  - Implementation: `backend/app/core/agent_auth.py`.
+
+Typical agent flows:
+- Heartbeat/presence updates
+- Task comment posting (evidence)
+- Board memory updates
+- Lead coordination actions (if board-lead agent)
+
+### 4) Streaming/feeds (server-sent events)
+
+Some endpoints support streaming via SSE (`text/event-stream`).
+Notes:
+- Uses `sse-starlette` in backend routes (e.g. task/activity/memory routers).
+
+### 5) Gateway integration (optional)
+
+Mission Control can coordinate with OpenClaw Gateways over WebSockets.
+
+- Protocol methods/events list: `backend/app/services/openclaw/gateway_rpc.py`.
+- Operator-facing protocol docs: `docs/openclaw_gateway_ws.md`.
+
+## Where to start reading code
+
+- Backend entrypoint + router wiring: `backend/app/main.py`
+- Auth dependencies + access enforcement: `backend/app/api/deps.py`
+- User auth: `backend/app/core/auth.py`
+- Agent auth: `backend/app/core/agent_auth.py`
+- Agent API surface: `backend/app/api/agent.py`