firstintent · firstintent · May 24, 2026 · May 24, 2026
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
diff --git a/.mcp.json b/.mcp.json
@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "ccteam": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/index.js"]
+      "command": "ccteam",
+      "args": ["mcp-serve"]
     }
   }
 }
diff --git a/README.md b/README.md
@@ -26,48 +26,47 @@ Not sure? Just describe it in natural language   /ccteam "<what you want>"
 
 ## Get started
 
-### Install (Claude Code or Codex)
+```bash
+# 0. Install Claude Code first: https://code.claude.com/docs/install
 
-Inside any Claude Code session:
+# 1. Install the ccteam CLI binary (one line, no Rust toolchain needed):
+curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh
+#    Installs to ~/.local/bin/ccteam. The script prints a PATH-export
+#    hint if that directory isn't on your PATH yet — follow it, then
+#    restart your shell (or `source ~/.bashrc` / `source ~/.zshrc`).
+#    Pin a specific release tag: CCTEAM_VERSION=<tag> curl ... | sh
+#    Install system-wide:        CCTEAM_INSTALL_DIR=/usr/local/bin curl ... | sh
+#    Or download an archive from https://github.com/firstintent/ccteam/releases
+#    Build from source instead (requires Rust 1.85+):
+#      cargo install --git https://github.com/firstintent/ccteam ccteam-cli
+
+# 2. Inside any Claude session, register the marketplace + install the plugin:
+claude
+```
 
 ```
 /plugin marketplace add https://github.com/firstintent/ccteam
 /plugin install ccteam
 ```
 
-Inside any Codex session:
-
-```
-codex plugin marketplace add firstintent/ccteam
-```
-
-The plugin auto-downloads the Rust engine into its own sandbox on the first MCP invocation — no system-wide binary required, no Rust toolchain, no separate install step. A Node.js bridge (`index.js`) ships in the repo, detects the host (Claude vs Codex), pulls the matching prebuilt tarball from GitHub Releases, and execs `ccteam mcp-serve` under the covers. It also symlinks the binary to `~/.local/bin/ccteam` so the CLI is available from any terminal.
-
-### Use it
-
 ```
-# Universal entry — describe what you want in any language:
+# 3. Try the universal entry — describe what you want in any language:
 /ccteam "scan this repo and tell me what it does"
 /ccteam "fix the TypeScript errors in src/"
 /ccteam "build a Telegram bot that summarizes my GitHub PRs at 7am"
 
-# (Optional) Bootstrap a per-project workflow scaffold from the CLI:
+# 4. (Optional) Bootstrap a per-project workflow scaffold from the CLI:
 ccteam init <project>
 ```
 
-Supported platforms for the prebuilt binary: Linux x86_64, macOS arm64 (Apple Silicon), macOS x86_64 (Intel). Windows users: install via WSL2 and use the linux-x64 binary — native Windows isn't supported because tmux + inotify + POSIX signals are foundational to ccteam. On macOS, if Gatekeeper blocks the binary on first run: `xattr -d com.apple.quarantine ~/.local/bin/ccteam`.
-
-The plugin install registers the seven `/ccteam*` slash commands and `mcp__ccteam__*` MCP tools — they light up immediately. The 5-minute walkthrough for "private IM assistant" (the flagship use case) lives in [docs/quickstart.md](docs/quickstart.md).
-
-### Advanced: system-wide CLI without the plugin
-
-If you want `ccteam` on `$PATH` for daemon use (`ccteam start`) without going through a Claude or Codex session — for example on a headless server — install the binary directly:
-
-```bash
-curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh
-```
+Supported platforms for the prebuilt binary: Linux x86_64, macOS arm64
+(Apple Silicon), macOS x86_64 (Intel). Windows users: install via WSL2
+and use the linux-x64 binary — native Windows isn't supported because
+tmux + inotify + POSIX signals are foundational to ccteam. On macOS,
+if Gatekeeper blocks the binary on first run:
+`xattr -d com.apple.quarantine ~/.local/bin/ccteam`.
 
-Pin a tag: `CCTEAM_VERSION=<tag> curl ... | sh`. System-wide: `CCTEAM_INSTALL_DIR=/usr/local/bin curl ... | sh`. Or build from source: `cargo install --git https://github.com/firstintent/ccteam ccteam-cli` (Rust 1.85+).
+Step 2 registers ccteam as a Claude Code plugin marketplace, then installs the plugin — the seven `/ccteam*` slash commands and `mcp__ccteam__*` MCP tools light up immediately. The 5-minute walkthrough for "private IM assistant" (the flagship use case) lives in [docs/quickstart.md](docs/quickstart.md).
 
 ## Three ways to talk to ccteam
 

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -116,67 +116,62 @@ ccteam probe-project --json    # 看 ccteam 怎么"看"你的仓库
 
 ## Step 1 — 装 ccteam plugin(30 秒)
 
