@moretea-labs/forge 1.5.0-rc.1

package/docs/operations/route-session-concurrency-baseline.md

@@ -0,0 +1,94 @@
+# Route and Session Concurrency Baseline
+
+Baseline date: 2026-08-09
+
+This baseline is generated by the repository benchmark rather than hand-authored:
+
+```sh
+bun run benchmark:route-session-concurrency --iterations 7 \
+  --output docs/operations/route-session-concurrency-baseline.json
+```
+
+The JSON output contains every measured phase for every scenario, p50/p95/p99, success rate, timeout rate, contention rate, failure rate, and the derived threshold. The threshold policy is:
+
+```text
+max(1 ms, observed p99 * 1.25, observed p95 * 1.5)
+```
+
+The one-millisecond floor means an unused or sub-millisecond phase still has a non-zero governance value. Thresholds are a baseline comparison signal, not a reason to add waiting or to hide contention.
+
+## Measured scenario summary
+
+All values are milliseconds. `threshold` is the derived wall-clock threshold except where a phase is explicitly named.
+
+| Scenario | p50 | p95 | p99 | Threshold | Result |
+| --- | ---: | ---: | ---: | ---: | --- |
+| Context cold read | 0.13 | 26.26 | 26.26 | 40 | 100% success, 0% timeout |
+| Context warm read | 0.07 | 0.11 | 0.11 | 1 | 100% success, 0% timeout |
+| Requirement Board read | 1.72 | 13.17 | 13.17 | 20 | 100% success, 0% timeout |
+| Work prepare | 1.05 | 1.77 | 1.77 | 3 | 100% success, 0% timeout |
+| Direct Edit claim | 9.52 | 12.23 | 12.23 | 19 | 100% success, 0% contention |
+| Durable Process submit | 36.51 | 41.32 | 41.32 | 62 | 100% success, 0% timeout |
+| Process start | 66.22 | 74.74 | 74.74 | 113 | 100% success, 0% timeout |
+| Check completion | 80.99 | 112.45 | 112.45 | 169 | 100% success, 0% timeout |
+| Concurrent two-repository Process writes | 199.09 | 217.13 | 217.13 | 326 | 100% success, 0% timeout |
+| Same repository, real different-checkout writes | 200.89 | 217.73 | 217.73 | 327 | 100% success, 0% contention |
+| Same checkout real Process contention | 288.41 | 293.64 | 293.64 | 441 | 100% contention, 0% failure |
+| Check coalescing/reuse/invalidation cycle | 435.95 | 475.88 | 475.88 | 714 | 100% success, 0% timeout |
+| Gateway restart recovery | 97.58 | 98.43 | 98.43 | 148 | 100% success, 0% timeout |
+
+The cold-read distribution includes the initial Git/projection observation: Git observation and projection p95/p99 were 26.24 ms, with a 40 ms derived phase threshold. Warm projection p95/p99 was 0.10 ms. Requirement Board storage p95/p99 was 13.17 ms. Work prepare storage p95/p99 was 1.77 ms. Direct Edit lock wait p95/p99 was 12.23 ms. Same-checkout contention rejected the second physical Process with `PROCESS_LEASE_CONFLICT`; bounded end-to-end Lease admission was p50 39.02 ms and p95/p99 43.84 ms. Gateway restart storage re-read p50 was 0.18 ms and p95/p99 was 0.67 ms.
+
+## Physical concurrency and cache evidence
+
+The benchmark now uses two temporary Git repositories plus one real `git worktree`, registered as two checkouts of the same repository. Every concurrency sample launches Process Runners and writes an ignored marker in the intended checkout; it no longer substitutes context reads or invented checkout ids for physical work.
+
+Across seven iterations:
+
+- two-repository concurrency: 14 logical subscribers, 14 physical executions, 14 independently verified repo identities;
+- same-repository/different-checkout concurrency: 14 logical subscribers, 14 physical executions, 14 independently verified checkout identities;
+- same-checkout contention: 14 logical submissions, 7 physical executions, and 7 bounded Lease conflicts; no blocked marker was written;
+- Check cache: 28 logical subscribers, 14 physical executions, 7 active coalesces, 7 completed cache hits across the clean worktree, and 7 dirty-workspace invalidations.
+
+The Check identity is repository-scoped in the durable binding and content-bound by the workspace revision, check definition digest, environment/toolchain fingerprint, timeout contract, and safe reuse scope. Dependency lockfiles and relevant repository config participate through the content revision. Session and request ids are deliberately subscriber identity, not cache-key inputs. Cross-checkout reuse is enabled only when both checkouts are clean and the check declares fingerprintable read-only effects; the dirty-workspace sample changes the content fingerprint, narrows reuse to checkout scope, and forces a new Process.
+
+`durable_job_submit` measures durable Process admission and persistence because new ExecutionJob creation is retired. `gateway_restart_recovery` reads the persisted Process handle from a fresh store access before terminal completion.
+
+## Required interpretation
+
+- Same-checkout contention is successful behavior when it returns a bounded contention result. It is therefore reported with contention rate 1.0 and failure rate 0.
+- Different checkouts and different repositories must retain success rate 1.0 in the baseline matrix.
+- Cache accounting must retain the invariant `physicalExecutions < logicalSubscribers` only when the report also proves coalescing/reuse and explicit invalidation with distinct Process ids.
+- An increase must be investigated by phase. Raising a timeout or adding a global lock is not an acceptable remediation.
+- A new baseline must be generated from the benchmark on the candidate committed HEAD. Do not manually edit percentile or threshold values.
+- The benchmark uses temporary controller homes and temporary Git repositories, so it does not mutate registered production repositories.
+
+## T2 prior failure classification
+
+The previous T2 Work failed verification before commit because its isolated worktree had not materialized Bun type dependencies. `tsc` reported `TS2688: Cannot find type definition file for 'bun'`; the fallback command also resolved dependencies during verification and changed its input state. This was an infrastructure/dependency-materialization failure, not evidence that the resolver implementation was invalid.
+
+The corrected procedure is:
+
+```sh
+bun install --frozen-lockfile
+./node_modules/.bin/tsc --noEmit
+```
+
+The frozen install prevents verification from silently changing the lockfile or selecting a different dependency graph.
+
+## Validation set
+
+Run the following on the candidate HEAD:
+
+```sh
+bun test tests/runtime/diagnostic-process-invocation.test.ts
+bun test tests/runtime/thin-harness.test.ts
+bun test tests/runtime/thin-harness-gateway-routing.test.ts
+bun run benchmark:route-session-concurrency --iterations 7
+bun run check:type
+bun run check:runtime-architecture
+bun run check:forge-runtime
+bun run test
+```
+
+Also run the focused projection/source-identity tests selected by the test manifest. The committed benchmark JSON and all validation receipts must identify the same final HEAD.

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

