@flame0510/project-aether 1.6.2 → 1.8.0

package/docs/dev/API-REFERENCE.md

@@ -1,6 +1,6 @@
 # Rev4a API Reference
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-26
 
 All routes are under `/api/`. Authentication is required on every endpoint
 unless otherwise noted.
@@ -249,7 +249,10 @@ Returns current provider configuration state.
 |---|---|
 | `summary=1` | Returns only `{ provider, label, configured }` per provider — no `models`, no `pricing`, no `apiKey`. The full response awaits live pricing from OpenRouter, a network round trip costing ~2.4s on a cold cache; callers that only need to know whether *any* provider is configured should use this. |
 
-**Response:**
+**Response:** each provider carries its models, and a model carries `params` (the total
+parameter count) when its Hugging Face card publishes one — the Gateway row shows it next
+to the price, and a model without a card simply omits it.
+
 ```json
 {
   "providers": [
@@ -1576,7 +1579,7 @@ nothing opens until an operator approves it.
 
 **Response:**
 ```json
-{ "url": "http://212.0.113.7:3710/#token=…", "loopbackHost": false }
+{ "url": "http://203.0.113.7:3710/#token=…", "loopbackHost": false }
 ```
 
 - `url` is the plain token link. The host is the one the request reached Rev4a on
@@ -1737,6 +1740,17 @@ in flight, so polling this endpoint does not re-query the registry every time.
 {
   "downloading": false,
   "downloadingVersion": null,
+  "downloadPercent": null,
+  "downloadMessage": null,
+  "canceled": false,
+  "lastResult": {
+    "version": "2026.9.3",
+    "result": "succeeded",
+    "source": "registry",
+    "message": "OpenClaw 2026.9.3 image downloaded",
+    "at": 1758700000000
+  },
+  "serverTime": 1758700004000,
   "exists": true,
   "needsUpdate": false,
   "localVersions": ["2026.9.3"],
@@ -1754,6 +1768,11 @@ in flight, so polling this endpoint does not re-query the registry every time.
 | `newestLocal` | The version new agents are created on |
 | `available` | Newest supported version on the registry that is not downloaded and is newer than `newestLocal`, or null |
 | `downloading` / `downloadingVersion` | A download running, and its version |
+| `downloadPercent` | Fraction of layers finished, from `docker pull`'s own per-layer lines (`getDownloadProgress()`), 0-99. Null until it can be computed: while the version is resolved, while docker is still listing the layers, on a pull where every layer is already present, and on the local-build fallback |
+| `downloadMessage` | The latest line of docker's output, verbatim (the banner shows it under the percent) |
+| `canceled` | Whether the last finished download ended as cancelled — derived from `lastResult`, so a cancel that arrived after the image was already tagged does not make a successful download read as cancelled |
+| `serverTime` | The server's clock (epoch ms) when it answered; clients age `lastResult.at` with it instead of their own clock |
+| `lastResult` | The last download's outcome (`getLastDownloadResult()`, `lib/buildAgentImage.ts`), or null before any download has run this process. `result` is `succeeded` / `failed` / `canceled`; `source` (`present` / `registry` / `build`) only on success. Kept regardless of whether a download is running now, so a client that missed the live transition — a page reload, a return from another screen — still sees it via `at` (epoch ms); overwritten by the next download, never cleared on its own. Same idea as `finished` in `lib/cold-backup.ts` |
 | `registryReachable` | The tag list could be read |
 
 ### `POST /api/agents/download-image`
@@ -1770,19 +1789,42 @@ newest supported version the registry publishes.
 { "started": true, "version": "2026.9.3" }
 ```
 
-**Errors:** `400` unsupported version; `409` a download is already in progress.
+**Errors:** `400` unsupported version; `409` a download is already in progress; `503`
+Docker is not available (refused here, before `202`, so the client gets the reason).
 
 The download is `lib/buildAgentImage.ts` → `downloadAgentImage({ version, onEvent, signal })`:
 - nothing to do when `openclaw-agent-base:<version>` is already here
 - `docker pull <registry>:<version>`, tag `openclaw-agent-base:<version>`, untag the
