@silicaclaw/cli 1.0.0-beta.0 → 1.0.0-beta.10

package/packages/storage/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./jsonRepo";
+export * from "./repos";
+export * from "./socialRuntimeRepo";

package/packages/storage/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./jsonRepo"), exports);
+__exportStar(require("./repos"), exports);
+__exportStar(require("./socialRuntimeRepo"), exports);

package/packages/storage/dist/jsonRepo.d.ts

@@ -0,0 +1,7 @@
+export declare class JsonFileRepo<T> {
+    private filePath;
+    private fallback;
+    constructor(filePath: string, fallback: () => T);
+    get(): Promise<T>;
+    set(value: T): Promise<void>;
+}

package/packages/storage/dist/jsonRepo.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonFileRepo = void 0;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+class JsonFileRepo {
+    filePath;
+    fallback;
+    constructor(filePath, fallback) {
+        this.filePath = filePath;
+        this.fallback = fallback;
+    }
+    async get() {
+        try {
+            const raw = await (0, promises_1.readFile)(this.filePath, "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            const seed = this.fallback();
+            await this.set(seed);
+            return seed;
+        }
+    }
+    async set(value) {
+        await (0, promises_1.mkdir)((0, path_1.dirname)(this.filePath), { recursive: true });
+        await (0, promises_1.writeFile)(this.filePath, JSON.stringify(value, null, 2), "utf8");
+    }
+}
+exports.JsonFileRepo = JsonFileRepo;

package/packages/storage/dist/repos.d.ts

@@ -0,0 +1,21 @@
+import { AgentIdentity, DirectoryState, PublicProfile } from "@silicaclaw/core";
+import { JsonFileRepo } from "./jsonRepo";
+export type LogEntry = {
+    id: string;
+    level: "info" | "warn" | "error";
+    message: string;
+    timestamp: number;
+};
+export declare class IdentityRepo extends JsonFileRepo<AgentIdentity | null> {
+    constructor(rootDir?: string);
+}
+export declare class ProfileRepo extends JsonFileRepo<PublicProfile | null> {
+    constructor(rootDir?: string);
+}
+export declare class CacheRepo extends JsonFileRepo<DirectoryState> {
+    constructor(rootDir?: string);
+}
+export declare class LogRepo extends JsonFileRepo<LogEntry[]> {
+    constructor(rootDir?: string);
+    append(entry: Omit<LogEntry, "id">): Promise<void>;
+}

package/packages/storage/dist/repos.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogRepo = exports.CacheRepo = exports.ProfileRepo = exports.IdentityRepo = void 0;
+const path_1 = require("path");
+const core_1 = require("@silicaclaw/core");
+const jsonRepo_1 = require("./jsonRepo");
+class IdentityRepo extends jsonRepo_1.JsonFileRepo {
+    constructor(rootDir = process.cwd()) {
+        super((0, path_1.resolve)(rootDir, "data", "identity.json"), () => null);
+    }
+}
+exports.IdentityRepo = IdentityRepo;
+class ProfileRepo extends jsonRepo_1.JsonFileRepo {
+    constructor(rootDir = process.cwd()) {
+        super((0, path_1.resolve)(rootDir, "data", "profile.json"), () => null);
+    }
+}
+exports.ProfileRepo = ProfileRepo;
+class CacheRepo extends jsonRepo_1.JsonFileRepo {
+    constructor(rootDir = process.cwd()) {
+        super((0, path_1.resolve)(rootDir, "data", "cache.json"), () => (0, core_1.createEmptyDirectoryState)());
+    }
+}
+exports.CacheRepo = CacheRepo;
+class LogRepo extends jsonRepo_1.JsonFileRepo {
+    constructor(rootDir = process.cwd()) {
+        super((0, path_1.resolve)(rootDir, "data", "logs.json"), () => []);
+    }
+    async append(entry) {
+        const current = await this.get();
+        const next = [
+            {
+                id: `${entry.timestamp}-${Math.random().toString(36).slice(2, 8)}`,
+                ...entry,
+            },
+            ...current,
+        ].slice(0, 50);
+        await this.set(next);
+    }
+}
+exports.LogRepo = LogRepo;

package/packages/storage/dist/socialRuntimeRepo.d.ts

@@ -0,0 +1,5 @@
+import { SocialRuntimeConfig } from "@silicaclaw/core";
+import { JsonFileRepo } from "./jsonRepo";
+export declare class SocialRuntimeRepo extends JsonFileRepo<SocialRuntimeConfig> {
+    constructor(rootDir?: string);
+}

package/packages/storage/dist/socialRuntimeRepo.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialRuntimeRepo = void 0;
+const path_1 = require("path");
+const jsonRepo_1 = require("./jsonRepo");
+function emptyRuntime() {
+    return {
+        enabled: true,
+        public_enabled: false,
+        source_path: null,
+        last_loaded_at: 0,
+        social_found: false,
+        parse_error: null,
+        resolved_identity: null,
+        resolved_profile: null,
+        resolved_network: {
+            mode: "lan",
+            adapter: "real-preview",
+            namespace: "silicaclaw.preview",
+            port: null,
+            signaling_url: "http://localhost:4510",
+            signaling_urls: [],
+            room: "silicaclaw-room",
+            seed_peers: [],
+            bootstrap_hints: [],
+            bootstrap_sources: [],
+        },
+        resolved_discovery: {
+            discoverable: true,
+            allow_profile_broadcast: true,
+            allow_presence_broadcast: true,
+        },
+        visibility: {
+            show_display_name: true,
+            show_bio: true,
+            show_tags: true,
+            show_agent_id: true,
+            show_last_seen: true,
+            show_capabilities_summary: true,
+        },
+        openclaw: {
+            bind_existing_identity: true,
+            use_openclaw_profile_if_available: true,
+        },
+    };
+}
+class SocialRuntimeRepo extends jsonRepo_1.JsonFileRepo {
+    constructor(rootDir = process.cwd()) {
+        super((0, path_1.resolve)(rootDir, ".silicaclaw", "social.runtime.json"), emptyRuntime);
+    }
+}
+exports.SocialRuntimeRepo = SocialRuntimeRepo;

package/packages/storage/tsconfig.json

@@ -1,7 +1,12 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    "outDir": "./dist"
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@silicaclaw/core": ["../../node_modules/@silicaclaw/core/dist/index.d.ts"]
+    }
   },
   "include": ["src"]
 }