@@ -0,0 +1,14 @@
+# Runtime performance diagnostics
+
+Forge exposes a read-only runtime_performance_diagnostics MCP tool for host-level performance inspection.
+
+It is intended for questions such as:
+
+- Why is Forge using CPU while the queue is empty?
+- Are there orphan job-worker processes?
+- Is the Local Controller actually running even if persisted runtime state is stale?
+- Which temporary Forge directories are stale cleanup candidates?
+
+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.

package/docs/operations/sqlite-control-plane-recovery.md

@@ -0,0 +1,65 @@
+# SQLite control-plane backup and recovery
+
+Status: current runbook  
+Authority: `<durable-controller-home>/control-plane.sqlite`
+
+## Safety boundary
+
+Recovery restores only a verified SQLite backup. Do not copy, replay or merge
+repository Issue/Task JSON, Markdown, project-state, task-ledger output or an
+offline export into an existing control-plane database. Those files are frozen
+compatibility material and may be stale.
+
+Canonical Runtime bootstrap and standalone Recovery retain their minimum
+capability without consulting legacy Issue/Task files. If the database is
+unavailable, Recovery may diagnose, require the Runtime to be stopped, inspect
+local backups and restore a verified database; it must not synthesize authority
+from Git JSON.
+
+## Backup
+
+1. Resolve the durable Controller home and exact repository/check-out identity.
+2. Create a new backup path; never overwrite an earlier backup.
+3. Use the control-plane backup API, which snapshots through SQLite and then
+   verifies `quick_check`, the required schema, required tables, record count and
+   audit continuity.
+4. Record the repository ID, checkout ID, branch and HEAD associated with the
+   backup evidence. Do not place secrets, credentials, logs or binaries in the
+   database or backup metadata.
+
+A backup is not restorable merely because it is a readable file. It must pass
+the same supported-schema and audit-continuity validation as the live database.
+The database and every backup are local project-execution data below Controller
+Home. They are never committed, packaged, embedded in a Runtime release, listed
+as manifest payload, or sent to another user; only schema compatibility metadata
+belongs to the distributed release contract.
+
+## Restore
+
+1. Fence normal control-plane writers.
+2. Verify the candidate backup before changing the live path.
+3. Copy it to a staging path under the durable Controller home.
+4. Re-run integrity, schema and audit-continuity checks against staging.
+5. Remove stale WAL/SHM sidecars and atomically rename staging into the live
+   `control-plane.sqlite` path.
+6. Reopen the database and verify Requirement, Plan, PlanStep and Work
+   relationships, revisions and exact repository/check-out/branch/HEAD
+   identity.
+7. Restart the daemon and compare Requirement Board plus Execution Diagnostics
+   with the pre-restart inspection.
+
+A failed staging verification leaves the current authority untouched. Never
+replace corruption with an empty database and never downgrade an unknown
+required schema version.
+
+## Acceptance checks
+
+A recovery is accepted only when:
+
+- SQLite integrity is `ok`;
+- the schema version is supported;
+- every current record revision has a matching audit event;
+- Requirement-to-Plan and Plan-to-Work relationships are preserved;
+- repository, checkout, branch and HEAD identity are unchanged;
+- daemon restart produces the same authoritative state;
+- no Issue/Task, `currentIssue`, legacy board or export file was used as input.

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

