diff --git a/.gitignore b/.gitignore
index 09cb76c1..9a996e72 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 **/dist
 **/node_modules
 **/.env
+**/.cloudbase-sites/
 **/*.dxt
 # Environment variables
 .env.local
diff --git a/doc/mcp-tools.md b/doc/mcp-tools.md
index 87c2ea8a..c4ac6f24 100644
--- a/doc/mcp-tools.md
+++ b/doc/mcp-tools.md
@@ -1065,7 +1065,7 @@ CloudBase 云函数统一写入口。支持创建函数、更新代码、更新
 ---
 
 ### `manageHosting`
-管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。若任务只是查看配置、文件或域名状态，请改用 queryHosting。
+管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物到共享域名（域名格式：<envId>-<appId>.tcloudbaseapp.com/<cloudPath>）；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。⚠️ 新项目部署优先使用 manageApps（部署到独立子域名），本工具适合已有老项目继续使用或作为 manageApps 的 fallback。manageApps 与 manageHosting 域名不同，切换会导致老链接失效。若任务只是查看配置、文件或域名状态，请改用 queryHosting。
 
 #### 参数
 
diff --git a/mcp/src/tools/apps.test.ts b/mcp/src/tools/apps.test.ts
index 03f06aca..70c2ac07 100644
--- a/mcp/src/tools/apps.test.ts
+++ b/mcp/src/tools/apps.test.ts
@@ -62,6 +62,7 @@ describe("app tools", () => {
     mockDescribeAppInfo.mockResolvedValue({
       ServiceName: "demo-app",
       DeployType: "static-hosting",
+      Domain: "demo-app-env-test.webapps.tcloudbase.com",
       RequestId: "req-app-info",
     });
     mockDescribeAppVersionList.mockResolvedValue({
@@ -153,15 +154,43 @@ describe("app tools", () => {
         buildType: "ZIP",
       }),
     );
+    expect(mockDescribeAppInfo).toHaveBeenCalledWith({
+      deployType: "static-hosting",
+      serviceName: "demo-app",
+    });
     expect(payload).toMatchObject({
       success: true,
       data: {
         action: "deployApp",
         serviceName: "demo-app",
+        domain: "demo-app-env-test.webapps.tcloudbase.com",
+        accessUrl: "https://demo-app-env-test.webapps.tcloudbase.com",
       },
     });
   });
 
+  it("manageApps(action=deployApp) should normalize access URL from app details", async () => {
+    mockDescribeAppInfo.mockResolvedValueOnce({
+      ServiceName: "demo-app",
+      DeployType: "static-hosting",
+      Domain: "https://demo-app-env-test.webapps.tcloudbase.com/",
+      RequestId: "req-app-info",
+    });
+
+    const result = await tools.manageApps.handler({
+      action: "deployApp",
+      serviceName: "demo-app",
+      filePath: "/tmp/demo-app",
+      buildPath: "dist",
+    });
+    const payload = JSON.parse(result.content[0].text);
+
+    expect(payload.data.domain).toBe("demo-app-env-test.webapps.tcloudbase.com");
+    expect(payload.data.accessUrl).toBe("https://demo-app-env-test.webapps.tcloudbase.com");
+    expect(payload.data.accessUrlSource).toBe("describeAppInfo.Domain");
+    expect(payload.data.nextStep.hint).toContain("accessUrl");
+  });
+
   it("manageApps(action=deployApp) with cosTimestamp should skip uploadCode", async () => {
     const result = await tools.manageApps.handler({
       action: "deployApp",
diff --git a/mcp/src/tools/apps.ts b/mcp/src/tools/apps.ts
index ffbac8a7..f0042cc4 100644
--- a/mcp/src/tools/apps.ts
+++ b/mcp/src/tools/apps.ts
@@ -37,6 +37,24 @@ function getCloudAppService(cloudbase: any) {
   return cloudbase.cloudAppService ?? cloudbase.getCloudAppService?.();
 }
 
+function normalizeAccessUrlFromDomain(domain: unknown): { domain?: string; accessUrl?: string } {
+  if (typeof domain !== "string" || !domain.trim()) return {};
+  const trimmed = domain.trim();
+  const withProtocol = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  try {
+    const url = new URL(withProtocol);
+    url.hash = "";
+    url.search = "";
+    url.pathname = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+    return {
+      domain: url.host,
+      accessUrl: url.toString().replace(/\/$/, ""),
+    };
+  } catch {
+    return {};
+  }
+}
+
 export function registerAppTools(server: ExtendedMcpServer) {
   const cloudBaseOptions = server.cloudBaseOptions;
   const getManager = () => getCloudBaseManager({ cloudBaseOptions });
@@ -288,7 +306,7 @@ export function registerAppTools(server: ExtendedMcpServer) {
         appPath: z
           .string()
           .optional()
-          .describe("应用线上访问路径（hosting mount path），例如 /my-web-app。不是本地目录路径；省略时默认为 /serviceName。"),
+          .describe("应用线上访问路径（hosting mount path），例如 /my-web-app。不是本地目录路径；CloudApp 已有独立子域名，省略时默认为 /（根路径）。"),
         buildPath: z
           .string()
           .optional()
@@ -476,6 +494,21 @@ export function registerAppTools(server: ExtendedMcpServer) {
           logCloudBaseResult(server.logger, result);
 
           const { BuildId, VersionName } = result;
+          let appInfo: Record<string, unknown> | undefined;
+          let domain: string | undefined;
+          let accessUrl: string | undefined;
+          let accessUrlLookupWarning: string | undefined;
+          try {
+            appInfo = await appService.describeAppInfo({
+              deployType: "static-hosting",
+              serviceName,
+            });
+            logCloudBaseResult(server.logger, appInfo);
+            ({ domain, accessUrl } = normalizeAccessUrlFromDomain(appInfo?.Domain));
+          } catch (error) {
+            accessUrlLookupWarning = error instanceof Error ? error.message : String(error);
+          }
+
           return jsonContent(
             buildEnvelope(
               {
@@ -483,6 +516,11 @@ export function registerAppTools(server: ExtendedMcpServer) {
                 serviceName,
                 versionName: VersionName,
                 buildId: BuildId,
+                domain,
+                accessUrl,
+                accessUrlSource: accessUrl ? "describeAppInfo.Domain" : undefined,
+                accessUrlLookupWarning,
+                app: appInfo,
                 upload: { cosTimestamp: cosTs },
                 deployment: result,
                 buildConfig: {
@@ -498,10 +536,14 @@ export function registerAppTools(server: ExtendedMcpServer) {
                     serviceName,
                     buildId: BuildId,
                   },
-                  hint: `调用 queryApps(action="getAppVersion", serviceName="${serviceName}", buildId="${BuildId}") 轮询构建状态，直到 status 变为 SUCCESS 或 FAILED。构建通常需要 3~5 分钟。若状态为 FAILED，可继续调用 queryApps(action="getBuildLog", serviceName="${serviceName}", buildId="${BuildId}") 查看构建日志诊断失败原因。`,
+                  hint: accessUrl
+                    ? `调用 queryApps(action="getAppVersion", serviceName="${serviceName}", buildId="${BuildId}") 轮询构建状态，直到 status 变为 SUCCESS 或 FAILED。构建成功后，后续记录部署时必须使用本结果的 accessUrl=${accessUrl}，不要自行拼接域名。若状态为 FAILED，可继续调用 queryApps(action="getBuildLog", serviceName="${serviceName}", buildId="${BuildId}") 查看构建日志诊断失败原因。`
+                    : `调用 queryApps(action="getAppVersion", serviceName="${serviceName}", buildId="${BuildId}") 轮询构建状态，直到 status 变为 SUCCESS 或 FAILED；再调用 queryApps(action="getApp", serviceName="${serviceName}") 读取 app.Domain 作为 accessUrl，不能自行拼接域名。若状态为 FAILED，可继续调用 queryApps(action="getBuildLog", serviceName="${serviceName}", buildId="${BuildId}") 查看构建日志诊断失败原因。`,
                 },
               },
-              "CloudBase 应用构建已触发，请通过 queryApps 轮询构建状态。",
+              accessUrl
+                ? "CloudBase 应用构建已触发，已返回真实 accessUrl；请通过 queryApps 轮询构建状态。"
+                : "CloudBase 应用构建已触发，请通过 queryApps 轮询构建状态，并用 getApp 读取真实域名。",
             ),
           );
         }
diff --git a/plugin/cloudbase-sites/.claude-plugin/plugin.json b/plugin/cloudbase-sites/.claude-plugin/plugin.json
new file mode 100644
index 00000000..6bd1fc27
--- /dev/null
+++ b/plugin/cloudbase-sites/.claude-plugin/plugin.json
@@ -0,0 +1,22 @@
+{
+  "name": "cloudbase-sites",
+  "description": "CloudBase Sites — create, save, deploy, and inspect React/Vite web apps hosted on Tencent CloudBase. Inspired by Codex Sites' two-stage save→deploy pattern; powered by cloudbase-mcp.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Tencent CloudBase",
+    "url": "https://cloudbase.net"
+  },
+  "homepage": "https://github.com/TencentCloudBase/cloudbase-mcp",
+  "license": "MIT",
+  "keywords": [
+    "cloudbase",
+    "sites",
+    "vibe-coding",
+    "vite",
+    "react",
+    "vue",
+    "claude-code",
+    "codebuddy",
+    "openclaw"
+  ]
+}
diff --git a/plugin/cloudbase-sites/.codex-plugin/plugin.json b/plugin/cloudbase-sites/.codex-plugin/plugin.json
new file mode 100644
index 00000000..6cd310d7
--- /dev/null
+++ b/plugin/cloudbase-sites/.codex-plugin/plugin.json
@@ -0,0 +1,44 @@
+{
+  "name": "cloudbase-sites",
+  "version": "0.1.0",
+  "description": "CloudBase Sites lets Codex create, preview, save, deploy, inspect, and roll back Vite web apps hosted on Tencent CloudBase.",
+  "author": {
+    "name": "Tencent CloudBase",
+    "url": "https://cloudbase.net"
+  },
+  "homepage": "https://github.com/TencentCloudBase/cloudbase-mcp",
+  "repository": "https://github.com/TencentCloudBase/cloudbase-mcp",
+  "license": "MIT",
+  "keywords": [
+    "cloudbase",
+    "sites",
+    "codex",
+    "vibe-coding",
+    "vite",
+    "react",
+    "vue",
+    "deployment"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "CloudBase Sites",
+    "shortDescription": "Build, preview, version, and deploy sites to Tencent CloudBase.",
+    "longDescription": "Create Vite-based React or Vue web apps, preview them locally, save versions, deploy to CloudBase CloudApp independent domains, and add CloudBase database, storage, auth, functions, or CloudRun backend capabilities through cloudbase-mcp.",
+    "developerName": "Tencent CloudBase",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://cloudbase.net",
+    "privacyPolicyURL": "https://cloud.tencent.com/document/product/301/11470",
+    "termsOfServiceURL": "https://cloud.tencent.com/document/product/301/1967",
+    "defaultPrompt": [
+      "Build a CloudBase site and preview it locally.",
+      "Save this version, then deploy it to CloudBase.",
+      "Add database-backed state to this CloudBase site."
+    ],
+    "brandColor": "#006EFF"
+  }
+}
diff --git a/plugin/cloudbase-sites/.mcp.json b/plugin/cloudbase-sites/.mcp.json
new file mode 100644
index 00000000..3551de7c
--- /dev/null
+++ b/plugin/cloudbase-sites/.mcp.json
@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "cloudbase-mcp": {
+      "command": "npx",
+      "args": ["-y", "@cloudbase/cloudbase-mcp@latest"],
+      "env": {}
+    }
+  }
+}
diff --git a/plugin/cloudbase-sites/README.md b/plugin/cloudbase-sites/README.md
new file mode 100644
index 00000000..4391b4f6
--- /dev/null
+++ b/plugin/cloudbase-sites/README.md
@@ -0,0 +1,26 @@
+# CloudBase Sites Plugin
+
+CloudBase Sites packages the shared CloudBase site runtime for Claude Code,
+CodeBuddy, and Codex.
+
+## Codex local validation
+
+Validate the Codex plugin manifest from the repository root:
+
+```bash
+python3 /Users/bookerzhao/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugin/cloudbase-sites
+```
+
+Run the focused regression tests:
+
+```bash
+cd mcp
+node_modules/.bin/vitest run --config vitest.config.js ../tests/cloudbase-sites-plugin.test.js
+```
+
+## Runtime state
+
+Project-local runtime state is stored in `<project>/.cloudbase-sites/`.
+Machine-level supervisor state is stored in `~/.cloudbase-sites/`.
+
+These paths are runtime-only and should not be committed.
diff --git a/plugin/cloudbase-sites/bin/cloudbase-sites b/plugin/cloudbase-sites/bin/cloudbase-sites
new file mode 100755
index 00000000..ac5e2a60
--- /dev/null
+++ b/plugin/cloudbase-sites/bin/cloudbase-sites
@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * cloudbase-sites — single CLI for the CloudBase Sites plugin.
+ *
+ * Subcommands:
+ *   init          bootstrap CloudBase + React/Vue + Vite project from zero
+ *   preview       daemonize / inspect / stop / restart the Vite dev server
+ *   save          create a saved version (git commit + tag + app.json entry)
+ *   deploy        deploy a saved version to CloudApp via cloudbase-mcp manageApps
+ *   rollback      revert working tree to a saved version
+ *   versions      list saved versions and deployment status
+ *   supervisor    global watchdog daemon (start/stop/status/list/heal/reload)
+ *
+ * Run `cloudbase-sites <verb> --help` for verb-specific options.
+ *
+ * Every invocation also calls ensureSupervisorRunning() so the global
+ * watchdog stays alive across plugin operations (best-effort).
+ */
+
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const ctl = await import(join(__dirname, "..", "lib", "supervisor-ctl.mjs"));
+const { ensureSupervisorRunning } = ctl;
+
+// Best-effort supervisor ensure on every bin invocation. Skipped for the
+// daemon-loop entry to avoid recursion.
+const argv0 = process.argv[2];
+const argv1 = process.argv[3];
+const isDaemonLoop = argv0 === "supervisor" && argv1 === "--daemon-loop";
+if (!isDaemonLoop) {
+  try { ensureSupervisorRunning({ silent: true }); } catch { /* ignore */ }
+}
+
+const args = process.argv.slice(2);
+const verb = args[0];
+
+if (!verb || verb === "--help" || verb === "-h") {
+  printHelp();
+  process.exit(0);
+}
+
+const verbArgs = args.slice(1);
+
+main().catch(async (err) => {
+  const { emitErr } = await import(join(__dirname, "..", "lib", "emit.mjs"));
+  emitErr(err.message || String(err), err.code || 1);
+  process.exit(err.code || 1);
+});
+
+async function main() {
+  switch (verb) {
+    case "init": {
+      const { runInit, initHelp } = await import(join(__dirname, "..", "lib", "verbs", "init.mjs"));
+      const opts = parseInit(verbArgs);
+      if (opts.help) { console.log(initHelp); return; }
+      return runInit(opts);
+    }
+    case "preview": {
+      const { runPreview, previewHelp } = await import(join(__dirname, "..", "lib", "verbs", "preview.mjs"));
+      const opts = parsePreview(verbArgs);
+      if (opts.help) { console.log(previewHelp); return; }
+      return runPreview(opts);
+    }
+    case "save": {
+      const { runSave, saveHelp } = await import(join(__dirname, "..", "lib", "verbs", "save.mjs"));
+      const opts = parseSave(verbArgs);
+      if (opts.help) { console.log(saveHelp); return; }
+      return runSave(opts);
+    }
+    case "deploy": {
+      const { runDeploy, deployHelp } = await import(join(__dirname, "..", "lib", "verbs", "deploy.mjs"));
+      const opts = parseDeploy(verbArgs);
+      if (opts.help) { console.log(deployHelp); return; }
+      return runDeploy(opts);
+    }
+    case "rollback": {
+      const { runRollback, rollbackHelp } = await import(join(__dirname, "..", "lib", "verbs", "rollback.mjs"));
+      const opts = parseRollback(verbArgs);
+      if (opts.help) { console.log(rollbackHelp); return; }
+      return runRollback(opts);
+    }
+    case "versions": {
+      const { runVersions, versionsHelp } = await import(join(__dirname, "..", "lib", "verbs", "versions.mjs"));
+      if (verbArgs.includes("--help") || verbArgs.includes("-h")) { console.log(versionsHelp); return; }
+      return runVersions({});
+    }
+    case "supervisor": {
+      const { runSupervisor, supervisorHelp } = await import(join(__dirname, "..", "lib", "verbs", "supervisor.mjs"));
+      const sub = verbArgs[0];
+      if (!sub || sub === "--help" || sub === "-h") { console.log(supervisorHelp); return; }
+      return runSupervisor(sub, verbArgs.slice(1));
+    }
+    case "status":
+      // Convenience alias for `preview --status`
+      {
+        const { runPreview } = await import(join(__dirname, "..", "lib", "verbs", "preview.mjs"));
+        const opts = parsePreview(["--status", ...verbArgs]);
+        return runPreview(opts);
+      }
+    default: {
+      const { emitErr } = await import(join(__dirname, "..", "lib", "emit.mjs"));
+      emitErr(`Unknown verb: ${verb}. Run \`cloudbase-sites --help\` for the list.`, 1);
+      process.exit(1);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-verb arg parsers
+// ---------------------------------------------------------------------------
+
+function parseInit(argv) {
+  const out = { template: null, start: false, skipInstall: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--template") out.template = argv[++i];
+    else if (a === "--start") out.start = true;
+    else if (a === "--skip-install") out.skipInstall = true;
+    else if (a === "--help" || a === "-h") out.help = true;
+  }
+  return out;
+}
+
+function parsePreview(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--port") out.port = argv[++i];
+    else if (a === "--base") out.base = argv[++i];
+    else if (a === "--force" || a === "-f") out.force = true;
+    else if (a === "--restart") out.restart = true;
+    else if (a === "--stop") out.stop = true;
+    else if (a === "--status") out.status = true;
+    else if (a === "--quiet" || a === "-q") out.quiet = true;
+    else if (a === "--help" || a === "-h") out.help = true;
+  }
+  return out;
+}
+
+function parseSave(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--message" || a === "-m") out.message = argv[++i];
+    else if (a === "--help" || a === "-h") out.help = true;
+  }
+  return out;
+}
+
+function parseDeploy(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--version") out.version = argv[++i];
+    else if (a === "--skip-build") out.skipBuild = true;
+    else if (a === "--post" || a === "--post-deploy") out.post = true;
+    else if (a === "--access-url") out.accessUrl = argv[++i];
+    else if (a === "--build-id") out.buildId = argv[++i];
+    else if (a === "--version-name") out.versionName = argv[++i];
+    else if (a === "--build-status") out.buildStatus = argv[++i];
+    else if (a === "--help" || a === "-h") out.help = true;
+  }
+  return out;
+}
+
+function parseRollback(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--to-version") out.toVersion = argv[++i];
+    else if (a === "--no-restart") out.noRestart = true;
+    else if (a === "--help" || a === "-h") out.help = true;
+  }
+  return out;
+}
+
+function printHelp() {
+  process.stdout.write([
+    "cloudbase-sites — CloudBase Sites plugin CLI",
+    "",
+    "Subcommands:",
+    "  init          scaffold CloudBase + React/Vue + Vite from empty cwd",
+    "  preview       daemonize / inspect / stop / restart Vite dev server",
+    "  save          create a saved version (git checkpoint + app.json entry)",
+    "  deploy        deploy a saved version to CloudApp (manageApps)",
+    "  rollback      revert working tree to a saved version",
+    "  versions      list saved versions + deployment status",
+    "  supervisor    global watchdog daemon",
+    "",
+    "Run `cloudbase-sites <verb> --help` for verb-specific options.",
+    "",
+    "State files:",
+    "  <cwd>/.cloudbase-sites/preview.json    current dev server state",
+    "  <cwd>/.cloudbase-sites/app.json        siteName + versions[] + deployments[]",
+    "  ~/.cloudbase-sites/registry.json       all registered cwds (supervisor)",
+    "  ~/.cloudbase-sites/supervisor.json     global daemon state",
+    "",
+  ].join("\n"));
+}
diff --git a/plugin/cloudbase-sites/hooks/hooks.json b/plugin/cloudbase-sites/hooks/hooks.json
new file mode 100644
index 00000000..b2dbf1b4
--- /dev/null
+++ b/plugin/cloudbase-sites/hooks/hooks.json
@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/hooks/on-session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/hooks/on-file-change.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugin/cloudbase-sites/hooks/on-file-change.sh b/plugin/cloudbase-sites/hooks/on-file-change.sh
new file mode 100755
index 00000000..e4208173
--- /dev/null
+++ b/plugin/cloudbase-sites/hooks/on-file-change.sh
@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# on-file-change.sh — Claude Code / OpenClaw / CodeBuddy PostToolUse hook
+#
+# Reads the hook event payload from stdin (JSON). Restarts the daemonized
+# Vite dev server iff the edited file is one Vite HMR cannot handle (config
+# files, tsconfig, .env, package.json).
+#
+# Constraints:
+#   - exit fast (≤ ~50ms)
+#   - debounce: 1.5s lockfile so a rapid burst of edits restart only once
+#   - background restart so the hook returns immediately
+#   - exit code is always 0 — never block the user's tool call
+
+set -u
+
+# Read hook payload from stdin.
+PAYLOAD="$(cat)"
+
+# Without jq we cannot parse — silently skip. (Don't block the user.)
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+FILE_PATH="$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.file_path // empty')"
+CWD="$(printf '%s' "$PAYLOAD" | jq -r '.cwd // empty')"
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# --- Decide if file warrants a dev-server restart ---------------------------
+# Vite HMR handles src/*.tsx / *.css / public/* etc. We only restart for
+# changes Vite cannot hot-swap.
+restart=0
+case "$(basename "$FILE_PATH")" in
+  package.json | tsconfig.json | tsconfig.*.json) restart=1 ;;
+  vite.config.* | tailwind.config.* | postcss.config.*) restart=1 ;;
+  .env | .env.* ) restart=1 ;;
+esac
+if [ "$restart" = "0" ]; then
+  case "$FILE_PATH" in
+    */vite.config.* | */tailwind.config.* | */postcss.config.*) restart=1 ;;
+    */.env | */.env.*) restart=1 ;;
+  esac
+fi
+[ "$restart" = "1" ] || exit 0
+
+# --- Resolve target cwd (where preview.json lives) --------------------------
+TARGET_CWD="${CWD:-$(dirname "$FILE_PATH")}"
+
+find_preview_root() {
+  local d="$1"
+  while [ "$d" != "/" ] && [ -n "$d" ]; do
+    if [ -f "$d/.cloudbase-sites/preview.json" ]; then
+      printf '%s' "$d"
+      return 0
+    fi
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+PROJECT_ROOT="$(find_preview_root "$TARGET_CWD" || true)"
+[ -z "$PROJECT_ROOT" ] && exit 0
+
+# --- Debounce: 1.5s lockfile (Node.js Date.now() — cross-platform) ----------
+LOCK="$PROJECT_ROOT/.cloudbase-sites/restart.lock"
+NOW="$(node -e 'console.log(Date.now())' 2>/dev/null || python3 -c 'import time;print(int(time.time()*1000))' 2>/dev/null || echo 0)"
+if [ -f "$LOCK" ]; then
+  LAST="$(cat "$LOCK" 2>/dev/null || echo 0)"
+  case "$NOW$LAST" in *[!0-9]*) ;; *)
+    DELTA=$(( NOW - LAST ))
+    if [ "$DELTA" -lt 1500 ]; then
+      exit 0
+    fi
+  ;; esac
+fi
+mkdir -p "$(dirname "$LOCK")"
+printf '%s' "$NOW" > "$LOCK"
+
+# --- Async restart -----------------------------------------------------------
+SITES_BIN="$(command -v cloudbase-sites || true)"
+if [ -z "$SITES_BIN" ]; then
+  HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+  SITES_BIN="$HOOK_DIR/../bin/cloudbase-sites"
+  [ -x "$SITES_BIN" ] || exit 0  # give up silently — never block the user
+fi
+
+HOOK_LOG="$PROJECT_ROOT/.cloudbase-sites/logs/hook-restart.log"
+mkdir -p "$(dirname "$HOOK_LOG")"
+(
+  cd "$PROJECT_ROOT" || exit 0
+  printf '\n[%s] restart trigger: %s\n' "$(date -Iseconds 2>/dev/null || date)" "$FILE_PATH" >> "$HOOK_LOG"
+  "$SITES_BIN" preview --restart >> "$HOOK_LOG" 2>&1 || true
+) </dev/null >/dev/null 2>&1 &
+disown 2>/dev/null || true
+
+exit 0
diff --git a/plugin/cloudbase-vibe-coding/hooks/on-session-start.sh b/plugin/cloudbase-sites/hooks/on-session-start.sh
similarity index 55%
rename from plugin/cloudbase-vibe-coding/hooks/on-session-start.sh
rename to plugin/cloudbase-sites/hooks/on-session-start.sh
index e551f2c8..bb638bf5 100755
--- a/plugin/cloudbase-vibe-coding/hooks/on-session-start.sh
+++ b/plugin/cloudbase-sites/hooks/on-session-start.sh
@@ -15,16 +15,16 @@
 #     }
 #   }
 #
