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

package/README.md

@@ -1,132 +1,112 @@
 <a id="english"></a>
 
-<p align="center"><img src="docs/images/forge-banner.svg" alt="Forge — local-first action runtime" width="1280"></p>
-<p align="center"><strong>Local-first action runtime for ChatGPT and AI coding assistants.</strong></p>
-<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="docs/README.md">Docs</a> · <a href="docs/forge-plugin-management.md">Plugins</a> · <a href="https://github.com/moretea-labs/forge/releases">Releases</a></p>
-<p align="center"><img alt="CI" src="https://github.com/moretea-labs/forge/actions/workflows/ci.yml/badge.svg"> <img alt="Release" src="https://img.shields.io/github/v/release/moretea-labs/forge?include_prereleases&sort=semver"> <img alt="npm next" src="https://img.shields.io/npm/v/%40moretea-labs%2Fforge?tag=next&label=npm%20next"> <img alt="License" src="https://img.shields.io/github/license/moretea-labs/forge"></p>
+<p align="center"><img src="docs/images/forge-banner.svg" alt="Forge — ChatGPT decides, Forge acts" width="1280"></p>
+<p align="center"><strong>Give ChatGPT real, controlled hands on your computer, code, browser, and services.</strong></p>
+<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="docs/README.md">Docs</a> · <a href="docs/operations/features.md">Features</a> · <a href="docs/forge-plugin-management.md">Plugins</a> · <a href="https://github.com/moretea-labs/forge/releases">Releases</a></p>
+<p align="center"><img alt="CI" src="https://github.com/moretea-labs/forge/actions/workflows/ci.yml/badge.svg"> <img alt="Release" src="https://img.shields.io/github/v/release/moretea-labs/forge?include_prereleases&sort=semver"> <img alt="npm latest" src="https://img.shields.io/npm/v/%40moretea-labs%2Fforge?tag=latest&label=npm%20latest"> <img alt="License" src="https://img.shields.io/github/license/moretea-labs/forge"></p>
 
-Forge gives ChatGPT a bounded, auditable way to work with **real local repositories, processes, plugins, and recovery state**. It keeps durable execution facts outside the chat, uses the lightest valid path for small work, and preserves explicit safety boundaries for remote, destructive, secret, and outside-workspace effects.
+**Forge has no internal AI brain.** One external controller owns semantic decisions; Forge provides the controlled execution, state, permissions, and recovery layer. ChatGPT is the recommended controller, but you can choose Codex, Claude, or another MCP client instead, and you may configure several controller entries while keeping one primary controller at a time.
 
-## Why Forge
+With ChatGPT as the controller, Forge does **not** require a separate OpenAI API key or a second per-token model budget. Your existing ChatGPT plan/session limits still apply. Codex and Claude are not Forge dependencies unless you explicitly choose or configure them.
 
-| Need | Forge behavior |
-| --- | --- |
-| Work on real code | Stable `repoId + checkoutId` identity binds every repository operation to the intended checkout. |
-| Keep small tasks fast | Direct-first execution avoids Plan/Issue/Agent/worktree overhead when the change is already understood. |
-| Run long work once | Process Runtime owns build/test/process lifecycle; status, wait, logs, and cancel attach to the same process. |
-| Work concurrently | Independent repositories run in parallel; worktrees are introduced only when isolation is actually needed. |
-| Trust the result | Focused checks, diffs, receipts, evidence, immutable runtime releases, and Recovery make outcomes reviewable. |
-| Extend safely | Typed external providers install through Forge's pinned catalog and reuse the same authorization/evidence path. |
+## What Forge gives ChatGPT
 
-## Quick start
+| Capability | What that means for you |
+| --- | --- |
+| **Your local computer** | Authorize a folder, then let ChatGPT list/read/write/copy/move files, create directories, open documents or Finder, run bounded commands, inspect processes, and manage verified macOS LaunchAgents. |
+| **Real software work** | Inspect and edit repositories, run tests/builds, use Git and worktrees, keep long commands attached, verify results, commit, and clean temporary work. |
+| **Browser + desktop** | Navigate, inspect, click, fill, screenshot, transfer files, and hand off when human interaction is required; Chrome/Vivaldi native attach and macOS desktop actions are supported where available. |
+| **Apple workflows** | Build and inspect iOS projects, work with simulators/devices, and use App Store Connect for apps, builds, TestFlight, review state, and Xcode Cloud workflows. |
+| **Your services** | Typed plugins for GitHub, Gmail, Google Calendar, Google Tasks, Resend, plus independently released Forge providers. |
+| **Automation + recovery** | Long commands stay attached instead of being restarted; scheduled/recurring work can persist outside chat and hand control back to ChatGPT when reasoning is needed. Repository identity, checks, approvals, and recovery facts survive outside the conversation. |
 
-Requirements: Git, Node.js 20.10+, npm, and a writable home directory. Bun 1.0+ is recommended for source development and the full test suite.
+### Ask for outcomes, not tools
 
-```bash
-npm install -g @moretea-labs/forge@next
-forge --version
-forge setup open --target both
-forge setup next     # repeat until ready
-forge setup close
-forge doctor
+```text
+“Clean up these generated files, run the project checks, commit the fix, and remove the worktree.”
+“Read this authorized folder, reorganize the documents, and open the result in Finder.”
+“Open the web app, test this flow in Chrome, capture evidence, then fix the UI regression.”
+“Summarize today’s inbox, archive obvious promotions, and prepare the important replies.”
+“Check the latest TestFlight build and tell me what blocks release.”
 ```
 
-Connect ChatGPT with [Tutorial 2](docs/tutorials/02-connect-chatgpt.md), then adopt a repository:
+Forge deliberately keeps the tool mechanics below the conversation. You describe the goal to your chosen external controller; that controller decides, while Forge enforces scope, persistence, execution policy, and evidence. Forge never invents an internal agent just because Codex or Claude happens to be installed.
 
-```bash
-forge adopt --repo /path/to/your-project --dry-run
-forge adopt --repo /path/to/your-project
-forge repo list --json
-```
+## Start in minutes
 
-For source development, follow [Install and start](docs/tutorials/01-install-and-start.md) or install the reviewed checkout directly:
+Base install: **Node.js 20.10+, npm (or Bun), and a writable home directory**. Git is only required when you enable repository/software-work features; Codex and Claude are optional.
 
 ```bash
