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

package/docs/operations/platform-support.zh-CN.md

@@ -1,61 +1,63 @@
-# 平台支持说明
+# 平台支持
 
-本文定义项目当前真正承诺的平台范围。代码中存在 Windows 分支并不等于所有流程都已在 Windows 原生环境验证；只有安装、主要工作流和发布检查均覆盖的范围才称为支持。
+本文描述 Forge **普通 package 用户路径**的真实支持范围，并把源码/维护者基础设施与首次使用依赖分开，避免用户为了使用 Forge 被迫安装开发工具链。
 
 ## 支持矩阵
 
-| 平台 | 状态 | 建议用途 |
+| 平台 | 状态 | 普通用户路径 |
 | --- | --- | --- |
-| macOS | 支持 | 完整本地 Controller、仓库接入、MCP、Direct Edit、Agent、浏览器能力和发布检查。 |
-| 现代 Linux | 支持 | 完整本地 Controller 工作流，需要 Bash、Git、Node.js 和常见进程工具。 |
-| Windows + WSL2 | 支持，且是 Windows 推荐方案 | 在 WSL2 内按 Linux 流程运行，仓库建议放在 WSL 文件系统。 |
-| Windows 原生 PowerShell | 预览支持 | 支持安装、CLI、doctor、仓库注册/读取和可移植运行时路径；依赖 Bash 的流程仍有限制。 |
+| macOS | 支持 | Package 安装、主控优先 setup、launchd Package Runtime、仓库/普通目录、MCP、Browser/Desktop 与插件。 |
+| 现代 Linux | 支持 | Package 安装、主控优先 setup、优先 `systemd --user` 的 Package Runtime、仓库/普通目录、MCP 与可移植 Provider。 |
+| Windows + WSL2 | 支持且为 Windows 推荐路径 | Forge Runtime 在 WSL2 内按 Linux 方式运行；Windows 仍可承载 ChatGPT/浏览器客户端。 |
+| Windows 原生 | 预览 | Package 安装、setup、portable Runtime/MCP、仓库注册/读取和可移植能力；暂不宣称重启后 Runtime 自动持久化和所有外部 Provider 组合都完整。 |
 
-## 基础环境
+## 基础安装依赖
 
-所有安装方式都需要：
+普通安装只要求：
 
-- Git 已加入 `PATH`；
-- Node.js 20.10 或更高版本，因为发布后的 `forge` 启动器由 Node 执行；
-- npm（随 Node.js 安装）或 Bun 1.0+，用于安装 package；
-- 可写的用户主目录。
+- Node.js 20.10 或更高；
+- npm（Node 自带）或 Bun；
+- 可写用户目录。
 
-Bun 是开发和完整测试的推荐执行器，但不再是唯一安装器。
+**Git 只在启用仓库/软件开发能力时才需要。** 普通 package 用户不要求 Bun、Forge 源码 checkout、CodeGraph、Codex、Claude、Standalone Recovery、Cloudflare、Tailscale 或 OpenAI tunnel-client。
 
-以下环境按功能选装：
+按能力才出现的依赖包括：Git 仓库操作；明确选择的 Codex/Claude 主控或执行入口；GitHub CLI；Browser/Desktop 平台依赖；Google/Apple 等账号凭证；以及远程主控连接本机 MCP 时选择的 tunnel/provider。
 
-- Codex 或 Claude CLI：委派复杂代码实现；
-- GitHub CLI `gh`：GitHub Issue、Project 和云端 Agent；
-- Tailscale Funnel 或 `cloudflared`：稳定公网 HTTPS `/mcp` 地址；
-- Playwright 浏览器依赖：浏览器自动化；
-- CodeGraph：额外代码导航；
-- Google Workspace 凭据：Gmail、Calendar 插件。
+## 各平台 Runtime owner
 
-## Windows 原生支持范围
+普通用户使用：
 
-Windows PowerShell 路径当前发布验证覆盖：
+```bash
+forge runtime service install-package
+```
 
-- 前置环境检查和 CLI 安装；
-- `forge --version`、命令加载与 `forge doctor`；
-- 仓库注册表；
-- 可移植测试覆盖的 Windows 路径、进程、junction 和命令处理；
-- 不依赖 Bash helper 的默认 MCP facade 与有边界仓库操作。
+它会对已安装 `@moretea-labs/forge` 的 Runtime 表面做内容指纹；package 内容与记录身份不一致时拒绝启动，而不是静默跨版本执行。
 
