shadow-claw 1.23.4 → 1.24.0

package/bin/utils/webrtc-control-client.test.mjs

@@ -0,0 +1,318 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  jest,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+} from "@jest/globals";
+
+import {
+  ensureWebRtcPolyfill,
+  CliWebRtcControlClient,
+  getOrCreateCliPeerId,
+  renewCliPeerId,
+  readCliPeerId,
+  getIpcFilePath,
+  writeIpcFile,
+  clearIpcFile,
+} from "./webrtc-control-client.mjs";
+
+describe("webrtc-control-client", () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = path.join(
+      os.tmpdir(),
+      "test-webrtc-peer-" +
+        Date.now() +
+        "-" +
+        Math.random().toString(36).slice(2),
+    );
+  });
+
+  afterEach(() => {
+    try {
+      if (fs.existsSync(tempDir)) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }
+    } catch (_) {}
+  });
+
+  it("initializes WebRTC polyfill in Node environment", async () => {
+    const ok = await ensureWebRtcPolyfill();
+    expect(ok).toBe(true);
+    expect(globalThis.RTCPeerConnection).toBeDefined();
+  });
+
+  it("constructs CliWebRtcControlClient with default options", () => {
+    const client = new CliWebRtcControlClient({
+      host: "127.0.0.1",
+      port: 8888,
+      peerId: "cli-test-peer",
+      cacheDir: tempDir,
+    });
+
+    expect(client.cliPeerId).toBe("cli-test-peer");
+    expect(client.host).toBe("127.0.0.1");
+    expect(client.port).toBe(8888);
+    expect(client.path).toBe("/");
+  });
+
+  it("creates, reads, and renews CLI peer IDs via helper functions", () => {
+    expect(readCliPeerId(tempDir)).toBe("");
+
+    const id1 = getOrCreateCliPeerId(undefined, tempDir);
+    expect(id1).toMatch(/^cli-[0-9a-z]+$/);
+    expect(readCliPeerId(tempDir)).toBe(id1);
+
+    // Subsequent call returns same
+    const id2 = getOrCreateCliPeerId(undefined, tempDir);
+    expect(id2).toBe(id1);
+
+    // Renewal generates new ID
+    const id3 = renewCliPeerId(undefined, tempDir);
+    expect(id3).not.toBe(id1);
+    expect(readCliPeerId(tempDir)).toBe(id3);
+
+    // Custom renewal
+    const custom = renewCliPeerId("my-special-peer", tempDir);
+    expect(custom).toBe("my-special-peer");
+    expect(readCliPeerId(tempDir)).toBe("my-special-peer");
+  });
+
+  it("CliWebRtcControlClient uses the stored persistent peer ID", () => {
+    const client = new CliWebRtcControlClient({ cacheDir: tempDir });
+    // Should auto-create and persist a cli-* ID
+    expect(client.cliPeerId).toMatch(/^cli-[0-9a-z]+$/);
+    // A second instance in the same dir reuses the same ID
+    const client2 = new CliWebRtcControlClient({ cacheDir: tempDir });
+    expect(client2.cliPeerId).toBe(client.cliPeerId);
+  });
+
+  it("CliWebRtcControlClient respects an explicit --peer-id override", () => {
+    const client = new CliWebRtcControlClient({
+      cacheDir: tempDir,
+      peerId: "cli-my-custom-id",
+    });
+    expect(client.cliPeerId).toBe("cli-my-custom-id");
+  });
+
+  it("CliWebRtcControlClient.listClients returns empty array when no listener is active", async () => {
+    const client = new CliWebRtcControlClient({ cacheDir: tempDir });
+    const clients = await client.listClients();
+    expect(clients).toEqual([]);
+  });
+
+  it("CliWebRtcControlClient.listClients retrieves connected clients from listener IPC socket", async () => {
+    const http = await import("node:http");
+    const { getIpcSocketPath } = await import("./webrtc-control-client.mjs");
+    const socketPath = getIpcSocketPath(tempDir);
+
+    fs.mkdirSync(tempDir, { recursive: true });
+    const mockClients = [
+      {
+        clientId: "browser-peer-1",
+        peerId: "browser-peer-1",
+        deviceLabel: "Chrome Browser",
+        capabilities: ["webrtc", "peerjs"],
+        version: "1.0.0",
+      },
+    ];
+
+    const server = http.createServer((req, res) => {
+      if (req.method === "GET" && req.url === "/ping") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true }));
+        return;
+      }
+      if (req.method === "GET" && req.url === "/clients") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true, clients: mockClients }));
+        return;
+      }
+      res.writeHead(404);
+      res.end();
+    });
+
+    await new Promise((resolve) => server.listen(socketPath, resolve));
+
+    try {
+      const client = new CliWebRtcControlClient({ cacheDir: tempDir });
+      const clients = await client.listClients();
+      expect(clients).toEqual(mockClients);
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  });
+});
+
+describe("IPC socket helpers", () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = path.join(
+      os.tmpdir(),
+      "test-webrtc-ipc-" +
+        Date.now() +
+        "-" +
+        Math.random().toString(36).slice(2),
+    );
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch (_) {}
+  });
+
+  it("getIpcFilePath returns the .sock path inside cacheDir", () => {
+    const p = getIpcFilePath(tempDir);
+    expect(p).toBe(path.join(tempDir, "webrtc-ipc.sock"));
+  });
+
+  it("writeIpcFile is a no-op (socket file is created by the server)", () => {
+    expect(() => writeIpcFile("/some/path.sock", tempDir)).not.toThrow();
+    // No file should be created
+    expect(fs.existsSync(getIpcFilePath(tempDir))).toBe(false);
+  });
+
+  it("clearIpcFile removes the socket file if it exists", () => {
+    const sockPath = getIpcFilePath(tempDir);
+    // Create a dummy socket file to simulate a running listener
+    fs.writeFileSync(sockPath, "");
+    expect(fs.existsSync(sockPath)).toBe(true);
+    clearIpcFile(tempDir);
+    expect(fs.existsSync(sockPath)).toBe(false);
+  });
+
+  it("clearIpcFile does not throw if socket file does not exist", () => {
+    expect(() => clearIpcFile(tempDir)).not.toThrow();
+  });
+});
+
+describe("CliWebRtcListener", () => {
+  let tempDir;
+  let CliWebRtcListener;
+
+  beforeEach(async () => {
+    tempDir = path.join(
+      os.tmpdir(),
+      "test-webrtc-listener-" +
+        Date.now() +
+        "-" +
+        Math.random().toString(36).slice(2),
+    );
+    // Dynamic import to pick up after initial module load
+    ({ CliWebRtcListener } = await import("./webrtc-control-client.mjs"));
+  });
+
+  afterEach(() => {
+    try {
+      if (fs.existsSync(tempDir)) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }
+    } catch (_) {}
+  });
+
+  it("constructs CliWebRtcListener with defaults and assigns a cli- peer ID", () => {
+    const listener = new CliWebRtcListener({ cacheDir: tempDir });
+    expect(listener.cliPeerId).toMatch(/^cli-[0-9a-z]+$/);
+    expect(listener.host).toBe("127.0.0.1");
+    expect(listener.port).toBe(8888);
+    expect(listener.path).toBe("/");
+    expect(listener.secure).toBe(false);
+    expect(listener.trustedPeerIds).toBeInstanceOf(Set);
+    expect(listener.trustedPeerIds.size).toBe(0);
+  });
+
+  it("constructs CliWebRtcListener with a fixed peer ID", () => {
+    const listener = new CliWebRtcListener({
+      cacheDir: tempDir,
+      peerId: "cli-fixed-peer",
+    });
+    expect(listener.cliPeerId).toBe("cli-fixed-peer");
+  });
+
+  it("populates trustedPeerIds from options", () => {
+    const listener = new CliWebRtcListener({
+      cacheDir: tempDir,
+      trustedPeerIds: ["browser-peer-1", "browser-peer-2"],
+    });
+    expect(listener.trustedPeerIds.has("browser-peer-1")).toBe(true);
+    expect(listener.trustedPeerIds.has("browser-peer-2")).toBe(true);
+    expect(listener.trustedPeerIds.size).toBe(2);
+  });
+
+  it("_isTrusted returns true for any peer when trustedPeerIds is empty", () => {
+    const listener = new CliWebRtcListener({ cacheDir: tempDir });
+    expect(listener._isTrusted("any-random-peer")).toBe(true);
+    expect(listener._isTrusted("cli-abc")).toBe(true);
+  });
+
+  it("_isTrusted returns true only for listed peers when trustedPeerIds is set", () => {
+    const listener = new CliWebRtcListener({
+      cacheDir: tempDir,
+      trustedPeerIds: ["browser-abc"],
+    });
+    expect(listener._isTrusted("browser-abc")).toBe(true);
+    expect(listener._isTrusted("browser-xyz")).toBe(false);
+    expect(listener._isTrusted("")).toBe(false);
+  });
+
+  it("_isTrusted supports wildcard suffix matching", () => {
+    const listener = new CliWebRtcListener({
+      cacheDir: tempDir,
+      trustedPeerIds: ["browser-*"],
+    });
+    expect(listener._isTrusted("browser-abc")).toBe(true);
+    expect(listener._isTrusted("browser-123")).toBe(true);
+    expect(listener._isTrusted("other-peer")).toBe(false);
+  });
+
+  it("close() before start() does not throw", () => {
+    const listener = new CliWebRtcListener({ cacheDir: tempDir });
+    expect(() => listener.close()).not.toThrow();
+  });
+
+  it("renewPeerId generates a fresh peer ID on construction", () => {
+    const listener1 = new CliWebRtcListener({ cacheDir: tempDir });
+    const listener2 = new CliWebRtcListener({
+      cacheDir: tempDir,
+      renewPeerId: true,
+    });
+    expect(listener2.cliPeerId).not.toBe(listener1.cliPeerId);
+  });
+
+  it("_scheduleReconnect implements exponential backoff and tracks attempts", () => {
+    const listener = new CliWebRtcListener({ cacheDir: tempDir });
+    listener._running = true;
+    const mockPeer = {
+      destroyed: false,
+      reconnect: jest.fn(),
+    };
+    listener._peer = mockPeer;
+
+    expect(listener._reconnectAttempts).toBe(0);
+    expect(listener._reconnectTimer).toBeNull();
+
+    // First schedule
+    listener._scheduleReconnect();
+    expect(listener._reconnectAttempts).toBe(1);
+    expect(listener._reconnectTimer).not.toBeNull();
+
+    // Scheduling again while timer is active is a no-op
+    listener._scheduleReconnect();
+    expect(listener._reconnectAttempts).toBe(1);
+
+    // Closing clears timer and resets attempts
+    listener.close();
+    expect(listener._reconnectAttempts).toBe(0);
+    expect(listener._reconnectTimer).toBeNull();
+  });
+});