@@ -0,0 +1,136 @@
+# Standalone disaster recovery
+
+`forge-recovery` is an independent, fixed-command recovery service family. It is not a second primary Runtime owner and it does not start, stop, restart, repair, or roll out individual core components.
+
+## Authority boundaries
+
+The primary application has three relevant records under Controller Home:
+
+```text
+runtime/active-runtime-owner.json       live Canonical Runtime ownership
+runtime/status.json                     read-only Runtime status projection
+runtime/releases/authority.json         atomic active/previous whole-release authority
+runtime/releases/backups/*.sqlite       local pre-upgrade database backups
+```
+
+Recovery reads those records and probes the configured Runtime MCP endpoint. It does not connect to a Supervisor socket, select a blue/green slot, submit component operations, or infer authority from a source checkout.
+
+SQLite rows are local project-execution state. Database files and backups remain below Controller Home and are never included in source control, a package, an immutable release, a release manifest, or data distributed to another user. The release manifest carries only SQLite schema compatibility metadata.
+
+## Recovery service state
+
+Recovery-owned configuration, evidence, locks and audit records remain below:
+
+```text
+controller-home/recovery/
+├── config/
+├── releases/
+├── state/
+├── locks/
+├── audit/
+├── tmp/
+└── launchd/
+```
+
+Recovery release binaries may be installed independently so diagnostics remain available when the primary Runtime is down. That independent installation does not grant primary Runtime lifecycle authority.
+
+## Fixed recovery surface
+
+The CLI and Recovery MCP surface expose bounded operations:
+
+```text
+runtime_status
+verify_stable_runtime
+verify_external_runtime
+list_releases
+attest_known_good
+restart_primary_runtime
+recover_primary_runtime
+rollback_previous
+activate_runtime_release
+restart_public_tunnel
+reconnect_primary_connector
+```
+
+`restart_primary_runtime` restarts only the installed canonical Forge Runtime service and requires whole-Runtime verification. `recover_primary_runtime` is the complete failure transaction: stop the canonical service, restore the attested previous whole release and its SQLite backup, restart the service, and require verification.
+
+`activate_runtime_release` is the controlled bootstrap/upgrade escape hatch. It accepts an already staged and validated immutable Runtime release manifest and executes the same bounded transaction without depending on the primary Runtime execution plane: stop the complete canonical service, atomically switch active/previous whole-release authority with a local SQLite backup, start the one Runtime service, require whole-Runtime verification, and on failure restore the previous whole release and its SQLite backup before restarting. The candidate must match its manifest artifact identity and database schema compatibility; a fenced or stale primary Runtime is never required to stage, validate, or activate the release.
+
+`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.
+
+## Whole-Runtime rollback
+
+The rollback primitive is deliberately offline, while `recover_primary_runtime` owns the complete bounded service transaction:
+
+1. acquire the cross-process Recovery mutation lock;
+2. boot out the canonical Forge Runtime launchd service;
+3. prove the active Runtime owner is no longer running;
+4. require an independently attested previous whole release with a verified local SQLite backup;
+5. back up the current local SQLite database;
+6. restore the previous local backup;
+7. atomically switch active/previous whole-release authority;
+8. start the same canonical Forge Runtime service, which reads the newly selected active release;
+9. require whole-Runtime verification;
+10. if the restored release fails verification, stop the service to prevent an automatic restart loop.
+
+Recovery never rolls back Gateway, Controller Services, Scheduler, MCP Transport, Worker code, configuration, or database independently. They move as one release compatibility set. If the authority commit fails after database restoration, the rollback implementation restores the just-created current backup.
+
+## Watchdog rules
+
+One watchdog tick performs at most one mutation under the cross-process Recovery lock.
+
+Allowed self-repair is narrow and ordered:
+
+1. restart the standalone Recovery Gateway when only its own loopback health fails;
+2. restart the explicitly configured Recovery public tunnel when local Runtime and Recovery health are good but that external endpoint fails;
+3. after a sustained local whole-Runtime failure, restart the canonical Forge Runtime service with a bounded attempt count and cooldown;
+4. only after those restart attempts are exhausted, require sustained multi-signal evidence, an unattested active release, and an independently attested previous release before executing automatic whole-Runtime recovery;
+5. stop, roll back, restart, and verify under one Recovery mutation lock.
+
+The watchdog cannot launch an Agent, edit a source checkout, generate repair scripts, mutate repository files, restart an individual core module, or select a Runtime slot. A brief outage remains diagnostic evidence and does not trigger rollback. Default policy permits at most three primary Runtime restart attempts before rollback eligibility is evaluated. Failed recovery transactions are independently cooldown-bounded; `rollbackUsed` becomes permanent only after the previous whole-release authority actually commits, so a transient lock or service-stop failure neither causes a retry storm nor suppresses recovery forever.
+
+## Installation
+
+Build, canary, and activate the immutable Recovery release with the public CLI:
+
+```sh
+forge recovery install \
+  --controller-home /absolute/controller-home \
+  --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.
+
+A public Recovery endpoint is optional for local-only operations. A ChatGPT Recovery Connector requires an explicit HTTPS Recovery URL and its dedicated tunnel service owner. Print the exact non-secret connector descriptor with:
+
+```sh
+forge recovery connector --controller-home /absolute/controller-home
+```
+
+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.
+
+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.
+
+No rollout, service installation, or live restart is implied by source changes. Activating a new primary Runtime release still requires separate explicit authorization and exact release evidence.
+
+## Operator CLI
+
+The `forge recovery` command exposes the same bounded lifecycle surface as the Recovery Gateway tools, so routine maintenance never requires hand-written `launchctl`:
+
+```sh
+forge recovery status --controller-home /absolute/controller-home
+forge recovery verify --controller-home /absolute/controller-home
+forge recovery restart-runtime --controller-home /absolute/controller-home
+forge recovery recover --controller-home /absolute/controller-home
+forge recovery rollback --controller-home /absolute/controller-home
+forge recovery restart --controller-home /absolute/controller-home
+forge recovery install --controller-home /absolute/controller-home
+forge recovery activate-runtime --controller-home /absolute/controller-home --release-manifest /absolute/staged-release/manifest.json
+```
+
+`forge runtime status --controller-home /absolute/controller-home` reads the canonical Runtime status projection. `forge runtime service install --stage-only` builds and validates an immutable Runtime release without publishing it; the staged manifest can then be activated through `forge recovery activate-runtime` when the primary Runtime is fenced or unavailable.