-# Hook log: <cwd>/.cloudbase-agent/logs/hook-session-start.log
+# Hook log: <cwd>/.cloudbase-sites/logs/hook-session-start.log
 
 set -u
 CWD="$(pwd)"
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLUGIN_ROOT="$(cd "$HOOK_DIR/.." && pwd)"
-LOG_FALLBACK="/tmp/cloudbase-vibe-session-start.log"
+LOG_FALLBACK="/tmp/cloudbase-sites-session-start.log"
 
 log() {
-  local target="$CWD/.cloudbase-agent/logs/hook-session-start.log"
+  local target="$CWD/.cloudbase-sites/logs/hook-session-start.log"
   mkdir -p "$(dirname "$target")" 2>/dev/null || target="$LOG_FALLBACK"
   printf '[%s] %s\n' "$(date -Iseconds 2>/dev/null || date)" "$*" >> "$target" 2>/dev/null || true
 }
@@ -50,19 +50,20 @@ emit_context() {
   # If node is missing, we silently skip — the hook still ran its decision tree.
 }
 
-# Build the static rules block used in every active branch. ~370 tokens.
-RULES_BLOCK='## CloudBase Vibe Coding (plugin-injected, MUST follow)
+# Build the static rules block used in every active branch.
+RULES_BLOCK='## CloudBase Sites (plugin-injected, MUST follow)
 
-You are in a session managed by the cloudbase-vibe-coding plugin. The dev server
-lifecycle is owned by hooks; you must not bypass them.
+You are in a session managed by the cloudbase-sites plugin. The dev server
+lifecycle and version control are owned by hooks + the `cloudbase-sites` CLI;
+you must not bypass them.
 
 ### Hard rules
 
 1. **Never guess the preview URL.** It is NOT 5173/5174/5175 — the plugin uses
    the 17173..17272 range AND each cwd may have its own port. Always run
-   `cloudbase-vibe-status-preview` (or read `<cwd>/.cloudbase-agent/preview.json`)
-   to obtain `internalUrl`. If status reports NO_PREVIEW (exit 5), wait ~5s
-   and retry once — the SessionStart hook may still be installing/starting.
+   `cloudbase-sites preview --status` (or read `<cwd>/.cloudbase-sites/preview.json`)
+   to obtain `internalUrl`. If it reports NO_PREVIEW (exit 5), wait ~5s and
+   retry once — the SessionStart hook may still be installing/starting.
 
 2. **"Make me a X app" = X IS the homepage.** When the user uses whole-house
    language ("build me a todo app", "make a chat app"), the request means
@@ -77,32 +78,37 @@ lifecycle is owned by hooks; you must not bypass them.
 
 3. **UI work for NEW features requires a design specification first.** When
    the user asks you to build a new app/feature/page from scratch (e.g.
-   "make a todo app", "build a chat UI", "add a dashboard"), you MUST invoke
-   the `ui-design` skill BEFORE writing any `.tsx`/`.css`/`.html` and produce
-   its design spec (Aesthetic Direction, Color Palette, Typography, Layout
-   Strategy). Do NOT improvise generic AI-default styling.
+   "make a todo app", "build a chat UI", "add a dashboard"), you MUST first
+   fetch the CloudBase ui-design skill via
+   `searchKnowledgeBase(mode=skill, skillName="ui-design")`,
+   produce its 4-part design spec (Aesthetic Direction, Color Palette,
+   Typography, Layout Strategy), output the spec to the user, THEN write
+   any `.tsx`/`.css`/`.html`. Do NOT improvise generic AI-default styling.
    Note: the CloudBase template'\''s `CLAUDE.md` "Existing Implementation First"
    exemption applies only to bug fixes / completing TODO markers in existing
-   code — it does NOT exempt you from `ui-design` when creating a new app
+   code — it does NOT exempt you from ui-design when creating a new app
    on top of the template.
 
 4. **Never spawn `npm run dev` / `vite` / `vite build` yourself.** Dev-server
    lifecycle is the SessionStart + PostToolUse hooks. Build/deploy is
-   `cloudbase-vibe-deploy`. Bypassing them loses host=0.0.0.0, port allocation,
-   daemonization, snapshot, and deploy history.
+   `cloudbase-sites deploy`. Bypassing them loses host=0.0.0.0, port allocation,
+   daemonization, version metadata, and deploy history.
 
 5. **Data persistence: BaaS-first via Web SDK + MCP-managed schema.** When
    the user'\''s feature needs to store / query / update data:
    - **Schema:** call cloudbase-mcp `writeNoSqlDatabaseStructure(action="createCollection", ...)`
      to create the collection (and `updateCollection` for indexes). Do NOT
-     ask the user to create collections manually in the console. The
-     `no-sql-web-sdk` skill describes the canonical patterns.
+     ask the user to create collections manually in the console. For canonical
+     patterns, fetch the no-sql-web-sdk skill via
+     `searchKnowledgeBase(mode=skill, skillName="no-sql-web-sdk")`.
    - **Reads/writes:** use `@cloudbase/js-sdk` directly from the React/Vue
      code (`db.collection(...).where(...).get()`, `.add()`, `.update()`,
      `db.collection(...).watch(...)` for realtime). The template already
      ships an initialized SDK at `src/utils/cloudbase.ts` — use it.
-   - **Auth:** if the feature needs user accounts, follow the `auth-tool`
-     skill first to verify provider config, then `auth-web` for client code.
+   - **Auth:** if the feature needs user accounts, fetch
+     `searchKnowledgeBase(mode=skill, skillName="auth-tool")` first to
+     verify provider config (the management-side configuration), then
+     `searchKnowledgeBase(mode=skill, skillName="auth-web")` for client code.
    - **Reach for cloud functions only when ALL of these are true:**
      (a) the logic absolutely cannot be expressed as database security rules,
      (b) it needs server-side secrets / third-party API keys, OR
@@ -112,48 +118,77 @@ lifecycle is owned by hooks; you must not bypass them.
      function "just for safety" is over-engineering.
 
 6. **Do not run browser tests / playwright / agent-browser by default.**
-   The user wants to SEE the running app, not read 5 minutes of test
-   reports. After you finish a feature:
+   The user wants to SEE the running app, not read 5 minutes of test reports.
+   After you finish a feature:
    - Spend zero turns on writing/running automated UI tests unless the user
      explicitly says "write tests" or "test it for me".
-   - Verify reasonably (preview is healthy, no compile error in `cloudbase-vibe-status-preview`
-     log) — that'\''s enough for the first version.
-   - Then ASK the user (similar to the deploy question): "要不要我用内置浏览器
-     打开 <URL> 帮你点一遍验证一下?" — only run browser-based verification
-     after explicit yes.
-
-### Tool quick-reference (only when user explicitly asks)
-
-- "stop the dev server"        → `cloudbase-vibe-stop-preview`
-- "is it running" / "the URL"  → `cloudbase-vibe-status-preview`
-- "deploy this" / "publish"    → `cloudbase-vibe-deploy` (then call `manageApps`
-                                  per its `nextAction` — it will pass
-                                  `framework=static, installCmd="", buildCmd=""`
-                                  to skip remote build, then
-                                  `cloudbase-vibe-deploy --post-deploy ...`).
-                                  **Uses `manageApps` (CloudApp, independent
-                                  per-session domain), NOT `manageHosting`.**
-                                  After deploy succeeds, ask the user:
-                                  "要我用 UI 设计能力进一步优化样式和体验吗?"
-
-### Deploy contract
-
-- **Each cwd has a stable `serviceName`** like `<dirname>-<6hex>` written to
-  `<cwd>/.cloudbase-agent/app.json` on first invocation. Re-deploying the same
-  cwd reuses this serviceName so the public URL stays stable for the user.
-- **`cloudbase-vibe-deploy` emits `nextAction` with `framework=static, installCmd="", buildCmd=""`**
-  — local build already produces dist/, so remote npm install/build are skipped.
-  Only `tcb hosting deploy` runs. See `skills/cloudbase-agent-runtime/SKILL.md` for full detail.
-- **Pre-flight you may need:** if no envId is bound yet (the deploy may fail
-  with an env error), call MCP `envQuery({ action: "info" })` once. If the
-  user has multiple envs, ask them to pick. After binding, retry the deploy.
-- **Active suggestion (D):** after you finish a user-requested feature
-  (i.e. you just completed "make/build/add a X" and tests / preview look good),
-  ASK the user at the end of your reply: "现在这版要部署看一下吗?" — do NOT
-  deploy unsolicited. Only deploy after explicit user consent. After deploy
-  succeeds, also ask: "要我用 UI 设计能力进一步优化样式和体验吗?"
-
-For full contract see `skills/cloudbase-agent-runtime/SKILL.md`.'
+   - Verify reasonably (preview is healthy, no compile error in
+     `cloudbase-sites preview --status` log) — that'\''s enough.
+   - Then ASK the user: "要不要我用内置浏览器打开 <URL> 帮你点一遍验证一下?"
+     — only run browser-based verification after explicit yes.
+
+7. **Two-stage save→deploy workflow (Codex-Sites-style).** Versions are
+   labeled git checkpoints; deploys are publishes of saved versions.
+   - When a user-visible feature is complete and the preview looks good,
+     ASK: "要保存这一版吗?(下次还能再调出来)" then run `cloudbase-sites save -m "<label>"`.
+     Each save creates `version/<n>` git tag + appends to `app.json.versions[]`.
+   - Then ASK: "现在要部署看一下吗?(独立 URL,可分享)". Only deploy after explicit yes.
+   - Deploy is two-phase via `cloudbase-sites deploy [--version <n>]`:
+     Phase 1 emits `nextAction.tool="manageApps"` with `framework=static,
+     installCmd="", buildCmd=""` (skips remote build — we built locally).
+     Phase 2 is `cloudbase-sites deploy --post --version <n> --access-url <url>
+     --build-id <BuildId> [--version-name <VersionName>]`. If `manageApps`
+     returns `BuildId`, you MUST pass it so build logs remain traceable.
+   - After deploy succeeds, ask: "要我用 ui-design 能力进一步优化样式和体验吗?"
+     If yes, fetch `searchKnowledgeBase(mode=skill, skillName="ui-design")`
+     and iterate.
+   - Rollback: `cloudbase-sites rollback [--to-version <n>]` (defaults to
+     current production deploy). Use only when user says "回到上一版" or similar.
+
+### CLI quick-reference
+
+- preview health/URL → `cloudbase-sites preview --status`
+- stop dev server   → `cloudbase-sites preview --stop`
+- list versions     → `cloudbase-sites versions`
+- save a version    → `cloudbase-sites save -m "<label>"`
+- deploy            → `cloudbase-sites deploy [--version <n>]`  (two-phase, see Rule 7)
+- rollback          → `cloudbase-sites rollback [--to-version <n>]`
+- supervisor info   → `cloudbase-sites supervisor status`
+
+### CloudBase Skill catalog (fetch on demand via cloudbase-mcp)
+
+These CloudBase domain skills are NOT bundled with this plugin and are NOT
+Claude Code native skills — fetch their full content on demand via:
+  `searchKnowledgeBase(mode=skill, skillName="<name>")`
+
+When a Hard rule above (or anywhere in your reasoning) references a skill
+"by name" — e.g. "调 ui-design skill", "follow auth-tool" — that means
+"call the MCP tool with skillName=<that-name> and apply the returned
+content". Do NOT look in `~/.claude/skills/` or `.claude/skills/`; these
+skills only live inside cloudbase-mcp.
+
+Likely-needed in a vibe-coding session:
+
+- `ui-design`               — UI 设计规范(必读,见 Rule 3)
+- `web-development`         — Web 项目开发与部署规范
+- `auth-tool`               — 认证 provider 启用与配置(管理端)
+- `auth-web`                — Web SDK 认证客户端代码
+- `no-sql-web-sdk`          — 文档型数据库 Web SDK CRUD
+- `cloud-storage-web`       — 云存储 Web SDK 上传下载
+- `relational-database-web` — MySQL Web SDK
+- `cloudbase-platform`      — CloudBase 平台总览(资源、链接、控制台路径)
+
+The full list of available skill names is returned by calling
+`searchKnowledgeBase(mode=skill)` with no `skillName` — the response lists
+all skills with their descriptions.
+
+### Pre-flight you may need
+
+If `manageApps` deploy fails with "no envId" or env-related error, call MCP
+`envQuery({ action: "info" })` once. If the user has multiple envs, ask them
+to pick. After binding, retry the deploy.
+
+For full contract see `skills/cloudbase-sites-runtime/SKILL.md`.'
 
 # Read payload (Claude Code passes JSON; OpenClaw should too).
 PAYLOAD="$(cat 2>/dev/null || true)"