package/dist/electron/main.cjs

@@ -30,7 +30,7 @@ t.exports=a,t.exports.append=r;var n=/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;function r
       keys_auth TEXT NOT NULL,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     )
-  `),ze)}function Ve(e=`mailto:admin@creativeindustrial.com`){if(!ze)throw Error(`Push store not opened. Call openPushStore() first.`);let t=ze.prepare(`SELECT * FROM vapid_keys WHERE id = 1`).get();if(t)return{publicKey:`${t.public_key}`,privateKey:`${t.private_key}`,subject:`${t.subject}`};let n=E.default.generateVAPIDKeys();return ze.prepare(`INSERT INTO vapid_keys (id, public_key, private_key, subject) VALUES (1, ?, ?, ?)`).run(n.publicKey,n.privateKey,e),{publicKey:n.publicKey,privateKey:n.privateKey,subject:e}}function He(e){if(!ze)throw Error(`Push store not opened.`);ze.prepare(`INSERT OR REPLACE INTO subscriptions (endpoint, keys_p256dh, keys_auth) VALUES (?, ?, ?)`).run(e.endpoint,e.keys.p256dh,e.keys.auth)}function Ue(e){if(!ze)throw Error(`Push store not opened.`);ze.prepare(`DELETE FROM subscriptions WHERE endpoint = ?`).run(e)}function We(e){if(!ze)throw Error(`Push store not opened.`);ze.prepare(`DELETE FROM subscriptions WHERE id = ?`).run(e)}function Ge(e){if(!ze)throw Error(`Push store not opened.`);let t=ze.prepare(`SELECT * FROM subscriptions WHERE endpoint = ?`).get(e);return t?{id:Number(t.id),endpoint:`${t.endpoint}`,keys_p256dh:`${t.keys_p256dh}`,keys_auth:`${t.keys_auth}`,created_at:`${t.created_at}`}:void 0}function Ke(){if(!ze)throw Error(`Push store not opened.`);let e=ze.prepare(`SELECT * FROM subscriptions ORDER BY created_at DESC`).all();return e?e.map(e=>({id:Number(e.id),endpoint:`${e.endpoint}`,keys_p256dh:`${e.keys_p256dh}`,keys_auth:`${e.keys_auth}`,created_at:`${e.created_at}`})):[]}async function qe(e){let t=Ke();if(t.length===0)return{sent:0,failed:0,noSubscribers:!0};let n=Ve(),r=JSON.stringify(e),i={TTL:3600,vapidDetails:{subject:n.subject,publicKey:n.publicKey,privateKey:n.privateKey}},a=0,o=0;return await Promise.all(t.map(async e=>{let t={endpoint:e.endpoint,keys:{p256dh:e.keys_p256dh,auth:e.keys_auth}};try{await E.default.sendNotification(t,r,i),a++}catch(t){o++,(t.statusCode===410||t.statusCode===404)&&Ue(e.endpoint)}})),{sent:a,failed:o}}function Je(e){e.get(`/push/vapid-public-key`,(e,t)=>{let n=Ve();t.json({publicKey:n.publicKey})}),e.post(`/push/subscribe`,(e,t)=>{let n=e.body;if(!n?.endpoint||!n?.keys)return t.status(400).json({error:`Invalid subscription object`});He(n),t.sendStatus(201)}),e.delete(`/push/subscribe`,(e,t)=>{let{endpoint:n}=e.body||{};if(!n)return t.status(400).json({error:`Missing endpoint`});Ue(n),t.sendStatus(200)}),e.get(`/push/subscriptions`,(e,t)=>{let n=Ke();t.json(n)}),e.post(`/push/send`,async(e,t)=>{let{endpoint:n,payload:r}=e.body||{};if(!n)return t.status(400).json({error:`Missing endpoint`});let i=Ge(n);if(!i)return t.status(404).json({error:`Subscription not found`});let a=Ve(),o={endpoint:i.endpoint,keys:{p256dh:i.keys_p256dh,auth:i.keys_auth}},s=JSON.stringify({title:`ShadowClaw`,body:r||`Test notification`}),c={TTL:3600,vapidDetails:{subject:a.subject,publicKey:a.publicKey,privateKey:a.privateKey}};try{await E.default.sendNotification(o,s,c),t.sendStatus(200)}catch(e){if(console.error(`Push send failed:`,e.message),e.statusCode===410||e.statusCode===404)return Ue(n),t.status(410).json({error:`Subscription expired, removed from store`});t.status(500).json({error:e.message})}}),e.delete(`/push/subscription/:id`,(e,t)=>{let n=parseInt(e.params.id,10);if(isNaN(n))return t.status(400).json({error:`Invalid subscription ID`});We(n),t.sendStatus(200)}),e.post(`/push/broadcast`,async(e,t)=>{let{title:n,body:r}=e.body||{};if(!r)return t.status(400).json({error:`Missing body`});try{let e=await qe({title:n||`ShadowClaw`,body:r});t.json(e)}catch(e){t.status(500).json({error:e.message})}})}let Ye=null;function Xe(e){return{id:`${e.id}`,group_id:`${e.group_id}`,schedule:`${e.schedule}`,type:e.type?`${e.type}`:null,prompt:`${e.prompt}`,tools:e.tools?`${e.tools}`:null,enabled:Number(e.enabled),last_run:e.last_run==null?null:Number(e.last_run),created_at:Number(e.created_at),channel:e.channel?`${e.channel}`:null,subscriber_id:e.subscriber_id?`${e.subscriber_id}`:null,name:e.name?`${e.name}`:null,task_order:e.task_order==null?null:Number(e.task_order)}}function Ze(e=`database/scheduled-tasks.db`){if(Ye)return Ye;Ye=new D.DatabaseSync(e),Ye.exec(`
+  `),ze)}function Ve(e=`mailto:admin@creativeindustrial.com`){if(!ze)throw Error(`Push store not opened. Call openPushStore() first.`);let t=ze.prepare(`SELECT * FROM vapid_keys WHERE id = 1`).get();if(t)return{publicKey:`${t.public_key}`,privateKey:`${t.private_key}`,subject:`${t.subject}`};let n=E.default.generateVAPIDKeys();return ze.prepare(`INSERT INTO vapid_keys (id, public_key, private_key, subject) VALUES (1, ?, ?, ?)`).run(n.publicKey,n.privateKey,e),{publicKey:n.publicKey,privateKey:n.privateKey,subject:e}}function He(e){if(!ze)throw Error(`Push store not opened.`);ze.prepare(`INSERT OR REPLACE INTO subscriptions (endpoint, keys_p256dh, keys_auth) VALUES (?, ?, ?)`).run(e.endpoint,e.keys.p256dh,e.keys.auth)}function Ue(e){if(!ze)throw Error(`Push store not opened.`);ze.prepare(`DELETE FROM subscriptions WHERE endpoint = ?`).run(e)}function We(e){if(!ze)throw Error(`Push store not opened.`);ze.prepare(`DELETE FROM subscriptions WHERE id = ?`).run(e)}function Ge(e){if(!ze)throw Error(`Push store not opened.`);let t=ze.prepare(`SELECT * FROM subscriptions WHERE endpoint = ?`).get(e);return t?{id:Number(t.id),endpoint:`${t.endpoint}`,keys_p256dh:`${t.keys_p256dh}`,keys_auth:`${t.keys_auth}`,created_at:`${t.created_at}`}:void 0}function Ke(){if(!ze)throw Error(`Push store not opened.`);let e=ze.prepare(`SELECT * FROM subscriptions ORDER BY created_at DESC, id DESC`).all();return e?e.map(e=>({id:Number(e.id),endpoint:`${e.endpoint}`,keys_p256dh:`${e.keys_p256dh}`,keys_auth:`${e.keys_auth}`,created_at:`${e.created_at}`})):[]}async function qe(e){let t=Ke();if(t.length===0)return{sent:0,failed:0,noSubscribers:!0};let n=Ve(),r=JSON.stringify(e),i={TTL:3600,vapidDetails:{subject:n.subject,publicKey:n.publicKey,privateKey:n.privateKey}},a=0,o=0;return await Promise.all(t.map(async e=>{let t={endpoint:e.endpoint,keys:{p256dh:e.keys_p256dh,auth:e.keys_auth}};try{await E.default.sendNotification(t,r,i),a++}catch(t){o++,(t.statusCode===410||t.statusCode===404)&&Ue(e.endpoint)}})),{sent:a,failed:o}}function Je(e){e.get(`/push/vapid-public-key`,(e,t)=>{let n=Ve();t.json({publicKey:n.publicKey})}),e.post(`/push/subscribe`,(e,t)=>{let n=e.body;if(!n?.endpoint||!n?.keys)return t.status(400).json({error:`Invalid subscription object`});He(n),t.sendStatus(201)}),e.delete(`/push/subscribe`,(e,t)=>{let{endpoint:n}=e.body||{};if(!n)return t.status(400).json({error:`Missing endpoint`});Ue(n),t.sendStatus(200)}),e.get(`/push/subscriptions`,(e,t)=>{let n=Ke();t.json(n)}),e.post(`/push/send`,async(e,t)=>{let{endpoint:n,payload:r}=e.body||{};if(!n)return t.status(400).json({error:`Missing endpoint`});let i=Ge(n);if(!i)return t.status(404).json({error:`Subscription not found`});let a=Ve(),o={endpoint:i.endpoint,keys:{p256dh:i.keys_p256dh,auth:i.keys_auth}},s=JSON.stringify({title:`ShadowClaw`,body:r||`Test notification`}),c={TTL:3600,vapidDetails:{subject:a.subject,publicKey:a.publicKey,privateKey:a.privateKey}};try{await E.default.sendNotification(o,s,c),t.sendStatus(200)}catch(e){if(console.error(`Push send failed:`,e.message),e.statusCode===410||e.statusCode===404)return Ue(n),t.status(410).json({error:`Subscription expired, removed from store`});t.status(500).json({error:e.message})}}),e.delete(`/push/subscription/:id`,(e,t)=>{let n=parseInt(e.params.id,10);if(isNaN(n))return t.status(400).json({error:`Invalid subscription ID`});We(n),t.sendStatus(200)}),e.post(`/push/broadcast`,async(e,t)=>{let{title:n,body:r}=e.body||{};if(!r)return t.status(400).json({error:`Missing body`});try{let e=await qe({title:n||`ShadowClaw`,body:r});t.json(e)}catch(e){t.status(500).json({error:e.message})}}),e.post(`/push/command`,async(e,t)=>{let{clientId:n,action:r,args:i,prompt:a}=e.body||{};if(!r)return t.status(400).json({error:`Missing action`});try{let e=await qe({type:`remote-command`,title:`ShadowClaw Command`,body:a||`Remote command: ${r}`,clientId:n,action:r,args:i});t.json(e)}catch(e){t.status(500).json({error:e.message})}})}let Ye=null;function Xe(e){return{id:`${e.id}`,group_id:`${e.group_id}`,schedule:`${e.schedule}`,type:e.type?`${e.type}`:null,prompt:`${e.prompt}`,tools:e.tools?`${e.tools}`:null,enabled:Number(e.enabled),last_run:e.last_run==null?null:Number(e.last_run),created_at:Number(e.created_at),channel:e.channel?`${e.channel}`:null,subscriber_id:e.subscriber_id?`${e.subscriber_id}`:null,name:e.name?`${e.name}`:null,task_order:e.task_order==null?null:Number(e.task_order)}}function Ze(e=`database/scheduled-tasks.db`){if(Ye)return Ye;Ye=new D.DatabaseSync(e),Ye.exec(`
     CREATE TABLE IF NOT EXISTS scheduled_tasks (
       id TEXT PRIMARY KEY,
       group_id TEXT NOT NULL,

package/dist/public/AGENTS.md

@@ -5,7 +5,7 @@
 
 ## Project Snapshot
 
-ShadowClaw is a browser-native AI assistant written in **TypeScript** (`.ts`).
+ShadowClaw is a browser-native AI assistant written in **TypeScript** (`.ts`) — deployable as a PWA, a native desktop app via Electron, a standalone Node.js server, and driven via the `shadow-claw` CLI (for builds, dev serving, and runtime agent interaction).
 The project uses a **Rolldown build pipeline** to bundle the application.
 
 **Stack:** HTML + TypeScript / ESM · Web Components · TC39 Signals · IndexedDB · OPFS · Web Workers · Service Worker (Workbox PWA · Web Push) · Express dev server · Electron desktop · AWS Bedrock · Jest + Playwright tests
@@ -44,6 +44,8 @@ ShadowClaw has been significantly deduplicated. Instead of a massive `AGENTS.md`
 | WebMCP Integration            | [docs/subsystems/webmcp.md](docs/subsystems/webmcp.md)                                   |
 | WebVM (v86 Alpine)            | [docs/subsystems/vm.md](docs/subsystems/vm.md)                                           |
 | CLI & Static Site Publishing  | [docs/subsystems/cli.md](docs/subsystems/cli.md)                                         |
+| Control Plane & Client Bridge | [docs/subsystems/control-plane.md](docs/subsystems/control-plane.md)                     |
+| File Backup Subsystem         | [docs/subsystems/backup.md](docs/subsystems/backup.md)                                   |
 
 ## Conventions & Guardrails
 
@@ -150,7 +152,7 @@ Markdown and HTML preview work should preserve the Settings-backed iframe host a
 ### CLI & Dual-Root Build Pipeline
 
 - **Dual-Root Path Resolution:** The build toolchain (`bin/build/build.mjs`) cleanly decouples `toolchainRoot` (the ShadowClaw package/repo root) from `contentRoot` (the consumer template project). In-repo builds (`resolve(contentRoot) === resolve(toolchainRoot)`) preserve the standalone in-tree compilation path. CLI/template consumer builds read pre-bundled web assets from `toolchainRoot/dist/public` and inject `pages/`, `site-config.json`, `assets/`, `.agents/`, and pretty routes from `contentRoot`, outputting to `<contentRoot>/dist/public`.
-- **CLI Commands (`bin/cli.mjs`):** The `shadow-claw` / `shadowclaw` CLI provides `build`, `dev`, `run`, `serve`, and `init` commands. It supports running dev servers programmatically via `startServer` (`src/server/server.ts`) with custom `--root-path` and `--database-dir` arguments.
+- **CLI Commands (`bin/cli.mjs`):** The `shadow-claw` / `shadowclaw` CLI provides `build`, `dev`, `run`, `serve`, `init`, `clients`, `send`, `backup`, `tasks`, `webrtc`, and `peer-id` commands. It supports running dev servers programmatically via `startServer` (`src/server/server.ts`) with custom `--root-path` and `--database-dir` arguments.
 - **Naming Conventions:** Refer to the product/brand in prose and documentation as **ShadowClaw**. Use kebab-case **`shadow-claw`** for package name, CLI commands (`npx shadow-claw`), repositories, directory paths, and custom elements.
 
 ## What to Avoid
@@ -162,7 +164,7 @@ Markdown and HTML preview work should preserve the Settings-backed iframe host a
 - **Do not** import Electron modules from browser-side `.ts` files — Electron is desktop-only.
 - **Do not** register or inject unapproved custom elements without configuring them through `site-config.json` or `setAllowedCustomElements`.
 - **Do not** rely on `navigator.modelContext` alone for WebMCP detection; prefer `document.modelContext` with `navigator.modelContext` fallback for compatibility. Use `parseWebMcpInputSchema` to normalize schemas across Chrome 154+ (native object) and Chrome < 154 (DOMString JSON) versions, and `getWebMcpTools` for querying registered tools with graceful degradation.
-- **Do not** commit `dist-electron/`, `push-subscriptions.db`, or `scheduled-tasks.db` — they are git-ignored.
+- **Do not** commit `dist-electron/`, `push-subscriptions.db`, `scheduled-tasks.db`, or `clients.db` — they are git-ignored.
 - **Do not** add new docs pages without updating `docs/README.md` and verifying references in `AGENTS.md`.
 - **Do not** allow file-browser copy/move flows to target the same folder or any descendant folder; enforce the guard in both UI and storage paths and cover it with tests. Always specify both `sourceGroupId` and `targetGroupId` when invoking storage moves/copies.
 - **Do not** use raw `window.location.href` or traditional link anchors for internal navigation. Always dispatch a `shadow-claw-navigate` custom event (or use the `handleSpecialLinkNavigation` utility) to switch pages, open files, or scroll to anchors seamlessly.

package/dist/public/README.md

@@ -2,23 +2,43 @@
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/xt-ml/shadow-claw)
 
-A browser-native, fully-featured AI assistant. TypeScript + Web Components + IndexedDB + File System API.
+A browser-native, fully-featured AI assistant — runs as a PWA, a native desktop app, a Node.js server, and via the `shadow-claw` CLI. TypeScript + Web Components + IndexedDB + File System API.
 
 [![ShadowClaw Screenshot](https://xt-ml.github.io/shadow-claw/assets/screenshots/shadow-claw-screenshot-1920x1052.png)](https://xt-ml.github.io/shadow-claw/)
 
 ## Quick Start
 
+### 1. Launch ShadowClaw instantly without cloning the repo
+
 ```bash
-npm install && npm run dev  # Dev server → http://localhost:8888
+npx shadow-claw dev --open
 ```
 
-Open Settings, select a provider (or use browser Prompt API), and start chatting.
+Open Settings, select your AI provider (or use the in-browser Prompt API / local models), and start chatting.
+
+### 2. Scaffold a Project or Knowledge Hub
+
+Create a custom template with pages and site configuration:
+
+```bash
+npx shadow-claw init my-assistant
+cd my-assistant
+npx shadow-claw dev --open
+```
+
+### 3. From Source (Contributing / Development)
+
+```bash
+git clone https://github.com/xt-ml/shadow-claw.git
+cd shadow-claw
+npm install && npm run dev  # Dev server → http://localhost:8888
+```
 
-**Desktop:** `npm run electron` or `npm run electron:build` for distributable.
+**Desktop App:** `npm run electron` or `npm run electron:build` for distributable installer.
 
 ## What is ShadowClaw?
 
-A fully-functional agent runtime that runs entirely in the browser—no AI processing on a server. Built with TypeScript, it provides:
+A fully-functional agent runtime built on browser-native technology — the orchestration and tool-use loop run client-side, with AI inference routing to remote APIs, local servers, or in-browser models depending on your configuration. Built with TypeScript, it provides:
 
 - **Multi-model support**: OpenRouter, Anthropic, Google Gemini, AWS Bedrock, Ollama, Llamafile, Mesh LLM, Transformers.js, and browser-native Prompt API
 - **Web Components UI**: Native Custom Elements + TC39 Signals for reactive updates
@@ -378,6 +398,23 @@ npm run electron:build:win   # Build Electron for Windows
 npm run electron:build:mac   # Build Electron for macOS
 ```
 
+### CLI Runtime Commands
+
+The `shadow-claw` CLI connects to a running server or browser clients to interact with active sessions:
+
+```bash
+npx shadow-claw clients                              # List connected browser/Electron clients
+npx shadow-claw send "your prompt" --client <id>    # Send a message to a connected client
+npx shadow-claw backup                               # Trigger OPFS workspace backup
+npx shadow-claw backup list                          # List available backup snapshots
+npx shadow-claw backup delete --backup-id <id>      # Delete a backup snapshot
+npx shadow-claw tasks --client <id>                  # List scheduled tasks on a client
+npx shadow-claw webrtc listen                        # Start headless WebRTC DataChannel daemon
+npx shadow-claw peer-id                              # Get or generate persistent CLI Peer ID
+```
+
+Commands support `--transport webrtc` for direct peer-to-peer DataChannel execution with connected browser clients. Control plane authentication uses `SHADOWCLAW_CONTROL_TOKEN` (env) or `--token` flag. The control plane endpoint and token are printed to the console on server start.
+
 ## License
 
 AGPLv3. Core logic derived from [openbrowserclaw](https://github.com/sachaa/openbrowserclaw) (MIT).