package/scripts/quickstart.sh

@@ -1,8 +1,23 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+INVOKE_PWD="${INIT_CWD:-$PWD}"
 ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-cd "$ROOT_DIR"
+WORK_DIR="$ROOT_DIR"
+IS_NPX_MODE=0
+DEFAULT_MODE_PICK="${QUICKSTART_DEFAULT_MODE:-1}"
+CONNECT_MODE="${QUICKSTART_CONNECT_MODE:-0}"
+
+case "$DEFAULT_MODE_PICK" in
+  1|2|3) ;;
+  *) DEFAULT_MODE_PICK="1" ;;
+esac
+
+case "$ROOT_DIR" in
+  *"/.npm/_npx/"*)
+    IS_NPX_MODE=1
+    ;;
+esac
 
 STEP=1
 
@@ -22,6 +37,16 @@ run_cmd() {
   eval "$cmd"
 }
 
+run_cmd_may_fail() {
+  local cmd="$1"
+  printf '→ %s\n' "$cmd"
+  set +e
+  eval "$cmd"
+  local code=$?
+  set -e
+  return $code
+}
+
 ask_yes_no() {
   local prompt="$1"
   local default="${2:-Y}"
@@ -43,11 +68,76 @@ pause_continue() {
   read -r -p "按回车继续..." _ || true
 }
 
+detect_public_ip() {
+  local ip=""
+  if command -v curl >/dev/null 2>&1; then
+    ip="$(curl -fsSL --max-time 3 https://api.ipify.org 2>/dev/null || true)"
+  fi
+  if [ -z "$ip" ] && command -v curl >/dev/null 2>&1; then
+    ip="$(curl -fsSL --max-time 3 https://ifconfig.me 2>/dev/null || true)"
+  fi
+  if [ -z "$ip" ] && command -v wget >/dev/null 2>&1; then
+    ip="$(wget -qO- --timeout=3 https://api.ipify.org 2>/dev/null || true)"
+  fi
+  ip="$(printf '%s' "$ip" | tr -d '[:space:]')"
+  printf '%s' "$ip"
+}
+
+url_host() {
+  local raw="${1:-}"
+  if [ -z "$raw" ]; then
+    printf ''
+    return 0
+  fi
+  node -e "try{const u=new URL(process.argv[1]); process.stdout.write(u.hostname||'');}catch{process.stdout.write('');}" "$raw"
+}
+
+url_port_or_default() {
+  local raw="${1:-}"
+  local fallback="${2:-4510}"
+  if [ -z "$raw" ]; then
+    printf '%s' "$fallback"
+    return 0
+  fi
+  node -e "try{const u=new URL(process.argv[1]); process.stdout.write(String(u.port || '$fallback'));}catch{process.stdout.write('$fallback');}" "$raw"
+}
+
 title "SilicaClaw Quick Start 启动"
 echo "目录: $ROOT_DIR"
 echo "目标: 用终端一步步完成安装与启动（类似 OpenClaw Quick Start）"
 pause_continue
 
+if [ "$IS_NPX_MODE" -eq 1 ]; then
+  title "选择安装目录（npx 模式）"
+  DEFAULT_TARGET_DIR="$INVOKE_PWD/silicaclaw"
+  TARGET_DIR_INPUT=""
+  read -r -p "请输入安装目录（默认: ${DEFAULT_TARGET_DIR:-$HOME/silicaclaw}）: " TARGET_DIR_INPUT || true
+  TARGET_DIR="${TARGET_DIR_INPUT:-$DEFAULT_TARGET_DIR}"
+  TARGET_DIR="${TARGET_DIR/#\~/$HOME}"
+
+  if [ -e "$TARGET_DIR" ] && [ ! -d "$TARGET_DIR" ]; then
+    echo "目标路径存在且不是目录: $TARGET_DIR"
+    exit 1
+  fi
+
+  mkdir -p "$TARGET_DIR"
+  echo "正在复制项目文件到: $TARGET_DIR"
+  if command -v rsync >/dev/null 2>&1; then
+    rsync -a --delete \
+      --exclude '.git/' \
+      --exclude 'node_modules/' \
+      --exclude '.npm-cache/' \
+      --exclude '*.tgz' \
+      "$ROOT_DIR/" "$TARGET_DIR/"
+  else
+    cp -R "$ROOT_DIR/." "$TARGET_DIR/"
+    rm -rf "$TARGET_DIR/.git" "$TARGET_DIR/node_modules" "$TARGET_DIR/.npm-cache"
+  fi
+  WORK_DIR="$TARGET_DIR"
+  echo "工作目录已切换到: $WORK_DIR"
+  pause_continue
+fi
+
 title "检查 Node.js / npm"
 if ! command -v node >/dev/null 2>&1; then
   echo "未找到 node，请先安装 Node.js 18+"
@@ -69,23 +159,46 @@ if ! node -e "const v=process.versions.node.split('.').map(Number); if (v[0] < 1
 fi
 
 title "安装依赖"
-if [ ! -d "$ROOT_DIR/node_modules" ]; then
-  run_cmd "npm install"
+if [ ! -d "$WORK_DIR/node_modules" ]; then
+  run_cmd "cd \"$WORK_DIR\" && npm_config_cache=\"$WORK_DIR/.npm-cache\" npm install"
 else
   if ask_yes_no "检测到 node_modules，是否仍执行 npm install 同步依赖？" "N"; then
-    run_cmd "npm install"
+    run_cmd "cd \"$WORK_DIR\" && npm_config_cache=\"$WORK_DIR/.npm-cache\" npm install"
   else
     echo "跳过 npm install"
   fi
 fi
 
+title "安装系统命令（silicaclaw）"
+if command -v silicaclaw >/dev/null 2>&1; then
+  echo "已检测到系统命令: $(command -v silicaclaw)"
+  echo "跳过全局安装。"
+else
+  echo "为了获得生产体验（可直接运行 silicaclaw ...），建议安装全局命令。"
+  if ask_yes_no "是否现在安装全局命令 @silicaclaw/cli@beta？" "Y"; then
+    if run_cmd_may_fail "npm_config_cache=\"$WORK_DIR/.npm-cache\" npm i -g @silicaclaw/cli@beta"; then
+      echo "全局命令安装成功。"
+    else
+      echo "普通权限安装失败（常见于 macOS /usr/local 权限）。"
+      if ask_yes_no "是否使用 sudo 重试安装全局命令？" "Y"; then
+        run_cmd "npm_config_cache=\"$WORK_DIR/.npm-cache\" sudo npm i -g @silicaclaw/cli@beta"
+        echo "全局命令安装成功。"
+      else
+        echo "已跳过全局安装。你仍可使用: npx @silicaclaw/cli@beta <command>"
+      fi
+    fi
+  else
+    echo "已跳过全局安装。你仍可使用: npx @silicaclaw/cli@beta <command>"
+  fi
+fi
+
 title "准备 social.md"
-if [ -f "$ROOT_DIR/social.md" ]; then
+if [ -f "$WORK_DIR/social.md" ]; then
   echo "已存在 social.md，保留现有配置。"
 else
   if ask_yes_no "未找到 social.md，是否自动从 social.md.example 生成？" "Y"; then
-    run_cmd "cp social.md.example social.md"
-    echo "已生成: $ROOT_DIR/social.md"
+    run_cmd "cd \"$WORK_DIR\" && cp social.md.example social.md"
+    echo "已生成: $WORK_DIR/social.md"
   else
     echo "跳过生成 social.md（local-console 首启也会自动生成最小模板）"
   fi
@@ -95,13 +208,21 @@ title "选择网络模式"
 echo "1) local           单机预览（最快）"
 echo "2) lan             局域网预览（A/B 双机）"
 echo "3) global-preview  非局域网预览（WebRTC）"
-read -r -p "请输入模式编号 [1/2/3] (默认 1): " MODE_PICK || true
-MODE_PICK="${MODE_PICK:-1}"
+echo "提示: 不确定就直接回车（默认 local）。"
+echo "提示: 只有在你已有可达 signaling 地址时，才选择 3。"
+if [ "$CONNECT_MODE" = "1" ]; then
+  MODE_PICK="3"
+  echo "connect 模式：已自动选择 global-preview。"
+else
+  read -r -p "请输入模式编号 [1/2/3] (默认 ${DEFAULT_MODE_PICK}): " MODE_PICK || true
+  MODE_PICK="${MODE_PICK:-$DEFAULT_MODE_PICK}"
+fi
 
 NETWORK_MODE="local"
 NETWORK_ADAPTER="local-event-bus"
 WEBRTC_SIGNALING_URL_VALUE=""
 WEBRTC_ROOM_VALUE="silicaclaw-demo"
+AUTO_START_SIGNALING=0
 
 case "$MODE_PICK" in
   2)
