@flame0510/project-aether 1.1.11 → 1.1.13

package/docs/dev/GATEWAY.md

@@ -227,6 +227,11 @@ Updates model config for a single agent container (primary model only).
 
 Returns current provider configuration state.
 
+Add `?summary=1` for a cheap variant — `{ provider, label, configured }` only,
+skipping the live-pricing fetch. Used by the agents page, which needs nothing
+more than "is any provider configured" and shouldn't block on a network call to
+OpenRouter to find out.
+
 **Response:**
 ```json
 {
@@ -237,13 +242,49 @@ Returns current provider configuration state.
       "configured": true,
       "baseUrl": "https://api.deepseek.com",
       "models": [
-        { "id": "deepseek/deepseek-v4-flash", "name": "DeepSeek V4 Flash", "enabled": true }
+        {
+          "id": "deepseek/deepseek-v4-flash",
+          "name": "DeepSeek V4 Flash",
+          "enabled": true,
+          "pricing": { "input": 0.05, "output": 0.10 },
+          "pricingLive": true,
+          "modality": "text->text"
+        }
       ]
     }
   ]
 }
 ```
 
+`pricing` is USD per 1M tokens. `-1 / -1` means the model routes dynamically
+(OpenRouter Auto) — the UI renders "Dynamic" and shows "varies" for
+capabilities rather than concrete icons.
+
+#### Live pricing
+
+`model-pricing.json` is maintained by hand and drifts — 16 of 79 OpenRouter
+entries were wrong when this was added, one understating the real cost ~8x.
+`lib/openrouter-pricing.ts` overlays the live catalogue on top of it and sets
+`pricingLive: true` on the models it covers, which the UI marks with a `LIVE`
+pill.
+
+- Endpoint: `GET https://openrouter.ai/api/v1/models` — public, no API key,
+  CDN-cached, never billed.
+- Scope: **only** models whose provider is `openrouter`. The same model sold
+  direct (openai, anthropic, google…) has different rates, so applying
+  OpenRouter's price there would show the wrong vendor's number.
+- Cache mirrors what the endpoint itself declares: `max-age=300` for
+  freshness, `stale-if-error=3600` as the upper bound past which a stale
+  entry is dropped in favour of the static file. Failures back off for a
+  minute instead of retrying on every request.
+- Skipped entirely when OpenRouter isn't configured, so callers that only
+  read `configured` (the agents page) don't wait on a network round trip.
+- `modality` is **not** taken from upstream. `sync.ts` provisions agent
+  containers from the curated `models.config.json` value, so a different
+  capability set in the UI would advertise inputs the container never
+  accepted. (`moonshotai/kimi-k3` currently differs: `text+image` curated
+  vs `text+image+video` upstream.)
+
 ---
 
 ## Config Page (`/config`)

package/docs/dev/PROVIDERS.md

@@ -218,9 +218,10 @@ Key points:
 
 ## Security Notes
 
-- The `GET /api/vault/provider/key` endpoint is protected by the authentication
-  middleware (browser cookie or bearer token). Only authenticated users can reveal
-  keys.
+- The `GET /api/vault/provider/key` endpoint calls `requireAuthJWT` directly
+  (browser cookie or bearer token) — API routes are never covered by `proxy.ts`
+  (it explicitly exempts `/api/*`), so each route must guard itself. Only
+  authenticated users can reveal keys.
 - The UI **must never** log, screenshot, or otherwise persist the revealed key
   outside the active screen view.
 - All secrets in documentation, logs, or reports must be masked (e.g. `sk-...ast4`).

package/docs/rag/REV4A-OVERVIEW.md

@@ -87,7 +87,7 @@ Browse installed OpenClaw plugins. Enable/disable toggle per plugin. Plugins ext
 
 ### Skills (`/skills`)
 Skill registry showing all skills across three sources:
-- **Shared** — global skills from `/docker/shared-skills`, available to all agents
+- **Shared** — global skills from `~/.config/rev4a/shared/shared-skills`, available to all agents
 - **Per-agent** — skills in each agent's workspace (`<workspace>/skills`), shown with agent label
 - **Bundled** — skills shipped with OpenClaw (read-only)
 

package/instrumentation.ts

