@moretea-labs/forge 1.5.0-rc.1

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

@@ -0,0 +1,58 @@
+# MCP tool exposure profiles
+
+Controller MCP uses one stable default schema so ChatGPT can reliably read, edit, run checks, use Git, delegate to local Agents, operate Campaigns, capture iOS evidence, and recover from failures without a permission switch hiding tools.
+
+## Profiles
+
+| Toolset | CLI | Behavior |
+| --- | --- | --- |
+| **advanced** (default) | `--toolset advanced` | Stable repair-capable surface, capped at 128 tools. Includes the five `rh_*` facades plus high-value repository, Direct Edit, command, Git, Work/Job, Agent, Campaign, plugin, browser, iOS, artifact, and recovery tools. |
+| **core** | `--toolset core` | Compatibility label for the same stable default 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. |
+
+Configure via CLI flags, `FORGE_MCP_TOOLSET`, or Controller Home MCP config. Empty/default controller configuration resolves to `advanced`.
+
+## Single source of truth
+
+`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:
+
+- expected and actual tool names/counts;
+- missing, unexpected, and duplicate names;
+- schema fingerprint;
+- readiness.
+
+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, Campaign, 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`, `campaign`, `browser`, `ios`, `plugin`, `evidence`, and `runtime-maintenance`. `rh_status`, `rh_context`, and `controller_capabilities` expose this metadata.
+
+The MCP transport currently publishes a static stable schema. It does **not** support loading a domain schema only after ChatGPT selects that domain. Therefore capability grouping improves selection and documentation, but it must not be described as dynamic tool loading. A future transport-level implementation may reduce the discovered schema while retaining the same internal handlers.
+
+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`, Campaign, iOS, plugin, and artifact tools when the facade is not the shortest reliable path.
+- 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
+```

package/docs/operations/mobile-intents-shortcuts.md