@@ -194,10 +229,10 @@ fi
 
 # Helper: read internalUrl from preview.json if it exists, else "(starting...)".
 read_url() {
-  if command -v node >/dev/null 2>&1 && [ -f .cloudbase-agent/preview.json ]; then
+  if command -v node >/dev/null 2>&1 && [ -f .cloudbase-sites/preview.json ]; then
     node -e '
       try {
-        const p = JSON.parse(require("fs").readFileSync(".cloudbase-agent/preview.json","utf8"));
+        const p = JSON.parse(require("fs").readFileSync(".cloudbase-sites/preview.json","utf8"));
         process.stdout.write(p.internalUrl || "(starting...)");
       } catch { process.stdout.write("(starting...)"); }
     ' 2>/dev/null
@@ -208,38 +243,41 @@ read_url() {
 
 # Helper: build a deployment status block from app.json.
 read_deploy_block() {
-  if command -v node >/dev/null 2>&1 && [ -f .cloudbase-agent/app.json ]; then
+  if command -v node >/dev/null 2>&1 && [ -f .cloudbase-sites/app.json ]; then
     node -e '
       try {
-        const a = JSON.parse(require("fs").readFileSync(".cloudbase-agent/app.json","utf8"));
-        const serviceName = a.serviceName || "(not generated)";
-        const last = a.lastDeployedAt;
-        const lastUrl = a.lastAccessUrl;
-        const count = (a.deployHistory||[]).length;
+        const a = JSON.parse(require("fs").readFileSync(".cloudbase-sites/app.json","utf8"));
+        const siteName = a.siteName || "(not generated)";
+        const versions = Array.isArray(a.versions) ? a.versions : [];
+        const deployments = Array.isArray(a.deployments) ? a.deployments : [];
+        const last = deployments[deployments.length - 1] || null;
+        const currentVersion = a.currentVersion || versions[versions.length - 1]?.n || null;
+        const currentDeploy = a.currentDeploy || last?.version || null;
         let s = "- **deploy target:** CloudApp (manageApps) — independent service & domain per cwd\n";
-        s += `- **serviceName:** ${serviceName}` + (last ? "" : " (no deploy yet)") + "\n";
+        s += `- **siteName:** ${siteName}` + (last ? "" : " (no deploy yet)") + "\n";
+        s += `- **saved versions:** ${versions.length}` + (currentVersion ? ` (current v${currentVersion})` : "") + "\n";
         if (last) {
-          s += `- **last deploy:** ${last} (#${count})\n`;
-          s += `- **last access URL:** ${lastUrl}\n`;
+          s += `- **last deploy:** v${currentDeploy} at ${last.deployedAt}\n`;
+          s += `- **last access URL:** ${last.finalUrl || last.accessUrl}\n`;
+          if (last.buildId) s += `- **last buildId:** ${last.buildId}\n`;
         } else {
           s += "- **last deploy:** never — first deploy will create the CloudApp and assign a domain\n";
         }
         process.stdout.write(s);
       } catch (e) {
-        process.stdout.write("- **deploy target:** CloudApp (manageApps) — first deploy will generate serviceName & domain\n");
+        process.stdout.write("- **deploy target:** CloudApp (manageApps) — first deploy will generate siteName & domain\n");
       }
     ' 2>/dev/null
   else
-    printf -- '- **deploy target:** CloudApp (manageApps) — first deploy will generate serviceName & domain\n'
+    printf -- '- **deploy target:** CloudApp (manageApps) — first deploy will generate siteName & domain\n'
   fi
 }
 
 if [ "$is_vite_project" = "1" ]; then
   log "vite project detected"
-  STATUS_BIN="$PLUGIN_ROOT/bin/cloudbase-vibe-status-preview"
-  START_BIN="$PLUGIN_ROOT/bin/cloudbase-vibe-start-preview"
+  SITES_BIN="$PLUGIN_ROOT/bin/cloudbase-sites"
 
-  if "$STATUS_BIN" --quiet 2>/dev/null; then
+  if "$SITES_BIN" preview --status --quiet 2>/dev/null; then
     log "preview already running and healthy — reuse"
     URL="$(read_url)"
     DEPLOY_LINES="$(read_deploy_block)"
@@ -249,7 +287,7 @@ if [ "$is_vite_project" = "1" ]; then
 - **template:** vite-react/vue (existing)
 - **preview status:** running and healthy
 - **preview URL:** $URL
-- **first action:** confirm the URL with \`cloudbase-vibe-status-preview\` once before showing it to the user.
+- **first action:** confirm the URL with \`cloudbase-sites preview --status\` once before showing it to the user.
 $DEPLOY_LINES"
     emit_context "$RULES_BLOCK
 
@@ -261,8 +299,8 @@ $STATE_BLOCK"
     log "node_modules missing — install + start in background"
     nohup bash -c "
       pnpm install >/dev/null 2>&1 || npm install >/dev/null 2>&1
-      '$START_BIN' >/dev/null 2>&1
-    " </dev/null >>"$CWD/.cloudbase-agent/logs/hook-session-start.log" 2>&1 &
+      '$SITES_BIN' preview >/dev/null 2>&1
+    " </dev/null >>"$CWD/.cloudbase-sites/logs/hook-session-start.log" 2>&1 &
     disown 2>/dev/null || true
     DEPLOY_LINES="$(read_deploy_block)"
     STATE_BLOCK="### Current cwd state
@@ -270,8 +308,8 @@ $STATE_BLOCK"
 - **cwd:** $CWD
 - **template:** vite-react/vue (existing)
 - **preview status:** installing dependencies in background (~30s expected)
-- **preview URL:** (will be available after install — run \`cloudbase-vibe-status-preview\` to fetch it; wait 5–60s if it reports NO_PREVIEW)
-- **first action:** when the user is ready, confirm preview health by running \`cloudbase-vibe-status-preview\`, retrying once after 5s if needed.
+- **preview URL:** (will be available after install — run \`cloudbase-sites preview --status\` to fetch it; wait 5–60s if it reports NO_PREVIEW)
+- **first action:** when the user is ready, confirm preview health by running \`cloudbase-sites preview --status\`, retrying once after 5s if needed.
 $DEPLOY_LINES"
     emit_context "$RULES_BLOCK
 
@@ -280,7 +318,7 @@ $STATE_BLOCK"
   fi
 
   log "starting preview in background"
-  nohup "$START_BIN" </dev/null >>"$CWD/.cloudbase-agent/logs/hook-session-start.log" 2>&1 &
+  nohup "$SITES_BIN" preview </dev/null >>"$CWD/.cloudbase-sites/logs/hook-session-start.log" 2>&1 &
   disown 2>/dev/null || true
   DEPLOY_LINES="$(read_deploy_block)"
   STATE_BLOCK="### Current cwd state
@@ -288,8 +326,8 @@ $STATE_BLOCK"
 - **cwd:** $CWD
 - **template:** vite-react/vue (existing)
 - **preview status:** starting in background (a few seconds)
-- **preview URL:** (run \`cloudbase-vibe-status-preview\` to fetch the URL)
-- **first action:** run \`cloudbase-vibe-status-preview\` before quoting any URL to the user.
+- **preview URL:** (run \`cloudbase-sites preview --status\` to fetch the URL)
+- **first action:** run \`cloudbase-sites preview --status\` before quoting any URL to the user.
 $DEPLOY_LINES"
   emit_context "$RULES_BLOCK
 
@@ -301,7 +339,7 @@ fi
 empty_enough=1
 for entry in $(ls -A 2>/dev/null); do
   case "$entry" in
-    .git|.gitignore|.DS_Store|.cloudbase-agent|LICENSE|LICENSE.md|LICENSE.txt) ;;
+    .git|.gitignore|.DS_Store|.cloudbase-sites|LICENSE|LICENSE.md|LICENSE.txt) ;;
     README|README.md|README.MD|README.txt|readme.md) ;;
     *) empty_enough=0; break ;;
   esac
@@ -309,16 +347,16 @@ done
 
 if [ "$empty_enough" = "1" ]; then
   log "cwd is empty-enough — auto init react template + start in background"
-  INIT_BIN="$PLUGIN_ROOT/bin/cloudbase-vibe-init"
-  nohup "$INIT_BIN" --start </dev/null >>"$CWD/.cloudbase-agent/logs/hook-session-start.log" 2>&1 &
+  SITES_BIN="$PLUGIN_ROOT/bin/cloudbase-sites"
+  nohup "$SITES_BIN" init --start </dev/null >>"$CWD/.cloudbase-sites/logs/hook-session-start.log" 2>&1 &
   disown 2>/dev/null || true
   DEPLOY_LINES="$(read_deploy_block)"
   STATE_BLOCK="### Current cwd state
 
 - **cwd:** $CWD
 - **template:** none yet — auto-initializing CloudBase official React+Vite template in background (~10s expected: download zip + pnpm install + start dev server)
-- **preview URL:** (not ready yet — wait ~10s, then run \`cloudbase-vibe-status-preview\`; retry once after 5s if it reports NO_PREVIEW)
-- **first action:** wait until the user actually requests something, then run \`cloudbase-vibe-status-preview\` to confirm template+preview are ready before editing any files. The template will scaffold \`src/App.tsx\`, \`src/main.tsx\`, etc. — DO NOT create competing files until you have read what the template provides.
+- **preview URL:** (not ready yet — wait ~10s, then run \`cloudbase-sites preview --status\`; retry once after 5s if it reports NO_PREVIEW)
+- **first action:** wait until the user actually requests something, then run \`cloudbase-sites preview --status\` to confirm template+preview are ready before editing any files. The template will scaffold \`src/App.tsx\`, \`src/main.tsx\`, etc. — DO NOT create competing files until you have read what the template provides.
 $DEPLOY_LINES"
   emit_context "$RULES_BLOCK
 
diff --git a/plugin/cloudbase-sites/lib/app-store.mjs b/plugin/cloudbase-sites/lib/app-store.mjs
new file mode 100644
index 00000000..ce90210f
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/app-store.mjs
@@ -0,0 +1,134 @@
+/**
+ * <cwd>/.cloudbase-sites/app.json — site identity + version history.
+ *
+ * V2 schema:
+ *   {
+ *     siteName,                 // stable per cwd, generated once: <dirname>-<6hex>
+ *     cwd,
+ *     firstSeenAt,
+ *     versions: [
+ *       { n, commitSha, label, savedAt, status }   // status: saved|deployed|rolled-back
+ *     ],
+ *     deployments: [
+ *       { version, deployedAt, accessUrl, buildId, versionName, buildStatus, finalUrl }
+ *     ],
+ *     currentVersion,           // highest n in versions
+ *     currentDeploy             // version n of last successful deploy
+ *   }
+ */
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { ensureDir, STATE_DIR } from "./preview-state.mjs";
+
+export const APP_JSON_PATH = join(STATE_DIR, "app.json");
+
+// ---------------------------------------------------------------------------
+// Read / write
+// ---------------------------------------------------------------------------
+
+export function readApp() {
+  if (!existsSync(APP_JSON_PATH)) return null;
+  try { return JSON.parse(readFileSync(APP_JSON_PATH, "utf8")); }
+  catch { return null; }
+}
+
+export function writeApp(app) {
+  ensureDir(STATE_DIR);
+  const tmp = `${APP_JSON_PATH}.tmp`;
+  writeFileSync(tmp, JSON.stringify(app, null, 2));
+  renameSync(tmp, APP_JSON_PATH);
+}
+
+// ---------------------------------------------------------------------------
+// siteName: stable per cwd, generated once
+// ---------------------------------------------------------------------------
+
+export function getOrCreateSiteName() {
+  const existing = readApp();
+  if (existing?.siteName) return existing.siteName;
+
+  const CWD = process.cwd();
+  const raw = basename(CWD).toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 36);
+  const safe = raw || "site";
+  const suffix = randomBytes(3).toString("hex");
+  const name = `${safe}-${suffix}`;
+
+  const app = existing || { versions: [], deployments: [] };
+  app.siteName = name;
+  app.cwd = CWD;
+  if (!app.firstSeenAt) app.firstSeenAt = new Date().toISOString();
+  writeApp(app);
+  return name;
+}
+
+// ---------------------------------------------------------------------------
+// Version mutations
+// ---------------------------------------------------------------------------
+
+export function appendVersion({ commitSha, label }) {
+  const app = readApp() || { siteName: getOrCreateSiteName(), versions: [], deployments: [] };
+  const n = (app.versions[app.versions.length - 1]?.n || 0) + 1;
+  const entry = {
+    n,
+    commitSha,
+    label: label || null,
+    savedAt: new Date().toISOString(),
+    status: "saved",
+  };
+  app.versions.push(entry);
+  app.currentVersion = n;
+  writeApp(app);
+  return entry;
+}
+
+export function findVersion(n) {
+  const app = readApp();
+  if (!app) return null;
+  return app.versions.find((v) => v.n === Number(n)) || null;
+}
+
+export function latestSavedVersion() {
+  const app = readApp();
+  if (!app) return null;
+  // Highest n that's still in saved/deployed state (skip rolled-back).
+  for (let i = app.versions.length - 1; i >= 0; i--) {
+    if (app.versions[i].status !== "rolled-back") return app.versions[i];
+  }
+  return null;
+}
+
+export function appendDeployment({ version, accessUrl, buildId, versionName, buildStatus, finalUrl }) {
+  const app = readApp();
+  if (!app) throw new Error("no app.json — run save first");
+  const ts = new Date().toISOString();
+  app.deployments.push({
+    version,
+    deployedAt: ts,
+    accessUrl,
+    buildId: buildId || null,
+    versionName: versionName || null,
+    buildStatus: buildStatus || null,
+    finalUrl: finalUrl || accessUrl,
+  });
+  app.currentDeploy = version;
+  if (!app.firstDeployedAt) app.firstDeployedAt = ts;
+  // Mark the version as deployed.
+  const v = app.versions.find((x) => x.n === version);
+  if (v) v.status = "deployed";
+  writeApp(app);
+  return app.deployments[app.deployments.length - 1];
+}
+
+export function markVersionRolledBack(n) {
+  const app = readApp();
+  if (!app) return;
+  const v = app.versions.find((x) => x.n === n);
+  if (v) v.status = "rolled-back";
+  writeApp(app);
+}
diff --git a/plugin/cloudbase-sites/lib/emit.mjs b/plugin/cloudbase-sites/lib/emit.mjs
new file mode 100644
index 00000000..f1b112e9
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/emit.mjs
@@ -0,0 +1,25 @@
+/**
+ * Shared emit + error helpers used by every verb.
+ *
+ * Convention:
+ *   stdout — single JSON line, machine-readable.
+ *   stderr — single human-readable summary line, prefixed with [cloudbase-sites].
+ */
+
+export function emitOk(payload, humanLine) {
+  process.stdout.write(JSON.stringify({ ok: true, ...payload }) + "\n");
+  if (humanLine) process.stderr.write(`[cloudbase-sites] ${humanLine}\n`);
+}
+
+export function emitErr(message, code = 1, hint) {
+  const out = { ok: false, code, message };
+  if (hint) out.hint = hint;
+  process.stdout.write(JSON.stringify(out) + "\n");
+  process.stderr.write(`[cloudbase-sites] error (code=${code}): ${message}\n`);
+}
+
+export function withCode(code, message) {
+  const e = new Error(message);
+  e.code = code;
+  return e;
+}
diff --git a/plugin/cloudbase-sites/lib/git-utils.mjs b/plugin/cloudbase-sites/lib/git-utils.mjs
new file mode 100644
index 00000000..8aef4bc5
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/git-utils.mjs
@@ -0,0 +1,72 @@
+/**
+ * Common git helpers for save/deploy/rollback.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function isGitRepo(cwd) {
+  return spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "ignore" }).status === 0;
+}
+
+export function gitHead(cwd) {
+  const r = spawnSync("git", ["rev-parse", "--short", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"] });
+  if (r.status !== 0) return null;
+  return r.stdout.toString().trim();
+}
+
+export function gitHeadFull(cwd) {
+  const r = spawnSync("git", ["rev-parse", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"] });
+  if (r.status !== 0) return null;
+  return r.stdout.toString().trim();
+}
+
+export function gitWorkingTreeDirty(cwd) {
+  const r = spawnSync("git", ["status", "--porcelain", "--untracked-files=all"], {
+    cwd,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (r.status !== 0) return false;
+  return r.stdout.toString().trim().length > 0;
+}
+
+export function gitAddCommitTag(cwd, tag, message) {
+  spawnSync("git", [
+    "add", "-A", "--", ".",
+    ":!.cloudbase-sites",
+    ":!dist",
+    ":!node_modules",
+    ":!.env",
+    ":!.env.*",
+  ], { cwd, stdio: "ignore" });
+  spawnSync("git", ["commit", "--allow-empty", "-m", message], { cwd, stdio: "ignore" });
+  const tagR = spawnSync("git", ["tag", "-f", tag], { cwd, stdio: "ignore" });
+  return tagR.status === 0;
+}
+
+export function gitTagOnly(cwd, tag) {
+  return spawnSync("git", ["tag", "-f", tag], { cwd, stdio: "ignore" }).status === 0;
+}
+
+export function gitResetHard(cwd, ref) {
+  return spawnSync("git", ["reset", "--hard", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] }).status === 0;
+}
+
+export function gitStashIncludeUntracked(cwd, message) {
+  return spawnSync("git", ["stash", "push", "--include-untracked", "-m", message], { cwd, stdio: ["ignore", "pipe", "pipe"] }).status === 0;
+}
+
+export function ensureGitignoreEntry(cwd, entry) {
+  const gitignorePath = join(cwd, ".gitignore");
+  const normalized = entry.trim();
+  if (!normalized) return;
+  let current = "";
+  if (existsSync(gitignorePath)) {
+    current = readFileSync(gitignorePath, "utf8");
+    const lines = current.split(/\r?\n/).map((line) => line.trim());
+    if (lines.includes(normalized)) return;
+  }
+  const prefix = current && !current.endsWith("\n") ? "\n" : "";
+  writeFileSync(gitignorePath, `${current}${prefix}${normalized}\n`);
+}
diff --git a/plugin/cloudbase-sites/lib/preview-state.mjs b/plugin/cloudbase-sites/lib/preview-state.mjs
new file mode 100644
index 00000000..e8a94317
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/preview-state.mjs
@@ -0,0 +1,110 @@
+/**
+ * Preview state helpers (per-cwd).
+ *
+ * State at <cwd>/.cloudbase-sites/preview.json. Each cwd is its own world;
+ * cross-cwd coordination lives in lib/registry.mjs.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import http from "node:http";
+
+export const STATE_DIR = join(process.cwd(), ".cloudbase-sites");
+export const LOG_DIR = join(STATE_DIR, "logs");
+export const PREVIEW_JSON = join(STATE_DIR, "preview.json");
+
+export const ERR = Object.freeze({
+  GENERIC: 1,
+  NOT_VITE_PROJECT: 2,
+  PORT_POOL_EXHAUSTED: 3,
+  HEALTH_CHECK_FAILED: 4,
+  NO_PREVIEW_RUNNING: 5,
+  STOP_FAILED: 6,
+  BUILD_FAILED: 7,
+  DIST_MISSING: 8,
+  CWD_BLACKLISTED: 9,
+  CWD_NOT_EMPTY: 10,
+  DOWNLOAD_FAILED: 11,
+  EXTRACT_FAILED: 12,
+  INSTALL_FAILED: 13,
+  // V2: version control verbs
+  VERSION_NOT_FOUND: 14,
+  ROLLBACK_FAILED: 15,
+});
+
+// Re-export emit helpers so existing call sites keep working.
+export { emitOk, emitErr, withCode } from "./emit.mjs";
+
+// ---------------------------------------------------------------------------
+// State persistence
+// ---------------------------------------------------------------------------
+
+export function readPreview() {
+  if (!existsSync(PREVIEW_JSON)) return null;
+  try { return JSON.parse(readFileSync(PREVIEW_JSON, "utf8")); }
+  catch { return null; }
+}
+
+export function writePreview(state) {
+  ensureDir(STATE_DIR);
+  const tmp = `${PREVIEW_JSON}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2));
+  renameSync(tmp, PREVIEW_JSON);
+}
+
+export function clearPreview() {
+  try { if (existsSync(PREVIEW_JSON)) unlinkSync(PREVIEW_JSON); } catch {}
+}
+
+// ---------------------------------------------------------------------------
+// Process / health probes
+// ---------------------------------------------------------------------------
+
+export function isAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export function healthOk(port, timeoutMs = 2_000) {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host: "127.0.0.1", port, path: "/", timeout: timeoutMs },
+      (res) => {
+        res.resume();
+        resolve(!!(res.statusCode && res.statusCode < 500));
+      },
+    );
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => { req.destroy(); resolve(false); });
+  });
+}
+
+export async function stopPid(pid, { graceMs = 3_000 } = {}) {
+  if (!pid || !isAlive(pid)) return { ok: true, escalated: false };
+  if (graceMs > 0) {
+    try { process.kill(pid, "SIGTERM"); } catch (e) {
+      return { ok: false, escalated: false, error: e.message };
+    }
+    const t0 = Date.now();
+    while (Date.now() - t0 < graceMs) {
+      if (!isAlive(pid)) return { ok: true, escalated: false };
+      await sleep(120);
+    }
+  }
+  try { process.kill(pid, "SIGKILL"); } catch {}
+  await sleep(200);
+  return { ok: !isAlive(pid), escalated: true };
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+export function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
diff --git a/plugin/cloudbase-sites/lib/registry.mjs b/plugin/cloudbase-sites/lib/registry.mjs
new file mode 100644
index 00000000..d95ed26d
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/registry.mjs
@@ -0,0 +1,214 @@
+/**
+ * Global registry for vibe-coding workspaces.
+ *
+ * The supervisor and the bin scripts share state through:
+ *   ~/.cloudbase-sites/registry.json
+ *
+ * Schema:
+ *   { version, updatedAt,
+ *     entries: [
+ *       { cwd, sessionId, port, mountPath, previewPid,
+ *         registeredAt, lastCheckedAt, lastRestartAt,
+ *         restartCount, consecutiveFailures, status, lastFailureReason? } ] }
+ *
+ * Concurrency:
+ *   - mkdir-based file lock for each mutation (cross-process atomic)
+ *   - reads are lock-free; tolerate truncated/missing files
+ *   - mutations always rewrite the entire file (no partial JSON updates)
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const GLOBAL_DIR = join(homedir(), ".cloudbase-sites");
+export const REGISTRY_PATH = join(GLOBAL_DIR, "registry.json");
+export const SUPERVISOR_STATE_PATH = join(GLOBAL_DIR, "supervisor.json");
+export const SUPERVISOR_LOCK_DIR = join(GLOBAL_DIR, "supervisor.lock");
+export const REGISTRY_LOCK_DIR = join(GLOBAL_DIR, "registry.lock");
+export const SUPERVISOR_LOG = join(GLOBAL_DIR, "supervisor.log");
+
+const REGISTRY_VERSION = 1;
+const RESTART_BUDGET_BEFORE_DEGRADED = 5;
+export const RESTART_BUDGET = RESTART_BUDGET_BEFORE_DEGRADED;
+
+export const STATUS = Object.freeze({
+  RUNNING: "running",
+  STARTING: "starting",
+  RESTARTING: "restarting",
+  DEGRADED: "degraded",
+});
+
+export function ensureGlobalDir() {
+  if (!existsSync(GLOBAL_DIR)) mkdirSync(GLOBAL_DIR, { recursive: true });
+}
+
+// ---------------------------------------------------------------------------
+// Lock helpers (mkdir-based, atomic across processes)
+// ---------------------------------------------------------------------------
+
+function tryAcquireLock(lockDir, { timeoutMs = 2000, retryMs = 30 } = {}) {
+  ensureGlobalDir();
+  const t0 = Date.now();
+  for (;;) {
+    try { mkdirSync(lockDir); return true; } catch {}
+    if (Date.now() - t0 >= timeoutMs) return false;
+    // Tiny busy-wait (sync; ms-scale, OK for short locks).
+    const start = Date.now();
+    while (Date.now() - start < retryMs) { /* spin */ }
+  }
+}
+
+function releaseLock(lockDir) {
+  try { rmdirSync(lockDir); } catch {}
+}
+
+function withRegistryLock(fn) {
+  if (!tryAcquireLock(REGISTRY_LOCK_DIR)) {
+    // Stuck lock — break it. Risk is minimal since each mutation is a
+    // wholesale rewrite anyway.
+    try { rmdirSync(REGISTRY_LOCK_DIR); } catch {}
+    tryAcquireLock(REGISTRY_LOCK_DIR, { timeoutMs: 100 });
+  }
+  try { return fn(); } finally { releaseLock(REGISTRY_LOCK_DIR); }
+}
+
+// ---------------------------------------------------------------------------
+// Read / write
+// ---------------------------------------------------------------------------
+
+export function readRegistry() {
+  if (!existsSync(REGISTRY_PATH)) {
+    return { version: REGISTRY_VERSION, updatedAt: null, entries: [] };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(REGISTRY_PATH, "utf8"));
+    if (!Array.isArray(parsed.entries)) parsed.entries = [];
+    return parsed;
+  } catch {
+    return { version: REGISTRY_VERSION, updatedAt: null, entries: [] };
+  }
+}
+
+function writeRegistry(reg) {
+  ensureGlobalDir();
+  reg.version = REGISTRY_VERSION;
+  reg.updatedAt = new Date().toISOString();
+  const tmp = `${REGISTRY_PATH}.tmp`;
+  writeFileSync(tmp, JSON.stringify(reg, null, 2));
+  renameSync(tmp, REGISTRY_PATH);
+}
+
+// ---------------------------------------------------------------------------
+// Mutations
+// ---------------------------------------------------------------------------
+
+/**
+ * Idempotent: if cwd already exists, port/sessionId/previewPid are updated
+ * and counters reset.
+ */
+export function registerWorkspace({ cwd, sessionId, port, previewPid }) {
+  return withRegistryLock(() => {
+    const reg = readRegistry();
+    const i = reg.entries.findIndex((e) => e.cwd === cwd);
+    const now = new Date().toISOString();
+    const sid = sessionId || (reg.entries[i]?.sessionId ?? cwd.split("/").filter(Boolean).pop() ?? "vibe");
+    const next = {
+      cwd,
+      sessionId: sid,
+      port,
+      mountPath: `/s/${sid}/`,
+      previewPid: previewPid || null,
+      registeredAt: i === -1 ? now : reg.entries[i].registeredAt,
+      lastCheckedAt: now,
+      lastRestartAt: null,
+      restartCount: i === -1 ? 0 : (reg.entries[i].restartCount || 0),
+      consecutiveFailures: 0,
+      status: STATUS.RUNNING,
+    };
+    if (i === -1) reg.entries.push(next);
+    else reg.entries[i] = { ...reg.entries[i], ...next };
+    writeRegistry(reg);
+    return next;
+  });
+}
+
+export function unregisterWorkspace(cwd) {
+  return withRegistryLock(() => {
+    const reg = readRegistry();
+    const before = reg.entries.length;
+    reg.entries = reg.entries.filter((e) => e.cwd !== cwd);
+    if (reg.entries.length !== before) {
+      writeRegistry(reg);
+      return true;
+    }
+    return false;
+  });
+}
+
+export function patchWorkspace(cwd, patch) {
+  return withRegistryLock(() => {
+    const reg = readRegistry();
+    const i = reg.entries.findIndex((e) => e.cwd === cwd);
+    if (i === -1) return null;
+    reg.entries[i] = { ...reg.entries[i], ...patch };
+    writeRegistry(reg);
+    return reg.entries[i];
+  });
+}
+
+/**
+ * Increment failure counter; if it crosses the budget, mark as degraded.
+ * Returns { entry, degraded }.
+ */
+export function recordFailure(cwd, reason) {
+  return withRegistryLock(() => {
+    const reg = readRegistry();
+    const i = reg.entries.findIndex((e) => e.cwd === cwd);
+    if (i === -1) return { entry: null, degraded: false };
+    const e = reg.entries[i];
+    const fails = (e.consecutiveFailures || 0) + 1;
+    const degraded = fails >= RESTART_BUDGET_BEFORE_DEGRADED;
+    reg.entries[i] = {
+      ...e,
+      consecutiveFailures: fails,
+      lastRestartAt: new Date().toISOString(),
+      status: degraded ? STATUS.DEGRADED : STATUS.RESTARTING,
+      lastFailureReason: reason || null,
+    };
+    writeRegistry(reg);
+    return { entry: reg.entries[i], degraded };
+  });
+}
+
+export function recordSuccess(cwd, { wasRestart = false, previewPid = null, port = null } = {}) {
+  return withRegistryLock(() => {
+    const reg = readRegistry();
+    const i = reg.entries.findIndex((e) => e.cwd === cwd);
+    if (i === -1) return null;
+    const now = new Date().toISOString();
+    const e = reg.entries[i];
+    reg.entries[i] = {
+      ...e,
+      lastCheckedAt: now,
+      consecutiveFailures: 0,
+      status: STATUS.RUNNING,
+      previewPid: previewPid ?? e.previewPid,
+      port: port ?? e.port,
+      ...(wasRestart ? { restartCount: (e.restartCount || 0) + 1, lastRestartAt: now } : {}),
+    };
+    writeRegistry(reg);
+    return reg.entries[i];
+  });
+}
+
+export function listWorkspaces() {
+  return readRegistry().entries;
+}
diff --git a/plugin/cloudbase-sites/lib/supervisor-ctl.mjs b/plugin/cloudbase-sites/lib/supervisor-ctl.mjs
new file mode 100644
index 00000000..05d4f46f
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/supervisor-ctl.mjs
@@ -0,0 +1,158 @@
+/**
+ * Supervisor control plane: shared helpers used by both the supervisor daemon
+ * (cloudbase-sites supervisor) and every other bin script.
+ *
+ * The exported `ensureSupervisorRunning()` is the contract every bin command
+ * calls at startup. It is:
+ *   - safe (mkdir-based lock so 5 parallel callers spawn at most 1 daemon)
+ *   - cheap (a healthy supervisor returns in ~1ms)
+ *   - non-blocking (spawns detached and returns; doesn't wait for daemon ready)
+ */
+
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import {
+  GLOBAL_DIR,
+  SUPERVISOR_LOCK_DIR,
+  SUPERVISOR_LOG,
+  SUPERVISOR_STATE_PATH,
+  ensureGlobalDir,
+} from "./registry.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SITES_BIN = join(__dirname, "..", "bin", "cloudbase-sites");
+
+// ---------------------------------------------------------------------------
+// Supervisor PID file
+// ---------------------------------------------------------------------------
+
+export function readSupervisorState() {
+  if (!existsSync(SUPERVISOR_STATE_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(SUPERVISOR_STATE_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeSupervisorState(state) {
+  ensureGlobalDir();
+  const tmp = `${SUPERVISOR_STATE_PATH}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2));
+  renameSync(tmp, SUPERVISOR_STATE_PATH);
+}
+
+export function clearSupervisorState() {
+  try { if (existsSync(SUPERVISOR_STATE_PATH)) unlinkSync(SUPERVISOR_STATE_PATH); } catch {}
+}
+
+export function isSupervisorAlive() {
+  const s = readSupervisorState();
+  if (!s?.pid) return false;
+  try { process.kill(s.pid, 0); return true; } catch { return false; }
+}
+
+// ---------------------------------------------------------------------------
+// ensureSupervisorRunning — public entry every bin command calls
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn a detached supervisor daemon if (and only if) one isn't already
+ * running. Idempotent and concurrency-safe.
+ *
+ * Returns: { spawned: boolean, alive: boolean, pid: number|null }
+ */
+export function ensureSupervisorRunning({ silent = true } = {}) {
+  if (isSupervisorAlive()) {
+    return { spawned: false, alive: true, pid: readSupervisorState()?.pid ?? null };
+  }
+
+  ensureGlobalDir();
+
+  // Acquire spawn lock so 5 parallel callers don't all spawn.
+  const lockTimeoutMs = 1500;
+  const t0 = Date.now();
+  let acquired = false;
+  while (Date.now() - t0 < lockTimeoutMs) {
+    try { mkdirSync(SUPERVISOR_LOCK_DIR); acquired = true; break; } catch {}
+    // Re-probe in case the other caller already finished spawning.
+    if (isSupervisorAlive()) {
+      return { spawned: false, alive: true, pid: readSupervisorState()?.pid ?? null };
+    }
+    const start = Date.now();
+    while (Date.now() - start < 60) { /* spin */ }
+  }
+  if (!acquired) {
+    // Stuck lock — break it (the previous spawn likely crashed mid-flight).
+    try { rmdirSync(SUPERVISOR_LOCK_DIR); } catch {}
+    try { mkdirSync(SUPERVISOR_LOCK_DIR); } catch {}
+  }
+
+  try {
+    // Re-check inside the lock.
+    if (isSupervisorAlive()) {
+      return { spawned: false, alive: true, pid: readSupervisorState()?.pid ?? null };
+    }
+    const logFd = openSync(SUPERVISOR_LOG, "a");
+    const child = spawn(process.execPath, [SITES_BIN, "supervisor", "--daemon-loop"], {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      windowsHide: true,
+      cwd: GLOBAL_DIR,
+    });
+    child.unref();
+    if (!silent) {
+      process.stderr.write(`[cloudbase-sites] supervisor started (pid ${child.pid})\n`);
+    }
+    // The daemon writes supervisor.json itself once running; we don't pre-write
+    // here because a race could leave a stale file if the daemon crashes early.
+    return { spawned: true, alive: true, pid: child.pid };
+  } finally {
+    try { rmdirSync(SUPERVISOR_LOCK_DIR); } catch {}
+  }
+}
+
+/**
+ * Stop the running supervisor (graceful TERM, then KILL fallback).
+ * Returns { stopped, pid, escalated?, reason? }.
+ */
+export async function stopSupervisor({ graceMs = 3000 } = {}) {
+  const s = readSupervisorState();
+  if (!s?.pid) {
+    clearSupervisorState();
+    return { stopped: false, pid: null, reason: "not running" };
+  }
+  if (!isSupervisorAlive()) {
+    clearSupervisorState();
+    return { stopped: false, pid: s.pid, reason: "process already gone" };
+  }
+  try { process.kill(s.pid, "SIGTERM"); } catch {}
+  const t0 = Date.now();
+  while (Date.now() - t0 < graceMs) {
+    if (!isSupervisorAlive()) {
+      clearSupervisorState();
+      return { stopped: true, pid: s.pid, escalated: false };
+    }
+    await sleep(120);
+  }
+  try { process.kill(s.pid, "SIGKILL"); } catch {}
+  await sleep(200);
+  const finallyDead = !isSupervisorAlive();
+  if (finallyDead) clearSupervisorState();
+  return { stopped: finallyDead, pid: s.pid, escalated: true };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
diff --git a/plugin/cloudbase-sites/lib/verbs/deploy.mjs b/plugin/cloudbase-sites/lib/verbs/deploy.mjs
new file mode 100644
index 00000000..304e80a2
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/verbs/deploy.mjs
@@ -0,0 +1,279 @@
+/**
+ * `cloudbase-sites deploy` — bridge a saved version to cloudbase-mcp manageApps.
+ *
+ * Two phases (model bridges via MCP):
+ *   Phase 1 — `cloudbase-sites deploy [--version <n>]`:
+ *     - Resolve version (default: latest saved). Refuse if no version saved
+ *       — user must `save` first.
+ *     - If currently checked out commit != version's commit, stash local edits
+ *       and reset to the saved version before building. Deploying a saved
+ *       version means building that saved commit, not the current working tree.
+ *     - pnpm/npm run build → validate dist/
+ *     - emit nextAction { tool:"manageApps", args:{ action:"deployApp",
+ *         serviceName:siteName, filePath:cwd, buildPath:"dist",
+ *         framework:"static", installCmd:"", buildCmd:"" } }
+ *
+ *   Phase 2 — `cloudbase-sites deploy --post --version <n> --access-url <url> [--build-id <id>] [--version-name <name>]`:
+ *     - Append to app.json.deployments[]
+ *     - Mark version as "deployed"
+ *     - git tag deploy/<n>-<ts>
+ *     - emit { finalUrl: <accessUrl>?v=<rand6> }
+ *
+ * Rationale: see Codex Sites two-stage save→deploy pattern. Local build runs
+ * here; remote `manageApps` only does `tcb hosting deploy` (framework=static,
+ * no install/build).
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { emitOk, withCode } from "../emit.mjs";
+import { ERR } from "../preview-state.mjs";
+import {
+  appendDeployment,
+  findVersion,
+  getOrCreateSiteName,
+  latestSavedVersion,
+  readApp,
+} from "../app-store.mjs";
+import {
+  gitHeadFull,
+  gitResetHard,
+  gitStashIncludeUntracked,
+  gitTagOnly,
+  gitWorkingTreeDirty,
+  isGitRepo,
+} from "../git-utils.mjs";
+
+export const deployHelp = `cloudbase-sites deploy — deploy a saved version to CloudApp (manageApps).
+
+Phase 1 (build + emit nextAction):
+  cloudbase-sites deploy [--version <n>]   # default: latest saved version
+  cloudbase-sites deploy --skip-build      # already built; just emit nextAction
+
+Phase 2 (record after manageApps succeeds):
+  cloudbase-sites deploy --post --version <n> --access-url <url> [--build-id <id>] [--version-name <name>]
+
+Behavior:
+  - Reads stable siteName from <cwd>/.cloudbase-sites/app.json.
+  - Phase 1 builds dist/ and emits a JSON whose nextAction tells the model to
+    call cloudbase-mcp manageApps with framework=static (skip remote install/build).
+  - Phase 2 appends to deployments[], tags git deploy/<n>-<ts>, returns finalUrl.
+
+Refuses to deploy if no version has been saved (run \`cloudbase-sites save\` first).`;
+
+export async function runDeploy(args) {
+  if (args.post) return runPostDeploy(args);
+
+  const CWD = process.cwd();
+
+  // Verify Vite project.
+  const pkg = readPkg(CWD);
+  if (!pkg) throw withCode(ERR.NOT_VITE_PROJECT, "no package.json in cwd");
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  if (!deps.vite) throw withCode(ERR.NOT_VITE_PROJECT, "vite not in dependencies/devDependencies");
+  if (!deps.react && !deps.vue) throw withCode(ERR.NOT_VITE_PROJECT, "neither react nor vue is a dependency");
+
+  // Resolve version.
+  let version;
+  if (args.version) {
+    version = findVersion(args.version);
+    if (!version) throw withCode(ERR.VERSION_NOT_FOUND, `version ${args.version} not found — run \`cloudbase-sites versions\` to list`);
+  } else {
+    version = latestSavedVersion();
+    if (!version) {
+      throw withCode(
+        ERR.VERSION_NOT_FOUND,
+        "no saved version yet — run `cloudbase-sites save` to create one before deploying",
+      );
+    }
+  }
+
+  const siteName = getOrCreateSiteName();
+  const checkout = ensureSavedVersionCheckedOut(CWD, version);
+
+  // Build.
+  if (!args.skipBuild) {
+    const buildScript = pkg.scripts?.build;
+    if (!buildScript) throw withCode(ERR.BUILD_FAILED, "package.json has no scripts.build");
+    runBuild(CWD);
+  }
+
+  // Validate dist/.
+  const distPath = join(CWD, "dist");
+  if (!existsSync(distPath) || !statSync(distPath).isDirectory()) {
+    throw withCode(ERR.DIST_MISSING, "dist/ does not exist after build");
+  }
+  const entries = readdirSync(distPath);
+  if (entries.length === 0) throw withCode(ERR.DIST_MISSING, "dist/ is empty after build");
+
+  const app = readApp();
+  const previouslyDeployed = !!app?.currentDeploy;
+
+  emitOk(
+    {
+      stage: "build-complete",
+      siteName,
+      version: version.n,
+      versionLabel: version.label,
+      versionCommit: version.commitSha,
+      checkout,
+      distPath,
+      distEntries: entries.length,
+      previouslyDeployed,
+      nextAction: {
+        tool: "manageApps",
+        args: {
+          action: "deployApp",
+          serviceName: siteName,
+          filePath: CWD,
+          buildPath: "dist",
+          framework: "static",
+          installCmd: "",
+          buildCmd: "",
+        },
+        hint: previouslyDeployed
+          ? `Re-deploys CloudApp '${siteName}' (URL stays the same).`
+          : `First-time deploy creates CloudApp '${siteName}' with its own subdomain.`,
+        followup: {
+          tool: "cloudbase-sites",
+          args: ["deploy", "--post", "--version", String(version.n), "--access-url", "<manageApps data.accessUrl; do not infer>", "--build-id", "<manageApps data.buildId>", "--version-name", "<manageApps data.versionName optional>"],
+          purpose: "record this deploy and CloudBase build metadata in app.json, then tag git",
+        },
+      },
+    },
+    `build complete; deploy version ${version.n} of '${siteName}' next via manageApps (framework=static)`,
+  );
+}
+
+function ensureSavedVersionCheckedOut(cwd, version) {
+  if (!isGitRepo(cwd)) return { checked: false, reason: "not a git repository" };
+  const head = gitHeadFull(cwd);
+  const headMatches = head && (head === version.commitSha || head.startsWith(version.commitSha) || version.commitSha.startsWith(head));
+  const dirty = gitWorkingTreeDirty(cwd);
+  if (headMatches && !dirty) {
+    return { checked: true, changed: false, commitSha: version.commitSha };
+  }
+  const stashed = gitStashIncludeUntracked(cwd, `cloudbase-sites pre-deploy version ${version.n}`);
+  if (dirty && !stashed) {
+    throw withCode(ERR.GENERIC, "git stash failed before deploy; aborting to avoid publishing or discarding unsaved edits");
+  }
+  if (!gitResetHard(cwd, version.commitSha)) {
+    throw withCode(ERR.GENERIC, `git reset --hard ${version.commitSha} failed before deploy`);
+  }
+  return {
+    checked: true,
+    changed: !headMatches,
+    dirty,
+    stashed,
+    commitSha: version.commitSha,
+  };
+}
+
+async function runPostDeploy(args) {
+  if (!args.accessUrl) throw withCode(ERR.GENERIC, "--post requires --access-url");
+  const accessUrl = normalizeAccessUrl(args.accessUrl);
+  const versionN = args.version ? Number(args.version) : null;
+  if (!versionN) throw withCode(ERR.GENERIC, "--post requires --version <n>");
+  if (!findVersion(versionN)) {
+    throw withCode(ERR.VERSION_NOT_FOUND, `version ${versionN} not found in app.json`);
+  }
+
+  const cacheBust = randomBytes(3).toString("hex");
+  const finalUrl = appendQuery(accessUrl, `v=${cacheBust}`);
+
+  const entry = appendDeployment({
+    version: versionN,
+    accessUrl,
+    buildId: args.buildId,
+    versionName: args.versionName,
+    buildStatus: args.buildStatus || "SUCCESS",
+    finalUrl,
+  });
+  const warnings = [];
+  if (!args.buildId) {
+    warnings.push("No buildId was provided; this deployment cannot directly query CloudBase build status or logs.");
+  }
+
+  // Tag git: deploy/<n>-<ts>.
+  const tag = `deploy/${versionN}-${Date.now()}`;
+  if (isGitRepo(process.cwd())) gitTagOnly(process.cwd(), tag);
+
+  const app = readApp();
+  emitOk(
+    {
+      stage: "post-deploy",
+      siteName: app?.siteName ?? null,
+      version: versionN,
+      ...entry,
+      gitTag: tag,
+      deployCount: app?.deployments?.length ?? 0,
+      warnings,
+    },
+    `deploy recorded for '${app?.siteName}' v${versionN} — open: ${finalUrl}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function readPkg(cwd) {
+  const p = join(cwd, "package.json");
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+
+function pickRunner(cwd) {
+  const which = (b) => spawnSync(process.platform === "win32" ? "where" : "which", [b], { stdio: "ignore" }).status === 0;
+  if (existsSync(join(cwd, "pnpm-lock.yaml")) && which("pnpm")) return ["pnpm", "run", "build"];
+  if (which("pnpm")) return ["pnpm", "run", "build"];
+  if (which("npm")) return ["npm", "run", "build"];
+  return ["npx", "--yes", "--no-install", "vite", "build"];
+}
+
+function runBuild(cwd) {
+  const [cmd, ...rest] = pickRunner(cwd);
+  const r = spawnSync(cmd, rest, { cwd, stdio: ["ignore", "inherit", "inherit"], env: process.env });
+  if (r.status !== 0) {
+    throw withCode(ERR.BUILD_FAILED, `build exited with code ${r.status} (cmd: ${cmd} ${rest.join(" ")})`);
+  }
+}
+
+function appendQuery(url, qs) {
+  if (!url || !qs) return url;
+  return url + (url.includes("?") ? "&" : "?") + qs;
+}
+
+function normalizeAccessUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw withCode(ERR.GENERIC, "--access-url must be a valid http(s) URL returned by manageApps data.accessUrl");
+  }
+
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw withCode(ERR.GENERIC, "--access-url must use http or https");
+  }
+
+  const host = url.hostname.toLowerCase();
+  if (host.endsWith(".service.tcloudbase.com")) {
+    throw withCode(
+      ERR.GENERIC,
+      '--access-url looks like a guessed CloudBase service domain. Use manageApps data.accessUrl, or queryApps(action="getApp") and pass app.Domain; CloudBase Sites default domains end with .webapps.tcloudbase.com.',
+    );
+  }
+
+  if (host.endsWith(".tcloudbase.com") && !host.endsWith(".webapps.tcloudbase.com")) {
+    throw withCode(
+      ERR.GENERIC,
+      '--access-url is not a CloudBase Sites app domain. Use manageApps data.accessUrl, or queryApps(action="getApp") and pass app.Domain; expected .webapps.tcloudbase.com for default CloudBase Sites domains.',
+    );
+  }
+
+  url.hash = "";
+  url.pathname = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+  return url.toString().replace(/\/$/, "");
+}
diff --git a/plugin/cloudbase-sites/lib/verbs/init.mjs b/plugin/cloudbase-sites/lib/verbs/init.mjs
new file mode 100644
index 00000000..d5c102cf
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/verbs/init.mjs
@@ -0,0 +1,217 @@
+/**
+ * `cloudbase-sites init` — bootstrap CloudBase + React/Vue + Vite project from zero.
+ *
+ * Steps:
+ *   1. Sanity: cwd is not in the danger blacklist.
+ *   2. Sanity: cwd is "empty enough" (only .git/.gitignore/README/LICENSE/.cloudbase-sites allowed).
+ *   3. Download CloudBase official template zip via HTTPS.
+ *   4. Extract zip into cwd (template is a flat zip).
+ *   5. Run pnpm/npm install.
+ *   6. Optionally `cloudbase-sites preview` if --start passed.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+} from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import https from "node:https";
+import { emitOk, withCode } from "../emit.mjs";
+import { ensureGitignoreEntry } from "../git-utils.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const ERR = {
+  GENERIC: 1,
+  CWD_BLACKLISTED: 9,
+  CWD_NOT_EMPTY: 10,
+  DOWNLOAD_FAILED: 11,
+  EXTRACT_FAILED: 12,
+  INSTALL_FAILED: 13,
+};
+
+const TEMPLATE_URLS = {
+  react: "https://static.cloudbase.net/cloudbase-examples/web-cloudbase-react-template.zip",
+  vue: "https://static.cloudbase.net/cloudbase-examples/web-cloudbase-vue-template.zip",
+};
+
+export const initHelp = `cloudbase-sites init — bootstrap CloudBase + React/Vue + Vite project in cwd
+
+Options:
+  --template <name>   react (default) | vue
+  --start             also start dev server after install (call cloudbase-sites preview)
+  --skip-install      download + extract only, no npm/pnpm install
+
+Refuses to run in danger blacklist dirs ($HOME, /, /tmp, ~/Desktop, ...).
+Refuses to run if cwd has files other than .git/.gitignore/README/LICENSE/.cloudbase-sites.
+
+Exit codes:  9=cwd blacklisted  10=cwd not empty  11=download failed
+             12=extract failed  13=install failed`;
+
+export async function runInit(args) {
+  const CWD = process.cwd();
+
+  // 1. Blacklist check.
+  const blackReason = checkBlacklist(CWD);
+  if (blackReason) {
+    throw withCode(ERR.CWD_BLACKLISTED, `Refusing to init in '${CWD}' (${blackReason}). Cd to a project directory first.`);
+  }
+
+  // 2. Empty-enough check.
+  const occupants = listMeaningfulFiles(CWD);
+  if (occupants.length > 0) {
+    throw withCode(
+      ERR.CWD_NOT_EMPTY,
+      `Cwd is not empty (found: ${occupants.slice(0, 5).join(", ")}${occupants.length > 5 ? ", ..." : ""}). Remove or move them first.`,
+    );
+  }
+
+  const template = args.template || "react";
+  if (!TEMPLATE_URLS[template]) {
+    throw withCode(ERR.GENERIC, `unsupported template '${template}', expected react|vue`);
+  }
+  ensureGitignoreEntry(CWD, ".cloudbase-sites/");
+  const url = TEMPLATE_URLS[template];
+
+  // 3. Download.
+  const zipPath = join(CWD, ".cloudbase-sites", "template.zip");
+  mkdirSync(dirname(zipPath), { recursive: true });
+  process.stderr.write(`[cloudbase-sites] downloading ${template} template…\n`);
+  await downloadFile(url, zipPath);
+
+  // 4. Extract.
+  process.stderr.write(`[cloudbase-sites] extracting…\n`);
+  const unzipR = spawnSync("unzip", ["-q", "-o", zipPath, "-d", CWD], { stdio: "inherit" });
+  if (unzipR.status !== 0) {
+    throw withCode(ERR.EXTRACT_FAILED, `unzip exited with code ${unzipR.status}. Is 'unzip' installed?`);
+  }
+  try { rmSync(zipPath); } catch {}
+
+  // 5. Install.
+  if (!args.skipInstall) {
+    process.stderr.write(`[cloudbase-sites] installing dependencies (this may take ~30s)…\n`);
+    const ok = runInstall(CWD);
+    if (!ok) throw withCode(ERR.INSTALL_FAILED, "dependency install failed; see terminal output above");
+  }
+
+  // 6. Optionally start preview.
+  let preview = null;
+  if (args.start) {
+    process.stderr.write(`[cloudbase-sites] starting preview…\n`);
+    preview = await runPreviewSubprocess();
+  }
+
+  emitOk(
+    {
+      template,
+      cwd: CWD,
+      installed: !args.skipInstall,
+      preview,
+    },
+    `init complete: cloudbase + ${template} + vite scaffolded in cwd${args.start ? ` (preview: ${preview?.internalUrl || "?"})` : ""}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function checkBlacklist(cwd) {
+  const home = homedir();
+  let real = cwd;
+  try { real = realpathSync(cwd); } catch {}
+  const candidates = [cwd, real];
+  const exact = [
+    "/", "/tmp", "/var", "/private/tmp", "/private/var",
+    "/Users", "/Volumes", "/System", "/usr", "/etc", "/bin", "/sbin",
+    home,
+    join(home, "Desktop"), join(home, "Downloads"), join(home, "Documents"),
+    join(home, "Library"), join(home, "Movies"), join(home, "Music"),
+    join(home, "Pictures"), join(home, "Public"),
+  ];
+  for (const c of candidates) {
+    const cn = c.replace(/\/$/, "") || "/";
+    if (exact.includes(cn)) return `cwd '${cn}' is on the danger blacklist`;
+  }
+  for (const c of candidates) {
+    const cn = c.replace(/\/$/, "");
+    if (cn.startsWith(home + "/.")) return `cwd '${cn}' looks like a hidden config dir under $HOME`;
+  }
+  return null;
+}
+
+function listMeaningfulFiles(dir) {
+  const ignored = new Set([
+    ".git", ".gitignore", ".DS_Store", "Thumbs.db", ".cloudbase-sites",
+    "LICENSE", "LICENSE.md", "LICENSE.txt",
+  ]);
+  const ignoredPatterns = [/^README(\.[a-z]+)?$/i];
+  return readdirSync(dir).filter((name) => {
+    if (ignored.has(name)) return false;
+    if (ignoredPatterns.some((re) => re.test(name))) return false;
+    return true;
+  });
+}
+
+function downloadFile(url, dest, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 5) return reject(withCode(ERR.DOWNLOAD_FAILED, "too many redirects"));
+    https.get(url, (res) => {
+      if ([301, 302, 303, 307, 308].includes(res.statusCode || 0)) {
+        const loc = res.headers.location;
+        if (!loc) return reject(withCode(ERR.DOWNLOAD_FAILED, `redirect ${res.statusCode} without Location`));
+        res.resume();
+        return downloadFile(loc, dest, redirects + 1).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(withCode(ERR.DOWNLOAD_FAILED, `HTTP ${res.statusCode} from ${url}`));
+      }
+      const out = createWriteStream(dest);
+      res.pipe(out);
+      out.on("finish", () => out.close(() => resolve()));
+      out.on("error", (e) => reject(withCode(ERR.DOWNLOAD_FAILED, `write failed: ${e.message}`)));
+    }).on("error", (e) => reject(withCode(ERR.DOWNLOAD_FAILED, `request failed: ${e.message}`)));
+  });
+}
+
+function runInstall(cwd) {
+  const which = (b) => spawnSync(process.platform === "win32" ? "where" : "which", [b], { stdio: "ignore" }).status === 0;
+  let cmd, argv;
+  if (existsSync(join(cwd, "pnpm-lock.yaml")) && which("pnpm")) { cmd = "pnpm"; argv = ["install"]; }
+  else if (which("pnpm")) { cmd = "pnpm"; argv = ["install"]; }
+  else if (which("npm"))  { cmd = "npm";  argv = ["install"]; }
+  else return false;
+  const r = spawnSync(cmd, argv, { cwd, stdio: ["ignore", "inherit", "inherit"], env: process.env });
+  return r.status === 0;
+}
+
+async function runPreviewSubprocess() {
+  // Re-invoke own binary to call the preview verb. We use the binary path
+  // via PATH (since the plugin host adds bin/ to PATH); fall back to absolute.
+  const sitesBin = which("cloudbase-sites") || join(__dirname, "..", "..", "bin", "cloudbase-sites");
+  return new Promise((resolve) => {
+    const c = spawn(sitesBin, ["preview"], { stdio: ["ignore", "pipe", "inherit"] });
+    let buf = "";
+    c.stdout.on("data", (b) => { buf += b.toString(); });
+    c.on("exit", () => {
+      try {
+        const line = buf.split("\n").find((l) => l.trim().startsWith("{"));
+        resolve(line ? JSON.parse(line) : null);
+      } catch { resolve(null); }
+    });
+  });
+}
+
+function which(bin) {
+  const r = spawnSync(process.platform === "win32" ? "where" : "which", [bin], { stdio: ["ignore", "pipe", "ignore"] });
+  if (r.status !== 0) return null;
+  return r.stdout.toString().split("\n")[0].trim() || null;
+}
diff --git a/plugin/cloudbase-sites/lib/verbs/preview.mjs b/plugin/cloudbase-sites/lib/verbs/preview.mjs
new file mode 100644
index 00000000..373cfdf6
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/verbs/preview.mjs
@@ -0,0 +1,314 @@
+/**
+ * `cloudbase-sites preview` — daemonize/inspect/stop/restart Vite dev server.
+ *
+ * One verb, multiple modes via flags:
+ *   cloudbase-sites preview              # ensure running (start if not)
+ *   cloudbase-sites preview --status     # JSON status
+ *   cloudbase-sites preview --status -q  # exit code only
+ *   cloudbase-sites preview --restart    # stop + start
+ *   cloudbase-sites preview --stop       # stop the dev server
+ *   cloudbase-sites preview --port 17180
+ *   cloudbase-sites preview --base /s/sid/
+ *
+ * Always daemonizes (PPID=1, detached). Uses 17173..17272 port range by default.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, openSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import net from "node:net";
+import http from "node:http";
+import {
+  STATE_DIR, LOG_DIR,
+  readPreview, writePreview, clearPreview,
+  isAlive, healthOk, stopPid,
+  ensureDir, ERR,
+} from "../preview-state.mjs";
+import { emitOk, withCode } from "../emit.mjs";
+import { registerWorkspace, unregisterWorkspace } from "../registry.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const DEFAULT_PORT_RANGE_START = Number(process.env.CLOUDBASE_SITES_PORT_START || 17173);
+const DEFAULT_PORT_RANGE_END = Number(process.env.CLOUDBASE_SITES_PORT_END || 17272);
+const HEALTH_TIMEOUT_MS = Number(process.env.CLOUDBASE_SITES_HEALTH_TIMEOUT_MS || 30_000);
+
+export const previewHelp = `cloudbase-sites preview — daemonize/inspect/stop/restart Vite dev server in cwd
+
+Modes (default = ensure running):
+  --status             JSON status; exit code 0=healthy, 5=not running
+  --quiet, -q          (with --status) no output, exit code only
+  --restart            stop + start in one shot
+  --stop               stop the dev server
+  --force, -f          (with --stop) SIGKILL immediately
+
+Options for start/restart:
+  --port <N>           request specific port (default: auto from 17173..17272)
+  --base <P>           path-mount base, e.g. /s/<sid>/ (default: /)
+
+State file: <cwd>/.cloudbase-sites/preview.json
+Logs dir:   <cwd>/.cloudbase-sites/logs/`;
+
+export async function runPreview(args) {
+  if (args.stop) return runStop(args);
+  if (args.restart) {
+    await runStop({ ...args, force: true });
+    return runStart({ ...args, force: false });
+  }
+  if (args.status) return runStatus(args);
+  return runStart(args);
+}
+
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+
+async function runStatus(args) {
+  const state = readPreview();
+  if (!state) {
+    if (args.quiet) process.exit(ERR.NO_PREVIEW_RUNNING);
+    emitOk({ running: false, reason: "no preview recorded" }, "no preview running");
+    process.exit(ERR.NO_PREVIEW_RUNNING);
+  }
+  const alive = state.pid ? isAlive(state.pid) : false;
+  const healthy = alive && state.port ? await healthOk(state.port) : false;
+  const ok = alive && healthy;
+  if (args.quiet) process.exit(ok ? 0 : ERR.NO_PREVIEW_RUNNING);
+  emitOk(
+    {
+      running: ok,
+      alive,
+      healthy,
+      pid: state.pid,
+      port: state.port,
+      framework: state.framework,
+      base: state.base,
+      internalUrl: state.internalUrl,
+      logPath: state.logPath,
+      startedAt: state.startedAt,
+    },
+    ok
+      ? `preview healthy: ${state.internalUrl}`
+      : `preview unhealthy (alive=${alive}, http=${healthy})`,
+  );
+  process.exit(ok ? 0 : ERR.NO_PREVIEW_RUNNING);
+}
+
+// ---------------------------------------------------------------------------
+// stop
+// ---------------------------------------------------------------------------
+
+async function runStop(args) {
+  const state = readPreview();
+  if (!state) {
+    unregisterWorkspace(process.cwd());
+    emitOk({ stopped: false, reason: "no preview recorded" }, "no preview to stop");
+    return;
+  }
+  if (!state.pid || !isAlive(state.pid)) {
+    clearPreview();
+    unregisterWorkspace(process.cwd());
+    emitOk({ stopped: false, reason: "process already gone", pid: state.pid }, "stale state cleared");
+    return;
+  }
+  const graceMs = args.force ? 0 : 3_000;
+  const result = await stopPid(state.pid, { graceMs });
+  if (!result.ok) {
+    throw withCode(ERR.STOP_FAILED, `Failed to stop pid=${state.pid}: ${result.error || "still alive after SIGKILL"}`);
+  }
+  clearPreview();
+  unregisterWorkspace(process.cwd());
+  emitOk(
+    { stopped: true, pid: state.pid, escalated: result.escalated, port: state.port },
+    `preview stopped (pid=${state.pid}${result.escalated ? ", SIGKILL" : ", SIGTERM"})`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// start
+// ---------------------------------------------------------------------------
+
+async function runStart(args) {
+  const CWD = process.cwd();
+  ensureDir(STATE_DIR);
+  ensureDir(LOG_DIR);
+
+  const fingerprint = checkViteProject(CWD);
+  if (!fingerprint.ok) {
+    throw withCode(ERR.NOT_VITE_PROJECT, `Not a Vite project: ${fingerprint.reason}`);
+  }
+
+  // Idempotent reuse.
+  const existing = readPreview();
+  if (existing && existing.pid && isAlive(existing.pid) && (await healthOk(existing.port))) {
+    if (args.force) {
+      try { process.kill(existing.pid, "SIGTERM"); } catch {}
+      clearPreview();
+    } else {
+      registerInRegistry(existing, CWD);
+      emitOk({ ...existing, reused: true }, `preview ready: ${existing.internalUrl}`);
+      return;
+    }
+  }
+  if (existing) {
+    try { if (existing.pid) process.kill(existing.pid, "SIGTERM"); } catch {}
+    clearPreview();
+  }
+
+  const port = await allocPort(args.port ? Number(args.port) : null, DEFAULT_PORT_RANGE_START, DEFAULT_PORT_RANGE_END);
+  const base = args.base || process.env.CLOUDBASE_SITES_BASE || "/";
+
+  const ts = Date.now();
+  const logPath = join(LOG_DIR, `preview-${ts}.log`);
+  const logFd = openSync(logPath, "a");
+
+  const env = {
+    ...process.env,
+    HOST: "0.0.0.0",
+    PORT: String(port),
+    VITE_BASE_URL: base,
+  };
+
+  const argv = [
+    ...(fingerprint._viteEntry ? [fingerprint._viteEntry] : []),
+    "--host", "0.0.0.0",
+    "--port", String(port),
+    "--strictPort",
+    "--base", base,
+  ];
+
+  const child = spawn(fingerprint.viteBin, argv, {
+    cwd: CWD,
+    env,
+    stdio: ["ignore", logFd, logFd],
+    detached: true,
+    windowsHide: true,
+  });
+  child.unref();
+
+  const outcome = await Promise.race([
+    waitForHealth(port, HEALTH_TIMEOUT_MS),
+    waitForExit(child).then((code) => ({ exited: true, code })),
+  ]);
+  if (outcome && outcome.exited) {
+    throw withCode(ERR.HEALTH_CHECK_FAILED, `Dev server exited early with code=${outcome.code}. See log: ${logPath}`);
+  }
+  if (outcome && outcome.timedOut) {
+    try { process.kill(child.pid); } catch {}
+    throw withCode(ERR.HEALTH_CHECK_FAILED, `Dev server failed health check within ${HEALTH_TIMEOUT_MS}ms. See log: ${logPath}`);
+  }
+
+  const internalUrl = `http://127.0.0.1:${port}${base.endsWith("/") ? base : base + "/"}`;
+  const state = {
+    pid: child.pid,
+    port,
+    host: "0.0.0.0",
+    base,
+    framework: fingerprint.framework,
+    command: [fingerprint.viteBin, ...argv].join(" "),
+    internalUrl,
+    logPath,
+    cwd: CWD,
+    startedAt: new Date().toISOString(),
+  };
+  writePreview(state);
+  registerInRegistry(state, CWD);
+  emitOk({ ...state, reused: false }, `preview ready: ${internalUrl}`);
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function checkViteProject(dir) {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath)) return { ok: false, reason: "no package.json in cwd" };
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, "utf8")); }
+  catch (e) { return { ok: false, reason: `invalid package.json: ${e.message}` }; }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  if (!deps.vite) return { ok: false, reason: "vite not in dependencies/devDependencies" };
+  const hasReact = !!deps.react;
+  const hasVue = !!deps.vue;
+  if (!hasReact && !hasVue) return { ok: false, reason: "neither react nor vue is a dependency" };
+
+  const candidatePosixJs = join(dir, "node_modules", "vite", "bin", "vite.js");
+  const candidateBinPosix = join(dir, "node_modules", ".bin", "vite");
+  const candidateWin = join(dir, "node_modules", ".bin", "vite.cmd");
+
+  if (process.platform === "win32") {
+    if (existsSync(candidateWin)) {
+      return { ok: true, framework: hasReact ? "vite-react" : "vite-vue", viteBin: candidateWin, _viteEntry: null };
+    }
+  } else {
+    if (existsSync(candidatePosixJs)) {
+      return { ok: true, framework: hasReact ? "vite-react" : "vite-vue", viteBin: process.execPath, _viteEntry: candidatePosixJs };
+    }
+    if (existsSync(candidateBinPosix)) {
+      return { ok: true, framework: hasReact ? "vite-react" : "vite-vue", viteBin: candidateBinPosix, _viteEntry: null };
+    }
+  }
+  return { ok: false, reason: "local vite binary missing — run `pnpm install` (or `npm install`) first" };
+}
+
+async function allocPort(requested, start, end) {
+  if (requested) {
+    if (await portFree(requested)) return requested;
+    throw withCode(ERR.PORT_POOL_EXHAUSTED, `Requested port ${requested} is occupied.`);
+  }
+  for (let p = start; p <= end; p++) {
+    if (await portFree(p)) return p;
+  }
+  throw withCode(ERR.PORT_POOL_EXHAUSTED, `No free port in [${start}..${end}].`);
+}
+
+function portFree(port) {
+  return new Promise((resolve) => {
+    const tester = net.createServer()
+      .once("error", () => resolve(false))
+      .once("listening", () => tester.close(() => resolve(true)))
+      .listen(port, "0.0.0.0");
+  });
+}
+
+function waitForHealth(port, timeoutMs) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    const probe = () => {
+      const req = http.get({ host: "127.0.0.1", port, path: "/", timeout: 2000 }, (res) => {
+        res.resume();
+        if (res.statusCode && res.statusCode < 500) return resolve({ ready: true });
+        retry();
+      });
+      req.on("error", retry);
+      req.on("timeout", () => { req.destroy(); retry(); });
+    };
+    const retry = () => {
+      if (Date.now() - t0 >= timeoutMs) return resolve({ timedOut: true });
+      setTimeout(probe, 500);
+    };
+    probe();
+  });
+}
+
+function waitForExit(child) {
+  return new Promise((resolve) => { child.once("exit", (code) => resolve(code)); });
+}
+
+function registerInRegistry(state, cwd) {
+  let sessionId = null;
+  const appJsonPath = join(STATE_DIR, "app.json");
+  if (existsSync(appJsonPath)) {
+    try {
+      const app = JSON.parse(readFileSync(appJsonPath, "utf8"));
+      sessionId = app.siteName || app.serviceName || null;
+    } catch { /* ignore */ }
+  }
+  if (!sessionId) sessionId = cwd.split("/").filter(Boolean).pop() || "vibe";
+  try {
+    registerWorkspace({ cwd, sessionId, port: state.port, previewPid: state.pid });
+  } catch (e) {
+    process.stderr.write(`[cloudbase-sites] registry write failed: ${e.message}\n`);
+  }
+}
diff --git a/plugin/cloudbase-sites/lib/verbs/rollback.mjs b/plugin/cloudbase-sites/lib/verbs/rollback.mjs
new file mode 100644
index 00000000..b634fd6a
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/verbs/rollback.mjs
@@ -0,0 +1,95 @@
+/**
+ * `cloudbase-sites rollback` — revert working tree to a saved version.
+ *
+ * Default: rollback to currently deployed version (current production).
+ * Or specify --to-version <n>.
+ *
+ * Steps:
+ *   1. Resolve target version's commitSha from app.json.versions.
+ *   2. git stash --include-untracked (preserve any uncommitted edits).
+ *   3. git reset --hard <commitSha>
+ *   4. mark all versions newer than target as "rolled-back"
+ *   5. trigger a `preview --restart` so the dev server picks up the reset.
+ *
+ * Note: rollback DOES NOT auto-deploy. After rollback, user can:
+ *   - keep iterating (next save will create version n+1 ahead of the rolled
+ *     back tip — git history will show the rolled-back commits as orphaned)
+ *   - explicitly deploy the rolled-back version via `cloudbase-sites deploy`
+ */
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { emitOk, withCode } from "../emit.mjs";
+import { ERR } from "../preview-state.mjs";
+import { findVersion, markVersionRolledBack, readApp } from "../app-store.mjs";
+import { gitResetHard, gitStashIncludeUntracked, isGitRepo } from "../git-utils.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SITES_BIN = join(__dirname, "..", "..", "bin", "cloudbase-sites");
+
+export const rollbackHelp = `cloudbase-sites rollback — revert cwd to a saved version
+
+Options:
+  --to-version <n>     target version (default: current production deploy)
+  --no-restart         skip auto-restart of dev server after rollback
+
+Behavior:
+  - git stash --include-untracked any uncommitted edits (recoverable via \`git stash list\`)
+  - git reset --hard to the target version's commit
+  - marks all versions newer than target as "rolled-back" in app.json
+  - restarts dev server unless --no-restart`;
+
+export async function runRollback(args) {
+  const CWD = process.cwd();
+  if (!isGitRepo(CWD)) throw withCode(ERR.ROLLBACK_FAILED, "not a git repository");
+
+  const app = readApp();
+  if (!app || !app.versions || app.versions.length === 0) {
+    throw withCode(ERR.VERSION_NOT_FOUND, "no saved versions yet — nothing to rollback to");
+  }
+
+  // Default target: current production (last successful deploy).
+  let targetN;
+  if (args.toVersion) targetN = Number(args.toVersion);
+  else if (app.currentDeploy) targetN = app.currentDeploy;
+  else throw withCode(ERR.VERSION_NOT_FOUND, "no current deploy to rollback to — pass --to-version <n>");
+
+  const target = findVersion(targetN);
+  if (!target) throw withCode(ERR.VERSION_NOT_FOUND, `version ${targetN} not found`);
+
+  // 1. Stash uncommitted edits.
+  gitStashIncludeUntracked(CWD, `cloudbase-sites pre-rollback to v${targetN}`);
+
+  // 2. Reset.
+  if (!gitResetHard(CWD, target.commitSha)) {
+    throw withCode(ERR.ROLLBACK_FAILED, `git reset --hard ${target.commitSha} failed`);
+  }
+
+  // 3. Mark newer versions as rolled-back.
+  for (const v of app.versions) {
+    if (v.n > targetN) markVersionRolledBack(v.n);
+  }
+
+  // 4. Restart preview unless --no-restart.
+  let preview = null;
+  if (!args.noRestart) {
+    spawn(SITES_BIN, ["preview", "--restart"], {
+      cwd: CWD,
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    }).unref();
+    preview = "restart triggered (async)";
+  }
+
+  emitOk(
+    {
+      rolledBackTo: { n: target.n, commitSha: target.commitSha, label: target.label },
+      droppedVersions: app.versions.filter((v) => v.n > targetN).map((v) => v.n),
+      stashedChanges: "if any uncommitted edits, recover via `git stash list` + `git stash pop`",
+      preview,
+    },
+    `rolled back to version ${target.n} (${target.commitSha})`,
+  );
+}
diff --git a/plugin/cloudbase-sites/lib/verbs/save.mjs b/plugin/cloudbase-sites/lib/verbs/save.mjs
new file mode 100644
index 00000000..bab432bd
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/verbs/save.mjs
@@ -0,0 +1,79 @@
+/**
+ * `cloudbase-sites save` — create a new saved version (Codex Sites-style).
+ *
+ * Steps:
+ *   1. git add -A && git commit --allow-empty -m "version <n>: <label>"
+ *   2. git tag version/<n>
+ *   3. append { n, commitSha, label, savedAt, status:"saved" } to app.json.versions
+ *   4. emit JSON with the new version entry
+ *
+ * No build, no deploy. A version is just a labeled checkpoint that can later
+ * be deployed via `cloudbase-sites deploy --version <n>` (default: latest).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { emitOk, withCode } from "../emit.mjs";
+import { ERR } from "../preview-state.mjs";
+import { appendVersion, getOrCreateSiteName, readApp } from "../app-store.mjs";
+import { ensureGitignoreEntry, gitAddCommitTag, gitHead, isGitRepo } from "../git-utils.mjs";
+
+export const saveHelp = `cloudbase-sites save — create a new saved version (a labeled git checkpoint)
+
+Options:
+  -m, --message <text>     human-readable label for this version
+                            (defaults to a placeholder if omitted)
+
+Behavior:
+  - Creates a git commit (--allow-empty) and a tag version/<n>.
+  - Appends to <cwd>/.cloudbase-sites/app.json.versions[].
+  - Does NOT build or deploy. Use \`cloudbase-sites deploy\` for that.
+
+Output: JSON with the new version entry.`;
+
+export async function runSave(args) {
+  const CWD = process.cwd();
+
+  // Verify Vite project (cheap fingerprint).
+  const pkg = readPkg(CWD);
+  if (!pkg) throw withCode(ERR.NOT_VITE_PROJECT, "no package.json in cwd");
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  if (!deps.vite) throw withCode(ERR.NOT_VITE_PROJECT, "vite not in dependencies/devDependencies");
+  if (!deps.react && !deps.vue) throw withCode(ERR.NOT_VITE_PROJECT, "neither react nor vue is a dependency");
+
+  // Ensure siteName + git repo.
+  const siteName = getOrCreateSiteName();
+  if (!isGitRepo(CWD)) {
+    throw withCode(ERR.GENERIC, "not a git repository — run `git init` first");
+  }
+  ensureGitignoreEntry(CWD, ".cloudbase-sites/");
+
+  // Compute next version number.
+  const app = readApp();
+  const nextN = (app?.versions?.[app.versions.length - 1]?.n || 0) + 1;
+  const label = args.message || `auto-saved at ${new Date().toISOString()}`;
+  const tag = `version/${nextN}`;
+
+  // Commit + tag.
+  const ok = gitAddCommitTag(CWD, tag, `version ${nextN}: ${label}`);
+  if (!ok) throw withCode(ERR.GENERIC, `git tag ${tag} failed (check git status)`);
+
+  const commitSha = gitHead(CWD);
+  const entry = appendVersion({ commitSha, label });
+
+  emitOk(
+    {
+      siteName,
+      version: entry,
+      gitTag: tag,
+      previouslyDeployed: !!app?.currentDeploy,
+    },
+    `saved version ${nextN} (${commitSha}): ${label}`,
+  );
+}
+
+function readPkg(cwd) {
+  const p = join(cwd, "package.json");
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
diff --git a/plugin/cloudbase-sites/lib/verbs/supervisor.mjs b/plugin/cloudbase-sites/lib/verbs/supervisor.mjs
new file mode 100644
index 00000000..495ea021
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/verbs/supervisor.mjs
@@ -0,0 +1,242 @@
+/**
+ * `cloudbase-sites supervisor` — global watchdog daemon.
+ *
+ * Two modes:
+ *   1. Subcommands: start/stop/status/list/heal/reload (called by user).
+ *   2. --daemon-loop: internal entry point for the spawned detached child.
+ *
+ * Walks ~/.cloudbase-sites/registry.json every TICK_MS, probes each cwd's
+ * preview.json, restarts dead vites via the binary's own `preview` verb.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import http from "node:http";
+import {
+  ensureGlobalDir,
+  listWorkspaces,
+  patchWorkspace,
+  recordFailure,
+  recordSuccess,
+  STATUS,
+  RESTART_BUDGET,
+} from "../registry.mjs";
+import {
+  clearSupervisorState,
+  ensureSupervisorRunning,
+  isSupervisorAlive,
+  readSupervisorState,
+  stopSupervisor,
+  writeSupervisorState,
+} from "../supervisor-ctl.mjs";
+import { emitOk, emitErr } from "../emit.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SITES_BIN = join(__dirname, "..", "..", "bin", "cloudbase-sites");
+
+const TICK_MS = Number(process.env.CLOUDBASE_SITES_SUPERVISOR_TICK_MS || 15_000);
+const HEALTH_HTTP_TIMEOUT_MS = 1500;
+
+export const supervisorHelp = `cloudbase-sites supervisor — global watchdog for vibe-coding cwds
+
+Subcommands:
+  start                    spawn daemon (no-op if already running)
+  stop                     SIGTERM daemon (with SIGKILL fallback)
+  status                   JSON: alive/pid/uptime/workspaceCount
+  list                     JSON: all registered workspaces with health
+  heal <cwd>               clear DEGRADED state, trigger one restart
+  reload                   send SIGHUP to daemon (re-read registry)
+
+Internal:
+  --daemon-loop            entered by the spawned child; do not run manually
+
+State files:
+  ~/.cloudbase-sites/supervisor.json   daemon PID + startedAt + lastTickAt
+  ~/.cloudbase-sites/registry.json     all registered cwds
+  ~/.cloudbase-sites/supervisor.log    daemon stdout/stderr
+
+Tick interval: ${TICK_MS}ms (env CLOUDBASE_SITES_SUPERVISOR_TICK_MS to override)`;
+
+export async function runSupervisor(subcmd, rest) {
+  switch (subcmd) {
+    case "--daemon-loop": return runDaemonLoop();
+    case "start":         return cmdStart();
+    case "stop":          return cmdStop();
+    case "status":        return cmdStatus();
+    case "list":          return cmdList();
+    case "heal":          return cmdHeal(rest);
+    case "reload":        return cmdReload();
+    default:
+      emitErr(`Unknown supervisor subcommand: ${subcmd}`, 1);
+      process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Daemon loop
+// ---------------------------------------------------------------------------
+
+async function runDaemonLoop() {
+  ensureGlobalDir();
+  writeSupervisorState({
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    tickMs: TICK_MS,
+  });
+
+  let running = true;
+  const shutdown = () => {
+    running = false;
+    try { clearSupervisorState(); } catch {}
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+  process.on("SIGHUP", () => { /* registry is re-read every tick anyway */ });
+
+  log("daemon started");
+
+  while (running) {
+    await tickOnce().catch((e) => log(`tick error: ${e.message || e}`));
+    const s = readSupervisorState();
+    if (s) writeSupervisorState({ ...s, lastTickAt: new Date().toISOString() });
+    await sleep(TICK_MS);
+  }
+}
+
+async function tickOnce() {
+  const entries = listWorkspaces();
+  if (entries.length === 0) return;
+
+  for (const entry of entries) {
+    if (entry.status === STATUS.DEGRADED) continue;
+
+    const result = await checkHealth(entry);
+    if (result.healthy) {
+      recordSuccess(entry.cwd, { previewPid: result.observedPid });
+      continue;
+    }
+    log(`unhealthy cwd=${entry.cwd} reason=${result.reason}`);
+    const { degraded } = recordFailure(entry.cwd, result.reason);
+    if (degraded) {
+      log(`cwd=${entry.cwd} now DEGRADED after ${RESTART_BUDGET} consecutive failures`);
+      continue;
+    }
+    triggerRestart(entry.cwd);
+  }
+}
+
+async function checkHealth(entry) {
+  const previewJson = join(entry.cwd, ".cloudbase-sites", "preview.json");
+  if (!existsSync(previewJson)) return { healthy: false, reason: "preview.json missing" };
+  let pj;
+  try { pj = JSON.parse(readFileSync(previewJson, "utf8")); }
+  catch { return { healthy: false, reason: "preview.json unreadable" }; }
+  if (!pj.pid) return { healthy: false, reason: "no pid in preview.json" };
+  try { process.kill(pj.pid, 0); }
+  catch { return { healthy: false, reason: `pid ${pj.pid} dead` }; }
+  if (!pj.port) return { healthy: false, reason: "no port in preview.json" };
+  const httpOk = await httpHealthy("127.0.0.1", pj.port);
+  if (!httpOk) return { healthy: false, reason: `http probe ${pj.port} failed` };
+  return { healthy: true, observedPid: pj.pid };
+}
+
+function httpHealthy(host, port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host, port, path: "/", timeout: HEALTH_HTTP_TIMEOUT_MS }, (res) => {
+      res.resume();
+      resolve(!!(res.statusCode && res.statusCode < 500));
+    });
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => { req.destroy(); resolve(false); });
+  });
+}
+
+function triggerRestart(cwd) {
+  try {
+    const child = spawn(SITES_BIN, ["preview", "--restart"], {
+      cwd,
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+    log(`spawned restart for cwd=${cwd}`);
+  } catch (e) {
+    log(`failed to spawn restart for cwd=${cwd}: ${e.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// User-facing subcommands
+// ---------------------------------------------------------------------------
+
+async function cmdStart() {
+  const r = ensureSupervisorRunning({ silent: false });
+  emitOk(r);
+}
+
+async function cmdStop() {
+  const r = await stopSupervisor();
+  if (r.stopped || r.reason) emitOk(r);
+  else emitErr(r.reason || "stop failed", 1);
+}
+
+async function cmdStatus() {
+  const s = readSupervisorState();
+  const alive = isSupervisorAlive();
+  emitOk({
+    alive,
+    pid: s?.pid ?? null,
+    startedAt: s?.startedAt ?? null,
+    lastTickAt: s?.lastTickAt ?? null,
+    tickMs: s?.tickMs ?? null,
+    workspaceCount: listWorkspaces().length,
+  });
+}
+
+async function cmdList() {
+  const entries = listWorkspaces();
+  emitOk({ count: entries.length, entries });
+}
+
+async function cmdHeal(rest) {
+  const cwd = rest[0];
+  if (!cwd) {
+    emitErr("usage: cloudbase-sites supervisor heal <cwd>", 1);
+    process.exit(1);
+  }
+  const r = patchWorkspace(cwd, {
+    status: STATUS.RUNNING,
+    consecutiveFailures: 0,
+    lastFailureReason: null,
+  });
+  if (!r) {
+    emitErr(`cwd not registered: ${cwd}`, 1);
+    process.exit(1);
+  }
+  triggerRestart(cwd);
+  emitOk({ healed: r });
+}
+
+async function cmdReload() {
+  const s = readSupervisorState();
+  if (!s?.pid) { emitErr("supervisor not running", 1); process.exit(1); }
+  try { process.kill(s.pid, "SIGHUP"); } catch (e) {
+    emitErr(`kill -HUP ${s.pid} failed: ${e.message}`, 1);
+    process.exit(1);
+  }
+  emitOk({ signaled: s.pid });
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function log(msg) {
+  process.stderr.write(`[supervisor ${new Date().toISOString()}] ${msg}\n`);
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
diff --git a/plugin/cloudbase-sites/lib/verbs/versions.mjs b/plugin/cloudbase-sites/lib/verbs/versions.mjs
new file mode 100644
index 00000000..355fe4e3
--- /dev/null
+++ b/plugin/cloudbase-sites/lib/verbs/versions.mjs
@@ -0,0 +1,34 @@
+/**
+ * `cloudbase-sites versions` — list saved versions and deployment status.
+ */
+
+import { readApp } from "../app-store.mjs";
+import { emitOk } from "../emit.mjs";
+
+export const versionsHelp = `cloudbase-sites versions — list saved versions for the cwd
+
+Output:
+  {
+    siteName,
+    currentVersion,        // highest saved n
+    currentDeploy,         // version n of last successful deploy
+    versions: [{ n, commitSha, label, savedAt, status }],
+    lastDeploy: { version, accessUrl, finalUrl, deployedAt }   // or null
+  }`;
+
+export async function runVersions(_args) {
+  const app = readApp();
+  if (!app) {
+    emitOk({ siteName: null, versions: [], deployments: [] }, "no save history yet — run `cloudbase-sites save`");
+    return;
+  }
+  const lastDeploy = app.deployments?.[app.deployments.length - 1] || null;
+  emitOk({
+    siteName: app.siteName,
+    currentVersion: app.currentVersion,
+    currentDeploy: app.currentDeploy,
+    versions: app.versions || [],
+    deployments: app.deployments || [],
+    lastDeploy,
+  });
+}
diff --git a/plugin/cloudbase-sites/skills/cloudbase-sites-runtime/SKILL.md b/plugin/cloudbase-sites/skills/cloudbase-sites-runtime/SKILL.md
new file mode 100644
index 00000000..59293240
--- /dev/null
+++ b/plugin/cloudbase-sites/skills/cloudbase-sites-runtime/SKILL.md
@@ -0,0 +1,295 @@
+---
+name: cloudbase-sites-runtime
+description: |
+  Use when the user wants to develop, run, preview, save, deploy, or roll back
+  a CloudBase Web app in this conversation as a Lovable/Codex-Sites-like vibe-
+  coding session — i.e. any request that maps to "spin up a React+Vite project,
+  see it live in the browser, iterate, save versions, deploy". Activate ONLY
+  for browser-rendered Web projects based on the CloudBase official React
+  (or Vue) + Vite template. Do NOT activate for: WeChat/Alipay mini-program,
+  React Native / Flutter / Electron, pure cloud functions / CloudRun backends,
+  or Next.js / Nuxt / Astro / Remix / SvelteKit (those frameworks are
+  explicitly out of scope).
+---
+
+# CloudBase Sites Runtime
+
+This skill orchestrates a **single working directory = single project** flow
+for CloudBase Web apps. The cwd itself is the workspace; we do not manage
+cross-cwd state or session IDs at the skill level.
+
+This runtime is shared by the Codex, Claude Code, and CodeBuddy plugin
+surfaces. The CLI and CloudBase MCP workflows are the source of truth. Some
+hosts also run bundled lifecycle hooks that start previews or inject compact
+rules at session start; if hooks are unavailable, disabled, or not yet trusted,
+use the explicit CLI commands in this skill.
+
+## Activation contract
+
+### Use this skill when
+
+- The user says "build me a website / app", "I want to make a landing page",
+  "create a React app and let me preview", "deploy this to CloudBase",
+  "save this version", "roll back to v1", or similar.
+- The current cwd looks like a CloudBase + Vite project (has `package.json`
+  with `vite` + `react` or `vue`).
+- The user is running this conversation inside Codex, Claude Code, CodeBuddy,
+  or a compatible host with the `cloudbase-sites` plugin enabled —
+  `cloudbase-mcp` is registered and the `cloudbase-sites` binary is on PATH.
+
+### Do NOT use this skill when
+
+- It's a mini-program project — route to mini-program guidance instead.
+- It's a native app project — route to http-api guidance.
+- It's a backend-only project — route to cloud-functions / cloudrun guidance.
+- The framework is Next/Nuxt/Astro/Remix — politely tell the user this skill
+  only covers Vite-based React/Vue apps and stop. Do NOT try to adapt the
+  scripts to those frameworks.
+
+## What this skill orchestrates — three layers
+
+### 1. CloudBase MCP tools (provided by `cloudbase-mcp`, registered via plugin's `.mcp.json`)
+
+These are the only tools that produce CloudBase side effects. Highlights:
+
+- `downloadTemplate({ template: "react" | "vue", ide })` — pull official template
+- `envQuery({ action: "info" })` + `auth({ action: "set_env", envId })` — bind env
+- `manageApps({ action: "deployApp", ... })` — deploy to CloudApp (independent subdomain)
+- `envDomainManagement({ action: "create", domains })` — whitelist dev origin for CORS
+- `searchKnowledgeBase({ mode: "skill", skillName: "<name>" })` — fetch CloudBase domain skills (see below)
+
+For all CloudBase operations beyond the dev-server lifecycle (auth, db,
+storage, ai), fetch the corresponding CloudBase domain skill via
+`searchKnowledgeBase(mode="skill", skillName=...)`. Common ones:
+
+- `ui-design`               UI design spec (mandatory before new UI work)
+- `web-development`         Web project conventions
+- `auth-tool`               provider config (management-side)
+- `auth-web`                Web SDK auth client code
+- `no-sql-web-sdk`          document database Web SDK
+- `cloud-storage-web`       cloud storage Web SDK
+- `relational-database-web` MySQL Web SDK
+- `cloudbase-platform`      platform overview / console links
+
+These are **NOT Claude Code native skills** and are NOT bundled with this
+plugin. They live inside cloudbase-mcp and are fetched on demand. When this
+file (or the injected RULES_BLOCK) says "调 ui-design skill" or "follow the
+auth-tool skill", that means: call `searchKnowledgeBase(mode="skill",
+skillName="<that-name>")` and apply the returned content.
+
+### 2. The `cloudbase-sites` CLI (provided by this plugin's `bin/` directory)
+
+Single binary, multiple subcommands. Use these — and ONLY these — for the
+dev-server / version / deploy lifecycle:
+
+- `cloudbase-sites init` — scaffold from empty cwd (called by SessionStart hook)
+- `cloudbase-sites preview` — daemonize Vite (called by SessionStart hook)
+- `cloudbase-sites preview --status [--quiet]` — JSON status / exit code
+- `cloudbase-sites preview --restart` / `--stop [--force]`
+- `cloudbase-sites save -m "<label>"` — create a saved version
+- `cloudbase-sites versions` — list saved versions + deploy status
+- `cloudbase-sites deploy [--version <n>]` — deploy a saved version (Phase 1: emit nextAction)
+- `cloudbase-sites deploy --post --version <n> --access-url <url> [--build-id <BuildId>] [--version-name <VersionName>]` — record deploy
+- `cloudbase-sites rollback [--to-version <n>]` — revert to a saved version
+- `cloudbase-sites supervisor status|list|heal|reload|start|stop`
+
+Never invent `npm run dev` / `vite` / `vite build` invocations. The CLI
+handles host=0.0.0.0 forcing, port allocation (17173..17272), daemonization,
+base path injection, version metadata, and deploy history.
+
+### 3. Standard tools (Bash, git, Edit, Write)
+
+Use for editing files. The plugin's PostToolUse hook handles automatic
+restart on config-file edits — you don't need to manage that.
+
+## Lifecycle hooks and fallback
+
+**Do NOT invoke `cloudbase-sites init` or `cloudbase-sites preview`
+proactively in your first message when the host reports that CloudBase Sites
+hooks are active.** The plugin's SessionStart hook does this for you. By the
+time you read the user's first prompt:
+
+- If the cwd was an existing Vite project: dev server is up (or installing).
+- If the cwd was empty: `init --start` is running in background; preview
+  will be ready in ~10s.
+- If the cwd is a non-Vite / blacklisted project: hook stayed silent.
+
+Codex supports bundled plugin hooks, but non-managed command hooks may require
+the user to review and trust them before they run. If Codex hooks have not run,
+fall back to `cloudbase-sites preview --status`, `cloudbase-sites init`, and
+the other explicit commands below instead of assuming automatic startup.
+
+You only invoke a CLI verb when:
+
+- User explicitly says "stop the dev server" → `cloudbase-sites preview --stop`
+- User asks for the URL or "is it running" → `cloudbase-sites preview --status`
+- User wants to save a version → `cloudbase-sites save -m "<label>"`
+- User wants to deploy → `cloudbase-sites deploy` (then bridge to `manageApps`)
+- User wants to roll back → `cloudbase-sites rollback`
+
+## When the user just walked into the conversation
+
+1. **Check preview state first** — read `<cwd>/.cloudbase-sites/preview.json`
+   or run `cloudbase-sites preview --status`. It's overwhelmingly likely the
+   preview is already up — courtesy of the SessionStart hook.
+
+2. **Tell the user the URL** — surface `internalUrl` from the JSON. If the
+   file is missing, the hook is still installing/starting; tell the user to
+   wait ~10s and inspect `.cloudbase-sites/logs/hook-session-start.log`.
+
+3. **DO NOT** re-init / re-start. Calling `init` again will fail with code 10
+   (cwd no longer empty). Calling `preview` is idempotent and safe but
+   wastes a turn.
+
+4. **NEVER guess the port.** It is NOT 5173/5174/5175 — the plugin uses
+   17173..17272. Always read the recorded port from `preview.json`.
+
+## Two-stage save → deploy workflow
+
+Inspired by Codex Sites' `saved version` model:
+
+- **Save:** label a git checkpoint. `cloudbase-sites save -m "<label>"` runs
+  `git add -A && git commit && git tag version/<n>` and appends to
+  `<cwd>/.cloudbase-sites/app.json.versions[]`. No build, no deploy.
+- **Deploy:** publish a saved version to a CloudApp.
+  `cloudbase-sites deploy [--version <n>]` (default: latest saved) builds
+  `dist/` locally then emits `nextAction` telling you to call
+  `manageApps({ action: "deployApp", serviceName: <stable from app.json>,
+  filePath: cwd, buildPath: "dist", framework: "static",
+  installCmd: "", buildCmd: "" })`. The `framework=static` shape skips
+  remote install/build because we built locally.
+- **Record:** after `manageApps` succeeds and gives you the access URL,
+  call `cloudbase-sites deploy --post --version <n> --access-url <url>
+  --build-id <BuildId> [--version-name <VersionName>]`. This appends to
+  `app.json.deployments[]`, records CloudBase build metadata, tags git
+  `deploy/<n>-<ts>`, and returns `finalUrl` with a cache-busting query.
+  If the `manageApps` result includes `BuildId`, you MUST pass it to
+  `--build-id`; otherwise future build status and log queries cannot be
+  traced directly from the saved deployment.
+- **Rollback:** `cloudbase-sites rollback [--to-version <n>]` (default:
+  current production deploy). Stashes uncommitted edits, `git reset --hard`
+  to the version's commit, marks newer versions as `rolled-back`, and
+  restarts the dev server.
+
+**Why CloudApp (`manageApps`) not static hosting?** Each CloudApp has its
+own subdomain (`*.webapps.tcloudbase.com`); two vibe sessions on the same
+env never collide. The stable `siteName` in `app.json` ensures re-deploys
+preserve the URL.
+
+**Pre-flight:** if `manageApps` fails with "no envId" / env-related error,
+call `envQuery({ action: "info" })`. If multiple envs exist, ask the user
+to pick. After binding, retry the deploy.
+
+## Proactive prompts (do not act unsolicited)
+
+When you finish a user-requested feature (especially "make me a X app",
+"build me a Y", "add Z feature"), end your reply by asking:
+
+1. **Save?** "要保存这一版吗?(下次能再调出来)" → if yes, run
+   `cloudbase-sites save -m "<auto-generated label>"`.
+2. **Deploy?** "现在要部署看一下吗?(独立 URL,可分享)" → if yes, run the
+   two-stage deploy described above.
+3. **Verify in browser?** "要不要我用内置浏览器打开 <URL> 帮你点一遍验证一下?"
+   — only run browser-driving tools after explicit yes. Do NOT spawn
+   playwright / agent-browser by default.
+4. **After successful deploy** ask: "要我用 ui-design 能力进一步优化样式和体验吗?"
+   If yes, fetch `searchKnowledgeBase(mode="skill", skillName="ui-design")`
+   and iterate on the design.
+
+Skip any of these when:
+- The work was a bug fix or trivial refactor.
+- The user already chose this option earlier in the session.
+- The user explicitly said "don't deploy" / "no tests" / "no design changes".
+
+## Hard rules (also injected by SessionStart hook)
+
+1. **Never guess the preview URL.** Always read `preview.json` or run
+   `cloudbase-sites preview --status`. Default port range is 17173..17272.
+
+2. **"Make me a X app" = X IS the homepage.** When the user uses whole-house
+   language, REPLACE the content of `src/pages/HomePage.tsx` (or `App.tsx`
+   if no HomePage exists) with the new feature. Do NOT create a new
+   `<TodoApp />` component and leave the original template welcome at `/`.
+   Only add a new route when the user explicitly says "add a X page".
+
+3. **UI work for NEW features requires a design specification first.** Before
+   writing any `.tsx`/`.css`/`.html`, fetch
+   `searchKnowledgeBase(mode="skill", skillName="ui-design")`, output the
+   4-part spec (Aesthetic / Color / Typography / Layout), THEN write code.
+   The CloudBase template's CLAUDE.md "Existing Implementation First"
+   exemption applies only to bug fixes; new apps still need ui-design.
+
+4. **Never spawn `npm run dev` / `vite` / `vite build` yourself.** Lifecycle
+   is owned by hooks + the `cloudbase-sites` CLI.
+
+5. **BaaS-first data persistence.** Schema via
+   `writeNoSqlDatabaseStructure(action="createCollection")`; reads/writes
+   via `@cloudbase/js-sdk` from React/Vue code. Reach for cloud functions
+   only when (a) the logic cannot be expressed as security rules AND
+   (b) it needs server-side secrets or a third-party API AND (c) it's a
+   scheduled / background job. A Todo / Notes / Chat / Kanban app does NOT
+   need cloud functions.
+
+6. **Do not run browser tests by default.** Verify reasonably (preview
+   healthy, no compile error in `cloudbase-sites preview --status`). If
+   the user wants browser verification, ask first.
+
+7. **Two-stage save → deploy.** Don't deploy unsolicited. Don't bypass
+   `cloudbase-sites deploy` with your own `pnpm build` + `manageApps` call —
+   you'd lose version metadata, snapshot, deploy history, and the stable
+   siteName.
+
+## Hard rules — always parse CLI stdout as JSON
+
+The first stdout line of every `cloudbase-sites <verb>` invocation is a
+single JSON object. The stderr `[cloudbase-sites] ...` line is for humans —
+do not parse it. On error the JSON is `{ ok: false, code: <int>, message,
+hint?, logPath? }`. When a script reports failure, surface `logPath` to the
+user instead of guessing the cause.
+
+## Error codes from the CLI
+
+| code | meaning | recovery |
+|---|---|---|
+| 1 | generic failure | check the message |
+| 2 | not a Vite project (or `vite` binary missing) | `pnpm install` then retry |
+| 3 | port pool exhausted in 17173..17272 | `cloudbase-sites preview --stop` for stale ones, or pass `--port` |
+| 4 | dev server failed health check in 30s | read `logPath`; usually a build error in user code |
+| 5 | no preview is running (status / stop) | start one with `cloudbase-sites preview` |
+| 6 | stop failed (process refused SIGKILL) | inspect the PID manually with `ps`; very rare |
+| 7 | build failed (`cloudbase-sites deploy`) | inspect build output; fix code, retry |
+| 8 | `dist/` missing or empty after build | confirm `scripts.build` runs `vite build`; rerun |
+| 9 | cwd in danger blacklist (`init`) | cd to a real project directory first |
+| 10 | cwd not empty (`init`) | move conflicting files; only `.git`/`.gitignore`/README/LICENSE/.cloudbase-sites are tolerated |
+| 11 | template download failed | check internet; URL is `static.cloudbase.net/cloudbase-examples/...` |
+| 12 | template extract failed | install `unzip` |
+| 13 | dependency install failed | check terminal output |
+| 14 | version not found | run `cloudbase-sites versions` to list |
+| 15 | rollback failed | check git state |
+
+## State files
+
+| Path | Purpose |
+|---|---|
+| `<cwd>/.cloudbase-sites/preview.json` | dev server PID/port/URL/framework |
+| `<cwd>/.cloudbase-sites/app.json` | siteName + versions[] + deployments[] + currentVersion + currentDeploy |
+| `<cwd>/.cloudbase-sites/logs/preview-<ts>.log` | Vite stdout/stderr |
+| `<cwd>/.cloudbase-sites/logs/hook-session-start.log` | SessionStart hook trace |
+| `<cwd>/.cloudbase-sites/logs/hook-restart.log` | PostToolUse restart trail |
+| `~/.cloudbase-sites/registry.json` | global supervisor's view of all cwds |
+| `~/.cloudbase-sites/supervisor.json` | global supervisor PID + uptime |
+| `~/.cloudbase-sites/supervisor.log` | supervisor stdout/stderr |
+
+## What this skill is NOT
+
+- It is **not** a session manager. There is no sessionId at the skill level.
+  There is only cwd. (The supervisor's `registry.json` does track cwds
+  globally, but for self-healing — not as a user-facing concept.)
+- It is **not** a reverse proxy. If the host is on a public-facing server
+  and the user needs `<host>:8080/s/<sid>/` style routing, that's a separate
+  optional component (`cloudbase-sites-proxy`, future work) — out of scope here.
+- It is **not** a CloudBase auth/database guide. For those, fetch the
+  corresponding CloudBase domain skill via
+  `searchKnowledgeBase(mode="skill", skillName=...)`.
+- It is **not** a UI design guide. For visual decisions, fetch
+  `searchKnowledgeBase(mode="skill", skillName="ui-design")`.
diff --git a/plugin/cloudbase-vibe-coding/bin/cloudbase-vibe-deploy b/plugin/cloudbase-vibe-coding/bin/cloudbase-vibe-deploy
deleted file mode 100755
index 4dec5028..00000000
--- a/plugin/cloudbase-vibe-coding/bin/cloudbase-vibe-deploy
+++ /dev/null
@@ -1,318 +0,0 @@
-#!/usr/bin/env node
-/**
- * cloudbase-vibe-deploy
- *
- * Build the Vite project in cwd and bridge to cloudbase-mcp's `manageApps`
- * tool with framework=static (skips remote npm install/build, only runs
- * tcb hosting deploy). Each CloudApp gets an independent subdomain.
- *
- * Why manageApps not manageHosting:
- *   - manageApps gives each `serviceName` an independent `*.webapps.tcloudbase.com`
- *     subdomain — no path collisions between vibe sessions.
- *   - The local build already produced dist/, so we pass installCmd="" and
- *     buildCmd="" to skip remote build steps; only tcb hosting deploy runs.
- *   - Both manageApps and manageHosting support custom domain binding.
- *
- * Stable serviceName per cwd:
- *   First deploy generates a name `<dirname>-<6hex>` and writes it to
- *   `<cwd>/.cloudbase-agent/app.json`. Subsequent deploys reuse the same
- *   serviceName so the URL stays stable. Renaming cwd does not change it.
- *
- * Two-phase contract (model is expected to bridge them):
- *   Phase 1 (build):
- *     `cloudbase-vibe-deploy`
- *       → git tag snap/pre-deploy-<ts>
- *       → pnpm/npm run build
- *       → validate dist/
- *       → emit JSON with `nextAction.tool=manageApps` and exact args
- *         (framework=static, installCmd="", buildCmd="", filePath=CWD, buildPath="dist")
- *
- *   Phase 2 (post-deploy, after model calls manageApps):
- *     `cloudbase-vibe-deploy --post-deploy --access-url <url> [--build-id <id>]`
- *       → append to app.json deployHistory
- *       → git tag deploy/<ts>
- *       → return finalUrl with cache-bust query
- *
- * Usage:
- *   cloudbase-vibe-deploy                       # build + emit nextAction
- *   cloudbase-vibe-deploy --skip-build          # already built, just emit nextAction
- *   cloudbase-vibe-deploy --post-deploy \
- *     --access-url https://xxx.webapps.tcloudbase.com/ \
- *     --build-id <buildId>                       # record the deploy result
- *   cloudbase-vibe-deploy --service-name        # print stable serviceName for this cwd, exit
- *
- * Exit codes (canonical, also re-exported from lib/preview-state.mjs ERR):
- *   0 success
- *   1 generic
- *   2 not a Vite project
- *   7 build failed
- *   8 dist missing or empty after build
- */
-
-import { spawnSync } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
-import { fileURLToPath } from "node:url";
-import { basename, dirname, join } from "node:path";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const lib = await import(join(__dirname, "..", "lib", "preview-state.mjs"));
-const { ensureDir, STATE_DIR, emitOk, emitErr, ERR } = lib;
-
-const CWD = process.cwd();
-const APP_JSON = join(STATE_DIR, "app.json");
-
-const args = parseArgs(process.argv.slice(2));
-
-main().catch((err) => {
-  emitErr(err.message || String(err), err.code || ERR.GENERIC);
-  process.exit(err.code || ERR.GENERIC);
-});
-
-async function main() {
-  if (args.help) { printHelp(); process.exit(0); }
-
-  if (args.printServiceName) {
-    process.stdout.write(getOrCreateServiceName() + "\n");
-    return;
-  }
-
-  if (args.postDeploy) return recordPostDeploy();
-
-  // 1. Verify Vite project (cheap fingerprint).
-  const pkg = readPkg();
-  if (!pkg) throw withCode(ERR.NOT_VITE_PROJECT, "no package.json in cwd");
-  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-  if (!deps.vite) throw withCode(ERR.NOT_VITE_PROJECT, "vite not in dependencies/devDependencies");
-  if (!deps.react && !deps.vue) throw withCode(ERR.NOT_VITE_PROJECT, "neither react nor vue is a dependency");
-
-  // 2. Establish stable serviceName for this cwd.
-  const serviceName = getOrCreateServiceName();
-
-  // 3. Pre-deploy git snapshot (best-effort; not fatal if no git).
-  const snapshotTag = `snap/pre-deploy-${Date.now()}`;
-  const snapshotResult = gitSnapshot(snapshotTag);
-
-  // 4. Build.
-  if (!args.skipBuild) {
-    const buildScript = pkg.scripts?.build;
-    if (!buildScript) throw withCode(ERR.BUILD_FAILED, "package.json has no scripts.build");
-    runBuild();
-  }
-
-  // 5. Validate dist/.
-  const distPath = join(CWD, "dist");
-  if (!existsSync(distPath) || !statSync(distPath).isDirectory()) {
-    throw withCode(ERR.DIST_MISSING, "dist/ does not exist after build");
-  }
-  const entries = readdirSync(distPath);
-  if (entries.length === 0) {
-    throw withCode(ERR.DIST_MISSING, "dist/ is empty after build");
-  }
-
-  // 6. Emit nextAction. Local build is done → manageApps(framework=static)
-  //    skips remote install/build, only runs tcb hosting deploy.
-  const previouslyDeployed = readAppJson()?.lastDeployedAt != null;
-  const out = {
-    stage: "build-complete",
-    serviceName,
-    distPath,
-    distEntries: entries.length,
-    snapshotTag: snapshotResult.ok ? snapshotTag : null,
-    snapshotWarning: snapshotResult.ok ? null : snapshotResult.reason,
-    previouslyDeployed,
-    nextAction: {
-      tool: "manageApps",
-      args: {
-        action: "deployApp",
-        serviceName,
-        filePath: CWD,
-        buildPath: "dist",
-        framework: "static",
-        installCmd: "",
-        buildCmd: "",
-      },
-      hint: previouslyDeployed
-        ? `Re-deploys the existing CloudApp '${serviceName}' (URL stays the same).`
-        : `First-time deploy creates a new CloudApp '${serviceName}' with its own subdomain.`,
-      followup: {
-        tool: "cloudbase-vibe-deploy",
-        args: ["--post-deploy", "--access-url", "<accessUrl from manageApps result>", "--build-id", "<optional>"],
-        purpose: "record this deploy in app.json and tag git",
-      },
-    },
-  };
-
-  emitOk(out, `build complete; deploy '${serviceName}' next via manageApps (framework=static)`);
-}
-
-function recordPostDeploy() {
-  if (!args.accessUrl) throw withCode(ERR.GENERIC, "--post-deploy requires --access-url");
-
-  ensureDir(STATE_DIR);
-  const app = readAppJson() || { serviceName: getOrCreateServiceName(), deployHistory: [] };
-  const ts = new Date().toISOString();
-  const entry = {
-    deployedAt: ts,
-    accessUrl: args.accessUrl,
-    buildId: args.buildId || null,
-  };
-  app.deployHistory = [...(app.deployHistory || []), entry].slice(-50);
-  app.lastDeployedAt = ts;
-  app.lastAccessUrl = args.accessUrl;
-  if (!app.firstDeployedAt) app.firstDeployedAt = ts;
-  writeFileSync(APP_JSON, JSON.stringify(app, null, 2));
-
-  // Tag git.
-  const tag = `deploy/${Date.now()}`;
-  const tagResult = gitSnapshot(tag);
-
-  const cacheBust = randomQuery();
-  const finalUrl = appendQuery(args.accessUrl, `v=${cacheBust}`);
-
-  emitOk(
-    {
-      stage: "post-deploy",
-      serviceName: app.serviceName,
-      ...entry,
-      gitTag: tagResult.ok ? tag : null,
-      finalUrl,
-      deployCount: app.deployHistory.length,
-    },
-    `deploy recorded for '${app.serviceName}' — open: ${finalUrl}`,
-  );
-}
-
-// ---------------------------------------------------------------------------
-// serviceName: stable per cwd, generated once, written to app.json
-// ---------------------------------------------------------------------------
-
-function getOrCreateServiceName() {
-  const existing = readAppJson();
-  if (existing?.serviceName) return existing.serviceName;
-
-  // Generate: <sanitized dirname>-<6hex>.
-  const raw = basename(CWD).toLowerCase()
-    .replace(/[^a-z0-9-]/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "")
-    .slice(0, 36);              // CloudApp service names have length limits;
-                                // leave room for the suffix.
-  const safe = raw || "vibe";
-  const suffix = randomBytes(3).toString("hex");
-  const name = `${safe}-${suffix}`;
-
-  // Persist immediately so re-runs and --service-name are stable.
-  ensureDir(STATE_DIR);
-  const app = existing || {};
-  app.serviceName = name;
-  app.cwd = CWD;
-  if (!app.firstSeenAt) app.firstSeenAt = new Date().toISOString();
-  writeFileSync(APP_JSON, JSON.stringify(app, null, 2));
-  return name;
-}
-
-function readAppJson() {
-  if (!existsSync(APP_JSON)) return null;
-  try { return JSON.parse(readFileSync(APP_JSON, "utf8")); } catch { return null; }
-}
-
-// ---------------------------------------------------------------------------
-// helpers
-// ---------------------------------------------------------------------------
-
-function readPkg() {
-  const p = join(CWD, "package.json");
-  if (!existsSync(p)) return null;
-  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
-}
-
-function pickRunner() {
-  const which = (b) => spawnSync(process.platform === "win32" ? "where" : "which", [b], { stdio: "ignore" }).status === 0;
-  if (existsSync(join(CWD, "pnpm-lock.yaml")) && which("pnpm")) return ["pnpm", "run", "build"];
-  if (which("pnpm")) return ["pnpm", "run", "build"];
-  if (which("npm")) return ["npm", "run", "build"];
-  return ["npx", "--yes", "--no-install", "vite", "build"];
-}
-
-function runBuild() {
-  const [cmd, ...rest] = pickRunner();
-  const r = spawnSync(cmd, rest, {
-    cwd: CWD,
-    stdio: ["ignore", "inherit", "inherit"],
-    env: process.env,
-  });
-  if (r.status !== 0) {
-    throw withCode(ERR.BUILD_FAILED, `build exited with code ${r.status} (cmd: ${cmd} ${rest.join(" ")})`);
-  }
-}
-
-function gitSnapshot(tag) {
-  const inRepo = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: CWD, stdio: "ignore" });
-  if (inRepo.status !== 0) return { ok: false, reason: "not a git repository" };
-
-  spawnSync("git", ["add", "-A"], { cwd: CWD, stdio: "ignore" });
-  spawnSync("git", ["commit", "--allow-empty", "-m", `cloudbase-vibe: ${tag}`], { cwd: CWD, stdio: "ignore" });
-  const tagR = spawnSync("git", ["tag", "-f", tag], { cwd: CWD, stdio: "ignore" });
-  if (tagR.status !== 0) return { ok: false, reason: `git tag ${tag} failed` };
-  return { ok: true };
-}
-
-function randomQuery() {
-  return randomBytes(3).toString("hex");
-}
-
-function appendQuery(url, qs) {
-  if (!url || !qs) return url;
-  return url + (url.includes("?") ? "&" : "?") + qs;
-}
-
-function parseArgs(argv) {
-  const out = {};
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--skip-build") out.skipBuild = true;
-    else if (a === "--post-deploy") out.postDeploy = true;
-    else if (a === "--access-url") out.accessUrl = argv[++i];
-    else if (a === "--build-id") out.buildId = argv[++i];
-    else if (a === "--service-name") out.printServiceName = true;
-    else if (a === "--help" || a === "-h") out.help = true;
-  }
-  return out;
-}
-
-function printHelp() {
-  process.stdout.write([
-    "cloudbase-vibe-deploy — build + bridge to manageApps (framework=static, independent subdomain)",
-    "",
-    "Default flow (build phase):",
-    "  cloudbase-vibe-deploy                  # git snapshot + build + emit nextAction (-> manageApps)",
-    "  cloudbase-vibe-deploy --skip-build     # skip build, just emit nextAction (assumes dist/ exists)",
-    "",
-    "Post-deploy flow (call after manageApps succeeds):",
-    "  cloudbase-vibe-deploy --post-deploy --access-url <url> [--build-id <id>]",
-    "",
-    "Other:",
-    "  cloudbase-vibe-deploy --service-name   # print the stable serviceName for this cwd, exit",
-    "",
-    "Output: single JSON line on stdout. The build phase emits a `nextAction`",
-    "field telling the model to call manageApps with framework=static",
-    "(skips remote install/build; only tcb hosting deploy runs).",
-    "",
-    "State files:",
-    "  <cwd>/.cloudbase-agent/app.json           stable serviceName + deploy history",
-    "  git tag snap/pre-deploy-<ts>              before each build",
-    "  git tag deploy/<ts>                       after each --post-deploy",
-    "",
-  ].join("\n"));
-}
-
-function withCode(code, message) {
-  const e = new Error(message); e.code = code; return e;
-}
diff --git a/plugin/cloudbase-vibe-coding/skills/cloudbase-agent-runtime/SKILL.md b/plugin/cloudbase-vibe-coding/skills/cloudbase-agent-runtime/SKILL.md
deleted file mode 100644
index 3dfcba7b..00000000
--- a/plugin/cloudbase-vibe-coding/skills/cloudbase-agent-runtime/SKILL.md
+++ /dev/null
@@ -1,268 +0,0 @@
----
-name: cloudbase-agent-runtime
-description: |
-  Use when the user wants to develop, run, preview, or deploy a CloudBase
-  Web app in this conversation as a Lovable-like vibe-coding session — i.e.
-  any request that maps to "spin up a React+Vite project, see it live in
-  the browser, iterate, deploy". Activate ONLY for browser-rendered Web
-  projects based on the CloudBase official React (or Vue) + Vite template.
-  Do NOT activate for: WeChat/Alipay mini-program, React Native / Flutter /
-  Electron, pure cloud functions / CloudRun backends, or Next.js / Nuxt /
-  Astro / Remix / SvelteKit (those frameworks are explicitly out of scope).
----
-
-# CloudBase Agent Runtime — Web Vibe Coding
-
-This skill orchestrates a **single working directory = single project** flow
-for CloudBase Web apps. Every operation in this skill assumes the user's
-current shell `cwd` IS the project root. We do NOT manage cross-cwd state,
-session IDs, or workspaces — the cwd itself is the workspace.
-
-## Activation contract
-
-### Use this skill when
-
-- The user says "build me a website / app", "I want to make a landing page",
-  "create a React app and let me preview", "deploy this to CloudBase",
-  "vibe coding with CloudBase", or similar.
-- The current cwd looks like a CloudBase + Vite project (has `package.json`
-  with `vite` + `react` or `vue`).
-- The user is running this conversation inside a host (OpenClaw / Claude
-  Code) that has both `cloudbase-mcp` registered AND the `cloudbase-vibe-*`
-  binaries on PATH from this plugin.
-
-### Do NOT use this skill when
-
-- It's a mini-program project (`miniprogram-development` skill instead).
-- It's a native app project (`http-api` skill instead).
-- It's a backend-only project (`cloud-functions` or `cloudrun-development`).
-- The framework is Next/Nuxt/Astro/Remix — politely tell the user this skill
-  only covers Vite-based React/Vue apps and stop. Do NOT try to adapt the
-  scripts to those frameworks.
-
-## What this skill orchestrates
-
-Think of it as three layers:
-
-1. **CloudBase MCP tools** (provided by the `cloudbase-mcp` server registered
-   in `.mcp.json`). Use these for:
-   - `downloadTemplate({ template: "react" | "vue", ide: "<host>" })` — pull
-     the official template into cwd.
-   - `envQuery({ action: "info" })` and `auth({ action: "set_env", envId })`
-     — bind a CloudBase environment.
-   - `manageHosting({ action: "upload", localPath: "dist", cloudPath: "/" })`
-     — deploy the build output to static hosting.
-   - `envDomainManagement({ action: "create", domains: [...] })` — whitelist
-     the dev origin if Web SDK calls fail with CORS.
-   - All other CloudBase operations (auth, db, storage) follow the existing
-     `auth-tool` / `auth-web` / `no-sql-web-sdk` skills.
-
-2. **Plugin shell scripts** (provided by this plugin's `bin/` directory; on
-   PATH automatically when the plugin is enabled). Use these — and ONLY these
-   — for dev-server lifecycle:
-   - `cloudbase-vibe-start-preview` — daemonize Vite on `0.0.0.0:<auto>`.
-   - `cloudbase-vibe-stop-preview` — SIGTERM with SIGKILL fallback.
-   - `cloudbase-vibe-restart-preview` — stop + start in one shot.
-   - `cloudbase-vibe-status-preview` — JSON line of current state.
-
-   Never invent your own `npm run dev` / `vite` invocation. The shell scripts
-   handle host=0.0.0.0 forcing, port allocation, daemonization, base path
-   injection, and state file management. Reinventing them will break preview
-   on Lighthouse hosts and lose the recorded PID.
-
-3. **Standard tools** (Bash, git). Use for editing files, snapshots
-   (`git tag snap/<ts>`), rollback (`git reset --hard`), build (`pnpm build`).
-
-## How dev-server lifecycle is handled
-
-**You do NOT manage the dev server yourself.** Two host hooks do it for you:
-
-- **SessionStart hook** (auto-runs when the conversation begins):
-  - If cwd is on the danger blacklist (`$HOME`, `/`, `/tmp`, `~/Desktop`, ...) → skips silently.
-  - If cwd is a Vite + React/Vue project: starts the daemon (`cloudbase-vibe-start-preview`) if not already running, otherwise reuses the live one.
-  - If cwd is "empty enough" (only `.git` / `.gitignore` / `README*` / `LICENSE` allowed): auto-runs `cloudbase-vibe-init --start` which downloads the official CloudBase React template, runs `pnpm install`, and starts the daemon. **By the time you read the user's first prompt the dev server is usually live or ~10s away.**
-  - If cwd is a non-Vite project: skips silently.
-
-- **PostToolUse(Edit|Write|MultiEdit) hook**:
-  - If you edited `vite.config.*` / `package.json` / `tsconfig*.json` / `tailwind.config.*` / `postcss.config.*` / `.env*` → triggers `cloudbase-vibe-restart-preview` automatically (1.5s debounced).
-  - Other file edits → does nothing. Vite HMR handles them.
-
-**Implication: you almost never need to call `cloudbase-vibe-*` scripts directly.** The hooks handle init / start / restart. You only invoke a `cloudbase-vibe-*` script when:
-
-- The user explicitly says "stop the dev server" → `cloudbase-vibe-stop-preview`.
-- The user explicitly says "what's the URL" or "is it running" → `cloudbase-vibe-status-preview`.
-- The user wants to deploy → `cloudbase-vibe-deploy` (see deploy section below).
-
-If `cloudbase-vibe-status-preview` reports the preview is unhealthy and SessionStart didn't fix it (e.g., user-level error in `vite.config.ts`), surface the JSON `logPath` to the user — never try to fix it by editing their config blindly.
-
-## When the user just walked into the conversation
-
-1. **Check the preview state** before doing anything else by reading `<cwd>/.cloudbase-agent/preview.json` (or run `cloudbase-vibe-status-preview --quiet`). It is overwhelmingly likely that the preview is already up — courtesy of SessionStart.
-
-2. **Tell the user the URL**. If the file has `internalUrl`, surface it. If not (rare — SessionStart still running or skipped), inform the user the dev server is starting and ask them to wait ~10s, OR check `<cwd>/.cloudbase-agent/logs/hook-session-start.log` for the reason it skipped.
-
-3. **DO NOT** call `cloudbase-vibe-init` or `cloudbase-vibe-start-preview` proactively in your first message. The hook already does this. Calling it again is redundant and wastes a turn (`start` is idempotent so it's safe, but `init` will fail with code 10 because cwd is no longer empty).
-
-## When the user asks you to deploy
-
-The deploy flow uses **two-step bridge**: local build → CloudApp deploy.
-
-1. `bash> cloudbase-vibe-deploy` — performs `git tag snap/pre-deploy-...` + `pnpm run build`, validates `dist/`, generates a stable `serviceName` (e.g. `cb-test3-9f0d62`) on first run, and emits a JSON line with `nextAction`.
-2. Read `nextAction.tool` and `nextAction.args`. The tool will be `manageApps` with `framework=static` (skips remote npm install/build — only deploys the pre-built dist/):
-   ```
-   manageApps({
-     action: "deployApp",
-     serviceName: "<stable name from app.json>",
-     filePath: "<cwd>",
-     buildPath: "dist",
-     framework: "static",
-     installCmd: "",
-     buildCmd: ""
-   })
-   ```
-3. After `manageApps` succeeds and gives you the access URL, call:
-   `bash> cloudbase-vibe-deploy --post-deploy --access-url <url> [--build-id <id>]`
-   This appends to `<cwd>/.cloudbase-agent/app.json`'s `deployHistory`, tags git with `deploy/<ts>`, and returns a `finalUrl` with cache-busting query.
-4. Show `finalUrl` to the user. Optionally suggest the user can further polish the design by asking you to apply the **CloudBase UI design skill** (`ui-design`) for a more polished look.
-5. After deployment, proactively ask: "要我在部署后的基础上用 UI 设计能力进一步优化样式和体验吗？"
-
-**Why `manageApps(framework=static)` not `manageHosting`?** Each `manageApps` service gets its own independent `*.webapps.tcloudbase.com` subdomain — no path collisions between vibe sessions, and no need to bind a custom domain just for isolation. Since the local build already produced `dist/`, we pass `installCmd=""` and `buildCmd=""` to skip remote build steps; only the `tcb hosting deploy` step runs in the cloud. If that still fails, fall back to `manageHosting` + bind a custom domain.
-
-**If `manageApps` fails with "no envId" or env-related error:** call `envQuery({ action: "info" })` once. If multiple envs exist, ask the user to pick. After the env is bound, retry.
-
-**If `manageApps` builds FAILED:** call `queryApps({ action: "getBuildLog", serviceName, buildId })` to diagnose. Common cause is the remote `tcb hosting deploy` step failing — fall back to `manageHosting` upload in that case.
-
-Never bypass `cloudbase-vibe-deploy` with your own `pnpm build` + manual `manageApps` — you would lose the snapshot, deploy history, and serviceName stability.
-
-## Proactive deploy suggestion
-
-When you finish a user-requested feature (especially "make me a X app", "build me a Y", "add Z feature"), end your reply by asking the user **whether to deploy**:
-
-> 现在这版要部署看一下吗?(部署到 CloudApp,会得到一个独立的可分享 URL)
-
-Do NOT deploy unsolicited — only after the user explicitly says yes. The reason for asking is to make sharing as low-friction as possible, similar to Lovable: the user shouldn't have to learn that "deploy" is a separate action they need to ask for.
-
-Skip the suggestion when:
-- The work was a bug fix or small refactor (no new feature).
-- The user already deployed in this conversation and the change since then is trivial.
-- The user explicitly said "don't deploy yet" earlier.
-
-## Proactive verification suggestion
-
-After finishing a feature, do NOT spend turns on writing or running automated UI tests / playwright / agent-browser by default. Instead end your reply by asking the user **whether to verify in a browser**:
-
-> 现在这版要不要我用内置浏览器打开 <internalUrl> 帮你点一遍验证一下?
-
-Skip when:
-- The user already said "no tests" / "skip tests" earlier.
-- The change was config-only or non-visual.
-- The user is mid-iterating and obviously wants to keep editing.
-
-Only after explicit consent should you spawn a browser-driving tool. The first version of a vibe-coding app is judged by "does the user see the UI working in the dev server", not by passing tests.
-
-## Data persistence — BaaS-first
-
-When the feature needs to store / query / update data:
-
-1. **Create the schema via cloudbase-mcp.** Call:
-   ```
-   writeNoSqlDatabaseStructure({
-     action: "createCollection",
-     collectionName: "todos"
-   })
-   ```
-   And add indexes via `updateCollection` with `updateOptions.CreateIndexes`. Do NOT ask the user to create collections in the console.
-2. **Read/write via Web SDK directly from the React/Vue code.** The template ships an initialized `@cloudbase/js-sdk` at `src/utils/cloudbase.ts`. Use it:
-   ```ts
-   import { db } from "@/utils/cloudbase";
-   await db.collection("todos").add({ text, done: false, createdAt: Date.now() });
-   const { data } = await db.collection("todos").orderBy("createdAt", "desc").get();
-   db.collection("todos").watch({ onChange: (snap) => setTodos(snap.docs) });
-   ```
-3. **For auth**: follow `auth-tool` skill first (provider check), then `auth-web` for client code.
-
-**Do NOT add a cloud function** unless ALL of these are true:
-(a) the logic absolutely cannot be expressed as database security rules;
-(b) it needs server-side secrets / third-party APIs (e.g. payment, SMS);
-(c) it's a scheduled / background job, not user-triggered.
-
-A Todo app, Notes app, Chat app, Kanban etc. live ENTIRELY in the JS SDK + database rules. Adding a cloud function "just to be safe" is over-engineering and slows the user.
-
-## When the conversation ends
-
-Do nothing. The dev server is daemonized (PPID=1) and survives. The next SessionStart will detect it's still running and reuse it — the user comes back to a live URL with no startup delay.
-
-## Hard rules
-
-1. **Never** spawn `npm run dev` / `vite` / `vite build` yourself. Dev-server lifecycle is owned by the SessionStart and PostToolUse hooks; build/deploy is owned by `cloudbase-vibe-deploy`. Bypassing them loses host=0.0.0.0 forcing, port allocation, daemonization, snapshot, and deploy history.
-
-2. **Never** edit the user's `vite.config.*` to set `server.host` or `base`.
-   The CLI flags from `start-preview` already override config. If the user's
-   config conflicts (for example `server.host: false`), surface error code 4
-   from start-preview and ask the user to relax that config — do NOT silently
-   patch their file.
-
-3. **Never** touch the `~/.cloudbase-agent/` global directory. State lives
-   in `<cwd>/.cloudbase-agent/preview.json`. Each cwd is independent.
-
-4. **Always** parse stdout of `cloudbase-vibe-*` scripts as a single JSON
-   line. The first line of stdout is the machine-readable result. The
-   stderr `[cloudbase-agent] ...` line is for humans only — do not parse it.
-
-5. **Always** surface `logPath` to the user when a script reports failure.
-   Don't guess the cause from a one-line error — point them at the log file.
-
-## Error codes from the bin scripts
-
-| code | meaning | recovery |
-|---|---|---|
-| 1 | generic failure | check the message |
-| 2 | not a Vite project (or `vite` binary missing) | `pnpm install` then retry |
-| 3 | port pool exhausted in 17173..17272 | `cloudbase-vibe-stop-preview` for stale ones, or pass `--port` |
-| 4 | dev server failed health check in 30s | read `logPath`; usually a build error in user code |
-| 5 | no preview is running (status / stop) | start one with `cloudbase-vibe-start-preview` |
-| 6 | stop failed (process refused SIGKILL) | check the PID manually with `ps`; very rare |
-| 7 | build failed (`cloudbase-vibe-deploy`) | inspect build output in this terminal; fix code, retry |
-| 8 | `dist/` missing or empty after build | confirm `scripts.build` runs `vite build`; rerun |
-
-## State files (for debugging)
-
-- `<cwd>/.cloudbase-agent/preview.json` — current preview state.
-- `<cwd>/.cloudbase-agent/logs/preview-<timestamp>.log` — Vite stdout/stderr.
-- `<cwd>/.cloudbase-agent/logs/hook-restart.log` — restart trigger trail (PostToolUse hook).
-- `<cwd>/.cloudbase-agent/restart.lock` — debounce lock for the hook (1.5s window).
-
-These are owned by the scripts. If the user asks "show me the dev log",
-open the path from `status-preview`'s JSON output.
-
-## Hook & monitor behavior (auto-driven, model is passive)
-
-This plugin ships two host-driven mechanisms; the model itself does NOT need
-to invoke them, but should be aware they exist:
-
-- **PostToolUse hook** (`hooks/hooks.json`): when the model edits a file via
-  `Edit` / `Write` / `MultiEdit`, the host fires `hooks/on-file-change.sh`.
-  The hook checks the edited file path; if it's a config file (`vite.config.*`,
-  `tailwind.config.*`, `postcss.config.*`, `package.json`, `tsconfig*.json`,
-  `.env*`), it triggers `cloudbase-vibe-restart-preview` in the background
-  with a 1.5s debounce. The model does NOT need to manually restart on
-  config edits — the hook handles it. If the host doesn't support hooks,
-  fall back to manually calling restart per the rule above.
-
-- **Vite log monitor** (`monitors/monitors.json`, EXPERIMENTAL): the host
-  tails the latest `<cwd>/.cloudbase-agent/logs/preview-*.log` and forwards
-  each new line to the model as a notification. The model can use this to
-  proactively report build errors / HMR failures without the user asking.
-  ⚠️ This relies on the host's monitor implementation honoring the project
-  cwd; if monitor lines do not appear in the conversation, treat it as not
-  available and fall back to `cloudbase-vibe-status-preview` on demand.
-
-## What this skill is NOT
-
-- It is **not** a session manager. There is no sessionId. There is only cwd.
-- It is **not** a reverse proxy. If the host is on Lighthouse and the user
-  needs `0.0.0.0:8080/s/<sid>/` style routing, that's a separate runtime
-  component (`cloudbase-agent-proxy`, see project README) — out of scope here.
-- It is **not** a CloudBase auth/database guide. For those, route to the
-  existing `auth-web`, `auth-tool`, `no-sql-web-sdk` skills.
-- It is **not** a UI design guide. For visual decisions, route to `ui-design`.
diff --git a/scripts/tools.json b/scripts/tools.json
index 42b41f5a..5db488cf 100644
--- a/scripts/tools.json
+++ b/scripts/tools.json
@@ -1087,7 +1087,7 @@
     },
     {
       "name": "manageHosting",
-      "description": "管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。若任务只是查看配置、文件或域名状态，请改用 queryHosting。",
+      "description": "管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物到共享域名（域名格式：<envId>-<appId>.tcloudbaseapp.com/<cloudPath>）；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。⚠️ 新项目部署优先使用 manageApps（部署到独立子域名），本工具适合已有老项目继续使用或作为 manageApps 的 fallback。manageApps 与 manageHosting 域名不同，切换会导致老链接失效。若任务只是查看配置、文件或域名状态，请改用 queryHosting。",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2286,8 +2286,7 @@
               "getUploadUrl",
               "deleteApp",
               "deleteAppVersion"
-            ],
-            "description": "可填写的值: deployApp, getUploadUrl, deleteApp, deleteAppVersion"
+            ]
           },
           "serviceName": {
             "type": "string",
@@ -2776,4 +2775,4 @@
       }
     }
   ]
-}
+}
\ No newline at end of file
diff --git a/specs/cloudbase-sites-codex-plugin/design.md b/specs/cloudbase-sites-codex-plugin/design.md
new file mode 100644
index 00000000..8717eb9f
--- /dev/null
+++ b/specs/cloudbase-sites-codex-plugin/design.md
@@ -0,0 +1,258 @@
+# 技术方案
+
+## 概述
+
+CloudBase Sites 将在现有 `plugin/cloudbase-sites` 目录中补充 Codex 插件形态，并将运行时命名统一为 Sites。实现目标是让同一套核心 CLI 和 runtime 同时服务 Claude Code / CodeBuddy / Codex，宿主差异只保留在 manifest、hook 包装和文档说明中。
+
+本方案不兼容旧的 `.cloudbase-agent/` 状态目录。实现后所有项目级状态写入 `<cwd>/.cloudbase-sites/`，所有机器级 supervisor 状态写入 `~/.cloudbase-sites/`。
+
+## 架构
+
+```mermaid
+flowchart TD
+  User["User in Codex / Claude Code / CodeBuddy"] --> Skill["cloudbase-sites Skill"]
+  Skill --> CLI["bin/cloudbase-sites"]
+  Skill --> MCP["cloudbase-mcp"]
+  Hook["Host lifecycle hooks"] --> CLI
+  CLI --> LocalState["<cwd>/.cloudbase-sites"]
+  CLI --> GlobalState["~/.cloudbase-sites"]
+  CLI --> Git["Project Git commits/tags"]
+  MCP --> CloudBase["Tencent CloudBase resources"]
+```
+
+### 分层职责
+
+- Plugin manifests
+  - `.claude-plugin/plugin.json` 保留 Claude Code / CodeBuddy 元数据。
+  - `.codex-plugin/plugin.json` 新增 Codex 插件元数据，引用 `./skills/` 和 `./.mcp.json`。
+  - Codex manifest 不写 `hooks` 字段；Codex 通过默认 `hooks/hooks.json` 发现插件 hooks。
+- Shared runtime
+  - `bin/cloudbase-sites` 是唯一用户入口。
+  - `lib/verbs/*` 继续承载 `init`、`preview`、`save`、`deploy`、`rollback`、`versions`、`supervisor`。
+  - `lib/*` 中所有状态路径统一从 `.cloudbase-agent` 改为 `.cloudbase-sites`。
+- Host hooks
+  - `hooks/hooks.json` 保留生命周期声明，但 hook command 需要避免硬编码 Claude-only 变量。
+  - `on-session-start.sh` 和 `on-file-change.sh` 继续作为 hook 实现。
+  - 如果 Codex 未信任或禁用 hooks，skill 中的显式 CLI 流程仍可工作。
+- Cloud effects
+  - 只有 `cloudbase-mcp` 负责 CloudBase 资源副作用，例如 `manageApps`、`envQuery`、数据库和认证配置。
+
+## Codex 插件 Manifest
+
+新增 `plugin/cloudbase-sites/.codex-plugin/plugin.json`，字段遵循本地 `plugin-creator` 校验器：
+
+- `name`: `cloudbase-sites`
+- `version`: 与 Claude manifest 初始保持一致，例如 `0.1.0`
+- `description`: 明确为 CloudBase 托管的 Sites-like workflow
+- `author`: Tencent CloudBase
+- `homepage` / `repository` / `license` / `keywords`
+- `skills`: `./skills/`
+- `mcpServers`: `./.mcp.json`
+- `interface`
+  - `displayName`: `CloudBase Sites`
+  - `shortDescription`: 建站、预览、保存版本、部署到 CloudBase
+  - `longDescription`: 说明 CloudBase hosting/database/storage/auth/backend 能力
+  - `developerName`: `Tencent CloudBase`
+  - `category`: `Developer Tools`
+  - `capabilities`: 至少包含 `Write`、`Interactive`
+  - `defaultPrompt`: 3 条以内，覆盖创建站点、部署、加数据库
+
+先不添加 logo/screenshots，避免引入资源验证问题。后续如需要插件卡片视觉，再放入 `assets/` 并更新 manifest。
+
+## Hooks 设计
+
+Codex 支持插件 bundled hooks，但非托管 hooks 需要用户信任。实现上遵守以下原则：
+
+- `hooks/hooks.json` 使用 Codex/Claude 都能理解的事件名和 matcher：`SessionStart`、`PostToolUse`、`Edit|Write|MultiEdit`。
+- hook command 不依赖 `${CLAUDE_PLUGIN_ROOT}` 作为唯一路径来源。
+- hook 脚本应通过如下顺序解析插件根目录：
+  1. host 提供的插件根环境变量；
+  2. 脚本自身路径 `dirname "$0"/..`；
+  3. `command -v cloudbase-sites`。
+- hook 失败不阻塞用户操作，错误写入 `.cloudbase-sites/logs/`。
+- `SessionStart` 输出的 Claude additionalContext 对 Codex 不作为强依赖；Codex 主要依赖 bundled skill 和 hook 副作用。
+
+## 状态与日志
+
+### 项目级状态
+
+所有项目级状态写入：
+
+```text
+<cwd>/.cloudbase-sites/
+  preview.json
+  app.json
+  restart.lock
+  template.zip
+  logs/
+    preview-<ts>.log
+    hook-session-start.log
+    hook-restart.log
+```
+
+`app.json` 继续使用 V2 schema：
+
+```json
+{
+  "siteName": "project-abcdef",
+  "cwd": "/path/to/project",
+  "firstSeenAt": "ISO timestamp",
+  "versions": [
+    {
+      "n": 1,
+      "commitSha": "abc1234",
+      "label": "initial version",
+      "savedAt": "ISO timestamp",
+      "status": "saved"
+    }
+  ],
+  "deployments": [
+    {
+      "version": 1,
+      "deployedAt": "ISO timestamp",
+      "accessUrl": "https://...",
+      "buildId": "optional",
+      "versionName": "optional",
+      "buildStatus": "SUCCESS",
+      "finalUrl": "https://...?v=..."
+    }
+  ],
+  "currentVersion": 1,
+  "currentDeploy": 1
+}
+```
+
+### 机器级状态
+
+所有跨项目 supervisor 状态写入：
+
+```text
+~/.cloudbase-sites/
+  registry.json
+  supervisor.json
+  supervisor.lock
+  registry.lock
+  supervisor.log
+```
+
+### Git ignore
+
+`cloudbase-sites init` 和任何会创建状态目录的命令应确保用户项目 `.gitignore` 包含：
+
+```gitignore
+.cloudbase-sites/
+```
+
+仓库自身 `.gitignore` 也应加入 `**/.cloudbase-sites/`，防止测试或本地运行产生状态文件被提交。
+
+## Save / Deploy / Rollback 语义
+
+### Save
+
+`cloudbase-sites save -m "<label>"` 保持 Git checkpoint 模型：
+
+1. 确认当前目录是 Git repo。
+2. 确保 `.cloudbase-sites/` 已被 Git 忽略。
+3. `git add -A`
+4. `git commit --allow-empty -m "version <n>: <label>"`
+5. `git tag -f version/<n>`
+6. 写入 `app.json.versions[]`
+
+该命令只创建本地 commit/tag，不 push。
+
+### Deploy
+
+为避免“指定版本”和“当前工作区”语义不一致，部署指定版本时采用清晰策略：
+
+- `cloudbase-sites deploy --version <n>` 应部署版本 `n` 对应的 Git commit。
+- 如果当前 HEAD 不是目标版本 commit，命令应先 stash 当前未提交修改，再 checkout/reset 到目标 commit 进行 build。
+- build 完成并输出 `nextAction` 后，不自动恢复工作树；恢复或继续编辑由用户通过 rollback/save 流程显式完成。
+
+Phase 1 输出 `nextAction`：
+
+```json
+{
+  "tool": "manageApps",
+  "args": {
+    "action": "deployApp",
+    "serviceName": "<siteName>",
+    "filePath": "<cwd>",
+    "buildPath": "dist",
+    "framework": "static",
+    "installCmd": "",
+    "buildCmd": ""
+  }
+}
+```
+
+Phase 2 由 agent 在 `manageApps` 成功后调用：
+
+```bash
+cloudbase-sites deploy --post --version <n> --access-url <url> --build-id <optional>
+```
+
+记录 `deployments[]`、更新 `currentDeploy`，并打 `deploy/<n>-<ts>` tag。
+
+Phase 2 应尽量记录 CloudBase 构建元数据：
+
+- `buildId`: `manageApps` 返回的 `BuildId`，用于后续 `queryApps(action="getAppVersion")` 和 `queryApps(action="getBuildLog")`。
+- `versionName`: `manageApps` 返回的 `VersionName`，如果存在则记录。
+- `buildStatus`: 当前已知构建状态，成功部署时默认可记录为 `SUCCESS`。
+
+如果 `manageApps` 返回了 `BuildId`，agent 必须通过 `--build-id` 传给 `cloudbase-sites deploy --post`。如果 Phase 2 未收到 buildId，CLI 应在 JSON 输出中给出 warning，提示该部署无法直接追踪 CloudBase 构建日志。
+
+### Rollback
+
+`cloudbase-sites rollback --to-version <n>`：
+
+1. stash 未提交修改；
+2. `git reset --hard <version.commitSha>`；
+3. 标记目标版本之后的版本为 `rolled-back`；
+4. 异步 `preview --restart`。
+
+Rollback 不自动部署，用户需要显式 deploy。
+
+## 已知 runtime 修正
+
+本次实现应包含以下修正：
+
+- `cloudbase-sites status` 改为 `preview --status` 的真实别名。
+- `on-session-start.sh` 读取 V2 `app.json` 的 `versions/deployments/currentVersion/currentDeploy`。
+- 所有 `[cloudbase-agent]` stderr 前缀改为 `[cloudbase-sites]`。
+- `cloudbase-agent-runtime` skill 目录或 skill name 改为 Sites 命名，例如 `skills/cloudbase-sites-runtime/SKILL.md`。
+- `init` 的 empty-enough 允许列表从 `.cloudbase-agent` 改为 `.cloudbase-sites`。
+
+## 安全性
+
+- 不提交 secret、日志、PID、端口、模板压缩包或运行态 JSON。
+- `save` 和 rollback 都只做本地 Git 操作，不 push。
+- Codex hook 信任由 Codex 自身 hook review 机制处理。
+- CloudBase 云端资源变更继续走 `cloudbase-mcp`，受 MCP tool approval 和 CloudBase auth 约束。
+
+## 测试策略
+
+### 静态验证
+
+- 运行 Codex plugin validator：
+
+```bash
+python3 /Users/bookerzhao/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugin/cloudbase-sites
+```
+
+- grep 验证插件 runtime 不再出现 `.cloudbase-agent` 和 `[cloudbase-agent]`。
+
+### CLI 验证
+
+在临时 Vite fixture 或测试项目中验证：
+
+- `cloudbase-sites --help`
+- `cloudbase-sites status`
+- `cloudbase-sites preview --status` 在无 preview 时返回可解析 JSON
+- `cloudbase-sites save -m "test"` 不会提交 `.cloudbase-sites/`
+- `cloudbase-sites versions`
+- `cloudbase-sites deploy --skip-build` 在已有 saved version 和 dist 时输出 `nextAction`
+
+### 文档/生成物控制
+
+- 本任务不需要更新 `doc/mcp-tools.md` 或 `scripts/tools.json`。
+- 提交前检查 `git diff --stat`，排除无关生成产物漂移。
diff --git a/specs/cloudbase-sites-codex-plugin/requirements.md b/specs/cloudbase-sites-codex-plugin/requirements.md
new file mode 100644
index 00000000..992be3ed
--- /dev/null
+++ b/specs/cloudbase-sites-codex-plugin/requirements.md
@@ -0,0 +1,90 @@
+# 需求文档
+
+## 介绍
+
+CloudBase Sites 需要在现有 Claude Code / CodeBuddy 插件基础上补充 Codex 插件形态，使 Codex 用户可以安装并使用 CloudBase 的站点创建、预览、版本保存、部署、回滚和后端能力。该能力参考 Codex Sites 的 save -> deploy 心智，但实际托管、数据库、存储、认证、云函数和云托管能力由 Tencent CloudBase 与 `cloudbase-mcp` 提供。
+
+本需求不追求复制 OpenAI 官方 Sites 的托管控制台或访问控制面板，而是让 CloudBase Sites 在 Codex 中成为可安装、可调用、可验证的 CloudBase 全栈建站插件。实现时需要复用现有 `plugin/cloudbase-sites` 的 CLI、skills、MCP 配置和运行时逻辑，同时隔离 Claude Code / CodeBuddy 专属 manifest 与 hook 行为，避免破坏现有宿主。
+
+## 需求
+
+### 需求 1 - Codex 插件元数据与安装入口
+
+**用户故事：** 作为 Codex 用户，我希望能以 Codex 插件的形式安装 CloudBase Sites，从而在 Codex 中直接调用 CloudBase 建站和部署能力。
+
+#### 验收标准
+
+1. When Codex 读取 `plugin/cloudbase-sites` 插件目录时，the CloudBase Sites plugin shall provide a valid `.codex-plugin/plugin.json` manifest with name `cloudbase-sites`, display name `CloudBase Sites`, semver version, author, description, interface metadata, skills path, and MCP server path.
+2. When Codex 插件校验脚本运行时，the CloudBase Sites plugin shall pass the local plugin validation without unsupported manifest fields, placeholder values, or missing referenced files.
+3. When Codex 用户浏览插件时，the CloudBase Sites plugin shall present CloudBase-oriented descriptions and starter prompts that distinguish it from OpenAI official Sites while preserving the site-building mental model.
+4. While preserving existing Claude Code / CodeBuddy support, when Codex metadata is added, the CloudBase Sites plugin shall keep `.claude-plugin/plugin.json` working and shall not rename or remove existing runtime files used by those hosts.
+
+### 需求 2 - 跨宿主复用边界
+
+**用户故事：** 作为插件维护者，我希望 Codex、Claude Code 和 CodeBuddy 复用同一套 CloudBase Sites 核心能力，同时把宿主专属配置隔离开，降低维护成本和兼容风险。
+
+#### 验收标准
+
+1. When maintaining shared behavior, the CloudBase Sites plugin shall keep the shared CLI under `bin/cloudbase-sites` and shared runtime under `lib/` as the single implementation source for init, preview, save, deploy, rollback, versions, and supervisor behavior.
+2. When host-specific behavior is required, the CloudBase Sites plugin shall keep host-specific manifests or hook contracts in separate host-facing files instead of embedding Claude-only assumptions into the Codex manifest.
+3. When the skill documentation references host-specific lifecycle behavior, the CloudBase Sites plugin shall describe Codex, Claude Code, and CodeBuddy differences accurately enough that agents do not rely on unavailable features.
+4. When adding Codex support, the CloudBase Sites plugin shall continue to register `cloudbase-mcp` via the plugin MCP configuration so CloudBase tools remain the source of cloud-side effects.
+
+### 需求 3 - Codex hooks 支持与降级策略
+
+**用户故事：** 作为 Codex 用户，我希望 CloudBase Sites 能自动启动预览和在配置变更后重启预览，但在 hooks 未启用或未信任时仍能通过显式命令工作。
+
+#### 验收标准
+
+1. While Codex hooks are enabled and trusted, when a Codex thread starts in a supported project directory, the CloudBase Sites plugin shall run its SessionStart lifecycle logic to initialize or start preview according to the existing safety rules.
+2. While Codex hooks are enabled and trusted, when Codex edits Vite-related config files, package metadata, or environment files, the CloudBase Sites plugin shall trigger a debounced preview restart through `cloudbase-sites preview --restart`.
+3. While Codex hooks are disabled, untrusted, or unavailable, when the user asks for preview status, save, deploy, versions, or rollback, the CloudBase Sites plugin shall still provide explicit CLI-based workflows through the bundled skill.
+4. When Codex hook configuration is packaged, the CloudBase Sites plugin shall use a Codex-compatible hook layout and shall not depend on Claude-only environment variables such as `CLAUDE_PLUGIN_ROOT` unless a host-specific branch guarantees them.
+5. When a hook command fails, the CloudBase Sites plugin shall avoid blocking the user’s editing action and shall write diagnostics to the configured local log path.
+
+### 需求 4 - 本地状态、日志和 Git 安全
+
+**用户故事：** 作为使用 CloudBase Sites 迭代项目的开发者，我希望预览状态、部署历史和日志可靠保存，但不希望 PID、日志、环境信息或构建产物被误提交。
+
+#### 验收标准
+
+1. When CloudBase Sites records preview runtime state, the CloudBase Sites plugin shall store process-local state such as PID, port, preview URL, and log paths under `<cwd>/.cloudbase-sites/`.
+2. When CloudBase Sites records site lifecycle state, the CloudBase Sites plugin shall store site name, saved versions, deployments, current version, and current deploy metadata under `<cwd>/.cloudbase-sites/app.json`.
+3. When CloudBase Sites initializes or manages a project, the CloudBase Sites plugin shall ensure `.cloudbase-sites/` is ignored by Git to prevent local state and logs from being committed.
+4. When cross-project supervision is active, the CloudBase Sites plugin shall store machine-level registry and supervisor state under `~/.cloudbase-sites/`, not in an individual project repository.
+5. When future shared project metadata is needed, the CloudBase Sites plugin shall use a separate commit-safe file such as `.cloudbase/sites.json` and shall keep secrets, logs, PIDs, and transient runtime details out of that file.
+
+### 需求 5 - Save / deploy / rollback 语义一致性
+
+**用户故事：** 作为 CloudBase Sites 用户，我希望保存版本、部署版本和回滚版本的行为清楚一致，避免以为部署的是某个保存版本但实际部署了当前工作区。
+
+#### 验收标准
+
+1. When the user runs `cloudbase-sites save`, the CloudBase Sites plugin shall create a labeled Git checkpoint and append a version record to `app.json.versions[]`.
+2. When the user deploys a specified saved version, the CloudBase Sites plugin shall either build exactly that saved version or clearly document and report that it is deploying the current working tree associated with that version label.
+3. When deployment phase 1 succeeds, the CloudBase Sites plugin shall emit a JSON `nextAction` instructing the agent to call `manageApps(action="deployApp")` with stable `siteName`, `filePath`, `buildPath`, `framework`, `installCmd`, and `buildCmd`.
+4. When deployment phase 2 records a CloudBase access URL, the CloudBase Sites plugin shall append deployment metadata to `app.json.deployments[]` and report a final URL with cache-busting when appropriate.
+5. When `manageApps` returns a build identifier or version identifier, the CloudBase Sites plugin shall record that CloudBase build metadata in the deployment entry so future status and log queries can trace the deployed artifact.
+6. When the user rolls back to a saved version, the CloudBase Sites plugin shall preserve uncommitted edits through Git stash, reset to the target version, mark newer versions as rolled back, and restart preview unless disabled by user option.
+
+### 需求 6 - 现有 runtime 缺陷修正
+
+**用户故事：** 作为插件维护者，我希望在接入 Codex 前修复现有 CloudBase Sites runtime 中会影响稳定性的明显问题。
+
+#### 验收标准
+
+1. When the user runs `cloudbase-sites status`, the CloudBase Sites CLI shall behave as an alias for `cloudbase-sites preview --status` and shall not recurse indefinitely.
+2. When SessionStart reports deployment state, the hook shall read the current V2 `app.json` schema including `versions`, `deployments`, `currentVersion`, and `currentDeploy`.
+3. When `save`, `deploy`, or `rollback` perform Git operations, the CloudBase Sites plugin shall avoid staging ignored runtime state such as `.cloudbase-sites/`, `dist/`, `node_modules/`, and `.env`.
+4. When generated tool/schema docs are unrelated to this plugin task, the implementation shall not include accidental generated artifact drift in the final change.
+
+### 需求 7 - 验证与文档
+
+**用户故事：** 作为维护者和用户，我希望 CloudBase Sites 的 Codex 插件形态有基本验证和说明，方便本地安装、回归和后续发布。
+
+#### 验收标准
+
+1. When implementation is complete, the CloudBase Sites plugin shall be validated with the local Codex plugin validator.
+2. When runtime CLI behavior changes, the implementation shall include focused verification for affected commands such as `status`, `save`, `deploy --skip-build`, and version listing where feasible.
+3. When Codex support is added, the repository shall include concise documentation or comments explaining how to install or test CloudBase Sites as a local Codex plugin.
+4. When final diffs are reviewed, the implementation shall not include unrelated changes to generated MCP docs or tool JSON unless the task explicitly requires them.
diff --git a/specs/cloudbase-sites-codex-plugin/tasks.md b/specs/cloudbase-sites-codex-plugin/tasks.md
new file mode 100644
index 00000000..e1d1f5ce
--- /dev/null
+++ b/specs/cloudbase-sites-codex-plugin/tasks.md
@@ -0,0 +1,67 @@
+# 实施计划
+
+- [x] 1. 补充 Codex 插件 manifest
+  - 新增 `plugin/cloudbase-sites/.codex-plugin/plugin.json`
+  - 填写 `CloudBase Sites` 的 Codex UI 元数据、starter prompts、skills 和 MCP server 路径
+  - 运行本地 Codex plugin validator，修正 manifest schema 问题
+  - _需求: 1_
+
+- [x] 2. 统一 Sites 状态目录命名
+  - 将项目级状态路径从 `.cloudbase-agent` 改为 `.cloudbase-sites`
+  - 将全局 supervisor/registry 路径从 `~/.cloudbase-agent` 改为 `~/.cloudbase-sites`
+  - 将 CLI help、skill 文档、hook 日志路径和错误提示同步为 Sites 命名
+  - 将 stderr 前缀从 `[cloudbase-agent]` 改为 `[cloudbase-sites]`
+  - 不实现旧 `.cloudbase-agent` 兼容迁移
+  - _需求: 4, 6_
+
+- [x] 3. 更新 Git ignore 防护
+  - 在仓库 `.gitignore` 中加入 `**/.cloudbase-sites/`
+  - 在 `cloudbase-sites init` 或状态目录创建流程中确保用户项目 `.gitignore` 包含 `.cloudbase-sites/`
+  - 确认 `save` 的 `git add -A` 不会提交 `.cloudbase-sites/`、`dist/`、`node_modules/`、`.env`
+  - _需求: 4, 6_
+
+- [x] 4. 梳理跨宿主 manifest 与 skill 复用
+  - 保留 `.claude-plugin/plugin.json`
+  - 将 skill 文件或 skill name 从 agent runtime 命名调整为 CloudBase Sites runtime 命名
+  - 在 skill 文档中明确 Codex、Claude Code、CodeBuddy 的 hooks 和 context 注入差异
+  - 确保 shared CLI/runtime 仍为唯一实现源
+  - _需求: 2_
+
+- [x] 5. 适配 Codex-compatible hooks
+  - 调整 `hooks/hooks.json` 保持 Codex 可发现的默认 hook 布局
+  - 修改 hook 脚本的插件根目录解析逻辑，避免只依赖 `CLAUDE_PLUGIN_ROOT`
+  - 将 `on-session-start.sh` 的状态读取逻辑更新到 V2 `app.json`
+  - 保持 hooks 失败不阻塞，诊断写入 `.cloudbase-sites/logs/`
+  - _需求: 3, 6_
+
+- [x] 6. 修复 CLI alias 和 runtime 行为
+  - 修复 `cloudbase-sites status`，使其真实等价于 `cloudbase-sites preview --status`
+  - 更新 `init` 的 empty-enough allowlist 为 `.cloudbase-sites`
+  - 更新 `versions`、`preview`、`supervisor` 的路径和输出
+  - _需求: 4, 6_
+
+- [x] 7. 收紧 save / deploy / rollback 语义
+  - 明确 `save` 创建本地 Git commit/tag，不 push
+  - 部署指定 version 时构建对应 saved commit，避免部署当前工作区却标记为旧版本
+  - 保留 rollback 的 stash + reset + preview restart 行为
+  - 确认命令输出 JSON 可被 agent 稳定解析
+  - _需求: 5_
+
+- [x] 8. 记录 CloudBase 构建元数据
+  - 扩展部署记录 schema，支持 `buildId`、`versionName`、`buildStatus`
+  - 调整 `deploy --post` 参数解析和 `appendDeployment`
+  - 当未传 `--build-id` 时在 JSON 中输出 warning
+  - 更新 skill 文档，要求 agent 将 `manageApps` 返回的 BuildId 传回 Phase 2
+  - _需求: 5_
+
+- [x] 9. 添加或更新聚焦验证
+  - 为路径常量、deployment schema、status alias 等可单测逻辑添加测试或轻量验证脚本
+  - 用临时 Vite fixture 验证 `status`、`save`、`versions`、`deploy --skip-build` 的关键输出
+  - 验证 Codex plugin validator 通过
+  - _需求: 1, 6, 7_
+
+- [x] 10. 文档与最终自查
+  - 补充本地安装/测试 CloudBase Sites Codex 插件的简短说明
+  - 检查 `git diff --stat`，排除无关 `doc/mcp-tools.md`、`scripts/tools.json` 漂移
+  - 扫描确认无 `.cloudbase-agent`、`[cloudbase-agent]` 残留
+  - _需求: 7_
diff --git a/tests/cloudbase-sites-plugin.test.js b/tests/cloudbase-sites-plugin.test.js
new file mode 100644
index 00000000..b1714b4c
--- /dev/null
+++ b/tests/cloudbase-sites-plugin.test.js
@@ -0,0 +1,232 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { afterEach, describe, expect, test } from 'vitest';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT_DIR = path.resolve(__dirname, '..');
+const PLUGIN_DIR = path.join(ROOT_DIR, 'plugin', 'cloudbase-sites');
+const BIN = path.join(PLUGIN_DIR, 'bin', 'cloudbase-sites');
+
+const tempDirs = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makeTempDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cloudbase-sites-test-'));
+  const realDir = fs.realpathSync(dir);
+  tempDirs.push(realDir);
+  return realDir;
+}
+
+function writeAppJson(cwd, app) {
+  const stateDir = path.join(cwd, '.cloudbase-sites');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'app.json'), JSON.stringify(app, null, 2));
+}
+
+async function importPluginModule(relativePath, cwd) {
+  const previous = process.cwd();
+  process.chdir(cwd);
+  try {
+    const url = pathToFileURL(path.join(PLUGIN_DIR, relativePath));
+    url.search = `?t=${Date.now()}-${Math.random()}`;
+    return await import(url.href);
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+describe('CloudBase Sites Codex plugin packaging', () => {
+  test('provides a Codex plugin manifest that references skills and MCP config', () => {
+    const manifestPath = path.join(PLUGIN_DIR, '.codex-plugin', 'plugin.json');
+    expect(fs.existsSync(manifestPath)).toBe(true);
+
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    expect(manifest.name).toBe('cloudbase-sites');
+    expect(manifest.skills).toBe('./skills/');
+    expect(manifest.mcpServers).toBe('./.mcp.json');
+    expect(manifest.interface.displayName).toBe('CloudBase Sites');
+    expect(manifest.interface.defaultPrompt.length).toBeLessThanOrEqual(3);
+  });
+});
+
+describe('CloudBase Sites runtime state paths', () => {
+  test('uses .cloudbase-sites for project-local state', async () => {
+    const cwd = makeTempDir();
+    const state = await importPluginModule('lib/preview-state.mjs', cwd);
+
+    expect(state.STATE_DIR).toBe(path.join(cwd, '.cloudbase-sites'));
+    expect(state.LOG_DIR).toBe(path.join(cwd, '.cloudbase-sites', 'logs'));
+    expect(state.PREVIEW_JSON).toBe(path.join(cwd, '.cloudbase-sites', 'preview.json'));
+  });
+
+  test('uses ~/.cloudbase-sites for machine-level registry state', async () => {
+    const cwd = makeTempDir();
+    const registry = await importPluginModule('lib/registry.mjs', cwd);
+
+    expect(registry.GLOBAL_DIR).toBe(path.join(os.homedir(), '.cloudbase-sites'));
+    expect(registry.REGISTRY_PATH).toBe(path.join(os.homedir(), '.cloudbase-sites', 'registry.json'));
+    expect(registry.SUPERVISOR_STATE_PATH).toBe(path.join(os.homedir(), '.cloudbase-sites', 'supervisor.json'));
+  });
+});
+
+describe('CloudBase Sites CLI behavior', () => {
+  test('status is a non-recursive alias for preview --status', () => {
+    const cwd = makeTempDir();
+    const result = spawnSync(process.execPath, [BIN, 'status'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.status).toBe(5);
+    const payload = JSON.parse(result.stdout.trim().split('\n')[0]);
+    expect(payload.ok).toBe(true);
+    expect(payload.running).toBe(false);
+    expect(result.stderr).toContain('no preview');
+  });
+});
+
+describe('CloudBase Sites deploy version isolation', () => {
+  test('deploy stashes dirty edits even when HEAD already matches the saved version', () => {
+    const cwd = makeTempDir();
+    spawnSync('git', ['init'], { cwd, encoding: 'utf8' });
+    spawnSync('git', ['config', 'user.email', 'test@example.com'], { cwd, encoding: 'utf8' });
+    spawnSync('git', ['config', 'user.name', 'CloudBase Sites Test'], { cwd, encoding: 'utf8' });
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({
+      scripts: {
+        build: 'node -e "require(\'fs\').mkdirSync(\'dist\', { recursive: true }); require(\'fs\').copyFileSync(\'src.txt\', \'dist/index.html\')"',
+      },
+      dependencies: {
+        react: '1.0.0',
+        vite: '1.0.0',
+      },
+    }, null, 2));
+    fs.writeFileSync(path.join(cwd, 'src.txt'), 'saved version');
+    fs.writeFileSync(path.join(cwd, '.gitignore'), '.cloudbase-sites/\ndist/\n');
+    spawnSync('git', ['add', '.'], { cwd, encoding: 'utf8' });
+    spawnSync('git', ['commit', '-m', 'initial'], { cwd, encoding: 'utf8' });
+    const commitSha = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8' }).stdout.trim();
+    writeAppJson(cwd, {
+      siteName: 'demo-site',
+      cwd,
+      versions: [{ n: 1, commitSha, label: 'saved', savedAt: 'now', status: 'saved' }],
+      deployments: [],
+      currentVersion: 1,
+      currentDeploy: null,
+    });
+
+    fs.writeFileSync(path.join(cwd, 'src.txt'), 'unsaved edit');
+    fs.mkdirSync(path.join(cwd, 'dist'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, 'dist', 'index.html'), 'previous build');
+    const result = spawnSync(
+      process.execPath,
+      [BIN, 'deploy', '--version', '1', '--skip-build'],
+      { cwd, encoding: 'utf8', timeout: 5000 },
+    );
+
+    expect(result.status).toBe(0);
+    const payload = JSON.parse(result.stdout.trim().split('\n')[0]);
+    expect(payload.ok).toBe(true);
+    expect(payload.checkout).toMatchObject({
+      checked: true,
+      dirty: true,
+      stashed: true,
+      commitSha,
+    });
+    expect(fs.readFileSync(path.join(cwd, 'src.txt'), 'utf8')).toBe('saved version');
+    const stashList = spawnSync('git', ['stash', 'list'], { cwd, encoding: 'utf8' }).stdout;
+    expect(stashList).toContain('cloudbase-sites pre-deploy version 1');
+  });
+});
+
+describe('CloudBase Sites deployment metadata', () => {
+  test('deploy --post rejects guessed CloudBase service domains', async () => {
+    const cwd = makeTempDir();
+    writeAppJson(cwd, {
+      siteName: 'demo-site',
+      cwd,
+      versions: [{ n: 1, commitSha: 'abc1234', label: 'first', savedAt: 'now', status: 'saved' }],
+      deployments: [],
+      currentVersion: 1,
+      currentDeploy: null,
+    });
+
+    const result = spawnSync(
+      process.execPath,
+      [BIN, 'deploy', '--post', '--version', '1', '--access-url', 'https://demo-site.service.tcloudbase.com', '--build-id', 'build-123'],
+      { cwd, encoding: 'utf8', timeout: 5000 },
+    );
+
+    expect(result.status).toBe(1);
+    const payload = JSON.parse(result.stdout.trim().split('\n')[0]);
+    expect(payload.ok).toBe(false);
+    expect(payload.message).toContain('queryApps(action="getApp")');
+    expect(payload.message).toContain('.webapps.tcloudbase.com');
+  });
+
+  test('deploy --post accepts CloudBase Sites app domains', async () => {
+    const cwd = makeTempDir();
+    writeAppJson(cwd, {
+      siteName: 'demo-site',
+      cwd,
+      versions: [{ n: 1, commitSha: 'abc1234', label: 'first', savedAt: 'now', status: 'saved' }],
+      deployments: [],
+      currentVersion: 1,
+      currentDeploy: null,
+    });
+
+    const result = spawnSync(
+      process.execPath,
+      [BIN, 'deploy', '--post', '--version', '1', '--access-url', 'https://demo-site-env.webapps.tcloudbase.com/', '--build-id', 'build-123'],
+      { cwd, encoding: 'utf8', timeout: 5000 },
+    );
+
+    expect(result.status).toBe(0);
+    const payload = JSON.parse(result.stdout.trim().split('\n')[0]);
+    expect(payload.ok).toBe(true);
+    expect(payload.accessUrl).toBe('https://demo-site-env.webapps.tcloudbase.com');
+  });
+
+  test('records CloudBase build metadata in deployment entries', async () => {
+    const cwd = makeTempDir();
+    const appStore = await importPluginModule('lib/app-store.mjs', cwd);
+    appStore.writeApp({
+      siteName: 'demo-site',
+      cwd,
+      versions: [{ n: 1, commitSha: 'abc1234', label: 'first', savedAt: 'now', status: 'saved' }],
+      deployments: [],
+      currentVersion: 1,
+      currentDeploy: null,
+    });
+
+    const deployment = appStore.appendDeployment({
+      version: 1,
+      accessUrl: 'https://demo.example.com',
+      buildId: 'build-123',
+      versionName: 'v-001',
+      buildStatus: 'SUCCESS',
+      finalUrl: 'https://demo.example.com?v=abc123',
+    });
+
+    expect(deployment.buildId).toBe('build-123');
+    expect(deployment.versionName).toBe('v-001');
+    expect(deployment.buildStatus).toBe('SUCCESS');
+
+    const saved = appStore.readApp();
+    expect(saved.deployments[0]).toMatchObject({
+      buildId: 'build-123',
+      versionName: 'v-001',
+      buildStatus: 'SUCCESS',
+    });
+  });
+});