@flame0510/project-aether 1.1.12 → 1.1.13

package/app/components/ui/ModalityIcons.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+/**
+ * Modality badges for a model.
+ *
+ * Reads the `modality` string that ships in models.config.json (and matches
+ * OpenRouter's `architecture.modality` format verbatim), e.g.
+ *   "text+image+file->text"        → accepts text, images, files
+ *   "text+image+file+audio+video->text+image"  → also *produces* images
+ *
+ * Inputs are shown as icons; a non-text output is called out separately,
+ * since "can read an image" and "can generate an image" are very different
+ * capabilities and collapsing them would be misleading.
+ */
+
+interface ModalitySpec {
+  label: string;
+  icon: React.ReactNode;
+}
+
+const ICONS: Record<string, ModalitySpec> = {
+  text: {
+    label: 'Text',
+    icon: (
+      <svg viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round">
+        <path d="M3 4h10M3 8h10M3 12h6" />
+      </svg>
+    ),
+  },
+  image: {
+    label: 'Images',
+    icon: (
+      <svg viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="1.4">
+        <rect x="2" y="3" width="12" height="10" rx="1.5" />
+        <circle cx="6" cy="6.5" r="1.2" />
+        <path d="M3 11.5l3.2-3 2.3 2.2 2-1.8 2.5 2.6" strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+    ),
+  },
+  file: {
+    label: 'Files / PDF',
+    icon: (
+      <svg viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinejoin="round">
+        <path d="M9 2H4.5A1.5 1.5 0 0 0 3 3.5v9A1.5 1.5 0 0 0 4.5 14h7a1.5 1.5 0 0 0 1.5-1.5V6z" />
+        <path d="M9 2v4h4" />
+      </svg>
+    ),
+  },
+  audio: {
+    label: 'Audio',
+    icon: (
+      <svg viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round">
+        <path d="M8 2.5v11" />
+        <path d="M5 5.5v5M11 5.5v5" />
+        <path d="M2.5 7.5v1M13.5 7.5v1" />
+      </svg>
+    ),
+  },
+  video: {
+    label: 'Video',
+    icon: (
+      <svg viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinejoin="round">
+        <rect x="2" y="4" width="8.5" height="8" rx="1.5" />
+        <path d="M10.5 8l3.5-2v6l-3.5-2z" />
+      </svg>
+    ),
+  },
+};
+
+export interface ParsedModality {
+  inputs: string[];
+  outputs: string[];
+}
+
+/** Split "text+image->text+image" into its input and output lists. */
+export function parseModality(modality: string | undefined | null): ParsedModality | null {
+  if (!modality || typeof modality !== 'string') return null;
+  const [rawIn, rawOut] = modality.split('->');
+  if (!rawIn) return null;
+  const split = (s: string) => s.split('+').map((p) => p.trim()).filter(Boolean);
+  return { inputs: split(rawIn), outputs: rawOut ? split(rawOut) : [] };
+}
+
+/** Own-property lookup: a token like "constructor" must not resolve to Object.prototype. */
+function iconFor(token: string): ModalitySpec | null {
+  return Object.hasOwn(ICONS, token) ? ICONS[token] : null;
+}
+
+interface ModalityIconsProps {
+  modality?: string | null;
+  /**
+   * Router models (OpenRouter Auto) advertise the union of everything they
+   * might route to, which reads as a guarantee it isn't. They already show
+   * "Dynamic" for price; capabilities get the same treatment rather than
+   * concrete icons.
+   */
+  dynamic?: boolean;
+}
+
+export default function ModalityIcons({ modality, dynamic }: ModalityIconsProps) {
+  if (dynamic) {
+    return (
+      <span
+        title="Routed to a different model per request — capabilities vary"
+        style={{ fontSize: 10, color: 'var(--text-dim)', fontStyle: 'italic' }}
+      >
+        varies
+      </span>
+    );
+  }
+
+  const parsed = parseModality(modality);
+  if (!parsed) return null;
+
+  // Anything the model can produce beyond plain text is worth surfacing:
+  // only 15 of 422 upstream models do, and "reads images" vs "makes images"
+  // are very different capabilities.
+  const generates = parsed.outputs.filter((o) => o !== 'text');
+
+  return (
+    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 5, verticalAlign: 'middle' }}>
+      {parsed.inputs.map((input) => {
+        const spec = iconFor(input);
+        if (!spec) return null;
+        return (
+          <span
+            key={input}
+            title={`Accepts ${spec.label.toLowerCase()}`}
+            aria-label={`Accepts ${spec.label.toLowerCase()}`}
+            style={{ display: 'inline-flex', color: 'var(--text-dim)', opacity: 0.75 }}
+          >
+            {spec.icon}
+          </span>
+        );
+      })}
+
+      {generates.map((out) => {
+        const spec = iconFor(out);
+        if (!spec) return null;
+        return (
+          <span
+            key={`out-${out}`}
+            title={`Generates ${spec.label.toLowerCase()}`}
+            aria-label={`Generates ${spec.label.toLowerCase()}`}
+            style={{
+              display: 'inline-flex', alignItems: 'center', gap: 2,
+              color: 'var(--violet)', fontSize: 9, fontWeight: 600,
+            }}
+          >
+            <span aria-hidden="true">→</span>
+            {spec.icon}
+          </span>
+        );
+      })}
+    </span>
+  );
+}