@@ -0,0 +1,117 @@
+# Mobile Intent and iPhone Shortcuts Entry Point
+
+forge exposes a narrowly-scoped mobile intent endpoint for local voice/text automation, including iPhone Shortcuts and Siri phrases.
+
+## Server Mode
+
+The normal Controller UI remains loopback-only:
+
+```bash
+forge controller ui --repo .
+```
+
+To allow a phone on the same trusted LAN to reach only the mobile intent endpoint, bind the server to a wildcard address and explicitly enable the LAN gate:
+
+```bash
+forge controller ui --repo . --host 0.0.0.0 --mobile-lan
+```
+
+When `--mobile-lan` is enabled, non-loopback requests are still rejected for `/`, `/api/*`, and the visual dashboard. Only `/mobile/intent` may be called from a non-loopback host, and every request must pass device-token authentication plus replay checks.
+
+## Device Enrollment
+
+Create device tokens from the local UI API. The returned token is shown once; forge stores only its SHA-256 hash in `.forge/mobile-intents.json`.
+
+```bash
+curl -sS \
+  -H "x-forge-local-token: <local-ui-token>" \
+  -H "content-type: application/json" \
+  -d '{
+    "name": "Greyson iPhone",
+    "scopes": ["plugins:read", "jobs:read", "plugin:gmail:configure", "plugin:gmail:send_message"]
+  }' \
+  http://127.0.0.1:8766/api/mobile/devices
+```
+
+Device scopes are intentionally explicit:
+
+- `plugins:read` lists plugin status and action schemas.
+- `jobs:read` polls a submitted durable Execution Job.
+- `plugin:*:*` permits all plugin actions.
+- `plugin:<plugin-id>:*` permits all actions for one plugin.
+- `plugin:<plugin-id>:<action-id>` permits one action.
+
+Revoke a device immediately when a phone or Shortcut is no longer trusted:
+
+```bash
+curl -sS \
+  -X POST \
+  -H "x-forge-local-token: <local-ui-token>" \
+  http://127.0.0.1:8766/api/mobile/devices/<device-id>/revoke
+```
+
+## Shortcut Request Contract
+
+Every `/mobile/intent` request must include these headers:
+
+```text
+Authorization: Bearer <one-time-returned-device-token>
+x-forge-device-id: <device-id>
+x-forge-timestamp: <ISO-8601 timestamp>
+x-forge-nonce: <unique random nonce, 8-128 safe characters>
+x-forge-signature: <optional HMAC-SHA256>
+```
+
+The timestamp must be within five minutes of the Controller clock. Each nonce may be used once within the ten-minute nonce window. The optional signature is computed over:
+
+```text
+<timestamp>.<nonce>.<raw-json-body>
+```
+
+using the device token as the HMAC key. Hex, base64url, and `sha256=<hex>` signatures are accepted. If the signature header is present, it must match the raw body or the request is rejected.
+
+## Intent Bodies
+
+List plugins:
+
+```json
+{ "intent": "list_plugins" }
+```
+
+Submit a plugin action:
+
+```json
+{
+  "intent": "plugin_action",
+  "pluginId": "gmail",
+  "actionId": "configure",
+  "requestId": "shortcut-gmail-config-1",
+  "confirmAuthorization": true,
+  "arguments": {
+    "enabled": true,
+    "provider": "mock",
+    "account_email": "assistant@example.com"
+  }
+}
+```
+
+Poll a durable Execution Job:
+
+```json
+{ "intent": "poll_job", "jobId": "JOB-..." }
+```
+
+Write actions still follow the plugin confirmation policy. If a Shortcut calls a strong-confirmation action without confirmation, the endpoint returns `409` with `approvalRequired: true`, the action risk, and the required confirmation text.
+
+## iPhone Shortcuts Shape
+
+A Shortcut should:
+
+1. Dictate or receive text.
+2. Build the JSON body for one allowed plugin action.
+3. Generate a timestamp and random nonce.
+4. Optionally compute HMAC-SHA256 over `<timestamp>.<nonce>.<raw-json-body>`.
+5. POST to `http://<mac-lan-ip>:8766/mobile/intent`.
+6. Speak the `approvalRequired` message or store the returned `job.jobId` for polling.
+
+Tokens are scoped per device and can be revoked without changing the Local Controller token.

package/docs/operations/open-source-release-hygiene.md

@@ -0,0 +1,31 @@
+# Open-source release hygiene
+
+Short checklist before publishing source or npm artifacts from this repository.
+
+## Do not ship
+
+- `_ops/`, `.ai/harness` runtime state, controller home checkouts
+- `.forge/*.local.json`, tokens, OAuth, grants, plugin runtime JSON
+- Personal absolute paths (`/Users/<name>/…`, `/home/<name>/…`)
+- Real `repo_*` / `checkout_*` binding ids
+- Real Tailscale hostnames or CGNAT addresses bound to a maintainer machine
+- Credentials, private keys, `.env` files
+
+## Commands
+
+```bash
+# Tracked-file audit (paths + finding class only; match values never printed)
+bash scripts/check-open-source-tracked-surface.sh
+
+# Public allowlist export + content scanners
+bun run check:public-export
+
+# Combined release-readiness gate for tool surface + hygiene
+bash scripts/check-release-readiness.sh
+```
+
+Justified historical hits can be listed in `scripts/open-source-audit-allowlist.txt`. Prefer scrubbing new files over expanding the allowlist.
+
+## Package exclusions
+
+`.gitignore` and `.npmignore` exclude runtime/plugin grants, tokens, `_ops`, research/tasks/plans noise, and key material patterns. Re-run the audit after adding new paths under `.forge/` or docs with machine-local examples.

package/docs/operations/personal-assistant-operator-guide.md

