@flame0510/project-aether 1.6.2 → 1.8.0

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Rev4a Architecture — Design & Vision
 
 > **Status:** Active — `main` branch
-> **Last updated:** 2026-09-22
+> **Last updated:** 2026-09-26
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -35,7 +35,7 @@
 
 ```
 ┌────────────────────────────────────────────────────────────────┐
-│  DOCKER HOST (187.77.156.41, 4 CPU, 15 GB RAM, 193 GB disk)   │
+│  DOCKER HOST                                                   │
 │                                                                │
 │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐ │
 │  │ rev4a-control  │  │ agent-argus      │  │ agent-atlas  │ │
@@ -72,7 +72,7 @@
 
 **Credentials vault:** The `/credentials` page stores third-party service tokens in `credentials.db` and installs them into containers on explicit sync. Provider API keys live separately in `provider-keys.json`, managed from the Gateway UI.
 
-**Container management UI:** The `/containers` page lists all running Docker containers with resource usage and quick links, and opens a web terminal into any of them. Fully functional.
+**Container management UI:** The `/containers` page lists all Docker containers, running or stopped, with status, image, IP and ports, and opens a web terminal into any of them. Fully functional. (Machine CPU, RAM and disk are on `/system`.)
 
 **Workspace API:** Lazy-loaded file tree explorer with real-time reads (no caching), supports both host and container workspaces via `docker exec`.
 
@@ -81,7 +81,7 @@
 | Feature | Status | Notes |
 |---|---|---|
 | Credentials (UI + API) | 🟢 Implemented | SQLite, no encryption yet |
-| Container page | 🟢 Functional | Lists all containers, resources, web terminal |
+| Container page | 🟢 Functional | Lists all containers, web terminal |
 | Agent creation wizard | 🟢 Implemented | One-click create with model/template selection |
 | Provider proxy | 🟢 Implemented | Agents route through Rev4a provider gateway |
 | Shared volumes | 🟢 Implemented | Skills + repos mounted on all agents |
@@ -132,6 +132,18 @@ The central container, running the Next.js dashboard + orchestration API.
   a key), `isModelOffered()` (enforced by the proxy and the assistant) and
   `catalogueStatus()`. A failed read of `models.config.json` falls back to the last
   good copy and never deletes overrides.
+- **The model data has three files and three scripts.** `models.config.json` is curated by
+  hand (identity, `enabled`, `deprecated`, and an optional `info` block for what no API
+  publishes: the vendor's size claim, benchmarks, the docs link, notes).
+  `model-pricing.json` and `model-details.json` are **generated** by
+  `npm run refresh:pricing` (`scripts/refresh-model-pricing.mjs`): prices from OpenRouter,
+  and per model the description, architecture and benchmarks from OpenRouter plus the size,
+  weight mix, licence and dates from the Hugging Face card. Two scripts back the curation
+  of `info`: `npm run info:suggest` (`scripts/model-info-suggest.mjs`) prints the candidate
+  facts from a card, and `npm run info:verify` (`scripts/model-info-verify.mjs`) refuses a
+  proposal the card does not support — evidence per field, every benchmark value under the
+  column that names this model. `GET /api/models/details` merges the three files for the
+  details modal (`docs/dev/GATEWAY.md`).
 - **Agent images and OpenClaw versions.** `lib/agent-versions.json` lists the supported
   OpenClaw versions, newest first, with the model `input` list for each; the server reads
   it through `lib/agent-versions.ts`, the `rev4a` CLI with `require`. The provider sync
@@ -560,19 +572,19 @@ The Rev4a daemon (`daemon.js`) is a standalone Node.js process that bridges the
 
 ### Responsibilities
 
-1. Poll `openclaw sessions --json --all-agents` on a configurable interval
+1. Poll `openclaw sessions --json --all-agents` every 30 s
 2. Upsert session rows into `events.db`
-3. Emit `spawn` / `complete` / `error` events into the `events` table
-4. Collect system metrics (CPU, RAM, disk) every poll cycle
-5. Detect anomalies (CPU > 90%, RAM > 90%) and log warnings
-6. Manage DB lifecycle (WAL mode, checkpoint after each cycle)
+3. Emit `spawn` / `complete` / `fail` / `spawn_timeout` events into the `events` table
+4. Sample the host machine (CPU, RAM, swap, storage) every 30 s into `metrics.db`, on a
+   timer of its own
+5. Detect anomalies (CPU > 85%, RAM > 90%, a disk > 90%) and record them as events
+6. Manage DB lifecycle (WAL mode; events.db checkpointed after each poll cycle)
 
-### Poll Intervals
+### Poll Interval
 
-| Condition | Interval |
-|---|---|
-| No active sessions | 30 s |
-| ≥ 1 session with status `working` | 15 s |
+A fixed 30 s timer, whether or not sessions are working. When the OpenClaw CLI is not on
+the host, the session poll logs it once and stays idle; the machine metrics keep being
+sampled, since they have their own timer.
 
 ### Cost Estimation
 
@@ -614,28 +626,45 @@ The daemon uses `INSERT … ON CONFLICT DO UPDATE` with these rules:
 
 ### System Metrics
 
-Every poll cycle the daemon records a `system_metrics` row. Data sources:
-
-- **CPU**: cgroup v2 usage delta (`/sys/fs/cgroup/cpu.stat`) when available, falls back to `/proc/stat` host ticks
-- **RAM**: `/proc/meminfo`
-- **Disk**: `df -BG /data`
-- **Load**: `os.loadavg()[0]`
-
-Metrics older than 24 h are pruned automatically each cycle.
+Every 30 s (`METRICS_INTERVAL_MS`) the daemon samples the machine it runs on and writes a
+`system_metrics` row plus one `system_disks` row per filesystem into `metrics.db` — its
+own database next to `events.db` (schema in `docs/dev/DATABASE.md`). Machine-wide sources:
+
+- **CPU**: busy share of all cores since the previous sample, from host ticks
+  (`os.cpus()`, i.e. `/proc/stat` on Linux) — the whole machine, not Rev4a's cgroup
+- **RAM / swap**: `/proc/meminfo` on Linux, used = `MemTotal − MemAvailable` (what `free`
+  shows); on macOS (development) active + wired + compressed pages from `vm_stat` and
+  `vm.swapusage`; elsewhere `os.totalmem()` / `os.freemem()` and no swap
+- **Storage**: `fs.statfsSync()` on `/`, Docker's data root (`docker info`, asked once and
+  retried every 10 min while Docker is down) and Rev4a's data directory, each device once;
+  a path that cannot be read (Docker Desktop's root inside its VM) is skipped
+- **Load**: `os.loadavg()` 1 / 5 / 15 min
+
+The first sample comes about 5 s after start (the CPU figure needs a delta from the baseline
+taken at load), then one every 30 s. Samples older than 30 days are pruned at every sample.
+`metrics.db` is opened in a try: if it cannot be (corrupt, unwritable), sampling is off —
+`[METRICS] disabled` in the log — and the session poll keeps running. The API side reads
+it through `lib/metrics-db.ts` (read-only, `null` when there is nothing to read);
+`GET /api/metrics` serves the System page (`/system`) and the dashboard's Machine card.
 
 ### Anomaly Detection
 
-The daemon compares the last two metric samples. If a threshold is exceeded and the cooldown (5 min) has passed, it logs a `WARN` line:
+After each sample the daemon inserts a `system_anomaly` event into `events.db`
+(`{ metric, values, threshold, message }`) and logs `[ANOMALY] <message>` when:
 
-| Metric | Threshold |
-|---|---|
-| CPU | > 90% |
-| RAM | > 90% |
+| Metric | Condition | Repeats |
+|---|---|---|
+| CPU | > 85% on two consecutive samples | at most once per 5 min |
+| RAM | > 90% on two consecutive samples | at most once per 5 min |
+| Disk (each filesystem) | ≥ 90% | once when it reaches it, no cooldown — again only after it drops back under, or after the daemon restarts |
+
+No feature consumes `system_anomaly` events yet; they only pass through the generic
+event feeds.
 
 ### DB Safety
 
 - WAL mode + `PRAGMA synchronous = NORMAL` for concurrent read safety
-- `PRAGMA wal_checkpoint(PASSIVE)` runs after each poll cycle
+- `PRAGMA wal_checkpoint(PASSIVE)` runs after each poll cycle, `FULL` every 10 cycles
 - On `uncaughtException` the daemon logs but does NOT exit — relies on systemd Restart=always for recovery
 
 ### Migrations
@@ -722,17 +751,19 @@ ALTER TABLE sessions ADD COLUMN ended_at INTEGER;
 
 Rev4a provides a real, interactive terminal for any agent container via
 a WebSocket-connected PTY. The implementation is documented in detail in
-[docs/container-terminal.md](container-terminal.md).
+[docs/CONTAINER-TERMINAL.md](CONTAINER-TERMINAL.md).
 
 ### Two-process architecture
 
 | Process | Port | Role |
 |---|---|---|
-| `rev4a-next` (Next.js) | 3740 | Serves the terminal page, auth, API |
-| `rev4a-terminal-ws` (standalone) | 3741 | WebSocket PTY server via `node-pty` |
+| Next.js (`next start`) | 3740 | Serves the terminal page, auth, API |
+| `terminal-ws-server.js` | 3741 (127.0.0.1) | WebSocket PTY server via `node-pty` |
 
-The terminal server runs as a separate systemd service (rev4a-terminal-ws) to avoid event-loop
-contention with Next.js during high-throughput I/O.
+Both are started by `rev4a serve`; the terminal server is a process of its own to avoid
+event-loop contention with Next.js during high-throughput I/O. It has no authentication
+of its own and is reachable only through a reverse proxy route (see
+[CONTAINER-TERMINAL.md](CONTAINER-TERMINAL.md#routing)).
 
 ### Why custom DOM over xterm.js
 
@@ -742,7 +773,7 @@ CSS conflicts. The current implementation uses a plain `<div>` with native
 browser scrolling and a hidden `<textarea>` for input — stable under any
 output volume.
 
-See [container-terminal.md](container-terminal.md#terminal-client-browser)
+See [CONTAINER-TERMINAL.md](CONTAINER-TERMINAL.md#terminal-client-browser)
 for the full rationale.
 
 ## 12. Technology Stack

package/docs/CONTAINER-TERMINAL.md

@@ -15,7 +15,7 @@ via `node-pty` and streaming I/O over a dedicated WebSocket server.
 Browser (xterm-compatible DOM terminal)
   │  WebSocket wss://rev4a/containers/terminal/{id}
   ▼
-terminal-ws-server.js (port 3741, proxied by Traefik)
+terminal-ws-server.js (127.0.0.1:3741, reached through a reverse proxy — see Routing)
   │  node-pty
   ▼
 docker exec -it {containerId} env TERM=xterm-256color bash
@@ -30,20 +30,30 @@ Container Shell (bash, interactive, full PTY)
 
 | Process          | Port  | Role |
 |------------------|-------|------|
-| `rev4a-next`   | 3740  | Next.js app (pages, API routes, auth) |
-| `rev4a-terminal-ws` | 3741 | Standalone WebSocket server for terminal sessions |
+| Next.js (`next start`) | 3740  | Next.js app (pages, API routes, auth) |
+| `terminal-ws-server.js` | 3741 | Standalone WebSocket server for terminal sessions, bound to 127.0.0.1 |
 
-The terminal server is a separate systemd service (rev4a-terminal-ws). It was isolated from
+Both are child processes of `rev4a serve` (with `daemon.js`), under the single
+`rev4a.service` unit in production. The terminal server is its own process, isolated from
 the Next.js app to avoid event-loop contention during high-throughput I/O (fast
 `seq`, `cat` on large files, interactive shell sessions).
 
-### Traefik routing
+### Routing
 
 ```
 /containers/terminal/{id}          → Next.js (page serving TerminalClient)