-暂不宣称完整原生支持：
+- **macOS：** launchd 用户服务。
+- **Linux / WSL2 且 user systemd 可用：** `systemd --user`，异常退出自动重启。
+- **Linux 无 user systemd：** 明确退化为 portable detached-session，并提示不具备重启持久化。
+- **Windows 原生：** 当前是 portable user-process 预览，不宣称重启持久化。
 
-- Bash 编写的仓库迁移和 Hook 脚本；
-- 完整源码发布 Bash 门禁；
-- CodeGraph 自动配置；
-- 所有 Agent CLI 与隧道组合。
+`forge runtime service install --repo ...` 的 Git/source immutable release 路径和 Standalone Recovery 都属于高级维护能力，不是普通用户初始化依赖。
 
-这些场景请使用 WSL2。原生安装流程会主动跳过 Bash skill 同步和未验证的 CodeGraph 自动配置，而不是让整体安装失败。
+## ChatGPT / 远程 MCP 连接方式
 
-## WSL2 使用建议
+Forge MCP 始终保持 loopback。远程主控明确选择一种连接方式：
 
-在 WSL2 内安装 Git、Node.js 和可选的 Bun，并将仓库放在 Linux 主目录，例如 `~/src/project`。不要让同一个 checkout 交替由 Windows 和 WSL 操作，否则文件权限、符号链接、换行符和运行时路径可能漂移。
+| Provider | 是否需要公网入站 | 典型用途 |
+| --- | --- | --- |
+| OpenAI Secure MCP Tunnel | 不需要 | OpenAI 组织有 tunnel 权限时优先；使用官方 `tunnel-client`，Forge 只记录非秘密 tunnel ID。 |
+| Cloudflare Tunnel | 是 / HTTPS 互联网可达 | 用户管理 Cloudflare 账号/域名，需要稳定 named HTTPS endpoint。 |
+| Tailscale Funnel | 是 / HTTPS 互联网可达 | 已有兼容 Tailscale 环境。 |
+| 已有 HTTPS `/mcp` | 取决于用户基础设施 | 用户已有反代或 tunnel。 |
+| None | 不需要 | 本地主控，或稍后再接远程。 |
+
+setup 会检测操作系统与 provider CLI，不会假定所有用户都是 macOS + Homebrew。第三方登录始终由用户明确完成，Forge 不要求把账号密码/API key 粘贴进 setup。
+
+## Windows 原生范围
 
-ChatGPT 客户端和浏览器仍可运行在 Windows 主机；Controller 与 MCP 运行在 WSL2，只通过受控 HTTPS 隧道公开 MCP endpoint。
+PowerShell 路径会检查安装器/CLI、doctor、setup/profile、仓库 Registry、Windows 路径/进程和 portable Node 行为。依赖 Bash 的仓库迁移、所有 Browser/Provider 组合，以及 Windows 持久 Service owner 仍不属于完整支持；这些场景优先使用 WSL2。
 
 ## 验证边界
 
-仓库提供 `windows-latest` smoke workflow，验证 PowerShell dry-run、安装契约、Windows 默认策略和 Node 可移植测试。它证明的是上述有边界范围，不代表所有 Bash 或外部 Provider 集成都已原生 Windows 验证。
+仓库有平台/public-doc 检查和 Windows smoke。这里的“支持”只代表列出的主路径有验证证据，不表示每台机器都已安装每个第三方 Provider。

package/docs/operations/releasing.md

@@ -72,13 +72,13 @@ The tag workflow uses GitHub OIDC and does not require `NODE_AUTH_TOKEN` or a st
 
 ## Stable release
 
-Before `1.4.0`:
+Before a stable `X.Y.Z` release:
 
 - install the exact packed artifact on macOS, Linux, WSL2, and the supported Windows path;
-- verify `forge init`, `forge doctor`, repository registration/adoption, and the ChatGPT MCP connection;
+- verify `forge install`, `forge doctor`, repository registration/adoption, and the ChatGPT MCP connection;
 - confirm no RC-only warning or unstable install command remains in the stable docs;
 - change `package.json` from an RC version to the intended stable `X.Y.Z`; the package identity gate will require `latest`;
-- publish from tag `v1.4.0` through the protected environment;
+- publish from the exact `vX.Y.Z` tag through the protected environment;
 - only then create or update the Homebrew tap formula.
 
 ## Rollback and incident rule

package/docs/operations/releasing.zh-CN.md

