@flame0510/project-aether 1.1.15 → 1.3.0

package/docs/dev/API-REFERENCE.md

@@ -1,6 +1,6 @@
 # Rev4a API Reference
 
-> **Last updated:** 2026-07-19
+> **Last updated:** 2026-09-14
 
 All routes are under `/api/`. Authentication is required on every endpoint
 unless otherwise noted.
@@ -68,100 +68,134 @@ Delete the `rev4a_token` cookie.
 
 ---
 
-## Onboarding
+### `GET /api/auth/status`
+Whether a password has been configured, in the environment or in the `.env` the
+setup wizard writes. Used by the frontend to choose between the setup wizard and
+the login form.
 
-### `GET /api/onboarding/status`
-Returns per-step onboarding progress.
+**Auth:** none — it reveals only whether setup has happened, never the password
 
-**Auth:** browser cookie
+**Response:** `{ "configured": true }`
 
-**Response:**
-```json
-{
-  "complete": false,
-  "steps": { "welcome": true, "providers": false, "agents": false },
-  "completedAt": null
-}
-```
+---
 
-If no progress file exists, returns all steps as `false`.
+## Setup & wizard
 
-### `POST /api/onboarding/complete`
-Mark a step as completed, complete all steps, or reset the wizard.
+### `GET /api/wizard/status`
+Whether the first-run wizard has been completed.
 
-**Auth:** browser cookie
+**Auth:** browser cookie or bearer token
 
-**Body:**
-| Shape | Effect |
-|---|---|
-| `{ "step": "providers" }` | Mark a single step as done |
-| `{}` | Mark all steps as done (complete onboarding) |
-| `{ "reset": true }` | Reset all steps to `false` (restart wizard) |
+**Response:** `{ "done": true }`
 
-**Response:**
-```json
-{
-  "status": "ok",
-  "steps": { "welcome": true, "providers": true, "agents": false },
-  "complete": false
-}
-```
+### `POST /api/wizard/complete`
+Mark the wizard as completed.
+
+**Auth:** browser cookie or bearer token
+
+**Response:** `{ "done": true }`
+
+### `POST /api/wizard/reset`
+Reset the wizard so it runs again.
+
+**Auth:** browser cookie or bearer token
+
+**Response:** `{ "done": false }`
 
 ---
 
-## Gateway
+### `POST /api/setup/password`
+Set the dashboard password during first-run setup.
 
-The Gateway API reads the model catalogue from [`models.config.json`](../models.config.json)
-(tracked in the repository). Full documentation at [GATEWAY.md](GATEWAY.md) and
-[PROVIDERS.md](PROVIDERS.md).
+**Auth:** none, and only usable once — returns `409` if a password already exists
 
-### `GET /api/gateway`
-Returns live gateway status from all agent containers.
+**Body:** `{ "password": "..." }` — minimum 8 characters
 
-**Auth:** any auth method
+**Errors:** `400` invalid JSON, missing password, or shorter than 8 characters;
+`409` already configured; `500` the `.env` file could not be written.
 
-**Response:**
-```json
-{
-  "agents": {
-    "total": 1,
-    "list": [
-      {
-        "containerName": "openclaw-atlas",
-        "agentId": "atlas",
-        "agentName": "Atlas",
-        "defaultModel": "rev4a/deepseek/deepseek-v4-flash",
-        "configured": true
-      }
-    ]
-  }
-}
-```
+**Response:** `{ "status": "ok" }`
+
+### `POST /api/setup/restart`
+Restart the service so a freshly written `.env` takes effect.
+
+**Auth:** open before a password exists, then browser cookie or bearer token (`requireAuthIfConfigured`)
+
+**Errors:** `500` if the `.env` file is missing, or the restart could not be issued.
+
+### `GET /api/setup/agent-image`
+Whether the `openclaw-agent-base` image is present.
+
+**Auth:** open before a password exists, then browser cookie or bearer token (`requireAuthIfConfigured`)
+
+**Response:** `{ "exists": true, "imageId": "sha256:..." }`, or `{ "exists": false }`
+when the image is absent **or Docker is unreachable** — the two are not distinguished.
+
+### `POST /api/setup/agent-image`
+Pull or build the agent base image, streaming progress.
+
+**Auth:** open before a password exists, then browser cookie or bearer token (`requireAuthIfConfigured`)
+
+**Errors:** `409` if a download is already running.
+
+---
+
+## Gateway
+
+The Gateway API reads the model catalogue from [`models.config.json`](../../models.config.json)
+(tracked in the repository). Full documentation at [GATEWAY.md](GATEWAY.md) and
+[PROVIDERS.md](PROVIDERS.md).
 
 ### `PUT /api/gateway/provider`
-Trigger a full provider model sync to all agent containers.
+Enable or disable a single model in the catalogue, then sync every agent.
 
-**Auth:** any auth method
+**Auth:** browser cookie or bearer token
 