-git clone https://github.com/moretea-labs/forge.git && cd forge
-npm ci --ignore-scripts --no-audit --no-fund
-npm install -g . --omit=optional --no-audit --no-fund
-```
-
-## How ChatGPT uses Forge
-
-The normal ChatGPT connector exposes a bounded **19-tool MCP surface**. Five preferred facades—`rh_status`, `rh_access`, `rh_inbox`, `rh_context`, and `rh_work`—cover most orchestration; repository, source/patch, check, Process, plugin-dispatch, and result tools complete the default surface.
-
-```text
-Small task  → inspect → relevant context → Direct Edit → focused check → commit
-Long task   → resolve identity → durable work only if needed → Process/worktree → verify → integrate → clean
+npm install -g @moretea-labs/forge
+forge setup
+# Recommended path; then follow one Next action at a time:
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
 ```
 
-<p align="center"><img src="docs/images/forge-controller-flow.svg" alt="Forge canonical runtime flow" width="980"></p>
-
-Ask for the outcome, not the tool: “fix this failing test and commit”, “compare these repositories in parallel”, or “run the build and keep using the same Process”.
-
-## Official providers
+Setup persists progress and guides the selected path through the user-level Package Runtime, remote connectivity, controller registration, and connection verification. For ChatGPT, prefer **OpenAI Secure MCP Tunnel** when your organization supports it; Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS `/mcp` URL, or deferred remote access remain alternatives. Local Codex/Claude controllers do not need a tunnel.
 
-| Provider | Purpose | Install |
-| --- | --- | --- |
-| [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | Native macOS desktop automation | `forge plugin install desktop_operator` |
-| [Forge Design](https://github.com/moretea-labs/forge-design) | Repository-native design workspace and `design.md` provider | `forge plugin install design` |
-| [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | Local-first personal knowledge retrieval, memory, and safe writes | `forge plugin install personal_knowledge` |
+Then follow [Install and start](docs/tutorials/01-install-and-start.md) and [Connect ChatGPT](docs/tutorials/02-connect-chatgpt.md). A repository is optional during initial setup; add one later with `forge adopt --repo /path/to/your-project`.
 
-See [Plugin Management](docs/forge-plugin-management.md) for trust, distribution, update, and transport boundaries. Investment Decision System remains an independent product rather than a Forge plugin.
+For a reviewed source checkout: `git clone https://github.com/moretea-labs/forge.git && cd forge && npm ci --ignore-scripts --no-audit --no-fund && npm install -g . --omit=optional --no-audit --no-fund`.
 
-## Safety model
+## Built in, and extensible
 
-Forge distinguishes observation, normal local changes, remote effects, destructive actions, outside-workspace access, and secrets. Full Access reduces repetitive approval for ordinary local work; it does **not** weaken destructive, remote, or secret boundaries. See [Security Model](docs/wiki/Security-Model.md) and [SECURITY.md](SECURITY.md).
+Forge ships typed local/browser/desktop/iOS/GitHub/Gmail/Calendar/Tasks/App Store Connect/Resend capabilities. The public provider catalog currently includes **Forge Desktop Operator**, **Forge Design**, and **Personal Knowledge Assistant**; install with `forge plugin catalog` / `forge plugin install <id>`. See [Features](docs/operations/features.md) and [Plugin Management](docs/forge-plugin-management.md).
 
-## Documentation
+## Controlled by design
 
-- **Start:** [Documentation hub](docs/README.md) · [Wiki](docs/wiki/Home.md) · [Quick Start](docs/wiki/Quick-Start.md) · [Public usage guide](docs/public-usage-guide.md)
-- **Understand:** [Core Concepts](docs/wiki/Core-Concepts.md) · [Architecture](docs/wiki/Architecture.md) · [Work Lifecycle](docs/wiki/Work-Lifecycle.md)
-- **Operate:** [Operations](docs/wiki/Operations.md) · [Troubleshooting](docs/operations/troubleshooting.md) · [Platform support](docs/operations/platform-support.md)
-- **Maintain:** [Contributing](CONTRIBUTING.md) · [Release process](docs/operations/releasing.md) · [Changelog](CHANGELOG.md) · [Support](SUPPORT.md)
+Local read/write grants are explicit and expiring; remote or destructive effects are distinguished from ordinary local work; high-impact actions require stronger confirmation. Full Access reduces repetitive prompts for normal work without removing the hard boundaries around secrets, destructive actions, and outside-workspace access. See [Security](SECURITY.md) and the [Security Model](docs/wiki/Security-Model.md).
 
-**Current release candidate:** `1.5.0-rc.1` on the npm `next` channel. Stable releases use `latest`. Forge is MIT licensed; see [LICENSE](LICENSE), [NOTICE](NOTICE), and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+**Docs:** [Wiki](docs/wiki/Home.md) · [Support](SUPPORT.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md). Current stable release: `1.5.0`; stable installs use npm `latest`.
 
 ---
 <a id="zh-cn"></a>
 
-<p align="center"><img src="docs/images/forge-banner-cn.svg" alt="Forge——本地优先的行动运行时" width="1280"></p>
-<p align="center"><strong>面向 ChatGPT 与 AI 编程助手的本地优先行动运行时。</strong></p>
-<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="docs/forge-plugin-management.md">插件</a> · <a href="https://github.com/moretea-labs/forge/releases">版本</a></p>
+<p align="center"><img src="docs/images/forge-banner-cn.svg" alt="Forge——ChatGPT 决策，Forge 执行" width="1280"></p>
+<p align="center"><strong>让 ChatGPT 真正、安全地操作你的电脑、代码、浏览器和外部服务。</strong></p>
+<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="docs/operations/features.zh-CN.md">功能</a> · <a href="docs/forge-plugin-management.md">插件</a></p>
 
