fix: route windows start through cross-platform entry

README.md

@@ -87,7 +87,7 @@ pnpm build
 # 4. Configure — add at least one model API key
 cp .env.example .env
 
-# 5. Start (auto-creates runtime worktree, starts Redis + API + Frontend)
+# 5. Start
 pnpm start
 
 # Pin to a specific release? Use start:direct instead (won't auto-update):
@@ -102,7 +102,12 @@ pnpm stop
 
 Open `http://localhost:3003` and start talking to your team.
 
-> **One-line alternative (Linux):** `bash scripts/install.sh` handles Node, pnpm, Redis, dependencies, `.env`, and first launch in one step. Options: `--start` (auto-start), `--memory` (skip Redis), `--registry=URL` (custom npm mirror). On **Windows**, use `scripts/install.ps1` then `scripts/start-windows.ps1`.
+`pnpm start` launches the local Clowder services: Redis (unless using `--memory`), API, and Frontend.
+
+On Unix-like systems, `pnpm start` uses the runtime worktree flow (auto-sync + isolated runtime checkout).
+On Windows, `pnpm start` dispatches to `scripts/start-windows.ps1` and starts from the current checkout.
+
+> **One-line alternative (Linux):** `bash scripts/install.sh` handles Node, pnpm, Redis, dependencies, `.env`, and first launch in one step. Options: `--start` (auto-start), `--memory` (skip Redis), `--registry=URL` (custom npm mirror). On **Windows**, use `scripts/install.ps1`, then either `pnpm start` or `scripts/start-windows.ps1`.
 
 **Full setup guide** (API keys, CLI auth, voice, Feishu/Telegram, troubleshooting): **[SETUP.opensource.md](SETUP.opensource.md)**
 

README.zh-CN.md

@@ -81,7 +81,7 @@ pnpm build
 # 4. 配置 — 至少添加一个模型 API key
 cp .env.example .env
 
-# 5. 启动（自动创建运行时 worktree，启动 Redis + API + 前端）
+# 5. 启动
 pnpm start
 
 # 想固定在某个版本？用 start:direct（不会自动更新）：
@@ -96,7 +96,12 @@ pnpm stop
 
 打开 `http://localhost:3003`，开始和你的团队对话。
 
-> **一键替代方案（Linux）：** `bash scripts/install.sh` 一步搞定 Node、pnpm、Redis、依赖、`.env` 和首次启动。可选参数：`--start`（自动启动）、`--memory`（跳过 Redis）、`--registry=URL`（国内镜像）。**Windows** 用户请使用 `scripts/install.ps1`，然后 `scripts/start-windows.ps1`。
+`pnpm start` 会启动本地 Clowder 服务：Redis（使用 `--memory` 时除外）、API 和前端。
+
+在 Unix-like 系统上，`pnpm start` 会走 runtime worktree 流程（自动同步 + 隔离运行时 checkout）。
+在 Windows 上，`pnpm start` 会转到 `scripts/start-windows.ps1`，并直接在当前 checkout 启动。
+
+> **一键替代方案（Linux）：** `bash scripts/install.sh` 一步搞定 Node、pnpm、Redis、依赖、`.env` 和首次启动。可选参数：`--start`（自动启动）、`--memory`（跳过 Redis）、`--registry=URL`（国内镜像）。**Windows** 用户请使用 `scripts/install.ps1`，然后用 `pnpm start` 或 `scripts/start-windows.ps1` 启动。
 
 **完整安装指南**（API key 配置、CLI 认证、语音、飞书/Telegram、常见问题）：**[SETUP.opensource.zh-CN.md](SETUP.opensource.zh-CN.md)**
 

SETUP.md