@@ -72,13 +72,13 @@ Tag workflow 使用 GitHub OIDC，不需要 `NODE_AUTH_TOKEN` 或仓库内 npm t
 
 ## 稳定版要求
 
-发布 `1.4.0` 前：
+发布稳定版 `X.Y.Z` 前：
 
 - 在 macOS、Linux、WSL2 和已声明的 Windows 路径安装精确 packed artifact；
-- 验证 `forge init`、`forge doctor`、仓库注册/接入和 ChatGPT MCP 连接；
+- 验证 `forge install`、`forge doctor`、仓库注册/接入和 ChatGPT MCP 连接；
 - 确认稳定文档中没有 RC 专属警告或不稳定安装命令；
 - 把 `package.json` 从 RC 版本改为目标稳定版 `X.Y.Z`，package identity gate 会要求 `latest`；
-- 从受保护环境发布 tag `v1.4.0`；
+- 从受保护环境发布精确 tag `vX.Y.Z`；
 - 完成后才创建或更新 Homebrew tap formula。
 
 ## 回滚与事故规则

package/docs/operations/troubleshooting.md

@@ -15,7 +15,7 @@ forge --version
 
 ## Doctor reports missing Git or Node
 
-Install Git and Node.js 20.10 or newer, then open a new terminal. Node is required even when the package was installed with Bun because the published launcher uses Node.
+Node.js 20.10 or newer is a base requirement even when the package was installed with Bun. Git is **not** a base installation requirement; install Git when you enable repository/software-work features. If plain `forge setup` is blocked only by an unselected Codex/Claude/CodeGraph check, update Forge—the controller-first setup path should filter unrelated host tooling.
 
 ## Native Windows stops at a shell-owned step
 
@@ -23,7 +23,12 @@ Use WSL2 for repository adoption, Bash hooks, source release checks, or shell li
 
 ## MCP works locally but ChatGPT cannot connect
 
-`http://127.0.0.1:8765/mcp` is local-only. ChatGPT needs a stable public HTTPS URL ending in `/mcp`. Check the tunnel, the exact path, and `forge mcp doctor`. Do not expose the local Controller UI port publicly.
+`http://127.0.0.1:8765/mcp` is intentionally local-only. Run `forge setup next` and inspect the selected remote provider.
+
+- **OpenAI Secure MCP Tunnel:** run `tunnel-client runtimes status forge --json`; do not claim success unless the runtime is running, healthy, and ready. Keep `CONTROL_PLANE_API_KEY` outside Forge state.
+- **Cloudflare/Tailscale/existing HTTPS:** verify the stable `/mcp` address and OAuth discovery with `forge mcp doctor` plus the provider's own status tools.
+
+Do not expose the local Utility Console port publicly.
 
 ## MCP config seems to be in the wrong place
 
@@ -35,11 +40,11 @@ Current service-level MCP config lives under Controller Home, not as the primary
 - `controllerHome/mcp/mcp.oauth-tokens.json`
 - `controllerHome/mcp/mcp.runtime.json`
 
-Controller Home is the sole authority for service-level MCP configuration. Repository-scoped `.forge/mcp.policy.json` remains the repository access policy; repository-local service configuration is unsupported. Rerun `forge mcp setup chatgpt --repo /path/to/your-project`, then verify the active endpoint and server name from Controller Home.
+Controller Home is the sole authority for service-level MCP configuration. Repository-scoped `.forge/mcp.policy.json` remains repository access policy. For the normal ChatGPT path rerun `forge mcp setup chatgpt --user-level` or simply `forge setup next`; repository-scoped setup remains a compatibility path.
 
 ## Only some tools appear in ChatGPT
 
-The default controller uses a stable repair-capable schema (normally 100–128 tools). Request/Full Access never changes that schema. Compare `expectedToolCount`, `actualToolCount`, `missingTools`, `unexpectedTools`, and the fingerprint from `rh_status` or `controller_ready`. Reconnect only when the Connector snapshot itself is stale, not after a permission change.
+The default controller intentionally exposes a bounded stable facade rather than every atomic internal handler. Request/Full Access changes authorization, not the tool schema. Compare the current fingerprint and missing/unexpected tools from `rh_status`; refresh/recreate the ChatGPT app only when the connector snapshot itself is stale or tool definitions changed.
 
 ## Runtime storage is not ready or the Local UI looks stale
 