-  registry reference (`pullAgentImage()` in `lib/agent-images.ts`)
+  registry reference — also when the tag step fails or is cancelled, so no
+  `<registry>:<version>` reference is left behind (`pullAgentImage()` in `lib/agent-images.ts`)
 - when the pull fails and the repository Dockerfile's `ARG OPENCLAW_VERSION` is that
   version, `docker build --build-arg OPENCLAW_VERSION=<version>` instead; any other
   version fails
 - one download at a time (in-process lock, `getIsDownloading()` /
-  `getDownloadingVersion()`); output goes to `/tmp/rev4a-download-<timestamp>.log`
+  `getDownloadingVersion()`); docker's output also goes to
+  `/tmp/rev4a-download-<timestamp>.log` (mode 0600; logs older than 24 h are removed when a download ends) for diagnosis
+- progress: a layer counts as finished at `Pull complete` or `Already exists` (not at
+  `Download complete`, which still has the extraction ahead); the percent is withheld
+  until the first layer starts transferring — before that the layer list may be
+  incomplete — never goes down, and stays below 100: completion is reported by
+  `lastResult`, not by the percent
+
+### `DELETE /api/agents/download-image`
+Cancels the running download, if any (`cancelDownload()`): the `docker pull`/`docker build`
+process is killed, or never started when the cancel arrives before it (`runDocker` refuses
+an already-aborted signal, and the download checks after every wait). The rejected
+`downloadAgentImage()` promise carries a distinct `'canceled'` message, so the route's
+background `.catch` does not log it as a failure; `lastResult.result` becomes `canceled`.
 
-### `GET /api/agents-active`
+**Auth:** browser cookie or bearer token
+
+**Response (202):**
+```json
+{ "canceling": true }
+```
+
+**Errors:** `404` nothing is running — the download has not started yet, or has
+already ended.
 
 ### `GET /api/agents-active`
 Configured agents (from `openclaw.json`) enriched with recent session activity
@@ -1864,42 +1906,83 @@ Register a parent→child relationship between sessions.
 ## Metrics
 
 ### `GET /api/metrics`
-System metrics: latest snapshot + 24 h history + 24 h aggregates.
+Machine metrics of the host Rev4a runs on — CPU, RAM, swap, storage — read from
+`metrics.db` (written by the daemon every 30 s, see `docs/dev/DATABASE.md`): the latest
+sample, live host facts, and a bucketed history for one range. The System page
+(`/system`) and the dashboard's Machine card use it.
 
 **Auth:** Bearer or browser cookie
 
+**Query:** `range` — `1h` (default), `24h`, `7d` or `30d`; anything else answers `400`.
+The range is cut into buckets of `bucket_s` seconds (about 120 points, never shorter than
+60 s — two samples, so a timer that drifts a second leaves no false gaps), each with its
+average and peak: 60 s for `1h`, 720 s for `24h`, 5040 s for `7d`, 21 600 s for `30d`.
+
 **Response:**
 ```json
 {
-  "latest": { "ts": 1749201000000, "cpu_percent": 12.5, "ram_used_mb": 1820, "ram_total_mb": 4096, "disk_used_gb": 38.2, "disk_total_gb": 100.0, "load_avg_1m": 0.42 },
-  "history": [ ...up to 288 rows (24h at 5min intervals)... ],
-  "stats_24h": { "avg_cpu": 14.2, "max_cpu": 68.0, "avg_ram_mb": 1750 }
+  "latest": {
+    "ts": 1790419256, "age_s": 12, "cpu": 21.5,
+    "ram_used_mb": 4779, "ram_total_mb": 7851, "swap_used_mb": 2048, "swap_total_mb": 4096,
+    "load_avg_1m": 1.35, "load_avg_5m": 1.56, "load_avg_15m": 1.21,
+    "disks": [
+      { "mount": "/", "roles": ["root", "docker", "data"], "used_mb": 61440, "avail_mb": 38912, "total_mb": 102400, "percent": 61 }
+    ]
+  },
+  "host": { "hostname": "vps", "platform": "linux", "cores": 4, "uptime_s": 290000 },
+  "interval_s": 30,
+  "range": "1h",
+  "bucket_s": 60,
+  "history": [ { "ts": 1790419230, "cpu_avg": 21.5, "cpu_max": 29.1, "ram_avg": 60.9, "ram_max": 61.2 } ],
+  "disk_history": [ { "mount": "/", "points": [ { "ts": 1790419230, "percent": 61 } ] } ]
 }
 ```
 
