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

package/docs/forge-chatgpt-mcp-setup.md

@@ -1,239 +1,130 @@
-# forge ChatGPT Controller Setup
+# Forge ChatGPT Controller — Low-level Reference
 
-## Purpose
+> For normal onboarding, start with `forge setup` and [Tutorial 2](tutorials/02-connect-chatgpt.md). This file is the lower-level MCP reference and may also be regenerated by repository-scoped compatibility setup.
 
-The `controller` profile makes ChatGPT the project control plane. ChatGPT can inspect code and documents, maintain durable Issues and dependency-aware Tasks, apply bounded direct edits, publish Issues to GitHub Projects, dispatch short local Codex/Claude runs or visible GitHub Copilot cloud sessions, and review the resulting state. Repository files remain the source of truth; chat history is not required for recovery.
+## Product model
 
-## Prerequisites
+Forge has no internal AI brain. ChatGPT is one external controller option: ChatGPT decides semantic next steps, while Forge owns bounded execution, durable state, authorization, Runtime lifecycle, and evidence. Codex/Claude are optional and are not enabled merely because they are installed.
 
-- A forge adopted repository.
-- Bun and the `forge` CLI on PATH.
-- Codex and/or Claude CLI installed for delegated local execution.
-- GitHub CLI `gh` authenticated when GitHub Issues, Projects, or Copilot cloud sessions are used.
-- ChatGPT workspace access to Developer Mode and custom MCP Connectors.
-- A public HTTPS `/mcp` endpoint for ChatGPT.
+## Normal package path
 
-For a shared editable installation, keep the forge checkout at a stable path such as `~/DevProjects/forge`, run `bun install`, and reinstall the CLI after pulling updates.
-
-## One-time setup
-
-```bash
-forge mcp setup chatgpt --repo .
-forge runtime service install   --controller-home <absolute-controller-home>   --repo <absolute-repo-root>   --host 127.0.0.1   --port 8765
-```
-
-The `controller` profile writes the service-level MCP configuration consumed by the single `forge-runtime`. The macOS launchd service starts and restarts that one root process; Gateway, Controller Services, Scheduler, and MCP Transport share the same Runtime lifecycle owner. There is no MCP KeepAlive wrapper or component-level lifecycle command.
-
-The Runtime endpoint is loopback-only at `http://127.0.0.1:8765/`. The local visual controller surface is part of the same Runtime configuration; do not expose it directly.
-
-Health check:
+A repository is not required for the user-level ChatGPT connection:
 
 ```bash
-curl http://127.0.0.1:8765/ready
-forge runtime status --controller-home <absolute-controller-home>
-forge mcp doctor --repo .
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
 ```
 
-For a fixed Cloudflare domain, verify both local and public discovery without leaking tokens:
+The corresponding low-level commands are:
 
 ```bash
-curl http://127.0.0.1:8765/ready
-curl https://<named-tunnel-host>/.well-known/oauth-protected-resource/mcp
-env | grep -Ei 'proxy|no_proxy'
-HTTPS_PROXY= HTTP_PROXY= ALL_PROXY= curl -v https://<named-tunnel-host>/mcp
+forge mcp setup chatgpt --user-level
+forge runtime service install-package
+forge runtime status --json
 ```
 
-If a local HTTP proxy interferes with endpoint checks, add the fixed domain, `*.trycloudflare.com`, `*.ts.net`, and `100.64.0.0/10` to `NO_PROXY` instead of disabling proxies globally.
+The Package Runtime does not require a Forge Git checkout, Bun compilation, CodeGraph, or Standalone Recovery. The older `forge runtime service install --repo ...` command is an advanced source/immutable-release path.
 
-The controller profile stores service-level MCP config under `controllerHome/mcp/mcp.local.json`, including allowed local agents, timeout, endpoint, and `chatgpt.serverName`. OAuth credentials live in `controllerHome/mcp/mcp.oauth.json`; the bearer fallback lives in `controllerHome/mcp/mcp.tokens.json`. Existing repo-local `.forge/mcp.*` files remain a legacy fallback.
+## Local boundaries
 
-Repository-specific MCP access rules may be added in `.forge/mcp.policy.json`. Repository policy can narrow access, but immutable secret, credential, Git-internal, and build-output denies remain enforced.
-
-## Stable endpoint
-
-Use this Connector URL:
+Forge keeps two MCP boundaries on loopback by default:
 
 ```text
-<https-tunnel-url>/mcp
+ChatGPT OAuth Gateway: http://127.0.0.1:8767/mcp
+Canonical Runtime:      http://127.0.0.1:8765/mcp
 ```
 
