@flame0510/project-aether 1.2.0 → 1.4.0

package/docs/rag/DATA-FRESHNESS.md

@@ -1,6 +1,6 @@
 # Data Freshness in Rev4a
 
-> **Last updated:** 2026-07-18
+> **Last updated:** 2026-09-15
 
 Understanding how current the data in Rev4a is — and what is truly real-time vs. periodically updated.
 
@@ -8,47 +8,60 @@ Understanding how current the data in Rev4a is — and what is truly real-time v
 
 ## Session data
 
-**Update frequency:** every 15–30 seconds
+**Update frequency:** every 30 seconds
 
-The daemon polls `openclaw sessions --json --all-agents` on this schedule:
-- 15 seconds when at least one session has status `working`
-- 30 seconds when no sessions are actively working
+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.
 
-This means session statuses, token counts, and costs are at most 30 seconds behind reality during quiet periods, and 15 seconds behind during active work.
+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.
 
-**What this means for PULSE:** if you ask "is Argus working right now?", the answer reflects data that is up to 30 seconds old.
+**What this means for PULSE:** if you ask "is Argus working right now?", the
+answer reflects data that is up to 30 seconds old.
 
 ---
 
 ## Event feed
 
-**Update frequency:** ~3 seconds (via SSE stream)
+**Update frequency:** every 5 seconds (via SSE stream)
 
-The `/api/stream` endpoint pushes updates to the dashboard every ~3 seconds. This includes:
+The `/api/stream` endpoint pushes updates to the dashboard every 5 seconds. It
+sends exactly three things:
 - New events (spawn, complete, error, tool_call)
-- Updated session list
+- The session list
 - Today's cost total
-- Lineage data
 
-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 to 30 seconds to appear.
+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
+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 (15–30 seconds)
+**Update frequency:** every daemon poll cycle (30 seconds)
+
+**Retention:** 30 days (older rows are pruned automatically each cycle)
 
-**Retention:** last 24 hours only (older rows are pruned automatically)
+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.
 
 ---
 
 ## Cost totals
 
-**Update frequency:** every 15–30 seconds (recalculated from sessions on each API call)
+**Update frequency:** every 30 seconds (recalculated from sessions on each API call)
 
-The cost figures shown in the dashboard are always computed fresh from the database on each page load or SSE push. They are not cached.
+The cost figures shown in the dashboard are always computed fresh from the
+database on each page load or SSE push. They are not cached.
 
-**Cost override:** if a manual override is set for the current month, it is shown immediately after being saved — no delay.
+**Cost override:** `/api/cost-override` exists, but no page in the dashboard
+reads or writes it. There is no UI for setting one, so do not direct a user to
+"the cost override screen".
 
 ---
 
@@ -66,16 +79,27 @@ Cron status (last run, next run) is fetched directly from the OpenClaw gateway e
 
 **Update frequency:** on demand (read from `openclaw.json` on each request)
 
-The agents list, Telegram accounts, and bindings are read directly from `openclaw.json` each time the Agents Config page is accessed. Changes saved via the UI take effect immediately.
+The agents list, Telegram accounts, and bindings are read directly from
+`openclaw.json` each time they are requested.
+
+`GET /api/agents-config` serves this, but no page calls it — there is no "Agents
+Config page". Per-agent settings are reached from the agent's detail panel on the
+Agents page.
 
 ## Agent base image
 
-**Update frequency:** polled every 2 seconds during a build; on page load otherwise
+**Update frequency:** polled every 2 seconds, continuously
 
-The `GET /api/agents/image-status` endpoint compares the local image digest
-with the remote registry digest (ghcr.io). Download progress is shown inline
-via polling `GET /api/agents/image-status` and reading logs from
-`/tmp/rev4a-download-<timestamp>.log`.
+`GET /api/agents/image-status` lists the supported OpenClaw versions downloaded and
+compares them with the versions the registry publishes. The registry list is refreshed
+at most every 10 minutes, so a newly published version can take that long to appear.
+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
+`/tmp/rev4a-download-<timestamp>.log`, but nothing in the dashboard reads it.
 
 ---
 
