@flame0510/project-aether 1.1.15 → 1.3.0

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-08-09
+> **Last updated:** 2026-09-14
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -107,22 +107,21 @@ When environment variables are saved via the Config page (Save & Restart):
 
 | Route | Description |
 |---|---|
-| `/dashboard` | System overview — containers, resources, quick links |
+| `/` | System overview — containers, resources, quick links |
 | `/agents` | Running agents (Docker containers with `AGENT_ID`), gateway token management, agent creation wizard, channel manager (Telegram pairing) |
 | `/containers` | All Docker containers on the host |
-| `/onboarding` | First-run setup wizard (Welcome → Providers → Agent → Ready) |
+| `/wizard` | First-run setup wizard (Welcome → Providers → Agent → Ready) |
 | `/workspace` | File explorer with tree view + editor — VPS host or container workspaces |
 | `/lineage` | Agent lineage / orchestration tree |
 | `/memory` | Agent memory browser |
 | `/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) — JSON vault with audit trail, sync to agent containers via CLI auth (gh, vercel, supabase) or env files (trello) |
+| `/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 |
 | `/plugins` | Plugin manager |
-| `/plugins-skills` | Plugin skills |
 | `/skills` | Skill registry — browse/edit all skills (shared, per-agent workspace, bundled). Promote agent skills to shared with one click. |
 | `/tools` | Tool configuration |
-| `/gateway` | LLM provider sync + agent model configuration — see [GATEWAY.md](dev/GATEWAY.md) |
+| `/gateway` | LLM provider keys, model catalogue and sync — see [GATEWAY.md](dev/GATEWAY.md) |
 | `/config` | Environment management and server restart |
-| `/vault` | Credential storage (per-agent permissions) — see [PROVIDERS.md](dev/PROVIDERS.md) |
 | `/login` | Authentication page |
 
 ---
@@ -189,6 +188,18 @@ sudo systemctl status rev4a.service
 sudo journalctl -u rev4a -f
 ```
 
+### Start-up and Docker
+
+`rev4a serve` waits for the Docker daemon before its Docker-dependent steps, up to
+`REV4A_DOCKER_WAIT_SECONDS` (default 90, capped at 600; `0` checks once without
+waiting; a negative or non-numeric value means 90). It asks the daemon itself with
+`docker info`, so the wait works the same on any Docker install. The variable is
+read from the process environment, not from the `.env` file.
+
+If the daemon never answers, `serve` starts anyway, skips the network and image
+checks, and says so in the log. The startup sync then reaches no agent, and logs
+that too; run Sync All Agents once Docker is up.
+
 ### Systemd environment override
 
 File: `/etc/systemd/system/rev4a-next.service` (EnvironmentFile)
@@ -261,19 +272,29 @@ Container workspaces are discovered dynamically — any Docker container with an
 
 ## Features (current)
 
-### Vault (`/vault`)
-Store and manage credentials (API keys, tokens) with per-agent permissions.
-
-- **SQLite storage:** `credentials.db` in the data directory
-- **Provider keys:** stored in `data/provider-keys.json`, managed via the Gateway UI
-- **Agent permissions:** each credential can be scoped to specific agents
-- **Service management:** add/remove provider API keys and service tokens via the UI
+### Credentials (`/credentials`)
+Store third-party service credentials and install them into agent containers.
+
+- **SQLite storage:** `credentials.db` in the data directory. Secrets are held
+  **unencrypted**; anything that can read the file has them in the clear.
+- **Provider keys** are a separate store — `provider-keys.json`, managed from the
+  Gateway UI.
+- **Five providers.** GitHub, Vercel and Supabase are handed to their CLI —
+  `gh auth login --with-token`, `~/.local/share/com.vercel.cli/auth.json`,
+  `supabase login --token`. Trello and Notion have no CLI in the loop: their
+  credentials are written to `~/.config/trello/config.json` and
+  `~/.config/notion/config.json`, and TOOLS.md tells the agent how to call each
+  REST API with them.
+- **Delivery is explicit.** A credential reaches a container only on sync, and
+  leaves only on de-sync. There is no per-agent permission model: any stored
+  credential can be synced to any container.
+- **Live detection** shows which credentials are actually installed, matching
+  SHA-256 hashes of the tokens found in each container against the stored ones.
 
 ### Container management (`/containers`)
 View all running Docker containers with:
 - Name, image, status, ports, uptime
 - Resource usage (CPU, memory)
-- Per-container logs
 - Quick links to agent control UIs
 
 ### Agent management (`/agents`)
@@ -302,15 +323,16 @@ Available templates:
 **Post-creation pipeline:**
 1. The container boots with the **openclaw-agent-base:latest** image — see [Agent Templates](#agent-templates) below.
 2. OpenClaw gateway starts automatically with `--allow-unconfigured`, generating its own default config.
-3. The route waits for the gateway to be fully ready (health check poll, up to 60 s).
+3. The route waits for the gateway to finish starting with `waitForGatewayReady()`, up
+   to 60 s. On OpenClaw 9.x it waits for `/startupz` to report `started`. The
+   2026.7.1-2 image has no `/startupz`, so there it waits for `/health`, which only
+   shows the server is listening.
 4. Once ready, the route writes:
    - `gateway.controlUi.allowedOrigins` — Rev4a dashboard URL + Traefik hostname (required for browser Control UI access)
    - `agents.defaults.model.primary` + fallbacks — the primary model selected in the wizard
-5. `syncAgent(name)` writes `models.providers.rev4a` into the container.
+5. The route builds `models.providers.rev4a` with `buildRev4aProviderConfig()` and writes it with `openclaw config patch --stdin`.
 6. The agent's control UI is immediately accessible at `https://<name>.<your-domain>.com#token=<gateway-token>`.
 