-Quick tunnels are useful for one-off smoke tests, but their URL may change. For routine use, prefer a fixed Cloudflare domain. Forge never owns the tunnel process: publish the loopback Runtime endpoint through your own stable HTTPS tunnel. With Cloudflare, create and route a named tunnel:
+The OAuth Gateway is the endpoint for Secure Tunnel or HTTPS connectors. It proxies authenticated controller traffic to the bearer-only Canonical Runtime; remote clients should never target the internal Runtime directly. `forge mcp setup chatgpt --user-level` records the actual OAuth endpoint, so custom ports remain supported.
 
-```bash
-cloudflared tunnel login
-cloudflared tunnel create forge-mcp
-cloudflared tunnel route dns forge-mcp <named-tunnel-host>
-cloudflared tunnel run forge-mcp
-```
-
-Keep forge on the fixed public origin without owning the tunnel process:
+Fresh user-level setup keeps the repository-centric Utility Console disabled until a repository/workbench target is configured. When enabled later it uses a separate loopback port (normally 8766). Never expose it to the internet.
 
-```bash
-forge mcp setup chatgpt --repo . --endpoint https://<named-tunnel-host>/mcp
-forge runtime service install --controller-home <absolute-controller-home> --repo <absolute-repo-root> --host 127.0.0.1 --port 8765
-```
-
-Regenerate this guide with the stable endpoint:
-
-```bash
-forge mcp setup chatgpt --repo . --endpoint <https-url>/mcp
-```
-
-The real endpoint stays in ignored local config; the tracked guide stays placeholder-only. The OAuth discovery endpoint includes `oauth-protected-resource` metadata.
-
-## Create the ChatGPT Connector
-
-1. Open ChatGPT Settings and enable Developer Mode.
-2. Create a custom Connector using the server name from `controllerHome/mcp/mcp.local.json` under `chatgpt.serverName`.
-3. Paste the public HTTPS URL ending in `/mcp`.
-4. Configure Connector authentication as OAuth. ChatGPT must use the `/mcp` OAuth URL; do not point ChatGPT at `/mcp-bearer`.
-5. Scan tools and authorize with the passphrase from `controllerHome/mcp/mcp.oauth.json`.
-6. Keep write confirmations enabled.
-7. Re-scan tools after updating forge tool schemas.
-
-### Grok and other OAuth MCP clients
-
-Current Grok custom connectors support OAuth dynamic client registration + PKCE. Use the same canonical endpoint as ChatGPT:
-
-```text
-<https-tunnel-url>/mcp
-```
+Service-level MCP configuration lives below `Controller Home/mcp/`. OAuth credentials and bearer fallback tokens are local secrets and must not be pasted into chat or committed. Repository-specific `.forge/mcp.policy.json` can narrow access when a repository is later adopted.
 
-Do not use the legacy /mcp-grok route for new connectors. Grok's current OAuth callback is /connectors-oauth-exchange-code/ on grok.com; forge accepts that callback through dynamic registration or its public-client fallback.
+## App identity vs. transport
 
-### Non-OAuth MCP clients
+The ChatGPT App/connector is the application identity and owns the visible Forge tool schema. **Secure MCP Tunnel is the transport.** Switching an existing Forge App from a public HTTPS/Cloudflare route to Tunnel changes how commands reach Forge; it does not create a second Forge tool schema.
 
-Clients that cannot complete OAuth dynamic client registration + PKCE should use the dedicated bearer endpoint instead of `/mcp` or `/authorize`:
+Default path:
 
 ```text
-<https-tunnel-url>/mcp-bearer
+ChatGPT App -> OpenAI Secure MCP Tunnel -> tunnel-client
+            -> Forge loopback OAuth Gateway -> Canonical Runtime
 ```
 
-Authenticate with `Authorization: Bearer <token>` using the token stored under `controllerHome/mcp/mcp.tokens.json` (or `FORGE_MCP_TOKEN`). Do not paste the raw token into chat or docs. `/health` advertises both `mcpEndpoint` and `bearerEndpoint`. Incomplete OAuth hits on `/authorize` return HTTP 400 and point clients to `/mcp-bearer`.
-
-## Verify the loaded tool surface
-
-Default `--toolset core` exposes the five-tool ChatGPT facade (`rh_access`, `rh_status`, `rh_inbox`, `rh_context`, `rh_work`) plus bounded repository discovery/edit escape hatches. Use `--toolset advanced` for the supervised typed controller menu or `--toolset full` for exhaustive legacy compatibility. Confirm all five `rh_*` tools appear after connect. If only legacy planning tools are visible, refresh or recreate the Connector so ChatGPT reloads the MCP tool schema.
-
-## Refresh newly added repository tools
+A fresh chat is useful for isolated A/B testing, but Forge does not require a new conversation merely because transport changed when the same App is already connected and its tool schema is unchanged. If published tool definitions change, use ChatGPT's current app refresh/re-publish workflow.
 
