docs: add canonical IA landing + first-pass core pages

docs/07-api-reference.md

@@ -0,0 +1,52 @@
+# API reference (first pass)
+
+This is a **map** of the Mission Control HTTP API surface. It’s intentionally light-weight for the first pass.
+
+## Base
+- Backend service: `backend/app/main.py`
+- API prefix: `/api/v1`
+
+## Auth
+
+### User/browser auth (Clerk)
+- Used for the human UI.
+- Frontend enables Clerk when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set.
+- Backend verifies JWTs when `CLERK_JWKS_URL` is configured.
+
+### Agent auth (X-Agent-Token)
+- Used by automation/agents.
+- Header: `X-Agent-Token: <token>`
+- Agent endpoints live under `/api/v1/agent/*`.
+
+## Endpoint groups (routers)
+Routers are registered in `backend/app/main.py`:
+- `auth_router`
+- `agent_router` (agent surface)
+- `agents_router`
+- `activity_router`
+- `gateway_router`, `gateways_router`
+- `metrics_router`
+- `organizations_router`
+- `souls_directory_router`
+- `board_groups_router`, `board_group_memory_router`
+- `boards_router`, `board_memory_router`, `board_onboarding_router`
+- `approvals_router`
+- `tasks_router`
+- `users_router`
+
+## Examples
+
+### Health
+```bash
+curl -s http://localhost:8000/healthz
+```
+
+### Agent call (example)
+```bash
+curl -s http://localhost:8000/api/v1/agent/boards \
+  -H "X-Agent-Token: $AGENT_TOKEN"
+```
+
+## Next
+- Add a per-router table of key paths once we standardize which endpoints are “public” vs “internal”.
+- If an OpenAPI schema exists/gets added, link it here.