-**Key difference from the old pipeline:** the entrypoint no longer generates `openclaw.json`. The bootstrap config (including `controlUi.allowedOrigins`) is written by the create route after the gateway has already started. This eliminates the race condition where the entrypoint would overwrite synced provider config on boot.
-
 ---
 
 ## Agent persistence & lifecycle
@@ -376,23 +398,33 @@ repo. The copy is skipped when the workspace is already populated (see
 
 ## Gateway Page (`/gateway`)
 
-Two panels:
+One job: provider configuration. API keys, which catalogue models this deployment
+offers, and pushing that catalogue to every agent.
+
+- Reads the model catalogue from `models.config.json`, merged with user toggles in
+  `<data dir>/model-overrides.json`
+- Scans providers with keys in `<data dir>/provider-keys.json`
+- `PUT /api/gateway/provider` runs `syncAllAgents()`, which writes
+  `models.providers.rev4a` into every agent container
+- **Does NOT touch** `agents.defaults.model` or `agents.list[].model` — those are
+  per-agent settings
+
+### Per-agent model, elsewhere
 
-### Provider Sync
-- Reads active models from `models.config.json` (file-based model catalogue)
-- Scans providers with keys in `data/provider-keys.json`
-- `PUT /api/gateway/provider` runs `syncAllAgents()` which writes `models.providers.rev4a` to every agent container
-- **Does NOT touch** `agents.defaults.model` or `agents.list[].model` — model references are managed per-container from the Agents Tab
+Choosing which model one agent runs is not on this page. It lives in the Model
+section of that agent's detail panel on the Agents page
+(`app/agents/ModelSection.tsx`), which calls `PUT /api/gateway/agent` to write the
+model ref into that container's `openclaw.json`. No gateway restart: OpenClaw
+watches the file and hot-applies the change.
 
-### Agent Model Config
-- Select a container and set its primary model
-- `PUT /api/gateway/agent` writes the model ref (`primary`, `fallbacks`) directly into the container's `openclaw.json`
-- Does NOT restart the gateway — writes are live via file write
+The model is a property of the agent, not of the gateway. See
+[GATEWAY.md](dev/GATEWAY.md) for the write semantics: omitting `fallbacks` keeps the
+agent's current list, `[]` clears it.
 
 ### Model Catalogue (`models.config.json`)
 File-based, tracked in git. Each entry:
 ```json
-{ "id": "deepseek/deepseek-v4-flash", "name": "DeepSeek V4 Flash", "provider": "deepseek", "enabled": true }
+{ "id": "deepseek/deepseek-flash", "name": "DeepSeek Flash", "provider": "deepseek", "enabled": true }
 ```
 Models with `enabled: false` are ignored.
 Only models whose provider has a key in `data/provider-keys.json` are synced.