@moretea-labs/forge 1.8.0 → 1.8.2

package/docs/operations/mcp-tool-exposure.md

@@ -1,60 +1,21 @@
-# MCP tool exposure profiles
+# MCP capability surface
 
-Controller MCP uses one stable default schema so ChatGPT can reliably read, edit, run checks, use Git, delegate to local Agents, coordinate durable Goal/Work, capture iOS evidence, and recover from failures without a permission switch hiding tools.
+Forge exposes one complete MCP `tools/list` registry. There is **no toolset selector**: the former `facade`, `core`, `advanced`, and `full` exposure modes no longer select different schemas. Each currently registered capability is discoverable and retains its own typed validation and execution authority.
 
-## Profiles
+The model may prefer the small `rh_*` entry points, `execute_command`, `capability_execute`, and `plugin_action_execute` for ordinary work, but preference is guidance, not a visibility gate. `adapters/mcp/toolset-names.ts` retains a small *preferred-name reference* for connector freshness and ergonomic routing; it is not a second public tool inventory. `adapters/mcp/toolset.ts` assembles the actual tool definitions once from the current module registries, returning the canonical ordered names and schema fingerprint to MCP discovery, health, status and connection diagnostics.
 
-| Toolset | CLI | Behavior |
-| --- | --- | --- |
-| **facade** (opt-in) | `--toolset facade` | Five-tool ChatGPT orchestration surface: `rh_access`, `rh_status`, `rh_inbox`, `rh_context`, `rh_work`. Internal handlers and capabilities remain registered; only MCP discovery is reduced. Intended for latency/tool-selection A/B before any default migration. |
-| **advanced** (default) | `--toolset advanced` | Current stable 19-tool controller surface. Includes the five `rh_*` facades plus repository, Direct Edit, command, check, plugin-dispatch, Process, and result/evidence tools. |
-| **core** | `--toolset core` | Compatibility label for the same stable default 19-tool schema. It does not reduce capability or require reconnecting. |
-| **full** | `--toolset full` | Every historical legacy and runtime definition. Use only for old integrations or deep compatibility diagnosis because the much larger schema can reduce tool-selection quality. |
+## Execution authority
 
-Configure via CLI flags, `FORGE_MCP_TOOLSET`, or Controller Home MCP config. Empty/default controller configuration resolves to `advanced`.
+- `execute_command`: general repository/workspace terminal and explicitly granted ForgeInstance host processes; Process Runtime owns execution and receipts.
+- `capability_execute`: core typed capability actions owned by their canonical domain module.
+- `plugin_action_execute`: external plugin actions owned by their provider authority.
+- Other typed tools remain callable until their callers are migrated to a genuinely equivalent canonical action. Do not delete an operation simply to reduce `tools/list` count.
+- Access modes (request/full access) and host/OS grants control *execution*, never tool discovery. Changing permissions does not add or hide tools.
 
-## Single source of truth
+The MCP transport publishes the complete static schema; it cannot dynamically load tools for a selected domain. Any removal or schema change requires a current-host connector refresh according to actual connector support, but does not justify retaining a second toolset profile. Historical persisted `toolset` fields never select an exposure mode. A previous `core`-only configuration is interpreted once as Request permission (to avoid silently widening access), and the obsolete selector is cleared on the next canonical configuration write.
 
-`src/cli/mcp/toolset-names.ts` owns the dependency-free stable name list. `src/cli/mcp/toolset.ts` joins that list with the actual definition registry and returns one exposure snapshot containing:
+## Performance and maintenance
 
-- expected and actual tool names/counts;
-- missing, unexpected, and duplicate names;
-- schema fingerprint;
-- readiness.
+A large `tools/list` can increase initial schema/context cost and tool selection ambiguity. Optimize this by measuring actual discover-to-action latency, schema bytes, routing errors and total calls to complete a task, then **migrating and deleting redundant public tools**, not by creating hidden profiles or duplicate authority. Retain typed semantics, remote mutation receipts and process observation where a shell-only replacement would lose safety or reliability.
 