@@ -59,9 +64,9 @@ If you are using the operator surfaces, inspect the runtime-maintenance path bef
 
 A `502`, reconnect, or truncated response does not prove a durable write failed. Confirm the Job, Run, or evidence summary before retrying the mutation.
 
-## Agent delegation is unavailable
+## Codex or Claude controller entry is unavailable
 
-Core Direct Edit and repository workflows still work. Install and authenticate Codex or Claude, then restart MCP with the dev runner explicitly enabled. Do not enable agent flags in the basic setup unless the CLI is present.
+Forge has no internal agent that must be repaired. If Codex/Claude was not selected, ignore its absence. If it was explicitly selected as a controller entry, install/authenticate that client and run `forge mcp setup codex --scope user --profile controller` or `forge mcp setup claude --scope user --profile controller`, then continue with `forge setup next`.
 
 ## Repository paths behave differently between Windows and WSL2
 

package/docs/operations/troubleshooting.zh-CN.md

@@ -13,7 +13,7 @@ forge --version
 
 ## Doctor 提示缺少 Git 或 Node
 
-安装 Git 和 Node.js 20.10+ 后重新打开终端。即使 package 由 Bun 安装，发布后的启动器仍由 Node 执行，因此 Node 是基础依赖。
+Node.js 20.10+ 是基础依赖，即使 package 由 Bun 安装也需要 Node。Git **不是**基础安装依赖；只有启用仓库/软件开发能力时才需要。如果普通 `forge setup` 只是被未选择的 Codex/Claude/CodeGraph 检查挡住，应更新 Forge——主控优先 setup 会过滤无关 host tooling。
 
 ## Windows 原生流程停在 shell 步骤
 
@@ -21,7 +21,12 @@ forge --version
 
 ## 本机 MCP 正常，但 ChatGPT 无法连接
 
-`http://127.0.0.1:8765/mcp` 只能本机访问。ChatGPT 需要稳定的公网 HTTPS `/mcp` 地址。检查隧道、路径和 `forge mcp doctor`。不要把本地 Controller UI 端口暴露到公网。
+`http://127.0.0.1:8765/mcp` 本来就只允许本机访问。执行 `forge setup next` 并检查当前选择的远程 provider。
+
+- **OpenAI Secure MCP Tunnel：** 执行 `tunnel-client runtimes status forge --json`；只有 runtime 同时 running、healthy、ready 才算成功。`CONTROL_PLANE_API_KEY` 不进入 Forge state。
+- **Cloudflare/Tailscale/已有 HTTPS：** 检查稳定 `/mcp` 地址、Provider 状态以及 `forge mcp doctor`。
+
+不要把本地 Utility Console 端口暴露到公网。
 
 ## MCP 配置看起来写到了错误的位置
 
@@ -33,11 +38,11 @@ forge --version
 - `controllerHome/mcp/mcp.oauth-tokens.json`
 - `controllerHome/mcp/mcp.runtime.json`
 
-Controller Home 是 service-level MCP 配置的唯一权威来源；仓库级 `.forge/mcp.policy.json` 仍是仓库访问策略。仓库内的 service 配置不再受支持。重新执行 `forge mcp setup chatgpt --repo /path/to/your-project` 后，从 Controller Home 核对当前 endpoint 与 server name。
+Controller Home 是 service-level MCP 配置的唯一权威来源；仓库级 `.forge/mcp.policy.json` 仍是仓库访问策略。普通 ChatGPT 路径重新执行 `forge mcp setup chatgpt --user-level`，或直接继续 `forge setup next`；repo-scoped setup 仅保留兼容入口。
 
 ## ChatGPT 只显示少量工具
 
-默认 Controller 使用固定、可修复的工具 schema（通常 100–128 个工具）。Request/Full Access 不会改变 schema。请从 `rh_status` 或 `controller_ready` 对比 `expectedToolCount`、`actualToolCount`、缺失/意外工具和 fingerprint；只有 Connector 快照本身过期时才需要重连，权限切换不需要。
+默认 Controller 故意暴露收敛后的稳定 facade，而不是所有内部原子 handler。Request/Full Access 改变授权，不改变工具 schema。通过 `rh_status` 检查 fingerprint 和缺失/意外工具；只有 ChatGPT app 的工具快照过期或定义发生变化时才刷新/重建。
 
 ## runtime storage 未就绪，或本地 UI 看起来是旧状态
 
@@ -57,9 +62,9 @@ forge repo list --json
 
 看到 `502`、重连或大结果截断，不代表 durable 写入一定失败；先回到 Job、Run 或证据摘要确认真实状态。
 