-For the current repository only, prefer a bounded local restart:
+Upgrade existing Forge installs with:
 
 ```bash
-forge recovery restart-runtime --controller-home <absolute-controller-home>
+npm install -g @moretea-labs/forge@latest
+forge --version
+forge setup next
 ```
 
-The single Runtime restart also refreshes repository tools. There is no per-repository rollout or component restart surface, and you never need to compute the launchd label or hand-write `launchctl kickstart` for routine maintenance.
-
-After the restart, rescan or recreate the ChatGPT Connector, then call `controller_capabilities` again and verify `expectedTools` still includes `repository_latest_source_diagnose` and `repository_bootstrap_local_project`.
-
-## Daily workflow
-
-Start a new ChatGPT conversation with:
+## Remote controller connection
 
-```text
-Use forge as the project controller. Read project_snapshot, current Issues, active Runs, and relevant code before deciding the next action. Keep work in small dependency-aware Tasks. Do not dispatch one large Issue as one agent run.
-```
+The setup profile owns the connection choice. Supported paths are:
 
-Typical requests:
+1. **OpenAI Secure MCP Tunnel** — preferred when the OpenAI organization/workspace has tunnel permission; no public inbound Forge endpoint is required. Forge stores only the non-secret `tunnel_id`. The runtime API key remains an `env:`/file reference owned by the official `tunnel-client`.
+2. **Cloudflare Tunnel** — stable public/internet-reachable HTTPS endpoint.
+3. **Tailscale Funnel** — HTTPS endpoint for compatible Tailscale environments.
+4. **Existing HTTPS** — user-managed reverse proxy/tunnel ending in `/mcp`.
+5. **None** — local setup only; remote connectivity can be configured later.
 
-```text
-Analyze this requirement and the current implementation. Create or update an Issue and split it into executable Tasks. Do not execute yet.
-```
+For OpenAI Secure MCP Tunnel, setup uses the official managed runtime surface and considers a matching local alias ready only when `tunnel-client` reports the configured `tunnel_id` running, healthy, and ready. Alias names are not tunnel identity.
 
-```text
-Inspect readiness for this Issue, publish it to GitHub when collaboration is useful, and launch at most two independent Tasks. Review every local diff or GitHub pull request and record verification evidence before accepting it.
-```
+For public HTTPS paths, the configured connector URL is:
 
 ```text
-Read the project board and failed Runs. Retry only the smallest failed Task, or re-plan the Issue when the original split is wrong.
-```
-
-```text
-This is a small local fix. Open a bounded edit session, modify only the named files, inspect the Git diff, run focused checks, and finalize or rollback the edit.
+<https-tunnel-url>/mcp
 ```
 
-## Persistent model
+Record a stable endpoint with:
 