-/api/terminal-ws?id={containerId}  → WebSocket proxy → ws://127.0.0.1:3741
+/api/terminal-ws?id={containerId}  → reverse proxy → ws://127.0.0.1:3741
 ```
 
+The browser opens the socket on the dashboard's own host (`/api/terminal-ws`). Next.js
+has no route for that path, so the terminal works only when a reverse proxy in front of
+Rev4a forwards it to port 3741; without one the socket gets a 404.
+
+**No authentication of its own.** `terminal-ws-server.js` checks neither the session
+cookie nor the token: whoever reaches it gets a shell in the container named by `id`.
+It listens on 127.0.0.1 only, so the exposure is exactly what the proxy route above
+opens. An open issue.
+
 ### Data flow
 
 1. User opens `/containers/terminal/openclaw-atlas`
@@ -257,8 +267,7 @@ app/containers/terminal/
 ├── [id]/
 │   ├── page.tsx               # Next.js page (auth-protected)
 │   └── TerminalClient.tsx     # Client-side terminal component
-terminal-ws-server.js           # WebSocket PTY server (rev4a-terminal-ws.service)
-rev4a.service                  # Systemd target for all three services
+terminal-ws-server.js           # WebSocket PTY server, started by `rev4a serve`
 ```
 
 ## Known Limitations