-## 无法委派 Agent
+## Codex 或 Claude 控制入口不可用
 
-核心 Direct Edit 和仓库工作流仍可使用。安装并登录 Codex 或 Claude 后，再显式开启 dev runner。基础配置不应默认加入 Agent 参数。
+Forge 没有一个必须修复的内部 Agent。没有选择 Codex/Claude 时直接忽略它们；明确选择为主控后，才安装/登录对应客户端，并执行 `forge mcp setup codex --scope user --profile controller` 或 `forge mcp setup claude --scope user --profile controller`，随后继续 `forge setup next`。
 
 ## Windows 与 WSL2 路径行为不一致
 

package/docs/public-usage-guide.md

@@ -1,33 +1,40 @@
 # Public Usage Guide
 
-Use this page when you want the shortest current path through Forge without reading the entire docs tree first.
+Use this page for the shortest current Forge path.
 
-## Fast path
+## 1. Install and choose the external controller
 
-1. [Install and start](tutorials/01-install-and-start.md)
-2. [Connect ChatGPT](tutorials/02-connect-chatgpt.md)
-3. [Complete the first repository task](tutorials/03-first-repository-task.md)
+```bash
+npm install -g @moretea-labs/forge
+forge setup
+```
 
-## What Forge is
+Forge has no internal AI brain. Choose one primary external controller; ChatGPT is recommended, while Codex, Claude, or another MCP client can be selected explicitly. Multiple controller entries may be configured without turning unselected clients into dependencies.
 
-Forge is a local execution bridge that lets ChatGPT work on one or more repositories through a stable, bounded tool schema. The preferred orchestration tools are `rh_status`, `rh_access`, `rh_context`, `rh_work`, and `rh_inbox`, while the default schema also exposes practical Direct Edit, command, Git, Agent, Campaign, iOS, plugin, artifact, and recovery entry points.
+```bash
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
+```
 
-Direct Edit is the default for small known changes. `quick_agent_session` provides a direct local Codex/Claude path without requiring an Issue or Task. Durable Issue → Task → Run flows remain available for work that must survive sessions, carry dependencies, or preserve formal review evidence. Request/Full Access changes approval behavior only and never requires reconnecting the MCP Connector.
+## 2. Follow setup until the selected path is usable
 
-## Current runtime facts
+For ChatGPT, `--tunnel auto` prefers OpenAI Secure MCP Tunnel and does not silently switch to a public ingress provider just because one is installed. The packaged setup keeps the bearer-only Canonical Runtime private and manages a separate loopback OAuth Gateway for the ChatGPT App. Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS `/mcp` endpoint, or deferred remote access are explicit alternatives. Existing users update with `npm install -g @moretea-labs/forge@latest`, then `forge setup next`.
 
-- Controller Home is primary for MCP service config, authentication, and runtime state under `controllerHome/mcp/`: `mcp.local.json`, `mcp.tokens.json`, `mcp.oauth.json`, `mcp.oauth-tokens.json`, and `mcp.runtime.json`.
-- The matching repo-local `.Forge/mcp.local.json`, `.Forge/mcp.tokens.json`, `.Forge/mcp.oauth.json`, `.Forge/mcp.oauth-tokens.json`, and `.Forge/mcp.runtime.json` files are legacy fallback only. Repository-scoped `.Forge/mcp.policy.json` remains the access policy.
-- The controller is global across registered repositories, but repository work still routes by explicit `repoId` and `checkoutId`.
-- The public MCP endpoint is separate from the localhost-only Local Controller UI on `127.0.0.1:8766`. The UI is an execution-assistant console with Command Center, Approvals and Decisions, Current Work, Capabilities / Plugins, Models / Tools, System Status, Repositories, and Advanced Diagnostics.
-- Long-running work returns durable Jobs/Runs with bounded previews. Check those records before assuming a `502`, reconnect, or truncated response means the write failed.
+The normal package Runtime is `forge runtime service install-package`. Source immutable Runtime and Standalone Recovery are advanced maintainer paths.
 
-## Choose the next guide by goal
+## 3. Add only the capabilities you need
 
-- Need install and connector setup: [Tutorials](tutorials/README.md)
-- Need manual MCP/tunnel details: [Forge ChatGPT MCP setup](Forge-chatgpt-mcp-setup.md)
-- Need provider or executor routing: [Provider configuration and routing](operations/provider-configuration.md)
-- Need browser, Gmail/Calendar, or other plugins: [Documentation hub](README.md)
-- Need troubleshooting or runtime-storage recovery: [Troubleshooting](operations/troubleshooting.md), [Self-healing loop](Forge-runtime-self-healing-loop.md)
+A Git repository is optional during first setup. Adopt one for software work:
 