-```text
-Issue
-  -> Task T1
-       -> Run 1
-       -> Run 2 (retry)
-  -> Task T2
-  -> Task T3
+```bash
+forge setup configure --controller chatgpt --tunnel existing --endpoint https://forge.example.com/mcp
 ```
 
-- Issues and Tasks are stored under `tasks/issues/` as JSON plus readable Markdown.
-- Agent jobs, logs, edit backups, and worktrees are stored under ignored `.ai/harness/` runtime directories.
-- A completed isolated agent Run moves its Task to review. ChatGPT must inspect it with `get_task_diff`, integrate it with `integrate_task_run`, record named-check and criterion evidence through `verify_task`, then explicitly accept it or request changes.
-- Dependency completion unlocks later Tasks automatically.
-- Any new ChatGPT conversation can recover state through `project_snapshot` and `get_project_board`.
-
-## Capability boundaries
-
-- `observe`: inspect repository state, search code, and read bounded file ranges.
-- `manage`: create Issues, dynamically split Tasks, inspect launch readiness, publish to GitHub Issues/Projects, update status, and maintain project documents.
-- `edit`: use a bounded edit session with allowed paths, SHA preconditions, change limits, backups, and rollback.
-- `execute`: dispatch a ready Task to an allowed local agent in an isolated worktree or to a visible GitHub Copilot cloud session.
-- Protected operations such as secrets, Git internals, package lockfiles, CI workflow changes, commits, merges, and pushes are not default controller actions.
+Forge synchronizes an explicitly recorded endpoint into the user-level ChatGPT MCP configuration. A configured URL is not proof of live end-to-end connectivity; verify from ChatGPT with a real tool call.
 
-Kernel-managed Agent goals and persistent Task Runs are retired. New work uses
-`rh_work` to create or continue a WorkContract, `rh_work.controller_claim` to
-establish ownership, and `rh_work.launcher_start` to begin an external
-SuperController session.
+## ChatGPT-side setup
 
-## Dev Mode Agent Runner
+ChatGPT developer-mode/MCP availability is controlled by the current ChatGPT plan and workspace policy. Follow OpenAI's current developer-mode documentation; Forge cannot bypass plan, administrator, RBAC, or tool-action restrictions.
 
-Local Agent execution is opt-in. GitHub cloud sessions use authenticated `gh` and do not require the local dev runner:
+- With **Secure MCP Tunnel**, create the ChatGPT app/connector using the Tunnel connection and the tunnel ID.
+- With **HTTPS**, use the stable URL ending in `/mcp` and Forge's OAuth flow.
+- Refresh/scan tools after Forge tool definitions change.
 
-The runner is enabled through the service-level MCP configuration written by `forge mcp setup chatgpt` (`devMode.agentRunner` and `devMode.allowedAgents`). It executes inside the single Forge Runtime's bounded worker processes; there is no separate `forge mcp serve` lifecycle to supervise.
+The bounded default surface intentionally exposes the preferred `rh_*` facade plus repository/source/check/process/plugin escape hatches. Do not switch to exhaustive compatibility mode merely to see more tool names.
 
-The runner defaults to 60 minutes per local Task and supports explicit values up to 12 hours. Requested values are validated and persisted unchanged; an invalid value fails instead of silently falling back to 120 seconds.
+## Verify
 
-The runner:
+Local Runtime:
 
-- accepts only configured `codex` or `claude` agents;
-- creates one persistent Run per Task;
-- normally creates an isolated Git worktree;
-- records prompt, process metadata, streaming stdout/stderr, structured events, and result under `.ai/harness/jobs/`;
-- never exposes arbitrary shell input through MCP;
-- does not commit, merge, or push automatically.
+```bash
+forge runtime status --json
+forge mcp doctor
+```
 
-Watch local or GitHub execution from a terminal:
+Then verify from the selected external controller:
 
-```bash
-forge controller runs --repo .
-forge controller watch <RUN-ID> --repo . --log
+```text
+Use Forge. Call rh_status and report whether the Runtime is ready. Do not modify anything yet.
 ```
 
-The `--log` view streams local Codex/Claude output while the process is running and polls GitHub cloud-session logs when available.
+A successful controller-to-Forge tool call is the meaningful end-to-end setup milestone.
 
-## Local Codex MCP
+## Optional controller entries
 
-Configure Codex to read forge state:
+Codex and Claude are configured only when explicitly selected:
 
 ```bash
-forge mcp setup codex --repo . --scope project
+forge mcp setup codex --scope user --profile controller
+forge mcp setup claude --scope user --profile controller
 ```
 
-The executor profile remains read-oriented. Controller-dispatched Codex work is scoped by the generated Task prompt and worktree.
-
-## Security
-
-- Keep OAuth passphrases, bearer tokens, tunnel tokens, `~/.codex/auth.json`, and other credentials out of chat and Git.
-- Keep the MCP server bound to loopback; expose it only through the authenticated tunnel.
-- Do not remove immutable hard-deny patterns in order to make a Task pass.
-- Review every completed local diff or GitHub pull request and record passing Verification Gate evidence before accepting a Task.
-- Use the smallest allowed path set and focused checks for direct edits.
+Multiple controller entries may coexist, while one external controller remains the semantic owner at a time.
 
-## Troubleshooting
+## Advanced source/Recovery path
 
-- ChatGPT cannot connect: verify the HTTPS tunnel ends in `/mcp` and local `/ready` responds.
-- Grok cannot connect: recreate it with the canonical `…/mcp` URL. The legacy `…/mcp-grok` URL is compatibility-only.
-- A genuinely non-OAuth client loops on `/authorize`: use `…/mcp-bearer` with a bearer token from `controllerHome/mcp/mcp.tokens.json`.
-- ChatGPT auth loops: retry authorization and inspect `controllerHome/mcp/mcp.oauth.json` first, then legacy `.forge/mcp.oauth.json` only when using fallback; do not paste the passphrase into chat.
-- Tool scan misses tools: restart the Forge Runtime service with `launchctl kickstart -k gui/$(id -u)/com.moretea.forge.runtime.<controller-home-suffix>`, then rescan or recreate the versioned Connector and verify `controller_capabilities.expectedTools` includes `repository_latest_source_diagnose` and `repository_bootstrap_local_project`.
-- Codex cannot see the MCP server: rerun `forge mcp setup codex --repo . --scope project`.
-- A quick tunnel URL changed: update the Connector URL or switch to a named tunnel.
-- A Task is blocked: inspect `get_task_run`, shrink or re-plan the Task, then retry that Task rather than redispatching the full Issue.
+Maintainers who intentionally need immutable Git/source releases and independent disaster recovery may use the source Runtime and Standalone Recovery documentation. Those mechanisms are not required by ordinary npm/package users and are deliberately excluded from normal setup.