@@ -83,7 +107,9 @@ via polling `GET /api/agents/image-status` and reading logs from
 
 **Update frequency:** on demand (files read from disk on each request)
 
-Memory files (MEMORY.md, etc.) are read from disk each time they are requested. There is no caching.
+Memory files are read from disk each time they are requested. There is no caching.
+
+The tracked set is `USER.md`, `MEMORY.md`, `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md`.
 
 ---
 
@@ -91,7 +117,7 @@ Memory files (MEMORY.md, etc.) are read from disk each time they are requested.
 
 | Data | Why it may be stale |
 |---|---|
-| Sessions ended more than 7 days ago | `agents-active` endpoint only looks back 7 days |
+| Cron sessions older than 7 days | The daemon prunes cron session rows after 7 days |
 | Sessions never polled by daemon | If the daemon was down, sessions from that window are missing |
 | Tool calls for a session | Only captured if the OpenClaw session export includes them |
 | Costs before Rev4a was installed | Historical data before the first daemon run is not available |
@@ -100,10 +126,15 @@ Memory files (MEMORY.md, etc.) are read from disk each time they are requested.
 
 ## How to check if data is fresh
 
-The System Health page shows a check like "last event X seconds ago". If this number is larger than ~60 seconds, the daemon may have stopped.
+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.
 
-You can also run this command on the server to check directly:
+To check directly on the server:
 ```bash
-sqlite3 data/events.db \
+sqlite3 ~/.config/rev4a/data/events.db \
   "SELECT datetime(MAX(ts)/1000, 'unixepoch', 'localtime') FROM events"
 ```
+
+The database lives under the Rev4a data directory, which defaults to
+`~/.config/rev4a/` and moves with `REV4A_DATA_DIR`. It is not inside the repo.

package/docs/rag/GLOSSARY.md

@@ -1,6 +1,6 @@
 # Rev4a Glossary
 
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-15
 
 Terms you'll encounter while using the Rev4a dashboard.
 
@@ -10,16 +10,19 @@ Terms you'll encounter while using the Rev4a dashboard.
 An AI assistant configured with a specific role, AI model, and workspace. Each agent has a name (e.g. "Argus") and can run multiple sessions over time. Agents are deployed as Docker containers with persistent data volumes.
 
 ## Agent Template
-A pre-built configuration used when creating a new agent. Templates include default files (AGENTS.md, SOUL.md, MEMORY.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md) and settings. Located in `agent-templates/`. Available templates: **Atlas** (general dev), **Argus** (security/audit), **Prometheus** (client-facing), and **Custom** (blank slate — bootstraps identity interactively on first run).
+A pre-built configuration used when creating a new agent. Each template ships its own set of files. Atlas has AGENTS.md, SOUL.md, IDENTITY.md, TOOLS.md, MEMORY.md and HEARTBEAT.md; Argus and Prometheus have the same minus HEARTBEAT.md; Custom has only AGENTS.md, MEMORY.md and BOOTSTRAP.md. Located in `agent-templates/`. Available templates: **Atlas** (general dev), **Argus** (security/audit), **Prometheus** (client-facing), and **Custom** (blank slate — bootstraps identity interactively on first run).
 
 ## Badge
-A small inline label component used for status indicators and channel chips. Supports success, danger, warning, and neutral tones. Used for TG/WA chips on the agent list and pairing status in the Channel Manager.
+A small inline label component used for status indicators and channel chips. Six tones: neutral, accent, success, warning, danger, info. Used for the Telegram chip on the agent list and pairing status in the Channel Manager. There is no WhatsApp support anywhere in Rev4a.
 
 ## Backup (Agent)
 A compressed archive (`.tar.gz`) of an agent's persistent volume (`/root/`). Backups exclude the npm cache to keep sizes small (~1.5 MB). Stored in the `rev4a-backups` Docker volume. Used for restore operations and auto-created before each recreate.
 