@@ -0,0 +1,61 @@
+# Personal assistant operator guide
+
+This runtime is intended to be used with ChatGPT as the primary control plane. The Local Controller is the execution, policy, audit, and persistence layer.
+
+## Recommended daily path
+
+1. Ask ChatGPT for the goal in natural language.
+2. ChatGPT calls the high-level assistant API or MCP tools.
+3. The runtime plans safe plugin actions, submits durable jobs, and writes results into Assistant Inbox.
+4. High-risk actions stay blocked until explicit human confirmation.
+
+## Readiness check
+
+Use `assistant_readiness` or `GET /api/assistant/readiness` before relying on the assistant.
+
+The report separates:
+
+- live Google capability
+- mock-only capability
+- disabled plugins
+- routine, inbox, and memory state
+- recommended next actions
+
+Mock mode proves the execution path only. It does not read real Gmail, Calendar, or Tasks data.
+
+## Gmail read self-test
+
+A low-risk Gmail read test can be submitted through either:
+
+- `plugin_action_execute` with `gmail.list_messages`
+- `POST /api/assistant/self-test/gmail-read`
+- `POST /api/assistant/intent` with an utterance such as `测试读取最近一周 Gmail`
+
+When Gmail is in mock mode, the test returns deterministic mock messages. For real Gmail, configure the plugin with provider `google-workspace` and set one of the supported token environment variables documented by the plugin health message.
+
+## Cleanup workflow
+
+Use `runtime_cleanup_preview` or `POST /api/assistant/maintenance/cleanup-preview` first. It is non-destructive.
+
+Use cleanup apply only after reviewing the preview:
+
+- `runtime_cleanup_apply` with `confirm_cleanup=true`
+- `POST /api/assistant/maintenance/cleanup-apply` with `confirmCleanup=true`
+
+Cleanup is limited to explicit Forge candidates:
+
+- old `Forge-*` temp directories that are not referenced by running processes
+- terminal local jobs, when explicitly included
+- historical attention acknowledgements, when explicitly included
+
+Do not use cleanup apply as a substitute for reviewing active jobs, active leases, or running workers.
+
+## What still needs real productization
+
+The current runtime can route assistant intents and run safe data collection jobs. A full personal-assistant product still needs:
+
+- real OAuth/token broker and refresh support
+- wall-clock routine scheduling
+- model-backed summarization of collected data
+- approval summaries for risky actions
+- cleanup apply integration in a dedicated maintenance UI

package/docs/operations/platform-support.md

@@ -0,0 +1,62 @@
+# Platform Support
+
+This document defines what the project currently supports. It is intentionally narrower than “the code contains Windows branches.” A platform is called supported only when the installation path, primary workflow, and release checks are covered.
+
+## Support matrix
+
+| Platform | Status | Recommended use |
+| --- | --- | --- |
+| macOS | Supported | Full local Controller, repository adoption, MCP, Direct Edit, agents, browser tooling, and release checks. |
+| Modern Linux | Supported | Full local Controller workflow. A system with Bash, Git, Node.js, and standard process tools is expected. |
+| WSL2 on Windows | Supported and recommended for Windows | Run the Linux workflow inside WSL2. Keep the repository inside the WSL filesystem for predictable permissions and performance. |
+| Native Windows | Preview | PowerShell installation, CLI loading, doctor, repository registration/inspection, and the portable runtime paths are supported. Shell-heavy workflow helpers remain limited. |
+
+## Required environment
+
+All installations require:
+
+- Git available on `PATH`;
+- Node.js 20.10 or newer, because the published `forge` launcher is a Node executable;
+- either npm, which ships with Node.js, or Bun 1.0 or newer as the package installer;
+- a writable user home directory.
+
+Bun is recommended for development and the full test suite, but it is not the only supported package installer.
+
+The following dependencies are optional and enable additional capabilities:
+
+- Codex or Claude CLI for delegated implementation;
+- GitHub CLI (`gh`) for GitHub Issue, Project, and cloud-agent operations;
+- Tailscale Funnel or `cloudflared` for a stable public HTTPS `/mcp` endpoint;
+- Playwright browser dependencies for browser automation;
+- CodeGraph for additional repository navigation;
+- Google Workspace credentials for Gmail or Calendar plugins.
+
+## Native Windows scope
+
+The native PowerShell path is release-tested for:
+
+- prerequisite checks and CLI package installation;
+- `forge --version` and command loading;
+- `forge doctor`;
+- repository registry operations;
+- Windows path, process, junction, and command handling covered by the portable test suite;
+- the default MCP facade and bounded repository operations that do not depend on Bash helpers.
+
+The following are not yet claimed as complete native Windows workflows:
+
+- Bash-owned repository migration and hook scripts;
+- the full source-release Bash gate;
+- automatic CodeGraph configuration;
+- every external agent CLI and tunnel combination.
+
+For those workflows, use WSL2. The native installer intentionally skips Bash skill synchronization and automatic CodeGraph setup instead of failing the whole installation.
+
+## WSL2 guidance
+
+Install Git, Node.js, and optionally Bun inside WSL2, then clone repositories under the Linux home directory, for example `~/src/project`. Avoid running one checkout alternately from Windows and WSL because file modes, symlinks, line endings, and runtime paths can diverge.
+
+The Windows host can still provide the browser and ChatGPT client. The Controller and MCP process run inside WSL2; expose only the MCP endpoint through a controlled HTTPS tunnel.
+
+## Verification boundary
+
+The repository contains a `windows-latest` smoke workflow covering the PowerShell dry run, installer contracts, native-Windows policy behavior, and portable Node tests. That smoke workflow is evidence for the bounded native scope above; it is not evidence that every Bash- or provider-dependent integration works natively.

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