@@ -111,11 +232,37 @@ case "$MODE_PICK" in
   3)
     NETWORK_MODE="global-preview"
     NETWORK_ADAPTER="webrtc-preview"
-    read -r -p "请输入 signaling URL（例如 http://your-server:4510）: " WEBRTC_SIGNALING_URL_VALUE
+    PUBLIC_IP="$(detect_public_ip)"
+    SIGNALING_DEFAULT="${WEBRTC_SIGNALING_URL:-http://localhost:4510}"
+    if [ -n "$PUBLIC_IP" ]; then
+      SIGNALING_DEFAULT="http://$PUBLIC_IP:4510"
+    fi
+    echo "提示: signaling 地址需要“所有节点可访问”。"
+    if [ -n "$PUBLIC_IP" ]; then
+      echo "已检测到本机公网 IP: $PUBLIC_IP"
+      echo "如果你这台机器就是 signaling 服务器，可直接回车使用默认值。"
+    else
+      echo "未检测到公网 IP，将使用默认值: $SIGNALING_DEFAULT"
+      echo "如果 signaling 在其他机器，请输入该机器公网地址。"
+    fi
+    read -r -p "请输入 signaling URL（默认 ${SIGNALING_DEFAULT}）: " WEBRTC_SIGNALING_URL_INPUT || true
+    WEBRTC_SIGNALING_URL_VALUE="${WEBRTC_SIGNALING_URL_INPUT:-$SIGNALING_DEFAULT}"
     if [ -z "${WEBRTC_SIGNALING_URL_VALUE:-}" ]; then
       echo "global-preview 必须提供 signaling URL"
       exit 1
     fi
