@moretea-labs/forge 1.8.1 → 1.8.2

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,15 +7,15 @@ 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. 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.
 
@@ -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.

package/docs/wiki/Quick-Start.md

@@ -1,27 +1,29 @@
-# Quick Start
+# Quick Start — use ChatGPT to work with your computer via Forge MCP
 
-## 1. Install from source
+Forge gives an external controller (ChatGPT recommended) a local-first, permission-scoped execution runtime for files, Git repositories, browser/desktop actions, and connected services. Forge itself is **not** a second AI agent and does not require a separate OpenAI API key when your controller is ChatGPT.
 
-Until the npm RC is publicly available, use the verified source path:
+## 1. Install the current stable CLI
+
+Requires Node.js 20.10+, npm, and a writable home directory.
 
 ```bash
-git clone https://github.com/moretea-labs/forge.git
-cd forge
-bun install --frozen-lockfile
-npm install -g . --omit=optional --no-audit --no-fund
+npm install -g @moretea-labs/forge@latest
+forge --version
 ```
 
-Requirements: Git, Node.js 20.10+, npm, and a writable user directory. Bun is recommended for development and the complete test suite.
+Bun alternative: `bun add -g @moretea-labs/forge`. Source compilation is **not** necessary for a normal install; see [Installation](Installation).
 
-## 2. Initialize and diagnose
+## 2. Configure ChatGPT as the external controller
 
 ```bash
-forge --version
-forge install --target both
-forge doctor
+forge setup
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
 ```
 
-## 3. Register a repository
+Follow each reported next step to configure the Package Runtime and authenticated connector. OpenAI Secure MCP Tunnel is preferred when available; it is a transport, not another Forge controller. Read the [ChatGPT MCP setup tutorial](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/02-connect-chatgpt.md).
+
+## 3. Adopt a code repository only when needed
 
 ```bash
 forge adopt --repo /path/to/project --dry-run
@@ -29,18 +31,29 @@ forge adopt --repo /path/to/project
 forge repo list --json
 ```
 
-Use dry-run first when adopting an existing project. Review the proposed files and runtime configuration before applying.
+You can use authorized file, browser or service capabilities without first adopting a Git repository.
+
+## 4. Complete a small task and check the result
 
-## 4. Connect ChatGPT
+Ask ChatGPT to inspect a repository, make a scoped change, run the focused check, review the diff, and commit if verified. The [first repository task](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/03-first-repository-task.md) walks through the process. Destructive, secret-bearing and external effects have separate authorization requirements.
 
-Follow the maintained [connector tutorial](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/02-connect-chatgpt.md). After connection, verify status and repository context before starting write work.
+## Source checkout for contributors
 
-## 5. Complete one bounded task
+A normal package install does not require source, Git, or Bun. If you are modifying Forge itself, use the same frozen Bun dependency lock as CI:
 
-Start with a small change, inspect the diff, run the focused check, commit, and clean the branch or worktree. The full walkthrough is in [First Repository Task](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/03-first-repository-task.md).
+```bash
+git clone https://github.com/moretea-labs/forge.git
+cd forge
+bun install --frozen-lockfile
+npm install -g . --omit=optional --no-audit --no-fund
+```
+
+## Upgrade and help
 
-## Next
+```bash
+npm install -g @moretea-labs/forge@latest
+forge setup next
+forge doctor
+```
 