+- `ts` values are in **seconds**; a `history` point's `ts` is the start of its bucket.
+  Buckets with no samples are absent (the daemon was not running), not zero.
+- `ram_used_mb` is total − available, the figure `free` shows (Linux `/proc/meminfo`); on
+  macOS active + wired + compressed pages. `swap_*` are `null` where there is no swap
+  figure. `ram_avg`/`ram_max` are percentages.
+- `disks`: each filesystem once — `/`, Docker's data root (`docker info`), and Rev4a's
+  data directory, merged when they are the same device; `roles` says which of the three
+  it is. `percent` is used / (used + available), as `df` computes it.
+- `latest` is `null` before the daemon's first sample (the database is created when the
+  daemon starts, the first sample about 5 s later), and when `metrics.db` has no tables. `age_s` older than 3 × `interval_s`
+  means the daemon is not sampling; the page says so.
+- `host` is read live by the API process, which runs on the same host.
+
 ---
 
 ## System Health
 
 ### `GET /api/system-health`
-Aggregated health checks with recommendations.
+Aggregated checks of the runtime, cron jobs and usage cost, with recommendations. It
+does not report CPU, RAM or disk (those are in `GET /api/metrics`). Its `runtime.heartbeat`
+check ("Daemon heartbeat") reads the age of the newest machine metrics sample in
+`metrics.db`: it shows the daemon is alive, not that the OpenClaw session poll ingests —
+the two run on separate timers. A `metrics.db` that cannot be read makes this one check
+say so; it does not fail the others.
 
-**Auth:** browser cookie
+**Auth:** browser cookie or bearer token
 
 **Response:**
 ```json
 {
   "health": "ok",
   "checks": [
-    { "name": "daemon", "status": "ok", "detail": "last poll 18s ago" },
-    { "name": "disk", "status": "warn", "detail": "82% used" }
+    { "id": "runtime.sessions", "label": "Runtime sessions", "health": "ok", "value": 1, "details": "last session activity 3m ago", "source": "runtime" }
+  ],
+  "recommendations": [
+    { "id": "cost.review-usage-based", "severity": "warning", "source": "cost", "title": "High usage-based cost", "details": "…", "actionHref": "/gateway", "dismissible": true, "createdAt": "2026-09-26T10:00:00.000Z" }
   ],
-  "recommendations": [ "Consider archiving old sessions to reduce disk usage." ],
-  "generatedAt": 1749201500000
+  "generatedAt": "2026-09-26T10:00:00.000Z"
 }
 ```
 
-`health` values: `"ok"` / `"warn"` / `"error"`
+Checks: `runtime.sessions`, `runtime.heartbeat`, `runtime.errors24h`,
+`cost.usageBasedToday`, `cron.jobs`. `health` (overall and per check) is `"ok"` /
+`"warning"` / `"error"`; a recommendation's `severity` is `"info"` / `"warning"` /
+`"critical"`. `generatedAt` and `createdAt` are ISO strings.
 
 ---
 
@@ -2619,7 +2702,7 @@ the process that spawned it, so that file is the only record of what happened.
 
 **Response:** `{ "success": true, "message": "...", "log": "update.log" }`
 
-The banner records what it asked for, polls `/api/version` until the installed version
+The banner records what it asked for, polls `/api/update-check` until the installed version
 moves (or two minutes pass), reloads, and on the next mount either confirms
 "Updated to vX" or reports that the update did not complete and points at the log.
 

package/docs/dev/DATABASE.md

@@ -1,14 +1,17 @@
 # Rev4a — Database Reference
 
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-26
 