package/docs/DESIGN-SYSTEM.md

@@ -2,7 +2,7 @@
 
 Source of truth: `app/design-system.ts` + CSS tokens in `app/globals.css`.
 
-> **Last updated:** 2026-07-03
+> **Last updated:** 2026-09-26
 
 ---
 
@@ -44,19 +44,22 @@ Rev4a uses a **square/sharp** visual language:
 Defined in `app/globals.css` as CSS custom properties:
 
 ```css
---bg:           #0a0a0a      /* Page background */
---bg2:          #111         /* Slightly lighter surface */
---border:       #222         /* Default border */
---text:         #e0e0e0      /* Primary text */
---text-dim:     #888         /* Muted/secondary text */
---violet:       #a78bfa      /* Brand accent */
---violet-bg:    #1a1030     /* Violet-tinted hover/active background */
---green:        #22c55e      /* Success */
---red:          #ef4444      /* Error */
---yellow:       #eab308      /* Warning */
---blue:         #60a5fa      /* Info / links */
+--bg:         var(--color-bg-950)       /* #0A0A0B  Page background */
+--bg2:        var(--color-bg-900)       /* #111114  Slightly lighter surface */
+--border:     var(--color-border-700)   /* #222228  Default border */
+--text:       var(--color-text-100)     /* #E8E8E8  Primary text */
+--text-dim:   var(--color-text-400)     /* #888     Muted/secondary text */
+--violet:     var(--color-accent-500)   /* #925BFC  Brand accent */
+--violet-bg:  rgba(146, 91, 252, 0.08)  /* Violet-tinted hover/active background */
+--green:      var(--color-success-500)  /* #22c55e  Success */
+--red:        var(--color-danger-500)   /* #ef4444  Error */
+--yellow:     var(--color-warning-500)  /* #f59e0b  Warning */
+--blue:       var(--color-blue-400)     /* #60a5fa  Info / links */
 ```
 
