@flame0510/project-aether 1.10.0 → 1.11.1

package/docs/dev/API-REFERENCE.md

@@ -1,6 +1,6 @@
 # Rev4a API Reference
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-02
 
 All routes are under `/api/`. Authentication is required on every endpoint
 unless otherwise noted.
@@ -251,10 +251,15 @@ Returns current provider configuration state.
 
 **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.
+to the price, and a model without a card simply omits it. A model priced by time of day
+carries `band` (`"peak"` or `"off-peak"`, what the vendor bills right now — the Gateway row
+shows it as a chip) and its `pricing` is the rate in force at answer time, not the peak
+list price: it flips with the band, like the agents' synced prices. The top level carries
+`nextPriceChangeMs`, when the band flips next, so an open page can refresh the chips.
 
 ```json
 {
+  "nextPriceChangeMs": 1790532000000,
   "providers": [
     {
       "provider": "deepseek",
@@ -263,8 +268,8 @@ to the price, and a model without a card simply omits it.
       "baseUrl": "https://api.deepseek.com",
       "docsUrl": "https://platform.deepseek.com/api_keys",
       "models": [
-        { "id": "deepseek/deepseek-flash", "name": "DeepSeek Flash", "enabled": true },
-        { "id": "deepseek/deepseek-v4-pro", "name": "DeepSeek V4 Pro", "enabled": true }
+        { "id": "deepseek/deepseek-flash", "name": "DeepSeek Flash", "enabled": true, "band": "off-peak", "pricing": { "input": 0.15, "output": 0.6, "cacheRead": 0.003, "cacheWrite": 0.15 } },
+        { "id": "deepseek/deepseek-v4-pro", "name": "DeepSeek V4 Pro", "enabled": true, "band": "off-peak", "pricing": { "input": 0.66, "output": 1.98, "cacheRead": 0.022, "cacheWrite": 0.66 } }
       ]
     }
   ]
@@ -320,8 +325,8 @@ Rev4a Provider Gateway — proxy chat completions to the correct upstream.
 ---
 
 ### `GET /api/models/details?id=<model id>`
-Everything the details modal shows for one model, and nothing more: fields the sources do
-not have are **absent**, never `null` and never a guess.
+Everything the details modal shows for one model, and nothing more: unknown optional
+facts are omitted; `price` and `info` can be `null` when absent.
 
 **Auth:** browser cookie or bearer token
 
@@ -330,7 +335,7 @@ not have are **absent**, never `null` and never a guess.
 {
   "id": "glm/glm-5.3-flash", "name": "GLM-5.3 Flash", "provider": "glm",
   "modality": "text+image+video->text", "enabled": false, "deprecated": false,
-  "price": { "input": 0.15, "output": 0.5, "source": "vendor" },
+  "price": { "input": 0.15, "output": 0.5, "source": "vendor", "scheduled": false },
   "details": { "description": "…", "created": "2026-08-26", "context": 1310720,
                "providerContext": 1048576, "maxOutput": 943718,
                "reasoning": { "mandatory": true, "default_effort": "max", "supported_efforts": ["max","high","low"] },
@@ -338,13 +343,15 @@ not have are **absent**, never `null` and never a guess.
                "benchmarks": { "design_arena": [ … ], "artificial_analysis": { … } },
                "huggingFaceId": "zai-org/GLM-5.3-Flash", "url": "https://openrouter.ai/…" },
   "info": null,
-  "asOf": "2026-09-23T14:02:40.271Z",
+  "asOf": "2026-10-02T10:46:53.452Z",
   "detailsSource": "openrouter"
 }
 ```
 
 `price.source` is `openrouter` for an `openrouter/*` entry and `vendor` for a direct one,
-which keeps prices honest: the refresh script never writes a vendor price. `details` comes
+which keeps prices honest: the refresh script never writes a vendor price. `price.scheduled`
+identifies a time-of-day list price; the Gateway row separately shows the rate in force.
+`details` comes
 from the generated `model-details.json` (`npm run refresh:pricing`, see
 `docs/dev/GATEWAY.md`), `info` from the catalogue's hand-written block, and `asOf` is when
 the generated part was produced. An id the catalogue does not carry answers `404`.