-MCP `tools/list`, call validation, `/health`, `controller_ready`, `rh_status`, Connector freshness, and the Local Controller UI derive from this contract. Readiness cannot be `ready` while required tools are missing.
-
-## Three-layer tool contract
-
-The current implementation separates orchestration from capability without deleting product functions:
-
-1. **Workflow facade:** `rh_status`, `rh_access`, `rh_inbox`, `rh_context`, and `rh_work` are the preferred ChatGPT control-plane entry points.
-2. **Typed atomic tools:** repository inspection, Direct Edit, command, Git, Work/Job, Issue/Task, Goal/Work, plugin, browser, iOS, artifact, and recovery handlers remain public because their schemas preserve operation-specific validation and evidence.
-3. **Internal handlers and capability registry:** capabilities are grouped as `controller`, `repository-core`, `git`, `issue-task`, `browser`, `ios`, `plugin`, `evidence`, and `runtime-maintenance`. `rh_status`, `rh_context`, and `controller_capabilities` expose this metadata.
-
-The MCP transport publishes a static schema for each selected toolset. It does **not** dynamically load a domain schema after ChatGPT selects that domain. The opt-in `facade` toolset reduces initial discovery to five facade tools while retaining the same internal handlers; `core`/`advanced` keep the current 19-tool stable schema and `full` keeps the exhaustive compatibility schema.
-
-Capability metadata changes do not change `tools/list`; restart the Controller to load new code, but reconnect/rescan ChatGPT only when tool names or input schemas change.
-
-## Permissions
-
-Request/Full Access is an execution-policy decision below tool discovery. Switching access mode does not change the schema, does not require an MCP restart, and does not require reconnecting ChatGPT.
-
-Remote writes, destructive actions, outside-repository paths, and secret access remain independently gated.
-
-## Guidance
-
-- Prefer `rh_status`, `rh_access`, `rh_context`, `rh_work`, and `rh_inbox` for normal orchestration.
-- Use first-class Direct Edit, command, Git, `quick_agent_session`, Goal/Work, iOS, plugin, and artifact tools when the facade is not the shortest reliable path.
-- Use `--toolset facade` only for explicit experiments/clients until latency and workflow coverage are validated; the default remains the stable 19-tool surface.
-- Keep the stable surface unique and at or below 128 tools.
-- Add new public tools only when they unlock a real end-to-end workflow; otherwise route capabilities through an existing facade or plugin action.
-
-## Related checks
-
-```bash
-bun test tests/cli/mcp-tool-exposure-profiles.test.ts
-bun test tests/cli/connector-freshness.test.ts
-bun test tests/runtime/facade-mcp-surface.test.ts
-bun run check:mcp-compatibility
-```
+Every source change should preserve the one-inventory invariant, the current permission model and the real MCP `tools/list` plus execution-path acceptance checks. No Runtime cutover is implied by a source-only change.

package/docs/operations/releasing.md

@@ -34,6 +34,8 @@ bun bin/forge.mjs --help
 
 The main gate reuses the focused task receipt and does not run the full suite. The release gate reuses that receipt, verifies package identity, documentation, licenses and notices, tracked-file hygiene and public export contents, then creates one tarball under `.ai/harness/artifacts/release/`. Isolated installation and publication consume that same tarball. `test:full` is a manual diagnostic only.
 
+The committed `package-lock.json` must resolve all distribution artifacts through the public `https://registry.npmjs.org/` origin with unchanged integrity checksums. Local npm mirrors and private CI package gateways must not become dependencies of the public source archive. An isolated install timeout is an incomplete release gate, not a passing smoke test.
+
 ## Bootstrap npm publication (only while the package does not exist)
 
 npm Trusted Publishing cannot be configured for a package that does not exist yet. The bootstrap publication therefore requires an npm maintainer for the `@moretea-labs` scope with two-factor authentication. Because this one-time local path has no OIDC provider, `NPM_RELEASE_BOOTSTRAP=1` disables provenance only for that bootstrap publish; `publishConfig.provenance` remains `true` for normal GitHub OIDC releases.

package/docs/operations/runtime-performance-diagnostics.md

@@ -12,3 +12,11 @@ It is intended for questions such as:
 The tool returns controller queue state, bounded Forge process samples, orphan worker detection, Local Controller process inference, temporary directory accumulation, and a no-side-effect cleanup preview.
 
 The cleanup preview is intentionally non-destructive. Terminating processes or deleting temporary directories must remain a separate explicit operation.
+
+## Quality Harness benchmark evidence
+
+`bun run check:quality-harness` runs `scripts/benchmark-quality-harness.ts` on an isolated temporary Git repository. It checks cache correctness and latency, a successful physical `git status` invocation, and the lightweight Process lane. Empty optional structural timing samples are reported as `null`, never invented as `0 ms`; a missing required pre-spawn sample fails the check.
+
+`durableProcessWrites` and `leaseOperations` are **runtime-reported** execution metrics collected per invocation, not independently instrumented physical-write/lease counters. `durableProcessRecordsObserved` is a separate read of the canonical managed Process store for each returned lightweight process ID. `persistedHandleIndexEntriesObserved` independently reads the existing SQLite handle-index projection and **must equal the number of commands**, because lightweight commands do persist handles even though they do not create managed Process records. Neither metric claims zero total filesystem/SQLite writes or measures write frequency. No result may be presented as proof of zero underlying operations beyond the evidence each observer covers. The benchmark is an internal diagnostic gate, **not** a cross-version superiority verdict; formal comparisons remain under `evaluation/` with frozen candidate and environment identities.
+
+The governed `check:main` candidate gate enforces the frozen MCP public Tool Contract via `check:mcp-compatibility` and runs `check:quality-harness` after the reusable task receipt; normal `check:task`/inner-loop checks do **not** run it. The `check:release` gate inherits the main result rather than creating another Benchmark authority. The threshold is an in-version diagnostic guard, not an A/B superiority conclusion.

package/docs/operations/standalone-disaster-recovery.md

@@ -58,7 +58,9 @@ reconnect_primary_connector
 
 `runtime_status` reads canonical Runtime observation. `list_releases` reads the whole-release authority. `attest_known_good` succeeds only after Runtime status, release identity, authenticated MCP initialization, tools/list, and the configured read-only MCP call pass together.
 