package/docs/operations/troubleshooting.md

@@ -0,0 +1,72 @@
+# Installation and Connection Troubleshooting
+
+## `forge` is not found after installation
+
+Reopen the terminal first. With npm, inspect the global prefix with `npm config get prefix`; its executable directory must be on `PATH`. With Bun, ensure the Bun bin directory is on `PATH`.
+
+Verify the runtimes:
+
+```bash
+node --version
+npm --version
+bun --version   # optional
+forge --version
+```
+
+## Doctor reports missing Git or Node
+
+Install Git and Node.js 20.10 or newer, then open a new terminal. Node is required even when the package was installed with Bun because the published launcher uses Node.
+
+## Native Windows stops at a shell-owned step
+
+Use WSL2 for repository adoption, Bash hooks, source release checks, or shell lifecycle scripts. Native Windows intentionally skips the Bash skill-sync and automatic CodeGraph steps.
+
+## MCP works locally but ChatGPT cannot connect
+
+`http://127.0.0.1:8765/mcp` is local-only. ChatGPT needs a stable public HTTPS URL ending in `/mcp`. Check the tunnel, the exact path, and `forge mcp doctor`. Do not expose the local Controller UI port publicly.
+
+## MCP config seems to be in the wrong place
+
+Current service-level MCP config lives under Controller Home, not as the primary repo-local source:
+
+- `controllerHome/mcp/mcp.local.json`
+- `controllerHome/mcp/mcp.tokens.json`
+- `controllerHome/mcp/mcp.oauth.json`
+- `controllerHome/mcp/mcp.oauth-tokens.json`
+- `controllerHome/mcp/mcp.runtime.json`
+
+Controller Home is the sole authority for service-level MCP configuration. Repository-scoped `.forge/mcp.policy.json` remains the repository access policy; repository-local service configuration is unsupported. Rerun `forge mcp setup chatgpt --repo /path/to/your-project`, then verify the active endpoint and server name from Controller Home.
+
+## Only some tools appear in ChatGPT
+
+The default controller uses a stable repair-capable schema (normally 100–128 tools). Request/Full Access never changes that schema. Compare `expectedToolCount`, `actualToolCount`, `missingTools`, `unexpectedTools`, and the fingerprint from `rh_status` or `controller_ready`. Reconnect only when the Connector snapshot itself is stale, not after a permission change.
+
+## Runtime storage is not ready or the Local UI looks stale
+
+Do not delete `.ai/harness`, `.forge`, or Controller Home state as a first response. Start with bounded diagnostics:
+
+```bash
+forge mcp doctor --repo /path/to/your-project
+forge repo list --json
+```
+
+If you are using the operator surfaces, inspect the runtime-maintenance path before restarting or replaying writes. The self-healing and reliability docs describe the safe recovery flow:
+
+- `runtime_maintenance_status`
+- `runtime_maintenance_apply`
+- [Self-healing loop](../forge-runtime-self-healing-loop.md)
+- [Controller reliability runbook](controller-reliability-runbook.md)
+
+A `502`, reconnect, or truncated response does not prove a durable write failed. Confirm the Job, Run, or evidence summary before retrying the mutation.
+
+## Agent delegation is unavailable
+
+Core Direct Edit and repository workflows still work. Install and authenticate Codex or Claude, then restart MCP with the dev runner explicitly enabled. Do not enable agent flags in the basic setup unless the CLI is present.
+
+## Repository paths behave differently between Windows and WSL2
+
+Do not share one active checkout between native Windows and WSL2. Clone inside the environment that runs Forge and register that path. This avoids file-mode, line-ending, symlink, and performance problems.
+
+## Release checks fail on personal paths or logs
+
+Remove tracked runtime state, absolute home paths, credentials, logs, PID files, and generated artifacts. Do not add broad allowlist entries to silence genuine findings.

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

