@flame0510/project-aether 1.2.0 → 1.4.0

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-15
 
 ## Layering
 
@@ -24,7 +24,8 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 |-----------|------|---------|
 | `Button` | `Button.tsx` | Action button, 5 variants (`primary`, `secondary`, `danger`, `ghost`, `success`), 2 sizes (`sm`, `md`), loading spinner. |
 | `Input` | `Input.tsx` | Text input with label, error state, placeholder. |
-| `Select` | `Select.tsx` | Native select with typed options, label, error state. |
+| `Select` | `Select.tsx` | Native select with typed options, label, error state. An option can be `disabled`, to display a current value that may not be chosen again. |
+| `RemoveButton` | `RemoveButton.tsx` | The `×` that removes an item from a list — one `danger` style everywhere. Whether the removal is immediate or pending goes in `title`, not in the colour. Not for dismissing dialogs — see rule 8. |
 | `Modal` | `Modal.tsx` | Overlay modal, Escape-to-close, maxWidth prop, `type="button"` on close. |
 | `Toast` | `Toast.tsx` | Lightweight toast notification with auto-dismiss (4s), `success` / `error` variants. |
 | `LoadingSpinner` | `LoadingSpinner.tsx` | Inline or fullscreen spinner. |
@@ -41,6 +42,15 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
 | `Icons` | `Icons.tsx` | SVG icons (`EyeIcon`, `EyeOffIcon`), 16/20px shared. |
 | `PasswordInput` | `PasswordInput.tsx` | Password input with inline show/hide toggle (`<button type="button">` with `aria-label`). |