-Forge 让 ChatGPT 在**真实本地仓库、进程、插件与恢复状态**上执行有边界、可审查的工作。小任务默认走最短路径；长任务复用同一个 Process；远程、破坏性、密钥和工作区外访问继续保持明确安全边界。
+**Forge 自己没有 AI 大脑。** 语义判断始终由一个外部主控负责，Forge 负责受控执行、持久状态、权限和恢复。推荐 ChatGPT，也可以明确选择 Codex、Claude 或其他 MCP 客户端；可以预配置多个入口，但同一时刻只有一个主控负责决策。
 
-## 核心能力
+选择 ChatGPT 时**不要求再配置一份 OpenAI API Key，也不需要额外准备一套按 token 计费的模型预算**；仍受你的 ChatGPT 套餐和会话限制。Codex、Claude 没被选中时就不是 Forge 的依赖。
 
-- **Direct-first**：范围明确的小修改不因调查自动创建 Plan、Issue、Agent 或 worktree。
-- **真实并发**：不同仓库可并行；需要隔离时再建立 worktree；同一 checkout 保持单写者。
-- **可恢复执行**：build/test 只启动一次，后续 status/wait/log/cancel 连接同一个 Process。
-- **明确身份**：`repoId + checkoutId` 防止一个会话误操作另一个 checkout。
-- **可验证结果**：diff、focused check、receipt、evidence、不可变 Runtime release 与 Recovery 都可追溯。
-- **类型化插件**：官方 Provider 从固定版本目录安装，并复用 Forge 的授权、资源声明与证据链。
+## Forge 能让 ChatGPT 做什么
 
-## 快速开始
+| 能力 | 用户真正得到什么 |
+| --- | --- |
+| **操作本机** | 授权一个目录后，可列出/读取/写入/复制/移动文件，创建目录，打开文档或 Finder，执行受控命令，查看进程并管理经过身份校验的 macOS LaunchAgent。 |
+| **完成真实开发任务** | 读取和修改仓库、运行测试/构建、操作 Git/worktree、持续跟踪长命令、验证结果、提交并清理临时工作区。 |
+| **浏览器与桌面** | 页面导航、读取、点击、填写、截图、文件传输；需要人工时再 handoff；可使用 Chrome/Vivaldi 原生 attach 与 macOS 桌面能力。 |
+| **Apple 工作流** | iOS 构建、模拟器/设备，以及 App Store Connect 的版本、构建、TestFlight、审核状态和 Xcode Cloud。 |
+| **连接你的服务** | GitHub、Gmail、Google Calendar、Google Tasks、Resend，以及独立发布的 Forge Provider。 |
+| **自动化与可恢复执行** | 长命令不会因为聊天继续而重跑；定时/周期工作可以持久化，在需要判断时再交回 ChatGPT。仓库身份、检查、授权与恢复状态也不只存在于聊天上下文里。 |
 
-```bash
-npm install -g @moretea-labs/forge@next
-forge setup open --target both
-forge setup next     # 重复直到 ready
-forge setup close
-forge doctor
+```text
+“把这个 bug 修好，跑完测试，提交，然后把临时 worktree 清掉。”
+“读取我授权的这个目录，整理文件，并在 Finder 里打开结果。”
+“在 Chrome 里把这个流程走一遍，截图核对，然后修 UI。”
+“汇总今天邮件，把明显广告归档，重要邮件整理给我。”
+“看最新 TestFlight 构建，告诉我离发布还差什么。”
 ```
 
-接入仓库：
+## 快速开始
+
+基础安装只需要 **Node.js 20.10+、npm（或 Bun）和可写用户目录**。Git 只在启用仓库/软件开发能力时需要；Codex、Claude 都是可选项。
 
 ```bash
-forge adopt --repo /path/to/your-project --dry-run
-forge adopt --repo /path/to/your-project
-forge repo list --json
+npm install -g @moretea-labs/forge
+forge setup
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next     # 按每次显示的 Next 动作继续
 ```
 
-普通 ChatGPT Connector 默认收敛为 **19 个 MCP 工具**，其中 `rh_status`、`rh_access`、`rh_inbox`、`rh_context`、`rh_work` 五个 facade 覆盖主要编排。正常使用时直接描述目标，不需要自己挑工具。
-
-## 官方 Provider
+远程主控的 setup 会继续引导 Package Runtime、远程连接、主控配置和连接验证；ChatGPT 在组织支持时优先 **OpenAI Secure MCP Tunnel**，也可选 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp`，或暂缓远程连接。本地 Codex/Claude 主控不需要 tunnel，也不会配置未选择的 CLI。
 