+
+    SIGNALING_HOST="$(url_host "$WEBRTC_SIGNALING_URL_VALUE")"
+    if [ "$SIGNALING_HOST" = "localhost" ] || [ "$SIGNALING_HOST" = "127.0.0.1" ]; then
+      echo "提示: 当前 signaling URL 是本机地址，仅本机可用，不适合跨网络双机演示。"
+    fi
+
+    if ask_yes_no "是否在当前机器自动后台启动 signaling server（用于演示）？" "Y"; then
+      AUTO_START_SIGNALING=1
+      SIGNALING_PORT_VALUE="$(url_port_or_default "$WEBRTC_SIGNALING_URL_VALUE" "4510")"
+      echo "将尝试以 PORT=$SIGNALING_PORT_VALUE 后台启动 signaling server"
+    fi
+
     read -r -p "请输入 room（默认 silicaclaw-demo）: " WEBRTC_ROOM_VALUE_INPUT || true
     WEBRTC_ROOM_VALUE="${WEBRTC_ROOM_VALUE_INPUT:-silicaclaw-demo}"
     ;;
@@ -128,17 +275,47 @@ esac
 echo "已选择: $NETWORK_MODE ($NETWORK_ADAPTER)"
 
 title "启动 local-console"
-if [ "$NETWORK_MODE" = "global-preview" ]; then
-  echo "将使用以下参数启动："
-  echo "NETWORK_ADAPTER=$NETWORK_ADAPTER"
-  echo "WEBRTC_SIGNALING_URL=$WEBRTC_SIGNALING_URL_VALUE"
-  echo "WEBRTC_ROOM=$WEBRTC_ROOM_VALUE"
-  pause_continue
-  run_cmd "NETWORK_ADAPTER=$NETWORK_ADAPTER WEBRTC_SIGNALING_URL=$WEBRTC_SIGNALING_URL_VALUE WEBRTC_ROOM=$WEBRTC_ROOM_VALUE npm run local-console"
+echo "1) gateway（推荐）  后台服务模式，可用 start/stop/restart/status 管理"
+echo "2) dev watch        前台开发模式（tsx watch）"
+read -r -p "请选择启动方式 [1/2] (默认 1): " START_MODE_PICK || true
+START_MODE_PICK="${START_MODE_PICK:-1}"
+
+if [ "$START_MODE_PICK" = "2" ]; then
+  if [ "$NETWORK_MODE" = "global-preview" ]; then
+    if [ "$AUTO_START_SIGNALING" -eq 1 ]; then
+      mkdir -p "$WORK_DIR/.silicaclaw"
+      SIGNALING_LOG="$WORK_DIR/.silicaclaw/signaling.log"
+      SIGNALING_PID_FILE="$WORK_DIR/.silicaclaw/signaling.pid"
+      run_cmd "cd \"$WORK_DIR\" && PORT=${SIGNALING_PORT_VALUE:-4510} nohup npm run webrtc-signaling > \"$SIGNALING_LOG\" 2>&1 & echo \$! > \"$SIGNALING_PID_FILE\""
+      echo "已后台启动 signaling server，日志: $SIGNALING_LOG"
+      echo "停止 signaling: kill \$(cat \"$SIGNALING_PID_FILE\")"
+    fi
+    echo "将使用以下参数启动（dev watch）："
+    echo "NETWORK_ADAPTER=$NETWORK_ADAPTER"
+    echo "WEBRTC_SIGNALING_URL=$WEBRTC_SIGNALING_URL_VALUE"
+    echo "WEBRTC_ROOM=$WEBRTC_ROOM_VALUE"
+    pause_continue
+    run_cmd "cd \"$WORK_DIR\" && NETWORK_ADAPTER=$NETWORK_ADAPTER WEBRTC_SIGNALING_URL=$WEBRTC_SIGNALING_URL_VALUE WEBRTC_ROOM=$WEBRTC_ROOM_VALUE npm run local-console"
+  else
+    echo "将使用以下参数启动（dev watch）："
+    echo "NETWORK_ADAPTER=$NETWORK_ADAPTER"
+    pause_continue
+    run_cmd "cd \"$WORK_DIR\" && NETWORK_ADAPTER=$NETWORK_ADAPTER npm run local-console"
+  fi
 else