package/app/components/ui/index.ts

@@ -17,3 +17,4 @@ export * from './tokens';
 export * from './Tabs';
 export * from './ItemList';
 export * from './TemplateOption';
+export { default as ModalityIcons, parseModality, type ParsedModality } from './ModalityIcons';

package/app/gateway/PageClient.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { Button, ConfirmModal, LoadingSpinner, Metric, Page, PageHeader, Pill, Surface, Tabs, type Tone } from '../components/ui';
+import { Button, ConfirmModal, Input, LoadingSpinner, Metric, ModalityIcons, Page, PageHeader, Pill, Surface, Tabs, type Tone } from '../components/ui';
 import PasswordInput from '../components/PasswordInput';
 import { Skeleton } from '../components/Skeleton';
 
@@ -14,6 +14,12 @@ interface ModelInfo {
   id: string;
   name: string;
   enabled: boolean;
+  /** USD per 1M tokens. -1/-1 means the model routes dynamically. */
+  pricing?: { input: number; output: number };
+  /** Set when the price came from the live OpenRouter catalogue, not the static file. */
+  pricingLive?: boolean;
+  /** e.g. "text+image+file->text" — curated, matches what sync.ts provisions. */
+  modality?: string;
 }
 
 interface GatewayProvider {
@@ -345,6 +351,9 @@ export default function GatewayPageClient() {
   const [revealedKeys, setRevealedKeys] = useState<Record<string, string | null>>({});
   const [revealing, setRevealing] = useState<Record<string, boolean>>({});
 
+  // Per-provider model filter (purely local, no requests)
+  const [modelSearch, setModelSearch] = useState<Record<string, string>>({});
+
   // Agent edit state
   const [editingAgent, setEditingAgent] = useState<string | null>(null);
   const [agentModelInput, setAgentModelInput] = useState('');
@@ -431,6 +440,24 @@ export default function GatewayPageClient() {
     return `${f(p.input)} / ${f(p.output)}`;
   }
 
+  /**
+   * Local model filter. Matches against both the display name and the id,
+   * because the upstream vendor often only appears in one of them — e.g.
+   * "Kimi K2 (OR)" has id `openrouter/moonshotai/kimi-k2`, so searching
+   * either "kimi" or "moonshot" has to find it.
+   *
+   * Every whitespace-separated term must match somewhere, so "kimi code"
+   * narrows rather than widening.
+   */
+  function filterModels<T extends { id: string; name: string }>(models: T[], query: string): T[] {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0) return models;
+    return models.filter((m) => {
+      const haystack = `${m.name} ${m.id}`.toLowerCase();
+      return terms.every((t) => haystack.includes(t));
+    });
+  }
+
   /* ---- Overlay helper ---- */
   async function withOverlay<T>(message: string, fn: () => Promise<T>): Promise<T> {
     setOverlay({ active: true, message });
@@ -904,33 +931,93 @@ export default function GatewayPageClient() {
                     )}
 
                     {/* Models with checkboxes */}
-                    {p.models.length > 0 && (
+                    {p.models.length > 0 && (() => {
+                      const query = modelSearch[p.provider] || '';
+                      const visibleModels = filterModels(p.models, query);
+                      // Below this many, everything fits on screen and a
+                      // search box is just noise.
+                      const showSearch = p.models.length > 6;
+                      return (
                       <div style={{ borderTop: '1px solid var(--border)', paddingTop: 12 }}>
-                        <div style={{ fontSize: 11, color: 'var(--text-dim)', marginBottom: 8, textTransform: 'uppercase', letterSpacing: '0.06em' }}>
-                          Models
-                          <span style={{ marginLeft: 8, textTransform: 'none', letterSpacing: 'normal', color: 'var(--violet)', opacity: 0.7, fontSize: 10 }}>
-                            in / out per 1M tokens
-                          </span>
+                        <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between', gap: 8, marginBottom: 8, flexWrap: 'wrap' }}>
+                          <div style={{ fontSize: 11, color: 'var(--text-dim)', textTransform: 'uppercase', letterSpacing: '0.06em' }}>
+                            Models
+                            <span style={{ marginLeft: 8, textTransform: 'none', letterSpacing: 'normal', color: 'var(--violet)', opacity: 0.7, fontSize: 10 }}>
+                              in / out per 1M tokens
+                            </span>
+                          </div>
+                          {query && (
+                            <span style={{ fontSize: 10, color: 'var(--text-dim)' }}>
+                              {visibleModels.length} of {p.models.length}
+                            </span>
+                          )}
                         </div>
+
+                        {showSearch && (
+                          <div style={{ marginBottom: 8 }}>
+                            {/* Deliberately type="text": Safari clears type="search"
+                                on Escape via a `search` event React never sees,
+                                leaving an empty box over a still-filtered list. */}
+                            <Input
+                              type="text"
+                              value={query}
+                              placeholder="Filter by name or provider — e.g. kimi, moonshot, flash"
+                              aria-label={`Filter ${p.label} models`}
+                              onChange={(e) => setModelSearch((prev) => ({ ...prev, [p.provider]: e.target.value }))}
+                            />
+                          </div>
+                        )}
+
                         <div style={{ display: 'grid', gap: 4, maxHeight: 360, overflowY: 'auto' }}>
-                          {p.models.map((m) => {
+                          {visibleModels.length === 0 && (
+                            <div style={{ fontSize: 12, color: 'var(--text-dim)', padding: '8px 4px' }}>
+                              No model matches “{query}”.
+                            </div>
+                          )}
+                          {visibleModels.map((m) => {
                             const modelMsg = messages[`model-${m.id}`];
+                            const pricing = m.pricing;
+                            // -1/-1 is OpenRouter's marker for router models,
+                            // whose price and capabilities both vary per call.
+                            const isDynamic = pricing?.input === -1 && pricing?.output === -1;
                             return (
-                              <label key={m.id} style={{
-                                display: 'flex', alignItems: 'center', gap: 10, padding: '5px 8px', borderRadius: 0,
+                              // Only the name/id are inside the <label>: clicking
+                              // anywhere in a label toggles its checkbox, and the
+                              // badges below carry tooltips people will click to
+                              // read — which would silently flip the model and
+                              // restart every agent container.
+                              <div key={m.id} style={{
+                                display: 'flex', alignItems: 'center', gap: 10, padding: '5px 8px',
                                 background: m.enabled ? 'rgba(var(--green-rgb,34,197,94),0.06)' : 'transparent',
-                                cursor: overlay.active ? 'wait' : 'pointer', fontSize: 12,
+                                fontSize: 12,
                               }}>
                                 <input type="checkbox" checked={m.enabled} disabled={overlay.active}
+                                  id={`model-${m.id}`}
                                   onChange={(e) => handleToggleModel(m.id, e.target.checked)}
                                   style={{ accentColor: 'var(--green)', cursor: 'pointer' }} />
-                                <div style={{ flex: 1 }}>
-                                  <div style={{ fontWeight: m.enabled ? 500 : 400 }}>{m.name}</div>
+                                <div style={{ flex: 1, minWidth: 0 }}>
+                                  <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
+                                    <label
+                                      htmlFor={`model-${m.id}`}
+                                      style={{ fontWeight: m.enabled ? 500 : 400, cursor: overlay.active ? 'wait' : 'pointer' }}
+                                    >
+                                      {m.name}
+                                    </label>
+                                    <ModalityIcons modality={m.modality} dynamic={isDynamic} />
+                                  </div>
                                   <div style={{ fontSize: 11, color: 'var(--text-dim)', fontFamily: 'monospace' }}>
                                     {m.id}
                                     <span style={{ marginLeft: 8, color: 'var(--violet)', fontWeight: 500 }}>
-                                      {fmtPrice((m as any).pricing)}
+                                      {fmtPrice(pricing)}
                                     </span>
+                                    {m.pricingLive && (
+                                      <span
+                                        title="Live price from the OpenRouter API"
+                                        style={{ marginLeft: 6, display: 'inline-block', verticalAlign: 'middle' }}
+                                      >
+                                        <Pill tone="success">LIVE</Pill>
+                                      </span>
+                                    )}
                                   </div>
                                 </div>
                                 {modelMsg && (
@@ -938,12 +1025,13 @@ export default function GatewayPageClient() {
                                     {modelMsg.text}
                                   </span>
                                 )}
-                              </label>
+                              </div>
                             );
                           })}
                         </div>
                       </div>
-                    )}
+                      );
+                    })()}
 
                     {msg && (
                       <div className={msg.type === 'success' ? 'msg-success' : 'msg-error'}>

package/bin/rev4a.js

@@ -29,8 +29,14 @@ const os = require('os');
 const ROOT = join(__dirname, '..');
 const NEXT_DIR = join(ROOT, '.next');
 const PKG_JSON = join(ROOT, 'package.json');
-// Config lives outside the npm package so it survives npm update / reinstall
-const CONFIG_DIR = join(os.homedir(), '.config', 'rev4a');
+// Config lives outside the npm package so it survives npm update / reinstall.
+// REV4A_DATA_DIR must be honoured here exactly as rev4aDataDir() honours it in
+// lib/rev4a-paths.ts: this file creates the shared directories that the app then
+// bind-mounts into agents, so a divergence would have serve writing the system
+// rules to one path while every agent mounted another — silently empty.
+// It can only come from the real process environment, never from the .env file:
+// that file is looked up under this very directory.
+const CONFIG_DIR = process.env.REV4A_DATA_DIR || join(os.homedir(), '.config', 'rev4a');
 const DATA_DIR = join(CONFIG_DIR, 'data');
 const ENV_SOURCE = join(CONFIG_DIR, '.env');
 const ENV_LINK = join(ROOT, '.env');
@@ -213,14 +219,26 @@ function ensureNetwork() {
 // ── Rev4a system rules ───────────────────────────────────────────────────
 
 function ensureRev4aRules() {
-  // Ensure all Rev4a host directories exist (shared-skills, rev4a-rules, …).
-  // Defined centrally in lib/agent-setup so create & recreate routes stay in sync.
+  // These must mirror SHARED_SKILLS_DIR / REV4A_RULES_DIR in lib/rev4a-paths.ts.
+  // This file is CommonJS and runs before .next exists (it is what builds it),
+  // so it cannot import from lib/ — same reason CONFIG_DIR is recomputed above.
+  //
+  // It previously tried `require('.next/server/lib/agent-setup.js')` to reuse
+  // ensureHostDirs(). Next bundles route code and never emits that path, so the
+  // require always threw into an empty catch and the directories were never
+  // created here at all.
+  const sharedDir = join(CONFIG_DIR, 'shared');
+  const sharedSkillsDir = join(sharedDir, 'shared-skills');
+  const rev4aRulesDir = join(sharedDir, 'rev4a-rules');
+
   try {
-    const { ensureHostDirs } = require(join(ROOT, '.next', 'server', 'lib', 'agent-setup.js'));
-    if (typeof ensureHostDirs === 'function') ensureHostDirs();
-  } catch { /* .next not built yet — dirs may already exist */ }
+    mkdirSync(sharedSkillsDir, { recursive: true });
+    mkdirSync(rev4aRulesDir, { recursive: true });
+  } catch (err) {
+    log('RULES', `⚠ Could not create shared directories: ${err.message}`);
+    return;
+  }
 
-  const rev4aRulesDir = '/docker/rev4a-rules';
   const ruleFile = join(rev4aRulesDir, 'AGENTS.md');
   const source = join(ROOT, 'rev4a-rules', 'AGENTS.md');
 
@@ -241,14 +259,10 @@ function ensureRev4aRules() {
   }
 
   try {
-    const sudo = isRoot() ? '' : 'sudo ';
-    if (!existsSync(rev4aRulesDir)) {
-      execSync(`${sudo}mkdir -p ${rev4aRulesDir}`);
-    }
-    const tmpFile = `/tmp/rev4a-rules-${Date.now()}.md`;
-    writeFileSync(tmpFile, sourceContent, 'utf-8');
-    execSync(`${sudo}cp ${tmpFile} ${ruleFile} && ${sudo}rm ${tmpFile}`);
-    log('RULES', 'Deployed rev4a system rules to /docker/rev4a-rules/');
+    // Direct write — the old /tmp + `sudo cp` + `sudo rm` dance was only
+    // needed because the destination sat outside the user's home.
+    writeFileSync(ruleFile, sourceContent, 'utf-8');
+    log('RULES', `Deployed rev4a system rules to ${rev4aRulesDir}/`);
   } catch (err) {
     log('RULES', `⚠ Failed to deploy rev4a rules: ${err.message}`);
   }
@@ -539,14 +553,11 @@ const args = process.argv.slice(2);
 const cmd = args[0];
 
 const BANNER = `
-                                ██
-   ███████╗  ██╗      █████╗   ██╗
-  ██╔═══██╗ ██║     ██╔══██╗  ██║
-  ██║   ██║ ██║     ████████║  ██║
-  ██║   ██║ ██║     ██╔════╝  ██║
-  ███████╔╝ ██████╗ ██║       ██║
-  ╚══════╝  ╚═════╝ ╚═╝       ╚═╝
-                               
+  ████   █████  █   █  █   █   ███
+  █   █  █      █   █  █   █  █   █
+  ████   ████   █   █  █████  █████
+  █  █   █       █ █       █  █   █
+  █   █  █████    █        █  █   █
 `;
 
 const HELP_TEXT = `

package/docs/ARCHITECTURE.md

@@ -55,7 +55,7 @@
 │                                                                │
 │  ┌──────────────────────────────────────────────────────────┐  │
 │  │ SHARED VOLUMES                                           │  │
-│  │ • /docker/shared-skills → read-only on all agents        │  │
+│  │ • ~/.config/rev4a/shared/shared-skills → all agents (ro) │  │
 │  │ • /docker/shared-repos  → shared project repos           │  │
 │  └──────────────────────────────────────────────────────────┘  │
 │  └──────────────────────────────────────────────────────────┘  │
@@ -107,14 +107,14 @@ The central container, running the Next.js dashboard + orchestration API.
 
 **Volume mounts (target):**
 ```
-/path/to/rev4a/data          → /data (persistent)
-/var/run/docker.sock            → /var/run/docker.sock
-/docker/shared-skills           → /data/.openclaw/shared-skills (ro)
-/docker/shared-repos            → /data/repos (rw)
+/path/to/rev4a/data                   → /data (persistent)
+/var/run/docker.sock                  → /var/run/docker.sock
+~/.config/rev4a/shared/shared-skills  → /data/.openclaw/shared-skills (ro)
+/docker/shared-repos                  → /data/repos (rw)
 ```
 
 **Rev4a System Rules** (`rev4a-rules/AGENTS.md`):
-- Versioned in the repo, deployed to `/docker/rev4a-rules/` on every `rev4a serve` start
+- Versioned in the repo, deployed to `~/.config/rev4a/shared/rev4a-rules/` on every `rev4a serve` start
 - Mounted read-only into every agent at `/root/.openclaw/workspace/.rev4a/AGENTS.md`
 - Injected into every session via the `bootstrap-extra-files` hook (glob `.rev4a/*.md`)
 - Immutable by agents — enforced by the `:ro` mount
@@ -132,9 +132,9 @@ copies the entrypoint script, and applies baseline gateway config patches.
 
 **Volume mounts (per agent):**
 ```
-/docker/shared-skills         → /data/.openclaw/shared-skills  (ro)
-/docker/rev4a-rules         → /root/.openclaw/workspace/.rev4a (ro)
-agent-{name}-data (named vol) → /root                            (rw, per-agent persistent state)
+~/.config/rev4a/shared/shared-skills  → /data/.openclaw/shared-skills    (ro)
+~/.config/rev4a/shared/rev4a-rules    → /root/.openclaw/workspace/.rev4a  (ro)
+agent-{name}-data (named vol)         → /root                             (rw, per-agent persistent state)
 ```
 
 All shared volumes are defined centrally in `lib/agent-setup.ts`
@@ -287,9 +287,9 @@ GET    /api/agents                 List all agents (Docker containers with AGENT
 
 ## 6. Shared Volumes
 
-### Shared Skills (`/docker/shared-skills`)
+### Shared Skills (`~/.config/rev4a/shared/shared-skills`)
 ```
-/docker/shared-skills/
+~/.config/rev4a/shared/shared-skills/
   my-custom-skill/    # promoted from an agent workspace
     SKILL.md
   another-skill/
@@ -306,12 +306,30 @@ This keeps the layout simple and avoids hierarchy debates at this stage.
 **Auto-configuration:**
 - The agent base image (`openclaw-agent-base`) pre-configures `skills.load.extraDirs: ["/data/.openclaw/shared-skills"]` so every new agent discovers shared skills automatically.
 - Both create and recreate routes guarantee this via `applyRuntimeConfig()` from `lib/agent-setup.ts`.
-- On first install, create `/docker/shared-skills` with `mkdir -p /docker/shared-skills && chmod 2775 /docker/shared-skills`.
+- No manual setup: `rev4a serve` creates both shared directories during
+  preflight (`ensureRev4aRules()` in `bin/rev4a.js`). They live under
+  `REV4A_DATA`, so a plain `mkdir` suffices — no `sudo`, no permission
+  bits to set.
+
+> These directories used to live at `/docker/shared-skills` and
+> `/docker/rev4a-rules`, which needed `sudo` on Linux and could not exist at
+> all on macOS — the root volume is a sealed APFS system volume, so `/docker`
+> is not creatable even as root, and agent creation failed with
+> `mounts denied`. Being under the user's home also puts them inside the
+> directories Docker Desktop shares with its Linux VM by default, so bind
+> mounts work with no extra configuration.
+>
+> Upgrading an existing install: move any promoted skills from
+> `/docker/shared-skills` into the new location, then hit **Recreate** on each
+> agent so its container picks up the new mount source. Containers freeze
+> their mounts at creation time, so running agents keep using the old path
+> until recreated. `rev4a-rules/AGENTS.md` needs no migration — it is
+> regenerated from the package on every start.
 
 ### Rev4a System Rules (`rev4a-rules/`)
 
 Versioned in the repo at `rev4a-rules/AGENTS.md`. Deployed to
-`/docker/rev4a-rules/` on every `rev4a serve` startup via
+`~/.config/rev4a/shared/rev4a-rules/` on every `rev4a serve` startup via
 `ensureRev4aRules()` in `bin/rev4a.js`. Mounted read-only into every
 agent container and injected into sessions through the
 `bootstrap-extra-files` hook (glob `.rev4a/*.md`).

package/docs/FRONTEND-ARCHITECTURE.md

@@ -34,6 +34,7 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `PropertyList` | `PropertyList.tsx` | 2-column grid for label/value pairs. Children rendered as `<Fragment>` — do not wrap in extra `<div>`. |
 | `TemplateOption` | `TemplateOption.tsx` | Agent template selection card with avatar, description, optional badge. Centralises create-agent card styling. |
 | `Pill` | `Pill.tsx` | Small status/attribute label. Variants: `default`, `accent`. |
+| `ModalityIcons` | `ModalityIcons.tsx` | Capability badges parsed from a model's `modality` string (`"text+image->text"`). Input types render as icons; a non-text **output** is called out separately, since reading an image and generating one are different capabilities. Pass `dynamic` for router models, which advertise the union of everything they might route to and so show "varies" instead. |
 | `Metric` | `Metric.tsx` | Metric card with title, value, subtitle, tone. |
 | `StatusCard` | `StatusCard.tsx` | Health/status report card. |
 | `Surface` | `Surface.tsx` | Shared panel/card surface, variant prop. |

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-07-27
+> **Last updated:** 2026-08-09
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -52,15 +52,24 @@ A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
 ### Environment
 
-Rev4a reads the following environment variables. Set them in `/config` (UI) or directly in `.env`.
+Rev4a reads the following environment variables. Set them in `/config` (UI) or directly in `.env`. See [.env.example](../.env.example) for the canonical, always-current list.
 
 | Variable | Required | Description |
 |---|---|---|
 | `REV4A_PASSWORD` | Yes | Login password for the dashboard |
 | `REV4A_TOKEN` | Yes | Token used for programmatic API access |
 | `REV4A_JWT_SECRET` | Yes | Secret used to sign session JWT tokens |
-| `REV4A_DB` | No | Path to the events database (default: `data/events.db`) |
+| `REV4A_API_KEY` | No | API key for the Gateway provider endpoint (auto-generated) |
+| `GATEWAY_TOKEN` | No | Shared token handed to agent containers |
+| `REV4A_DATA_DIR` | No | Root of all persistent data (default: `~/.config/rev4a`) |
+| `REV4A_DB` | No | Path to the events database (default: `<data dir>/data/events.db`) |
+| `REV4A_CREDENTIALS_DB` | No | Path to the credentials vault database |
 | `REV4A_WORKSPACE_ROOT` | No | Filesystem path for the local file explorer |
+| `REV4A_ROOT` | No | Installation root, used by `rev4a update` to detect a git checkout |
+| `REV4A_TIMEZONE` | No | IANA timezone used for scheduling and timestamps |
+| `REV4A_FORCE_INSECURE_COOKIE` | No | Allow a non-Secure session cookie — plain-HTTP deployments only |
+
+See [Alerts](#alerts-telegram) below for the Telegram alert variables.
 
 ## Agent creation
 
@@ -138,6 +147,29 @@ REV4A_JWT_SECRET=***  # Secret for signing JWTs
 
 ---
 
+## Alerts (Telegram)
+
+Rev4a can send Telegram alerts when the events database goes stale (no
+recent writes — see `/api/system-health`). Implemented in `lib/alerts.ts`.
+
+**Env vars:**
+```
+REV4A_ALERTS_ENABLED=false        # Master switch — no alerts sent unless "true"
+REV4A_TELEGRAM_BOT_TOKEN=         # Telegram bot token
+REV4A_TELEGRAM_CHAT_ID=           # Telegram chat to notify
+REV4A_ALERT_COOLDOWN_MS=600000    # Minimum time between repeat alerts for the same condition
+REV4A_ALERT_STALE_SECONDS=120     # How long without a DB write before the system is considered stale
+REV4A_ALERT_SMOKE=false           # Set true to send a one-off test alert on startup
+```
+
+**Behavior:**
+- If `REV4A_ALERTS_ENABLED` is not `"true"`, `maybeSendAlert` is a no-op — nothing is sent, nothing is recorded.
+- If enabled but `REV4A_TELEGRAM_BOT_TOKEN` or `REV4A_TELEGRAM_CHAT_ID` is missing, alerts run in **dry-run**: state transitions are still recorded in the `alert_state` table (SQLite), but no Telegram message is sent — visible in server logs as `[alerts] dry-run`.
+- Alert state (`ok` / `alerted` / `resolved`) is tracked per `alert_key` in `alert_state`, so a resolved condition sends a follow-up "✅ resolved" message instead of staying silent.
+- `REV4A_ALERT_COOLDOWN_MS` prevents repeat-sending the same stale alert while the condition persists.
+
+---
+
 ## Service Management
 
 ```bash
@@ -167,8 +199,6 @@ Environment=REV4A_PASSWORD=***
 Environment=REV4A_TOKEN=***
 Environment=REV4A_JWT_SECRET=***
 Environment=REV4A_DB=/path/to/rev4a/data/events.db
-Environment=OPENCLAW_CONFIG_PATH=/path/to/openclaw-core.json
-Environment=SHARED_CONTEXT_DIR=/path/to/shared-context
 Environment=NODE_ENV=production
 Environment=NEXT_TELEMETRY_DISABLED=1
 ```
@@ -498,7 +528,7 @@ curl -b /tmp/cookies.txt -X PUT http://localhost:3740/api/workspace \
 ├── public/                  # Static assets
 ├── scripts/                 # Utility scripts (setup, helpers)
 ├── .env                     # Local env vars (gitignored)
-├── proxy.ts                  # Auth proxy
+├── proxy.ts                    # Auth gate — redirects to /login without a valid JWT cookie
 ├── next.config.mjs
 └── package.json
 ```

package/docs/dev/API-REFERENCE.md

@@ -197,6 +197,11 @@ Returns current provider configuration state.
 
 **Auth:** any auth method
 
+**Query params:**
+| Param | Effect |
+|---|---|
+| `summary=1` | Returns only `{ provider, label, configured }` per provider — no `models`, no `pricing`, no `apiKey`. The full response awaits live pricing from OpenRouter, a network round trip costing ~2.4s on a cold cache; callers that only need to know whether *any* provider is configured should use this. |
+
 **Response:**
 ```json
 {
@@ -1562,7 +1567,7 @@ Enable or disable a plugin.
 ## Skills
 
 Skill discovery across three sources:
-- **Shared:** skills in `/docker/shared-skills` on the VPS host (global, available to all agents)
+- **Shared:** skills in `~/.config/rev4a/shared/shared-skills` on the VPS host (global, available to all agents)
 - **Workspace:** skills in `<workspace>/skills` inside each agent container (discovered via `docker exec`)
 - **Bundled:** skills shipped with OpenClaw (read-only)
 
@@ -1578,8 +1583,8 @@ List all available skills from all sources.
     {
       "name": "code-review",
       "type": "shared",
-      "path": "/docker/shared-skills/code-review",
-      "skillMdPath": "/docker/shared-skills/code-review/SKILL.md",
+      "path": "~/.config/rev4a/shared/shared-skills/code-review",
+      "skillMdPath": "~/.config/rev4a/shared/shared-skills/code-review/SKILL.md",
       "hasSkillMd": true,
       "description": "Systematic code review patterns...",
       "version": "1.0"
@@ -1643,7 +1648,7 @@ Copy a skill from an agent's workspace to the shared skills directory, making it
   "skillName": "my-custom-skill",
   "agentId": "atlas",
   "containerName": "openclaw-atlas",
-  "destPath": "/docker/shared-skills/my-custom-skill",
+  "destPath": "~/.config/rev4a/shared/shared-skills/my-custom-skill",
   "overwritten": false,
   "extraCopied": 0
 }