-`forge plugin catalog` 可查看当前目录；官方 Provider 包括 [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator)、[Forge Design](https://github.com/moretea-labs/forge-design) 与 [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant)。详见[插件管理](docs/forge-plugin-management.md)。
+继续阅读[安装与启动](docs/tutorials/01-install-and-start.zh-CN.md)和[连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md)。仓库不是首次 setup 的前置条件，需要开发能力时再运行 `forge adopt --repo /path/to/your-project`。源码安装：`git clone https://github.com/moretea-labs/forge.git && cd forge && npm ci --ignore-scripts --no-audit --no-fund && npm install -g . --omit=optional --no-audit --no-fund`。
 
-## 文档与维护
+Forge 内置本机、Browser、Desktop、iOS、GitHub、Gmail、Calendar、Tasks、App Store Connect、Resend 等类型化能力；公开 Provider 目录还有 **Forge Desktop Operator / Forge Design / Personal Knowledge Assistant**。详见[功能清单](docs/operations/features.zh-CN.md)与[插件管理](docs/forge-plugin-management.md)。
 
-[中文文档中心](docs/README.zh-CN.md) · [安装教程](docs/tutorials/01-install-and-start.zh-CN.md) · [公开使用指南](docs/public-usage-guide.zh-CN.md) · [架构](docs/wiki/Architecture.md) · [故障排查](docs/operations/troubleshooting.zh-CN.md) · [贡献](CONTRIBUTING.md) · [安全](SECURITY.md)
+安全上，普通本地修改、远程影响、破坏性操作、密钥和工作区外访问是不同边界；Full Access 不会取消高风险确认。详见[安全说明](SECURITY.md)和[安全模型](docs/wiki/Security-Model.md)。
 
-**当前候选版本：** `1.5.0-rc.1`，npm 使用 `next`；稳定版使用 `latest`。项目采用 [MIT License](LICENSE)。
+**文档：** [Wiki](docs/wiki/Home.md) · [支持](SUPPORT.md) · [贡献](CONTRIBUTING.md) · [更新日志](CHANGELOG.md)。当前稳定版为 `1.5.0`，稳定安装使用 npm `latest`。

package/README.zh-CN.md

@@ -1,45 +1,62 @@
 # Forge
 
-<p align="center"><img src="docs/images/forge-banner-cn.svg" alt="Forge——本地优先的行动运行时" width="1280"></p>
-<p align="center"><strong>面向 ChatGPT 与 AI 编程助手的本地优先行动运行时。</strong></p>
-<p align="center"><a href="README.md#english">English</a> · <a href="README.md#zh-cn">仓库首页中文</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="https://github.com/moretea-labs/forge/releases">版本发布</a></p>
-<p align="center"><img alt="CI" src="https://github.com/moretea-labs/forge/actions/workflows/ci.yml/badge.svg"> <img alt="Release" src="https://img.shields.io/github/v/release/moretea-labs/forge?include_prereleases&sort=semver"> <img alt="npm next" src="https://img.shields.io/npm/v/%40moretea-labs%2Fforge?tag=next&label=npm%20next"> <img alt="License" src="https://img.shields.io/github/license/moretea-labs/forge"></p>
+<p align="center"><img src="docs/images/forge-banner-cn.svg" alt="Forge——ChatGPT 决策，Forge 执行" width="1280"></p>
+<p align="center"><strong>让 ChatGPT 真正、安全地操作你的电脑、代码、浏览器和外部服务。</strong></p>
+<p align="center"><a href="https://github.com/moretea-labs/forge#english">English</a> · <a href="https://github.com/moretea-labs/forge#zh-cn">仓库首页中文</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="docs/operations/features.zh-CN.md">功能清单</a> · <a href="https://github.com/moretea-labs/forge/releases">版本发布</a></p>
+<p align="center"><img alt="CI" src="https://github.com/moretea-labs/forge/actions/workflows/ci.yml/badge.svg"> <img alt="Release" src="https://img.shields.io/github/v/release/moretea-labs/forge?include_prereleases&sort=semver"> <img alt="npm latest" src="https://img.shields.io/npm/v/%40moretea-labs%2Fforge?tag=latest&label=npm%20latest"> <img alt="License" src="https://img.shields.io/github/license/moretea-labs/forge"></p>
 
-Forge 让 ChatGPT 在**真实本地仓库、进程、插件和恢复状态**上执行有边界、可审查的工作。它把 Git、Process、检查和发布证据保存在聊天之外，小任务走最短路径，长任务复用同一个执行生命周期。
+**Forge 自己没有 AI 大脑。** 每次语义决策都由一个外部主控负责，Forge 负责执行、持久状态、权限和恢复。默认推荐 ChatGPT，也可以明确选择 Codex、Claude 或其他 MCP 客户端；可以配置多个控制入口，但同一时刻只有一个主控拥有语义控制权。
 
-## 为什么使用 Forge
+选择 ChatGPT 时**不要求单独配置 OpenAI API Key，也不需要额外准备一套按 token 计费的模型预算**；仍受你的 ChatGPT 套餐和会话限制。没有选择 Codex/Claude，就不会把它们当成安装或就绪依赖。
 
-| 需求 | Forge 的处理方式 |
+## 为什么这和普通 Coding Agent 不一样
+
+- **外部主控就是大脑**：推荐把 ChatGPT 对话作为主工作台；也可明确让 Codex、Claude 或其他 MCP 客户端担任主控，Forge 本身不参与语义决策。
+- **不只会写代码**：同一个对话可以处理目录文件、命令、浏览器、桌面、邮件、日历、GitHub、iOS 与 App Store Connect。
+- **真实执行状态在聊天之外**：长命令、检查、仓库身份、授权和恢复状态可以继续接上；定时/周期任务也可以持久化，在需要判断时再交回 ChatGPT。
+- **没选就不依赖**：Codex/Claude 不会因为安装在机器上就进入 Forge readiness；只有你明确配置它们为主控或外部执行入口时才检查。
+- **权限不是全有或全无**：本机目录授权可过期；远程、破坏性、密钥和工作区外访问有独立边界。
+
+## 你可以直接这样说
+
+```text
+“把这个 bug 修好，跑完测试，提交，然后把临时 worktree 清掉。”
+“读取我授权的这个目录，整理文件，并在 Finder 里打开结果。”
+“在 Chrome 里把这个流程走一遍，截图核对，然后修 UI。”
+“汇总今天邮件，把明显广告归档，重要邮件整理给我。”
+“看最新 TestFlight 构建，告诉我离发布还差什么。”
+```
+
+## 现在能做什么
+
+| 领域 | 典型能力 |
 | --- | --- |
-| 操作真实代码 | 使用稳定的 `repoId + checkoutId` 绑定目标仓库和 checkout。 |
-| 小任务不要重流程 | Direct-first；仅调查不会自动创建 Plan、Issue、Agent 或 worktree。 |
-| 长命令不要重复跑 | Process Runtime 只启动一次，后续 status/wait/log/cancel 连接同一个 Process。 |
-| 多仓库并发工作 | 不同仓库可并行；真正需要隔离时才建立 worktree。 |
-| 结果能够复核 | diff、focused check、receipt、evidence、不可变 Runtime release 与 Recovery 都可追溯。 |
-| 安全扩展能力 | 官方 Provider 从固定版本目录安装，复用 Forge 的授权、资源声明和证据链。 |
+| **本机文件与命令** | 授权目录后列出/读取/写入/复制/移动文件、创建目录、打开文件/Finder、typed command、校验过的项目脚本、系统与进程诊断、macOS LaunchAgent 管理。 |
+| **软件开发** | 多仓库读取与修改、Git、patch、测试/构建、长进程、worktree、验证、提交与清理；支持 Direct-first 的快速任务路径。 |
+| **Browser / Desktop** | 页面导航、读取、选择器、点击、填写、截图、文件传输、人工 handoff；Chrome/Vivaldi 原生 attach；macOS Desktop 与可安装的 Desktop Operator。 |
+| **Apple** | iOS 项目/模拟器/设备；App Store Connect 应用、版本、Build、TestFlight、审核信息和 Xcode Cloud workflow。 |
+| **生产力服务** | GitHub Issue/Project、Gmail、Google Calendar、Google Tasks、Resend Email。 |
+| **扩展能力** | 官方目录中的 Forge Design、Personal Knowledge Assistant、Desktop Operator；外部 Provider 仍复用 Forge 的权限和执行边界。 |
+
+> 具体能力依赖操作系统、已安装 Provider、账号授权和目标服务配置。Forge 不会因为 README 写了某项能力就绕过平台权限或服务认证。
 
 ## 快速开始
 
-需要 Git、Node.js 20.10+、npm 和可写用户目录。源码开发建议安装 Bun 1.0+。
+基础安装只需要 **Node.js 20.10+、npm（或 Bun）和可写用户目录**；Git 只在启用仓库/软件开发能力时需要，源码开发建议 Bun 1.0+。
 
 ```bash
-npm install -g @moretea-labs/forge@next
+npm install -g @moretea-labs/forge
 forge --version
-forge setup open --target both
-forge setup next     # 重复直到 ready
-forge setup close
-forge doctor
+forge setup
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next     # 按每次显示的 Next 动作继续
 ```
 
-接入仓库：
+`forge setup` 会持久化进度。远程主控会继续经过 Package Runtime、远程连接、主控配置和连接验证；ChatGPT 在组织支持时优先 **OpenAI Secure MCP Tunnel**，也可选择 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接。本地主控 Codex/Claude 不需要 tunnel。
 
-```bash
-forge adopt --repo /path/to/your-project --dry-run
-forge adopt --repo /path/to/your-project
-forge repo list --json
-```
+接着阅读：[安装与启动](docs/tutorials/01-install-and-start.zh-CN.md) · [连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md) · [第一个仓库任务](docs/tutorials/03-first-repository-task.zh-CN.md)。仓库不是首次 setup 的前置条件；需要时再 `forge adopt --repo /path/to/your-project`。
 
-接下来按[连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md)和[完成第一个仓库任务](docs/tutorials/03-first-repository-task.zh-CN.md)继续。源码开发可使用：
+从源码安装已审查 checkout：
 
 ```bash
 git clone https://github.com/moretea-labs/forge.git && cd forge
@@ -47,38 +64,16 @@ npm ci --ignore-scripts --no-audit --no-fund
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 
-## ChatGPT 如何使用 Forge
-
-普通 ChatGPT Connector 默认是 **19 个 MCP 工具**。五个主要 facade——`rh_status`、`rh_access`、`rh_inbox`、`rh_context`、`rh_work`——覆盖日常编排，其余默认工具负责仓库、源码/补丁、check、Process、插件分发和结果读取。
-
-```text
-小任务 → 状态/上下文 → Direct Edit → focused check → commit
-长任务 → 确定身份 → 确有需要才建 durable work → Process/worktree → verify → integrate → clean
-```
-
-<p align="center"><img src="docs/images/forge-controller-flow.svg" alt="Forge Canonical Runtime 流程" width="980"></p>
-
-正常使用时直接描述目标即可，不需要自己挑工具。
-
-## 官方 Provider
-
-| Provider | 用途 | 安装 |
-| --- | --- | --- |
-| [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | macOS 原生桌面操作 | `forge plugin install desktop_operator` |
-| [Forge Design](https://github.com/moretea-labs/forge-design) | 仓库原生设计工作区和 `design.md` | `forge plugin install design` |
-| [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | 本地优先个人知识检索、记忆与安全写入 | `forge plugin install personal_knowledge` |
+## 插件与能力
 
-Forge 不扫描用户本机 sibling 仓库，也不允许模型临时提供任意 executable。完整边界见[插件管理](docs/forge-plugin-management.md)。Investment Decision System 保持独立产品，不进入 Forge 官方插件目录。
+Forge 内置本机、Browser、Desktop、iOS、GitHub、Gmail、Calendar、Tasks、App Store Connect、Resend 等类型化插件；公开 Provider 目录还提供 **Forge Desktop Operator**、**Forge Design**、**Personal Knowledge Assistant**。运行 `forge plugin catalog` 查看当前固定版本目录，详见[插件管理](docs/forge-plugin-management.md)和[功能清单](docs/operations/features.zh-CN.md)。
 
-## 安全模型
+## 安全不是宣传词
 
-Forge 区分读取、普通本地修改、远程影响、破坏性操作、工作区外访问和密钥访问。Full Access 只减少普通本地工作的重复授权，不会削弱 destructive、remote 或 secret 边界。详见[安全模型](docs/wiki/Security-Model.md)和 [SECURITY.md](SECURITY.md)。
+Forge 把读取、普通本地写入、远程操作、破坏性操作、工作区外访问和密钥访问分开处理。本机目录采用显式授权；高风险行为需要更强确认。Full Access 只减少普通工作的重复提示，不会取消这些硬边界。详见 [SECURITY.md](SECURITY.md) 和[安全模型](docs/wiki/Security-Model.md)。
 
-## 文档
+## 文档与项目
 
-- **开始使用：** [中文文档中心](docs/README.zh-CN.md) · [安装](docs/tutorials/01-install-and-start.zh-CN.md) · [公开使用指南](docs/public-usage-guide.zh-CN.md)
-- **理解系统：** [Wiki](docs/wiki/Home.md) · [核心概念](docs/wiki/Core-Concepts.md) · [架构](docs/wiki/Architecture.md) · [工作生命周期](docs/wiki/Work-Lifecycle.md)
-- **运维维护：** [故障排查](docs/operations/troubleshooting.zh-CN.md) · [平台支持](docs/operations/platform-support.zh-CN.md) · [发布流程](docs/operations/releasing.zh-CN.md)
-- **参与项目：** [贡献](CONTRIBUTING.md) · [安全](SECURITY.md) · [支持](SUPPORT.md) · [版本记录](CHANGELOG.md)
+[中文文档中心](docs/README.zh-CN.md) · [Wiki](docs/wiki/Home.md) · [SUPPORT.md](SUPPORT.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md)
 
-**当前候选版本：** `1.5.0-rc.1`，npm 使用 `next`；稳定版本使用 `latest`。项目采用 [MIT License](LICENSE)。
+当前稳定版本是 `1.5.0`，稳定安装使用 npm `latest`。

package/SKILL.md

@@ -36,15 +36,14 @@ Treat ChatGPT as the controller and Forge as its repository execution layer. Cha
 - Hard runtime boundaries remain for secrets, credentials, Git internals, concurrent write conflicts, out-of-scope writes when a scope is declared, and remote or irreversible side effects.
 ## Explicit mode directives
 
-Automatic routing remains authoritative when the user does not provide a mode directive. In particular, understood bounded work still defaults to Direct Edit; adding explicit modes must not make ordinary requests Plan-first, Agent-first, Issue-first, or Campaign-first.
+Automatic routing remains authoritative when the user does not provide a mode directive. In particular, understood bounded work still defaults to Direct Edit; adding explicit modes must not make ordinary requests Plan-first, Agent-first, Issue-first.
 
 A leading mode directive is an opt-in instruction to ChatGPT's Forge router. It applies only to the current request, is removed from the objective before execution, and never bypasses permissions, Runtime authority, protected-path rules, approvals, or destructive/remote-write confirmation.
 
 - `-plan` or `/plan`: force the reviewed planning path. Planning is read-only: inspect repository state and call `controller_context_pack` with `structural_context=required` so CodeGraph symbol/reference/dependency/impact evidence is used when the index is ready; load only relevant architecture/ADR/design/README material, then create or revise the existing PlanContract. Review the PlanContract before approval. Do not start mutation until the reviewed plan is approved and execution is explicitly bound to an approved plan step. If CodeGraph is unavailable or stale, keep the degraded evidence warning visible and use bounded current-source context instead of pretending graph coverage exists.
-- `-debug` or `/debug`: force evidence-first debugging. Reproduce or characterize the failure, then prefer `controller_context_pack` with `structural_context=auto` to isolate callers, dependencies, and the smallest causal surface before patching and focused verification. The directive does not force an Agent or Campaign; existing routing still chooses Direct, bounded Work, or an optional worker from the actual scope and risk.
-- `-campaign` or `/campaign`: force the durable Campaign topology for the current request. Use Campaign review checkpoints and independent task coordination even when automatic routing would otherwise choose Direct or bounded Work. This is an explicit user override of topology, not a permission override.
+- `-debug` or `/debug`: force evidence-first debugging. Reproduce or characterize the failure, then prefer `controller_context_pack` with `structural_context=auto` to isolate callers, dependencies, and the smallest causal surface before patching and focused verification. The directive does not force an Agent or durable Work; existing routing still chooses Direct, bounded Work, or an optional worker from the actual scope and risk.
 
-A bare directive with no objective should return/explain that mode's working contract and must not mutate repository state. Mode directives are not sticky across turns unless the user repeats them or explicitly asks to continue the same active Plan/Campaign.
+A bare directive with no objective should return/explain that mode's working contract and must not mutate repository state. Mode directives are not sticky across turns unless the user repeats them or explicitly asks to continue the same active Plan/Work.
 
 ## When to use
 
@@ -268,7 +267,7 @@ specific model providers, vector DBs, workflow engines, tracing vendors, or
 sidecar languages mandatory defaults.
 
 Scaffold is not an existing-repo adoption path. If the target already has a
-product tree, use `forge init`, `forge migrate`,
+product tree, use `forge adopt`, `forge setup`,
 `forge upgrade`, or `forge repair` and preserve the existing app
 shape. `create-project-dirs`, `hooks-init`, and `docs-init` remain internal
 steps behind public commands, not standalone user-facing scaffold aliases.
@@ -302,12 +301,10 @@ Migration defaults:
 - move hidden contracts and deep findings into topic-scoped `docs/researches/*.md`
 - distill repeated corrections into `tasks/lessons.md`
 - merge missing `external_tooling` defaults into `.ai/harness/policy.json` without overwriting explicit user values
-- keep gstack/gbrain/CodeGraph detection advisory-only; do not auto-install, auto-upgrade, auto-sync, or auto-enable MCP
-- let `forge init` bootstrap the required global runtime in one pass:
-  CLI install, forge runtime alias sync, user-level hook adapters, Waza
-  (`think`, `hunt`, `check`, `health`), Mermaid, brain root persistence, and
-  CodeGraph CLI/MCP configuration
-- treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source, `~/.agents/skills` is only skills CLI staging/cache, and updates require stage -> copy to Codex -> `cmp` verification
+- keep Waza, gstack, gbrain, Mermaid, and cross-review host skills optional; detect them but never make normal Forge execution depend on them
+- `forge install` bootstraps only Forge-owned runtime and host adapters by default; install third-party host skills only with `--with-external-skills`
+- Forge task routing uses `/direct`, `/plan`, `/debug`, `/review`, `/release`, and `/scale`; optional host skills may refine those workflows when already installed
+- distinguish the bundled CodeGraph read backend used by `rh_context` from an optional global CodeGraph CLI/MCP integration; missing global CLI is not Runtime unready
 
 ## Repo-Local Contract
 

package/THIRD_PARTY_NOTICES.md

@@ -1,8 +1,8 @@
 # Third-party notices
 
-This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.5.0-rc.1`.
+This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.5.0`.
 
-License values come from `package-lock.json` where available. For lock entries without a license field, the declared license was verified from package metadata during release-candidate preparation. This file is informational and does not replace the license text distributed by each dependency.
+License values come from `package-lock.json` where available. For lock entries without a license field, the declared license was verified from package metadata during release preparation. This file is informational and does not replace the license text distributed by each dependency.
 
 | Package | Version | Role | Declared license | Source |
 | --- | --- | --- | --- | --- |
@@ -10,9 +10,15 @@ License values come from `package-lock.json` where available. For lock entries w
 | `commander` | `14.0.3` | runtime | `MIT` | package metadata |
 | `express` | `5.2.1` | runtime | `MIT` | package metadata |
 | `playwright` | `1.61.1` | runtime | `Apache-2.0` | package metadata |
+| `react` | `19.2.8` | runtime | `MIT` | package metadata |
+| `react-dom` | `19.2.8` | runtime | `MIT` | package metadata |
 | `agent-device` | `0.20.2` | optional runtime (iOS/Android device automation provider) | `MIT` | package-lock.json |
 | `@colbymchenry/codegraph` | `1.0.1` | development | `MIT` | package-lock.json |
 | `@types/bun` | `1.3.14` | development | `MIT` | package-lock.json |
 | `@types/cors` | `2.8.19` | development | `MIT` | package-lock.json |
 | `@types/express` | `5.0.6` | development | `MIT` | package-lock.json |
-| `typescript` | `6.0.3` | development | `Apache-2.0` | package metadata |
+| `@types/react` | `19.2.18` | development | `MIT` | package metadata |
+| `@types/react-dom` | `19.2.4` | development | `MIT` | package metadata |
+| `@vitejs/plugin-react` | `5.2.0` | development | `MIT` | package metadata |
+| `typescript` | `6.0.3` | runtime | `Apache-2.0` | package metadata |
+| `vite` | `7.3.6` | development | `MIT` | package metadata |

package/assets/branding/README.md

@@ -2,9 +2,11 @@
 
 These files are the maintained, public-safe, first-party branding assets for **Forge**.
 
-- `docs/images/forge-banner.svg`: English README and social-share banner.
-- `docs/images/forge-banner-cn.svg`: Simplified Chinese README and social-share banner.
+- `docs/images/forge-banner.svg`: English product hero / social-share banner — **ChatGPT decides. Forge acts.**
+- `docs/images/forge-banner-cn.svg`: Simplified Chinese product hero / social-share banner — **ChatGPT 决策，Forge 执行。**
 - `docs/images/forge-controller-flow.svg`: current Forge controller and Runtime architecture diagram.
 - `forge-controller-flow.mmd`: editable Mermaid source for the architecture diagram.
 
+The README hero should communicate the product before the architecture: ChatGPT is the controller; Forge is the controlled action layer for local files, commands, code, browser/desktop, Apple workflows, and typed plugins.
+
 Use **Forge** in prose and lowercase `forge` only for commands, package paths, protocol identifiers, state paths, filenames, or code symbols. Do not add previous-product branding, compatibility messaging, third-party logos, trademarks, or stock illustrations.

package/assets/hooks/lib/workflow-state.sh

@@ -91,7 +91,7 @@ workflow_runs_dir() {
 }
 
 workflow_resume_packet_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.handoff_resume.resume_packet_file' '.ai/harness/handoff/resume.md')" '.ai/harness/handoff/resume.md' '.ai/harness/'
+  workflow_repo_relative_path "$(workflow_policy_get '.session.resume_file' '.ai/harness/session/resume.md')" '.ai/harness/session/resume.md' '.ai/harness/'
 }
 
 workflow_pending_orchestration_file() {
@@ -104,14 +104,14 @@ workflow_ensure_harness_surface() {
     "$(dirname "$(workflow_context_map_file)")" \
     "$(dirname "$(workflow_policy_file)")" \
     "$(dirname "$(workflow_checks_file)")" \
-    "$(dirname "$(workflow_handoff_file)")" \
+    "$(dirname "$(workflow_session_continuation_file)")" \
     "$(dirname "$(workflow_resume_packet_file)")" \
     "$(dirname "$(workflow_failure_log_file)")" \
     "$(dirname "$(workflow_pending_orchestration_file)")" \
     "$(workflow_runs_dir)"
 
   [[ -f "$(workflow_checks_file)" ]] || printf "{}\n" > "$(workflow_checks_file)"
-  [[ -f "$(workflow_handoff_file)" ]] || printf "# Harness Handoff\n\n> **Reason**: bootstrap\n" > "$(workflow_handoff_file)"
+  [[ -f "$(workflow_session_continuation_file)" ]] || printf "# Forge Session Continuation Snapshot\n\n> **Reason**: bootstrap\n" > "$(workflow_session_continuation_file)"
   [[ -f "$(workflow_resume_packet_file)" ]] || printf "# Codex Resume Packet\n\n> **Reason**: bootstrap\n" > "$(workflow_resume_packet_file)"
   [[ -f "$(workflow_failure_log_file)" ]] || : > "$(workflow_failure_log_file)"
   [[ -f "$(workflow_events_file)" ]] || : > "$(workflow_events_file)"
@@ -606,17 +606,17 @@ workflow_next_action() {
     checks_file="$(workflow_checks_file)"
 
     if [[ -z "$review_file" || ! -f "$review_file" ]]; then
-      printf 'check\t/check\tStage the completed module diff first; then run /check and record a sprint review before finishing this worktree.\n'
+      printf 'review\t/review\tStage the completed module diff first; then run /review and record a sprint review before finishing this worktree.\n'
       return 0
     fi
 
     if ! workflow_review_recommends_pass "$review_file"; then
-      printf 'check\t/check\tStage the completed module diff first; then run /check until %s records Recommendation: pass.\n' "$review_file"
+      printf 'review\t/review\tStage the completed module diff first; then run /review until %s records Recommendation: pass.\n' "$review_file"
       return 0
     fi
 
     if [[ -z "$contract_file" || ! -f "$contract_file" ]]; then
-      printf 'check\t/check\tStage the completed module diff first; then regenerate the active sprint contract and run /check.\n'
+      printf 'check\t/check\tStage the completed module diff first; then regenerate the active sprint contract and run /review.\n'
       return 0
     fi
 
@@ -629,7 +629,7 @@ workflow_next_action() {
     fi
 
     if [[ ! -f "$checks_file" ]]; then
-      printf 'check\t/check\tStage the completed module diff first; then run /check and verify-sprint so %s exists.\n' "$checks_file"
+      printf 'review\t/review\tStage the completed module diff first; then run /review and verify-sprint so %s exists.\n' "$checks_file"
       return 0
     fi
 
@@ -1111,8 +1111,8 @@ workflow_checks_file() {
   workflow_repo_relative_path "$(workflow_policy_get '.harness.checks_file' '.ai/harness/checks/latest.json')" '.ai/harness/checks/latest.json' '.ai/harness/'
 }
 
-workflow_handoff_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.handoff_file' '.ai/harness/handoff/current.md')" '.ai/harness/handoff/current.md' '.ai/harness/'
+workflow_session_continuation_file() {
+  workflow_repo_relative_path "$(workflow_policy_get '.session.continuation_file' '.ai/harness/session/continuation.md')" '.ai/harness/session/continuation.md' '.ai/harness/'
 }
 
 # mkdir-based mutual exclusion (macOS ships no flock). Spins ~2s, breaks locks
@@ -1258,7 +1258,7 @@ workflow_write_run_summary() {
       --arg active_review "${active_review:-}" \
       --arg active_notes "${active_notes:-}" \
       --arg checks_file "$(workflow_checks_file)" \
-      --arg handoff_file "$(workflow_handoff_file)" \
+      --arg handoff_file "$(workflow_session_continuation_file)" \
       --arg policy_file "$(workflow_policy_file)" \
       --arg context_map_file "$(workflow_context_map_file)" \
       '{
@@ -1278,7 +1278,7 @@ workflow_write_run_summary() {
   fi
 
   cat > "$output_file" <<EOF_RUN
-{"generated_at":"$(workflow_json_escape "$(date '+%Y-%m-%dT%H:%M:%S%z')")","run_id":"$(workflow_json_escape "$run_id")","reason":"$(workflow_json_escape "$reason")","checks_file":"$(workflow_json_escape "$(workflow_checks_file)")","handoff_file":"$(workflow_json_escape "$(workflow_handoff_file)")"}
+{"generated_at":"$(workflow_json_escape "$(date '+%Y-%m-%dT%H:%M:%S%z')")","run_id":"$(workflow_json_escape "$run_id")","reason":"$(workflow_json_escape "$reason")","checks_file":"$(workflow_json_escape "$(workflow_checks_file)")","handoff_file":"$(workflow_json_escape "$(workflow_session_continuation_file)")"}
 EOF_RUN
 }
 
@@ -1531,16 +1531,17 @@ workflow_contract_allows_path() {
 
   return 1
 }
-workflow_write_handoff() {
+workflow_write_session_continuation() {
+  # This file is a rebuildable host-session cache. Runtime HandoffItem/rh_inbox owns decisions that require ChatGPT or user judgement.
   local reason="${1:-session-stop}"
-  local handoff_file active_plan active_contract active_review active_notes checks_file next_task changed_files diff_stat spec_file source_plan parent_run_id supersedes
+  local continuation_file active_plan active_contract active_review active_notes checks_file next_task changed_files diff_stat spec_file source_plan parent_run_id supersedes
   local next_action next_stage next_command next_message
   local resume_file trace_file recent_commands blockers decisions goal latest_trace_file
   local active_sprint active_sprint_row
   local changed_count untracked_count
 
   workflow_ensure_harness_surface
-  handoff_file="$(workflow_handoff_file)"
+  continuation_file="$(workflow_session_continuation_file)"
   checks_file="$(workflow_checks_file)"
   resume_file="$(workflow_resume_packet_file)"
   spec_file="docs/spec.md"
@@ -1637,7 +1638,7 @@ workflow_write_handoff() {
   else
     goal="No active plan. Continue from the latest user request and filesystem state."
   fi
-  decisions="Use filesystem artifacts as source of truth; treat SQLite/thread state as a rebuildable read model only."
+  decisions="Canonical Runtime control-plane state is authoritative for migrated repositories. This snapshot is a non-authoritative, rebuildable session continuation cache derived from current source artifacts and evidence."
   blockers="(none recorded)"
   if [[ -f "$checks_file" ]] && command -v jq >/dev/null 2>&1; then
     latest_trace_file="$(jq -r '.run_file // empty' "$checks_file" 2>/dev/null || true)"
@@ -1646,8 +1647,8 @@ workflow_write_handoff() {
   fi
   latest_trace_file="${latest_trace_file:-$checks_file}"
 
-  cat > "$handoff_file" <<EOF_HANDOFF
-# Harness Handoff
+  cat > "$continuation_file" <<EOF_HANDOFF
+# Forge Session Continuation Snapshot
 
 > **Generated**: $(date '+%Y-%m-%d %H:%M:%S')
 > **Reason**: ${reason}
@@ -1695,7 +1696,7 @@ ${recent_commands}
 ## Resume Prompt
 
 - Resume packet: ${resume_file}
-- Start a fresh Codex session and read source artifacts first, then this handoff, before continuing; do not rely on auto-compact.
+- Start a fresh host session and read the current user input and Canonical Runtime state first. Use this snapshot only as bounded recovery context; do not treat it as lifecycle authority.
 
 ## Source Artifacts