-The Recovery Gateway listens on loopback, uses a separate scoped credential, bounds request/output size, and stores no primary MCP credential in logs. External HTTPS verification uses the trusted system curl transport; temporary headers, MCP payloads and session identifiers are written only to bounded mode-0600 files below `recovery/tmp` and are removed after each request.
+The Recovery Gateway listens on loopback, uses a separate scoped credential, bounds request/output size, and stores no primary MCP credential in logs. External HTTPS verification uses the trusted system curl transport; temporary headers and MCP payloads are written only to bounded mode-0600 files below `recovery/tmp` and are removed after each request.
+
+For MCP transport lifecycle, Standalone Recovery deliberately owns **no transport-session state**. MCP 2026-07-28 and bounded 2025-era compatibility requests are both served statelessly by the SDK handler. `Mcp-Session-Id` is therefore never Recovery authority and is not required to survive a Recovery Gateway process replacement; an old client sending a stale session header cannot strand the independent recovery path. Runtime/release authority remains durable and separate from transport process identity.
 
 ## Whole-Runtime rollback
 
@@ -79,7 +81,7 @@ Recovery never rolls back Gateway, Controller Services, Scheduler, MCP Transport
 
 ## Watchdog rules
 
-One watchdog tick performs at most one mutation under the cross-process Recovery lock.
+One watchdog tick performs at most one mutation under the cross-process Recovery lock. `src/runtime/standalone-recovery/operation-lock.ts` is the sole file-lock acquisition and cleanup implementation shared by Core recovery transactions, installer and certification. The Core transaction wrapper retains lock-owner request attribution, audit on identity uncertainty/races, and exclusive release in `finally`; it does not write a competing lock record.
 
 Allowed self-repair is narrow and ordered:
 
@@ -93,18 +95,23 @@ The watchdog cannot launch an Agent, edit a source checkout, generate repair scr
 
 ## Installation
 
-Build, canary, and activate the immutable Recovery release with the public CLI:
+Build and canary the immutable Recovery release with the public CLI. Installation role is explicit:
+
+- `manual` is the default. It publishes the Recovery artifact/configuration but registers no persistent Recovery Gateway or Watchdog.
+- `gateway` registers only the independently reachable Recovery Gateway.
+- `self-healing` registers Gateway plus Watchdog and is the only profile that pays the autonomous health-monitoring/recovery cost.
 
 ```sh
 forge recovery install \
   --controller-home /absolute/controller-home \
+  --profile gateway \
   --public-mcp-url https://mcp.example.com/mcp \
   --recovery-public-url https://recovery.example.com/recovery/mcp \
   --recovery-tunnel-service-label com.example.forge-recovery-tunnel \
   --recovery-tunnel-service-plist /absolute/path/com.example.forge-recovery-tunnel.plist
 ```
 
-Use `--stage-only` to build and canary without activating Gateway or Watchdog services. The source-level `bun scripts/install-standalone-recovery.ts` entry remains an internal packaging primitive, not a second operator surface.
+`--stage-only` remains a compatibility alias for build/canary-only behavior and does not mutate installed Recovery configuration or services. The source-level `bun scripts/install-standalone-recovery.ts` entry remains an internal packaging primitive, not a second operator surface. Shipping Forge source/CLI does not itself activate any persistent Recovery profile.
 
 A public Recovery endpoint is optional for local-only operations. A ChatGPT Recovery Connector requires one independently owned external transport: either an explicit HTTPS Recovery URL plus its dedicated tunnel service owner, or a dedicated OpenAI Secure MCP Tunnel. The OpenAI transport keeps the Recovery Gateway on loopback; `tunnel-client` is the outbound transport and is supervised separately from the primary Forge Runtime/Connector.
 
@@ -113,6 +120,7 @@ For a Windows/WSL Recovery installation, create a new OpenAI tunnel identity tha
 ```sh
 forge recovery install \
   --controller-home /home/<user>/.forge/controller \
+  --profile gateway \
   --recovery-openai-tunnel-id <dedicated-wsl-recovery-tunnel-id> \
   --recovery-openai-runtime-api-key-ref env:FORGE_RECOVERY_TUNNEL_KEY
 ```
@@ -127,9 +135,9 @@ forge recovery connector --controller-home /absolute/controller-home
 
 The descriptor and `runtime_status` expose a `RecoveryMachineIdentity` containing host, platform, resolved Controller Home, current Recovery release identity, and the exact target Runtime service/release identity. Every external Recovery mutation requires the caller to echo the current `expected_host`, `expected_platform`, `expected_controller_home`, `expected_recovery_release`, and `expected_target_runtime` values from that observation. Missing, stale, or cross-machine values are rejected before any mutation. Successful mutation responses include the post-operation machine identity as well. This makes accidentally selecting the macOS Recovery connector while intending to repair WSL fail closed rather than repairing the wrong machine.
 
-Because Gateway, Watchdog, immutable Recovery release, and the dedicated Recovery tunnel are installed independently of the primary Runtime/Connector, a primary Runtime outage does not remove this external Recovery control path.
+When the selected profile includes Gateway, the Recovery Gateway and any dedicated Recovery tunnel are installed independently of the primary Runtime/Connector, so a primary Runtime outage does not remove that external Recovery control path. Watchdog independence applies only to the explicit `self-healing` profile.
 