-**Body:** none (reads current provider state from `models.config.json` and `data/provider-keys.json`)
+**Body:** `{ "modelId": "deepseek/deepseek-flash", "enabled": true }` — both
+required. Missing either returns `400`; an unknown `modelId` returns `404`.
+If Docker cannot be reached the toggle is refused with `503` and nothing is saved,
+so a whole-fleet outage never leaves the checkboxes out of step with the agents.
 
-**Response:**
+**Response:** `status` is the toggle, which is saved before the sync runs. `sync`
+reports separately whether the agents received it.
 ```json
 {
   "status": "ok",
-  "activeModels": 2,
-  "results": ["Active models: 2 across 1 agent(s)"]
+  "modelId": "deepseek/deepseek-flash",
+  "enabled": true,
+  "provider": "deepseek",
+  "sync": {
+    "ok": true,
+    "activeModels": 3,
+    "total": 2,
+    "synced": ["agent_2a3c3a07", "agent_9253eee3"],
+    "stopped": [],
+    "failed": [],
+    "summary": "Synced 2 of 2 agent(s)."
+  }
 }
 ```
 
+`sync.ok` is true only when every agent container received the catalogue; zero
+agents counts as ok. "Every" includes agents that are not running (stopped, paused,
+created): they are written through `docker cp`, listed in `stopped` as well as
+`synced`, and apply the change when started or resumed. A container whose config
+cannot be read is listed in `failed` and left untouched — the sync never writes a
+config it did not read. When Docker cannot be reached, `total` is `0`, `dockerError`
+carries the cause and `ok` is false. For this toggle that case is refused up front
+with `503`, so it appears here only if Docker drops between the check and the sync;
+on a provider key save (`POST`) it is reported, not refused. `configError` is set,
+and nothing is attempted, when the gateway key is missing or `models.config.json`
+could not be read.
+
 **Side effects:**
 - Writes `models.providers.rev4a` to each agent container's `openclaw.json`
 - Cleans up stale `models.json` and `auth-profiles.json` inside containers
-- **Does NOT touch `agents.defaults.model` or `agents.list[].model`** — model references are managed per-container via the Agents Tab (`PUT /api/gateway/agent`)
+- **Does NOT touch `agents.defaults.model` or `agents.list[].model`** — model references are managed per-container from the agent detail panel (`PUT /api/gateway/agent`)
 - Does NOT restart the gateway (config is written live to the file)
 
 ### `PUT /api/gateway/agent`
-Update model config for a single agent container.
+Update the primary model and fallbacks of a single agent container.
 
 **Auth:** any auth method
 
@@ -169,28 +203,38 @@ Update model config for a single agent container.
 ```json
 {
   "containerName": "openclaw-atlas",
-  "model": "deepseek/deepseek-v4-flash",
-  "fallbacks": []
+  "model": "deepseek/deepseek-flash",
+  "fallbacks": ["deepseek/deepseek-v4-pro"]
 }
 ```
-If `fallbacks` is omitted or empty, no fallback models are set.
+`fallbacks` omitted and `fallbacks: []` are different requests. Omitted leaves the
+container's existing fallbacks untouched; `[]` clears them.
 
-**Response:**
+`containerName` is used verbatim as the `docker exec` target, not resolved from the
+`AGENT_ID` label. Every container's name currently equals its label, so an agent id
+works.
+
+**Response:** reports what was written, with the `rev4a/` prefix applied.
 ```json
 {
   "status": "ok",
   "agent": "openclaw-atlas",
   "model": {
-    "primary": "rev4a/deepseek/deepseek-v4-flash"
+    "primary": "rev4a/deepseek/deepseek-flash",
+    "fallbacks": ["rev4a/deepseek/deepseek-v4-pro"]
   },
   "verify": { "ok": true, "bytes": 2058 }
 }
 ```
 
 **Behaviour:**
-- Writes `agents.defaults.model.primary` and `agents.list[0].model.primary` with format `rev4a/<provider>/<model>`
-- No restart — writes are live via `docker exec node -e`
-- Does NOT set fallbacks unless explicitly provided
+- Writes `agents.defaults.model`, and the entry in `agents.list` whose `id` is
+  `main` (skipped if there is none), both as `{ primary, fallbacks }`. The primary is
+  removed from its own fallback list.
+- Rewrites the whole `openclaw.json` with `docker exec … cat >`. No gateway restart:
+  OpenClaw hot-applies the change.
+- Does not check the model against the catalogue. The proxy does that when the model
+  is used, so a model saved here while disabled is refused at request time.
 
 ### `GET /api/gateway/provider`
 Returns current provider configuration state.
@@ -213,7 +257,7 @@ Returns current provider configuration state.
       "baseUrl": "https://api.deepseek.com",
       "docsUrl": "https://platform.deepseek.com/api_keys",
       "models": [
-        { "id": "deepseek/deepseek-v4-flash", "name": "DeepSeek V4 Flash", "enabled": true },
+        { "id": "deepseek/deepseek-flash", "name": "DeepSeek Flash", "enabled": true },
         { "id": "deepseek/deepseek-v4-pro", "name": "DeepSeek V4 Pro", "enabled": true }
       ]
     }
@@ -223,7 +267,8 @@ Returns current provider configuration state.
 
 ### `GET /api/provider/v1/models`
 