-- [Core Concepts](Core-Concepts)
-- [Work Lifecycle](Work-Lifecycle)
-- [Troubleshooting](Troubleshooting)
+Read [Releases and Upgrades](Releases-and-Upgrades), [Troubleshooting](Troubleshooting), and the [full documentation](https://github.com/moretea-labs/forge/tree/main/docs). Current stable: [v1.8.1](https://github.com/moretea-labs/forge/releases/tag/v1.8.1).

package/docs/wiki/Releases-and-Upgrades.md

@@ -1,34 +1,24 @@
-# Releases and Upgrades
+# Forge Releases and Upgrades
 
-## Release channels
+## Published stable release
 
-- `next`: release candidates
-- `latest`: stable releases only
+**Forge v1.8.2** was released on October 19, 2026. The canonical package is [`@moretea-labs/forge` on npm](https://www.npmjs.com/package/@moretea-labs/forge), and the matching [GitHub Release](https://github.com/moretea-labs/forge/releases/tag/v1.8.2) provides an immutable `v1.8.1` tag. npm `latest` is the stable channel; `next` is reserved for release candidates.
 
-The package version, Git tag, npm channel, GitHub prerelease state, and release notes must agree. GitHub Releases and npm publication are separate facts.
+## Install or upgrade to the latest stable
 
-## Release gate
+```bash
+npm install -g @moretea-labs/forge@latest
+forge --version
+forge setup next
+forge doctor
+```
 
-A release candidate must pass the repository's release-readiness check on the exact revision. The gate covers type checking, package identity, public documentation, platform contracts, MCP compatibility, public export, package creation, and tarball installation.
+When using the packaged persistent service, `forge runtime service install-package` reconciles the installed Package Runtime. Review [Installation](Installation) and [ChatGPT connection](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/02-connect-chatgpt.md) for platform-specific setup. Updates do not remove the requirement to validate the authenticated MCP connector.
 
-## Stable runtime evidence
+## How releases are verified
 
-Before publication, build an immutable whole-Runtime release from a clean canonical source tree, activate it through the single Forge Runtime service, verify the complete authenticated MCP path, cold-restart that service, and confirm the active release authority still equals the intended commit. Record the fully verified release as known-good.
+Source version, package identity, immutable Git tag, npm dist-tag, and GitHub Release must agree. `check:release` checks source gates, packaging, licensing/open-source hygiene, and isolated installation; `check:release-published` checks npm registry metadata and downloaded tarball integrity against the local version and tag. Publication is performed by protected GitHub Actions with npm OIDC Trusted Publishing.
 
-## Upgrade principles
+Release readiness and active whole-Runtime activation are different authorities; do not infer a healthy local service just from successful package publication. Follow the [maintained release process](https://github.com/moretea-labs/forge/blob/main/docs/operations/releasing.md) for contributor instructions.
 
-- Keep the Forge-only command, state, environment, protocol, and release identity consistent across upgrades.
-- Read release notes before changing runtime or connector configuration.
-- Do not overwrite a healthy active release with a stale rollout operation.
-- Keep a verified rollback path before changing production runtime state.
-
-## Publication sequence
-
-1. Merge reviewed code and docs.
-2. Push the exact main revision.
-3. Wait for required CI and Windows checks on that revision.
-4. Synchronize reviewed Wiki source.
-5. Create the exact `v`-prefixed tag and GitHub prerelease.
-6. Verify npm separately; never claim publication without registry evidence.
-
-See the maintained [release process](https://github.com/moretea-labs/forge/blob/main/docs/operations/releasing.md).
+For future releases, derive their version from the then-current `package.json` and update the matching immutable GitHub Release link.

package/docs/wiki/_Sidebar.md

@@ -1,4 +1,4 @@
-**Forge Wiki**
+**Forge · ChatGPT MCP Wiki**
 
 - [Home](Home)
 - [Quick Start](Quick-Start)
@@ -10,6 +10,8 @@
 - [Implementation](Implementation)
 - [Operations](Operations)
 - [Integrations](Integrations)
+- [Computer and Plugins](Computer-and-Plugins)
+- [Computer 中文使用指南](Computer-and-Plugins.zh-CN)
 - [Troubleshooting](Troubleshooting)
 - [Security Model](Security-Model)
 - [Releases and Upgrades](Releases-and-Upgrades)
@@ -18,4 +20,6 @@
 
 - [Repository](https://github.com/moretea-labs/forge)
 - [Versioned Docs](https://github.com/moretea-labs/forge/tree/main/docs)
+- [Latest stable v1.8.1](https://github.com/moretea-labs/forge/releases/tag/v1.8.1)
+- [npm package](https://www.npmjs.com/package/@moretea-labs/forge)
 - [Support](https://github.com/moretea-labs/forge/blob/main/SUPPORT.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moretea-labs/forge",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Local-first action assistant for software work with resumable execution, bounded tools, and reviewable evidence",
   "license": "MIT",
   "author": "Moretea Labs contributors",
@@ -39,7 +39,6 @@
     "NOTICE",
     "THIRD_PARTY_NOTICES.md",
     "scripts/verify-forge-runtime.sh",
-    "agents/",
     "assets/",
     "docs/README.md",
     "docs/tutorials/",
@@ -78,7 +77,6 @@
     "supervisor/",
     "AGENTS.md",
     "CLAUDE.md",
-    "SKILL.md",
     "README.md"
   ],
   "bin": {
@@ -98,7 +96,6 @@
     "benchmark:thin-harness-mcp-e2e": "bun scripts/benchmark-thin-harness-mcp-e2e.ts --json",
     "benchmark:mcp-transport": "bun scripts/benchmark-mcp-transport.ts",
     "benchmark:mcp-host": "bash scripts/benchmark-mcp-host.sh",
-    "benchmark:work-efficiency": "bun scripts/benchmark-work-efficiency.ts",
     "benchmark:route-session-concurrency": "bun scripts/benchmark-route-session-concurrency.ts",
     "benchmark:quality-harness": "bun scripts/benchmark-quality-harness.ts",
     "benchmark:background-check-overlap": "bun scripts/benchmark-background-check-overlap.ts",
@@ -168,7 +165,6 @@
     "runtime:activate-source-baseline": "bun scripts/activate-source-baseline.ts request",
     "plugin:install-desktop-operator": "bun scripts/install-desktop-operator-registration.ts",
     "sync:brain-docs": "bun src/cli/index.ts run sync-brain-docs --all",
-    "sync:codex-installed": "bash scripts/sync-codex-installed-copies.sh",
     "check:forge-runtime": "bash scripts/verify-forge-runtime.sh",
     "repo:registry": "bun src/cli/v81-entry.ts repo",
     "smoke:schedule-engine": "node --loader ./src/runtime/shared/node-ts-loader.mjs scripts/smoke-schedule-engine.ts",
@@ -180,7 +176,6 @@
     "check:portable-package": "node --test tests/node/*.test.mjs && npm run smoke:tarball-install"
   },
   "devDependencies": {
-    "@colbymchenry/codegraph": "1.0.1",
     "@types/bun": "latest",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6"
@@ -197,12 +192,6 @@
   },
   "packageManager": "npm@10.0.0",
   "optionalDependencies": {
-    "@colbymchenry/codegraph-darwin-arm64": "1.0.1",
-    "@colbymchenry/codegraph-darwin-x64": "1.0.1",
-    "@colbymchenry/codegraph-linux-arm64": "1.0.1",
-    "@colbymchenry/codegraph-linux-x64": "1.0.1",
-    "@colbymchenry/codegraph-win32-arm64": "1.0.1",
-    "@colbymchenry/codegraph-win32-x64": "1.0.1",
     "agent-device": "0.20.2"
   }
 }