@flame0510/project-aether 1.1.14 → 1.2.0

package/app/credentials/loading.tsx

@@ -1,10 +1,24 @@
-import { Skeleton, CardRowSkeleton } from '../components/Skeleton';
+import { Page, PageHeader } from '../components/ui';
+import { CredentialCardsSkeleton } from '../components/Skeleton';
 
+/**
+ * Route-level loading UI, shown while the page chunk streams in.
+ *
+ * It renders the same chrome and the same skeleton as PageClient's own loading
+ * state, so the two hand over without a visible change. The previous version
+ * used a generic five-row card list at maxWidth 1080, while the real page is a
+ * card grid inside the default 1280 — the skeleton and the page it stood for
+ * did not line up.
+ */
 const PageSkeleton = () => (
-  <div style={{ padding: '24px 20px', maxWidth: 1080, margin: '0 auto' }}>
-    <Skeleton width={120} height={20} accent style={{ marginBottom: 20 }} />
-    <CardRowSkeleton count={5} height={48} />
-  </div>
+  <Page>
+    <PageHeader
+      eyebrow=""
+      title="Credentials"
+      description="Store third-party credentials once, sync to all agent containers."
+    />
+    <CredentialCardsSkeleton />
+  </Page>
 );
 
 export default PageSkeleton;

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Rev4a Architecture — Design & Vision
 
 > **Status:** Active — `main` branch
-> **Last updated:** 2026-06-30
+> **Last updated:** 2026-08-28
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -64,15 +64,15 @@
 
 ---
 
-## 2. Current Architecture (as of 2026-06-24)
+## 2. Current Architecture (as of 2026-08-28)
 
 ### What's already been implemented
 
 **Container separation:** `openclaw-atlas` already runs as a standalone container with `AGENT_ID=atlas`, discovered dynamically by Rev4a. This proves the container-per-agent model works.
 
-**Vault system:** A credentials vault (`/vault` page) stores API keys and service tokens with per-agent permissions. File-backed vault system (removed - sensitive data is env-only).
+**Credentials vault:** The `/credentials` page stores third-party service tokens in `credentials.db` and installs them into containers on explicit sync. Provider API keys live separately in `provider-keys.json`, managed from the Gateway UI.
 
-**Container management UI:** The `/containers` page lists all running Docker containers with resource usage, logs, and quick links. Fully functional.
+**Container management UI:** The `/containers` page lists all running Docker containers with resource usage and quick links, and opens a web terminal into any of them. Fully functional.
 
 **Workspace API:** Lazy-loaded file tree explorer with real-time reads (no caching), supports both host and container workspaces via `docker exec`.
 
@@ -80,8 +80,8 @@
 
 | Feature | Status | Notes |
 |---|---|---|
-| Vault (UI + API) | 🟢 Implemented | SQLite + JSON, no encryption yet |
-| Container page | 🟢 Functional | Lists all containers, logs, resources |
+| Credentials (UI + API) | 🟢 Implemented | SQLite, no encryption yet |
+| Container page | 🟢 Functional | Lists all containers, resources, web terminal |
 | Agent creation wizard | 🟢 Implemented | One-click create with model/template selection |
 | Provider proxy | 🟢 Implemented | Agents route through Rev4a provider gateway |
 | Shared volumes | 🟢 Implemented | Skills + repos mounted on all agents |
@@ -103,7 +103,7 @@ The central container, running the Next.js dashboard + orchestration API.
 - Centralized credential management
 - Docker socket access for container management
 - SQLite DB for cross-container event monitoring