@@ -0,0 +1,70 @@
+# 安装与连接故障排查
+
+## 安装后找不到 `forge`
+
+先重新打开终端。npm 用户可执行 `npm config get prefix`，确认其可执行目录已加入 `PATH`；Bun 用户确认 Bun bin 目录已加入 `PATH`。
+
+```bash
+node --version
+npm --version
+bun --version   # 可选
+forge --version
+```
+
+## Doctor 提示缺少 Git 或 Node
+
+安装 Git 和 Node.js 20.10+ 后重新打开终端。即使 package 由 Bun 安装，发布后的启动器仍由 Node 执行，因此 Node 是基础依赖。
+
+## Windows 原生流程停在 shell 步骤
+
+仓库接入、Bash Hook、源码发布检查或 shell 生命周期脚本请使用 WSL2。Windows 原生会主动跳过 Bash skill 同步和 CodeGraph 自动配置。
+
+## 本机 MCP 正常，但 ChatGPT 无法连接
+
+`http://127.0.0.1:8765/mcp` 只能本机访问。ChatGPT 需要稳定的公网 HTTPS `/mcp` 地址。检查隧道、路径和 `forge mcp doctor`。不要把本地 Controller UI 端口暴露到公网。
+
+## MCP 配置看起来写到了错误的位置
+
+当前 service-level MCP 配置以 Controller Home 为主，不再以仓库内文件作为新安装主路径：
+
+- `controllerHome/mcp/mcp.local.json`
+- `controllerHome/mcp/mcp.tokens.json`
+- `controllerHome/mcp/mcp.oauth.json`
+- `controllerHome/mcp/mcp.oauth-tokens.json`
+- `controllerHome/mcp/mcp.runtime.json`
+
+Controller Home 是 service-level MCP 配置的唯一权威来源；仓库级 `.forge/mcp.policy.json` 仍是仓库访问策略。仓库内的 service 配置不再受支持。重新执行 `forge mcp setup chatgpt --repo /path/to/your-project` 后，从 Controller Home 核对当前 endpoint 与 server name。
+
+## ChatGPT 只显示少量工具
+
+默认 Controller 使用固定、可修复的工具 schema（通常 100–128 个工具）。Request/Full Access 不会改变 schema。请从 `rh_status` 或 `controller_ready` 对比 `expectedToolCount`、`actualToolCount`、缺失/意外工具和 fingerprint；只有 Connector 快照本身过期时才需要重连，权限切换不需要。
+
+## runtime storage 未就绪，或本地 UI 看起来是旧状态
+
+不要把删除 `.ai/harness`、`.forge` 或 Controller Home 状态当成第一反应。先做有界诊断：
+
+```bash
+forge mcp doctor --repo /path/to/your-project
+forge repo list --json
+```
+
+如果你正在使用运维/高级工具面，先走 runtime maintenance 路径，再决定是否重启或重放写操作。安全恢复流程见：
+
+- `runtime_maintenance_status`
+- `runtime_maintenance_apply`
+- [自修复闭环](../forge-runtime-self-healing-loop.md)
+- [Controller 可靠性 runbook](controller-reliability-runbook.md)
+
+看到 `502`、重连或大结果截断，不代表 durable 写入一定失败；先回到 Job、Run 或证据摘要确认真实状态。
+
+## 无法委派 Agent
+
+核心 Direct Edit 和仓库工作流仍可使用。安装并登录 Codex 或 Claude 后，再显式开启 dev runner。基础配置不应默认加入 Agent 参数。
+
+## Windows 与 WSL2 路径行为不一致
+
+不要让一个 checkout 同时由 Windows 和 WSL2 操作。在哪个环境运行 Forge，就在该环境内 clone 并注册仓库，避免文件 mode、换行、symlink 和性能问题。
+
+## 发布检查发现个人路径或日志
+
+应删除被跟踪的运行态、绝对用户目录、凭据、日志、PID 和生成物，不要用大范围 allowlist 掩盖真实问题。