@@ -0,0 +1,61 @@
+# 平台支持说明
+
+本文定义项目当前真正承诺的平台范围。代码中存在 Windows 分支并不等于所有流程都已在 Windows 原生环境验证；只有安装、主要工作流和发布检查均覆盖的范围才称为支持。
+
+## 支持矩阵
+
+| 平台 | 状态 | 建议用途 |
+| --- | --- | --- |
+| macOS | 支持 | 完整本地 Controller、仓库接入、MCP、Direct Edit、Agent、浏览器能力和发布检查。 |
+| 现代 Linux | 支持 | 完整本地 Controller 工作流，需要 Bash、Git、Node.js 和常见进程工具。 |
+| Windows + WSL2 | 支持，且是 Windows 推荐方案 | 在 WSL2 内按 Linux 流程运行，仓库建议放在 WSL 文件系统。 |
+| Windows 原生 PowerShell | 预览支持 | 支持安装、CLI、doctor、仓库注册/读取和可移植运行时路径；依赖 Bash 的流程仍有限制。 |
+
+## 基础环境
+
+所有安装方式都需要：
+
+- Git 已加入 `PATH`；
+- Node.js 20.10 或更高版本，因为发布后的 `forge` 启动器由 Node 执行；
+- npm（随 Node.js 安装）或 Bun 1.0+，用于安装 package；
+- 可写的用户主目录。
+
+Bun 是开发和完整测试的推荐执行器，但不再是唯一安装器。
+
+以下环境按功能选装：
+
+- Codex 或 Claude CLI：委派复杂代码实现；
+- GitHub CLI `gh`：GitHub Issue、Project 和云端 Agent；
+- Tailscale Funnel 或 `cloudflared`：稳定公网 HTTPS `/mcp` 地址；
+- Playwright 浏览器依赖：浏览器自动化；
+- CodeGraph：额外代码导航；
+- Google Workspace 凭据：Gmail、Calendar 插件。
+
+## Windows 原生支持范围
+
+Windows PowerShell 路径当前发布验证覆盖：
+
+- 前置环境检查和 CLI 安装；
+- `forge --version`、命令加载与 `forge doctor`；
+- 仓库注册表；
+- 可移植测试覆盖的 Windows 路径、进程、junction 和命令处理；
+- 不依赖 Bash helper 的默认 MCP facade 与有边界仓库操作。
+
+暂不宣称完整原生支持：
+
+- Bash 编写的仓库迁移和 Hook 脚本；
+- 完整源码发布 Bash 门禁；
+- CodeGraph 自动配置；
+- 所有 Agent CLI 与隧道组合。
+
+这些场景请使用 WSL2。原生安装流程会主动跳过 Bash skill 同步和未验证的 CodeGraph 自动配置，而不是让整体安装失败。
+
+## WSL2 使用建议
+
+在 WSL2 内安装 Git、Node.js 和可选的 Bun，并将仓库放在 Linux 主目录，例如 `~/src/project`。不要让同一个 checkout 交替由 Windows 和 WSL 操作，否则文件权限、符号链接、换行符和运行时路径可能漂移。
+
+ChatGPT 客户端和浏览器仍可运行在 Windows 主机；Controller 与 MCP 运行在 WSL2，只通过受控 HTTPS 隧道公开 MCP endpoint。
+
+## 验证边界
+
+仓库提供 `windows-latest` smoke workflow，验证 PowerShell dry-run、安装契约、Windows 默认策略和 Node 可移植测试。它证明的是上述有边界范围，不代表所有 Bash 或外部 Provider 集成都已原生 Windows 验证。