package/docs/images/forge-banner-cn.svg

@@ -1 +1,26 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="320" viewBox="0 0 1280 320" role="img" aria-labelledby="title desc"><title id="title">Forge</title><desc id="desc">Forge 本地优先行动运行时</desc><rect width="1280" height="320" rx="36" fill="#111827"/><path d="M136 224V96h190v38H180v22h126v36H180v32h146v38H136Z" fill="#f9fafb"/><text x="376" y="190" fill="#f9fafb" font-family="system-ui, sans-serif" font-size="112" font-weight="700">Forge</text><text x="382" y="238" fill="#d1d5db" font-family="system-ui, sans-serif" font-size="28">本地优先行动运行时</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="420" viewBox="0 0 1280 420" role="img" aria-labelledby="title desc">
+  <title id="title">Forge</title><desc id="desc">Forge 让 ChatGPT 在明确权限边界内操作本机文件、命令、代码、浏览器、Apple 工作流与插件。</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#0b0d12"/><stop offset="1" stop-color="#171b24"/></linearGradient>
+    <linearGradient id="forge" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#ffb15c"/><stop offset="1" stop-color="#ff6b35"/></linearGradient>
+    <radialGradient id="glow" cx="0.18" cy="0.5" r="0.55"><stop offset="0" stop-color="#ff7a3d" stop-opacity="0.22"/><stop offset="1" stop-color="#ff7a3d" stop-opacity="0"/></radialGradient>
+  </defs>
+  <rect width="1280" height="420" rx="38" fill="url(#bg)"/><rect width="1280" height="420" rx="38" fill="url(#glow)"/>
+  <g opacity="0.12" stroke="#ffffff"><path d="M0 70H1280M0 140H1280M0 210H1280M0 280H1280M0 350H1280"/><path d="M160 0V420M320 0V420M480 0V420M640 0V420M800 0V420M960 0V420M1120 0V420"/></g>
+  <rect x="74" y="75" width="126" height="126" rx="28" fill="url(#forge)"/>
+  <path d="M108 170V106h67v18h-46v10h39v17h-39v19z" fill="#111318"/>
+  <text x="74" y="258" fill="#f8fafc" font-family="ui-sans-serif,system-ui,sans-serif" font-size="72" font-weight="760">Forge</text>
+  <text x="74" y="305" fill="#ff9b55" font-family="ui-sans-serif,system-ui,sans-serif" font-size="24" font-weight="700" letter-spacing="1">CHATGPT 决策，FORGE 执行</text>
+  <text x="74" y="344" fill="#b8c0cc" font-family="ui-sans-serif,system-ui,sans-serif" font-size="22">连接你的电脑、代码、浏览器与外部服务。</text>
+  <g font-family="ui-sans-serif,system-ui,sans-serif">
+    <rect x="700" y="78" width="190" height="72" rx="18" fill="#202631" stroke="#3b4556"/><text x="795" y="107" text-anchor="middle" fill="#9ba7b8" font-size="13" font-weight="700" letter-spacing="1.5">主控</text><text x="795" y="134" text-anchor="middle" fill="#f8fafc" font-size="22" font-weight="700">ChatGPT</text>
+    <path d="M895 114H945" stroke="#ff8a45" stroke-width="3"/><path d="M936 106l12 8-12 8" fill="none" stroke="#ff8a45" stroke-width="3"/>
+    <rect x="955" y="78" width="250" height="72" rx="18" fill="#27251f" stroke="#a65c2c"/><text x="1080" y="107" text-anchor="middle" fill="#ff9b55" font-size="13" font-weight="700" letter-spacing="1.5">行动层</text><text x="1080" y="134" text-anchor="middle" fill="#f8fafc" font-size="22" font-weight="700">Forge</text>
+    <g fill="#151a22" stroke="#343d4c">
+      <rect x="700" y="188" width="150" height="58" rx="16"/><rect x="866" y="188" width="150" height="58" rx="16"/><rect x="1032" y="188" width="173" height="58" rx="16"/>
+      <rect x="700" y="262" width="150" height="58" rx="16"/><rect x="866" y="262" width="150" height="58" rx="16"/><rect x="1032" y="262" width="173" height="58" rx="16"/>
+    </g>
+    <g fill="#e7ebf0" font-size="17" font-weight="650" text-anchor="middle"><text x="775" y="224">本机文件</text><text x="941" y="224">执行命令</text><text x="1118" y="224">Git 与代码</text><text x="775" y="298">浏览器</text><text x="941" y="298">Apple</text><text x="1118" y="298">插件</text></g>
+    <text x="700" y="363" fill="#8e99aa" font-size="15">明确权限 · 可恢复执行 · 可审查证据</text>
+  </g>
+</svg>