+The semantic tokens above point at the palette tokens (`--color-*`) defined at the top of
+`app/globals.css`; the hex values are the palette's, quoted for reference.
+
 ### Typography
 
 - Monospace by default: `var(--font-mono-stack)`
@@ -66,6 +69,12 @@ Defined in `app/globals.css` as CSS custom properties:
 
 ## Component design rules
 
+A shared component grows by **variant, never by copy**. `Metric` is the example: `size="sm"`
+is the compact form for a grid inside a dialog (smaller value, tighter spacing), and it lives
+on the primitive so the modal and the dashboard cannot drift apart. When a new page needs a
+pattern that does not exist yet, add it here and to `docs/FRONTEND-ARCHITECTURE.md`'s catalog,
+then use it — a one-off copy of markup is the thing this section exists to prevent.
+
 1. **Border radius: 0 everywhere.** `border-radius: 0` or sharp corners. Exceptions: `Pill`, avatar circles, status dots.
 2. **No shadows.** Flat design. Use `border: 1px solid var(--border)` to define surfaces.
 3. **Violet is the only accent.** `var(--violet)` for active states, primary actions, headings. `var(--violet-bg)` for hover/active backgrounds.
@@ -73,6 +82,7 @@ Defined in `app/globals.css` as CSS custom properties:
 5. **CSS vars over hardcoded colors.** Never inline `#22c55e`, `#ef4444`, `#888` — use the CSS token.
 6. **Loading feedback.** Use `loading` prop on `Button` (shows inline spinner). Do not render separate loader elements.
 7. **Minimal animation.** Transitions on hover/active (0.1s–0.12s), spin on loading spinner. No bounce, shake, or decorative animations.
+8. **Data display: violet for the data, status colours for levels.** A chart series is `var(--violet)` (2px line, 10% wash), grid and axis text are `var(--border)` / `var(--text-dim)`, never the series colour. A `Meter` fill is violet when fine and `var(--yellow)` / `var(--red)` at its warning / critical level, with the level also written out — status never rests on colour alone. Focus on a chart is a 1px `outline` in `var(--violet-dim)`, not a shadow. See `TimeSeriesChart` and `Meter` in `docs/FRONTEND-ARCHITECTURE.md`.
 
 ### React hook
 

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-09-22
+> **Last updated:** 2026-09-26
 
 ## Layering
 
@@ -38,6 +38,8 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `ModalityIcons` | `ModalityIcons.tsx` | Capability badges parsed from a model's `modality` string (`"text+image->text"`). Input types render as icons; a non-text **output** is called out separately, since reading an image and generating one are different capabilities. Pass `dynamic` for router models, which advertise the union of everything they might route to and so show "varies" instead. |
 | `Metric` | `Metric.tsx` | Metric card with title, value, subtitle, tone, and a `size` (`md` default, `sm` for a grid inside a dialog: smaller value, tighter spacing). |
 | `StatusCard` | `StatusCard.tsx` | Health/status report card. |