-For the broader map, use the maintained [documentation hub](README.md).
+```bash
+forge adopt --repo /path/to/project --dry-run
+forge adopt --repo /path/to/project
+```
+
+Or authorize a normal folder / configure Browser, Desktop, Gmail, Calendar, Apple, GitHub, or other typed providers later. Git, Codex, Claude, service credentials, and tunnel CLIs are capability-specific dependencies.
+
+## 4. Verify with a real controller call
+
+For ChatGPT, follow [Connect ChatGPT](tutorials/02-connect-chatgpt.md), then start with a read-only `rh_status` call. A running local process or saved endpoint is not enough; the first successful controller-to-Forge tool call is the useful setup milestone.
+
+See [Features](operations/features.md), [Platform Support](operations/platform-support.md), [Plugin Management](forge-plugin-management.md), and [Troubleshooting](operations/troubleshooting.md) for deeper paths.

package/docs/public-usage-guide.zh-CN.md

@@ -1,33 +1,40 @@
 # 公开使用指南
 
-如果你只想用最短路径理解并开始使用 Forge，先看这一页。
+这是当前最短的 Forge 使用路径。
 
-## 最短路径
+## 1. 安装并选择外部主控
 
-1. [安装并启动](tutorials/01-install-and-start.zh-CN.md)
-2. [连接 ChatGPT](tutorials/02-connect-chatgpt.zh-CN.md)
-3. [完成第一个仓库任务](tutorials/03-first-repository-task.zh-CN.md)
+```bash
+npm install -g @moretea-labs/forge
+forge setup
+```
 
-## Forge 是什么
+Forge 自己没有 AI 大脑。选择一个 primary 外部主控；推荐 ChatGPT，也可以明确选择 Codex、Claude 或其他 MCP 客户端。可以配置多个控制入口，但没被选择的客户端不会变成依赖。
 
-Forge 是一个本地执行桥，让 ChatGPT 通过固定且有边界的工具 schema 处理一个或多个仓库。日常编排优先使用 `rh_status`、`rh_access`、`rh_context`、`rh_work` 和 `rh_inbox`；默认工具面同时提供 Direct Edit、命令、Git、Agent、Campaign、iOS、插件、artifact 和恢复能力。
+```bash
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
+```
 
-小而确定的修改默认走 Direct Edit；`quick_agent_session` 可以直接调用本地 Codex/Claude，不强制先创建 Issue 或 Task。需要跨会话恢复、带依赖拆分或保留正式审查证据的工作，仍可进入 durable 的 Issue → Task → Run 路径。Request/Full Access 只改变审批行为，不会要求重连 MCP Connector。
+## 2. 按 Next 完成所选路径
 
-## 当前运行时事实
+对 ChatGPT，`--tunnel auto` 会优先 OpenAI Secure MCP Tunnel，不会因为机器上恰好安装了 cloudflared/Tailscale 就静默改用公网入口。Package setup 会保持 bearer-only Canonical Runtime 私有，并管理一个独立的 loopback OAuth Gateway 供 ChatGPT App 使用。Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接都是显式 fallback。已安装用户运行 `npm install -g @moretea-labs/forge@latest` 后再执行 `forge setup next`。
 
-- Controller Home 是 MCP service 配置、认证和运行态的主存储位置；`controllerHome/mcp/` 下保存 `mcp.local.json`、`mcp.tokens.json`、`mcp.oauth.json`、`mcp.oauth-tokens.json` 和 `mcp.runtime.json`。
-- 对应的 repo-local `.Forge/mcp.local.json`、`.Forge/mcp.tokens.json`、`.Forge/mcp.oauth.json`、`.Forge/mcp.oauth-tokens.json`、`.Forge/mcp.runtime.json` 只用于 legacy fallback；仓库级 `.Forge/mcp.policy.json` 仍是访问策略文件。
-- Controller 是跨已注册仓库的全局服务，但仓库工作仍通过显式 `repoId` 和 `checkoutId` 路由。
-- 公网 MCP endpoint 与 `127.0.0.1:8766` 上仅限本机访问的 Local Controller UI 是不同入口。当前 UI 是执行助手控制台，包含指挥中心、审批与决定、当前任务、能力 / 插件、模型与工具、系统状态、仓库和高级诊断。
-- 长任务默认返回 durable Job / Run 的摘要和有界预览；看到 `502`、重连或大结果截断时，先确认 Job / Run 状态，不要直接假定写入失败。
+普通 package Runtime 是 `forge runtime service install-package`。源码 immutable Runtime 与 Standalone Recovery 属于高级维护路径。
 