package/docs/images/forge-banner.svg

@@ -1 +1,26 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="320" viewBox="0 0 1280 320" role="img" aria-labelledby="title desc"><title id="title">Forge</title><desc id="desc">Forge local-first action runtime</desc><rect width="1280" height="320" rx="36" fill="#111827"/><path d="M136 224V96h190v38H180v22h126v36H180v32h146v38H136Z" fill="#f9fafb"/><text x="376" y="190" fill="#f9fafb" font-family="system-ui, sans-serif" font-size="112" font-weight="700">Forge</text><text x="382" y="238" fill="#d1d5db" font-family="system-ui, sans-serif" font-size="28">local-first action runtime</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="420" viewBox="0 0 1280 420" role="img" aria-labelledby="title desc">
+  <title id="title">Forge</title><desc id="desc">Forge gives ChatGPT a controlled action layer for local files, commands, code, browsers, Apple workflows, and plugins.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#0b0d12"/><stop offset="1" stop-color="#171b24"/></linearGradient>
+    <linearGradient id="forge" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#ffb15c"/><stop offset="1" stop-color="#ff6b35"/></linearGradient>
+    <radialGradient id="glow" cx="0.18" cy="0.5" r="0.55"><stop offset="0" stop-color="#ff7a3d" stop-opacity="0.22"/><stop offset="1" stop-color="#ff7a3d" stop-opacity="0"/></radialGradient>
+  </defs>
+  <rect width="1280" height="420" rx="38" fill="url(#bg)"/><rect width="1280" height="420" rx="38" fill="url(#glow)"/>
+  <g opacity="0.12" stroke="#ffffff"><path d="M0 70H1280M0 140H1280M0 210H1280M0 280H1280M0 350H1280"/><path d="M160 0V420M320 0V420M480 0V420M640 0V420M800 0V420M960 0V420M1120 0V420"/></g>
+  <rect x="74" y="75" width="126" height="126" rx="28" fill="url(#forge)"/>
+  <path d="M108 170V106h67v18h-46v10h39v17h-39v19z" fill="#111318"/>
+  <text x="74" y="258" fill="#f8fafc" font-family="ui-sans-serif,system-ui,sans-serif" font-size="72" font-weight="760">Forge</text>
+  <text x="74" y="305" fill="#ff9b55" font-family="ui-sans-serif,system-ui,sans-serif" font-size="24" font-weight="700" letter-spacing="1">CHATGPT DECIDES. FORGE ACTS.</text>
+  <text x="74" y="344" fill="#b8c0cc" font-family="ui-sans-serif,system-ui,sans-serif" font-size="22">A local-first action layer for your computer, code &amp; services.</text>
+  <g font-family="ui-sans-serif,system-ui,sans-serif">
+    <rect x="700" y="78" width="190" height="72" rx="18" fill="#202631" stroke="#3b4556"/><text x="795" y="107" text-anchor="middle" fill="#9ba7b8" font-size="13" font-weight="700" letter-spacing="1.5">CONTROLLER</text><text x="795" y="134" text-anchor="middle" fill="#f8fafc" font-size="22" font-weight="700">ChatGPT</text>
+    <path d="M895 114H945" stroke="#ff8a45" stroke-width="3"/><path d="M936 106l12 8-12 8" fill="none" stroke="#ff8a45" stroke-width="3"/>
+    <rect x="955" y="78" width="250" height="72" rx="18" fill="#27251f" stroke="#a65c2c"/><text x="1080" y="107" text-anchor="middle" fill="#ff9b55" font-size="13" font-weight="700" letter-spacing="1.5">ACTION LAYER</text><text x="1080" y="134" text-anchor="middle" fill="#f8fafc" font-size="22" font-weight="700">Forge</text>
+    <g fill="#151a22" stroke="#343d4c">
+      <rect x="700" y="188" width="150" height="58" rx="16"/><rect x="866" y="188" width="150" height="58" rx="16"/><rect x="1032" y="188" width="173" height="58" rx="16"/>
+      <rect x="700" y="262" width="150" height="58" rx="16"/><rect x="866" y="262" width="150" height="58" rx="16"/><rect x="1032" y="262" width="173" height="58" rx="16"/>
+    </g>
+    <g fill="#e7ebf0" font-size="17" font-weight="650" text-anchor="middle"><text x="775" y="224">LOCAL FILES</text><text x="941" y="224">COMMANDS</text><text x="1118" y="224">GIT &amp; CODE</text><text x="775" y="298">BROWSER</text><text x="941" y="298">APPLE</text><text x="1118" y="298">PLUGINS</text></g>
+    <text x="700" y="363" fill="#8e99aa" font-size="15">Bounded permissions · durable execution · reviewable evidence</text>
+  </g>
+</svg>