+## Browser Access
+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 (databases, reverse proxies, etc.), with CPU/memory metrics and a web terminal.
+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. It shows no CPU or memory metrics.
 
 ## 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).
@@ -31,7 +34,7 @@ Modal in the agent detail panel for configuring Telegram channels. Connect with
 The estimated cost of an agent session in USD, calculated from tokens used and per-model pricing. Rev4a shows cost by today, 7 days, 30 days, all-time, and by model.
 
 ## Cost Override
-A manual correction for a month's total cost. If the automatic calculation doesn't match the actual invoice, you can set an override value for that month with an optional note.
+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.
 
 ## Credential
 A third-party service token (GitHub PAT, Trello API key, Vercel token, Supabase access key, Notion API token) stored in the Rev4a vault. A credential is installed into a container only when the user syncs it, and removed on de-sync; any credential can be synced to any container. Every reveal is written to an audit table that no route or view reads.
@@ -40,25 +43,25 @@ 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, system health metrics (CPU, RAM, disk, load average), and a real-time event feed. A setup banner appears if the first-run wizard is incomplete.
+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 ~3 seconds.
+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.
 
 ## Gateway
-The routing layer that connects agents to AI providers. The Gateway page has two panels: Provider Sync (push the model catalogue to all agents) and Agent Model Config (set each agent's primary model and fallbacks).
+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.
 
 ## Lineage
-The parent-child relationship tree between sessions. When an agent spawns another agent to do work, that relationship is shown as an interactive graph on the Lineage page. Configurable time periods: 1d, 7d, 30d.
+The parent-child relationship tree between sessions. When an agent spawns another agent to do work, that relationship is shown as an interactive graph on the Lineage page. Configurable time periods: 1d, 3d, 7d, 15d, 30d and all.
 
 ## Memory
-Files that store an agent's persistent knowledge and personality: MEMORY.md, SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md. Editing them changes how an agent behaves. The Memory page shows all files with size and budget tracking.
+Files that store an agent's persistent knowledge and personality. The tracked set is USER.md, MEMORY.md, AGENTS.md, SOUL.md and HEARTBEAT.md. Editing them changes how an agent behaves. The Memory page shows these with size and budget tracking. A template may also ship IDENTITY.md or TOOLS.md, which are not tracked.
 
 ## Model
-The AI model used by an agent or session. Examples: GPT-5.4, Claude Sonnet 4, DeepSeek V4 Flash. Models are linked to specific providers. The Gateway page manages which models are enabled and which agent uses which model.
+The AI model used by an agent or session. Examples: GPT-5.4, Claude Sonnet 5, DeepSeek Flash. Models are linked to specific providers. The Gateway page controls which models are enabled for the whole deployment; the agent detail panel sets which one a given agent runs, plus its fallbacks. A model whose name the provider has retired is tagged `deprecated` on the agent card and in that panel. The Gateway page does not show it.
 
 ## First-run wizard
-First-time setup wizard at `/wizard`. Steps: Welcome → Providers → First Agent → Ready. Completion is recorded in `wizard.json` under the data directory. Always accessible from the sidebar or mobile navbar.
+First-time setup wizard at `/wizard`. Steps: Welcome → Providers → First Agent → Ready. Completion is recorded in `wizard.json` under the data directory. Always accessible from the sidebar. The mobile bottom navigation has five entries — Home, Agents, Workspace, Gateway, Containers — and the wizard is not one of them.
 
 ## Plugin
 An extension that adds new tools and capabilities to agents. Plugins are installed in the workspace and appear in the Plugins page with enable/disable toggles.
@@ -73,11 +76,14 @@ Rev4a's built-in proxy that gives all agents unified access to configured LLM pr
 The AI concierge embedded in Rev4a. Click the floating chat button (bottom-right) on any page to ask questions about the dashboard features and navigation.
 
 ## Recreate (Agent)
-Rebuild an agent container from the latest `openclaw-agent-base:latest` image while preserving the persistent volume. Auto-backups the volume first — if the backup fails, the recreate is aborted. This is how agents pick up OpenClaw image updates.
+Rebuild an agent container on its own OpenClaw version while preserving the persistent volume. Auto-backups the volume first — if the backup fails, the recreate is aborted. A recreate never changes the OpenClaw version; moving to a newer version is a separate update.
 
 ## Restore (Agent)
 Replace an agent's persistent volume with a previously created backup. The container is stopped, the volume content is fully replaced, then the container is restarted.
 
+## Rollback (Agent)
+Undo an agent's latest OpenClaw update: the backup taken just before the update is put back and the agent starts again on its previous version. Anything the agent did after the update is lost. Offered in the agent's OPENCLAW VERSION section while that backup exists.
+
 ## Session
 One instance of an agent doing work. Tracks: start/end time, tokens used, cost, model, status, and task description. A session starts when an agent receives a task and ends when it completes or fails.
 
@@ -113,13 +119,18 @@ A capability available to agents: running shell commands, reading files, searchi
 A record of an agent using a tool during a session. Useful for auditing what an agent actually did. Shown in the Session Drawer.
 
 ## Traefik
-Optional reverse proxy for routing web traffic to agent containers. If configured, an agent gets a public URL. Rev4a itself runs on port 3740 and does not require Traefik.
+Optional reverse proxy an operator can put in front of the Rev4a dashboard or of an agent's port. Rev4a does not configure it and sets no routing labels on agents: an agent's Control UI is reached on its published port. Rev4a itself runs on port 3740 and does not require Traefik.
+
+## Update (Agent)
+Move one agent to a newer OpenClaw version downloaded on the Agents page, from its OPENCLAW VERSION section. The agent goes offline for a few minutes: it is backed up while stopped, started on the new version (which converts its data), and checked for missing conversation history or cron jobs. Undone with Rollback.
 
 ## Vault
 Rev4a's store for third-party service tokens (GitHub, Trello, Vercel, Supabase, Notion). Provider API keys live separately in `provider-keys.json`, managed from the Gateway page. Supports reveal (written to an audit table no route or view reads), sync to and from containers, and live detection of which credentials are actually installed. Secrets are stored unencrypted.
 
 ## 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 VPS host and all agent containers.
+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 Health
-Hardware metrics shown on the Dashboard: CPU usage (%), RAM used/total (MB), disk used/total (GB), system load average (1m). The System Health API (`/api/system-health`) also generates recommendations (e.g. "Consider archiving old sessions to reduce disk usage"). Status can be `ok`, `warn`, or `error`.
+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.
+
+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.

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,13 +1,15 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-05
+> **Last updated:** 2026-09-15
 
 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.
 
 ## What can you do in Rev4a?
 
 ### Dashboard (`/`)
-The main page. See live sessions (who's working right now), cost summary by model and time period (today, 7 days, 30 days), system health (CPU, RAM, disk, load average), and a real-time event feed. Click any session row to open the Session Drawer and see every tool call the agent made. If the first-run wizard is incomplete, a banner appears at the top with a link to continue.
+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.
 
 ### First-run wizard (`/wizard`)
 First-run setup wizard that guides new users through configuration. Four steps:
@@ -16,7 +18,7 @@ First-run setup wizard that guides new users through configuration. Four steps:
 3. **First Agent** — understand how agents work and what you need to create one
 4. **Ready** — site map of key sections with quick links
 
-The wizard is always accessible from the sidebar. A progress badge (e.g. "1/3") shows how many steps are complete. Once finished, the badge disappears and the dashboard banner goes away.
+The wizard is always accessible from the sidebar. There is no progress badge on that entry and no banner elsewhere.
 
 ### Agents (`/agents`)
 Manage Docker containers running OpenClaw agents. See which agents are running, stopped, or errored. Filter by status, view agent details (environment variables, ports, auth tokens, backups, Telegram channels), and create new agents. Each agent card shows its template, status, TG channel chip, and a direct link to its Control UI.
@@ -32,34 +34,42 @@ Manage Docker containers running OpenClaw agents. See which agents are running,
 
 The agent list also shows a compact TG chip next to each agent name (green = connected, hidden if not configured).
 
-The Agents page includes a banner for the **agent base image** (`openclaw-agent-base:latest`):
-- Green: image is up-to-date (no banner shown)
-- Yellow: image is outdated or missing — click "Rebuild Image" to start a build
-- Copper: a build is running in the background — click "View Progress" to open
-  the build modal
-
-The build modal shows live Docker build logs (polled every 2s). You can:
-- **Run in Background** — close the modal, build continues on the server
-- **Abort** — kill the build process; the existing image stays intact
-- **Refresh / re-enter** — opening the modal again resumes log streaming
-  from the last seen line
-
-The build writes logs to `/tmp/rev4a-build-<timestamp>.log` so they survive
-page refreshes and modal closes.
+**Browser access:** on agents running OpenClaw 9.x, every new browser has to be approved once before the agent's Control UI connects. The detail panel's "BROWSER ACCESS" section lists browsers waiting for approval, with Approve and Reject, and the browsers already approved, with Rename and Revoke. A yellow "BROWSER WAITING" chip on the agent card says a request is pending. The **Open** button tries a one-time link that lets the browser in without any approval; if the agent cannot issue one (agents still on OpenClaw 2026.7.x) it opens the normal link, which on those agents needs no approval anyway. To let someone else in, **Invite link** gives a link to send them: their browser appears under waiting for approval, and nothing opens until you approve it. The link contains the token all agents share; changing the agents token cancels every link already sent.
+
+The Agents page includes a banner for the **agent base image**, which is kept per
+OpenClaw version. It is hidden when a supported version is downloaded and nothing newer
+is published. When no image is downloaded it offers **Download Image**; when a newer
+supported OpenClaw version is published it says so and offers **Download <version>**.
+Downloading changes no agent: new agents are created on the newest version downloaded,
+existing agents keep their version (a recreate never changes it), and their card shows
+**UPDATE AVAILABLE**.
+
+**Updating an agent:** the detail panel's "OPENCLAW VERSION" section shows the version the
+agent runs and, when a newer one is downloaded, **Update to <version>**. The update takes
+the agent offline for a few minutes: it backs the agent up while stopped, starts it on the
+new version (which converts its data), and checks that no conversation history or cron job
+went missing. Afterwards **Roll back to <version>** puts back the backup taken just before
+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.
 
 ### 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.
 
 ### Lineage (`/lineage?period=7d`)
-Interactive graph showing session family trees — which agent spawned which child agent, across configurable time periods (1d, 7d, 30d). Click any node to inspect. Includes a live feed side panel.
+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`)
-Central hub connecting agents to AI providers. Two panels:
-- **Provider Sync** — reads the model catalogue from `models.config.json`, discovers which providers have API keys, and syncs the full model list to every agent container
-- **Agent Model Config** — set each agent's primary model and fallback models via `PUT /api/gateway/agent`
+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.
 
 ### Containers (`/containers`)
-Full list of all Docker containers on the server. See name, image, status, ports, IP, CPU%, and memory usage. Click "Terminal" on any container to open an interactive shell. Use Start/Stop/Restart buttons to manage lifecycle.
+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.
 
 ### Container Terminal (`/containers/terminal/[id]`)
 Live web terminal into a Docker container. Run commands, inspect files, debug issues — like SSH but in the browser.
@@ -74,13 +84,15 @@ Manage third-party service credentials: GitHub, Trello, Vercel, Supabase, Notion
 Scheduled tasks auto-discovered from the host OpenClaw gateway (via `openclaw cron list --json`) and every running Docker container with the `AGENT_ID` label (via `docker exec openclaw cron list --json`). Filter jobs by agent using the toolbar tabs. Each job shows name, description, cron expression, next run, last run, and last status. Toggle on/off per job. The run history panel shows recent cron run executions for the selected job, loaded on demand from the container's gateway.
 
 ### Memory / Context (`/memory`)
-Browse agent memory files — MEMORY.md, SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md. These files define how agents behave, what they know, and their personality. Also shows total memory budget vs usage.
+Browse agent memory files. The tracked set is USER.md, MEMORY.md, AGENTS.md, SOUL.md and HEARTBEAT.md. These files define how agents behave, what they know, and their personality. Also shows total memory budget vs usage.
+
+A template may ship other files, such as IDENTITY.md or TOOLS.md, but those are not part of the tracked context set.
 
 ### Config (`/config`)
 Rev4a application settings. View and modify environment variables (password, tokens, secrets), restart the server. Changes are persisted to `.env`, synced to systemd, and a daemon-reload is triggered.
 
 ### Tools (`/tools`)
-Catalog of every tool available to agents — built-in commands, MCP server tools, plugin tools, and audio/TTS configuration. Includes timezone settings.
+Catalog of the OpenClaw built-in tools available to agents, grouped by area: file and code, shell, web, messaging, sessions, media, and others. The list is curated in the app, not discovered at runtime, so it covers built-ins only and does not enumerate MCP servers or plugin tools. The page also holds audio/TTS and timezone settings.
 
 ### Plugins (`/plugins`)
 Browse installed OpenClaw plugins. Enable/disable toggle per plugin. Plugins extend agent capabilities with new tools and integrations.
@@ -101,7 +113,7 @@ Password-protected access to the dashboard. Enter the Rev4a password to authenti
 
 ## What about Pulse?
 
-Pulse is the AI assistant embedded in Rev4a. She appears as a floating chat button in the bottom-right corner of every page. She can:
+Pulse is the AI assistant embedded in Rev4a. She appears as a floating chat button in the bottom-right corner, on every page except login, setup and the first-run wizard. She can:
 
 - Explain what any page does
 - Guide you through features ("how do I create an agent?")

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

@@ -1,6 +1,6 @@
 # What PULSE Can Answer
 
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-15
 
 PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
 
@@ -12,7 +12,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "How do I get to the container list?"
 - "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, models, agent assignments.
+- "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.
 - "How do I create a new agent?"
 - "What templates are available?"
 - "What is the Custom template?"
@@ -48,14 +48,18 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "How do I sync credentials to an agent?"
 - "How do I back up an agent?"
 - "How do I restore an agent from a backup?"
-- "How do I recreate an agent with the latest image?"
+- "How do I rebuild (recreate) an agent's container?"
 - "How do I delete an agent?"
 - "How do I restart the Rev4a server?"
 - "How do I change environment variables?"
-- "How do I add a cost override?"
+- "How do I add a cost override?" — There is no screen for it. The endpoint exists, but nothing in the dashboard calls it.
 - "How do I see the session lineage?"
 - "How do I log in to an agent's control UI?"
-- "How do I register a new provider via OAuth?"
+- "Why does the Control UI ask me to approve this browser?"
+- "How do I approve or revoke a browser for an agent?"
+- "How do I give someone else access to an agent's Control UI?"
+- "How do I update an agent to a newer OpenClaw version, and how do I go back?"
+- "How do I register a new provider via OAuth?" — The endpoint exists but no page uses it. Providers are added by pasting an API key on the Gateway page.
 - "How do I manage agent model fallbacks?"
 - "How do I connect an agent to Telegram?"
 - "How do I approve a pairing code?"
@@ -97,9 +101,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "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'?"
-- "What happens if I abort a build?"
-- "Can I close the build modal while it's running?"
-- "How do agent image rebuilds work?"
+- "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.
 - "Why is my Telegram bot not connecting?"
 - "Why can't I approve a pairing code?"
 - "Why is the TG badge missing from my agent?"

package/instrumentation.ts

@@ -9,10 +9,61 @@ export async function register() {
   if (process.env.NEXT_RUNTIME === 'nodejs') {
     try {
       const { syncAllAgents } = await import('./app/api/gateway/sync');
-      syncAllAgents();
+      // The outcome used to be discarded. syncAllAgents reports failures instead of
+      // throwing, so the catch below never saw a sync that reached no container —
+      // Docker not yet up at boot left the fleet stale with nothing in the log.
+      const outcome = syncAllAgents();
+      if (outcome.ok) {
+        console.log(`[rev4a] Startup sync: ${outcome.summary}`);
+      } else {
+        console.warn(`[rev4a] Startup sync incomplete: ${outcome.summary} Run Sync All Agents once the cause is fixed.`);
+      }
     } catch {
       // Best-effort — don't block startup if sync fails
       console.warn('[rev4a] Failed to sync agents on startup');
     }
+    // Updates cut off by the restart: no job runs in a fresh process, so any update
+    // still marked active becomes `interrupted` and waits for the operator.
+    try {
+      const { recoverInterruptedUpdates } = await import('./lib/agent-update');
+      const interrupted = await recoverInterruptedUpdates();
+      if (interrupted) console.warn(`[rev4a] ${interrupted} agent update(s) were interrupted by the restart`);
+    } catch {
+      console.warn('[rev4a] Could not check agent updates on startup');
+    }
+    // Recreates cut off by the restart: the row becomes `interrupted` and an agent the
+    // backup had stopped is started again, so nothing stays down.
+    try {
+      const { recoverInterruptedRecreates } = await import('./lib/agent-recreate');
+      const interrupted = await recoverInterruptedRecreates();
+      if (interrupted) console.warn(`[rev4a] ${interrupted} agent recreate(s) were interrupted by the restart`);
+    } catch {
+      console.warn('[rev4a] Could not check agent recreates on startup');
+    }
+    // Restores cut off by the restart: same treatment — the row becomes `interrupted`
+    // and a container left stopped is started again.
+    try {
+      const { recoverInterruptedRestores } = await import('./lib/agent-restore');
+      const interrupted = await recoverInterruptedRestores();
+      if (interrupted) console.warn(`[rev4a] ${interrupted} agent restore(s) were interrupted by the restart`);
+    } catch {
+      console.warn('[rev4a] Could not check agent restores on startup');
+    }
+    // Edits cut off by the restart: same treatment.
+    try {
+      const { recoverInterruptedEdits } = await import('./lib/agent-edit');
+      const interrupted = await recoverInterruptedEdits();
+      if (interrupted) console.warn(`[rev4a] ${interrupted} agent edit(s) were interrupted by the restart`);
+    } catch {
+      console.warn('[rev4a] Could not check agent edits on startup');
+    }
+    // Cold backups whose helper outlived a Rev4a restart: finish the exited ones (the
+    // agent is started again if it was running) and keep watching the rest.
+    try {
+      const { reconcileColdBackups } = await import('./lib/cold-backup');
+      await reconcileColdBackups();
+    } catch {
+      console.warn('[rev4a] Could not reconcile cold backups on startup');
+    }
   }
 }

package/lib/agent-busy.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether an agent is in the middle of a long operation that nothing else may touch:
+ * an edit (lib/agent-edit.ts), a restore (lib/agent-restore.ts), a recreate
+ * (lib/agent-recreate.ts), an update (lib/agent-update.ts) or a cold backup
+ * (lib/cold-backup.ts). The routes that change an agent answer 409 with this reason.
+ */
+import { isColdBackupRunning } from '@/lib/cold-backup';
+import { isUpdateActive } from '@/lib/agent-update-state';
+import { isRecreateActive } from '@/lib/agent-recreate-state';
+import { isRestoreActive } from '@/lib/agent-restore-state';
+import { isEditActive } from '@/lib/agent-edit-state';
+
+export async function agentBusyReason(agentId: string): Promise<string | null> {
+  if (isUpdateActive(agentId)) return 'An update of this agent is running';
+  if (isRecreateActive(agentId)) return 'A recreate of this agent is running';
+  if (isRestoreActive(agentId)) return 'A restore of this agent is running';
+  if (isEditActive(agentId)) return 'An edit of this agent is running';
+  if (await isColdBackupRunning(agentId)) return 'A backup of this agent is running';
+  return null;
+}
+