-## 按目标继续阅读
+## 3. 只增加需要的能力
 
-- 需要安装和 Connector 细节：看 [教程目录](tutorials/README.zh-CN.md)
-- 需要 MCP / 隧道 / OAuth 手动配置：看 [Forge ChatGPT MCP 配置](Forge-chatgpt-mcp-setup.md)
-- 需要 provider 或 executor 路由：看 [Provider 配置与路由](operations/provider-configuration.md)
-- 需要浏览器、Gmail/Calendar 或其他插件：看持续维护的 [文档中心](README.md)
-- 需要故障排查或 runtime-storage 恢复：看 [故障排查](operations/troubleshooting.zh-CN.md) 和 [自修复闭环](Forge-runtime-self-healing-loop.md)
+首次 setup 不要求 Git 仓库。需要软件开发时再接入：
 
-更完整的导航请回到持续维护的[文档中心](README.md)。
+```bash
+forge adopt --repo /path/to/project --dry-run
+forge adopt --repo /path/to/project
+```
+
+也可以之后授权普通目录，或配置 Browser、Desktop、Gmail、Calendar、Apple、GitHub 等类型化 Provider。Git、Codex、Claude、服务凭证和 tunnel CLI 都是按能力出现的依赖。
+
+## 4. 用真实主控调用验收
+
+ChatGPT 用户继续阅读[连接 ChatGPT](tutorials/02-connect-chatgpt.zh-CN.md)，先做只读 `rh_status`。本机进程在运行或 endpoint 已保存不等于真正完成；第一次主控到 Forge 的真实工具调用成功才是有意义的 setup 里程碑。
+
+更多内容见[功能清单](operations/features.zh-CN.md)、[平台支持](operations/platform-support.zh-CN.md)、[插件管理](forge-plugin-management.md)和[故障排查](operations/troubleshooting.zh-CN.md)。

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

@@ -1,35 +1,35 @@
-# Tutorial 1: Install and start
+# Tutorial 1: Install and choose your controller
 
-This tutorial installs the CLI, initializes the user-level runtime, checks the host, and registers one repository.
+This tutorial gets Forge from a package install to a resumable setup session. Forge has **no internal AI brain**: one external controller decides what should happen, while Forge owns bounded execution, durable state, permissions, and evidence.
 
-## 1. Platform and prerequisites
+## 1. Pick the platform path
 
-- macOS or Linux: full supported workflow.
-- Windows: use WSL2 for the full workflow.
-- Native Windows PowerShell: preview support for installation, doctor, repository registration/inspection, and portable controller operations.
+- **macOS:** supported; the packaged Runtime can persist through launchd.
+- **Modern Linux:** supported; the packaged Runtime uses `systemd --user` when available and otherwise reports a portable-session fallback.
+- **Windows + WSL2:** recommended Windows path; follow the Linux flow inside WSL2.
+- **Native Windows:** preview; CLI, setup, portable Runtime, MCP, and bounded portable capabilities work, but reboot-persistent Runtime ownership and every provider combination are not yet claimed.
 
-Install Git, Node.js 20.10 or newer, npm, and a writable home directory. Bun 1.0+ is optional and recommended for source development and the complete test suite.
+Base installation needs **Node.js 20.10 or newer**, npm (or Bun), and a writable user home. **Git is optional until you enable repository/software-work features.** Codex, Claude, `gh`, Cloudflare, Tailscale, CodeGraph, and service credentials are capability-specific dependencies, not Forge installation prerequisites.
 
 ```bash
-git --version
 node --version
 npm --version
 ```
 
 See [Platform Support](../operations/platform-support.md) for the exact matrix.
 
-## 2. Install the CLI
+## 2. Install Forge
 
-Release candidates are published on npm's `next` channel:
+Stable releases use npm `latest`:
 
 ```bash
-npm install -g @moretea-labs/forge@next
+npm install -g @moretea-labs/forge
 # or
-bun add -g @moretea-labs/forge@next
+bun add -g @moretea-labs/forge
 forge --version
 ```
 