package/docs/operations/features.md

@@ -31,7 +31,7 @@ These features are part of the default local setup:
 
 ## Tool exposure
 
-The default `core` / `advanced` toolset exposes one bounded ChatGPT-facing schema of 20 tools: the five `rh_*` workflow facades (with code retrieval routed through `rh_context.search`), repository selection, `repository_command_execute`, exact source read, `repository_safe_patch_apply`, `run_check`, one typed `plugin_action_execute` dispatcher with plugin schemas routed through `rh_context`, managed process lifecycle, result retrieval, and approval resolution. Git / issue-task / campaign / edit-session / other plugin / browser / iOS / maintenance atomics remain registered as internal handlers and are reachable through the `full` compatibility profile, which exposes every historical definition. The MCP transport does not dynamically load domain schemas; hiding from the default surface is a static exposure decision, never a handler deletion.
+The default `core` / `advanced` toolset exposes one bounded ChatGPT-facing schema of 19 tools: the five `rh_*` workflow facades (with code retrieval routed through `rh_context.search`), repository selection, `repository_command_execute`, exact source read, `repository_safe_patch_apply`, `run_check`, one typed `plugin_action_execute` dispatcher with plugin schemas routed through `rh_context`, managed process lifecycle, result retrieval, and approval resolution. Git / issue-task / edit-session / other plugin / browser / iOS / maintenance atomics remain registered as internal handlers and are reachable through the `full` compatibility profile when still supported. Retired lifecycles are removed rather than kept as dormant compatibility handlers. The MCP transport does not dynamically load domain schemas.
 
 ## Execution choices
 

package/docs/operations/homebrew.md

@@ -1,13 +1,13 @@
 # Homebrew distribution plan
 
-Homebrew is planned as a convenience layer after the first stable release. It is not a separate implementation or version line.
+Homebrew is planned as a convenience layer after the first stable npm/GitHub release is published and verified. It is not a separate implementation or version line.
 
 ## Gate before creating a tap
 
 Do not publish a formula until all of the following are true:
 
-- `@moretea-labs/forge@1.4.0` exists on npm;
-- Git tag and GitHub Release `v1.4.0` exist and point to the tested commit;
+- `@moretea-labs/forge@1.5.1` exists on npm;
+- Git tag and GitHub Release `v1.5.1` exist and point to the tested commit;
 - the npm tarball has an immutable checksum;
 - macOS installation and `forge --version` / `forge doctor` tests pass;
 - upgrade and uninstall behavior is documented.

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

@@ -1,12 +1,12 @@
 # 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.
+Controller MCP uses one stable default schema so ChatGPT can reliably read, edit, run checks, use Git, delegate to local Agents, coordinate durable Goal/Work, capture iOS evidence, and recover from failures without a permission switch hiding tools.
 
 ## 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. |
+| **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, Goal/Work, 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. |
 
@@ -28,8 +28,8 @@ MCP `tools/list`, call validation, `/health`, `controller_ready`, `rh_status`, C
 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.
+2. **Typed atomic tools:** repository inspection, Direct Edit, command, Git, Work/Job, Issue/Task, Goal/Work, plugin, browser, iOS, artifact, and recovery handlers remain public because their schemas preserve operation-specific validation and evidence.
+3. **Internal handlers and capability registry:** capabilities are grouped as `controller`, `repository-core`, `git`, `issue-task`, `browser`, `ios`, `plugin`, `evidence`, and `runtime-maintenance`. `rh_status`, `rh_context`, and `controller_capabilities` expose this metadata.
 
 The MCP transport 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.
 
@@ -44,7 +44,7 @@ Remote writes, destructive actions, outside-repository paths, and secret access
 ## 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.
+- Use first-class Direct Edit, command, Git, `quick_agent_session`, Goal/Work, iOS, plugin, and artifact tools when the facade is not the shortest reliable path.
 - 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.
 

package/docs/operations/platform-support.md

@@ -1,62 +1,70 @@
 # 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.
+This document defines the currently claimed Forge user experience. It distinguishes the **normal packaged setup path** from source/maintainer infrastructure so users are not required to install development-only dependencies.
 
 ## Support matrix
 