-  echo "将使用以下参数启动："
-  echo "NETWORK_ADAPTER=$NETWORK_ADAPTER"
+  GATEWAY_CMD="cd \"$WORK_DIR\" && npm run gateway -- start --mode=$NETWORK_MODE"
+  if [ "$NETWORK_MODE" = "global-preview" ]; then
+    GATEWAY_CMD="$GATEWAY_CMD --signaling-url=$WEBRTC_SIGNALING_URL_VALUE --room=$WEBRTC_ROOM_VALUE"
+  fi
+  echo "将使用 gateway 后台启动："
+  echo "$GATEWAY_CMD"
   pause_continue
-  run_cmd "NETWORK_ADAPTER=$NETWORK_ADAPTER npm run local-console"
+  run_cmd "$GATEWAY_CMD"
+  echo ""
+  echo "已启动完成。常用命令："
+  echo "cd \"$WORK_DIR\" && npm run gateway -- status"
+  echo "cd \"$WORK_DIR\" && npm run gateway -- logs local-console"
+  echo "cd \"$WORK_DIR\" && npm run gateway -- stop"
+  echo ""
+  echo "打开: http://localhost:4310"
 fi
-

package/scripts/silicaclaw-cli.mjs

@@ -23,18 +23,101 @@ function run(cmd, args, extra = {}) {
   process.exit(result.status ?? 0);
 }
 