@@ -36,15 +36,24 @@ pnpm start
 #   pnpm start:direct
 ```
 
-`pnpm start` uses the **runtime worktree** architecture: it creates an isolated `../cat-cafe-runtime` worktree (on first run), syncs it to `origin/main`, builds, starts Redis, and launches Frontend (port 3003) + API (port 3004). This keeps your development checkout clean.
+On Unix-like systems, `pnpm start` uses the **runtime worktree** architecture: it creates an isolated `../cat-cafe-runtime` worktree (on first run), syncs it to `origin/main`, builds, starts Redis, and launches Frontend (port 3003) + API (port 3004). This keeps your development checkout clean.
 
-> **Tip:** If `pnpm start` fails because `../cat-cafe-runtime` already exists, use `pnpm start:direct` instead — it runs directly in your current checkout without creating a worktree. You can also set a custom path: `CAT_CAFE_RUNTIME_DIR=../my-runtime pnpm start`.
+On Windows, `pnpm start` dispatches to `scripts/start-windows.ps1` and starts from the current checkout instead of creating/syncing a runtime worktree.
+
+> **Tip (Unix-like):** If `pnpm start` fails because `../cat-cafe-runtime` already exists, use `pnpm start:direct` instead — it runs directly in your current checkout without creating a worktree. You can also set a custom path: `CAT_CAFE_RUNTIME_DIR=../my-runtime pnpm start`.
 
 Open `http://localhost:3003` and start talking to your team.
 
-> **Alternative — One-line installer (Linux):** `bash scripts/install.sh` handles Node, pnpm, Redis, dependencies, `.env`, and first launch in one step. On **Windows**, use `scripts/install.ps1` then `scripts/start-windows.ps1`.
+> **Alternative — One-line installer (Linux):** `bash scripts/install.sh` handles Node, pnpm, Redis, dependencies, `.env`, and first launch in one step. On **Windows**, use `scripts/install.ps1` then either `pnpm start` or `scripts/start-windows.ps1`.
+
+## How `pnpm start` Works
+
+Platform behavior differs:
+
+- Unix-like systems: `pnpm start` uses the runtime worktree flow.
+- Windows: `pnpm start` forwards to `scripts/start-windows.ps1` and starts from the current checkout.
 
-## How `pnpm start` Works (Runtime Worktree)
+### Unix-like: Runtime Worktree
 
 Clowder uses a **runtime worktree** to keep your dev checkout clean:
 
@@ -73,7 +82,7 @@ First run creates `../cat-cafe-runtime` automatically. Subsequent runs do a fast
 
 ## Running a Specific Version (Without Auto-Update)
 
-By default, `pnpm start` auto-syncs to the latest `origin/main`. If you want to **stay on a specific release** — for stability, reproducibility, or because you're not ready to update — use `pnpm start:direct` instead.
+On Unix-like systems, `pnpm start` auto-syncs to the latest `origin/main`. If you want to **stay on a specific release** — for stability, reproducibility, or because you're not ready to update — use `pnpm start:direct` instead.
 
 ### Option 1: Checkout a Release Tag
 
@@ -120,7 +129,7 @@ pnpm start:direct -- --quick # Skip rebuild too
 
 > **Updating later:** When you're ready to update, simply `git fetch && git checkout v0.5.0` (or whichever new tag), then `pnpm install && pnpm build && pnpm start:direct`.
 
-## Background / Daemon Mode
+## Background / Daemon Mode (Unix-like)
 
 By default `pnpm start` runs in the foreground — if you close the terminal or SSH disconnects, the services stop. Use `--daemon` to run in the background:
 

SETUP.zh-CN.md