-The installer owns publication and activation. Before registering `com.moretea.forge-recovery-gateway` and `com.moretea.forge-recovery-watchdog`, it exits and removes stale Recovery services discovered under the Recovery-owned launchd directory. Configuration is rewritten from the current schema and does not preserve retired ingress, agent-repair, or legacy tunnel fields. Direct reload scripts are not a second mutation path.
+The installer owns Recovery publication and role reconciliation. It activates only the roles selected by the typed install profile and explicitly retires Recovery-owned Gateway/Watchdog services that are no longer selected. It never treats a package/source install as permission to enable Watchdog. Configuration is rewritten from the current schema and does not preserve retired ingress, agent-repair, or legacy tunnel fields. Direct reload scripts are not a second mutation path.
 
 Forge deliberately has no blue-green Runtime topology. There is one active whole-release authority and one canonical service. Candidate validation happens before activation; activation stops the complete Runtime, switches the atomic active release, starts one Runtime, and gates on whole-Runtime readiness. Failure restores the previous whole release and its bound SQLite backup.
 
@@ -156,6 +164,6 @@ forge recovery activate-runtime --controller-home /absolute/controller-home --re
 
 The controller may install the `local_recovery` external Assistant Plugin when the independently configured ChatGPT Recovery Connector is unavailable or bound to a stale external transport while the primary Runtime is still healthy enough to host plugins. This adapter is a transport client only; it is not another Runtime lifecycle authority.
 
-The managed helper is `scripts/forge-local-recovery-helper.mjs`. Its provider configuration contains only the absolute installed `controllerHome`. The helper loads the installed Recovery configuration and scoped Gateway token from that Controller Home, requires the Recovery Gateway endpoint to remain loopback, and invokes only allowlisted Recovery MCP tools. The initial action surface is `runtime_status`, `list_releases`, and `stage_and_activate_runtime_release`; every action has an empty caller argument schema. In particular, callers cannot supply a source root, release path, endpoint, token path, executable, command, tunnel identity, or mutation request id.
+The managed helper is `scripts/forge-local-recovery-helper.mjs`. Its provider configuration contains only the absolute installed `controllerHome`. The helper loads the installed Recovery configuration and scoped Gateway token from that Controller Home, requires the Recovery Gateway endpoint to remain loopback, and invokes only allowlisted Recovery MCP tools. The action surface includes `runtime_status`, `list_releases`, read-only `verify_stable_runtime`, the compatibility candidate-build action `stage_and_activate_runtime_release`, and the durable ReleaseSession lifecycle (`release_session_status`, static verification, isolated Candidate B verification, pre-cutover Candidate retirement, cutover, exact-session rollback, and known-good promotion). A source or admission gate discovered after Candidate creation invalidates that frozen candidate: Recovery retires it through the existing `failed` terminal state and removes the isolated Candidate lane before a replacement ReleaseSession is prepared. While a ReleaseSession owns an activation transaction, the watchdog may restart the same candidate Runtime but must not generically commit or roll back that transaction; exhausted recovery delegates back to the exact ReleaseSession rollback path. Ordinary actions accept no caller arguments; ReleaseSession actions accept only the bounded `session_id`, while mutation request ids remain provider-owned. Callers cannot supply a source root, release path, endpoint, token path, executable, command, tunnel identity, or mutation request id.
 
 `stage_and_activate_runtime_release` delegates to the existing standalone Recovery MCP tool of the same name. Staging source authority, Repository Registry provenance, Recovery mutation locking, active/previous whole-release authority, SQLite backup/rollback, launch-service ownership, and post-activation verification therefore remain entirely owned by standalone Recovery. The adapter is useful for in-band maintenance while the primary Runtime is alive; it does not replace the independent Recovery Connector for disaster recovery when the primary Runtime itself is unavailable.

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

@@ -20,7 +20,7 @@ npm --version
 
 ## 2. 安装 Forge
 
-Release Candidate 使用 npm `next`：
+稳定版本使用 npm `latest`（当前已发布 `v1.8.1`）：
 
 ```bash
 npm install -g @moretea-labs/forge

package/docs/tutorials/03-first-repository-task.md

@@ -10,6 +10,8 @@ Ask ChatGPT:
 Use Forge. Check rh_status, then load rh_context for my selected repository. Summarize the current branch, working-tree state, relevant files, and available named checks. Do not modify anything yet.
 ```
 
+For a CLI identity check, `forge repo validate <repo-id>` prints a bounded validation summary and checkout counts. Use `--json` only when the full repository, runtime-storage, and legacy-migration audit is needed; that detailed output can be large.
+
 Resolve a dirty tree or ambiguous repository selection before writing.
 
 ## 2. Give a bounded task

package/docs/wiki/Computer-and-Plugins.md