+function runCapture(cmd, args, extra = {}) {
+  const result = spawnSync(cmd, args, {
+    cwd: ROOT_DIR,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    env: process.env,
+    ...extra,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  return result;
+}
+
 function readVersion() {
   const versionFile = resolve(ROOT_DIR, "VERSION");
   if (!existsSync(versionFile)) return "unknown";
   return readFileSync(versionFile, "utf8").trim() || "unknown";
 }
 
+function readPackageVersion() {
+  const pkgFile = resolve(ROOT_DIR, "package.json");
+  if (!existsSync(pkgFile)) return "unknown";
+  try {
+    const pkg = JSON.parse(readFileSync(pkgFile, "utf8"));
+    return String(pkg.version || "unknown");
+  } catch {
+    return "unknown";
+  }
+}
+
+function isNpxRun() {
+  return ROOT_DIR.includes("/.npm/_npx/");
+}
+
+function showUpdateGuide(current, latest, beta) {
+  console.log("SilicaClaw update check");
+  console.log(`current: ${current}`);
+  console.log(`latest : ${latest || "-"}`);
+  console.log(`beta   : ${beta || "-"}`);
+  console.log("");
+
+  const upToDate = Boolean(beta) && current === beta;
+  if (upToDate) {
+    console.log("You are already on the latest beta.");
+  } else {
+    console.log("Update available.");
+  }
+  console.log("");
+  console.log("Recommended commands:");
+  console.log("1) npx mode (no global install)");
+  console.log("   npx @silicaclaw/cli@beta onboard");
+  console.log("   npx @silicaclaw/cli@beta connect");
+  console.log("");
+  console.log("2) global install mode");
+  console.log("   npm i -g @silicaclaw/cli@beta");
+  console.log("   silicaclaw version");
+  console.log("");
+  if (isNpxRun()) {
+    console.log("Detected npx runtime: use npx commands above for immediate update.");
+  }
+}
+
+function update() {
+  const current = readPackageVersion();
+  try {
+    const result = runCapture("npm", ["view", "@silicaclaw/cli", "dist-tags", "--json"]);
+    if ((result.status ?? 1) !== 0) {
+      console.error("Failed to query npm dist-tags.");
+      if (result.stderr) console.error(result.stderr.trim());
+      process.exit(result.status ?? 1);
+    }
+    const text = String(result.stdout || "").trim();
+    const tags = text ? JSON.parse(text) : {};
+    const latest = tags.latest ? String(tags.latest) : "";
+    const beta = tags.beta ? String(tags.beta) : "";
+    showUpdateGuide(current, latest, beta);
+    process.exit(0);
+  } catch (error) {
+    console.error(`Update check failed: ${error.message}`);
+    console.log("Try manually:");
+    console.log("npm view @silicaclaw/cli dist-tags --json");
+    process.exit(1);
+  }
+}
+
 function help() {
   console.log(`
 SilicaClaw CLI
 
 Usage:
   silicaclaw onboard
+  silicaclaw connect
+  silicaclaw update
+  silicaclaw gateway <start|stop|restart|status|logs>
   silicaclaw local-console
   silicaclaw explorer
   silicaclaw signaling
@@ -44,6 +127,9 @@ Usage:
 
 Commands:
   onboard        Interactive step-by-step onboarding (recommended)
+  connect        Cross-network connect wizard (global-preview first)
+  update         Check latest npm version and show upgrade commands
+  gateway        Manage background services (start/stop/restart/status/logs)
   local-console  Start local console (http://localhost:4310)
   explorer       Start public explorer (http://localhost:4311)
   signaling      Start WebRTC signaling preview server
@@ -59,6 +145,23 @@ switch (cmd) {
   case "onboard":
     run("bash", [resolve(ROOT_DIR, "scripts", "quickstart.sh")]);
     break;
+  case "connect":
+    run("bash", [resolve(ROOT_DIR, "scripts", "quickstart.sh")], {
+      env: {
+        ...process.env,
+        QUICKSTART_DEFAULT_MODE: "3",
+        QUICKSTART_CONNECT_MODE: "1",
+      },
+    });
+    break;
+  case "update":
+    update();
+    break;
+  case "gateway":
+    run("node", [resolve(ROOT_DIR, "scripts", "silicaclaw-gateway.mjs"), ...process.argv.slice(3)], {
+      cwd: process.cwd(),
+    });
+    break;
   case "local-console":
   case "console":
     run("npm", ["run", "local-console"]);