@@ -652,11 +659,14 @@ One agent's spend for its panel, from `costs.db`.
 
 **Auth:** browser cookie or Bearer
 
-**Response:** `{ "available": true, "intervalS": 300, "today": 0.011, "week": 0.019,
+**Response:** `{ "available": true, "intervalS": 300, "pricing": { "vendor": "DeepSeek", "band": "off-peak", "nextChange": 1790532000000, "source": "https://api-docs.deepseek.com/quick_start/pricing" }, "today": 0.011, "week": 0.019,
 "month": 0.022, "tokensMonth": 2409574, "topModel": { "model": "deepseek/deepseek-flash",
 "cost": 0.022 }, "unpricedMonth": 81, "collectedAt": 1790529516737, "error": null }` —
-UTC days (today, last 7, last 30); `collectedAt`/`error` from the agent's last read.
-`{ "available": false, "intervalS": 300 }` before `costs.db` exists.
+UTC days (today, last 7, last 30); `pricing` is the band billed right now, the same object
+the Costs page header shows (`null` when no scheduled model is on offer); `collectedAt`/`error`
+from the agent's last read. Before `costs.db` exists, the response is
+`{ "available": false, "intervalS": 300, "pricing": null }` (or the current pricing
+object when a scheduled model is on offer).
 
 **Errors:** `400` for an invalid container name; `500` when `costs.db` cannot be read.
 
@@ -2045,6 +2055,81 @@ average and peak: 60 s for `1h`, 720 s for `24h`, 5040 s for `7d`, 21 600 s for
   means the daemon is not sampling; the page says so.
 - `host` is read live by the API process, which runs on the same host.
 
+### `GET /api/metrics/containers?range=1h|24h|7d|30d`
+What every container consumes — now, and as an average and peak over the range — plus what is
+not a container and the disk Docker holds. From `metrics.db` (the daemon samples every 60 s,
+see `docs/dev/DATABASE.md`). Default range `1h`.
+
+**Auth:** browser cookie or Bearer
+
+**Response:**
+```json
+{
+  "available": true, "range": "1h", "interval_s": 60,
+  "host": { "ncpu": 10, "mem_total_mb": 7837 },
+  "sampled_at": 1790789760, "age_s": 10,
+  "containers": [
+    { "container": "agent_9253eee3", "name": "test", "agent_id": "agent_9253eee3", "is_agent": true,
+      "running": true, "last_seen": 1790789760,
+      "now": { "cpu_cores": 0.022, "cpu_percent": 0.22, "mem_mb": 668, "mem_percent": 8.5, "pids": 12,
+               "net_rx_bps": 0, "net_tx_bps": 0, "blk_read_bps": 0, "blk_write_bps": 0 },
+      "range": { "cpu_avg_percent": 1.02, "cpu_max_percent": 2.17, "mem_avg_mb": 679, "mem_max_mb": 701 },
+      "storage": { "volume_mb": 1544, "layer_mb": 10, "total_mb": 1554, "ts": 1790789645 } }
+  ],
+  "rest": { "cpu_percent": 42.26, "mem_mb": 11864 },
+  "docker_storage": { "ts": 1790789645, "images_mb": 4734, "images_reclaimable_mb": 3518,
+                      "build_cache_mb": 1597, "build_cache_reclaimable_mb": 1597,
+                      "volumes_mb": 10120, "unused_volumes_mb": 7337, "layers_mb": 30,
+                      "unused_volumes": [ { "name": "rev4a-backups", "size_mb": 7337 } ] }
+}
+```
+
+- `cpu_percent` is a share of Docker's cores (`host.ncpu`), `mem_percent` of Docker's memory —
+  on Docker Desktop that is its VM, on the VPS the machine. `cpu_cores` is the raw figure.
+- `now` is `null` for a container that is not running (no sample within 3 intervals of the
+  newest sample — running is judged against the newest sample, not the wall clock, so a
+  stopped daemon does not make every container look stopped);
+  `running: false` ones stay listed while they were seen in the range. A rate that is null in
+  the newest sample (the first after a start) is replaced by the previous reading.
+- The list is sorted running first, then by CPU now. `storage` is the named volumes plus the
+  writable layer, from the last Docker disk reading (every 10 min).
+- `rest` is the machine's newest sample minus the running containers (the containers' CPU
+  re-scaled to the machine's cores first, so on Docker Desktop the two shares still compare):
+  the host, Rev4a and other software (`null` without a machine sample or Docker's figures).
+- `docker_storage.*_reclaimable_mb` and `unused_volumes` (the 5 largest): what **no container
+  uses** — images of older agent versions you may still roll back to count as such; a volume
+  like the cold backups' is listed, not advised for removal. `volumes_mb` sums all volumes;
+  `unused_volumes_mb` is the total of what no container uses, `unused_volumes` only names the
+  five largest.
+- `available: false` until the daemon has created the tables; with the tables present and no
+  rows yet it answers `available: true` with an empty list.
+
+**With `&container=<name>`** — that container's history, bucketed like `GET /api/metrics`:
+```json
+{ "available": true, "range": "1h", "interval_s": 60, "host": { "ncpu": 10, "mem_total_mb": 7837 },
+  "container": "agent_9253eee3", "name": "test", "bucket_s": 120,
+  "history": [ { "ts": 1790789640, "cpu_avg": 1.41, "cpu_max": 2.17, "mem_avg": 685, "mem_max": 701 } ],
+  "storage_bucket_s": 1200, "storage_history": [ { "ts": 1790788800, "total_mb": 1554 } ] }
+```
+`cpu_*` are shares of Docker's cores, `mem_*` MB. A container that was not running has no
+points for that stretch (a gap). A name that matches the rules but was never sampled answers
+`available: true` with an empty history.
+
+**Errors:** `400` for another `range` or an invalid container name. A `metrics.db` that
+cannot be opened (missing, corrupt) answers `available: false`, not an error.
+
+### `GET /api/metrics/alerts?limit=10`
+The machine's latest `system_anomaly` events (CPU above 85 % or memory above 90 % on two
+samples in a row, a disk at 90 %), newest first, from `events.db`. `limit` 1–50, default 10.
+
+**Auth:** browser cookie or Bearer
+
+**Response:**
+```json
+{ "alerts": [ { "ts": 1790789625355, "metric": "disk", "message": "Disk high: / 94% used", "threshold": 90, "values": [94] } ] }
+```
+`ts` is in **milliseconds** (the `events` table's unit); `metric` is `cpu`, `ram`, `disk` or `null`.
+
 ---
 
 ## System Health
@@ -2302,27 +2387,26 @@ Full key management documentation at [PROVIDERS.md](PROVIDERS.md).
 ## Containers
 
 ### `GET /api/containers`
-List all running Docker containers with resource usage.
+Every Docker container, running or stopped, with its identity and network details. What a
+running container consumes lives in `GET /api/metrics/containers`.
 
-**Auth:** browser cookie
+**Auth:** browser cookie or Bearer
 
-**Response:**
+**Response:** a bare array —
 ```json