package/docs/public-usage-guide.md

@@ -0,0 +1,33 @@
+# Public Usage Guide
+
+Use this page when you want the shortest current path through Forge without reading the entire docs tree first.
+
+## Fast path
+
+1. [Install and start](tutorials/01-install-and-start.md)
+2. [Connect ChatGPT](tutorials/02-connect-chatgpt.md)
+3. [Complete the first repository task](tutorials/03-first-repository-task.md)
+
+## What Forge is
+
+Forge is a local execution bridge that lets ChatGPT work on one or more repositories through a stable, bounded tool schema. The preferred orchestration tools are `rh_status`, `rh_access`, `rh_context`, `rh_work`, and `rh_inbox`, while the default schema also exposes practical Direct Edit, command, Git, Agent, Campaign, iOS, plugin, artifact, and recovery entry points.
+
+Direct Edit is the default for small known changes. `quick_agent_session` provides a direct local Codex/Claude path without requiring an Issue or Task. Durable Issue → Task → Run flows remain available for work that must survive sessions, carry dependencies, or preserve formal review evidence. Request/Full Access changes approval behavior only and never requires reconnecting the MCP Connector.
+
+## Current runtime facts
+
+- Controller Home is primary for MCP service config, authentication, and runtime state under `controllerHome/mcp/`: `mcp.local.json`, `mcp.tokens.json`, `mcp.oauth.json`, `mcp.oauth-tokens.json`, and `mcp.runtime.json`.
+- The matching repo-local `.Forge/mcp.local.json`, `.Forge/mcp.tokens.json`, `.Forge/mcp.oauth.json`, `.Forge/mcp.oauth-tokens.json`, and `.Forge/mcp.runtime.json` files are legacy fallback only. Repository-scoped `.Forge/mcp.policy.json` remains the access policy.
+- The controller is global across registered repositories, but repository work still routes by explicit `repoId` and `checkoutId`.
+- The public MCP endpoint is separate from the localhost-only Local Controller UI on `127.0.0.1:8766`. The UI is an execution-assistant console with Command Center, Approvals and Decisions, Current Work, Capabilities / Plugins, Models / Tools, System Status, Repositories, and Advanced Diagnostics.
+- Long-running work returns durable Jobs/Runs with bounded previews. Check those records before assuming a `502`, reconnect, or truncated response means the write failed.
+
+## Choose the next guide by goal
+
+- Need install and connector setup: [Tutorials](tutorials/README.md)
+- Need manual MCP/tunnel details: [Forge ChatGPT MCP setup](Forge-chatgpt-mcp-setup.md)
+- Need provider or executor routing: [Provider configuration and routing](operations/provider-configuration.md)
+- Need browser, Gmail/Calendar, or other plugins: [Documentation hub](README.md)
+- Need troubleshooting or runtime-storage recovery: [Troubleshooting](operations/troubleshooting.md), [Self-healing loop](Forge-runtime-self-healing-loop.md)
+
+For the broader map, use the maintained [documentation hub](README.md).

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