-For Forge source development, install from the repository instead:
+For Forge source development only:
 
 ```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
 ```
 
-The package exposes exactly `forge`, `forge-hook`, and `forge-runtime`. Release candidates use `next`; stable releases use `latest`.
+The published package exposes `forge`, `forge-hook`, and `forge-runtime`. Normal package users do **not** need a Forge source checkout, Bun compilation, CodeGraph, or Standalone Recovery to start the user-level Runtime. To upgrade, run `npm install -g @moretea-labs/forge@latest`, verify `forge --version`, then run `forge setup next` so newer setup contracts can be reconciled without reinstalling from source.
 
-## 3. Open the guided setup session
+## 3. Start guided setup
 
 ```bash
-forge --version
-forge setup open --target both
+forge setup
 ```
 
-`forge setup open` creates or resumes one user-level setup session below `~/.forge/setup/`. It runs the readiness checks and prints exactly one next configuration action. Complete that action, then continue with the same command loop:
+On a fresh install the first action is to choose the external controller. ChatGPT is recommended, but it is not mandatory:
 
 ```bash
-forge setup next
+forge setup configure --controller chatgpt --tunnel auto
+# Alternatives:
+# forge setup configure --controller codex
+# forge setup configure --controller claude
+# forge setup configure --controller mcp
 ```
 
-Repeat `forge setup next` until the session reports `ready`, then close it:
+You can preconfigure additional controller entries while keeping one primary controller:
 
 ```bash
-forge setup close
+forge setup configure \
+  --controller chatgpt \
+  --add-controller codex \
+  --add-controller claude \
+  --tunnel auto
 ```
 
-Use `forge setup status` to inspect the persisted session and `forge setup check` for a one-shot read-only report. `--target codex` or `--target claude` limits host-specific configuration. The setup session never silently performs remote, secret-bearing, destructive, or service-installing actions.
+Forge does not install or check Codex/Claude merely because they exist on the machine. Their readiness becomes relevant only when you explicitly select them.
+
+## 4. Follow one Next action at a time
+
+```bash
+forge setup next
+```
+
+The setup session is stored below the user-level Forge directory, so you can close the terminal and resume later. Depending on the selected controller, the flow may ask for:
+
+1. controller registration;
+2. the packaged user-level Runtime;
+3. remote connectivity — OpenAI Secure MCP Tunnel first for ChatGPT, with explicit HTTPS fallbacks;
+4. account/browser authentication that only you can complete;
+5. a connection verification.
 
-## 4. Adopt or register a repository
+`forge setup status` shows persisted progress. `forge setup check` is read-only. `forge setup close` closes a ready setup session.
 
-For macOS, Linux, or WSL2, preview adoption first:
+The normal Runtime action is:
 
 ```bash
-forge adopt --repo /path/to/your-project --dry-run
-forge adopt --repo /path/to/your-project
+forge runtime service install-package
 ```
 
-All platforms can register explicitly:
+For ChatGPT setups this installs two local service boundaries together: the bearer-only Canonical Runtime and a separate loopback OAuth Gateway used by Secure Tunnel or HTTPS connectors. Users should follow the OAuth endpoint printed by setup instead of tunneling directly to the internal Runtime port.
+
+The older `forge runtime service install --repo ...` path builds an immutable Git/source Runtime and is an **advanced maintainer path**, not normal onboarding. Standalone Recovery is likewise optional advanced infrastructure.
+
+## 5. Repositories are optional at first
+
+Forge can be useful for authorized files, browser/desktop actions, and service plugins without adopting a Git repository. Add a project when you need software-work capabilities:
 
 ```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
 ```
 
-Keep the returned `repoId`; it is the stable repository identity used by ChatGPT and the Controller.
+Git becomes required for that repository workflow.
 
-## 5. Confirm readiness
+## 6. Verify the base install
 
 ```bash
 forge setup status
 forge doctor
-forge status --json
-forge repo list --json
 ```
 
-Runtime state belongs in Controller Home and ignored repository links, not in public source control. Never commit tokens, MCP runtime files, local jobs, logs, or generated worktrees.
-
-Continue with [Tutorial 2: Connect ChatGPT](02-connect-chatgpt.md). For errors, use [Troubleshooting](../operations/troubleshooting.md).
+If ChatGPT is your controller, continue with [Tutorial 2: Connect ChatGPT](02-connect-chatgpt.md). For errors, use [Troubleshooting](../operations/troubleshooting.md).