-{
-  "containers": [
-    {
-      "name": "openclaw-atlas",
-      "image": "openclaw-agent-base:2026.9.3",
-      "status": "running",
-      "ports": ["0.0.0.0:3731->3000/tcp"],
-      "created": "2026-06-20T10:00:00Z",
-      "cpu_percent": 2.1,
-      "mem_usage_mb": 340
-    }
-  ]
-}
+[
+  { "id": "a1b2c3d4e5f6", "name": "openclaw-atlas", "image": "openclaw-agent-base:2026.9.3",
+    "status": "Up 3 hours", "state": "running", "ports": "0.0.0.0:3731->3000/tcp",
+    "ip": "172.18.0.2", "agentId": "agent_atlas", "displayName": "Atlas", "created": null }
+]
 ```
 
+- `name` is the daemon's `primaryName` (the name with one leading slash) — the same key the
+  metrics store and the `/system?agent=` link use.
+- `displayName` is the agent's `AGENT_NAME`, read from the inspect. If an inspect fails, the
+  row still comes from Docker's list (`ip` and `displayName` then `null`): a container is
+  never dropped, and never renamed, because one call failed.
+
 The container list is the only container route. There is no logs endpoint and no
 action endpoint: logs are read through the terminal WebSocket, and lifecycle
 operations on agent containers go through `/api/agents/[id]/lifecycle`.
@@ -2807,8 +2891,10 @@ the update kills this process on its way in (`fuser -k <port>/tcp`) and `rev4a s
 brings the child back on the new binary via its `.restart-flag`, so the connection
 drops and the page has to wait for the server to answer again.
 