+| `UpdateSection` | `app/agents/UpdateSection.tsx` | OPENCLAW VERSION section of the agent detail panel: the version the agent runs, **Update to <version>** when a newer supported version is downloaded (confirm modal, disabled while the agent is stopped), the running update's steps with backup progress, the outcome, and **Roll back to <version>** after an update. Polls `/api/agents/[id]/update` every 2 s while an update or rollback runs; one action at a time (keyed busy state). |
+| `BackupSection` | inline in `app/agents/PageClient.tsx` | BACKUP section of the agent detail panel, on the cold backup and the restore. **Backup Now** starts `POST /api/agents/[id]/cold-backup`; while the job runs a banner shows the file and its live percent with **Cancel** (`DELETE /cold-backup`). **Restore** (after a confirm) starts `POST /restore` and a banner shows `Restoring <file>…` (no percent: the extract is a single `tar xzf`, and there is no Cancel). Both sections poll their `GET` every 2 s while running, and on mount pick up a job that is already running — a backup lives in a Docker helper, a restore in `agent_restores`, so reloading the page or navigating away never loses them nor allows a second one (the server answers 409 anyway). Delete per row; all actions disabled while one runs; keyed busy state `{ kind, file }` so only the row in action shows the spinner. On the agent list, an activity Badge (fed by `/api/agents/activity-summary`, polled at 2 s only while something runs, otherwise riding the 15 s list poll) reads `BACKUP nn%`, `RESTORING`, `RECREATING`, `EDITING` or `UPDATING`. |
+| `RecreateSection` | inline in `app/agents/PageClient.tsx` | RECREATE section of the agent detail panel. **Recreate Container** starts `POST /api/agents/[id]/recreate` (202) after a confirm; a banner then shows the phase — *Backing up … nn%* while the cold backup runs, *Recreating container…* while the container is rebuilt and the gateway starts. The section polls `GET /recreate` every 2 s, and on mount picks up a recreate that is already running, so a reload or navigation never loses it; it refetches the agent once the job reports `done`. |
+| `ImageDownloadBanner` | `app/agents/ImageDownloadBanner.tsx` | Agent image banner on the Agents page. Polls `/api/agents/image-status` every 2 s; offers **Download Image** when no supported version is downloaded, **Download <version>** when the registry publishes a newer one, and shows the download in progress and its completion. Downloading changes no agent. |
+| `BrowserAccessSection` / `OpenControlUiButton` | `app/agents/BrowserAccessSection.tsx` | Browser access to one agent's Control UI, in its detail panel: requests waiting for approval (Approve / Reject) and approved browsers (Rename / Revoke), refreshed every 5 s while mounted. A successful approve, reject, rename or revoke updates the list at once, since the refresh behind it runs the OpenClaw CLI and takes seconds; a read started before the mutation is discarded. On agents that require approval, "Invite link" fetches `/api/agents/[id]/invite-link` and shows the link in a read-only field with Copy, which uses the Clipboard API in a secure context and the field's selection over plain HTTP, plus a warning when the link uses localhost. `OpenControlUiButton` opens `/api/agents/[id]/open-control-ui` in a new tab inside the click; that route redirects to a one-time link that pairs the browser with no approval, or to the plain token link when none can be issued. Used on the agent cards and in the panel. |
+| `ChannelManager` / `ChannelSection` | `app/agents/ChannelManager.tsx`, `ChannelSection` inline in `app/agents/PageClient.tsx` | Telegram, in the agent detail panel (`ChannelSection` is the card that opens the modal; the modal title is the agent's display name). Reads `GET /channels`; lists pending pairing requests with **Approve** (`POST /channels/pairing`) and approved senders with **Revoke** after a confirm (`DELETE /channels/pairing?senderId=`). Pending comes from `openclaw pairing list`, approved from OpenClaw's pairing store (`lib/channelManager.ts`). Polls pairings every 5 s while open; one keyed busy state per action. |
+| `EditAgentModal` / `EditBanner` | `app/agents/PageClient.tsx` | Rename/ports editing. The modal has **Display Name** and **Host Port** (same input and validation messages as the create wizard, from `lib/agent-ports.ts`), sends `PATCH /api/agents/[id]` and closes on `202`; `EditBanner` (top of the agent detail) polls `GET /api/agents/[id]` every 2 s while an edit is `rebuilding`, resumes on mount, and refetches the agent once it finishes, so a reload or a navigation shows the running edit instead of allowing a second (the server answers 409). No backup is taken: the volume is untouched. |
+| `ModelSection` | `app/agents/ModelSection.tsx` | Primary model and fallbacks for one agent, in its detail panel. Explicit save, no restart. The model is a property of the agent, not of the gateway. Tags models the catalogue marks `deprecated`. |
+| `ModelsProvider` / `useModels` | `app/lib/models-context.tsx` | The client's single model list, from `/api/models`. Whatever changes what is offered calls `refresh()`: the Gateway page after a toggle, a key save or removal, or a sync, and the first-run wizard after saving keys. Everything else only reads, PulseChat included. |
 | `WizardPageClient` + step components | `app/wizard/PageClient.tsx` | Multi-step first-run wizard plus its frame shell, with mobile-first CSS. |
 | `useWizard` | `app/wizard/useWizard.ts` | Shared hook: wizard state, step transitions, provider save, restart. Receives server-side initial state to avoid a loading flash. |
 | Wizard icons | `app/wizard/icons.tsx` | Shared SVG icons (flyweight pattern): `ArrowRightIcon`, `CheckIcon`, `CheckCircleIcon`, `DockerIcon`, `GatewayIcon`, `AgentIcon`, `TemplateIcon`, `LinkIcon`, `ConfigIcon`, `InformationIcon`. |
@@ -62,6 +72,25 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 6c. **An optimistic update moves every field the render derives from, together.** A row that decides its state by reading two fields against each other flips to a third, wrong state if the update touches only one of them — and holds it until the slow refresh lands. Update the whole set the derivation reads, or none of it.
 7. **New UI component** — add it to `app/components/ui/`, export from `index.ts`, document it here. If it's specific to one page, keep it page-local unless another page needs it.
 
+8. **`×` means remove, `✕` means dismiss.** They look alike and are not the same
+    action. Removing an item from a list uses `RemoveButton`; dismissing a dialog
+    is the `Modal` component's own close control. Do not build a third variant of
+    either, and do not reuse one for the other.
+
+    *Outstanding:* four dialogs predate the shared `Modal` and roll their own close
+    control — the edit dialog and the `openclaw.json` dialog in
+    `app/agents/PageClient.tsx` (both a `ghost` Button with `✕`), the drawer in
+    `app/components/SessionDrawer.tsx` (a bare `<button>`), and
+    `app/components/ModelPickerModal.tsx` (`model-picker__close`, which compounds
+    the problem by using `×`, the *remove* glyph, to dismiss, and omits
+    `type="button"`). The fix is to move them onto `Modal`, not to extract a
+    `CloseButton`: they also reimplement Escape-to-close and overlay behaviour.
+    `ModelPickerModal` has no importers at all, so deleting it is the cheaper fix
+    there.
+
+    Separately, `app/agents/PageClient.tsx` has a raw `×` delete-backup button with
+    no accessible name that should be `RemoveButton`.
+
 ## GoF pattern mapping
 
 Already used:

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-09-05
+> **Last updated:** 2026-09-15
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -68,6 +68,7 @@ Rev4a reads the following environment variables. Set them in `/config` (UI) or d
 | `REV4A_ROOT` | No | Installation root, used by `rev4a update` to detect a git checkout |
 | `REV4A_TIMEZONE` | No | IANA timezone used for scheduling and timestamps |
 | `REV4A_FORCE_INSECURE_COOKIE` | No | Allow a non-Secure session cookie — plain-HTTP deployments only |
+| `REV4A_AGENT_IMAGE_REGISTRY` | No | Registry repository agent images are pulled from (default: `ghcr.io/flame0510/rev4a/openclaw-agent-base`); a `localhost` registry is reached over plain HTTP |
 
 See [Alerts](#alerts-telegram) below for the Telegram alert variables.
 
@@ -76,9 +77,9 @@ See [Alerts](#alerts-telegram) below for the Telegram alert variables.
 Every agent is created with:
 
 - A host port mapping (`-p <port>:3000`) for direct access
-- URL format: `http://<host-public-ip>:<port>#token=...`
+- Control UI at `http://<host>:<port>`, opened from the Agents page through `GET /api/agents/[id]/open-control-ui`
 - The provider gateway at `http://host.docker.internal:3740/api/provider/v1`
-- `allowedOrigins: ['*']` for browser Control UI access
+- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback: true`, so the Control UI opens on whatever host the agent is reached on, and pages from other origins are refused
 
 The port is auto-assigned starting from 3000 (or user-specified).
 
@@ -120,7 +121,7 @@ When environment variables are saved via the Config page (Save & Restart):
 | `/plugins` | Plugin manager |
 | `/skills` | Skill registry — browse/edit all skills (shared, per-agent workspace, bundled). Promote agent skills to shared with one click. |
 | `/tools` | Tool configuration |
-| `/gateway` | LLM provider sync + agent model configuration — see [GATEWAY.md](dev/GATEWAY.md) |
+| `/gateway` | LLM provider keys, model catalogue and sync — see [GATEWAY.md](dev/GATEWAY.md) |
 | `/config` | Environment management and server restart |
 | `/login` | Authentication page |
 
@@ -188,6 +189,18 @@ sudo systemctl status rev4a.service
 sudo journalctl -u rev4a -f
 ```
 
+### Start-up and Docker
+
+`rev4a serve` waits for the Docker daemon before its Docker-dependent steps, up to
+`REV4A_DOCKER_WAIT_SECONDS` (default 90, capped at 600; `0` checks once without
+waiting; a negative or non-numeric value means 90). It asks the daemon itself with
+`docker info`, so the wait works the same on any Docker install. The variable is
+read from the process environment, not from the `.env` file.
+
+If the daemon never answers, `serve` starts anyway, skips the network and image
+checks, and says so in the log. The startup sync then reaches no agent, and logs
+that too; run Sync All Agents once Docker is up.
+
 ### Systemd environment override
 
 File: `/etc/systemd/system/rev4a-next.service` (EnvironmentFile)
@@ -290,9 +303,10 @@ Lists all agents (Docker containers with `AGENT_ID` label), with:
 - Name, image, template, status, ports, IP
 - TG channel status chip (green = connected, hidden if not configured)
 - **Shared gateway token** — text input with Save & Sync. Changing the token saves it to `data/agents-token.json` and pushes it to all running containers.
-- **Control UI link** — direct Traefik URL with `#token=<token>` hash, reads the token from `agents-token.json` (source of truth), not from the container's local config.
+- **Control UI link** — the **Open** buttons go through `GET /api/agents/[id]/open-control-ui`, which redirects to the agent's published port on the host the dashboard was reached on: a one-time link on OpenClaw 9.x, the plain `#token=` link otherwise, with the token read inside the container.
 - **Agent creation wizard** — multi-step form at `/agents/create`.
-- **Channel Manager** — each agent detail panel has a Channels section with Telegram configuration and pairing management.
+- **Channel Manager** — each agent detail panel has a Channels section with Telegram configuration and pairing management. Pending requests (a sender's `/start` creates one) show an **Approve** button; approved senders show **Revoke** with a confirmation. Approved senders are OpenClaw's pairing store, not the agent config: on 2026.9.x the SQLite store, read and revoked through OpenClaw's own store functions (see [ARCHITECTURE.md](ARCHITECTURE.md)).
+- **Browser access** — the detail panel section right after Channels. From OpenClaw 9.x each new browser must be approved once before the Control UI connects: the section lists requests waiting for approval (Approve / Reject) and approved browsers (Rename / Revoke), and the agent card shows a "browser waiting" badge. The **Open** buttons first ask the agent for a one-time link that pairs the browser with no approval, and open the plain token link when none can be issued (every 2026.7.x agent). **Invite link** (9.x agents only) gives a link to send to someone else: their browser passes gateway auth and waits in the approval list until approved. The link carries the gateway token every agent shares; changing the agents token invalidates every link sent. All of it runs the OpenClaw CLI inside the container asynchronously.
 
 ### Agent Creation Wizard (`/agents/create`)
 
@@ -306,19 +320,20 @@ Available templates:
 
 **Step 2 — Config:** Enter agent name, optional port, select a primary model from the available providers (pre-filtered by configured provider keys). The first model is pre-selected.
 
-**Step 3 — Deploy:** `POST /api/agents/create` creates the Docker container and returns the Traefik URL with the shared gateway token.
+**Step 3 — Deploy:** `POST /api/agents/create` creates the Docker container and returns its port and the shared gateway token; the wizard links to `http://<host>:<port>#token=<token>`.
 
 **Post-creation pipeline:**
-1. The container boots with the **openclaw-agent-base:latest** image — see [Agent Templates](#agent-templates) below.
+1. The container boots with the newest supported OpenClaw version downloaded here, `openclaw-agent-base:<version>`; the create answers `409` when none is — see [Agent Templates](#agent-templates) below.
 2. OpenClaw gateway starts automatically with `--allow-unconfigured`, generating its own default config.
-3. The route waits for the gateway to be fully ready (health check poll, up to 60 s).
+3. The route waits for the gateway to finish starting with `waitForGatewayReady()`, up
+   to 60 s. On OpenClaw 9.x it waits for `/startupz` to report `started`. The
+   2026.7.1-2 image has no `/startupz`, so there it waits for `/health`, which only
+   shows the server is listening.
 4. Once ready, the route writes:
-   - `gateway.controlUi.allowedOrigins` — Rev4a dashboard URL + Traefik hostname (required for browser Control UI access)
+   - `gateway.controlUi` with the browser-origin policy (`withControlUiPolicy()` in `lib/agent-setup.ts`): the Host-header fallback on, so the Control UI is accepted from the host the browser connected to — a public IP is refused without it — while pages from other origins are refused; an `allowedOrigins: ["*"]` list and the retired `dangerouslyDisableDeviceAuth` are dropped, any other allowlist is kept. Recreate re-applies the policy. Each new browser still needs a one-time device approval
    - `agents.defaults.model.primary` + fallbacks — the primary model selected in the wizard
-5. `syncAgent(name)` writes `models.providers.rev4a` into the container.
-6. The agent's control UI is immediately accessible at `https://<name>.<your-domain>.com#token=<gateway-token>`.
-
-**Key difference from the old pipeline:** the entrypoint no longer generates `openclaw.json`. The bootstrap config (including `controlUi.allowedOrigins`) is written by the create route after the gateway has already started. This eliminates the race condition where the entrypoint would overwrite synced provider config on boot.
+5. The route builds `models.providers.rev4a` with `buildRev4aProviderConfig()` and writes it with `openclaw config patch --stdin`.
+6. The agent's Control UI is reachable at `http://<host>:<port>#token=<gateway-token>`. For HTTPS or a domain, put your own reverse proxy in front of the published port: Rev4a sets no reverse-proxy labels on agent containers.
 
 ---
 
@@ -328,8 +343,9 @@ Each agent is created with a **persistent Docker volume** `agent-<name>-data`
 mounted at `/root`. This cleanly separates two planes:
 
 - **Software → image.** OpenClaw, `gh`, `vercel`, `supabase`, `trello`, Node — all
-  live in `openclaw-agent-base:latest` (outside `/root`). Updated by rebuilding the
-  image and recreating the container.
+  live in the agent image `openclaw-agent-base:<version>` (outside `/root`). A recreate
+  keeps the agent's OpenClaw version; moving an agent to a newer version is a separate
+  update.
 - **Data → volume.** Config (`openclaw.json`), state DB (`openclaw.sqlite`),
   workspace files, and CLI credentials (`.config/gh`, `.local/share/com.vercel.cli`,
   `.supabase`, …) live in `/root` and survive container removal.
@@ -341,9 +357,12 @@ a re-created agent keeps the workspace the user edited.
 
 | Action | What it does |
 |---|---|
-| **Backup** | `tar` of `/root` (excl. npm cache) → `.tar.gz` in the `rev4a-backups` volume |
+| **Backup** | `tar` of `/root` (excl. npm cache) → `.tar.gz` in the `rev4a-backups` volume, while the agent runs |
+| **Cold backup** | stop → archive `/root` (excl. npm cache) as `.partial` in a helper container → read the archive back → rename → start again if it was running. Other operations on the agent answer 409 meanwhile. Survives a Rev4a restart. API only for now (`/api/agents/[id]/cold-backup`) |
+| **Update** | the agent panel's OPENCLAW VERSION section, when a newer supported version is downloaded: count transcript events and cron jobs → cold pre-update backup → recreate on the new version (its data migrates one way) → wait for that version → check nothing went missing. Unused agent images are removed afterwards |
+| **Rollback** | after an update: stop → restore the pre-update backup → recreate on the previous version. Everything since the backup is lost |
 | **Restore** | stop → replace `/root` with the backup (real wipe incl. dotfiles) → restart. Software/image untouched — only data goes back in time |
-| **Recreate** | auto-backup first (aborts if it fails) → rebuild from `openclaw-agent-base:latest` keeping the volume → picks up image/OpenClaw/CLI updates |
+| **Recreate** | auto-backup first (aborts if it fails) → rebuild on the agent's own OpenClaw version (`openclaw-agent-base:<version>`, tagged or pulled when missing) keeping the volume. Never changes version |
 | **Restart** | `docker restart`, nothing else |
 | **Delete** | **destructive**: removes container **+ volume + all backups**. Cannot be undone |
 
@@ -355,19 +374,50 @@ agent means rebuilding the image + Recreate, never `update` inside the container
 
 ## Agent Templates
 
-### Base Image (`openclaw-agent-base:latest`)
+### Base Image (`openclaw-agent-base:<version>`)
 
 **Dockerfile:** `agent-templates/base-image/Dockerfile`
 
+**Versions.** Images are kept locally per OpenClaw version, `openclaw-agent-base:<version>`;
+`:latest` is not used. The versions this release supports, newest first, and the model
+`input` list for each, are in `lib/agent-versions.json`, read by the server and the
+`rev4a` CLI. The Agents page banner offers the newest supported version the registry
+publishes (`ghcr.io/flame0510/rev4a/openclaw-agent-base`, or `REV4A_AGENT_IMAGE_REGISTRY`);
+downloading touches no agent. Create uses the newest supported version downloaded; recreate
+keeps the agent's version. An agent card shows **UPDATE AVAILABLE** when a newer supported
+version is downloaded.
+
 Built from `node:24-bookworm-slim`, includes:
-- OpenClaw CLI + DeepSeek provider plugin
+- OpenClaw, pinned by the `OPENCLAW_VERSION` build argument and recorded as the
+  `org.opencontainers.image.version` label
+- `gh`, `vercel`, `trello`, `supabase`
+- Plugins under `/opt/openclaw-plugins`, outside the agent volume and pinned to the same
+  OpenClaw release: DuckDuckGo web search
 - `openssl` (for local token generation)
 - Custom entrypoint `/agent-entrypoint.sh`
 
+See also [agent-templates/README.md](../agent-templates/README.md).
+
 **Entrypoint behavior:**
 - Resolves the auth token (file > env > local random)
 - Does NOT generate `openclaw.json` — OpenClaw creates its own default config on first boot
-- **Version-gated migration:** if the OpenClaw version differs from the one recorded in `/root/.openclaw/.last-version` (i.e. the image was rebuilt to a newer OpenClaw), runs `openclaw doctor --non-interactive` **before** starting the gateway. This applies only safe migrations (config normalization + on-disk state moves), skips service restarts, and aligns the persistent volume's state/config to the new binary. Best-effort — never blocks boot. Runs at most once per version change, not on every restart.
+- **Version-gated migration:** if the OpenClaw version differs from the one recorded in
+  `/root/.openclaw/.last-version` (a newer image, or a new volume), runs
+  `openclaw doctor --fix --non-interactive` **before** starting the gateway. `--fix` is
+  required from OpenClaw 9.x: the agent database schema is migrated only with the gateway
+  stopped, and the gateway refuses the old schema rather than migrating it. The version is
+  recorded only after a successful run, so a failed migration is retried on the next boot.
+  A failure does not block boot.
+- **Image defaults**, before the gateway starts, written only where missing:
+  - the image's plugin directories in `plugins.load.paths`
+  - `tools.web.search.provider: "duckduckgo"` when no provider is set
+  - `agents.defaults.heartbeat.every: "0m"` when unset: every heartbeat tick is a
+    model-calling turn, so the recurring cadence is opt-in
+
+  An explicit value, such as a heartbeat turned on for one agent, is never overwritten.
+  The config is read with one node process and written through `openclaw config patch`,
+  which validates; if `openclaw.json` cannot be read as JSON, the defaults are skipped and
+  the log says so.
 - Starts OpenClaw gateway with `--allow-unconfigured`: `openclaw gateway --bind lan --port 3000 --auth token --token "<token>" --allow-unconfigured`
 - Everything else (controlUi, model refs, providers) is handled by the create route and the Gateway sync module
 
@@ -385,23 +435,33 @@ repo. The copy is skipped when the workspace is already populated (see
 
 ## Gateway Page (`/gateway`)
 
-Two panels:
+One job: provider configuration. API keys, which catalogue models this deployment
+offers, and pushing that catalogue to every agent.
+
+- Reads the model catalogue from `models.config.json`, merged with user toggles in
+  `<data dir>/model-overrides.json`
+- Scans providers with keys in `<data dir>/provider-keys.json`
+- `PUT /api/gateway/provider` runs `syncAllAgents()`, which writes
+  `models.providers.rev4a` into every agent container
+- **Does NOT touch** `agents.defaults.model` or `agents.list[].model` — those are
+  per-agent settings
+
+### Per-agent model, elsewhere
 
-### Provider Sync
-- Reads active models from `models.config.json` (file-based model catalogue)
-- Scans providers with keys in `data/provider-keys.json`
-- `PUT /api/gateway/provider` runs `syncAllAgents()` which writes `models.providers.rev4a` to every agent container
-- **Does NOT touch** `agents.defaults.model` or `agents.list[].model` — model references are managed per-container from the Agents Tab
+Choosing which model one agent runs is not on this page. It lives in the Model
+section of that agent's detail panel on the Agents page
+(`app/agents/ModelSection.tsx`), which calls `PUT /api/gateway/agent` to write the
+model ref into that container's `openclaw.json`. No gateway restart: OpenClaw
+watches the file and hot-applies the change.
 
-### Agent Model Config
-- Select a container and set its primary model
-- `PUT /api/gateway/agent` writes the model ref (`primary`, `fallbacks`) directly into the container's `openclaw.json`
-- Does NOT restart the gateway — writes are live via file write
+The model is a property of the agent, not of the gateway. See
+[GATEWAY.md](dev/GATEWAY.md) for the write semantics: omitting `fallbacks` keeps the
+agent's current list, `[]` clears it.
 
 ### Model Catalogue (`models.config.json`)
 File-based, tracked in git. Each entry:
 ```json
-{ "id": "deepseek/deepseek-v4-flash", "name": "DeepSeek V4 Flash", "provider": "deepseek", "enabled": true }
+{ "id": "deepseek/deepseek-flash", "name": "DeepSeek Flash", "provider": "deepseek", "enabled": true }
 ```
 Models with `enabled: false` are ignored.
 Only models whose provider has a key in `data/provider-keys.json` are synced.
@@ -414,7 +474,7 @@ Only models whose provider has a key in `data/provider-keys.json` are synced.
 
 | Property | Value |
 |---|---|
-| Image | `openclaw-agent-base:latest` (Node 24-bookworm-slim + OpenClaw) |
+| Image | `openclaw-agent-base:<version>` (Node 24-bookworm-slim + OpenClaw) |
 | Port | `0.0.0.0:3731 → 3000` |
 | IP | `172.19.0.3` |
 | AGENT_ID | `atlas` |