-Rev4a Provider Gateway — returns available models filtered by auth token.
+Rev4a Provider Gateway — returns the models this deployment offers (enabled after
+overrides, provider has a key). A missing or wrong token gets an empty list, not a 401.
 
 **Auth:** Bearer token (must match `rev4a` key in `data/provider-keys.json`)
 
@@ -233,7 +278,7 @@ Rev4a Provider Gateway — returns available models filtered by auth token.
   "object": "list",
   "total": 9,
   "data": [
-    { "id": "deepseek/deepseek-v4-flash", "object": "model", "created": 1700000000, "owned_by": "deepseek", "permission": [], "root": "deepseek/deepseek-v4-flash" }
+    { "id": "deepseek/deepseek-flash", "object": "model", "created": 1700000000, "owned_by": "deepseek", "permission": [], "root": "deepseek/deepseek-flash" }
   ]
 }
 ```
@@ -245,6 +290,10 @@ Rev4a Provider Gateway — returns available models filtered by auth token.
 
 ### `POST /api/provider/v1/chat/completions`
 
+A model the deployment does not offer is refused with `400` before anything reaches
+upstream. Routing fields that would let the upstream choose another model — `models`,
+`route`, `preset` — are removed from the body before forwarding.
+
 Rev4a Provider Gateway — proxy chat completions to the correct upstream.
 
 **Auth:** Bearer token (must match `rev4a` key in `data/provider-keys.json`)
@@ -252,7 +301,7 @@ Rev4a Provider Gateway — proxy chat completions to the correct upstream.
 **Body:**
 ```json
 {
-  "model": "rev4a/deepseek-v4-flash",
+  "model": "rev4a/deepseek-flash",
   "messages": [{"role": "user", "content": "Hello"}]
 }
 ```
@@ -264,6 +313,79 @@ Rev4a Provider Gateway — proxy chat completions to the correct upstream.
 
 ---
 
+### `GET /api/models`
+Models eligible to be used: the catalogue filtered down to models that are enabled
+(after overrides) and whose provider has a key configured, grouped by provider. Feeds the model pickers in the agent's
+Model panel.
+
+**Auth:** browser cookie or bearer token
+
+**Response:**
+```json
+[
+  {
+    "provider": "DeepSeek",
+    "emoji": "🧠",
+    "models": [
+      {
+        "id": "deepseek/deepseek-flash",
+        "label": "DeepSeek Flash (V4.1)",
+        "input": 0.3,
+        "output": 1.2,
+        "deprecated": false
+      }
+    ]
+  }
+]
+```
+
+`input` and `output` are USD per 1M tokens, `null` when unpriced. `deprecated`
+marks a name upstream has retired; it stays selectable and the pickers tag it.
+See [GATEWAY.md](GATEWAY.md) for the deprecation lifecycle.
+
+### `GET /api/gateway/provider/balance`
+Remaining credit for one provider.
+
+**Auth:** browser cookie or bearer token
+
+**Query params:** `provider` — one of `deepseek`, `openrouter`, `glm`.
+
+**Errors:** `502` when the provider's API cannot be reached or rejects the call.
+
+### `POST /api/gateway/provider/oauth`
+Run the OAuth device flow for a provider that supports it.
+
+**Auth:** browser cookie or bearer token
+
+**Body:** `{ "provider": "..." }`
+
+**Errors:** `400` for an unknown provider; the response body carries `available`
+with the providers that do support OAuth.
+
+### `POST /api/aliases/add`
+Add a model alias.
+
+**Auth:** browser cookie or bearer token
+
+**Body:** `{ "alias": "fast", "model": "deepseek/deepseek-chat" }`
+
+**Response:** `{ "ok": true, "output": "..." }` — `output` is the CLI's stdout.
+
+**Errors:** `400` if `alias` or `model` is missing.
+
+### `POST /api/aliases/remove`
+Remove a model alias.
+
+**Auth:** browser cookie or bearer token
+
+**Body:** `{ "alias": "fast" }`
+
+**Response:** `{ "ok": true, "output": "..." }`
+
+**Errors:** `400` if `alias` is missing.
+
+---
+
 ## Config
 
 ### `PUT /api/config/env`
@@ -344,6 +466,17 @@ Returns a single session with its events and child sessions.
 
 ---
 
+### `GET /api/sessions/[id]`
+One session with its events and any child sessions.
+
+**Auth:** browser cookie or bearer token
+
+**Response:** `{ "session": {…}, "events": [...], "children": [...] }`
+
+**Errors:** `404` if the session does not exist.
+
+---
+
 ## Stats & Costs
 
 ### `GET /api/stats`
@@ -553,6 +686,7 @@ List running agent containers (Docker containers with `AGENT_ID` label) with ful
     "controlPort": "3033"
   }
 ]
+```
 
 **Notes:**
 - The URL is always `http://<host-ip>:<port>#token=...` (every agent gets a host port mapping)
@@ -562,6 +696,77 @@ List running agent containers (Docker containers with `AGENT_ID` label) with ful
 
 ---
 