-The child's output goes to `update.log` in the data directory — the update restarts
-the process that spawned it, so that file is the only record of what happened.
+The child's output goes to `update.log` under `<REV4A_DATA_DIR>/data` (or
+`~/.config/rev4a/data` by default) — the update restarts the process that spawned
+it, so that file is the only record of what happened. The endpoint creates the
+directory if needed and reports a failure if it cannot start the updater.
 
 **Auth:** browser cookie or bearer token
 

package/docs/dev/DATABASE.md

@@ -1,9 +1,9 @@
 # Rev4a — Database Reference
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 Rev4a keeps four 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
+`events.db` (sessions and events, below), `metrics.db` (machine and container metrics, see
 [Metrics Database](#metrics-database-metricsdb)), `costs.db` (what the agents spent, see
 [Costs Database](#costs-database-costsdb)) and `credentials.db` (see
 [Credentials Database](#credentials-database-credentialsdb)).
@@ -318,6 +318,62 @@ has dropped back under, or once after each daemon start: the state is kept in me
 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.
 
+### Container consumption (also in `metrics.db`)
+
+What each running container uses, and the disk Docker holds, so the System page can say
+*who* is using the machine. The daemon writes it from the Docker Engine API
+(`lib/docker-stats.js`; where the socket is comes from `lib/docker-socket-path.js`, shared
+with the dashboard's `lib/docker-socket.ts`); `lib/container-metrics.ts` reads it for
+`GET /api/metrics/containers`, the agent panel and the Containers page. The tables are
+created with `CREATE TABLE IF NOT EXISTS` when the daemon starts, so an update adds them;
+until then the API answers `available: false`.
+
+**Sampling:** containers every 60 s, on a timer of its own — a priming pass 6 s after the
+daemon starts (it only records the gauges: a CPU figure needs two readings), the first
+complete one 15 s later — and Docker's disk (`/system/df`) every 10 min, the first reading
+25 s after start. **Retention:** 30 days, pruned at every sample. A stopped container has no
+rows: a gap, not zeros. Size, estimated: 60 s × 10 containers × 30 days ≈ 430 000 rows ≈ 35 MB
+(to be measured on the VPS; rollups to 5 min may be added if it grows).
+
+```sql
+-- One row per running container per sample. CPU in cores (CPU-seconds per second), rates in
+-- bytes per second; each is NULL on the first sample after a start and when its counter went
+-- backwards (the container restarted) — never a negative rate or a spike. Memory is the
+-- working set: usage − inactive page cache, what `docker stats` shows.
+CREATE TABLE container_metrics (
+  ts INTEGER NOT NULL,            -- Unix seconds
+  container TEXT NOT NULL,
+  cpu_cores REAL,
+  mem_mb INTEGER,
+  pids INTEGER,
+  net_rx_bps INTEGER, net_tx_bps INTEGER,
+  blk_read_bps INTEGER, blk_write_bps INTEGER
+);
+CREATE INDEX idx_container_metrics_ts ON container_metrics(ts);
+CREATE INDEX idx_container_metrics_c_ts ON container_metrics(container, ts);
+
+-- Who each container is: an agent's name (AGENT_NAME), whether it is an agent, and its named
+-- volumes (the link to docker_storage). Forgotten after the retention.
+CREATE TABLE container_sources (
+  container TEXT PRIMARY KEY,
+  agent_id TEXT, name TEXT, is_agent INTEGER NOT NULL DEFAULT 0,
+  volumes TEXT,                   -- comma-separated volume names
+  last_seen INTEGER NOT NULL
+);
+
+-- Docker's own cores and memory: the denominators for a container's share (on Docker Desktop
+-- that is its VM — 8 GB of a 16 GB Mac — not the machine). One row.
+CREATE TABLE docker_host (id INTEGER PRIMARY KEY CHECK (id = 1), ncpu INTEGER, mem_total_mb INTEGER, updated_at INTEGER);
+
+-- Disk Docker holds, one set of rows per reading: kind 'volume' (name = the volume;
+-- reclaimable_mb = its size when no container uses it), 'layer' (name = a container, its
+-- writable layer), 'images' and 'build_cache' (totals; reclaimable_mb = what no container /
+-- no build uses). A size Docker could not compute is NULL.
+CREATE TABLE docker_storage (ts INTEGER NOT NULL, kind TEXT NOT NULL, name TEXT NOT NULL DEFAULT '', size_mb INTEGER, reclaimable_mb INTEGER);
+CREATE INDEX idx_docker_storage_ts ON docker_storage(ts);
+CREATE INDEX idx_docker_storage_kind_ts ON docker_storage(kind, name, ts);
+```
+
 ## Costs Database (`costs.db`)
 
 What each agent spent, **as its own OpenClaw priced it** — Rev4a computes no cost here.

package/docs/dev/GATEWAY.md

@@ -1,6 +1,6 @@
 # Gateway Page
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-02
 
 The Gateway page (`/gateway`) is the control panel for provider configuration:
 API keys and the model catalogue offered to every agent container. It does not
@@ -113,9 +113,10 @@ its own Control UI too. Rev4a computes no cost: the daemon reads OpenClaw's figu
   (cached tokens priced as if the cache gave no discount); one without `cacheWrite` to
   1.25 × the input rate — vendors that bill cache writes apart charge more than input
   (Anthropic's five-minute cache: 1.25×), and the ones that report no cache writes never
-  use it. Either way an overestimate, never an undercount. `refresh:pricing` writes them
-  for OpenRouter models when OpenRouter publishes them (104 and 44 of 181 entries when
-  added); direct vendors are filled by hand from their pricing page.
+  use it. These fallbacks avoid treating an unknown cache rate as free, but can differ
+  from what a vendor bills. `refresh:pricing` writes published OpenRouter cache rates;
+  the file currently has cache-read rates for 107 models and cache-write rates for 44 of
+  184 entries. Direct vendors are filled by hand from their pricing page.
 - **Time-of-day prices.** DeepSeek bills half its rates off-peak (peak 01:00–04:00 and
   06:00–10:00 UTC, Monday–Friday). `PRICE_SCHEDULES` in `lib/model-pricing.ts` holds
   that schedule; `priceAt()` writes the rate of the moment, and
@@ -131,6 +132,11 @@ its own Control UI too. Rev4a computes no cost: the daemon reads OpenClaw's figu
   time, so a later change of rate does not reprice a call (verified with a real call,
   priced off-peak and read again after the switch to peak). Chinese public holidays,
   which DeepSeek bills off-peak all day, are priced as peak — a small overestimate.
+  Where the band is visible: the Costs page header (a pill with the time of the next
+  change), the agent panel's COSTS section (Rates now), and the Gateway page — a
+  band-priced model's row carries a PEAK / OFF-PEAK chip next to its price, and that price
+  is the rate in force now (off-peak it shows half the list price), refreshed just after
+  each change while the page stays open (`nextPriceChangeMs`).
 - **Calls made before a model had a price** are priced by OpenClaw when read, at the
   rate in force then; OpenClaw reindexes its transcripts after a price change, which is
   why a read can briefly answer `cacheStatus: refreshing`.
@@ -206,6 +212,9 @@ sources, each one labelled in the modal:
 | Price | `model-pricing.json` | refreshed for `openrouter/*`, hand for direct vendors |
 | Description, specs, benchmarks | `model-details.json` | **generated**, never hand-edited |
 
+For a scheduled vendor, the modal labels the static rate as a list price; the Gateway
+row shows the rate in force and its peak/off-peak band.
+
 `npm run refresh:pricing` (script `scripts/refresh-model-pricing.mjs`) fetches the
 OpenRouter catalogue once and writes both the prices and `model-details.json`:
 description, release date (`created`), context and the provider's own limit, max output,

package/docs/rag/DATA-FRESHNESS.md

@@ -1,6 +1,6 @@
 # Data Freshness in Rev4a
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 Understanding how current the data in Rev4a is — and what is truly real-time vs. periodically updated.
 
@@ -56,6 +56,21 @@ the collector is not running instead of showing stale numbers as current.
 
 ---
 
+## Container consumption (System page, Containers page, agent panel)
+
+**Update frequency:** every 60 seconds for CPU, memory, processes, network and block I/O of
+each running container; every 10 minutes for the disk Docker holds (volumes, writable layers,
+images, build cache). Both are sampled by the Rev4a daemon on timers of their own and kept 30
+days in `metrics.db`. The first figures after the daemon starts take about 20 seconds (a CPU
+figure needs two readings). A stopped container leaves a gap in its charts, not zeros.
+
+CPU is a share of Docker's cores and memory a share of Docker's memory: on Docker Desktop that
+is its virtual machine (for example 8 GB of a 16 GB Mac), on a server it is the machine. If the
+newest sample is older than three minutes the System page says it is not collecting — the
+figures still on show are the last known ones, not live. The agent panel stands its "now" rows
+down, and the Containers page clears its usage row rather than leave stale figures. A container
+still seen in Docker's list but without fresh statistics says "no data", not "stopped".
+
 ## Agent costs (Costs page)
 
 **Update frequency:** every 5 minutes. The Rev4a daemon asks each running agent

package/docs/rag/GLOSSARY.md

@@ -1,6 +1,6 @@
 # Rev4a Glossary
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 Terms you'll encounter while using the Rev4a dashboard.
 
@@ -22,7 +22,7 @@ A compressed archive (`.tar.gz`) of an agent's persistent volume (`/root/`). Bac
 Which browsers may open an agent's Control UI. On OpenClaw 9.x every new browser must be approved once; the approval is remembered per browser. Managed in the "BROWSER ACCESS" section of the agent detail panel: approve or reject waiting browsers, rename or revoke approved ones. The Open button uses a one-time link that skips the approval. The Invite link button gives a link for someone else: their browser still waits for approval.
 
 ## Container
-A Docker container running on the server. Each agent runs in its own container. The Containers page shows all containers, including infrastructure ones such as databases and reverse proxies, with a web terminal link (a real shell in the browser; a dropped connection is resumed for 2 minutes). It shows no CPU or memory metrics.
+A Docker container running on the server. Each agent runs in its own container. The Containers page shows all containers (a running one also with its CPU, memory and processes now), including infrastructure ones such as databases and reverse proxies, with a web terminal link (a real shell in the browser; a dropped connection is resumed for 2 minutes).
 
 ## Channel
 A communication channel (Telegram) configured on an agent. Channels allow users to send DMs to the agent via messaging apps. The Channel Manager modal lets you connect/disconnect Telegram and manage pairings (approve/reject senders).
@@ -34,7 +34,7 @@ Modal in the agent detail panel for configuring Telegram channels. Connect with
 What an agent spent in USD. Each agent's OpenClaw prices every model call itself, with the prices Rev4a writes into it (input, output, cached input), and Rev4a reads those figures every 5 minutes. The Costs page (`/costs`) shows them for today, 7 or 30 days — by day, by agent, by model, and the most expensive sessions. The dashboard's "Spent today" card shows the same figures for today, and each agent's panel on the Agents page has a COSTS section with its own. The Costs page also compares the agents' figures with what DeepSeek and OpenRouter actually billed (their balance or usage, read every hour).
 
 ## Off-peak
-DeepSeek bills half price outside its peak hours (peak: 01:00–04:00 and 06:00–10:00 UTC, Monday–Friday). Rev4a writes the lower prices into the agents when off-peak starts and the full ones when it ends, so each call is priced at the rate in force when it ran. The Costs page header shows the current band.
+DeepSeek bills half price outside its peak hours (peak: 01:00–04:00 and 06:00–10:00 UTC, Monday–Friday). Rev4a writes the lower prices into the agents when off-peak starts and the full ones when it ends, so each call is priced at the rate in force when it ran. The Costs page header and the agent panel's COSTS section (Rates now) show the current band.
 
 ## Cost Override
 A manual correction for a month's total cost, stored through `/api/cost-override`. There is currently no screen for it: no page in the dashboard reads or writes an override, so it can only be set by calling the API directly.

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,6 +1,6 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 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.
 
@@ -74,19 +74,23 @@ 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. 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.
+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. A DeepSeek model row shows its current rate and a peak/off-peak chip; the rate updates after the next band change. Every model row has a **Details** button: the modal shows the model's description, list 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.
+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. A running container also shows what it consumes now — CPU share, memory and processes — with a "Charts" link to its history on the System page.
 
-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.
+The page has no start, stop, or restart buttons: it is read-only apart from the terminal link. Container lifecycle is managed from the Agents page.
 
 ### Costs (`/costs`)
-What each agent spent, as its own OpenClaw priced it with the prices Rev4a syncs. Pick today, 7 days or 30 days (UTC days): the total, where the money went (input, output, cache), the tokens and how much input came from cache, a chart of the spend per day, the spend by agent and by model, and the most expensive sessions. Calls that could not be priced are listed by model, and agents whose figures are not current are flagged. When a DeepSeek model is on offer, the header shows whether DeepSeek is billing peak or off-peak (half price) and until when. Figures are read from the agents every 5 minutes. *Against the bill* compares them with what DeepSeek and OpenRouter actually charged (their balance or usage, read every hour); a small gap is normal, since the same key may pay for the assistant too. Each agent's own spend is also in its panel on the Agents page (COSTS).
+What each agent spent, as its own OpenClaw priced it with the prices Rev4a syncs. Pick today, 7 days or 30 days (UTC days): the total, where the money went (input, output, cache), the tokens and how much input came from cache, a chart of the spend per day, the spend by agent and by model, and the most expensive sessions. Calls that could not be priced are listed by model, and agents whose figures are not current are flagged. When a DeepSeek model is on offer, the header shows whether DeepSeek is billing peak or off-peak (half price) and until when. Figures are read from the agents every 5 minutes. *Against the bill* compares them with what DeepSeek and OpenRouter actually charged (their balance or usage, read every hour); a small gap is normal, since the same key may pay for the assistant too. Each agent's own spend is also in its panel on the Agents page (COSTS), with the current DeepSeek band (Rates now).
 
 ### 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.
 
+### Agents and containers (on the System page)
+Under the machine's charts: what Docker holds on disk (images, volumes, writable layers, build cache, and how much of each no container uses), then one row per container sorted by CPU. A closed row shows its name, whether it is an agent, and its CPU share, memory, storage and processes now, with the average and peak over the chosen range (1 hour to 30 days); open it for the same three charts as the machine — CPU, Memory, Storage — for that container. "Everything else" is what is not a container (the host, Rev4a, other software). Each agent's panel on the Agents page has the same numbers in its RESOURCES section, with a link to its charts. Below, the machine's recent alerts: CPU, memory or a disk that crossed its limit, and when.
+When Docker still sees a container but it has no current statistics, its row says "no data". If collection stops, the current figures are hidden and old rows say "not current" instead of implying a live reading.
+
 ### Container Terminal (`/containers/terminal/[id]`)
 Live web terminal into a running Docker container — like SSH in the browser: Tab completion, command history, `top`, `vi`, resizing with the window. If the connection drops (network, laptop sleep) the shell keeps running for 2 minutes and reconnecting picks it up; reloading the page resumes it too. **Close** ends the shell. If the container is stopped or missing, the page says so and offers **Reconnect**. Only a logged-in user can open it.
 

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

@@ -1,6 +1,6 @@
 # What PULSE Can Answer
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
 
@@ -11,6 +11,9 @@ 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.
+- "Which agent is using the most CPU or memory?" — The "Agents and containers" section of the System page: one row per container, sorted by CPU, with memory, storage and processes; open a row for its charts. An agent's own panel has the same numbers under RESOURCES.
+- "What is filling the disk?" — The "Docker storage" block on the System page: images, volumes (an unused volume is named), writable layers and build cache.
+- "Why is there a red bar or an alert on the System page?" — "Recent alerts" at the bottom of the System page lists what crossed its limit and when.
 - "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.