@flame0510/project-aether 1.6.1 → 1.7.0

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
 
@@ -115,6 +104,7 @@ When environment variables are saved via the Config page (Save & Restart):
 | `/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 +149,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 +210,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 +476,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"`.

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,54 @@ Register a parent→child relationship between sessions.
 ## Metrics
 
 ### `GET /api/metrics`
-System metrics: latest snapshot + 24 h history + 24 h aggregates.
+System metrics from the daemon's `system_metrics` table: the latest sample, the most
+recent samples, and 24 h CPU aggregates.
 
 **Auth:** Bearer or browser cookie
 
+**Query:** `limit` — how many `history` rows (default 60, max 1000): the most recent ones, returned oldest first.
+
 **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": { "cpu": 12.5, "ram_used_mb": 1820, "ram_total_mb": 4096, "disk_used_gb": 38, "disk_total_gb": 100, "load_avg": 0.42, "ts": 1749201000 },
+  "history": [ { "cpu": 12.5, "ram_used_mb": 1820, "ram_total_mb": 4096, "ts": 1749201000 } ],
+  "stats_24h": { "cpu_avg": 14, "cpu_max": 68 }
 }
 ```
 
+`ts` is in **seconds**. The daemon records one sample per completed poll (every 30 s) and keeps
+30 days. A host without the OpenClaw CLI records none: the daemon stays idle there,
+and `latest` is `null`.
+
 ---
 
 ## 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, disk or the Docker daemon (those are in `GET /api/metrics`).
 
-**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.ingestion`, `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 +2673,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,6 +1,6 @@
 # Rev4a — Database Reference
 
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-26
 
 Rev4a uses a single SQLite file (`events.db`) in WAL mode.
 
@@ -105,7 +105,10 @@ CREATE TABLE system_metrics (
 CREATE INDEX idx_metrics_ts ON system_metrics(ts);
 ```
 
-Rows older than 24 h are pruned automatically by the daemon.
+Rows older than 30 days are pruned automatically by the daemon (one row per completed 30 s poll;
+none on a host without the OpenClaw CLI, where the daemon stays idle).
+No feature consumes the `system_anomaly` events the daemon writes to `events` yet; they
+only pass through the generic event feeds.
 
 ### `agent_upgrades` — agent updates and rollbacks
 
@@ -235,14 +238,22 @@ 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
 
-# Automated (via backup.sh in repo root)
-bash /data/.openclaw/workspace-ops/rev4a-next-ts/backup.sh
+# One database only, consistent while Rev4a runs (needs the sqlite3 CLI)
+sqlite3 ~/.config/rev4a/data/events.db ".backup events-$(date +%s).db"
 ```
 
-Backups are stored in `backups/` inside the repo directory.
+`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.
 
 ## Credentials Database (`credentials.db`)
 

package/docs/dev/GATEWAY.md

@@ -206,6 +206,29 @@ block, and every number there carries its source:
 No generated field ever replaces a curated one silently: prices are separate files, and the
 modal shows the generated part's date (`asOf`).
 
+### Curating an `info` block
+
+Nothing here is estimated, and every number carries its source and date. The workflow has
+three steps, one command each:
+
+```bash
+npm run info:suggest -- <model id> …   # candidate facts from the model card (read-only)
+# the maintainer, or a worker agent asked to follow the same contract, proposes the block
+npm run info:verify  -- proposals.json   # the gate: refuses what the card does not support
+```
+
+- `scripts/model-info-suggest.mjs` prints the card's size sentences, its benchmark tables
+  (headers included) and its doc links, so the reading is a lookup rather than a hunt.
+- `scripts/model-info-verify.mjs` checks a proposal against the card: `evidence` present,
+  every number in `params` in the card text, every benchmark value in a row named after it
+  **under the column that names this model** (never a sibling variant), and `docUrl` when
+  asked with `--check-links`. It exits non-zero on a rejected proposal.
+- The proposal contract is what makes this safe: one JSON object per model with an
+  `evidence` entry per field, the verbatim line, the column used and the card's own date.
+  A worker that skips the evidence — or takes a value from a variant's column — is caught
+  here, not in the catalogue. Benchmarks that a card states only for a sibling
+  (`-Max`, `-Base`, `-HighSpeed`) are dropped.
+
 ---
 
 ## Per-agent model assignment

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,7 +28,7 @@ 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
 
@@ -43,7 +42,8 @@ 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 completed daemon poll cycle (30 seconds). A host without the
+OpenClaw CLI records no metrics at all: the daemon stays idle there.
 
 **Retention:** 30 days (older rows are pruned automatically each cycle)
 
@@ -96,11 +96,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

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.
 
@@ -46,7 +46,7 @@ A scheduled task that runs an agent automatically at a fixed time (e.g. every ni
 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`.
 
 ## 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.

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.
 
@@ -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,7 +74,7 @@ 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.

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.
 
@@ -95,13 +95,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?"