@@ -0,0 +1,18 @@
+/**
+ * Next.js instrumentation hook — runs once at server startup.
+ *
+ * Syncs the provider gateway baseUrl to all agent containers on boot.
+ * This ensures agents pick up any domain/env changes after a restart,
+ * VPS reboot, or crash recovery — no manual Sync button needed.
+ */
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    try {
+      const { syncAllAgents } = await import('./app/api/gateway/sync');
+      syncAllAgents();
+    } catch {
+      // Best-effort — don't block startup if sync fails
+      console.warn('[rev4a] Failed to sync agents on startup');
+    }
+  }
+}

package/lib/agent-setup.ts

@@ -10,6 +10,7 @@
 
 import { execSync } from 'child_process';
 import * as fs from 'fs';
+import { SHARED_SKILLS_DIR, REV4A_RULES_DIR } from '@/lib/rev4a-paths';
 
 // ── Volumes ──────────────────────────────────────────────────────────────────
 
@@ -28,12 +29,12 @@ export interface Rev4aVolume {
  */
 export const REV4A_VOLUMES: Rev4aVolume[] = [
   {
-    source: '/docker/shared-skills',
+    source: SHARED_SKILLS_DIR,
     target: '/data/.openclaw/shared-skills',
     mode: 'ro',
   },
   {
-    source: '/docker/rev4a-rules',
+    source: REV4A_RULES_DIR,
     target: '/root/.openclaw/workspace/.rev4a',
     mode: 'ro',
   },
@@ -60,14 +61,12 @@ export function getMountFlags(): string[] {
  * multiple times.
  */
 export function ensureHostDirs(): void {
+  // Plain mkdir: these now live under the user's own data directory, so no
+  // elevation is needed. The previous `sudo mkdir` with a plain fallback was
+  // only required because the paths sat at the filesystem root, and it could
+  // hang on a password prompt when run non-interactively.
   for (const vol of REV4A_VOLUMES) {
-    if (!fs.existsSync(vol.source)) {
-      try {
-        execSync(`sudo mkdir -p ${escapeShell(vol.source)}`, { stdio: 'pipe' });
-      } catch {
-        execSync(`mkdir -p ${escapeShell(vol.source)}`, { stdio: 'pipe' });
-      }
-    }
+    fs.mkdirSync(vol.source, { recursive: true });
   }
 }
 

package/lib/buildAgentImage.ts

@@ -193,7 +193,11 @@ async function pullFromRegistry(
 
     child.on('error', (err: Error) => {
       appendLog(`Pull process error: ${err.message}`);
-      releaseLock();
+      // Do NOT release the lock here: the caller falls through to
+      // localBuild(), which must stay protected. Releasing early let a
+      // concurrent request past getIsDownloading() and start a second
+      // `docker build` against the same tag. The lock is released by
+      // localBuild's own close/error handlers, or by the success path.
       resolve(false);
     });
   });

package/lib/db.ts

@@ -1,19 +1,9 @@
 // Shared DB helpers for API routes
 import Database from 'better-sqlite3';
-import type { NextRequest } from 'next/server';
-import { NextResponse } from 'next/server';
 import { initializeRev4aDb } from './db-bootstrap.mjs';
 import { DB_FILE } from './rev4a-paths';
 
 export const DB_PATH = process.env.REV4A_DB || DB_FILE;
-export const TOKEN = process.env.REV4A_TOKEN ?? '';
-
-export function requireAuth(request: NextRequest): NextResponse | null {
-  const token = new URL(request.url).searchParams.get('token');
-  const auth = request.headers.get('authorization');
-  const ok = token === TOKEN || auth === `Bearer ${TOKEN}`;
-  return ok ? null : NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-}
 
 export function ensureDbReady(): void {
   initializeRev4aDb(DB_PATH);

package/lib/docker-socket.ts

@@ -0,0 +1,121 @@
+/**
+ * Docker Engine API over its local unix socket.
+ *
+ * The socket path is NOT the same everywhere. `/var/run/docker.sock` is the
+ * Linux default (and what the VPS uses), but Docker Desktop on macOS puts it
+ * at `~/.docker/run/docker.sock` and does not create the /var/run symlink
+ * unless the user opts in. Hardcoding the Linux path made every read-only
+ * Docker route return an empty list on macOS — agents existed and ran, but
+ * the dashboard showed nothing, because creation shells out to the `docker`
+ * CLI (which reads the context) while listing went through this socket.
+ *
+ * Talking to the socket directly is preferred over shelling out for reads:
+ * no fork, no shell quoting, no `--format` template to parse — just JSON.
+ */
+import * as http from 'http';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+
+let cached: string | null = null;
+let lastMissAt = 0;
+
+/**
+ * How long a failed resolution is remembered. Long enough that a Docker outage
+ * doesn't spawn a `docker context inspect` per request, short enough that a
+ * server which started before the Docker daemon picks it up on its own.
+ */
+const MISS_TTL_MS = 5000;
+
+function fromDockerHostEnv(): string | null {
+  const raw = process.env.DOCKER_HOST;
+  if (!raw) return null;
+  // Only unix sockets are usable here; tcp:// would need a different client.
+  if (!raw.startsWith('unix://')) return null;
+  return raw.slice('unix://'.length);
+}
+
+function fromDockerContext(): string | null {
+  try {
+    const out = execFileSync(
+      'docker',
+      ['context', 'inspect', '--format', '{{.Endpoints.docker.Host}}'],
+      { encoding: 'utf-8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    return out.startsWith('unix://') ? out.slice('unix://'.length) : null;
+  } catch {
+    return null;
+  }
+}
+
+function usable(candidate: string | null): string | null {
+  if (!candidate) return null;
+  try {
+    fs.accessSync(candidate, fs.constants.R_OK | fs.constants.W_OK);
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the Docker socket, most authoritative source first. Returns null when
+ * Docker isn't reachable at all.
+ *
+ * A success is cached for the life of the process — the path doesn't move. A
+ * failure is only cached for MISS_TTL_MS: Rev4a can legitimately start before
+ * the Docker daemon is up (systemd ordering, Docker Desktop still booting), and
+ * caching that failure permanently would leave every Docker route returning an
+ * empty list until someone restarted the server.
+ */
+export function resolveDockerSocket(): string | null {
+  if (cached) return cached;
+  if (Date.now() - lastMissAt < MISS_TTL_MS) return null;
+
+  const found =
+    usable(fromDockerHostEnv()) ??
+    usable(fromDockerContext()) ??
+    // Docker Desktop (macOS, and Windows with WSL integration)
+    usable(path.join(os.homedir(), '.docker', 'run', 'docker.sock')) ??
+    // Linux default — the VPS lands here
+    usable('/var/run/docker.sock');
+
+  if (found) cached = found;
+  else lastMissAt = Date.now();
+
+  return found;
+}
+
+/** True when a usable Docker socket exists. */
+export function dockerAvailable(): boolean {
+  return resolveDockerSocket() !== null;
+}
+
+/**
+ * GET/POST against the Docker Engine API, resolving the response as JSON.
+ * Rejects when Docker is unreachable or the payload isn't JSON.
+ */
+export function dockerFetch<T = any>(method: string, apiPath: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const socketPath = resolveDockerSocket();
+    if (!socketPath) {
+      reject(new Error('Docker socket not found'));
+      return;
+    }
+
+    const req = http.request(
+      { socketPath, path: apiPath, method, headers: { Host: 'localhost' } },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          try { resolve(JSON.parse(data) as T); }
+          catch { reject(new Error('Invalid JSON from Docker')); }
+        });
+      },
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}

package/lib/openrouter-pricing.ts

@@ -0,0 +1,184 @@
+/**
+ * Live pricing for OpenRouter-hosted models.
+ *
+ * model-pricing.json is maintained by hand and drifts: at the time this was
+ * written, 16 of 79 OpenRouter entries disagreed with the live catalogue —
+ * one of them (google/gemini-2.5-flash) understated the real cost by ~8x.
+ * The static file stays as the offline fallback; this overlays it when the
+ * catalogue is reachable.
+ *
+ * Scope is deliberately narrow: only models whose provider is `openrouter`.
+ * OpenRouter resells models that we ALSO offer direct (openai, anthropic,
+ * google, …) at different rates, so applying these prices to a direct
+ * provider entry would show the wrong vendor's price.
+ *
+ * Only pricing is taken from upstream — NOT modality. app/api/gateway/sync.ts
+ * provisions agent containers from the curated models.config.json value, so
+ * showing a different capability set in the UI would advertise inputs the
+ * container was never configured to accept.
+ *
+ * The endpoint is public (no API key, served from CDN) — calling it costs
+ * nothing and is never billed.
+ */
+
+const CATALOGUE_URL = 'https://openrouter.ai/api/v1/models';
+// The call measures ~300ms against the CDN, so 3s is ~10x headroom. A longer
+// limit wouldn't protect anything — it would just hold the response open when
+// the catalogue is unreachable, and the static file is a fine stand-in.
+const FETCH_TIMEOUT_MS = 3000;
+
+// Mirrors the cache policy OpenRouter declares on the endpoint itself:
+//   cache-control: public, max-age=300, stale-while-revalidate=3600, stale-if-error=3600
+const TTL_MS = 5 * 60 * 1000; // max-age=300
+const MAX_STALE_MS = 60 * 60 * 1000; // stale-if-error=3600
+// After a failure, don't retry on every single request — an unreachable
+// catalogue would otherwise make each one pay the full abort timeout.
+const RETRY_AFTER_FAILURE_MS = 60 * 1000;
+
+export interface LivePricing {
+  input: number; // USD per 1M prompt tokens
+  output: number; // USD per 1M completion tokens
+}
+
+interface OpenRouterModel {
+  id: string;
+  pricing?: { prompt?: string; completion?: string };
+}
+
+interface CacheEntry {
+  pricing: Map<string, LivePricing>;
+  fetchedAt: number;
+}
+
+let cache: CacheEntry | null = null;
+let lastFailureAt = 0;
+let inFlight: Promise<CacheEntry | null> | null = null;
+
+/** OpenRouter quotes per-token; the UI works in per-million. */
+function perMillion(raw: string | undefined): number | null {
+  if (!raw) return null;
+  const n = parseFloat(raw);
+  // -1 means "dynamic" (router models); not a real price, leave it to the
+  // static file which already encodes it as -1/-1 and renders as "Dynamic".
+  if (!Number.isFinite(n) || n < 0) return null;
+  return n * 1_000_000;
+}
+
+async function fetchCatalogue(): Promise<CacheEntry | null> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(CATALOGUE_URL, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) {
+      console.warn(`[openrouter-pricing] catalogue returned HTTP ${res.status}`);
+      return null;
+    }
+
+    const body = (await res.json()) as { data?: OpenRouterModel[] };
+    if (!Array.isArray(body?.data)) {
+      console.warn('[openrouter-pricing] unexpected catalogue shape');
+      return null;
+    }
+
+    const pricing = new Map<string, LivePricing>();
+    for (const m of body.data) {
+      if (!m?.id) continue;
+      const input = perMillion(m.pricing?.prompt);
+      const output = perMillion(m.pricing?.completion);
+      if (input !== null && output !== null) pricing.set(m.id, { input, output });
+    }
+
+    if (pricing.size === 0) return null;
+    return { pricing, fetchedAt: Date.now() };
+  } catch (e) {
+    const reason = e instanceof Error ? e.name : 'unknown';
+    console.warn(`[openrouter-pricing] catalogue unreachable (${reason}) — using static prices`);
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function isUsable(entry: CacheEntry | null): entry is CacheEntry {
+  // Past stale-if-error we stop trusting it entirely and fall back to the
+  // static file, rather than labelling day-old numbers as live.
+  return !!entry && Date.now() - entry.fetchedAt < MAX_STALE_MS;
+}
+
+/**
+ * Cached catalogue, refreshed when stale. Concurrent callers share one
+ * in-flight request. A failure is remembered so an unreachable catalogue
+ * doesn't make every request pay the timeout; the previous entry keeps
+ * being served until it exceeds the stale-if-error window.
+ */
+async function getCatalogue(): Promise<CacheEntry | null> {
+  const fresh = cache && Date.now() - cache.fetchedAt < TTL_MS;
+  if (fresh) return cache;
+
+  if (inFlight) return inFlight;
+
+  // Backing off after a recent failure — serve what we have, if still usable.
+  if (Date.now() - lastFailureAt < RETRY_AFTER_FAILURE_MS) {
+    return isUsable(cache) ? cache : null;
+  }
+
+  inFlight = fetchCatalogue()
+    .then((result) => {
+      if (result) {
+        cache = result;
+        lastFailureAt = 0;
+      } else {
+        lastFailureAt = Date.now();
+      }
+      return isUsable(cache) ? cache : null;
+    })
+    .finally(() => {
+      inFlight = null;
+    });
+
+  return inFlight;
+}
+
+/**
+ * Map one of our ids to the upstream one.
+ *
+ * Our catalogue namespaces OpenRouter entries as `openrouter/<upstream id>`,
+ * but OpenRouter also publishes its own house models under a literal
+ * `openrouter/` vendor prefix (`openrouter/auto`, `openrouter/auto-beta`, …).
+ * Stripping unconditionally turns `openrouter/auto` into `auto`, which does
+ * not exist upstream — so try the stripped form first and fall back to the
+ * id as-is.
+ */
+function candidateUpstreamIds(modelId: string): string[] {
+  if (!modelId.startsWith('openrouter/')) return [];
+  const stripped = modelId.slice('openrouter/'.length);
+  return stripped === modelId ? [modelId] : [stripped, modelId];
+}
+
+/**
+ * Pricing overlay keyed by OUR model ids, for the OpenRouter-hosted subset.
+ * Returns an empty map when the catalogue can't be reached — never throws.
+ */
+export async function getLivePricing(modelIds: string[]): Promise<Map<string, LivePricing>> {
+  const overlay = new Map<string, LivePricing>();
+
+  const wanted = modelIds.filter((id) => id.startsWith('openrouter/'));
+  if (wanted.length === 0) return overlay;
+
+  const catalogue = await getCatalogue();
+  if (!catalogue) return overlay;
+
+  for (const ourId of wanted) {
+    for (const upstreamId of candidateUpstreamIds(ourId)) {
+      const price = catalogue.pricing.get(upstreamId);
+      if (price) {
+        overlay.set(ourId, price);
+        break;
+      }
+    }
+  }
+  return overlay;
+}

package/lib/rev4a-auth.d.ts

@@ -1,3 +1,6 @@
 import { NextResponse } from "next/server";
-export function requireAuth(request: Request): NextResponse | null;
 export function requireAuthJWT(request: Request): Promise<NextResponse | null>;
+export function requireAuthIfConfigured(request: Request): Promise<NextResponse | null>;
+export function getPassword(): string;
+export function getJwtSecret(): string;
+export function isConfigured(): boolean;

package/lib/rev4a-auth.js

@@ -1,36 +1,84 @@
 import { NextResponse } from "next/server";
 import { jwtVerify } from "jose";
+import * as fs from "fs";
+import { ENV_FILE } from "@/lib/rev4a-paths";
 
-function getExpectedToken() {
-  const token = process.env.REV4A_TOKEN || process.env.NEXT_PUBLIC_REV4A_TOKEN || '';
-  if (!token) console.warn('REV4A_TOKEN is not set — auth will reject all requests');
-  return token;
+// ---------------------------------------------------------------------------
+// Single source of truth for secret resolution. Every route and proxy.ts
+// import these instead of keeping their own env+file-fallback copy — the
+// duplication used to drift (proxy.ts had an env-only version because it
+// used to run on Edge runtime, which can't use fs; now that it runs on
+// Node.js runtime the split serves no purpose and only risks desync).
+//
+// In the supported `rev4a serve` flow the file fallback is rarely hit:
+// bin/rev4a.js injects these into the Next.js child's env, and writeEnvVar()
+// updates process.env in-process. It exists for setups that bypass the CLI
+// (a hand-written systemd unit, `npm run dev` before .env exists).
+// ---------------------------------------------------------------------------
+const PASSWORD_RE = /^REV4A_PASSWORD=(.*)$/m;
+const JWT_SECRET_RE = /^REV4A_JWT_SECRET=(.*)$/m;
+
+function readEnvFileValue(re) {
+  try {
+    if (fs.existsSync(ENV_FILE)) {
+      const match = fs.readFileSync(ENV_FILE, "utf-8").match(re);
+      if (match && match[1].trim()) return match[1].trim();
+    }
+  } catch { /* ignore */ }
+  return "";
 }
 
-export function requireAuth(request) {
-  const auth = request.headers.get("authorization");
-  if (!auth || auth !== `Bearer ${getExpectedToken()}`) {
-    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-  }
-  return null;
+export function getPassword() {
+  return process.env.REV4A_PASSWORD || readEnvFileValue(PASSWORD_RE);
 }
 
-const JWT_SECRET = new TextEncoder().encode(
-  process.env.REV4A_JWT_SECRET || ''
-);
+export function getJwtSecret() {
+  return process.env.REV4A_JWT_SECRET || readEnvFileValue(JWT_SECRET_RE);
+}
 
+export function isConfigured() {
+  return getPassword().length > 0;
+}
+
+function unauthorized() {
+  return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+}
+
+/**
+ * Cookie (JWT) auth, falling back to `Authorization: Bearer <REV4A_TOKEN>`.
+ * Returns null when authorized, or a 401 response to return as-is.
+ */
 export async function requireAuthJWT(request) {
   const cookieToken = request.cookies?.get?.("rev4a_token")?.value;
-  if (cookieToken) {
+  const secret = getJwtSecret();
+
+  // An empty secret would mean verifying against a zero-length HMAC key.
+  // jose rejects that, but bail explicitly rather than relying on it.
+  if (cookieToken && secret) {
     try {
-      await jwtVerify(cookieToken, JWT_SECRET);
+      await jwtVerify(cookieToken, new TextEncoder().encode(secret));
       return null;
-    } catch {}
+    } catch { /* fall through to bearer */ }
+  }
+
+  const expectedToken = process.env.REV4A_TOKEN || process.env.NEXT_PUBLIC_REV4A_TOKEN || "";
+  // Without this guard an unset token would make `Bearer ` match an empty
+  // expected value. HTTP header normalisation already strips the trailing
+  // space so it isn't reachable in practice — the guard makes that safety
+  // explicit instead of dependent on it.
+  if (expectedToken) {
+    const auth = request.headers.get("authorization");
+    if (auth === `Bearer ${expectedToken}`) return null;
   }
 
-  const auth = request.headers.get("authorization");
-  const expectedToken = process.env.REV4A_TOKEN || process.env.NEXT_PUBLIC_REV4A_TOKEN || '';
-  if (auth === `Bearer ${expectedToken}`) return null;
+  return unauthorized();
+}
 
-  return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+/**
+ * For routes that must stay reachable during first-run setup (before any
+ * password exists) but must be protected once the instance is configured.
+ */
+export async function requireAuthIfConfigured(request) {
+  if (!isConfigured()) return null;
+  return requireAuthJWT(request);
 }

package/lib/rev4a-paths.ts

@@ -39,6 +39,25 @@ export const AGENTS_TOKEN_FILE = path.join(REV4A_DATA, 'data', 'agents-token.jso
 /** Provider API keys JSON */
 export const PROVIDER_KEYS_FILE = path.join(REV4A_DATA, 'data', 'provider-keys.json');
 
+/* ── Host directories bind-mounted into every agent container ───── */
+
+/**
+ * These used to live at `/docker/shared-skills` and `/docker/rev4a-rules`.
+ * That path can't work on macOS: the root volume is a sealed APFS system
+ * volume, so `/docker` cannot be created even as root. It also required
+ * `sudo mkdir` on Linux for no real benefit.
+ *
+ * Under REV4A_DATA they sit inside the user's home, which additionally
+ * falls within the directories Docker Desktop shares with its Linux VM by
+ * default — so a bind mount from here works with no extra configuration.
+ */
+
+/** Skills shared across all agents, mounted read-only. */
+export const SHARED_SKILLS_DIR = path.join(REV4A_DATA, 'shared', 'shared-skills');
+
+/** Rev4a system rules injected into every agent workspace, mounted read-only. */
+export const REV4A_RULES_DIR = path.join(REV4A_DATA, 'shared', 'rev4a-rules');
+
 /**
  * Model catalogue — read-only, shipped with the package.
  * Resolved at module load from the package root (alongside bin/rev4a.js).