@@ -0,0 +1,78 @@
+# Computer and Plugin Setup — macOS desktop, Browser, Design, Knowledge, Figma
+
+Forge includes a typed **Computer** capability for local-machine tasks and a separate **Browser** capability for websites. ChatGPT (or a selected MCP client) decides actions; Forge enforces permissions and reports evidence. Installing Forge's CLI does not automatically update independently released providers.
+
+## Quick setup on macOS
+
+Install or upgrade the Forge CLI first:
+
+```bash
+npm install -g @moretea-labs/forge@latest
+forge --version
+forge setup next
+```
+
+Then install the pinned native Computer provider and verify its health:
+
+```bash
+forge computer setup
+forge computer doctor
+forge computer status --json
+```
+
+For an **already installed** Computer provider, run `forge computer update` to install the provider release pinned by the current Forge catalog. If no newer compatible pin exists, this does not upgrade to an arbitrary GitHub tip. Complete any macOS Accessibility / Screen Recording permission prompts that the native provider requires, then re-run `forge computer doctor`. Only macOS currently has the catalogued native Desktop Operator provider; Linux/Windows users should not run `forge computer setup` expecting macOS desktop control.
+
+Computer's provider is **Forge Desktop Operator** (catalog tag `v0.4.5`). Computer can observe and interact with the macOS desktop, request capture and element operations, and use native console-unlock capabilities where authorized. Browser navigation/DOM and web sessions remain a separately owned Browser surface, not a second copy of Desktop Operator authority.
+
+## Other official providers
+
+Review available, platform-compatible pinned releases first:
+
+```bash
+forge plugin catalog
+forge plugin list --refresh
+```
+
+| Plugin ID | Purpose | Pinned catalog tag | Supported installation hosts |
+| --- | --- | --- | --- |
+| `desktop_operator` | Native Computer provider (use `forge computer` commands) | `v0.4.5` | macOS |
+| `design` | Repository-local design workspace and design artifacts | `v0.3.0` | macOS / Linux / Windows |
+| `personal_knowledge` | Local personal-knowledge retrieval and safe operations | `v0.2.1` | macOS / Linux / Windows |
+| `figma` | Figma plugin bridge and typed canvas operations | `v0.3.0` | macOS |
+
+Install only what you need:
+
+```bash
+forge plugin install design
+forge plugin install personal_knowledge
+forge plugin install figma          # macOS; requires its Figma bridge to be running
+forge plugin list --refresh
+```
+
+Re-running a provider's `forge plugin install <id>` uses the version pinned by the installed Forge catalog. Provider health can be `degraded` if the target app, local socket, native permission, browser session, or service authentication is missing. An install receipt alone is **not** proof of an operational provider. Figma and other app-specific bridges need their own app/bridge setup before typed calls become ready.
+
+## How to use from ChatGPT
+
+After [connecting ChatGPT to Forge MCP](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/02-connect-chatgpt.md), ask for a bounded goal:
+
+- “Inspect the currently open Chrome page, check form fields, and report what is wrong.”
+- “Read the authorized Finder folder, organize the documents, and show me the result.”
+- “Use Computer to observe this app and take a screenshot before changing anything.”
+- “Inspect the design workspace and prepare a reviewable design artifact.”
+- “Search my connected local knowledge base for the project decision.” (requires `personal_knowledge` to be ready)
+- “Inspect this open Figma file and tell me which components need review.” (requires a working Figma bridge)
+
+Each provider has its **own** authorization and readiness. Avoid assuming desktop control or website mutation is allowed solely because the MCP connector responds.
+
+## Diagnostics
+
+```bash
+forge computer status --json
+forge computer doctor
+forge plugin list --refresh
+forge doctor
+```
+
+If Browser readiness mentions Playwright, ensure the selected Browser attach mode and its browser dependencies are configured; native Chrome/Vivaldi attachment and managed Playwright browsing have different requirements. If Computer is not ready, resolve the reported macOS permissions/native provider state; if Figma reports a missing socket, start/configure the Figma bridge rather than repeatedly reinstalling Forge.
+
+More detail: [Plugin Management](https://github.com/moretea-labs/forge/blob/main/docs/forge-plugin-management.md), [Browser runbook](https://github.com/moretea-labs/forge/blob/main/docs/operations/controller-browser-plugin.md), and [Security Model](Security-Model).

package/docs/wiki/Computer-and-Plugins.zh-CN.md

@@ -0,0 +1,88 @@
+# Forge Computer 与官方插件中文使用指南
+
+Forge 是本地优先的 **ChatGPT MCP 执行工具**：由 ChatGPT 理解任务和决定下一步，Forge 管理权限、执行与证据。Forge 的主程序和独立 Provider **不是同一个升级渠道**。
+
+## 第一步：安装 Forge，连接 ChatGPT
+
+基础要求：Node.js 20.10+、npm（或 Bun），macOS / Linux 或 Windows WSL2。打开终端：
+
+~~~bash
+npm install -g @moretea-labs/forge@latest
+forge --version
+forge setup
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
+~~~
+
+按程序提示完成 Package Runtime 和 ChatGPT MCP 连接。详见[连接 ChatGPT 中文教程](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/02-connect-chatgpt.zh-CN.md)。
+
+## 第二步：macOS 安装 Computer
+
+~~~bash
+forge computer setup
+forge computer doctor
+forge computer status --json
+~~~
+
+已经安装 Computer 的用户可以更新到当前 Forge 官方目录固定的版本：
+
+~~~bash
+forge computer update
+forge computer doctor
+~~~
+
+Computer 原生实现是 [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator)，Forge v1.8.1 官方目录固定版本为 **v0.4.5**。使用桌面观察、截图、点击、输入时，macOS 可能需要手动授予**辅助功能**和**屏幕录制**权限。
+
+**Linux/Windows 没有这款 macOS 原生 Computer Provider**；不要把内置的文件/浏览器能力误认作跨平台原生桌面控制。Browser 使用独立的浏览器会话和权限边界。
+
+## 第三步：按需要安装插件
+
+先检查当前官方目录与已安装插件：
+
+~~~bash
+forge plugin catalog
+forge plugin list --refresh
+~~~
+
+| 插件 | v1.8.1 固定版本 | 用途 | 平台 |
+| --- | --- | --- | --- |
+| Computer / Desktop Operator | v0.4.5 | 原生桌面观察与交互 | macOS |
+| Forge Design | v0.3.0 | 仓库设计工作区与设计产物 | macOS / Linux / Windows |
+| Personal Knowledge Assistant | v0.2.1 | 本地知识检索、安全写入 | macOS / Linux / Windows |
+| Forge Figma Bridge | v0.3.0 | Figma 画布与组件操作 | macOS |
+
+按需执行安装，**不必全部安装**：
+
+~~~bash
+forge plugin install design
+forge plugin install personal_knowledge
+forge plugin install figma
+forge plugin list --refresh
+~~~
+
+Figma Bridge 还需要相应 Figma 插件与本地服务运行。插件安装成功不代表健康状态就绪；如果显示 degraded，应根据诊断信息检查应用、授权、Socket、浏览器连接或依赖。
+
+## 第四步：在 ChatGPT 中实际使用
+
+连接 Forge MCP 并授权目标资源后，直接用自然语言描述任务：
+
+- “检查当前 Chrome 页面中的表单字段，先报告问题，不要提交。”
+- “观察 Mac 当前桌面应用，截图并告诉我界面有什么异常。”
+- “整理这个已授权文件夹里的文档，并列出更改前后情况。”
+- “在已连接的本地知识库里搜索上次的架构决策。”
+- “查看当前 Figma 文件的组件结构。”（需要 Figma Bridge 健康就绪）
+
+Forge 不会因为连接成功就允许不受限的远程写入、破坏性操作、密钥获取或越权访问。
+
+## 第五步：升级和排查
+
+~~~bash
+npm install -g @moretea-labs/forge@latest
+forge setup next
+forge computer update       # 仅 macOS
+forge computer doctor       # 仅 macOS
+forge plugin list --refresh
+forge doctor
+~~~
+
+[English Computer Guide](Computer-and-Plugins) · [插件管理](https://github.com/moretea-labs/forge/blob/main/docs/forge-plugin-management.md) · [平台支持说明](https://github.com/moretea-labs/forge/blob/main/docs/operations/platform-support.zh-CN.md)

package/docs/wiki/Home.md

@@ -1,6 +1,19 @@
-# Forge Wiki
+# Forge Wiki — ChatGPT MCP for local computer and software tasks
 
-Forge is a local-first action assistant that gives ChatGPT a durable, policy-bounded execution layer for local software work. The product is intentionally Direct-first: ordinary bounded work stays lightweight, while Process Runtime, Work, worktrees, scheduling, and Recovery exist for the cases that actually need lifecycle or isolation.
+Forge is a local-first, permission-scoped MCP action runtime for ChatGPT and other explicitly selected external controllers. It gives ChatGPT durable execution tools for local files, Git repositories, browsers, and authorized services—**without putting an additional AI agent inside Forge**. The product is intentionally Direct-first: ordinary bounded work stays lightweight, while Process Runtime, Work, worktrees, scheduling, and Recovery exist for the cases that actually need lifecycle or isolation.
+
+## Get started with the latest stable version
+
+Install [Forge v1.8.1](https://github.com/moretea-labs/forge/releases/tag/v1.8.1) from [npm](https://www.npmjs.com/package/@moretea-labs/forge):
+
+```bash
+npm install -g @moretea-labs/forge@latest
+forge setup
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
+```
+
+macOS and Linux are supported; WSL2 is the recommended Windows path. Native Windows remains a preview. For upgrades and service setup, see [Installation](Installation).
 
 ## Start here
 
@@ -12,6 +25,7 @@ Forge is a local-first action assistant that gives ChatGPT a durable, policy-bou
 - Runtime behavior: [Runtime Architecture](Runtime-Architecture)
 - Source implementation map: [Implementation](Implementation)
 - Run and recover the service: [Operations](Operations)
+- Computer and provider setup: [Computer and Plugins](Computer-and-Plugins) · [中文教程](Computer-and-Plugins.zh-CN)
 - Optional capabilities: [Integrations](Integrations)
 - Diagnose a problem: [Troubleshooting](Troubleshooting)
 - Trust boundaries: [Security Model](Security-Model)

package/docs/wiki/Implementation.md

@@ -7,17 +7,17 @@ This page maps the public Forge model to the current source tree. It is an imple
 Primary code:
 
 ```text
-src/cli/mcp/server.ts
-src/cli/mcp/toolset-names.ts
-src/cli/mcp/repository-tools.ts
-src/cli/mcp/transports/http.ts
-src/cli/mcp/transports/session-registry.ts
-src/runtime/gateway/mcp/
+adapters/mcp/server.ts
+adapters/mcp/toolset-names.ts
+adapters/mcp/tool-mapping/repository-tools.ts
+adapters/mcp/transports/http.ts
+adapters/mcp/transports/session-registry.ts
+adapters/mcp/runtime-gateway/
 ```
 
-`toolset-names.ts` defines the bounded default connector surface. The five facade tools come from `src/runtime/control-plane/facade/types.ts`; repository, patch, check, Process, plugin-dispatch, and result tools bring the current default to 19.
+`toolset-names.ts` defines the bounded default connector surface. The six facade tools come from `src/runtime/control-plane/facade/types.ts`; repository, patch, check, Process, plugin-dispatch, and result tools bring the current default to 20.
 
-The HTTP transport owns authentication and protocol-era routing. MCP 2026-07-28 is the canonical public path: `createMcpHandler` serves each modern request without `Mcp-Session-Id`. `McpSessionRegistry` is retained only for explicit 2025-era compatibility, where it owns session capacity, active-request protection, stream leases, replacement, and close accounting. Durable Work/Process/ControllerRound authority never comes from either transport form. New Work claims mint an opaque Work-bound controller capability immediately; modern sessionless follow-up calls must present it, while legacy owner records without a digest require explicit `controller_claim` upgrade instead of principal-only inference. Legacy tool-surface mismatches still return a recoverable reinitialize response; modern requests resolve the current Runtime schema per request.
+The HTTP transport owns authentication and protocol-era routing. MCP 2026-07-28 is the canonical public path: `createMcpHandler` serves each modern request without `Mcp-Session-Id`. `McpSessionRegistry` is retained only for explicit 2025-era compatibility, where it owns session capacity, active-request protection, stream leases, replacement, and close accounting. Durable Work/Process/ControllerRound authority never comes from either transport form. Controller capability rotation and legacy-owner upgrades are Runtime recovery mechanics; ordinary model-facing Work operations neither expose nor require `controller_claim`. Legacy tool-surface mismatches still return a recoverable reinitialize response; modern requests resolve the current Runtime schema per request.
 
 ## 2. Repository registry and execution identity
 
@@ -29,7 +29,7 @@ src/cli/repositories/ephemeral-workspace.ts
 src/runtime/control-plane/execution/execution-identity.ts
 ```
 
-Registered work is resolved to `repoId` plus `checkoutId`. Git top-level/common-directory checks prevent a caller from supplying a different checkout through `cwd`. `ephemeral-workspace.ts` represents the separate explicit authority for an existing unregistered local directory.
+Registered work is resolved to `repoId` plus `checkoutId`. Git top-level/common-directory checks prevent a caller from supplying a different checkout through `cwd`. `ephemeral-workspace.ts` represents the separate explicit authority for an existing unregistered local directory. `src/cli/repositories/structured-git.ts` partitions porcelain status once; `src/runtime/projections/git-status-sampler.ts` uses that parser for its sampled projection rather than maintaining an independent classification.
 
 ## 3. Context and source access
 
@@ -51,10 +51,10 @@ Primary code:
 
 ```text
 src/cli/editing/edit-session.ts
-src/cli/mcp/repository-tools.ts
+adapters/mcp/tool-mapping/repository-tools.ts
 ```
 
-A bounded patch can be applied directly to the selected checkout with file fingerprints, revisions, savepoints, change budgets, and focused verification. Direct Edit is the default for understood small work; a Plan or worktree is not a prerequisite.
+A bounded patch can be applied directly to the selected checkout with file fingerprints, revisions, savepoints, change budgets, and focused verification. Direct Edit is the default for understood small work; a Plan or worktree is not a prerequisite. Anchor occurrence positioning is owned by `src/cli/editing/edit-session.ts` and reused by `src/cli/repositories/safe-patch.ts` preflight, so preview and the actual patch executor cannot drift on repeated anchors.
 
 ## 5. Command policy and ephemeral workspaces
 
@@ -70,6 +70,18 @@ The classifier distinguishes readonly, workspace write, remote write, and destru
 
 The MCP result envelope distinguishes “not authorized/executed” from “process executed and failed.” A blocked `rm` therefore returns authorization-required state rather than a fabricated exit-code failure, and successful ephemeral mutations are not labeled as readonly.
 
+`src/cli/commands/setup-execution.ts` is the single synchronous CLI setup/adoption owner for temporary process environment overlays and mapping bounded child-process results to setup steps. `init.ts`, `init-hook.ts`, and `global-runtime.ts` import this owner directly instead of maintaining their own `process.env` mutation and process-step wrappers. This setup convenience layer does not own Runtime or Work execution authority.
+
+Runtime/Connector service configuration, release materialization and CLI systemd unit
+files use `src/runtime/shared/atomic-text-file.ts` for atomic text replacement,
+including mode preservation and unique temporary paths. Independent Windows/WSL
+host rescue deliberately retains its local writer rather than importing a
+Runtime module into its emergency migration entrypoint.
+
+Adoption no longer emits repo-local generated Helper wrapper scripts. The unused
+compatibility generator under `src/core/adoption/helper-wrapper-plan.ts` is retired;
+`src/core/adoption/plan.ts` installs only the current project-level assets.
+
 ## 6. Unified Process Runtime
 
 Primary code:
@@ -79,7 +91,7 @@ src/runtime/execution/process-runtime/runtime.ts
 src/runtime/execution/process-runtime/store.ts
 src/runtime/execution/process-runtime/interactive-admission.ts
 src/runtime/shared/process-identity.ts
-src/runtime/gateway/mcp/process-tools.ts
+adapters/mcp/runtime-gateway/process-tools.ts
 ```
 
 `spawnManagedProcess` creates one Process record and one physical child execution. Exact PID/start-time/executable identity protects later lifecycle operations. Known-long processes can return handles immediately; short commands may complete during a bounded interactive window. Process startup captures command/start-time together and reuses the running-state persistence result instead of repeating store writes/reads on the hot path.
@@ -103,7 +115,7 @@ Primary code:
 
 ```text
 src/runtime/execution/process-runtime/check-facade.ts
-src/runtime/gateway/mcp/persisted-check-process.ts
+adapters/mcp/runtime-gateway/persisted-check-process.ts
 src/runtime/evidence/
 src/runtime/projections/
 ```

package/docs/wiki/Installation.md

@@ -1,50 +1,46 @@
-# Installation
+# Install Forge — ChatGPT MCP local action runtime
 
-## Supported paths
+Forge is a local-first MCP execution runtime. ChatGPT (or another explicitly selected external controller) makes decisions; Forge handles permission-scoped computer, repository, browser, and service operations. **Stable release: v1.8.1**, published to npm `latest`.
 
-### Source installation
+## Install from npm (recommended)
 
-This is the verified path while `@moretea-labs/forge` remains unpublished:
+Requirements: **Node.js 20.10+**, npm (or Bun), and a writable home directory. Git is only needed for software/repository operations.
 
 ```bash
-bun install --frozen-lockfile
-npm install -g . --omit=optional --no-audit --no-fund
+npm install -g @moretea-labs/forge@latest
+forge --version
+forge setup
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
 ```
 
-### npm RC channel
+You can also use `bun add -g @moretea-labs/forge`. For ChatGPT, setup prefers the OpenAI Secure MCP Tunnel; connection requires your ChatGPT account/session and appropriate authorization. Codex, Claude, and other MCP clients are optional external controllers.
 
-After the package is visibly published to npm:
+## Upgrade an existing install
 
 ```bash
-npm install -g @moretea-labs/forge
+npm install -g @moretea-labs/forge@latest
+forge --version
+forge setup next
+forge doctor
 ```
 
-Bun installs the same npm artifact:
+For an installed Package Runtime, use `forge runtime service install-package` to reconcile its service. Follow [Releases and Upgrades](Releases-and-Upgrades) and [release notes](https://github.com/moretea-labs/forge/releases/tag/v1.8.1).
+
+## Source development (not required for installation)
 
 ```bash
-bun add -g @moretea-labs/forge
+git clone https://github.com/moretea-labs/forge.git
+cd forge
+bun install --frozen-lockfile
+npm install -g . --omit=optional --no-audit --no-fund
 ```
 
-Do not infer npm publication from a GitHub tag or prerelease alone.
-
-## Platforms
+## Supported platforms
 
-- macOS and Linux are primary runtime hosts.
-- WSL2 is the recommended Windows host for the complete controller runtime.
-- Native Windows supports the documented CLI and command-shim surface; check the current matrix before relying on host-specific integrations.
-
-See [Platform Support](https://github.com/moretea-labs/forge/blob/main/docs/operations/platform-support.md).
-
-## Command compatibility
-
-Forge exposes only `forge`, `forge-hook`, and `forge-runtime`. State directories, environment variables, protocol identifiers, and release artifacts use the Forge namespace.
-
-## Verify installation
-
-```bash
-forge --version
-forge doctor
-forge repo list --json
-```
+- **macOS:** supported user-level Package Runtime using launchd.
+- **Linux:** supported with systemd user service where available; portable-session fallback otherwise.
+- **Windows + WSL2:** recommended Windows path, using Linux instructions inside WSL2.
+- **Native Windows:** preview; check the explicitly supported CLI and portable Runtime scope.
 
-A successful CLI launch is not enough to prove the MCP runtime is healthy; verify the connector separately when using ChatGPT.
+See the [platform support matrix](https://github.com/moretea-labs/forge/blob/main/docs/operations/platform-support.md). Forge publishes `forge`, `forge-hook`, and `forge-runtime`. A successful CLI version check alone does not prove MCP connectivity; complete the [ChatGPT connection tutorial](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/02-connect-chatgpt.md) and verify the connector.

package/docs/wiki/Integrations.md

@@ -14,6 +14,10 @@ Codex, Claude, and GitHub Copilot can implement bounded tasks when available. Ag
 
 GitHub operations cover issues, pull requests, checks, repository settings, Wiki synchronization, and releases. Remote writes remain explicit and should reference the exact local revision being published.
 
+## Computer, Desktop Operator, and official providers
+
+On macOS, the supported user interface to the native Desktop Operator is `forge computer setup|status|doctor|update`. The separately owned Browser capability covers browser session/DOM actions, while Desktop Operator provides native Computer operations. Forge Design, Personal Knowledge Assistant, and Figma Bridge use independently pinned official provider releases. Follow [Computer and Plugins](Computer-and-Plugins) to install, diagnose, and use them from ChatGPT.
+
 ## Browser and local system
 
 Browser and local-system plugins are optional controller capabilities. They use separate grants and do not turn repository access into unrestricted machine access.