@@ -36,15 +36,24 @@ pnpm start
 #   pnpm start:direct
 ```
 
-`pnpm start` 使用**运行时 worktree** 架构：首次运行时自动创建隔离的 `../cat-cafe-runtime` worktree，同步到 `origin/main`，构建，启动 Redis，然后启动前端（端口 3003）+ API（端口 3004）。这样你的开发目录保持干净。
+在 Unix-like 系统上，`pnpm start` 使用**运行时 worktree** 架构：首次运行时自动创建隔离的 `../cat-cafe-runtime` worktree，同步到 `origin/main`，构建，启动 Redis，然后启动前端（端口 3003）+ API（端口 3004）。这样你的开发目录保持干净。
 
-> **提示：** 如果 `pnpm start` 因为 `../cat-cafe-runtime` 已存在而失败，改用 `pnpm start:direct` — 直接在当前目录启动，不创建 worktree。也可以自定义路径：`CAT_CAFE_RUNTIME_DIR=../my-runtime pnpm start`。
+在 Windows 上，`pnpm start` 会转到 `scripts/start-windows.ps1`，直接在当前 checkout 启动，而不会创建或同步 runtime worktree。
+
+> **提示（Unix-like）：** 如果 `pnpm start` 因为 `../cat-cafe-runtime` 已存在而失败，改用 `pnpm start:direct` — 直接在当前目录启动，不创建 worktree。也可以自定义路径：`CAT_CAFE_RUNTIME_DIR=../my-runtime pnpm start`。
 
 打开 `http://localhost:3003`，开始和你的团队对话。
 
-> **替代方案 — 一键安装（Linux）：** `bash scripts/install.sh` 一步搞定 Node、pnpm、Redis、依赖、`.env` 和首次启动。**Windows** 用户请使用 `scripts/install.ps1`，然后 `scripts/start-windows.ps1`。
+> **替代方案 — 一键安装（Linux）：** `bash scripts/install.sh` 一步搞定 Node、pnpm、Redis、依赖、`.env` 和首次启动。**Windows** 用户请使用 `scripts/install.ps1`，然后用 `pnpm start` 或 `scripts/start-windows.ps1` 启动。
+
+## `pnpm start` 的工作原理
+
+不同平台的行为不同：
+
+- Unix-like 系统：`pnpm start` 走 runtime worktree 流程。
+- Windows：`pnpm start` 转发到 `scripts/start-windows.ps1`，直接在当前 checkout 启动。
 
-## `pnpm start` 的工作原理（运行时 Worktree）
+### Unix-like：运行时 Worktree
 
 Clowder 使用**运行时 worktree** 保持开发目录干净：
 
@@ -73,7 +82,7 @@ your-projects/
 
 ## 运行指定版本（不自动更新）
 
-默认情况下，`pnpm start` 会自动同步到最新的 `origin/main`。如果你想**停留在某个特定版本** — 为了稳定性、可复现性，或者暂时不想更新 — 请使用 `pnpm start:direct`。
+在 Unix-like 系统上，`pnpm start` 会自动同步到最新的 `origin/main`。如果你想**停留在某个特定版本** — 为了稳定性、可复现性，或者暂时不想更新 — 请使用 `pnpm start:direct`。
 
 ### 方式一：Checkout 到某个 Release Tag
 
@@ -120,7 +129,7 @@ pnpm start:direct -- --quick # 也跳过重编译
 
 > **后续更新：** 准备好更新时，执行 `git fetch && git checkout v0.5.0`（或者新版本 tag），然后 `pnpm install && pnpm build && pnpm start:direct` 即可。
 
-## 后台 / Daemon 模式
+## 后台 / Daemon 模式（Unix-like）
 
 默认情况下 `pnpm start` 在前台运行 — 关闭终端或 SSH 断开后服务会停止。使用 `--daemon` 可以在后台运行：
 

package.json

@@ -7,7 +7,7 @@
     "init": "./scripts/init-cafe.sh",
     "gate": "bash ./scripts/pre-merge-check.sh",
     "guards:install": "bash ./scripts/install-git-guards.sh",
-    "start": "./scripts/runtime-worktree.sh start",
+    "start": "node ./scripts/start-entry.mjs start",
     "stop": "./scripts/start-dev.sh --stop",
     "start:status": "./scripts/start-dev.sh --status",
     "start:direct": "node ./scripts/start-entry.mjs start:direct --profile=production",