package/docs/operations/provider-configuration.md

@@ -0,0 +1,31 @@
+# Provider configuration and routing
+
+Forge does not require or privilege a specific model vendor. A fresh installation builds neutral routing from provider kind, declared capabilities, health, and the configured provider priority. Providers with the same priority use the provider id only as a deterministic tie-breaker.
+
+## Where configuration lives
+
+The Controller GUI and the JSON files below edit the same controller-scoped configuration:
+
+- `<controllerHome>/global/provider-config.json`: enable/disable providers, priority, model and non-secret API settings.
+- `<controllerHome>/global/executor-routing.json`: explicit provider order for each task intent.
+- `<controllerHome>/global/provider-secrets.json`: locally stored API credentials. This file is outside the repository and must never be committed.
+
+Opening the GUI or reading configuration does not rewrite these files. Existing routing and priority choices remain authoritative across upgrades.
+
+## Precedence
+
+Provider selection applies these rules in order:
+
+1. Per-request provider preferences and allow/deny constraints.
+2. An explicit order or default in `executor-routing.json`, including changes made in the GUI routing editor.
+3. Neutral generated defaults based on provider kind and `provider-config.json` priority.
+4. Availability, enablement, authentication, live-call policy, safety gates, and required capabilities.
+5. A ChatGPT handoff packet when no direct provider can safely run.
+
+An explicit routing order intentionally overrides the general provider priority. The GUI shows both controls so users can decide whether task types follow a specific route or the general provider preference. Use **Use automatic routing** in the routing panel to remove explicit overrides and resume generated priority-based routing; do not delete the whole controller configuration.
+
+## Personal preferences
+
+Maintainers and users may place Grok, Codex, Claude, an API provider, or another registered provider first in their own Controller configuration. Those preferences belong under `controllerHome`; they are not open-source defaults and are not copied into the repository.
+
+Remote API calls remain double-gated: the provider must be enabled/configured in the GUI and `FORGE_ENABLE_LIVE_MODEL_PROVIDERS` must explicitly allow live calls. Without both, the API provider is proposal-only.

package/docs/operations/releasing.md