+### `GET /api/agents/models-summary`
+One row per agent container, running or not: the model it runs and whether that
+model is still in good standing. Feeds the model chip on the agent cards. Running
+agents are read with `docker exec`, others with `docker cp`. If Docker cannot be
+reached the route answers `503` with an `error`, not an empty list.
+
+**Auth:** any auth method
+
+**Response:**
+```json
+{
+  "agents": [
+    {
+      "agentId": "atlas",
+      "containerName": "openclaw-atlas",
+      "primary": "rev4a/deepseek/deepseek-flash",
+      "fallbackCount": 0,
+      "firstFallback": null,
+      "health": "ok"
+    }
+  ]
+}
+```
+
+`health`, ordered by the remedy each needs:
+
+| value | meaning | remedy |
+|---|---|---|
+| `missing` | the primary is not in the catalogue at all | pick another model |
+| `disabled` | in the catalogue but not offered — unchecked, or its provider has no key; the proxy refuses it | pick another model |
+| `out-of-sync` | offered by the gateway, absent from this container's synced copy | Sync All Agents |
+| `deprecated` | works, on a name upstream has retired | switch when convenient |
+| `ok` | usable | — |
+| `unset` | no primary configured | — |
+| `unknown` | the container did not answer | — |
+
+### `GET /api/agents/[id]/model`
+The model configuration of one agent, read from that container alone rather than
+by walking the fleet. Writes still go to `PUT /api/gateway/agent`.
+
+**Auth:** any auth method
+
+**Response:**
+```json
+{
+  "agentId": "atlas",
+  "reachable": true,
+  "primary": "rev4a/deepseek/deepseek-flash",
+  "fallbacks": [],
+  "resolvable": true,
+  "catalogueSize": 41,
+  "primaryStatus": "offered"
+}
+```
+
+`resolvable` is tri-state. `false` means the primary is absent from the catalogue
+synced into that container, usually because the model was disabled on the Gateway
+page while this agent still pointed at it. `true` means it is present. `null` means
+the question does not apply: either the container did not answer, or no primary is
+set.
+
+When `reachable` is `false` the container did not answer, `primary` and `fallbacks`
+come back empty rather than read, and **`catalogueSize` is omitted entirely** — it
+is present only on the reachable branch.
+
+`primaryStatus`, also reachable branch only, says why the primary would fail
+regardless of this container: `offered`, `disabled` (unchecked, or its provider has
+no key) or `missing` (no longer in the catalogue). `null` when no primary is set.
+`resolvable` answers a different question — whether *this container's* synced copy
+has it — so `offered` with `resolvable: false` means the container is out of sync.
+
 ### `POST /api/agents/create`
 Create a new agent container from a template.
 
@@ -573,7 +778,7 @@ Create a new agent container from a template.
   "name": "my-agent",
   "template": "prometheus",
   "portRange": "3700-3709",
-  "model": "deepseek/deepseek-v4-flash",
+  "model": "deepseek/deepseek-flash",
   "fallbacks": []
 }
 ```
@@ -583,7 +788,7 @@ Create a new agent container from a template.
 | `name` | yes | Container name, also becomes `AGENT_ID` and subdomain |
 | `template` | yes | Template name (directory in `agent-templates/`) |
 | `portRange` | no | Optional port range (e.g. `3700-3709`) or single port (e.g. `3700`). Default: auto-assigned 10-port block |
-| `model` | no | Primary model ID from `models.config.json` |
+| `model` | no | Primary model id. Must be offered by this deployment (in the catalogue, enabled, provider has a key), in any form the proxy accepts; otherwise `400`. Defaults to `rev4a/deepseek/deepseek-flash`, validated the same way |
 | `fallbacks` | no | Array of fallback model IDs |
 
 **Every agent is created with a host port mapping:**
@@ -610,11 +815,16 @@ Create a new agent container from a template.
 
 **Post-creation pipeline:**
 1. OpenClaw gateway starts with `--allow-unconfigured`, generating its own default config
-2. The route waits for the gateway to be fully up (health check poll, up to 60 s)
-3. Once ready, writes `gateway.controlUi.allowedOrigins` + `agents.defaults.model.primary` + fallbacks
-4. Writes `models.providers.rev4a` + extraDirs + update config → single `openclaw.json` write → single `gateway restart`
+2. The route waits for the gateway to finish starting (`waitForGatewayReady`, up to 60 s)
+3. Once ready, rewrites `openclaw.json` in one write — `gateway.controlUi`,
+   `agents.defaults.model` (primary and fallbacks, always as `rev4a/<provider>/<model>`)
+   and `update` — then runs `openclaw gateway restart`
+4. Applies the runtime config (hooks, shared skills) and writes `models.providers.rev4a`
+   with `openclaw config patch --stdin`. No restart for this step: `gateway.reload`
+   defaults to `hybrid`, which hot-applies changes under `agents`, `models` and
+   `routing`. If the catalogue cannot be read the provider patch is skipped and logged
 
-> **Note:** The entrypoint no longer generates `openclaw.json`. All post-creation config is written by the create route after gateway readiness, eliminating the race condition where the entrypoint would overwrite synced provider config.
+Failures in steps 3 and 4 do not fail the request.
 
 **Side effects:**
 - Template files (`AGENTS.md`, `SOUL.md`, etc.) are copied into the container workspace via `docker cp`
@@ -762,6 +972,21 @@ aligning the volume's state/config to the new binary.
 
 ---
 
+### `POST /api/agents/[id]/lifecycle`
+Start, stop or restart an agent container.
+
+**Auth:** browser cookie or bearer token
+
+**Body:** `{ "action": "start" | "stop" | "restart" }`
+
+Redundant actions are no-ops: starting a running container, or stopping a stopped
+one, succeeds without touching it.
+
+**Errors:** `400` for a malformed body, an unknown action, or an invalid agent id;
+`404` when no container carries that `AGENT_ID`.
+
+---
+
 ## Channels
 
 Channel APIs read/write agent channel configuration (Telegram) directly inside agent containers via `docker exec`. All endpoints require the agent container to be running.
@@ -935,7 +1160,7 @@ Useful for inspecting the container config without SSH or terminal.
   "name": "my-agent",
   "config": {
     "gateway": { "controlUi": { "allowedOrigins": ["..."], "dangerouslyDisableDeviceAuth": true } },
-    "agents": { "defaults": { "model": { "primary": "rev4a/deepseek/deepseek-v4-flash", "fallbacks": [] } } },
+    "agents": { "defaults": { "model": { "primary": "rev4a/deepseek/deepseek-flash", "fallbacks": [] } } },
     "models": { "providers": { "rev4a": { "baseUrl": "...", "apiKey": "***", "models": [...] } } }
   }
 }
@@ -987,7 +1212,10 @@ Update the shared agents gateway token and push it to all running agent containe
 ### `GET /api/agents/image-status`
 Check the status of the `openclaw-agent-base` Docker image.
 
-**Auth:** public (no auth required)
+**Auth:** browser cookie or bearer token
+
+The ghcr.io digest lookup is cached for 10 minutes and de-duplicated while in
+flight, so polling this endpoint does not re-query the registry every time.
 
 **Response:**
 ```json