-| Platform | Status | Recommended use |
+| Platform | Status | Normal user path |
 | --- | --- | --- |
-| 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. |
+| macOS | Supported | Package install, controller-first setup, Package Runtime via launchd, repositories, local files, MCP, browser/desktop providers, and plugins. |
+| Modern Linux | Supported | Package install, controller-first setup, Package Runtime via `systemd --user` when available, repositories, local files, MCP, and portable providers. |
+| WSL2 on Windows | Supported and recommended for Windows | Run the Linux Forge Runtime inside WSL2; Windows can still host ChatGPT/browser clients. |
+| Native Windows | Preview | Package install, setup, portable Runtime/MCP, repository registration/inspection, and portable capabilities. Automatic reboot-persistent Runtime ownership and every external provider combination are not yet claimed. |
 
-## Required environment
+## Base installation requirements
 
-All installations require:
+All normal 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;
+- Node.js 20.10 or newer;
+- npm (bundled with Node.js) or Bun as 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.
+**Git is optional until repository/software-work capabilities are enabled.** Bun is optional for ordinary package users. A Forge source checkout, CodeGraph, Codex, Claude, Standalone Recovery, Cloudflare, Tailscale, or OpenAI tunnel-client is not a base dependency.
 
-The following dependencies are optional and enable additional capabilities:
+Capability-specific dependencies include:
 
-- 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.
+- Git for repository adoption, Git operations, worktrees, commits, and source development;
+- Codex or Claude only when explicitly configured as an external controller/execution entry;
+- GitHub CLI for GitHub workflows that require it;
+- browser/OS provider prerequisites for browser or desktop automation;
+- Google/Apple/service credentials for their respective plugins;
+- one remote connection provider when a hosted controller must reach the loopback MCP endpoint.
 
-## Native Windows scope
+## Runtime ownership by platform
+
+Normal package users use:
+
+```bash
+forge runtime service install-package
+```
 
-The native PowerShell path is release-tested for:
+This path fingerprints the installed `@moretea-labs/forge` runtime surface and refuses to launch if that package content drifts from the recorded release identity.
 
-- 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.
+- **macOS:** launchd user service.
+- **Linux / WSL2 with user systemd:** `systemd --user` service with restart-on-failure.
+- **Linux without user systemd:** explicit portable detached-session fallback with a persistence warning.
+- **Native Windows:** portable user-process mode is preview. Forge does not currently claim automatic reboot persistence there.
 
-The following are not yet claimed as complete native Windows workflows:
+The source-oriented `forge runtime service install --repo ...` immutable-release command and Standalone Recovery remain advanced maintainer operations. They are not normal installation prerequisites.
 
-- Bash-owned repository migration and hook scripts;
-- the full source-release Bash gate;
-- automatic CodeGraph configuration;
-- every external agent CLI and tunnel combination.
+## Remote ChatGPT/MCP connection providers
 
-For those workflows, use WSL2. The native installer intentionally skips Bash skill synchronization and automatic CodeGraph setup instead of failing the whole installation.
+Forge keeps its MCP listener on loopback. A remote controller chooses one of these explicit connection methods:
 
-## WSL2 guidance
+| Provider | Inbound public exposure | Typical use |
+| --- | --- | --- |
+| OpenAI Secure MCP Tunnel | No | Preferred for ChatGPT/OpenAI-hosted clients when the organization has tunnel permission. Uses official `tunnel-client`; Forge stores only the non-secret tunnel ID. |
+| Cloudflare Tunnel | Yes / internet-reachable HTTPS | Stable named HTTPS endpoint when the user manages Cloudflare account/domain. |
+| Tailscale Funnel | Yes / internet-reachable HTTPS | Convenient when the user already operates a compatible Tailscale setup. |
+| Existing HTTPS `/mcp` | Depends on user infrastructure | Reverse proxy or tunnel already owned by the user. |
+| None | No | Local controller only, or remote connectivity configured later. |
+
+Setup detects the OS and available provider CLI. It does not assume Homebrew or macOS. Third-party authentication remains explicit and is never completed with credentials pasted into Forge setup.
 
-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.
+## Native Windows scope
 
-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.
+The native PowerShell path is release-tested for installer/CLI loading, doctor, setup/profile persistence, repository registry operations, Windows path/process behavior, and portable Node tests. Shell-heavy repository migration, every browser/provider integration, and persistent Windows service ownership remain outside the full-support claim; use WSL2 when those workflows are required.
 
 ## 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.
+The repository has platform/public-doc checks and a Windows smoke workflow. A platform claim means its named path is tested; it does not imply that every optional third-party provider is installed or available on every machine.