-- **Onboarding wizard** — first-run setup flow at `/onboarding`, tracks progress in `data/onboarding-progress.json`
+- **First-run wizard** — setup flow at `/wizard`; completion is recorded in `<data dir>/data/wizard.json` and read through `GET /api/wizard/status`
 
 **Volume mounts (target):**
 ```
@@ -120,6 +120,49 @@ The central container, running the Next.js dashboard + orchestration API.
 - Immutable by agents — enforced by the `:ro` mount
 - See `lib/agent-setup.ts` for the centralized volume + config guarantee logic
 
+**Running commands inside containers** (`lib/docker-exec.ts`):
+
+This module is how a route reaches an agent container. The migration to it is
+not finished — routes predating it still shell out directly — so treat these as
+the rules for anything you touch, not as a description of the whole tree:
+
+- **Never `execSync`/`execFileSync` in a request path.** They block Node's single
+  thread: while one runs, no other request is served and no agent's stream
+  advances. A `docker exec` costs ~90 ms warm and the OpenClaw CLI costs
+  seconds, so a route that walks the fleet freezes the event loop for the sum of
+  all of them. Use `dockerExec` / `dockerExecShell` and their `…NoFail` variants.
+- **`mapWithConcurrency` is fail-fast, like `Promise.all`.** If the mapped
+  function rejects for one item, the whole call rejects and results already
+  computed for other containers are discarded. Fanning out over a fleet requires
+  the `…NoFail` variants, or an explicit per-item try/catch, so one unreachable
+  container cannot blank an entire page. Callers: `app/api/skills/route.js`,
+  `app/api/gateway/route.ts`, `app/api/agents/channels-summary/route.ts`,
+  `lib/openclaw-cron.ts`, `app/api/credentials/detect/route.ts`,
+  `lib/credentials/delivery.ts`.
+- **Never interpolate a secret into a command string.** Pass it through the `env`
+  option and reference it as `"$KEY"`; command substitution inside an
+  interpolated value would otherwise execute on the host. Only the *name* reaches
+  argv, as `docker exec -e KEY` — docker forwards the value from its own
+  environment, so it appears neither in the host process table nor in any
+  rejection built from that argv.
+- **A timeout does not reject.** `docker exec` exits 0 on the SIGTERM Node sends
+  when the deadline passes, so a command killed halfway *resolves* with whatever
+  it had already printed. A `try/catch` therefore cannot tell a truncated read
+  from a complete one. Where that distinction matters, make the script prove it
+  finished — `detect.ts` emits a `probe:complete` sentinel before its slow calls,
+  `containerRead` prints a terminator after the file — and treat its absence as
+  failure. Anything that writes back what it read must refuse to write when the
+  proof is missing.
+- **A rejection carries `stderr`, never the command.** Node's own message is
+  `Command failed: <argv…>`, which reproduces whatever was interpolated into the
+  script. `dockerExec` replaces it with `docker exec <container>: <cause> —
+  <stderr>`, because these messages travel: `syncProfileToAgents` puts one into
+  `SyncResult.error` and the sync route returns it to the browser.
+
+`dockerExecWithInput` uses `spawn` rather than `execFile` because
+`promisify(exec)` silently ignores an `input` option: the process starts, stdin
+is never written, and the command hangs with no error to point at.
+
 ### 3.2 Agent Container Template (`openclaw-agent-base`)
 
 Docker image for every agent container.
@@ -196,30 +239,34 @@ detailed documentation.
 
 ## 4. Credential Management (Vault)
 
-Provider API keys are stored in `data/provider-keys.json`. Third-party service credentials
-(GitHub, Trello, Vercel, Supabase) are stored in `data/credentials.db` (SQLite).
-At agent spawn time, Rev4a injects only the credentials the agent is permitted to use.
-
-```json
-{
-  "providers": {
-    "openai-codex": "sk-...",
-    "anthropic": "sk-ant-...",
-    "groq": "gsk_..."
-  },
-  "services": {
-    "github": { "token": "***", "user": "Flame0510" },
-    "vercel": { "token": "***", "team": "flame0510" }
-  },
-  "agent_permissions": {
-    "argus": ["providers:all", "services:github", "services:vercel"],
-    "atlas": ["providers:openai-codex", "services:github"],
-    "prometheus": ["providers:openai-codex"]
-  }
-}
-```
+Two separate stores:
+
+- **Provider API keys** — `<data dir>/data/provider-keys.json`, used by the Rev4a
+  provider proxy.
+- **Third-party service credentials** — `<data dir>/data/credentials.db` (SQLite),
+  managed from the Credentials page. Five providers: `github-pat`, `trello`,
+  `vercel`, `supabase`, `notion` (`lib/credentials/providers.ts`).
+
+**Secrets are stored unencrypted.** `credential_secrets.payload` holds raw JSON.
+Anything able to read that file, or to reach `POST /api/credentials/[id]/reveal`
+with a valid session, obtains them in the clear. Encryption (AES-256-GCM, or an
+external vault) is not implemented.
+
+**Delivery is explicit, not automatic.** Creating an agent installs nothing: a
+credential reaches a container only when the user syncs it
+(`POST /api/credentials/[id]/sync`), and leaves only on de-sync
+(`DELETE /api/credentials/[id]/sync`). There is no per-agent permission model —
+any stored credential can be synced to any container. Delivery writes each CLI's
+own config inside the container (`lib/credentials/delivery.ts`); OpenClaw's
+`secrets` subsystem covers only OpenClaw's own configuration credentials and
+offers nothing for third-party CLIs.
+
+`GET /api/credentials/detect` reports which credentials are actually installed,
+by SHA-256 hashing the token found in each container and matching it against the
+stored profiles.
 
-**Current implementation:** SQLite (`credentials.db`) for services, JSON file (`provider-keys.json`) for provider keys (no encryption yet). Future: encrypted with AES-256-GCM or integrated with HashiCorp Vault / Vaultwarden.
+**Planned:** encryption at rest, and a per-agent permission model so a credential
+can be restricted to a subset of agents.
 
 ---
 
@@ -568,7 +615,7 @@ for the full rationale.
 | Database | SQLite (WAL mode) | Current `events.db`, may need to scale |
 | Memory | Per-agent SQLite + central index | New |
 | Config | Generated YAML/JSON | New |
-| Vault | SQLite + JSON | Current: credentials.db + provider-keys.json. Future: encrypted |
+| Credential stores | SQLite + JSON | credentials.db for service tokens, provider-keys.json for provider API keys. Neither is encrypted |
 | Reverse proxy | Traefik | Already in use |
 | Monitoring | Rev4a daemon (extended) | Evolution of current daemon |
 | Version control | Git + GitHub | `github.com/Flame0510/rev4a.git` |

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-07-19
+> **Last updated:** 2026-08-28
 
 ## Layering
 
@@ -41,11 +41,12 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
 | `Icons` | `Icons.tsx` | SVG icons (`EyeIcon`, `EyeOffIcon`), 16/20px shared. |
 | `PasswordInput` | `PasswordInput.tsx` | Password input with inline show/hide toggle (`<button type="button">` with `aria-label`). |
-| `OnboardingPageClient` + step components | `app/onboarding/PageClient.tsx` | 4-step wizard (`WelcomeStep`, `ProvidersStep`, `AgentsStep`, `DoneStep`) + `WizardFrame` shell with mobile-first CSS. |
-| `useOnboarding` | `app/onboarding/useOnboarding.ts` | Shared hook: onboarding state, step transitions, provider save, restart. Receives server-side initial state to avoid loading flash. |
-| `OnboardingIcons` | `app/onboarding/icons.tsx` | Shared SVG icons (flyweight pattern): `ArrowRightIcon`, `CheckIcon`, `DockerIcon`, `GatewayIcon`, etc. |
+| `WizardPageClient` + step components | `app/wizard/PageClient.tsx` | Multi-step first-run wizard plus its frame shell, with mobile-first CSS. |
+| `useWizard` | `app/wizard/useWizard.ts` | Shared hook: wizard state, step transitions, provider save, restart. Receives server-side initial state to avoid a loading flash. |
+| Wizard icons | `app/wizard/icons.tsx` | Shared SVG icons (flyweight pattern): `ArrowRightIcon`, `CheckIcon`, `CheckCircleIcon`, `DockerIcon`, `GatewayIcon`, `AgentIcon`, `TemplateIcon`, `LinkIcon`, `ConfigIcon`, `InformationIcon`. |
 | `tokens` | `tokens.ts` | TypeScript types for `Tone` and related token values. |
 | `Badge` | `Badge.tsx` | Inline status tag with tone variants (success, danger, warning, neutral). Used for channel chips, pairing labels, error/success messages. |
+| `Skeleton` + shape helpers | `app/components/Skeleton.tsx` | Shimmer placeholders. `Skeleton` is the primitive; the rest mirror one specific layout each: `TreeSkeleton`, `CodeSkeleton`, `CronJobsSkeleton`, `CronRunsSkeleton`, `CredentialCardsSkeleton`, `AgentSyncRowsSkeleton`, `SkeletonLines`, `SkeletonMetric`, `CardRowSkeleton`. A shape helper must match the real markup it stands in for — same row structure, same paddings, same element count where the count is known — so nothing reflows when data replaces it. |
 
 ### Rules
 
@@ -53,8 +54,12 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 2. **No inline styles on interactive elements.** Buttons, inputs, selects use the `app/components/ui/*` component with component props. Only layout/wrapping containers use inline style.
 3. **No Italian in code, labels, or comments.** UI strings, error messages, aria-labels — all English.
 4. **Clickable/custom interactive elements must be `<button type="button">`.** Not `<span onClick>`, not `<div onClick>`. Always include `aria-label` for icon-only buttons.
+4a. **A control gated on another field stays visible and disabled** — never conditionally unmounted. Rendering it only once its dependency is filled makes it appear out of nowhere, and any hint that references it is pointing at something not on screen. Show it disabled, with the reason beside it, so the shape of the form is stable from the first render.
 5. **Modals inside forms** — close button has `type="button"` to prevent accidental form submission.
-6. **Loading buttons** — set `loading={true}` on `Button`, do not render separate loaders next to the button. The spinner is built-in.
+6. **Loading buttons** — set `loading={true}` on `Button`, do not render separate loaders next to the button. The spinner is built-in. The label must also change for the duration (`Saving…`, `Deleting…`, `Syncing…`).
+6a. **One in-flight mutation, keyed.** Hold a single `busy` string identifying the running action (`delete:<id>`, `sync:<id>:<container>`), plus a `useRef` mirror as the authoritative guard — state is read from the render that produced the click, so two fast clicks would otherwise both pass. `loading` compares against the exact key; `disabled` is set for any busy value, so a control that would be refused looks refused. Never key a mutation on one dimension when the same control is rendered per row of another: a key holding only a container name puts every profile's button for that container into a spinner.
+6b. **Do not hold the lock across a slow refresh.** Release it when the mutation itself completes and refresh derived state afterwards, unawaited. Show the pending state by fading the stale values only — never the buttons, since `opacity` on an ancestor cannot be undone by a child and makes live controls read as disabled.
+6c. **An optimistic update moves every field the render derives from, together.** A row that decides its state by reading two fields against each other flips to a third, wrong state if the update touches only one of them — and holds it until the slow refresh lands. Update the whole set the derivation reads, or none of it.
 7. **New UI component** — add it to `app/components/ui/`, export from `index.ts`, document it here. If it's specific to one page, keep it page-local unless another page needs it.
 
 ## GoF pattern mapping
@@ -108,6 +113,9 @@ For interactive pages that can change view/file/tab quickly:
 2. Guard against stale updates after `await` boundaries.
 3. On navigation/context switch, kill in-flight requests before starting new ones.
 4. Mobile layout changes must not wait on network completion.
+5. After a mutation, refresh the cheap endpoint and await it; fire the expensive one without awaiting. A page that re-reads everything makes the user wait on work their change did not need.
+6. A refresh helper invoked from a mutation must never reject. The mutation has already succeeded by then, so a failed re-read surfacing as the caller's error reports a completed action as failed.
+7. Check `res.ok` before reading the body. An error response is still valid JSON, so `json.items ?? []` silently turns a 401 into an empty result presented as fact.
 
 ## Migration rule
 

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-08-09
+> **Last updated:** 2026-09-05
 
 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) |
 | `/config` | Environment management and server restart |
-| `/vault` | Credential storage (per-agent permissions) — see [PROVIDERS.md](dev/PROVIDERS.md) |
 | `/login` | Authentication page |
 
 ---
@@ -261,19 +260,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`)