-ccteam 走 Claude Code(或 Codex)官方 plugin 协议安装 —— **plugin 是首选**且唯一**必需**的入口。plugin 自带 Node.js bridge(`index.js`),首次在 MCP server 启动时探测宿主、按平台从 GitHub Release 拉对应 binary 到 plugin sandbox 内,然后 `exec ccteam mcp-serve`。**不需要预先装 CLI binary**(bridge 会顺手把 binary symlink 到 `~/.local/bin/ccteam`,所以装完 plugin 终端也直接能跑 `ccteam start`)。
+ccteam 走 Claude Code 官方 plugin marketplace 协议安装 —— **plugin 是首选路径**,CLI binary 作为前置条件先装好(plugin 通过 MCP 调用本机 `ccteam` 命令)。
 
-### 1.1 在 Claude session 里注册 marketplace + 装 plugin
+### 1.1 装 CLI binary(前置,一次性)
 
-任意 terminal 起 Claude session:
+**首选 ── 一行装预编译 binary(不需要 Rust toolchain):**
 
 ```bash
-$ claude
-```
-
-在 session 里依次输入:
-
-```
-/plugin marketplace add https://github.com/firstintent/ccteam
-/plugin install ccteam
-```
-
-预期输出:
-
-```
-✓ Installed ccteam
-  • slash commands registered: /ccteam, /ccteam-team, /ccteam-creator, /ccteam-control, /ccteam-im-setup, /ccteam-scan, /ccteam-advise
-  • mcp__ccteam__* tools available (workflow_* / chat_* / advise_* / admin_* / screenshot_*)
+curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh
+ccteam --version    # 应输出当前版本号
 ```
 
-首次调用任意 `mcp__ccteam__*` tool 时,`index.js` 会从 GitHub Release 拉对应平台的 tarball(linux-x64 / macos-arm64 / macos-x64),解压到 `${PLUGIN_ROOT}/bin/ccteam`,chmod +x,并 symlink 到 `~/.local/bin/ccteam`。第二次起秒启。
-
-跑 `ccteam doctor` 验装(claude CLI / MCP / tmux / pidfile 路径都查一遍);加 `--verify-mcp` 自检 MCP 工具表面齐全(应输出 `27 active, 0 stubs`,非零 exit 即 CI gate fail);加 `--check-codex-auto-critic` 验证 Codex 二审是否能开;加 `--check-cost-orphan` 对账 24h 内 ledger 与 progress.jsonl(catch spawn 路径漏写 ledger)。
+默认装到 `~/.local/bin/ccteam`。装完如果该路径不在 `$PATH`,脚本会打印一行 export 指令(贴进 `~/.bashrc` / `~/.zshrc` 再 `source` 即可)。
 
 支持的平台:Linux x86_64、macOS arm64(Apple Silicon)、macOS x86_64(Intel)。Windows 用户走 WSL2 + linux-x64 binary —— native Windows 不支持(tmux + inotify + POSIX signals 是 ccteam 架构根基)。
 
+环境变量:
+- `CCTEAM_INSTALL_DIR=/usr/local/bin sh install.sh` —— 改装目录(系统级安装)
+- `CCTEAM_VERSION=v0.6.6 sh install.sh` —— 装指定 tag(不取 latest)
+
 macOS Gatekeeper 拦截(首次跑报"not verified developer"):
 ```bash
 xattr -d com.apple.quarantine ~/.local/bin/ccteam
 ```
 
-### 1.2 Codex 用户
+**回退 ── 从源码 build(需要 Rust 1.85+,5-15 min 编译):**
 
-```
-codex plugin marketplace add firstintent/ccteam
+```bash
+cargo install --git https://github.com/firstintent/ccteam ccteam-cli
 ```
 
-同一仓库同时是 Codex plugin。Bridge 通过 `CODEX_ACTIVE` env 嗅探宿主,自动选择走 Codex 路径。
+新机器没装 Rust 时,先 `curl https://sh.rustup.rs -sSf | sh` 装 rustup,然后再跑上面这条。
 
-### 1.3 高级:不走 plugin,直接装 system-wide CLI(可选)
+### 1.2 在 Claude session 里注册 marketplace + 装 plugin
 
-只想在终端 / 服务器跑 `ccteam start` daemon、不打算用 Claude/Codex skill 路径时:
+任意 terminal 起 Claude session:
 
 ```bash
-curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh
-ccteam --version    # 应输出当前版本号
+$ claude
 ```
 
-默认装到 `~/.local/bin/ccteam`。装完如果该路径不在 `$PATH`,脚本会打印一行 export 指令。环境变量:
-- `CCTEAM_INSTALL_DIR=/usr/local/bin sh install.sh` —— 改装目录(系统级安装)
-- `CCTEAM_VERSION=v0.6.6 sh install.sh` —— 装指定 tag(不取 latest)
+在 session 里依次输入:
 
-回退 ── 从源码 build(需要 Rust 1.85+,5-15 min 编译):
-```bash
-cargo install --git https://github.com/firstintent/ccteam ccteam-cli
 ```
+/plugin marketplace add https://github.com/firstintent/ccteam
+/plugin install ccteam
+```
+
+预期输出:
+
+```
+✓ Installed ccteam
+  • slash commands registered: /ccteam, /ccteam-team, /ccteam-creator, /ccteam-control, /ccteam-im-setup, /ccteam-scan, /ccteam-advise
+  • mcp__ccteam__* tools available (workflow_* / chat_* / advise_* / admin_* / screenshot_*)
+```
+
+跑 `ccteam doctor` 验装(claude CLI / MCP / tmux / pidfile 路径都查一遍);加 `--verify-mcp` 自检 MCP 工具表面齐全(应输出 `26 active, 0 stubs`,非零 exit 即 CI gate fail);加 `--check-codex-auto-critic` 验证 Codex 二审是否能开;加 `--check-cost-orphan` 对账 24h 内 ledger 与 progress.jsonl(catch spawn 路径漏写 ledger)。
 
 → 卡了?见 [troubleshooting.md](troubleshooting.md) "plugin install 失败"。
 

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -21,17 +21,7 @@
 ### A3. `/plugin install ccteam@claude-plugins-official` 失败
 **原因**:网络 / GitHub rate-limit / 已装同名 plugin 冲突。
 **修复**:1) `/plugin list` 看是否同名 → `/plugin remove ccteam` 重装;2) 走代理 / 国内镜像;3) 仍失败:手动 `git clone` 到 `~/.claude/plugins/marketplaces/`。
-**相关**:A4 / A5 / A3b。
-
-### A3b. plugin 装好了,首次调 `mcp__ccteam__*` 时下载 binary 卡住 / 失败
-**原因**:plugin 的 Node.js bridge(`index.js`)首次 MCP 启动会从 GitHub Release 拉对应平台的 tarball(`ccteam-vX.Y.Z-<linux-x64|macos-arm64|macos-x64>.tar.gz`)到 `${PLUGIN_ROOT}/bin/ccteam`。慢/失败常因:1) GitHub Release 不在 CDN 近端(国内裸连慢);2) plugin sandbox 写权限缺;3) 平台 mismatch(`tar` 不在 PATH / 平台未发布)。
-**修复**:1) bridge 启动日志走 host stderr,Claude session `/mcp` 看 ccteam 启动报错 / Codex 看 server log;2) 走代理:在拉起 Claude/Codex 的 shell 里 `export HTTPS_PROXY=...`;3) 跳过 bridge 下载、走传统 system-wide 安装:`curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh`,然后**临时把 `.mcp.json` 的 command 改回 `ccteam` + args `["mcp-serve"]`** 直至 bridge 路径修复;4) 国内裸连慢首次卡住 → 镜像 GH Release 到内网,把 `index.js` 里的下载 URL 改成镜像。版本严格对齐 `.claude-plugin/plugin.json::version`(SoT);Bridge 通过 `binary --version` 输出与之比对,不匹配会重下。
-**相关**:A3 / A4。
-
-### A3c. plugin 装好但终端 `ccteam --version` 报 command not found
-**原因**:bridge 首次 MCP 调用会把 `${PLUGIN_ROOT}/bin/ccteam` symlink 到 `~/.local/bin/ccteam`,但如果 `~/.local/bin/` 不在 `$PATH`,终端找不到。
-**修复**:1) Claude/Codex 里先调一次 `mcp__ccteam__chat_list_bots` 触发 bridge 下载 + symlink;2) `echo $PATH | grep -q "$HOME/.local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc`(zsh 改 `~/.zshrc`)再 `source` 一次。bridge symlink 失败时会在 stderr 打印 hint,通常因 `~/.local/bin/` 不可写。
-**相关**:A3b。
+**相关**:A4 / A5。
 
 ### A4. `/mcp` 列表里没 `mcp__ct__*` 工具
 **原因**:MCP 没注册到 `.mcp.json` 或 `~/.claude.json`,或 plugin 装完没 reload。