@@ -0,0 +1,86 @@
+# Releasing Forge
+
+The public package is `@moretea-labs/forge`. It exposes exactly `forge`, `forge-hook`, and `forge-runtime`; previous product aliases are not published.
+
+## Release model
+
+`@moretea-labs/forge` publishes release candidates to npm `next` and stable releases to `latest`. Release documentation does not hard-code the “next version”; package version, Git tag, npm channel, and GitHub Release must be derived from the current `package.json` and agree exactly.
+
+## Distribution model
+
+1. **npm** is the primary package registry and version authority for the CLI artifact.
+2. **Bun** installs or executes the same npm package; no separate Bun publication is required.
+3. **GitHub Releases** publish release notes and immutable release identity for the matching Git tag.
+4. **Homebrew** is added through a Moretea Labs tap only after a stable release exists.
+
+RC versions use npm dist-tag `next`. Stable versions use `latest`. `publishConfig.provenance` remains enabled, while the channel is selected explicitly by the release command or workflow.
+
+## Required local gate
+
+From a clean checkout at the intended release commit:
+
+```bash
+bun install --frozen-lockfile
+bun run check:main
+bun run check:release
+```
+
+Also verify both supported launch paths:
+
+```bash
+node bin/forge.mjs --help
+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.
+
+## 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.
+
+```bash
+npm login
+npm whoami
+npm access ls-packages @moretea-labs
+
+# Create and inspect the local tag, but do not push it before publication succeeds.
+VERSION="$(node -p "require('./package.json').version")"
+git tag -a "v${VERSION}" -m "Forge ${VERSION}"
+NPM_RELEASE_BOOTSTRAP=1 RELEASE_TAG="v${VERSION}" npm run release:rc
+```
+
+If publication fails, remove the unpushed local tag, correct the problem, rerun the focused and release gates, and create a new release commit when repository content changes. Never reuse a published package version or move a pushed release tag.
+
+After npm confirms the package:
+
+```bash
+git push origin "v${VERSION}"
+gh release create "v${VERSION}" --verify-tag --generate-notes --prerelease
+npm run check:release-published
+```
+
+## Trusted Publishing after bootstrap
+
+After the package exists:
+
+1. Configure npm Trusted Publishing for `moretea-labs/forge` and `.github/workflows/release.yml`.
+2. Configure the GitHub environment `npm-publish` with required maintainer approval.
+3. Protect release tags and the `main` branch.
+4. Push only an exact `v<package-version>` tag after the release gate passes.
+
+The tag workflow uses GitHub OIDC and does not require `NODE_AUTH_TOKEN` or a stored npm token. It validates the exact tag and channel. If the exact version was already published by the one-time bootstrap path, the workflow skips duplicate npm publication and still creates the matching GitHub Release; later versions publish normally through Trusted Publishing.
+
+## Stable release
+
+Before `1.4.0`:
+
+- install the exact packed artifact on macOS, Linux, WSL2, and the supported Windows path;
+- verify `forge init`, `forge doctor`, repository registration/adoption, and the ChatGPT MCP connection;
+- confirm no RC-only warning or unstable install command remains in the stable docs;
+- change `package.json` from an RC version to the intended stable `X.Y.Z`; the package identity gate will require `latest`;
+- publish from tag `v1.4.0` through the protected environment;
+- only then create or update the Homebrew tap formula.
+
+## Rollback and incident rule
+
+npm versions and pushed release tags are immutable. A bad release is not overwritten: deprecate the affected npm version when appropriate, document the incident, restore the previous dist-tag if needed, and publish a new patch or RC version.

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

@@ -0,0 +1,86 @@
+# 发布 Forge
+
+公开 npm 包名为 `@moretea-labs/forge`，只发布 `forge`、`forge-hook` 与 `forge-runtime`，不再发布此前产品的命令别名。
+
+## 当前发布模型
+
+`@moretea-labs/forge` 的候选版本发布到 npm `next`，稳定版本发布到 `latest`。发布文档不硬编码“下一版本”；版本、Git tag、npm channel 和 GitHub Release 必须从 `package.json` 的当前版本推导并保持一致。
+
+## 分发模型
+
+1. **npm** 是 CLI artifact 的主要 registry 和版本权威。
+2. **Bun** 直接安装或执行同一个 npm 包，不需要单独发布 Bun 包。
+3. **GitHub Releases** 为对应 Git tag 提供发布说明和不可变发布身份。
+4. **Homebrew** 只在稳定版存在后，通过 Moretea Labs tap 提供。
+
+RC 使用 npm dist-tag `next`，稳定版使用 `latest`。`publishConfig.provenance` 始终保持启用；发布 channel 由受保护的命令或 workflow 显式选择。
+
+## 本地发布门禁
+
+在目标 release commit 的干净 checkout 中执行：
+
+```bash
+bun install --frozen-lockfile
+bun run check:main
+bun run check:release
+```
+
+同时验证两种启动路径：
+
+```bash
+node bin/forge.mjs --help
+bun bin/forge.mjs --help
+```
+
+main 门禁复用 focused task receipt，不执行全量测试。release 门禁复用该 receipt，检查 package 身份、公开文档、许可证与 notices、tracked 文件卫生和公开导出内容，然后只在 `.ai/harness/artifacts/release/` 生成一个 tarball；隔离安装与发布都复用这个 tarball。`test:full` 仅作为人工诊断命令。
+
+## npm 首次发布（仅 package 尚不存在时）
+
+一个尚不存在的 package 不能预先配置 npm Trusted Publishing。因此首次发布需要拥有 `@moretea-labs` scope 权限并开启双因素认证的 npm maintainer。由于这条一次性的本机 bootstrap 路径没有 OIDC provider，`NPM_RELEASE_BOOTSTRAP=1` 只对这次首发关闭 provenance；正常 GitHub OIDC 发布仍保持 `publishConfig.provenance=true`。
+
+```bash
+npm login
+npm whoami
+npm access ls-packages @moretea-labs
+
+# 先创建并检查本地 tag，发布成功前不要 push。
+VERSION="$(node -p "require('./package.json').version")"
+git tag -a "v${VERSION}" -m "Forge ${VERSION}"
+NPM_RELEASE_BOOTSTRAP=1 RELEASE_TAG="v${VERSION}" npm run release:rc
+```
+
+发布失败时，删除尚未 push 的本地 tag，修复后重新跑完整门禁。仓库内容变化后必须产生新的 release commit。已经发布的 npm 版本不能覆盖，已经 push 的 release tag 不能移动。
+
+npm 确认发布成功后：
+
+```bash
+git push origin "v${VERSION}"
+gh release create "v${VERSION}" --verify-tag --generate-notes --prerelease
+npm run check:release-published
+```
+
+## Bootstrap 后启用 Trusted Publishing
+
+首个 package 存在后：
+
+1. 在 npm 中为 `moretea-labs/forge` 与 `.github/workflows/release.yml` 配置 Trusted Publishing。
+2. 创建 GitHub environment `npm-publish`，设置 maintainer 审批。
+3. 保护 `main` 与 release tags。
+4. 只有完整门禁通过后，才 push 精确的 `v<package-version>` tag。
+
+Tag workflow 使用 GitHub OIDC，不需要 `NODE_AUTH_TOKEN` 或仓库内 npm token。它会校验 tag、RC 到 `next`、稳定版到 `latest`。如果精确版本已经由首次 bootstrap 发布到 npm，workflow 会跳过重复 publish 并继续创建 GitHub Release；后续新版本则通过 Trusted Publishing 正常发布。
+
+## 稳定版要求
+
+发布 `1.4.0` 前：
+
+- 在 macOS、Linux、WSL2 和已声明的 Windows 路径安装精确 packed artifact；
+- 验证 `forge init`、`forge doctor`、仓库注册/接入和 ChatGPT MCP 连接；
+- 确认稳定文档中没有 RC 专属警告或不稳定安装命令；
+- 把 `package.json` 从 RC 版本改为目标稳定版 `X.Y.Z`，package identity gate 会要求 `latest`；
+- 从受保护环境发布 tag `v1.4.0`；
+- 完成后才创建或更新 Homebrew tap formula。
+
+## 回滚与事故规则
+
+npm 版本和已 push 的 release tag 都是不可变的。错误版本不能覆盖发布：必要时 deprecate 该 npm 版本、记录事故、恢复之前的 dist-tag，并发布新的 patch 或 RC。