@@ -1011,7 +1239,7 @@ Starts pulling or building the `openclaw-agent-base:latest` image. Returns 202
 Accepted immediately — the operation runs in the background and writes logs.
 The frontend polls `GET /api/agents/image-status` for progress updates.
 
-**Auth:** public (no auth required)
+**Auth:** browser cookie or bearer token
 
 **Response (202):**
 ```json
@@ -1023,17 +1251,7 @@ The frontend polls `GET /api/agents/image-status` for progress updates.
 { "error": "A download is already in progress" }
 ```
 
-### `DELETE /api/agents/abort-download`
-Kills an in-progress docker pull/build.
-
-**Auth:** public (no auth required)
-
-**Response:**
-```json
-{ "aborted": true }
-```
-
-Image state is managed in `lib/buildAgentImage.ts`:
+Image state is managed in `lib/buildAgentImage.ts` (library functions, not HTTP routes):
 - `downloadAgentImage(opts)` — attempts `docker pull` from registry first, then falls back to `docker build`
   all stdout/stderr to a log file, supports optional `onEvent` callback and `AbortSignal`
 - `abortDownload()` — sends SIGKILL to the child process, releases the download lock
@@ -1274,7 +1492,7 @@ Run history for a specific cron job. Queries the container's gateway via `opencl
       "error": "Channel is required ...",
       "runAtMs": 1784820025581,
       "durationMs": 11046,
-      "model": "deepseek/deepseek-v4-flash",
+      "model": "deepseek/deepseek-flash",
       "usage": { "input_tokens": 15872, "output_tokens": 597 }
     }
   ]
@@ -1361,93 +1579,23 @@ Write content to a workspace file.
 
 ---
 