@@ -0,0 +1,33 @@
+# 公开使用指南
+
+如果你只想用最短路径理解并开始使用 Forge，先看这一页。
+
+## 最短路径
+
+1. [安装并启动](tutorials/01-install-and-start.zh-CN.md)
+2. [连接 ChatGPT](tutorials/02-connect-chatgpt.zh-CN.md)
+3. [完成第一个仓库任务](tutorials/03-first-repository-task.zh-CN.md)
+
+## Forge 是什么
+
+Forge 是一个本地执行桥，让 ChatGPT 通过固定且有边界的工具 schema 处理一个或多个仓库。日常编排优先使用 `rh_status`、`rh_access`、`rh_context`、`rh_work` 和 `rh_inbox`；默认工具面同时提供 Direct Edit、命令、Git、Agent、Campaign、iOS、插件、artifact 和恢复能力。
+
+小而确定的修改默认走 Direct Edit；`quick_agent_session` 可以直接调用本地 Codex/Claude，不强制先创建 Issue 或 Task。需要跨会话恢复、带依赖拆分或保留正式审查证据的工作，仍可进入 durable 的 Issue → Task → Run 路径。Request/Full Access 只改变审批行为，不会要求重连 MCP Connector。
+
+## 当前运行时事实
+
+- Controller Home 是 MCP service 配置、认证和运行态的主存储位置；`controllerHome/mcp/` 下保存 `mcp.local.json`、`mcp.tokens.json`、`mcp.oauth.json`、`mcp.oauth-tokens.json` 和 `mcp.runtime.json`。
+- 对应的 repo-local `.Forge/mcp.local.json`、`.Forge/mcp.tokens.json`、`.Forge/mcp.oauth.json`、`.Forge/mcp.oauth-tokens.json`、`.Forge/mcp.runtime.json` 只用于 legacy fallback；仓库级 `.Forge/mcp.policy.json` 仍是访问策略文件。
+- Controller 是跨已注册仓库的全局服务，但仓库工作仍通过显式 `repoId` 和 `checkoutId` 路由。
+- 公网 MCP endpoint 与 `127.0.0.1:8766` 上仅限本机访问的 Local Controller UI 是不同入口。当前 UI 是执行助手控制台，包含指挥中心、审批与决定、当前任务、能力 / 插件、模型与工具、系统状态、仓库和高级诊断。
+- 长任务默认返回 durable Job / Run 的摘要和有界预览；看到 `502`、重连或大结果截断时，先确认 Job / Run 状态，不要直接假定写入失败。
+
+## 按目标继续阅读
+
+- 需要安装和 Connector 细节：看 [教程目录](tutorials/README.zh-CN.md)
+- 需要 MCP / 隧道 / OAuth 手动配置：看 [Forge ChatGPT MCP 配置](Forge-chatgpt-mcp-setup.md)
+- 需要 provider 或 executor 路由：看 [Provider 配置与路由](operations/provider-configuration.md)
+- 需要浏览器、Gmail/Calendar 或其他插件：看持续维护的 [文档中心](README.md)
+- 需要故障排查或 runtime-storage 恢复：看 [故障排查](operations/troubleshooting.zh-CN.md) 和 [自修复闭环](Forge-runtime-self-healing-loop.md)
+
+更完整的导航请回到持续维护的[文档中心](README.md)。

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