+| `Meter` / `meterLevel` | `Meter.tsx` | Horizontal 0-100 % fill whose colour carries the level (`ok` accent, `warning` yellow, `critical` red); the level is also written out beside it, never colour alone. `meterLevel(percent, warning, critical)` picks the level. ARIA `role="meter"`. |
+| `TimeSeriesChart` | `TimeSeriesChart.tsx` | One series over time in plain SVG measured to its container (text never scaled): a 2px accent line for the value, a 10 % wash up to the bucket's peak, a hairline grid at 0 / 50 / 100 %, the latest value labelled at the line's end. Points further apart than 1.5 buckets are not joined (a gap means no samples). Hover or keyboard focus (← → Esc) shows a crosshair snapped to the nearest point with value and peak; a **Table** disclosure holds the same data. `stale` dims the previous render while a new range loads. Used by the System page. |
 | `Surface` | `Surface.tsx` | Shared panel/card surface, variant prop. |
 | `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
 | `Icons` | `Icons.tsx` | SVG icons (`EyeIcon`, `EyeOffIcon`), 16/20px shared. |
@@ -45,7 +47,9 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `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. |
+| System page | `app/system/PageClient.tsx` | `/system`: CPU, memory and storage of the host, from `GET /api/metrics`. Three cards (CPU with cores and load; memory with available and swap; one `Meter` per filesystem with its roles) — thresholds 85/95 % for CPU and memory, 80/90 % for storage — then a range switch (`Tabs`: 1h · 24h · 7d · 30d) scoping the charts below it: CPU and memory average with peak, one chart per filesystem. Polls every 30 s with an `AbortController` ref (a range change aborts the previous fetch). Times in the configured Rev4a timezone (`useRev4aTimezone`). Before the first answer the cards and charts are skeletons shaped like them (`app/system/SystemSkeleton.tsx`, also the route's `loading.tsx`), so nothing jumps; the hostname line is cut with an ellipsis and never widens the page. Says *No samples yet* before the daemon's first sample and *Not collecting* when the latest sample is older than three intervals. Two columns of charts from lg (992px) up, one below. |
+| Machine card | `app/components/SystemCockpit.tsx` | On the dashboard, next to Active sessions: CPU, RAM and the fullest disk now, each figure coloured only when past its threshold (same thresholds as the System page), the issues named in words, and a link to `/system`. It says *No samples yet* before the first sample, *Not collecting* when the newest is stale, and *Metrics unavailable* when a refresh fails (keeping the last figures). A `Surface`, not a `Metric`: a danger `Metric` paints its whole value red. |
+| `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 while a download runs shows the percent of layers finished and the latest line of docker's output (the bar is indeterminate until a percent can be computed). **Cancel** (`DELETE /api/agents/download-image`, own loading state) appears once `image-status` reports the download running; before that the button reads *Starting…* and is disabled. Every outcome — ready and cancelled for 3 s, a failure until the next action — comes from the server's `lastResult`, so one that ended while the page was closed or reloading is still reported if it is less than 30 s old (aged with `serverTime`). Each outcome is announced once per page load, although the Agents page mounts the banner in three places (mobile list, mobile detail, desktop). Downloading changes no agent. |
 | `VersionBanner` | `app/components/VersionBanner.tsx` | "Update available" banner for Rev4a itself, when `GET /api/update-check?check=1` reports a newer published version (dismissable per version, remembered in `localStorage`). **Update now** starts `POST /api/update-check`; because that update restarts the server, the banner cannot be told the outcome by the response: it records what it asked for in `sessionStorage`, polls `/api/update-check` until the installed version moves (two minutes at most) and reloads, then on the next mount either confirms "Updated to vX" or reports that the update did not complete and points at `update.log` (the update's own output). It never reloads blindly onto the same version. |
 | `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`). When that store cannot be read the panel shows the reason instead of "No approved senders" (`PairingState.error`), so an empty list is never a guess. Polls pairings every 5 s while open; one keyed busy state per action. |
@@ -58,7 +62,7 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | Wizard icons | `app/wizard/icons.tsx` | Shared SVG icons (flyweight pattern): `ArrowRightIcon`, `CheckIcon`, `CheckCircleIcon`, `DockerIcon`, `GatewayIcon`, `AgentIcon`, `TemplateIcon`, `LinkIcon`, `ConfigIcon`, `InformationIcon`. |
 | `tokens` | `tokens.ts` | TypeScript types for `Tone` and related token values. |
 | `Badge` | `Badge.tsx` | Inline status tag with tone variants (success, danger, warning, neutral). Used for channel chips, pairing labels, error/success messages. |
-| `Skeleton` + shape helpers | `app/components/Skeleton.tsx` | Shimmer placeholders. `Skeleton` is the primitive; the rest mirror one specific layout each: `TreeSkeleton`, `CodeSkeleton`, `CronJobsSkeleton`, `CronRunsSkeleton`, `CredentialCardsSkeleton`, `AgentSyncRowsSkeleton`, `SkeletonLines`, `SkeletonMetric`, `CardRowSkeleton`. A shape helper must match the real markup it stands in for — same row structure, same paddings, same element count where the count is known — so nothing reflows when data replaces it. |
+| `Skeleton` + shape helpers | `app/components/Skeleton.tsx` | Shimmer placeholders. `Skeleton` is the primitive; the rest mirror one specific layout each: `TreeSkeleton`, `CodeSkeleton`, `CronJobsSkeleton`, `CronRunsSkeleton`, `CredentialCardsSkeleton`, `AgentSyncRowsSkeleton`, `SkeletonLines`, `SkeletonMetric`, `CardRowSkeleton`. A shape helper must match the real markup it stands in for — same row structure, same paddings, same element count where the count is known — so nothing reflows when data replaces it. Inside text (a `<p>`, a `<span>`) pass `as="span"`: a `<div>` there is invalid HTML, and the parser splits the paragraph in the server-rendered page. The System page keeps its own shapes in `app/system/SystemSkeleton.tsx`, each shimmer inside the class of the text it replaces so the line boxes are the real ones — measured to 0 px of movement on desktop and mobile. |
 
 ### Rules
 
@@ -153,7 +157,7 @@ For interactive pages that can change view/file/tab quickly:
 For every new/changed page:
 
 1. No new one-off card styles unless justified.
-2. Use `app/components/ui/*` primitives first — `Button`, `Input`, `Select`, `Modal`, `Toast`, `Surface`, `Metric`, `StatusCard`, `Pill`, `Page`, `Tabs`, `ItemList`, `FilterBar`, `PropertyList`, `TemplateOption`, `LoadingSpinner`.
+2. Use `app/components/ui/*` primitives first — `Button`, `Input`, `Select`, `Modal`, `Toast`, `Surface`, `Metric`, `StatusCard`, `Meter`, `TimeSeriesChart`, `Pill`, `Page`, `Tabs`, `ItemList`, `FilterBar`, `PropertyList`, `TemplateOption`, `LoadingSpinner`.
 3. Async data must render skeleton, not fake zero values.
 4. Business logic stays in `lib`/API routes; UI consumes typed payloads.
 5. If a pattern is introduced, name it and keep it in `lib/patterns` or `app/components/ui`.

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-26
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -9,50 +9,34 @@ A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 **Process manager:** `rev4a serve` (single command). Production: systemd service (`rev4a.service`).
 **Repository:** `github.com/Flame0510/rev4a.git` (branch: `main`)
 
----
-
-## Overview
-
-| Field | Value |
-|---|---|
-| VPS IP | `187.77.156.41` |
-| OS | Ubuntu 24.04.4 LTS |
-| Resources | 4 CPU, 15 GB RAM, 193 GB disk |
-
-
 ---
 
 ## Architecture
 
 ```
-                      Internet
+              Browser (directly, or through a reverse proxy of your choice)
                          │
-                    ┌────┴────┐
-                    │ Traefik │  (Docker container, host network)
-                    │  :443   │
-                    └────┬────┘
+              ┌──────────┴──────────────────┐
+              │  rev4a serve                │
+              │  (systemd: rev4a.service)   │
+              │  Next.js 16      :3740      │
+              │  daemon.js                  │
+              │  terminal WS     :3741      │
+              └──────────┬──────────────────┘
                          │
-              ┌──────────┴──────────┐
-              │  rev4a             │
-              │  systemd (rev4a.service)    │
-              │  :3740              │
-              │  Next.js 16         │
-              └─────────────────────┘
+                docker exec / Docker API
                          │
            ┌─────────────┴─────────────┐
-           │                           │
-   docker exec / API           docker exec / API
-           │                           │
-    ┌──────┴──────┐           ┌────────┴────────┐
-    │ openclaw-core│           │  openclaw-atlas │
-    │ :3700-3708   │           │  :3731 → 3000   │
-    │ AGENT_ID=core│           │  AGENT_ID=atlas  │
-    └──────────────┘           └─────────────────┘
+    ┌──────┴──────┐             ┌──────┴──────┐
+    │ agent       │     …       │ agent       │
+    │ container   │             │ container   │
+    │ (OpenClaw)  │             │ (OpenClaw)  │
+    └─────────────┘             └─────────────┘
 ```
 
 ### Environment
 
-Rev4a reads the following environment variables. Set them in `/config` (UI) or directly in `.env`. See [.env.example](../.env.example) for the canonical, always-current list.
+Rev4a reads the following environment variables. Set them in `/config` (UI) or directly in `.env`, except the three read before `.env` is loaded — `REV4A_DATA_DIR`, `REV4A_DOCKER_WAIT_SECONDS` (both from the process environment: a shell export or a systemd `Environment=` line) and `REV4A_SKIP_POSTINSTALL_BUILD` (read by `npm install`). See [.env.example](../.env.example) for the canonical, always-current list.
 
 | Variable | Required | Description |
 |---|---|---|
@@ -67,8 +51,11 @@ Rev4a reads the following environment variables. Set them in `/config` (UI) or d
 | `REV4A_WORKSPACE_ROOT` | No | Filesystem path for the local file explorer |
 | `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_FORCE_INSECURE_COOKIE` | No | `1` allows a non-Secure session cookie — plain-HTTP deployments only (any other value, `true` included, does nothing) |
 | `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 |
+| `REV4A_DOCKER_WAIT_SECONDS` | No | How long `rev4a serve` waits for the Docker daemon at start-up (default `90`, capped at 600) |
+| `REV4A_DEV_ORIGINS` | No | Extra comma-separated hostnames or IPs allowed to reach `next dev`; no effect on a production build |
+| `REV4A_SKIP_POSTINSTALL_BUILD` | No | `1` in CI: `npm ci` then skips the post-install `next build` (the workflows build as a separate step). Any non-empty value skips it, `0` included — leave it unset to build |
 
 See [Alerts](#alerts-telegram) below for the Telegram alert variables.
 
@@ -91,10 +78,12 @@ to any specific reverse proxy.
 
 When environment variables are saved via the Config page (Save & Restart):
 
-1. Values are written to `.env` in the project root
-2. Secrets are loaded via `EnvironmentFile=` pointing to `.env` (chmod 600). Only non-secret vars (`NODE_ENV`, `PATH`, `REV4A_DB`) are in the unit file. Other vars (passwords, non-Rev4a keys) stay in `.env` for the application to read at runtime.
-3. `systemctl daemon-reload` is run
-4. The server restarts with the new environment
+1. Values are merged into the data directory's `.env` (`~/.config/rev4a/.env`; the
+   `.env` in the installation root is a link to it). An empty value removes the key.
+2. `sudo systemctl daemon-reload` is attempted; it is harmless where there is no systemd.
+3. **Save & Restart** runs `sudo systemctl restart rev4a.service`: the restart only works
+   when Rev4a runs as that systemd service. Started any other way, restart `rev4a serve`
+   yourself — `serve` reads `.env` at start-up, so nothing changes until then.
 
 ## Components
 
@@ -108,13 +97,15 @@ When environment variables are saved via the Config page (Save & Restart):
 
 | Route | Description |
 |---|---|
-| `/` | System overview — containers, resources, quick links |
+| `/` | System overview — health, sessions, the machine's CPU / RAM / disk (links to `/system`), cost, live feed |
 | `/agents` | Running agents (Docker containers with `AGENT_ID`), gateway token management, agent creation wizard, channel manager (Telegram pairing) |
 | `/containers` | All Docker containers on the host |
+| `/system` | The host machine: CPU, memory and swap, storage per filesystem — current values and 1h / 24h / 7d / 30d history (from `metrics.db`, sampled by the daemon every 30 s) |
 | `/wizard` | First-run setup wizard (Welcome → Providers → Agent → Ready) |
 | `/workspace` | File explorer with tree view + editor — VPS host or container workspaces |
 | `/lineage` | Agent lineage / orchestration tree |
 | `/memory` | Agent memory browser |
+| `/gateway` (model rows) | Each model has a **Details** (`⋯`) action opening a modal with what is known about it: description, price and the provider it comes from, architecture and parameters (mixture of experts, layers, hidden size, attention heads, vision encoder, precision, weights on disk), reasoning modes, capabilities, benchmarks with their sources, licence and popularity. The facts come from the model's card on Hugging Face and — for the vendor's own size claim and benchmarks — from hand-curated entries that always cite a source and a date; nothing is estimated. |
 | `/crons` | Scheduled cron jobs — auto-discovered from the host gateway and every running agent container (Docker containers with `AGENT_ID` label), on/off toggle, run history per job |
 | `/credentials` | Third-party tool credentials (GitHub, Trello, Vercel, Supabase, Notion) — SQLite vault, synced into agent containers as CLI config or, for the REST-only providers, as a config file the agent reads |
 | `/setup` | First-run password setup — sets `REV4A_PASSWORD` and the JWT secret before the dashboard is reachable |
@@ -159,7 +150,7 @@ REV4A_TELEGRAM_BOT_TOKEN=         # Telegram bot token
 REV4A_TELEGRAM_CHAT_ID=           # Telegram chat to notify
 REV4A_ALERT_COOLDOWN_MS=600000    # Minimum time between repeat alerts for the same condition
 REV4A_ALERT_STALE_SECONDS=120     # How long without a DB write before the system is considered stale
-REV4A_ALERT_SMOKE=false           # Set true to send a one-off test alert on startup
+REV4A_ALERT_SMOKE=false           # true enables GET /api/alerts/smoke (sends a test alert) in production
 ```
 
 **Behavior:**
@@ -220,14 +211,16 @@ echo 'vm.swappiness=10' > /etc/sysctl.d/99-rev4a-swap.conf
 
 ### Systemd environment override
 
-File: `/etc/systemd/system/rev4a-next.service` (EnvironmentFile)
+File: `/etc/systemd/system/rev4a.service.d/override.conf` — a drop-in for the single
+`rev4a.service` unit (`systemctl edit rev4a`). It is for the variables `.env` does not
+carry: `rev4a serve` reads `~/.config/rev4a/.env` itself, and a key present there wins
+over the same key set here — so secrets such as `REV4A_PASSWORD` or `REV4A_TOKEN`
+belong in `.env` (or `/config`), not in the drop-in. It is also the only place for the
+variables read before `.env` is loaded (`REV4A_DATA_DIR`, `REV4A_DOCKER_WAIT_SECONDS`).
 
 ```ini
 [Service]
-Environment=REV4A_PASSWORD=***
-Environment=REV4A_TOKEN=***
-Environment=REV4A_JWT_SECRET=***
-Environment=REV4A_DB=/path/to/rev4a/data/events.db
+Environment=REV4A_DOCKER_WAIT_SECONDS=180
 Environment=NODE_ENV=production
 Environment=NEXT_TELEMETRY_DISABLED=1
 ```
@@ -484,48 +477,6 @@ Only models whose provider has a key in `data/provider-keys.json` are synced.
 
 ---
 
-## Containers
-
-### openclaw-atlas
-
-| Property | Value |
-|---|---|
-| 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` |
-| Config mount | `/docker/atlas-data/openclaw-fixed.json → /root/.openclaw/openclaw.json` |
-| Auth mode | `token` |
-
-**Control UI:** `http://<vps-ip>:3731` — enter the gateway token to log in.
-Rev4a-generated direct links should use `#token=<gateway-token>` for automatic Control UI sign-in.
-
-### openclaw-core
-
-| Property | Value |
-|---|---|
-| Image | `ghcr.io/hostinger/hvps-openclaw:latest` |
-| Ports | `:3711-3719` (mapped to container `:3700-3708`) |
-| AGENT_ID | `core` |
-
-### openclaw-giacomo
-
-| Property | Value |
-|---|---|
-| Image | `ghcr.io/hostinger/hvps-openclaw:latest` |
-| Port | `:3730` |
-| AGENT_ID | `giacomo` |
-
-### Other containers
-
-| Name | Image | Notes |
-|---|---|---|
-| `hermes` | `nousresearch/hermes-agent:latest` | Hermes agent |
-| `hermes-dashboard` | `nousresearch/hermes-agent:latest` | Hermes dashboard |
-| `traefik-traefik-1` | `traefik:latest` | Reverse proxy |
-
----
-
 ## Key Gotchas
 
 1. **`auth.mode: "none"` + `0.0.0.0:3000`** → OpenClaw refuses to bind. Must be `auth.mode: "token"`.