-## Vault
-
-Full key management documentation at [PROVIDERS.md](PROVIDERS.md).
-
-### `GET /api/vault`
-List all stored credentials (keys masked).
-
-**Auth:** browser cookie
-
-**Response:**
-```json
-{
-  "providers": {
-    "deepseek": { "keyStatus": "present", "scoped": ["atlas"] }
-  },
-  "services": {
-    "github": { "tokenStatus": "present", "user": "Flame0510", "scoped": ["argus", "atlas"] }
-  }
-}
-```
-
-### `GET /api/vault/provider/key`
-Return the full API key for a provider.
-
-**Auth:** browser cookie
-
-**Query params:** `provider` (required), `agent` (optional)
-
-**Response (200):**
-```json
-{
-  "provider": "deepseek",
-  "apiKey": "sk-...full-key...",
-  "masked": "sk-...be03",
-  "source": "local"
-}
-```
-
-**Error:** `400` if `provider` missing; `404` if key not found.
-
-See [PROVIDERS.md](PROVIDERS.md#get-apivaultproviderkey) for full detail.
-
-### `POST /api/vault/provider`
-Add or update a provider API key.
-
-**Auth:** browser cookie
-
-**Body:** `{ "provider": "deepseek", "apiKey": "sk-...", "baseUrl": "https://api.deepseek.com" }`
-
-**Response:** `{ "status": "ok", "provider": "deepseek", "masked": "sk-...be03", "updatedAt": 1749200000000 }`
-
-### `DELETE /api/vault/provider`
-Remove a provider and all its keys.
-
-**Auth:** browser cookie
-
-**Body:** `{ "provider": "deepseek" }`
-
-**Response:** `{ "status": "removed" }`
-
-### `PUT /api/vault/service`
-Add or update a service token.
-
-**Auth:** browser cookie
-
-**Body:** `{ "id": "github", "token": "***", "user": "Flame0510", "scopes": ["atlas"] }`
-
-**Response:** `{ "ok": true }`
-
-### `DELETE /api/vault/service`
-Remove a service.
-
-**Auth:** browser cookie
+## Provider keys and credentials
 
-**Body:** `{ "id": "github" }`
+Provider API keys are read with `GET /api/gateway/provider` and set with
+`POST /api/gateway/provider` — documented in `docs/dev/PROVIDERS.md`, which is the
+only file carrying that endpoint's request bodies. `PUT` toggles a model, not a
+key. The keys are stored in `data/provider-keys.json`.
+Third-party service credentials are managed under `/api/credentials`
+(documented below) and stored in `credentials.db`.
 
-**Response:** `{ "ok": true }`
-
-### `PUT /api/vault/permissions`
-Update agent permissions for a credential.
+There is no `/api/vault` route, and no per-credential agent scoping: any stored
+credential can be synced to any container.
 
-**Body:** `{ "type": "provider" | "service", "id": "deepseek", "scopes": ["atlas", "argus"] }`
-
-**Response:** `{ "ok": true }`
+Full key management documentation at [PROVIDERS.md](PROVIDERS.md).
 
 ---
 
+
 ## Containers
 
 ### `GET /api/containers`
@@ -1472,24 +1620,13 @@ List all running Docker containers with resource usage.
 }
 ```
 
-### `GET /api/containers/logs?name=<name>&tail=<lines>`
-Get container logs.
-
-**Auth:** browser cookie
-
-**Query params:** `name` (required), `tail` (default 50)
-
-**Response:** `{ "name": "openclaw-atlas", "logs": "[log lines...]" }`
-
-### `POST /api/containers/action`
-Execute action on a container.
-
-**Body:** `{ "action": "restart" | "stop" | "start", "name": "openclaw-atlas" }`
-
-**Response:** `{ "ok": true, "message": "Container openclaw-atlas restarted" }`
+The container list is the only container route. There is no logs endpoint and no
+action endpoint: logs are read through the terminal WebSocket, and lifecycle
+operations on agent containers go through `/api/agents/[id]/lifecycle`.
 
 ---
 
+
 ## Tools
 
 ### `GET /api/tools-config`
@@ -1522,30 +1659,16 @@ Return the installed OpenClaw CLI version.
 
 **Fallback:** `{ "version": "unknown" }` if the command fails.
 
-### `GET /api/ws`
-Documentation placeholder for WebSocket access.
-
-**Auth:** browser cookie
-
-**Response:** plain text with HTTP `426 Upgrade Required`
-
-Example body:
-```text
-WebSocket endpoint available at ws://HOST/ws. This route is a documentation placeholder and does not upgrade connections.
-```
-
-### `GET /ws`
-Live WebSocket endpoint exposed by the custom server.
-
-**Auth:** same browser session as the dashboard
+### Terminal WebSocket
 
-**Protocol notes:**
-- Hosted on the main HTTP port, not under `/api/`
-- Accepts JSON messages such as `chat.send` and `chat.history`
-- Intended for the dashboard client rather than generic REST consumers
+Not an `/api/` route and not on the dashboard port. `terminal-ws-server.js`
+listens on **`ws://127.0.0.1:3741`** (`TERMINAL_WS_PORT`), bound to the loopback
+interface only, and speaks the PTY protocol described in
+[CONTAINER-TERMINAL.md](../CONTAINER-TERMINAL.md).
 
 ---
 
+
 ## Plugins
 
 ### `GET /api/plugins`