-Rev4a uses a single SQLite file (`events.db`) in WAL mode.
+Rev4a keeps three SQLite files in WAL mode, by default all in the data directory's `data/`:
+`events.db` (sessions and events, below), `metrics.db` (machine metrics, see
+[Metrics Database](#metrics-database-metricsdb)) and `credentials.db` (see
+[Credentials Database](#credentials-database-credentialsdb)).
 
 ## Location
 
 | Environment | Path |
 |---|---|
-| VPS (default) | `/path/to/rev4a/data/events.db` |
+| Default | `~/.config/rev4a/data/events.db` (`$REV4A_DATA_DIR/data/events.db`) |
 | Custom | Set `REV4A_DB` env var |
 
 ## WAL Mode
@@ -19,8 +22,9 @@ PRAGMA synchronous = NORMAL;
 ```
 
 - The daemon writes; the Next.js API routes open read-only connections
-- `PRAGMA wal_checkpoint(PASSIVE)` runs after each daemon poll cycle
-- WAL files: `events.db-shm`, `events.db-wal` — do not delete while daemon is running
+- `events.db`: `PRAGMA wal_checkpoint(PASSIVE)` after each daemon poll cycle, `FULL` every 10
+- `metrics.db`: SQLite's automatic checkpoint (every 1000 pages) — no explicit one
+- WAL files (`*.db-shm`, `*.db-wal`) — do not delete while the daemon is running
 
 ## Tables
 
@@ -88,24 +92,9 @@ CREATE TABLE cost_override (
 
 When a `cost_override` row exists for the current month, the UI displays the override value instead of the computed sum.
 
-### `system_metrics` — infrastructure metrics
-
-```sql
-CREATE TABLE system_metrics (
-  id           INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts           INTEGER NOT NULL,
-  cpu_percent  REAL,
-  ram_used_mb  INTEGER,
-  ram_total_mb INTEGER,
-  disk_used_gb REAL,
-  disk_total_gb REAL,
-  load_avg_1m  REAL
-);
-
-CREATE INDEX idx_metrics_ts ON system_metrics(ts);
-```
-
-Rows older than 24 h are pruned automatically by the daemon.
+The daemon also writes a `system_anomaly` event (session `system`) when the machine
+crosses a threshold — see [Metrics Database](#metrics-database-metricsdb). No feature
+consumes those events yet; they only pass through the generic event feeds.
 
 ### `agent_upgrades` — agent updates and rollbacks
 
@@ -235,14 +224,76 @@ SELECT * FROM tree;
 ## Backup
 
 ```bash
-# Manual snapshot
-sqlite3 events.db ".backup events.db.bak-$(date +%s)"
+# Everything Rev4a owns: the whole data directory (.env, data/, shared/)
+bash scripts/backup.sh                    # -> ~/rev4a-backups/rev4a-backup-<UTC time>.tar.gz
+bash scripts/restore.sh ~/rev4a-backups/rev4a-backup-<UTC time>.tar.gz
+
+# One database only, consistent while Rev4a runs (needs the sqlite3 CLI)
+sqlite3 ~/.config/rev4a/data/events.db ".backup events-$(date +%s).db"
+```
+
+`backup.sh` archives the Rev4a data directory (`$REV4A_DATA_DIR`, default
+`~/.config/rev4a`) whole, so a new file there is included without changing the script.
+The archive (mode 0600, directory 0700) holds every secret in plain text; keep a copy
+off the machine. `restore.sh` refuses an archive with links in it and a running
+`rev4a serve`, archives the current state into `~/rev4a-backups` first, stops
+`rev4a.service` when it runs, and replaces the data directory as a whole (a leftover
+SQLite `-wal` cannot mix into the restored state), then resets the permissions. Agent volumes are not included —
+the dashboard's cold backups cover them.
+
+## Metrics Database (`metrics.db`)
+
+Machine metrics of the host — CPU, RAM, swap, storage — kept apart from `events.db`, so
+the event log holds sessions and events only and the history can be dropped on its own.
+
+**Location:** `data/metrics.db`, next to `events.db` (it follows `REV4A_DB`'s directory; both
+the daemon and the API resolve the data directory the same way, `REV4A_DATA_DIR` included).
+**Created by** the daemon when it starts (`CREATE TABLE IF NOT EXISTS`), which is also its
+only writer; `GET /api/metrics` and `GET /api/system-health` read it
+(`lib/metrics-db.ts`). Until the daemon has run once the file does not exist, and the
+API answers with `latest: null`. If the daemon cannot open it (corrupt, unwritable), it
+logs `[METRICS] disabled` and keeps polling sessions without sampling.
+**Sampling:** the first sample about 5 s after the daemon starts, then every 30 s, on a timer
+of its own — independent of the OpenClaw session poll.
+**Retention:** 30 days, pruned at every sample: ~86 400 `system_metrics` rows, and one
+`system_disks` row per filesystem per sample (up to ~259 200 for three).
+
+```sql
+CREATE TABLE system_metrics (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts            INTEGER NOT NULL,   -- Unix seconds
+  cpu_percent   REAL,               -- all cores, busy share since the previous sample
+  ram_used_mb   INTEGER,            -- total − available (Linux), as `free` shows it
+  ram_total_mb  INTEGER,
+  swap_used_mb  INTEGER,            -- NULL where there is no swap figure
+  swap_total_mb INTEGER,
+  load_avg_1m   REAL,
+  load_avg_5m   REAL,
+  load_avg_15m  REAL
+);
+CREATE INDEX idx_metrics_ts ON system_metrics(ts);
 
-# Automated (via backup.sh in repo root)
-bash /data/.openclaw/workspace-ops/rev4a-next-ts/backup.sh
+-- One row per filesystem per sample: `/`, Docker's data root and Rev4a's data directory,
+-- each device once; roles lists which of them it is (e.g. 'root,docker,data').
+CREATE TABLE system_disks (
+  ts       INTEGER NOT NULL,        -- the same ts as the system_metrics row
+  mount    TEXT NOT NULL,
+  roles    TEXT,
+  used_mb  INTEGER,                 -- blocks − free
+  avail_mb INTEGER,                 -- what a normal user can still write
+  total_mb INTEGER
+);
+CREATE INDEX idx_disks_ts ON system_disks(ts);
+CREATE INDEX idx_disks_mount_ts ON system_disks(mount, ts);
 ```
 
-Backups are stored in `backups/` inside the repo directory.
+**Anomalies** go to `events.db` as `system_anomaly` events: CPU above 85 % or RAM above
+90 % on two consecutive samples (at most once per 5 minutes per metric), and a filesystem
+at 90 % or more once when it reaches the threshold, with no cooldown (again only after it
+has dropped back under, or once after each daemon start: the state is kept in memory).
+
+Installs from before this database may still have a `system_metrics` table in
+`events.db`: nothing reads or writes it any more, and it can be dropped.
 
 ## Credentials Database (`credentials.db`)
 

package/docs/dev/SESSION-MAINTENANCE-PLAN.md

@@ -597,11 +597,11 @@ POST /api/sessions/maintenance/cleanup
 
 ## 9. References
 
-- [Session maintenance](/concepts/session) — OpenClaw docs
-- [Session management deep dive](/reference/session-management-compaction) — store schema + maintenance rules
-- [Compaction](/concepts/compaction) — auto + manual compaction
-- [Session pruning](/concepts/session-pruning) — tool-result trimming
-- [Transcript hygiene](/reference/transcript-hygiene) — provider-specific fixups
-- [Cron jobs](/automation/cron-jobs) — cron.sessionRetention + run log config
+- [Session maintenance](https://docs.openclaw.ai/concepts/session) — OpenClaw docs
+- [Session management deep dive](https://docs.openclaw.ai/reference/session-management-compaction) — store schema + maintenance rules
+- [Compaction](https://docs.openclaw.ai/concepts/compaction) — auto + manual compaction
+- [Session pruning](https://docs.openclaw.ai/concepts/session-pruning) — tool-result trimming
+- [Transcript hygiene](https://docs.openclaw.ai/reference/transcript-hygiene) — provider-specific fixups
+- [Cron jobs](https://docs.openclaw.ai/automation/cron-jobs) — cron.sessionRetention + run log config
 - [Rev4a API Reference](API-REFERENCE.md)
 - [Rev4a Frontend Architecture](../FRONTEND-ARCHITECTURE.md)

package/docs/rag/DATA-FRESHNESS.md

@@ -1,6 +1,6 @@
 # Data Freshness in Rev4a
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-26
 
 Understanding how current the data in Rev4a is — and what is truly real-time vs. periodically updated.
 
@@ -14,9 +14,8 @@ The daemon polls `openclaw sessions --json --all-agents` on a fixed 30-second
 timer. Session statuses, token counts, and costs are therefore up to 30 seconds
 behind reality.
 
-The code declares a shorter 15-second interval for when a session is `working`,
-but nothing uses it — the timer is always 30 seconds. Do not tell a user the
-dashboard speeds up during active work.
+The interval is fixed: it does not speed up while a session is `working`. Do not tell
+a user the dashboard refreshes faster during active work.
 
 **What this means for PULSE:** if you ask "is Argus working right now?", the
 answer reflects data that is up to 30 seconds old.
@@ -29,26 +28,31 @@ answer reflects data that is up to 30 seconds old.
 
 The `/api/stream` endpoint pushes updates to the dashboard every 5 seconds. It
 sends exactly three things:
-- New events (spawn, complete, error, tool_call)
+- New events (spawn, complete, fail, spawn_timeout, system_anomaly)
 - The session list
 - Today's cost total
 
 Lineage is **not** pushed over the stream; the Lineage page fetches it itself.
 
 The event feed is as close to real-time as Rev4a gets. However, events are
-generated by the daemon's poll cycle, so an event that just happened may take up
+generated by the daemon every 30 seconds — session events by its poll of OpenClaw,
+system anomalies by its machine sampling — so an event that just happened may take up
 to 30 seconds to appear, plus up to 5 more to reach the browser.
 
 ---
 
 ## System metrics (CPU, RAM, disk)
 
-**Update frequency:** every daemon poll cycle (30 seconds)
+**Update frequency:** every 30 seconds, sampled by the Rev4a daemon on its own timer
+(it does not depend on OpenClaw being installed on the host). The System page refreshes
+every 30 seconds too, so a figure is at most about a minute old.
 
-**Retention:** 30 days (older rows are pruned automatically each cycle)
+**Retention:** 30 days, in their own database (`metrics.db`).
 
-These metrics are collected and stored, and served by `GET /api/metrics`. They
-are **not** shown on the dashboard — see the System Health note below.
+Shown on the **System** page (`/system`) — current CPU, memory, swap and storage, and
+their history over 1 hour, 24 hours, 7 days or 30 days — and, as three figures, on the
+Dashboard's Machine card. If the newest sample is older than 90 seconds the page says
+the collector is not running instead of showing stale numbers as current.
 
 ---
 
@@ -96,11 +100,22 @@ at most every 10 minutes, so a newly published version can take that long to app
 The banner polls the endpoint every 2 seconds for as long as the page is open, not only
 while something is running.
 
-The operation the banner triggers is a **`docker pull`**, not a build. While it
-runs the banner shows an indeterminate animated bar: there is no percentage, no
-byte count, and no log output in the UI. A log is written server-side to
+The operation the banner triggers is a **`docker pull`**, not a build (unless the
+pull fails and this repository's own Dockerfile builds that exact version, a
+development fallback). While it runs the banner shows the percent of layers
+finished and the latest line of docker's output; the bar is indeterminate until a
+percent can be computed (while the version is resolved and the layers are listed,
+and during the local-build fallback). The percent never goes down and stops at 99:
+completion is announced by the outcome, not by 100%. A **Cancel** button, offered
+once the download is running, stops it — the `docker pull`/`docker build` process is
+killed, or never started if the cancel came first. A log is written server-side to
 `/tmp/rev4a-download-<timestamp>.log`, but nothing in the dashboard reads it.
 
+The outcome comes from the server's own record of the last download: "ready" and
+"canceled" show for 3 seconds, a failure stays until the next action. An outcome
+that happened while the Agents page was closed or reloading is still reported if it
+is less than 30 seconds old.
+
 ---
 
 ## Memory / context files
@@ -127,8 +142,9 @@ The tracked set is `USER.md`, `MEMORY.md`, `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md
 ## How to check if data is fresh
 
 System health is a card on the **Dashboard**, not a page of its own. Its checks
-cover session runtime, ingestion freshness, errors in the last 24 hours, today's
-usage-based cost, and cron jobs. It reports no CPU, RAM, or disk figures.
+cover session runtime, the daemon heartbeat, errors in the last 24 hours, today's
+usage-based cost, and cron jobs. CPU, RAM and disk are on the System page (`/system`)
+and the Dashboard's Machine card instead.
 
 To check directly on the server:
 ```bash

package/docs/rag/GLOSSARY.md

@@ -1,6 +1,6 @@
 # Rev4a Glossary
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-26
 
 Terms you'll encounter while using the Rev4a dashboard.
 
@@ -43,10 +43,10 @@ A third-party service token (GitHub PAT, Trello API key, Vercel token, Supabase
 A scheduled task that runs an agent automatically at a fixed time (e.g. every night at 3:15 AM). Configured with standard cron syntax. Jobs can be enabled/disabled per entry.
 
 ## Dashboard
-The main page of Rev4a (`/`). Shows live sessions, cost summary, health cards for Rev4a's runtime, cron and lineage, and a real-time event feed. It shows no CPU, RAM, disk or load average, and there is no setup banner: an incomplete wizard redirects to `/wizard`.
+The main page of Rev4a (`/`). Shows live sessions, cost summary, health cards for Rev4a's runtime, cron and lineage, and a real-time event feed. Its Machine card shows the server's CPU, RAM and fullest disk right now, with a link to the System page. There is no setup banner: an incomplete wizard redirects to `/wizard`.
 
 ## Event
-A lifecycle occurrence for a session: spawned, completed, errored, or a tool call made. Events appear in the live feed on the Dashboard and are pushed via SSE every 5 seconds.
+A lifecycle occurrence for a session: spawned, completed, failed, or missing too long (spawn timeout); the daemon also records system anomalies (high CPU or RAM) as events. Events appear in the live feed on the Dashboard and are pushed via SSE every 5 seconds.
 
 ## Gateway
 The routing layer that connects agents to AI providers. The Gateway page manages provider API keys and the model catalogue, and pushes that catalogue to every agent. Which model a given agent runs is set elsewhere, in the Model section of that agent's detail panel.
@@ -130,7 +130,10 @@ Rev4a's store for third-party service tokens (GitHub, Trello, Vercel, Supabase,
 ## Workspace
 The directory where an agent's operational files live (config, memory files, skills, plugins, scripts). The Workspace page lets you browse, view, and edit files across the host workspace, which appears as `Local`, and all agent containers.
 
+## System (page)
+The page with the machine Rev4a runs on: CPU (with cores and load), memory and swap, and each disk's used and free space, now and over 1 hour, 24 hours, 7 days or 30 days. A bar turns yellow and then red when it reaches a threshold (CPU and memory 85 % / 95 %, disk 80 % / 90 %), and the level is written next to it.
+
 ## System Health
-A card on the Dashboard reporting whether Rev4a itself is working, not the hardware it runs on. `/api/system-health` returns checks for session runtime, feed ingestion freshness, errors in the last 24 hours, today's usage-based cost, and cron jobs, each with a health of `ok`, `warning` or `error`, plus a list of recommendations.
+A card on the Dashboard reporting whether Rev4a itself is working, not the hardware it runs on. `/api/system-health` returns checks for session runtime, the daemon heartbeat (how old its latest machine sample is), errors in the last 24 hours, today's usage-based cost, and cron jobs, each with a health of `ok`, `warning` or `error`, plus a list of recommendations.
 
-It reports no CPU, RAM, disk or load average. Those metrics are collected by the daemon and stored for 30 days, and are served by `/api/metrics`, but no page displays them.
+It reports no CPU, RAM, disk or load average: those are on the System page (`/system`), sampled every 30 seconds by the daemon and kept for 30 days.

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,6 +1,6 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-22
+> **Last updated:** 2026-09-26
 
 Rev4a is the control panel for your AI agent infrastructure. It shows you everything your agents are doing, how much they cost, and whether the system is healthy — all in one dashboard.
 
@@ -9,7 +9,7 @@ Rev4a is the control panel for your AI agent infrastructure. It shows you everyt
 ### Dashboard (`/`)
 The main page. See live sessions (who's working right now), cost summary, an overall health indicator, and a real-time event feed. Click any session row to open the Session Drawer and see every tool call the agent made.
 
-The health cards cover Rev4a's own runtime, cron and watchdog, and lineage. They do **not** show CPU, RAM, disk, or load average: those metrics are collected and stored, but no page displays them. There is no wizard banner on the dashboard; an incomplete setup redirects to `/wizard` instead.
+The health cards cover Rev4a's own runtime, cron and watchdog, and lineage. The Machine card shows the server's CPU, RAM and fullest disk right now, coloured when it reaches a threshold, and links to the System page for details. There is no wizard banner on the dashboard; an incomplete setup redirects to `/wizard` instead.
 
 ### First-run wizard (`/wizard`)
 First-run setup wizard that guides new users through configuration. Four steps:
@@ -58,10 +58,14 @@ went missing. Afterwards **Roll back to <version>** puts back the backup taken j
 the update, on the old version; anything the agent did after the update is lost. The agent
 must be running to start an update.
 
-That button runs a `docker pull` from the registry. It is a download, not a build.
-While it runs the banner shows an indeterminate animated bar with no percentage and
-no log output; there is no modal, no "View Progress", no "Run in Background", and
-no way to abort from the UI. Status is polled every 2 seconds.
+The agent base image banner above (not this update — an agent's own **Update to
+<version>** recreates it on an image already downloaded) is the one running the
+`docker pull`. While it runs the banner shows the percent of layers finished and the
+latest line of docker's output; a **Cancel** button, offered once the download is
+running, stops it. There is no modal, no "View Progress", no "Run in Background". The
+outcome ("ready" and "canceled" for 3 seconds, a failure until the next action) is
+reported even when it happened while the Agents page was closed or reloading, if it is
+less than 30 seconds old. Status is polled every 2 seconds.
 
 ### Create Agent (`/agents/create`)
 Wizard to spin up a new agent. Steps: choose a template (Prometheus, Argus, Atlas, etc.), name your agent, pick a model, set an optional port range (default: auto-assigned 10-port block, e.g. 3700-3709). The agent is created as a Docker container with a persistent volume — all config, workspace files, and credentials survive container restarts.
@@ -70,13 +74,16 @@ Wizard to spin up a new agent. Steps: choose a template (Prometheus, Argus, Atla
 Interactive graph showing session family trees — which agent spawned which child agent, across configurable time periods: 1d, 3d, 7d, 15d, 30d, and all. Click any node to inspect. Includes a live feed side panel.
 
 ### Gateway (`/gateway`)
-Connects agents to AI providers. Add and remove provider API keys, enable or disable individual models in the catalogue read from `models.config.json`, and push the resulting model list to every agent container. It does not assign models to agents: choosing which model an agent runs is done per agent, in the Model section of the agent's detail panel on the Agents page.
+Connects agents to AI providers. Add and remove provider API keys, enable or disable individual models in the catalogue read from `models.config.json`, and push the resulting model list to every agent container. It does not assign models to agents: choosing which model an agent runs is done per agent, in the Model section of the agent's detail panel on the Agents page. Every model row has a **Details** button: the modal shows the model's description, price and provider, its architecture and parameter count when the weights are public, reasoning modes, capabilities, benchmarks with sources, licence and how much disk the weights take — the numbers come from the model card on Hugging Face and from curated entries that cite a source, never from estimates.
 
 ### Containers (`/containers`)
 Full list of all Docker containers on the server, including stopped ones. Each row shows name, status, image, IP, ports, and an agent pill where applicable. Click "Terminal" to open an interactive shell into that container.
 
 The page shows no CPU or memory figures and has no start, stop, or restart buttons: it is read-only apart from the terminal link. Container lifecycle is managed from the Agents page.
 
+### System (`/system`)
+The machine Rev4a runs on. Three cards — CPU (percent, cores, load average), memory (used, available, swap) and storage (each disk with its used and free space, and whether it is the system disk, where Docker keeps agents, or where Rev4a keeps its data) — then charts of CPU, memory and each disk over 1 hour, 24 hours, 7 days or 30 days (for CPU and memory the average line with the peak shaded). Hover a chart (or focus it and use the arrow keys) to read a point; each chart has a Table view. Bars turn yellow and red when they reach their thresholds. Figures refresh every 30 seconds; history is kept 30 days.
+
 ### Container Terminal (`/containers/terminal/[id]`)
 Live web terminal into a Docker container. Run commands, inspect files, debug issues — like SSH but in the browser.
 

package/docs/rag/WHAT-I-CAN-ANSWER.md

@@ -1,6 +1,6 @@
 # What PULSE Can Answer
 
-> **Last updated:** 2026-09-22
+> **Last updated:** 2026-09-26
 
 PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
 
@@ -10,6 +10,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 
 - "Where do I find the agents page?"
 - "How do I get to the container list?"
+- "Where do I see CPU, RAM or disk usage of the server?" — The System page (`/system`), and the Machine card on the Dashboard.
 - "Where can I see the first-run wizard?"
 - "Is there a page for cron jobs?"
 - "Where can I see my AI providers?" — The Gateway page (`/gateway`) shows providers and the model catalogue. Which model an agent runs is on the Agents page, in that agent's detail panel.
@@ -95,13 +96,13 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "Why are costs missing for some sessions?"
 - "Why can't I connect to the container terminal?"
 - "Why is the gateway sync not working?"
-- "Why am I seeing a setup banner?"
 - "How do I check if the daemon is running?"
 - "Why are credentials not showing in my agent?"
 - "What does the yellow diamond next to an agent mean?"
 - "Why is the agent base image banner showing?"
 - "How do I fix 'image is outdated'?"
-- "How do agent image updates work?" — The banner on the Agents page runs a `docker pull`. It is a download, not a build: there is no modal, no live log, and no way to abort from the UI.
+- "How do agent image updates work?" — The banner on the Agents page runs a `docker pull` and shows the percent of layers finished and docker's latest output line, with a Cancel button once the download is running; there is no modal or live log. The outcome is reported even if it happened while you were away, as long as it is less than 30 seconds old.
+- "How big is model X / how many parameters does it have?" — Open the **Details** modal from the model row on the Gateway page: parameter counts, architecture and benchmark numbers come from the model's card on Hugging Face, with the vendor's own claim where it makes one. Models whose weights are not published (OpenAI, Anthropic, Google, Qwen's Plus/Max line) show no parameter count: the size is not public and Rev4a does not estimate it.
 - "How do I update Rev4a itself?" — The "Update available" banner starts `rev4a update` in the background (the same command as from a shell). It installs the new version and Rev4a restarts itself, so the dashboard drops for a short while; the banner waits for the new version and then confirms it, or says the update did not complete. The update's output is written to `update.log` in the Rev4a data directory (`~/.config/rev4a/data/update.log`) — the only place that says why an update failed.
 - "Why is my Telegram bot not connecting?"
 - "Why can't I approve a pairing code?"