shadow-claw 1.27.1 → 1.28.0

package/bin/cli.mjs

@@ -62,17 +62,34 @@ program
   .description("Browser-native personal AI assistant and static site publisher")
   .version(version, "-v, --version", "Output the current version");
 
+// ---------------------------------------------------------------------------
+// DEVELOPMENT COMMANDS
+// ---------------------------------------------------------------------------
+program.commandsGroup("Development:");
+
 // ---------------------------------------------------------------------------
 // BUILD COMMAND
 // ---------------------------------------------------------------------------
 program
   .command("build")
   .description("Build the static site bundle for production or staging")
+  .optionsGroup("Build Mode Options:")
   .option(
     "--prod, --production",
     "Build in production mode with minification and optimizations",
     false,
   )
+  .option(
+    "--prerender-pages <mode>",
+    "Prerender page mode (all, auto, none)",
+    "auto",
+  )
+  .option(
+    "--copy-all-assets",
+    "Copy entire assets/ directory into output",
+    false,
+  )
+  .optionsGroup("Path & Routing Options:")
   .option(
     "--origin <url>",
     "Canonical origin URL (e.g. https://user.github.io/repo/)",
@@ -84,16 +101,6 @@ program
     "dist/public",
   )
   .option("--content-root <dir>", "Content root directory", process.cwd())
-  .option(
-    "--prerender-pages <mode>",
-    "Prerender page mode (all, auto, none)",
-    "auto",
-  )
-  .option(
-    "--copy-all-assets",
-    "Copy entire assets/ directory into output",
-    false,
-  )
   .action(async (options) => {
     try {
       const contentRoot = path.resolve(options.contentRoot || process.cwd());
@@ -243,26 +250,32 @@ async function handleDev(portArg, options) {
 program
   .command("dev [port]")
   .description("Build and launch the development server")
+  .optionsGroup("Server & Network Options:")
   .option("-p, --port <port>", "Port to listen on (default: 8888)")
   .option("--host <host>", "Bind host/IP", "127.0.0.1")
   .option("--ip <host>", "Bind host/IP (alias)")
+  .option("--open", "Automatically open default browser", false)
+  .option("-v, --verbose", "Enable verbose request/proxy logging", false)
+  .optionsGroup("Site & Build Options:")
   .option("--content-root <dir>", "Content root directory", process.cwd())
   .option(
     "--out-dir <dir>",
     "Output directory relative to content root",
     "dist/public",
   )
+  .optionsGroup("Security & Proxy Options:")
   .option(
     "--cors-mode <mode>",
     "CORS policy: localhost | private | all",
     "localhost",
   )
-  .option("--peerjs", "Enable built-in PeerJS signaling server", false)
   .option(
     "--allow-private-proxy",
     "Allow proxy to reach private/loopback addresses",
     false,
   )
+  .option("--peerjs", "Enable built-in PeerJS signaling server", false)
+  .optionsGroup("TLS / HTTPS Options:")
   .option("--https", "Enable HTTPS dev server", false)
   .option("--cert <path>", "Path to existing TLS certificate file")
   .option("--key <path>", "Path to existing TLS private key file")
@@ -270,6 +283,7 @@ program
     "--ssl-dir <path>",
     "Directory for TLS certificate generation/storage",
   )
+  .optionsGroup("Storage & Database Options:")
   .option("--database-dir <dir>", "Directory where SQLite databases are stored")
   .option(
     "--cache-dir <dir>",
@@ -285,33 +299,37 @@ program
     "Skip interactive cache directory prompt and use default .cache",
     false,
   )
-  .option("-v, --verbose", "Enable verbose request/proxy logging", false)
-  .option("--open", "Automatically open default browser", false)
   .action(handleDev);
 
 program
   .command("run [port]")
   .description("Alias for dev: build and launch the development server")
+  .optionsGroup("Server & Network Options:")
   .option("-p, --port <port>", "Port to listen on (default: 8888)")
   .option("--host <host>", "Bind host/IP", "127.0.0.1")
   .option("--ip <host>", "Bind host/IP (alias)")
+  .option("--open", "Automatically open default browser", false)
+  .option("-v, --verbose", "Enable verbose request/proxy logging", false)
+  .optionsGroup("Site & Build Options:")
   .option("--content-root <dir>", "Content root directory", process.cwd())
   .option(
     "--out-dir <dir>",
     "Output directory relative to content root",
     "dist/public",
   )
+  .optionsGroup("Security & Proxy Options:")
   .option(
     "--cors-mode <mode>",
     "CORS policy: localhost | private | all",
     "localhost",
   )
-  .option("--peerjs", "Enable built-in PeerJS signaling server", false)
   .option(
     "--allow-private-proxy",
     "Allow proxy to reach private/loopback addresses",
     false,
   )
+  .option("--peerjs", "Enable built-in PeerJS signaling server", false)
+  .optionsGroup("TLS / HTTPS Options:")
   .option("--https", "Enable HTTPS dev server", false)
   .option("--cert <path>", "Path to existing TLS certificate file")
   .option("--key <path>", "Path to existing TLS private key file")
@@ -319,6 +337,7 @@ program
     "--ssl-dir <path>",
     "Directory for TLS certificate generation/storage",
   )
+  .optionsGroup("Storage & Database Options:")
   .option("--database-dir <dir>", "Directory where SQLite databases are stored")
   .option(
     "--cache-dir <dir>",
@@ -334,10 +353,13 @@ program
     "Skip interactive cache directory prompt and use default .cache",
     false,
   )
-  .option("-v, --verbose", "Enable verbose request/proxy logging", false)
-  .option("--open", "Automatically open default browser", false)
   .action(handleDev);
 
+// ---------------------------------------------------------------------------
+// SERVER COMMANDS
+// ---------------------------------------------------------------------------
+program.commandsGroup("Server:");
+
 // ---------------------------------------------------------------------------
 // SERVE COMMAND
 // ---------------------------------------------------------------------------
@@ -346,25 +368,35 @@ program
   .description(
     "Serve an existing static site build and start the backend proxy",
   )
+  .optionsGroup("Server & Network Options:")
   .option("-p, --port <port>", "Port to listen on (default: 8888)")
   .option("--host <host>", "Bind host/IP", "127.0.0.1")
+  .option(
+    "--no-static",
+    "Disable static file and UI serving (services-only mode)",
+  )
+  .option("--open", "Automatically open default browser", false)
+  .option("-v, --verbose", "Enable verbose request/proxy logging", false)
+  .optionsGroup("Site Options:")
   .option("--content-root <dir>", "Content root directory", process.cwd())
   .option(
     "--out-dir <dir>",
     "Output directory relative to content root",
     "dist/public",
   )
+  .optionsGroup("Security & Proxy Options:")
   .option(
     "--cors-mode <mode>",
     "CORS policy: localhost | private | all",
     "localhost",
   )
-  .option("--peerjs", "Enable built-in PeerJS signaling server", false)
   .option(
     "--allow-private-proxy",
     "Allow proxy to reach private/loopback addresses",
     false,
   )
+  .option("--peerjs", "Enable built-in PeerJS signaling server", false)
+  .optionsGroup("TLS / HTTPS Options:")
   .option("--https", "Enable HTTPS dev server", false)
   .option("--cert <path>", "Path to existing TLS certificate file")
   .option("--key <path>", "Path to existing TLS private key file")
@@ -372,6 +404,7 @@ program
     "--ssl-dir <path>",
     "Directory for TLS certificate generation/storage",
   )
+  .optionsGroup("Storage & Database Options:")
   .option("--database-dir <dir>", "Directory where SQLite databases are stored")
   .option(
     "--cache-dir <dir>",
@@ -387,12 +420,6 @@ program
     "Skip interactive cache directory prompt and use default .cache",
     false,
   )
-  .option(
-    "--no-static",
-    "Disable static file and UI serving (services-only mode)",
-  )
-  .option("-v, --verbose", "Enable verbose request/proxy logging", false)
-  .option("--open", "Automatically open default browser", false)
   .action(async (portArg, options) => {
     try {
       const contentRoot = path.resolve(options.contentRoot || process.cwd());
@@ -623,25 +650,12 @@ program
   .description(
     "Start backend services (Express, MCP, control plane) without building or serving the UI (aliases: services, api)",
   )
+  .optionsGroup("Server & Network Options:")
   .option("-p, --port <port>", "Port to listen on (default: 8888)")
   .option("--host <host>", "Bind host/IP", "127.0.0.1")
   .option("--ip <host>", "Bind host/IP (alias)")
-  .option("--content-root <dir>", "Content root directory", process.cwd())
-  .option("--database-dir <dir>", "Directory where SQLite databases are stored")
-  .option(
-    "--cache-dir <dir>",
-    "Custom cache directory for databases, tokens, and logs",
-  )
-  .option(
-    "--tmp, --temp",
-    "Store cache and databases in system temporary directory",
-    false,
-  )
-  .option(
-    "-y, --yes",
-    "Skip interactive cache directory prompt and use default .cache",
-    false,
-  )
+  .option("-v, --verbose", "Enable verbose request/proxy logging", false)
+  .optionsGroup("Security & Proxy Options:")
   .option(
     "--cors-mode <mode>",
     "CORS policy: localhost | private | all",
@@ -661,6 +675,7 @@ program
     "Allow proxy to reach private/loopback addresses",
     false,
   )
+  .optionsGroup("TLS / HTTPS Options:")
   .option("--https", "Enable HTTPS server", false)
   .option("--cert <path>", "Path to existing TLS certificate file")
   .option("--key <path>", "Path to existing TLS private key file")
@@ -668,184 +683,75 @@ program
     "--ssl-dir <path>",
     "Directory for TLS certificate generation/storage",
   )
-  .option("-v, --verbose", "Enable verbose request/proxy logging", false)
-  .action(handleServer);
-
-// ---------------------------------------------------------------------------
-// INIT COMMAND
-// ---------------------------------------------------------------------------
-program
-  .command("init [dir]")
-  .description(
-    "Initialize a new ShadowClaw content template in the specified directory",
-  )
-  .action(async (dirArg) => {
-    try {
-      const targetDir = path.resolve(dirArg || process.cwd());
-      await mkdir(path.join(targetDir, "pages/main"), { recursive: true });
-
-      const configPath = path.join(targetDir, "shadow-claw-config.json");
-      const legacyConfigPath1 = path.join(targetDir, "shadow-claw.config.json");
-      const legacyConfigPath2 = path.join(targetDir, "site-config.json");
-      if (
-        !(await pathExists(configPath)) &&
-        !(await pathExists(legacyConfigPath1)) &&
-        !(await pathExists(legacyConfigPath2))
-      ) {
-        const defaultSiteConfig = {
-          $schema: "https://json-schema.org/draft/2020-12/schema",
-          site: {
-            title: "My ShadowClaw Site",
-            description:
-              "Personal AI assistant and knowledge hub powered by ShadowClaw.",
-          },
-          branding: {
-            titleText: "My ShadowClaw Site",
-          },
-          pages: {
-            sortOrder: "asc",
-            defaultPinnedPage: "/pages/main/index.html",
-          },
-        };
-        await writeFile(
-          configPath,
-          JSON.stringify(defaultSiteConfig, null, 2) + "\n",
-          "utf8",
-        );
-        console.log(`Created ${configPath}`);
-      }
-
-      const indexPath = path.join(targetDir, "pages/main/index.html");
-      if (!(await pathExists(indexPath))) {
-        const defaultIndexHtml = `---
-title: "Welcome to ShadowClaw"
-created: "${new Date().toISOString()}"
-updated: "${new Date().toISOString()}"
-slug: "home"
----
-
-<article>
-  <h1>Welcome to ShadowClaw</h1>
-  <p>Your browser-native personal AI assistant and static site publisher.</p>
-</article>
-`;
-        await writeFile(indexPath, defaultIndexHtml, "utf8");
-        console.log(`Created ${indexPath}`);
-      }
-
-      const gitignorePath = path.join(targetDir, ".gitignore");
-      if (!(await pathExists(gitignorePath))) {
-        await writeFile(
-          gitignorePath,
-          "dist/\n.cache/\nnode_modules/\n",
-          "utf8",
-        );
-        console.log(`Created ${gitignorePath}`);
-      }
-
-      console.log(
-        `\nShadowClaw template successfully initialized in ${targetDir}`,
-      );
-      console.log(`To start developing, run:`);
-      console.log(`  npx shadow-claw dev\n`);
-    } catch (err) {
-      console.error("Init failed:", err);
-      process.exit(1);
-    }
-  });
-
-// ---------------------------------------------------------------------------
-// PEER-ID / WEBRTC COMMAND
-// ---------------------------------------------------------------------------
-program
-  .command("peer-id [action] [customId]")
-  .alias("webrtc-peer-id")
-  .description(
-    "Get, generate, or renew the WebRTC CLI peer ID stored in .cache/cli-peer-id",
-  )
-  .option(
-    "-r, --renew",
-    "Force renewal / generation of a new WebRTC CLI peer ID",
-  )
-  .option("--set <id>", "Set a specific custom WebRTC CLI peer ID")
-  .option("--cache-dir <dir>", "Custom cache directory (defaults to .cache)")
-  .option("-q, --quiet", "Output only the peer ID string")
-  .option("--json", "Output peer ID and file path as JSON")
-  .action(async (action, customId, options) => {
-    const opts = { ...options };
-    if (customId && !opts.set) {
-      opts.set = customId;
-    }
-    await runPeerIdCommand(action, opts);
-  });
-
-program
-  .command("webrtc [action] [customId]")
-  .description(
-    "Manage WebRTC CLI configuration and peer identity (.cache/cli-peer-id)\n\n" +
-      "  Actions:\n" +
-      "    (default)  Show or generate the CLI peer ID\n" +
-      "    listen     Register as a live PeerJS peer — browser tabs can then\n" +
-      "               connect directly without a control-plane connection",
-  )
+  .optionsGroup("Storage & Database Options:")
+  .option("--content-root <dir>", "Content root directory", process.cwd())
+  .option("--database-dir <dir>", "Directory where SQLite databases are stored")
   .option(
-    "-r, --renew",
-    "Force renewal / generation of a new WebRTC CLI peer ID",
+    "--cache-dir <dir>",
+    "Custom cache directory for databases, tokens, and logs",
   )
-  .option("--set <id>", "Set a specific custom WebRTC CLI peer ID")
-  .option("--cache-dir <dir>", "Custom cache directory (defaults to .cache)")
-  .option("-q, --quiet", "Output only the peer ID string")
-  .option("--json", "Output peer ID and file path as JSON")
-  // listen-specific options
-  .option("--host <host>", "PeerJS signaling server host (for listen)")
-  .option("--port <port>", "PeerJS signaling server port (for listen)", "8888")
-  .option("--path <path>", "PeerJS signaling server path (for listen)", "/")
   .option(
-    "--secure",
-    "Use TLS (wss://) for the signaling server (for listen)",
+    "--tmp, --temp",
+    "Store cache and databases in system temporary directory",
     false,
   )
   .option(
-    "--https",
-    "Alias for --secure: use TLS (wss://) for the signaling server",
+    "-y, --yes",
+    "Skip interactive cache directory prompt and use default .cache",
     false,
   )
-  .option(
-    "--trusted-peer <id>",
-    "Accept connections only from this peer ID (repeatable, for listen)",
-    (v, prev) => (prev ? [...prev, v] : [v]),
-    [],
+  .action(handleServer);
+
+// ---------------------------------------------------------------------------
+// MCP COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("mcp")
+  .description(
+    "Run the official Stateless Model Context Protocol (MCP 2026-07-28) server",
   )
-  .option("--verbose", "Verbose connection logging (for listen)", false)
-  .option("--renew-peer-id", "Renew CLI peer ID before listening", false)
+  .optionsGroup("MCP Protocol Options:")
+  .option("--mcp-transport <transport>", "MCP transport: stdio | http", "stdio")
   .option(
-    "-k, --insecure",
-    "Allow self-signed TLS certificates for the signaling server (wss://)",
+    "--relay-client-tools",
+    "Discover and relay tools from connected browser clients",
     true,
   )
-  .action(async (action, customId, options) => {
-    if (action === "listen") {
-      await runWebRtcListenCommand(options);
-      return;
-    }
-    const opts = { ...options };
-    if (customId && !opts.set) {
-      opts.set = customId;
-    }
-    await runPeerIdCommand(action, opts);
+  .option("--no-relay-client-tools", "Disable relaying browser client tools")
+  .optionsGroup("Target Client Options:")
+  .option("--client <id>", "Target client ID (defaults to first active client)")
+  .optionsGroup("Control Plane Connection Options:")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port or HTTP MCP port")
+  .option("--token <token>", "Control token")
+  .option("--https", "Connect to server via HTTPS", false)
+  .option("-k, --insecure", "Allow self-signed TLS certificates", true)
+  .optionsGroup("Transport & Peer Options:")
+  .option(
+    "--transport <transport>",
+    "Control plane client transport: http | webrtc",
+    "http",
+  )
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .action(async (options) => {
+    await runMcpCommand(options);
   });
 
 // ---------------------------------------------------------------------------
-// CLIENTS COMMAND
+// CONTROL PLANE & CLIENT BRIDGE COMMANDS
 // ---------------------------------------------------------------------------
+program.commandsGroup("Control Plane & Client Bridge:");
+
 program
   .command("clients")
   .description("List connected / registered browser and Electron clients")
+  .optionsGroup("Control Plane Connection Options:")
   .option("--host <host>", "Control plane host")
   .option("--port <port>", "Control plane port")
   .option("--token <token>", "Control token")
   .option("--https", "Connect to server via HTTPS", false)
   .option("-k, --insecure", "Allow self-signed TLS certificates", true)
+  .optionsGroup("Transport & Peer Options:")
   .option("--transport <transport>", "Transport to use: http | webrtc", "http")
   .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
   .option(
@@ -858,19 +764,19 @@ program
     await runClientsCommand(options);
   });
 
-// ---------------------------------------------------------------------------
-// SEND COMMAND
-// ---------------------------------------------------------------------------
 program
   .command("send <message>")
   .description("Send a message/prompt to a connected client")
+  .optionsGroup("Target Options:")
   .option("--client <id>", "Target client ID (defaults to first available)")
   .option("--group <groupId>", "Target conversation group ID")
+  .optionsGroup("Control Plane Connection Options:")
   .option("--host <host>", "Control plane host")
   .option("--port <port>", "Control plane port")
   .option("--token <token>", "Control token")
   .option("--https", "Connect to server via HTTPS", false)
   .option("-k, --insecure", "Allow self-signed TLS certificates", true)
+  .optionsGroup("Transport & Peer Options:")
   .option("--transport <transport>", "Transport to use: http | webrtc", "http")
   .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
   .option("--renew-peer-id", "Renew WebRTC CLI peer ID before sending", false)
@@ -879,22 +785,19 @@ program
     await runSendCommand(message, options);
   });
 
-// ---------------------------------------------------------------------------
-// BACKUP COMMAND
-// ---------------------------------------------------------------------------
 program
-  .command("backup [action]")
-  .description(
-    "Trigger or manage client workspace backups (trigger | list | delete)",
-  )
-  .option("--client <id>", "Client ID")
-  .option("--backup-id <id>", "Backup ID (for delete)")
-  .option("--group <groupId>", "Specific workspace group ID")
+  .command("tasks")
+  .description("List scheduled tasks on a connected client")
+  .optionsGroup("Target Options:")
+  .option("--client <id>", "Target client ID")
+  .option("--group <groupId>", "Filter tasks by conversation group ID")
+  .optionsGroup("Control Plane Connection Options:")
   .option("--host <host>", "Control plane host")
   .option("--port <port>", "Control plane port")
   .option("--token <token>", "Control token")
   .option("--https", "Connect to server via HTTPS", false)
   .option("-k, --insecure", "Allow self-signed TLS certificates", true)
+  .optionsGroup("Transport & Peer Options:")
   .option("--transport <transport>", "Transport to use: http | webrtc", "http")
   .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
   .option(
@@ -903,23 +806,26 @@ program
     false,
   )
   .option("--cache-dir <dir>", "Custom cache directory")
-  .action(async (action, options) => {
-    await runBackupCommand(action || "trigger", options);
+  .action(async (options) => {
+    await runTasksCommand(options);
   });
 
-// ---------------------------------------------------------------------------
-// TASKS COMMAND
-// ---------------------------------------------------------------------------
 program
-  .command("tasks")
-  .description("List scheduled tasks on a connected client")
-  .option("--client <id>", "Target client ID")
-  .option("--group <groupId>", "Filter tasks by conversation group ID")
+  .command("backup [action]")
+  .description(
+    "Trigger or manage client workspace backups (trigger | list | delete)",
+  )
+  .optionsGroup("Target Options:")
+  .option("--client <id>", "Client ID")
+  .option("--backup-id <id>", "Backup ID (for delete)")
+  .option("--group <groupId>", "Specific workspace group ID")
+  .optionsGroup("Control Plane Connection Options:")
   .option("--host <host>", "Control plane host")
   .option("--port <port>", "Control plane port")
   .option("--token <token>", "Control token")
   .option("--https", "Connect to server via HTTPS", false)
   .option("-k, --insecure", "Allow self-signed TLS certificates", true)
+  .optionsGroup("Transport & Peer Options:")
   .option("--transport <transport>", "Transport to use: http | webrtc", "http")
   .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
   .option(
@@ -928,50 +834,190 @@ program
     false,
   )
   .option("--cache-dir <dir>", "Custom cache directory")
-  .action(async (options) => {
-    await runTasksCommand(options);
+  .action(async (action, options) => {
+    await runBackupCommand(action || "trigger", options);
   });
 
 // ---------------------------------------------------------------------------
-// MCP COMMAND
+// WEBRTC COMMANDS
 // ---------------------------------------------------------------------------
+program.commandsGroup("WebRTC:");
+
 program
-  .command("mcp")
+  .command("webrtc [action] [customId]")
+  .summary(
+    "Manage WebRTC CLI configuration and peer identity (.cache/cli-peer-id)",
+  )
   .description(
-    "Run the official Stateless Model Context Protocol (MCP 2026-07-28) server",
+    "Manage WebRTC CLI configuration and peer identity (.cache/cli-peer-id)\n\n" +
+      "  Actions:\n" +
+      "    (default)  Show or generate the CLI peer ID\n" +
+      "    listen     Register as a live PeerJS peer — browser tabs can then\n" +
+      "               connect directly without a control-plane connection",
   )
-  .option("--mcp-transport <transport>", "MCP transport: stdio | http", "stdio")
-  .option("--client <id>", "Target client ID (defaults to first active client)")
-  .option("--host <host>", "Control plane host")
-  .option("--port <port>", "Control plane port or HTTP MCP port")
-  .option("--token <token>", "Control token")
-  .option("--https", "Connect to server via HTTPS", false)
-  .option("-k, --insecure", "Allow self-signed TLS certificates", true)
+  .optionsGroup("Identity Options:")
   .option(
-    "--transport <transport>",
-    "Control plane client transport: http | webrtc",
-    "http",
+    "-r, --renew",
+    "Force renewal / generation of a new WebRTC CLI peer ID",
   )
-  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option("--set <id>", "Set a specific custom WebRTC CLI peer ID")
+  .option("--cache-dir <dir>", "Custom cache directory (defaults to .cache)")
+  .option("-q, --quiet", "Output only the peer ID string")
+  .option("--json", "Output peer ID and file path as JSON")
+  .optionsGroup("Signaling & Listener Options (for listen action):")
+  .option("--host <host>", "PeerJS signaling server host (for listen)")
+  .option("--port <port>", "PeerJS signaling server port (for listen)", "8888")
+  .option("--path <path>", "PeerJS signaling server path (for listen)", "/")
   .option(
-    "--relay-client-tools",
-    "Discover and relay tools from connected browser clients",
+    "--secure",
+    "Use TLS (wss://) for the signaling server (for listen)",
+    false,
+  )
+  .option(
+    "--https",
+    "Alias for --secure: use TLS (wss://) for the signaling server",
+    false,
+  )
+  .option(
+    "--trusted-peer <id>",
+    "Accept connections only from this peer ID (repeatable, for listen)",
+    (v, prev) => (prev ? [...prev, v] : [v]),
+    [],
+  )
+  .option("--verbose", "Verbose connection logging (for listen)", false)
+  .option("--renew-peer-id", "Renew CLI peer ID before listening", false)
+  .option(
+    "-k, --insecure",
+    "Allow self-signed TLS certificates for the signaling server (wss://)",
     true,
   )
-  .option("--no-relay-client-tools", "Disable relaying browser client tools")
-  .action(async (options) => {
-    await runMcpCommand(options);
+  .action(async (action, customId, options) => {
+    if (action === "listen") {
+      await runWebRtcListenCommand(options);
+      return;
+    }
+    const opts = { ...options };
+    if (customId && !opts.set) {
+      opts.set = customId;
+    }
+    await runPeerIdCommand(action, opts);
+  });
+
+program
+  .command("peer-id [action] [customId]")
+  .alias("webrtc-peer-id")
+  .description(
+    "Get, generate, or renew the WebRTC CLI peer ID stored in .cache/cli-peer-id",
+  )
+  .optionsGroup("Identity Options:")
+  .option(
+    "-r, --renew",
+    "Force renewal / generation of a new WebRTC CLI peer ID",
+  )
+  .option("--set <id>", "Set a specific custom WebRTC CLI peer ID")
+  .option("--cache-dir <dir>", "Custom cache directory (defaults to .cache)")
+  .option("-q, --quiet", "Output only the peer ID string")
+  .option("--json", "Output peer ID and file path as JSON")
+  .action(async (action, customId, options) => {
+    const opts = { ...options };
+    if (customId && !opts.set) {
+      opts.set = customId;
+    }
+    await runPeerIdCommand(action, opts);
   });
 
 // ---------------------------------------------------------------------------
-// AGENT SKILLS INDEX COMMAND
+// PROJECT & PROTOCOL COMMANDS
 // ---------------------------------------------------------------------------
+program.commandsGroup("Project:");
+
+program
+  .command("init [dir]")
+  .description(
+    "Initialize a new ShadowClaw content template in the specified directory",
+  )
+  .action(async (dirArg) => {
+    try {
+      const targetDir = path.resolve(dirArg || process.cwd());
+      await mkdir(path.join(targetDir, "pages/main"), { recursive: true });
+
+      const configPath = path.join(targetDir, "shadow-claw-config.json");
+      const legacyConfigPath1 = path.join(targetDir, "shadow-claw.config.json");
+      const legacyConfigPath2 = path.join(targetDir, "site-config.json");
+      if (
+        !(await pathExists(configPath)) &&
+        !(await pathExists(legacyConfigPath1)) &&
+        !(await pathExists(legacyConfigPath2))
+      ) {
+        const defaultSiteConfig = {
+          $schema: "https://json-schema.org/draft/2020-12/schema",
+          site: {
+            title: "My ShadowClaw Site",
+            description:
+              "Personal AI assistant and knowledge hub powered by ShadowClaw.",
+          },
+          branding: {
+            titleText: "My ShadowClaw Site",
+          },
+          pages: {
+            sortOrder: "asc",
+            defaultPinnedPage: "/pages/main/index.html",
+          },
+        };
+        await writeFile(
+          configPath,
+          JSON.stringify(defaultSiteConfig, null, 2) + "\n",
+          "utf8",
+        );
+        console.log(`Created ${configPath}`);
+      }
+
+      const indexPath = path.join(targetDir, "pages/main/index.html");
+      if (!(await pathExists(indexPath))) {
+        const defaultIndexHtml = `---
+title: "Welcome to ShadowClaw"
+created: "${new Date().toISOString()}"
+updated: "${new Date().toISOString()}"
+slug: "home"
+---
+
+<article>
+  <h1>Welcome to ShadowClaw</h1>
+  <p>Your browser-native personal AI assistant and static site publisher.</p>
+</article>
+`;
+        await writeFile(indexPath, defaultIndexHtml, "utf8");
+        console.log(`Created ${indexPath}`);
+      }
+
+      const gitignorePath = path.join(targetDir, ".gitignore");
+      if (!(await pathExists(gitignorePath))) {
+        await writeFile(
+          gitignorePath,
+          "dist/\n.cache/\nnode_modules/\n",
+          "utf8",
+        );
+        console.log(`Created ${gitignorePath}`);
+      }
+
+      console.log(
+        `\nShadowClaw template successfully initialized in ${targetDir}`,
+      );
+      console.log(`To start developing, run:`);
+      console.log(`  npx shadow-claw dev\n`);
+    } catch (err) {
+      console.error("Init failed:", err);
+      process.exit(1);
+    }
+  });
+
 program
   .command("skills:index [dir]")
   .alias("agent-skills")
   .description(
     "Generate or update .well-known/agent-skills/index.json per the Agent Skills Discovery RFC",
   )
+  .optionsGroup("Output & Path Options:")
   .option(
     "--out-dir <dir>",
     "Output directory relative to content root (default: .well-known/agent-skills)",
@@ -985,6 +1031,7 @@ program
     "--config <file>",
     "Explicit path to shadow-claw.config.json or site-config.json",
   )
+  .optionsGroup("Generation Options:")
   .option("--no-bundled", "Exclude bundled ShadowClaw skills from index")
   .option("--stdout", "Print generated index.json to stdout", false)
   .option("--no-write", "Skip writing file to disk")
@@ -997,4 +1044,10 @@ program
     }
   });
 
+// ---------------------------------------------------------------------------
+// HELP & UTILITY COMMANDS
+// ---------------------------------------------------------------------------
+program.commandsGroup("Help & Utility:");
+program.helpCommand("help [command]", "display help for command");
+
 program.parse(process.argv);