@@ -1707,7 +1830,7 @@ Chat with the built-in AI assistant (PULSE).
 {
   "message": "What can I do on the Agents page?",
   "page": "/agents",
-  "model": "deepseek/deepseek-v4-flash",
+  "model": "deepseek/deepseek-flash",
   "history": []
 }
 ```
@@ -1716,7 +1839,7 @@ Chat with the built-in AI assistant (PULSE).
 |-----------|-------------------------|----------|--------------------------------------------------|
 | `message` | string                  | yes      | The user's question                              |
 | `page`    | string                  | no       | Current page path (used for contextual prompts)  |
-| `model`   | string                  | no       | AI model to use (e.g. `deepseek/deepseek-v4-flash`) |
+| `model`   | string                  | no       | AI model to use (e.g. `deepseek/deepseek-flash`) |
 | `history` | `{role, content}[]`     | no       | Recent conversation history (up to 10 messages)  |
 
 **Response:** `text/event-stream` (Server-Sent Events)
@@ -1745,11 +1868,19 @@ data: [DONE]
 ### `GET /api/credentials`
 List all stored credential profiles and the provider registry.
 
+**Auth:** browser cookie or bearer token
+
 **Response:** `{ profiles: CredentialProfile[], providers: CredentialProviderDef[] }`
 
+Secrets are never returned here — each profile carries only `secretMasked`.
+
+Each entry in a provider's `fields` may carry `docsUrl` and `docsLabel`, pointing at the page where that specific value is created. The provider-level `docsUrl` is the general one shown on the card; the field-level pair is what the add/edit form renders next to the input it is asking you to fill.
+
 ### `POST /api/credentials`
 Create a new credential profile.
 
+**Auth:** browser cookie or bearer token
+
 **Body:** `{ providerId: string, label: string, secret: Record<string, string> }`
 
 **Response:** `{ id: string }` (201)
@@ -1757,30 +1888,77 @@ Create a new credential profile.
 ### `GET /api/credentials/[id]`
 Get a single credential profile (no secret returned).
 
+**Auth:** browser cookie or bearer token
+
 ### `PATCH /api/credentials/[id]`
 Update label and/or secret of a credential.
 
+**Auth:** browser cookie or bearer token
+
 **Body:** `{ label: string, secret: Record<string, string> }`
 
+Secret fields are **merged** onto the stored payload, not substituted for it:
+only the fields carrying a non-empty value are written, and every blank field
+keeps whatever is already stored. This matters for the one two-field provider,
+Trello, where rotating the `token` alone must leave `apiKey` intact — both are
+required by the REST delivery. An empty `secret` (every field blank) therefore
+updates the label only.
+
+When the merge changes the stored payload, `last_synced_at` is reset to `NULL`:
+the agents still hold the previous value, so the profile reads "synced never"
+until it is delivered again, and `GET /api/credentials/detect` reports those
+agents as holding an unrecognised credential for that provider.
+
 ### `DELETE /api/credentials/[id]`
 Delete a credential and its secret permanently.
 
+**Auth:** browser cookie or bearer token
+
 ### `POST /api/credentials/[id]/sync`
-Sync the credential to all agent containers (or a specified subset).
+Sync the credential to agent containers.
 
-**Body (optional):** `{ containers?: string[] }` — if omitted or empty, syncs to all agent containers with `AGENT_ID` labels.
+**Auth:** browser cookie or bearer token
+
+**Body (optional):** `{ containers?: string[] }` — if omitted, targets every agent container carrying an `AGENT_ID` label.
 
 **Response:** `{ results: { container: string, status: 'ok'|'error', error?: string }[] }`
 
-Before syncing, **all agent containers are cleaned first** (env files, CLI auth, TOOLS.md integration markers removed).
-Only the selected containers receive the new credential and TOOLS.md section.
-This ensures that deselecting an agent or deleting a profile removes the credential from all agents.
+Each **targeted** container is first cleaned of this provider only — other
+providers on the same container are left alone — and then receives the new
+credential and its TOOLS.md row.
+
+**Containers outside `containers` are not touched.** Syncing is therefore not a
+way to revoke: dropping an agent from the list leaves whatever it already holds
+in place. Use `DELETE` below to remove a credential from a container.
+
+### `DELETE /api/credentials/[id]/sync`
+Remove this credential from a single container ("de-sync").
+
+**Auth:** browser cookie or bearer token
+
+**Body:** `{ container: string }` — required.
+
+**Response:** `{ ok: true }`
+
+Deletes the provider's CLI auth inside that container and drops its TOOLS.md
+row. `last_synced_at` is deliberately left untouched — it records the last
+delivery, and a removal is not one — and the audit entry is recorded as
+`desync`. The profile stays `active`, because de-sync targets one container and
+the credential may still be delivered to others.
 
 ### `GET /api/credentials/detect`
 Live-detect which credentials are actually present inside agent containers.
 
+**Auth:** browser cookie or bearer token
+
 **Query params (optional):** `?agent=prometheus` — filter to a single container.
 
+Costly: one `docker exec` per container, measured at ~6.5s each. Almost all of
+that is the three CLI calls reaching the network from inside the container, so
+the figure is largely platform-independent — the `docker exec` itself is ~90ms,
+and the local file reads another ~100ms. Callers should treat it as a background
+refresh, not something to block a page render on.
+
 **Response:**
 ```json
 {
@@ -1802,34 +1980,119 @@ Live-detect which credentials are actually present inside agent containers.
       "supabaseCliInstalled": true,
       "trelloLoggedIn": false,
       "trelloCliInstalled": true,
+      "notionLoggedIn": false,
       "toolsMdHasMarkers": true,
       "matchedProfiles": [
         { "profileId": "cred_xxx", "providerId": "github-pat", "label": "GitHub" }
-      ]
+      ],
+      "installedProviders": ["github-pat"]
     }
   ]
 }
 ```
 
-Detection runs `docker exec` inside each container:
-- `gh auth status` for GitHub (token read from `~/.config/gh/hosts.yml`)
-- `vercel whoami` for Vercel (token read from `~/.local/share/com.vercel.cli/auth.json`)
-- `supabase projects list --output json` for Supabase (token read from `~/.supabase/access-token`)
-- `test -f ~/.trello-cli/default/config.json` for Trello
-- TOOLS.md markers at `/root/.openclaw/workspace/TOOLS.md`
+An agent whose probe failed is returned in its place as
+`{ "container", "agentId", "error" }` — none of the fields above are present, so
+consumers must check `error` first.
+
+Each container is read with a **single** `docker exec` running one script that
+emits NUL-delimited key/value pairs; containers are probed concurrently. The
+script reads the credential files directly and the parsing happens in
+JavaScript. Three CLI calls run last and only feed display fields — `githubUser`,
+`vercelUser`, `vercelTeam`, and the `githubLoggedIn` / `vercelLoggedIn` /
+`supabaseLoggedIn` flags, along with `supabaseLinked` and `supabaseProjectRef`,
+which are read only when `supabaseLoggedIn` is true. `supabaseLoggedIn` follows
+the **exit status** of `supabase projects list`, not the text it prints, so a
+failure whose wording is unfamiliar still reads as not logged in.
+`trelloLoggedIn` and `notionLoggedIn` come from the config files instead, and so
+survive a probe cut short. The three calls reach the network from inside the
+container, so a completion sentinel is emitted before them: a probe cut short
+during them still yields valid token matching, with those display fields empty.
+
+Credential files read: `~/.config/gh/hosts.yml`,
+`~/.local/share/com.vercel.cli/auth.json` and `config.json`,
+`~/.supabase/access-token` and `/data/supabase/config.toml`,
+`~/.config/trello/config.json`, `~/.config/notion/config.json`, plus TOOLS.md
+markers at `/root/.openclaw/workspace/TOOLS.md`.
 
 `matchedProfiles` is determined by SHA256-hashing the token installed in the container
 and comparing it against the hashed token of each stored profile in the vault.
 Only exact token matches produce a match — no heuristics, no broad profile-level guesses.
 
+`installedProviders` lists every provider holding a token, matched or not. A
+provider present there but absent from `matchedProfiles` holds a credential no
+stored profile accounts for — an edited-but-not-resynced credential, one
+installed by hand, or the remains of a deleted profile.
+
 ### `POST /api/credentials/[id]/reveal`
-Return the raw secret payload. Every call is logged in the audit trail.
+Return the raw secret payload. Every call is written to `credential_audit_log`, which no route or view reads.
 Use sparingly.
 
+**Auth:** browser cookie or bearer token
+
+Secrets are stored **unencrypted** in `credentials.db` — `credential_secrets.payload`
+holds the raw JSON. Anything that can read that file, or reach this endpoint with a
+valid session, has the secrets in the clear.
+
 **Response:** `{ secret: Record<string, string> }`
 
 ---
 
+## Diagnostics
+
+### `GET /api/debug`
+Whether the three auth-related environment variables are set. Booleans only —
+no value, masked or otherwise, is returned.
+
+**Auth:** browser cookie or bearer token
+
+**Response:** `{ "hasPassword": true, "hasJwtSecret": true, "hasToken": false }`
+
+### `GET /api/envcheck`
+The process environment, with `REV4A_PASSWORD`, `REV4A_TOKEN`,
+`REV4A_JWT_SECRET` and `PROVIDER_DEEPSEEK_API_KEY` redacted. Every other
+variable is returned **in the clear**, so treat the response as sensitive.
+
+**Auth:** browser cookie or bearer token
+
+### `GET /api/provider-usage`
+Usage and quota state per provider, including live OpenRouter figures.
+
+**Auth:** browser cookie or bearer token
+
+**Response:** `{ "providers": [...], "openrouterLive": {…}, "quotas": {…} }`
+
+### `GET /api/update-check`
+Installed version against the latest published one.
+
+**Auth:** browser cookie or bearer token
+
+**Query params:** `check=1` queries the registry; without it the answer comes
+from local state only.
+
+**Response:** `{ "installed": "1.1.15", "latest": "1.1.16", "updateAvailable": true, "package": "@flame0510/project-aether" }`
+
+### `POST /api/update-check`
+Run `rev4a update` as a detached background process. The dashboard restarts
+itself as part of the update, so the connection drops.
+
+**Auth:** browser cookie or bearer token
+
+### `GET /api/alerts/smoke`
+Send a test alert, to verify the Telegram alerting path end to end.
+
+**Auth:** browser cookie or bearer token
+
+**Query params:** `stale=0` skips the staleness check.
+
+**Response:** `{ "ok": true, "stale": true, "result": {…}, "dryRun": false }` —
+`dryRun` is `true` when `REV4A_TELEGRAM_BOT_TOKEN` or `REV4A_TELEGRAM_CHAT_ID`
+is unset, meaning nothing was actually sent.
+
+**Errors:** `403` when smoke alerts are disabled.
+
+---
+
 ## Error Format
 
 All errors return JSON: