@moretea-labs/forge 1.5.0-rc.1 → 1.5.1

package/docs/tutorials/01-install-and-start.zh-CN.md

@@ -1,35 +1,35 @@
-# 教程 1：安装并启动
+# 教程 1：安装并选择主控
 
-本教程完成 CLI 安装、用户级运行时初始化、环境检查和第一个仓库注册。
+本教程把 Forge 从 package 安装带到可恢复的初始化流程。Forge **自己没有 AI 大脑**：始终由一个外部主控判断下一步，Forge 负责有边界的执行、持久状态、权限与证据。
 
-## 1. 平台与基础环境
+## 1. 选择平台路径
 
-- macOS / Linux：完整支持。
-- Windows：完整工作流推荐 WSL2。
-- Windows 原生 PowerShell：预览支持安装、doctor、仓库注册/读取和可移植 Controller 操作。
+- **macOS：** 支持；Package Runtime 使用 launchd 做用户级持久运行。
+- **现代 Linux：** 支持；优先使用 `systemd --user`，不可用时会明确退化为当前会话的 portable 模式。
+- **Windows + WSL2：** Windows 推荐路径；在 WSL2 内按 Linux 流程运行。
+- **Windows 原生：** 预览；支持 CLI、setup、portable Runtime、MCP 和有边界的可移植能力，但暂不宣称重启后 Runtime 持久化与所有 Provider 组合都完整支持。
 
-需要 Git、Node.js 20.10 或更高版本、npm 和可写的用户目录。Bun 1.0+ 是可选项，推荐用于源码开发和完整测试。
+基础安装只需要 **Node.js 20.10 或更高版本**、npm（或 Bun）和可写用户目录。**Git 只在启用仓库/软件开发能力时才需要。** Codex、Claude、`gh`、Cloudflare、Tailscale、CodeGraph 和各服务账号都是按能力选装，不是 Forge 的安装前置条件。
 
 ```bash
-git --version
 node --version
 npm --version
 ```
 
 详细范围见[平台支持说明](../operations/platform-support.zh-CN.md)。
 
-## 2. 安装 CLI
+## 2. 安装 Forge
 
-发布候选版本使用 npm 的 `next` channel：
+Release Candidate 使用 npm `next`：
 
 ```bash
-npm install -g @moretea-labs/forge@next
+npm install -g @moretea-labs/forge
 # 或
-bun add -g @moretea-labs/forge@next
+bun add -g @moretea-labs/forge
 forge --version
 ```
 
-需要参与 Forge 源码开发时，再从仓库安装：
+只有参与 Forge 源码开发时才需要源码安装：
 
 ```bash
 git clone https://github.com/moretea-labs/forge.git
@@ -38,56 +38,79 @@ npm ci --ignore-scripts --no-audit --no-fund
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 
-该 package 只提供 `forge`、`forge-hook` 与 `forge-runtime`。候选版本使用 `next`，稳定版本使用 `latest`。
+发布 package 提供 `forge`、`forge-hook`、`forge-runtime`。普通 package 用户启动用户级 Runtime **不需要** Forge Git checkout、Bun 编译、CodeGraph 或 Standalone Recovery。
 
-## 3. 打开引导式配置会话
+## 3. 开始引导式 setup
 
 ```bash
-forge --version
-forge setup open --target both
+forge setup
 ```
 
-`forge setup open` 会在 `~/.forge/setup/` 下创建或恢复同一个用户级配置会话，执行就绪检查，并且每次只给出一个下一步配置动作。完成该动作后继续执行：
+首次执行会先选择外部主控。推荐 ChatGPT，但不是强制：
 
 ```bash
-forge setup next
+forge setup configure --controller chatgpt --tunnel auto
+# 也可以：
+# forge setup configure --controller codex
+# forge setup configure --controller claude
+# forge setup configure --controller mcp
 ```
 
-反复执行 `forge setup next`，直到状态变成 `ready`，然后关闭会话：
+可以预配置多个控制入口，但只有一个 primary controller：
 
 ```bash
-forge setup close
+forge setup configure \
+  --controller chatgpt \
+  --add-controller codex \
+  --add-controller claude \
+  --tunnel auto
 ```
 
-可使用 `forge setup status` 查看持久化进度，使用 `forge setup check` 获取一次性只读报告。只使用一个 host 时可改为 `--target codex` 或 `--target claude`。配置会话不会静默执行远程写入、读取秘密、破坏性操作或服务安装。
+机器上即使已经安装 Codex/Claude，只要没有明确选择，Forge 就不会把它们当成 readiness 依赖。
+
+## 4. 每次只完成一个 Next 动作
+
+```bash
+forge setup next
+```
+
+setup 进度保存在用户级 Forge 目录，可以退出终端后继续。根据主控类型，流程会依次处理：
+
+1. 主控注册；
+2. Package Runtime；
+3. 远程主控需要的安全 HTTPS；
+4. 只能由用户完成的登录/浏览器认证；
+5. 连接验证。
 
-## 4. 接入或注册仓库
+`forge setup status` 查看持久化进度；`forge setup check` 只读检查；ready 后使用 `forge setup close`。
 
-macOS、Linux、WSL2 先预览再执行完整接入：
+普通用户的 Runtime 路径是：
 
 ```bash
-forge adopt --repo /path/to/your-project --dry-run
-forge adopt --repo /path/to/your-project
+forge runtime service install-package
 ```
 
-所有平台均可显式注册：
+对 ChatGPT，package 安装会同时维护两个本地服务边界：内部 bearer-only Canonical Runtime，以及供 Secure Tunnel/HTTPS connector 使用的 loopback OAuth Gateway。不要把 tunnel 直接指向内部 Runtime 端口，以 setup 输出的本地 OAuth endpoint 为准。
+
+旧的 `forge runtime service install --repo ...` 会构建 Git/source immutable Runtime，属于**高级维护路径**；Standalone Recovery 同样不是普通用户初始化的前置条件。
+
+## 5. 首次 setup 不要求仓库
+
+只使用授权目录、浏览器/桌面或服务插件时，不需要先 adopt Git 仓库。需要软件开发能力时再接入项目：
 
 ```bash
-forge repo register /path/to/your-project --name my-project --json
+forge adopt --repo /path/to/your-project --dry-run
+forge adopt --repo /path/to/your-project
 forge repo list --json
 ```
 
-保存返回的 `repoId`，它是 ChatGPT 和 Controller 使用的稳定仓库身份。
+从这一步开始，仓库工作流才需要 Git。
 
-## 5. 确认环境就绪
+## 6. 验证基础环境
 
 ```bash
 forge setup status
 forge doctor
-forge status --json
-forge repo list --json
 ```
 
-运行态应保存在 Controller Home 和被忽略的仓库链接中，不应进入公开源码。不要提交 token、MCP runtime 文件、Local Job、日志或 worktree。
-
-下一步阅读[教程 2：连接 ChatGPT](02-connect-chatgpt.zh-CN.md)，出现问题时看[故障排查](../operations/troubleshooting.zh-CN.md)。
+选择 ChatGPT 做主控时，继续阅读[教程 2：连接 ChatGPT](02-connect-chatgpt.zh-CN.md)。出现问题时看[故障排查](../operations/troubleshooting.zh-CN.md)。

package/docs/tutorials/02-connect-chatgpt.md

@@ -1,82 +1,154 @@
 # Tutorial 2: Connect ChatGPT
 
-This tutorial starts the local MCP service, publishes only its MCP endpoint through HTTPS, and verifies the default facade tools.
+This tutorial connects ChatGPT as the external controller for Forge. Forge stays local and loopback-bound; ChatGPT reaches it through either OpenAI Secure MCP Tunnel or an explicitly chosen HTTPS tunnel.
 
-## 1. Before you start
+## 1. Check ChatGPT availability first
 
-You need:
+ChatGPT MCP availability is controlled by your ChatGPT plan/workspace and can change independently of Forge. Check OpenAI's current [Developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) documentation before setup.
 
-- a repository already registered with `forge repo register`;
-- a healthy `forge doctor` result;
-- a stable public HTTPS address ending in `/mcp`;
-- ChatGPT access to Developer Mode and custom MCP connectors.
+At the time this guide was updated, full MCP including write/modify actions is a beta capability for ChatGPT Business, Enterprise, and Edu on web. Pro supports developer-mode MCP with read/fetch scope rather than full write MCP. Workspace administrators may also need to enable developer mode/RBAC.
 
-Coding agents are not required. Install Codex or Claude only when you intend to delegate implementation.
+Forge does not bypass those product permissions.
 
-Windows users should run the Controller and tunnel inside WSL2 for the full supported workflow. Native PowerShell operation remains preview scope.
+## 2. Let Forge prepare the local side
 
-## 2. Generate the MCP configuration
+Start or resume the user-level setup flow:
 
 ```bash
-forge mcp setup chatgpt --repo /path/to/your-project
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
 ```
 
-The local endpoint is loopback-only:
+Follow the single `Next` action until the local Package Runtime is ready. The normal user path uses:
+
+```bash
+forge mcp setup chatgpt --user-level
+forge runtime service install-package
+```
+
+The MCP listener remains loopback-only, normally:
 
 ```text
 http://127.0.0.1:8765/mcp
 ```
 
-Do not expose the local Controller UI at port 8766.
+Fresh user-level setup keeps the repository-centric Utility Console disabled until you configure a repository/workbench target. When enabled later it uses a separate loopback port (normally `8766`). **Never expose the Utility Console to the internet.**
+
+A repository is not required to connect ChatGPT. Add repositories, folders, browser capabilities, and service plugins later as needed.
+
+## 3. Choose the remote connection
 
-## 3. Verify the canonical Runtime service
+Run `forge setup next`. Forge supports these connection providers:
 
-`forge mcp setup chatgpt` installs or updates the configuration consumed by the single `forge-runtime`. Install the macOS service owner with `forge runtime service install`; launchd then owns startup and unexpected-exit restart of that one root process. There is no MCP KeepAlive wrapper or component-level lifecycle command.
+### A. OpenAI Secure MCP Tunnel — preferred when available
+
+Secure MCP Tunnel lets an OpenAI-hosted product reach the local MCP server through an outbound tunnel, without creating public inbound access. `--tunnel auto` treats this as the first-choice ChatGPT transport and does not silently choose Cloudflare/Tailscale merely because those CLIs are installed. See OpenAI's [Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) and the official [`openai/tunnel-client`](https://github.com/openai/tunnel-client).
+
+You need a tunnel ID and tunnel-use permission from OpenAI Platform. Record only the non-secret tunnel ID in Forge:
 
 ```bash
-forge runtime service install \
-  --controller-home /path/to/controller-home \
-  --repo /path/to/forge-source-or-runtime-root \
-  --host 127.0.0.1 \
-  --port 8765 \
-  --auth-token-file /path/to/controller-home/mcp/runtime-token
-forge runtime status --controller-home /path/to/controller-home --json
-forge mcp doctor --repo /path/to/your-project
+forge setup configure \
+  --controller chatgpt \
+  --tunnel openai \
+  --tunnel-id tunnel_0123456789abcdef0123456789abcdef
+forge setup next
 ```
 
-Publish only the configured loopback MCP endpoint through a stable Tailscale or Cloudflare HTTPS tunnel. Temporary tunnel URLs are suitable for testing but are poor long-lived Connector identities. Enable Codex or Claude only after their CLIs are installed and authenticated; provider availability does not change the Runtime process topology.
+Forge never asks for or stores the tunnel runtime API key. Keep it in the environment used by the official tunnel client:
 
-## 4. Add the Connector in ChatGPT
+```bash
+export CONTROL_PLANE_API_KEY='...'
+```
 
-1. Open **Settings → Apps & Connectors → Advanced settings**.
-2. Enable Developer Mode.
-3. Create a custom MCP Connector.
-4. Enter the public HTTPS URL ending in `/mcp`.
-5. Add the Connector to a new conversation.
+When `tunnel-client` is installed, setup guides the official supervised runtime path. Conceptually it is:
 
-## 5. Verify the safe default surface
+```bash
+tunnel-client runtimes connect \
+  --alias forge \
+  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
+  --runtime-api-key env:CONTROL_PLANE_API_KEY \
+  --mcp-server-url http://127.0.0.1:8767/mcp
 
-The core Connector should expose:
+tunnel-client runtimes status forge --json
+```
+
+Forge reports this provider ready only when `tunnel-client` reports the managed runtime as running, healthy, and ready.
+
+#### What address changes?
+
+With Secure Tunnel there is no public Forge `/mcp` address to paste. The ChatGPT App selects the `tunnel_id`; `tunnel-client` forwards commands to Forge's **loopback OAuth Gateway** (default `127.0.0.1:8767/mcp`), which proxies to the internal bearer-only Runtime (default `127.0.0.1:8765/mcp`). If you customize ports, use the OAuth endpoint printed by `forge mcp setup chatgpt --user-level`.
+
+The App/connector identity and Forge tool schema are separate from the transport. Switching from Cloudflare/HTTPS to Secure Tunnel changes the network path, not the 19-tool Forge schema. A fresh chat is useful for isolated A/B testing, but it is not required merely because transport changed when the same App is already connected.
 
-- `rh_status` — runtime and repository readiness;
-- `rh_context` — bounded context for the selected repository;
-- `rh_work` — start or continue bounded work;
-- `rh_inbox` — decisions, approvals, and items requiring attention.
+### B. Cloudflare Tunnel
 
-It also exposes a few repository bootstrap and selection tools. Do not switch to `full` merely to see more names; `advanced` and `full` are maintainer and compatibility surfaces.
+Choose this when you need a stable public HTTPS endpoint and control the Cloudflare account/domain:
 
-Test in this order:
+```bash
+forge setup configure --controller chatgpt --tunnel cloudflare
+forge setup next
+```
+
+Setup detects `cloudflared` and the current platform. On macOS it can suggest Homebrew when present; Linux/WSL2 and Windows receive their platform-specific official installation path. After creating a stable named tunnel, record only the resulting `/mcp` URL:
+
+```bash
+forge setup configure \
+  --controller chatgpt \
+  --tunnel existing \
+  --endpoint https://forge.example.com/mcp
+```
+
+### C. Tailscale Funnel
+
+If you already use Tailscale, choose:
+
+```bash
+forge setup configure --controller chatgpt --tunnel tailscale
+forge setup next
+```
+
+Forge detects the Tailscale CLI and guides Funnel setup for the current platform. Record the final HTTPS `/mcp` URL when available.
+
+### D. Existing HTTPS endpoint or defer
+
+```bash
+forge setup configure \
+  --controller chatgpt \
+  --tunnel existing \
+  --endpoint https://forge.example.com/mcp
+
+# Or keep local setup only for now:
+forge setup configure --controller chatgpt --tunnel none
+```
+
+Cloudflare/Tailscale/existing HTTPS make the MCP endpoint public or internet-reachable by design. OpenAI Secure MCP Tunnel is the private-outbound option when your OpenAI organization supports it.
+
+## 4. Create the ChatGPT app/connector
+
+The ChatGPT UI changes over time, so follow the current OpenAI developer-mode instructions rather than relying on screenshots in this repository.
+
+For a Secure MCP Tunnel connection, choose the **Tunnel** connection type and select/paste the tunnel ID. For an HTTPS connection, use the stable HTTPS URL ending in `/mcp` and the OAuth flow generated by Forge.
+
+After creating the app/connector, scan/refresh tools. Do not switch Forge to an exhaustive compatibility toolset simply to expose more names; the bounded default surface is intentional.
+
+## 5. Verify a real Forge call
+
+Start with a read-only prompt:
 
 ```text
-Use Forge. Check system readiness with rh_status. Then load bounded context for my registered repository with rh_context. Do not make changes yet.
+Use Forge. Call rh_status and tell me whether the Forge Runtime is ready.
+Do not modify anything yet.
 ```
 
-## 6. Security checks
+Then, after granting a repository or local folder, verify bounded context/read access. A successful setup means ChatGPT actually made a Forge tool call; a saved tunnel ID or a running local process alone is not proof of end-to-end connectivity.
+
+## 6. Security rules
 
-- Keep MCP bound to loopback and publish it only through a controlled HTTPS endpoint.
-- Keep the local UI private.
-- Start read-only, then authorize bounded writes when needed.
-- Remote Git, GitHub, email, destructive cleanup, and publication remain separately authorized.
-- Never paste MCP tokens or OAuth secrets into chat.
+- Keep Forge MCP and the Utility Console bound to loopback.
+- Prefer Secure MCP Tunnel when private outbound connectivity is available and appropriate.
+- If using a public HTTPS tunnel, expose only MCP—not the local Utility Console.
+- Never paste MCP tokens, OAuth secrets, tunnel runtime API keys, or admin keys into chat or Forge setup state.
+- Remote Git, GitHub, email, destructive cleanup, publication, and secret access remain separately authorized by Forge.
+- Codex/Claude are not installed or enabled unless you explicitly configure them as controller/execution entries.
 
-Continue with [Tutorial 3: First Repository Task](03-first-repository-task.md). Use [Troubleshooting](../operations/troubleshooting.md) if the Connector or tool surface is not healthy.
+Continue with [Tutorial 3: First Repository Task](03-first-repository-task.md) when you want software-work capabilities. Use [Troubleshooting](../operations/troubleshooting.md) when the Runtime, tunnel, connector, or tool surface is not healthy.

package/docs/tutorials/02-connect-chatgpt.zh-CN.md

@@ -1,80 +1,154 @@
 # 教程 2：连接 ChatGPT
 
-本教程启动本地 MCP 服务，只通过 HTTPS 公开 MCP endpoint，并验证默认 facade 工具。
+本教程把 ChatGPT 接成 Forge 的外部主控。Forge 和 MCP 仍只监听本机 loopback；ChatGPT 通过 OpenAI Secure MCP Tunnel，或用户明确选择的 HTTPS tunnel 访问它。
 
-## 1. 开始前需要
+## 1. 先确认 ChatGPT 当前支持范围
 
-- 已通过 `forge repo register` 注册仓库；
-- `forge doctor` 状态正常；
-- 一个稳定、以 `/mcp` 结尾的公网 HTTPS 地址；
-- ChatGPT Developer Mode 和自定义 MCP Connector 权限。
+ChatGPT 的 MCP 能力由套餐、工作区和管理员策略决定，会独立于 Forge 变化。开始前请查看 OpenAI 当前的[开发者模式和 MCP 应用](https://help.openai.com/zh-hans-cn/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt-beta)说明。
 
-编码 Agent 不是必需环境。只有准备委派实现时才安装 Codex 或 Claude。
+本文更新时，包含写入/修改的完整 MCP 正在 ChatGPT Business、Enterprise、Edu 网页版中以 beta 提供；Pro 的开发者模式 MCP 当前是 read/fetch 范围。工作区还可能要求管理员开启 Developer Mode / RBAC。
 
-Windows 用户建议在 WSL2 内运行 Controller 和隧道；Windows 原生 PowerShell 仍属于预览范围。
+Forge 不会绕过这些 ChatGPT 产品权限。
 
-## 2. 生成 MCP 配置
+## 2. 让 Forge 准备本地运行环境
 
 ```bash
-forge mcp setup chatgpt --repo /path/to/your-project
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
 ```
 
-本地 endpoint 只监听 loopback：
+每次只按一个 `Next` 动作继续。普通用户的本地路径最终会使用：
+
+```bash
+forge mcp setup chatgpt --user-level
+forge runtime service install-package
+```
+
+MCP 默认只监听：
 
 ```text
 http://127.0.0.1:8765/mcp
 ```
 
-不要把 8766 端口的本地 Controller UI 暴露到公网。
+首次 user-level setup 会保持 repository-centric Utility Console 关闭，直到你之后配置仓库/工作台目标；启用后它使用独立 loopback 端口（通常是 `8766`）。**不要把 Utility Console 暴露到公网。**
+
+连接 ChatGPT 不要求先注册 Git 仓库。仓库、普通目录、Browser、Gmail 等能力可以之后按需配置。
+
+## 3. 选择远程连接方式
+
+执行 `forge setup next`，Forge 支持以下 provider。
+
+### A. OpenAI Secure MCP Tunnel——有权限时优先
+
+Secure MCP Tunnel 通过出站连接把本机/private MCP 接到 OpenAI 托管产品，不要求给 Forge 开公网入站。 `--tunnel auto` 会把它作为 ChatGPT 的第一优先传输，不会仅仅因为机器上装了 cloudflared/Tailscale 就静默改用公网方案。详见 OpenAI 的 [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) 与官方 [`openai/tunnel-client`](https://github.com/openai/tunnel-client)。
+
+需要先在 OpenAI Platform 获得 tunnel ID 和使用权限。Forge 只记录**非秘密**的 tunnel ID：
+
+```bash
+forge setup configure \
+  --controller chatgpt \
+  --tunnel openai \
+  --tunnel-id tunnel_0123456789abcdef0123456789abcdef
+forge setup next
+```
+
+Forge 不要求、读取或保存 tunnel runtime API key。把它留在运行官方 tunnel-client 的环境中：
+
+```bash
+export CONTROL_PLANE_API_KEY='...'
+```
+
+安装 `tunnel-client` 后，setup 会引导官方的受管 runtime 路径，本质上是：
+
+```bash
+tunnel-client runtimes connect \
+  --alias forge \
+  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
+  --runtime-api-key env:CONTROL_PLANE_API_KEY \
+  --mcp-server-url http://127.0.0.1:8767/mcp
+
+tunnel-client runtimes status forge --json
+```
+
+只有 tunnel-client 返回 `process_running + healthy + ready` 后，Forge 才把这个连接判为 ready。
+
+#### 地址到底变成什么？
 
-## 3. 验证唯一 Forge Runtime 服务
+使用 Secure Tunnel 后，不再需要给 Forge 准备一个公网 `/mcp` 地址。ChatGPT App 选择 `tunnel_id`；本机 `tunnel-client` 把命令转发到 Forge 的 **loopback OAuth Gateway**（默认 `127.0.0.1:8767/mcp`），再由 Gateway 代理到内部 bearer-only Runtime（默认 `127.0.0.1:8765/mcp`）。如果改过端口，以 `forge mcp setup chatgpt --user-level` 输出的 OAuth endpoint 为准。
 
-`forge mcp setup chatgpt` 会安装或更新唯一 `forge-runtime` 使用的配置。通过 `forge runtime service install` 安装 macOS 服务后，launchd 负责该根进程的开机启动与异常退出自动拉起；系统不再提供 MCP KeepAlive 包装器或组件级生命周期命令。
+App/connector 身份及 Forge 工具 schema 与网络传输层是两件事。Cloudflare/HTTPS 切到 Secure Tunnel 改变的是网络路径，不会生成另一套 19-tool Forge schema。同一个 App 已连接且 schema 没变化时，单纯切换网络不要求新开会话；新会话主要用于隔离 A/B 或排查客户端缓存。
+
+### B. Cloudflare Tunnel
+
+需要稳定公网 HTTPS、并且你管理 Cloudflare 账号/域名时使用：
 
 ```bash
-forge runtime service install \
-  --controller-home /path/to/controller-home \
-  --repo /path/to/forge-source-or-runtime-root \
-  --host 127.0.0.1 \
-  --port 8765 \
-  --auth-token-file /path/to/controller-home/mcp/runtime-token
-forge runtime status --controller-home /path/to/controller-home --json
-forge mcp doctor --repo /path/to/your-project
+forge setup configure --controller chatgpt --tunnel cloudflare
+forge setup next
 ```
 
-只将配置好的 loopback MCP endpoint 通过稳定的 Tailscale 或 Cloudflare HTTPS tunnel 发布。Codex/Claude CLI 安装并登录后才启用对应 provider，但 provider 可用性不会改变 Runtime 进程拓扑。
+setup 会检测当前平台与 `cloudflared`。macOS 有 Homebrew 时可直接给出安装命令；Linux/WSL2 与 Windows 会给对应的官方安装路径，不会假设所有机器都是 Mac。
 
-## 4. 在 ChatGPT 添加 Connector
+named tunnel 建好后，只记录最终 `/mcp` URL：
 
-1. 打开 **Settings → Apps & Connectors → Advanced settings**。
-2. 开启 Developer Mode。
-3. 创建自定义 MCP Connector。
-4. 填入以 `/mcp` 结尾的公网 HTTPS URL。
-5. 在新会话中添加该 Connector。
+```bash
+forge setup configure \
+  --controller chatgpt \
+  --tunnel existing \
+  --endpoint https://forge.example.com/mcp
+```
 
-## 5. 验证默认安全工具面
+### C. Tailscale Funnel
 
-core Connector 应显示：
+已有 Tailscale 时可以选择：
 
-- `rh_status`：运行时和仓库就绪状态；
-- `rh_context`：当前仓库的有界上下文；
-- `rh_work`：开始或继续有边界工作；
-- `rh_inbox`：需要决定、审批或处理的事项。
+```bash
+forge setup configure --controller chatgpt --tunnel tailscale
+forge setup next
+```
 
-此外只会暴露少量仓库初始化和选择工具。不要为了“工具更多”直接切到 `full`；`advanced` 和 `full` 是维护/兼容工具面。
+Forge 检查当前平台的 Tailscale CLI 并引导 Funnel；获得最终 HTTPS `/mcp` URL 后再记录。
 
-按以下顺序测试：
+### D. 已有 HTTPS 或暂缓远程连接
+
+```bash
+forge setup configure \
+  --controller chatgpt \
+  --tunnel existing \
+  --endpoint https://forge.example.com/mcp
+
+# 暂时只完成本地配置：
+forge setup configure --controller chatgpt --tunnel none
+```
+
+Cloudflare/Tailscale/已有 HTTPS 本质上会让 MCP endpoint 成为公网或互联网可达地址；OpenAI Secure MCP Tunnel 是组织有权限时的私有出站方案。
+
+## 4. 在 ChatGPT 创建 App / Connector
+
+ChatGPT UI 会变化，所以以 OpenAI 当前 Developer Mode 文档为准，不在 Forge 文档中固定截图路径。
+
+使用 Secure MCP Tunnel 时选择 **Tunnel** 连接方式并选择/填入 tunnel ID；使用 HTTPS 时填入稳定、以 `/mcp` 结尾的 URL，并走 Forge 生成的 OAuth 流程。
+
+创建后扫描/刷新工具。不要为了看到更多工具名而直接切到 exhaustive compatibility toolset；默认收敛工具面是安全和可用性设计的一部分。
+
+## 5. 验证真实调用
+
+先从只读提示开始：
 
 ```text
-使用 Forge。先用 rh_status 检查系统状态，再用 rh_context 获取当前注册仓库的有界上下文，暂时不要修改文件。
+使用 Forge。调用 rh_status，告诉我 Forge Runtime 是否 ready。
+先不要做任何修改。
 ```
 
-## 6. 安全检查
+之后再授权一个仓库或普通目录做读取验证。**真正 setup 成功的证据是 ChatGPT 已经实际调用 Forge**；只保存了 tunnel ID，或本机进程在运行，都不等于端到端已经连通。
+
+## 6. 安全规则
 
-- MCP 保持监听 loopback，只通过受控 HTTPS 地址公开。
-- 本地 UI 不公开。
-- 先只读，确有需要时再授权有边界写入。
-- 远程 Git、GitHub、邮件、破坏性清理和发布仍分别授权。
-- 不要把 MCP token 或 OAuth secret 粘贴到聊天中。
+- Forge MCP 与 Utility Console 都保持 loopback。
+- 条件允许时优先使用私有出站的 Secure MCP Tunnel。
+- 使用公网 HTTPS tunnel 时只暴露 MCP，不暴露本地 Utility Console。
+- 不要把 MCP token、OAuth secret、tunnel runtime API key、admin key 发到聊天或写入 Forge setup state。
+- 远程 Git、GitHub、邮件、破坏性清理、发布和密钥仍分别授权。
+- Codex/Claude 只有明确选择为主控或执行入口时才配置。
 
-下一步阅读[教程 3：完成第一个仓库任务](03-first-repository-task.zh-CN.md)。Connector 或工具面异常时看[故障排查](../operations/troubleshooting.zh-CN.md)。
+需要软件开发能力时继续[教程 3：第一个仓库任务](03-first-repository-task.zh-CN.md)。Runtime、tunnel、Connector 或工具面异常时查看[故障排查](../operations/troubleshooting.zh-CN.md)。

package/docs/wiki/Architecture.md

@@ -47,7 +47,7 @@ Every registered-repository execution is bound to a stable `repoId` and an expli
 
 ### Direct versus durable work
 
-Investigation is not itself a reason to create Work. A small, understood change can stay Direct. Durable Work, worktrees, campaigns, or workers are introduced when recovery, dependency tracking, isolation, long-running execution, or real risk requires them.
+Investigation is not itself a reason to create Work. A small, understood change can stay Direct. Durable Work, worktrees, or workers are introduced when recovery, dependency tracking, isolation, long-running execution, or real risk requires them.
 
 ### Process Runtime
 

package/docs/wiki/Installation.md

@@ -16,13 +16,13 @@ npm install -g . --omit=optional --no-audit --no-fund
 After the package is visibly published to npm:
 
 ```bash
-npm install -g @moretea-labs/forge@next
+npm install -g @moretea-labs/forge
 ```
 
 Bun installs the same npm artifact:
 
 ```bash
-bun add -g @moretea-labs/forge@next
+bun add -g @moretea-labs/forge
 ```
 
 Do not infer npm publication from a GitHub tag or prerelease alone.

package/docs/wiki/Quick-Start.md

@@ -17,7 +17,7 @@ Requirements: Git, Node.js 20.10+, npm, and a writable user directory. Bun is re
 
 ```bash
 forge --version
-forge init --target both
+forge install --target both
 forge doctor
 ```
 

package/docs/wiki/Work-Lifecycle.md

@@ -6,7 +6,7 @@ Resolve the repository and checkout, read current status, and check whether an I
 
 ## 2. Plan the smallest safe unit
 
-Use direct edits for bounded changes. Use durable Tasks, isolated worktrees, or campaigns when work is long-running, parallel, dependency-aware, or high risk.
+Use direct edits for bounded changes. Use durable Tasks, isolated worktrees, or Goal Workloop coordination when work is long-running, parallel, dependency-aware, or high risk.
 
 ## 3. Execute with ownership
 

package/install.ps1

@@ -16,7 +16,6 @@ function Add-PathEntry([string]$PathEntry) { if ($PathEntry -and (Test-Path $Pat
 function Refresh-InstallerPath { Add-PathEntry $BunBin; if ($env:APPDATA) { Add-PathEntry (Join-Path $env:APPDATA "npm") }; if (Test-Command "npm") { $npmPrefix = (& npm config get prefix 2>$null | Select-Object -First 1).Trim(); Add-PathEntry $npmPrefix } }
 function Assert-Prerequisites {
   if ($PSVersionTable.PSVersion -lt [version]"5.1") { throw "PowerShell 5.1 or newer is required. PowerShell 7 is recommended." }
-  if (-not (Test-Command "git")) { throw "Git is required. Install Git for Windows, reopen PowerShell, and rerun this installer." }
   if (-not (Test-Command "node")) { throw "Node.js 20.10 or newer is required because the published Forge launcher uses Node." }
   $nodeText = (& node -p "process.versions.node").Trim(); if ($LASTEXITCODE -ne 0 -or -not $nodeText) { throw "Node.js is present, but its version could not be read." }
   if ([version]$nodeText -lt $MinimumNodeVersion) { throw "Node.js 20.10 or newer is required; found $nodeText." }
@@ -30,7 +29,7 @@ function Select-InstallRuntime {
     default { throw "Invalid FORGE_INSTALL_RUNTIME=$InstallRuntime. Expected auto, bun, or node." }
   }
 }
-if ($DryRun -or $env:FORGE_DRY_RUN -eq "1") { Write-Host "DRY RUN: would require Git and Node.js 20.10+, choose runtime ($InstallRuntime), install $PackageName@$PackageVersion, and verify the Forge CLI."; exit 0 }
+if ($DryRun -or $env:FORGE_DRY_RUN -eq "1") { Write-Host "DRY RUN: would require Node.js 20.10+ and npm/Bun, install $PackageName@$PackageVersion, and verify the Forge CLI. Git is optional until repository features are enabled."; exit 0 }
 Refresh-InstallerPath
 Assert-Prerequisites
 $Runtime = Select-InstallRuntime
@@ -43,6 +42,6 @@ $Version = (& forge --version | Select-Object -First 1).Trim(); if ($LASTEXITCOD
 & forge doctor --help *> $null; if ($LASTEXITCODE -ne 0) { throw "Forge installed, but the doctor command could not be loaded." }
 Write-Host "Forge $Version installed."
 Write-Host "Next:"
-Write-Host "  forge install --no-cli"
-Write-Host "  forge doctor"
-Write-Host "  forge adopt --repo C:\path\to\your-project --dry-run"
+Write-Host "  forge setup"
+Write-Host ""
+Write-Host "Git is only needed when you enable repository/software-work features."