@@ -0,0 +1,93 @@
+# Tutorial 1: Install and start
+
+This tutorial installs the CLI, initializes the user-level runtime, checks the host, and registers one repository.
+
+## 1. Platform and prerequisites
+
+- macOS or Linux: full supported workflow.
+- Windows: use WSL2 for the full workflow.
+- Native Windows PowerShell: preview support for installation, doctor, repository registration/inspection, and portable controller operations.
+
+Install Git, Node.js 20.10 or newer, npm, and a writable home directory. Bun 1.0+ is optional and recommended for source development and the complete test suite.
+
+```bash
+git --version
+node --version
+npm --version
+```
+
+See [Platform Support](../operations/platform-support.md) for the exact matrix.
+
+## 2. Install the CLI
+
+Release candidates are published on npm's `next` channel:
+
+```bash
+npm install -g @moretea-labs/forge@next
+# or
+bun add -g @moretea-labs/forge@next
+forge --version
+```
+
+For Forge source development, install from the repository instead:
+
+```bash
+git clone https://github.com/moretea-labs/forge.git
+cd forge
+npm ci --ignore-scripts --no-audit --no-fund
+npm install -g . --omit=optional --no-audit --no-fund
+```
+
+The package exposes exactly `forge`, `forge-hook`, and `forge-runtime`. Release candidates use `next`; stable releases use `latest`.
+
+## 3. Open the guided setup session
+
+```bash
+forge --version
+forge setup open --target both
+```
+
+`forge setup open` creates or resumes one user-level setup session below `~/.forge/setup/`. It runs the readiness checks and prints exactly one next configuration action. Complete that action, then continue with the same command loop:
+
+```bash
+forge setup next
+```
+
+Repeat `forge setup next` until the session reports `ready`, then close it:
+
+```bash
+forge setup close
+```
+
+Use `forge setup status` to inspect the persisted session and `forge setup check` for a one-shot read-only report. `--target codex` or `--target claude` limits host-specific configuration. The setup session never silently performs remote, secret-bearing, destructive, or service-installing actions.
+
+## 4. Adopt or register a repository
+
+For macOS, Linux, or WSL2, preview adoption first:
+
+```bash
+forge adopt --repo /path/to/your-project --dry-run
+forge adopt --repo /path/to/your-project
+```
+
+All platforms can register explicitly:
+
+```bash
+forge repo register /path/to/your-project --name my-project --json
+forge repo list --json
+```
+
+Keep the returned `repoId`; it is the stable repository identity used by ChatGPT and the Controller.
+
+## 5. Confirm readiness
+
+```bash
+forge setup status
+forge doctor
+forge status --json
+forge repo list --json
+```
+
+Runtime state belongs in Controller Home and ignored repository links, not in public source control. Never commit tokens, MCP runtime files, local jobs, logs, or generated worktrees.
+
+Continue with [Tutorial 2: Connect ChatGPT](02-connect-chatgpt.md). For errors, use [Troubleshooting](../operations/troubleshooting.md).