@moretea-labs/forge 1.5.0-rc.1

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

@@ -0,0 +1,239 @@
+# forge ChatGPT Controller Setup
+
+## Purpose
+
+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.
+
+## Prerequisites
+
+- 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.
+
+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:
+
+```bash
+curl http://127.0.0.1:8765/ready
+forge runtime status --controller-home <absolute-controller-home>
+forge mcp doctor --repo .
+```
+
+For a fixed Cloudflare domain, verify both local and public discovery without leaking tokens:
+
+```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
+```
+
+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 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.
+
+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:
+
+```text
+<https-tunnel-url>/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:
+
+```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:
+
+```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
+```
+
+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.
+
+### Non-OAuth MCP clients
+
+Clients that cannot complete OAuth dynamic client registration + PKCE should use the dedicated bearer endpoint instead of `/mcp` or `/authorize`:
+
+```text
+<https-tunnel-url>/mcp-bearer
+```
+
+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
+
+For the current repository only, prefer a bounded local restart:
+
+```bash
+forge recovery restart-runtime --controller-home <absolute-controller-home>
+```
+
+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:
+
+```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.
+```
+
+Typical requests:
+
+```text
+Analyze this requirement and the current implementation. Create or update an Issue and split it into executable Tasks. Do not execute yet.
+```
+
+```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.
+```
+
+```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.
+```
+
+## Persistent model
+
+```text
+Issue
+  -> Task T1
+       -> Run 1
+       -> Run 2 (retry)
+  -> Task T2
+  -> Task T3
+```
+
+- 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.
+
+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.
+
+## Dev Mode Agent Runner
+
+Local Agent execution is opt-in. GitHub cloud sessions use authenticated `gh` and do not require the local dev runner:
+
+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 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.
+
+The runner:
+
+- 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.
+
+Watch local or GitHub execution from a terminal:
+
+```bash
+forge controller runs --repo .
+forge controller watch <RUN-ID> --repo . --log
+```
+
+The `--log` view streams local Codex/Claude output while the process is running and polls GitHub cloud-session logs when available.
+
+## Local Codex MCP
+
+Configure Codex to read forge state:
+
+```bash
+forge mcp setup codex --repo . --scope project
+```
+
+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.
+
+## Troubleshooting
+
+- 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.

package/docs/forge-chatgpt-supervised-automation.md

@@ -0,0 +1,11 @@
+# Forge ChatGPT-Supervised Automation
+
+Forge models recurring or delegated work as bounded Schedules, Occurrences, Work contracts, Process executions, evidence, and explicit handoffs. ChatGPT or another external controller decides goals and semantic continuations; the Forge kernel persists ownership, enforces policy, executes deterministic operations, and records reviewable outcomes.
+
+Authoritative references:
+
+- [Automation and Schedule Engine](architecture/current/automation-and-schedule-engine.md)
+- [Dispatch and Agent Strategy](architecture/current/dispatch-and-agent-strategy.md)
+- [Failure Recovery](architecture/current/failure-recovery.md)
+
+Automation does not gain permission to publish, deploy, merge, send, or perform destructive effects without the required authorization.

package/docs/forge-github-issue-launcher.md

@@ -0,0 +1,7 @@
+# Forge GitHub Integration
+
+GitHub is an optional first-party Forge provider for repository collaboration and remote Issue/Project or pull-request operations. Local Requirement, Plan, Work, Process, Git, policy, evidence, and Runtime authority remain inside Forge; GitHub records are external collaboration artifacts, not a second lifecycle authority.
+
+Remote writes require explicit authorization and idempotent provider evidence. Configure the provider through the Forge CLI or plugin action surface and verify repository mapping before mutation.
+
+See [Integrations](wiki/Integrations.md), [Plugin baseline](architecture/current/personal-assistant-plugin-baseline.md), and [Verification and Release Gates](architecture/current/verification-and-release-gates.md).

package/docs/forge-plugin-management.md

@@ -0,0 +1,95 @@
+# Forge Plugin Management
+
+Forge 1.5 introduces a public installation path for independently released providers while keeping the Controller trust boundary small. Official providers are **separate products** with their own repositories and releases; Forge owns how those providers are selected, installed, registered, authorized, and executed.
+
+## Official catalog
+
+```bash
+forge plugin catalog
+```
+
+| Plugin ID | Product | Pinned release | Platforms |
+| --- | --- | --- | --- |
+| `desktop_operator` | [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | `v0.2.1` | macOS |
+| `design` | [Forge Design](https://github.com/moretea-labs/forge-design) | `v0.3.0` | macOS, Linux, Windows |
+| `personal_knowledge` | [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | `v0.2.1` | macOS, Linux, Windows |
+
+Investment Decision System remains an independent product and is intentionally not a Forge plugin.
+
+## Install and inspect
+
+```bash
+forge plugin install design
+forge plugin install personal_knowledge
+forge plugin install desktop_operator   # macOS
+forge plugin list --refresh
+```
+
+Re-running `forge plugin install <id>` installs the version currently pinned by Forge. A catalog version change is a reviewed Forge source change; providers cannot silently self-update through a ChatGPT request.
+
+## Trust boundary
+
+Official installation uses the package-owned [`assets/plugin-registry.v1.json`](../assets/plugin-registry.v1.json). Forge:
+
+1. resolves only catalog entries shipped with the installed Forge package;
+2. accepts only the fixed Moretea Labs HTTPS repository declared by that entry;
+3. checks out the immutable Git tag declared by the catalog;
+4. verifies the provider's `forge-plugin.json` identity and protocol declaration;
+5. runs the fixed `forge-plugin-install.mjs` installer entrypoint;
+6. validates the returned provider registration;
+7. writes it through the existing Controller Home external-registration authority;
+8. projects health and actions through the normal typed plugin surface.
+
+Forge does **not** scan sibling directories, accept a model-provided executable path, or provide a generic arbitrary-shell plugin transport.
+
+## Responsibility split
+
+### Forge core owns
+
+- trusted distribution and registration;
+- action schema and policy projection;
+- authorization and confirmations;
+- resource claims and concurrency boundaries;
+- idempotency and action receipts;
+- health projection and execution evidence.
+
+### External providers own
+
+- domain implementation;
+- provider-local data and configuration;
+- provider protocol implementation;
+- platform-specific installation details;
+- independent tests, releases, security policy, and support surface.
+
+This split keeps Forge extensible without moving product-specific implementation into the core repository.
+
+## Provider transports
+
+### `unix_socket_jsonl`
+
+Used by long-lived native providers such as Forge Desktop Operator. Forge connects to a stable local socket after trusted provider installation and lifecycle verification.
+
+### `managed_cli_json`
+
+Used by bounded one-shot providers such as Forge Design and Personal Knowledge Assistant. Forge launches a fixed runtime/helper pair from the installed package, validates the handshake, sends one bounded request, receives one bounded response, and terminates the process.
+
+Both transports resolve to the same `AssistantPluginManifest` and `plugin_action_execute` policy/evidence path.
+
+## Updates and rollback
+
+Provider package directories are versioned and installed transactionally. Trusted registration is replaced only after package identity and installer output validate. If a new provider release fails validation or health checks, the existing registration is not silently replaced with an untrusted or partially installed provider.
+
+Forge's catalog intentionally favors **reviewed pinned releases** over automatic marketplace-style updates. This is slower than an unbounded plugin marketplace and materially easier to audit.
+
+## Provider development
+
+Provider repositories expose their own development/install instructions. A provider release intended for the official catalog should have:
+
+- a public repository and immutable version tag;
+- a bounded `forge-plugin.json` contract;
+- a deterministic `forge-plugin-install.mjs` entrypoint;
+- focused protocol/health/action tests;
+- CI, security reporting, support, and contribution documentation;
+- no machine-specific paths, credentials, or user data in the public release.
+
+The catalog is updated only after a fresh-install acceptance test proves the provider can be installed without relying on local sibling repositories.

package/docs/forge-provider-configuration.md

@@ -0,0 +1,7 @@
+# Forge Provider Configuration
+
+Forge keeps provider selection separate from Runtime ownership. Codex, Claude, GitHub, browser, Google Workspace, Apple, iOS, Desktop, and other adapters execute bounded contracts through stable Forge policy, Process, receipt, and audit layers.
+
+Provider credentials are supplied through supported environment or OS credential mechanisms and are never copied into repository state or chat output. Provider availability does not change the one-Runtime topology.
+
+See [Provider configuration](operations/provider-configuration.md), [Plugin baseline](architecture/current/personal-assistant-plugin-baseline.md), and [Security Model](wiki/Security-Model.md).

package/docs/forge-runtime-self-healing-loop.md

@@ -0,0 +1,7 @@
+# Forge Runtime Self-Healing Loop
+
+The canonical Forge Runtime reconciles durable Work, Process, Lease, projection, plugin, and schedule state without creating another lifecycle owner. Recovery is evidence-driven and fail-closed: already-started commands are never blindly replayed, stale owners cannot mutate state, and uncertain writes require reconciliation or human attention.
+
+The OS service manager automatically starts and restarts the single `forge-runtime` process. Standalone Recovery remains independently installable for diagnostics, service repair, tunnel repair, and offline whole-Runtime rollback when the primary Runtime cannot start.
+
+See [Failure Recovery](architecture/current/failure-recovery.md), [Reliability runbook](operations/controller-reliability-runbook.md), and [Standalone disaster recovery](operations/standalone-disaster-recovery.md).

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

@@ -0,0 +1 @@
+<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>

package/docs/images/forge-banner.svg

@@ -0,0 +1 @@
+<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>

package/docs/images/forge-controller-flow.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="260" viewBox="0 0 1200 260" role="img" aria-labelledby="title"><title id="title">Forge canonical runtime flow</title><rect width="1200" height="260" fill="#fff"/><g font-family="system-ui, sans-serif" font-size="20" text-anchor="middle"><rect x="30" y="90" width="180" height="70" rx="12" fill="#e5e7eb"/><text x="120" y="132">Client</text><rect x="280" y="70" width="220" height="110" rx="12" fill="#111827"/><text x="390" y="122" fill="#fff">forge-runtime</text><text x="390" y="150" fill="#d1d5db" font-size="15">single lifecycle owner</text><rect x="570" y="90" width="190" height="70" rx="12" fill="#e5e7eb"/><text x="665" y="132">Repo Actor</text><rect x="830" y="90" width="160" height="70" rx="12" fill="#e5e7eb"/><text x="910" y="132">Process</text><rect x="1040" y="90" width="130" height="70" rx="12" fill="#e5e7eb"/><text x="1105" y="132">Evidence</text></g><g stroke="#374151" stroke-width="4" fill="none"><path d="M210 125h70"/><path d="M500 125h70"/><path d="M760 125h70"/><path d="M990 125h50"/></g></svg>

package/docs/operations/chatgpt-personal-assistant-runtime.md

@@ -0,0 +1,83 @@
+# ChatGPT-first Personal Assistant Runtime
+
+This runtime is designed for a local-first personal assistant where ChatGPT is the primary natural-language controller and Forge is the guarded local execution layer.
+
+## Product boundary
+
+The Local Controller should not be the main task input surface. It stores routines, inbox items, memory, approvals, audit events, device tokens, and plugin state. ChatGPT, MCP, or a GPT Action should translate natural language into one of the high-level assistant APIs.
+
+## High-level API surface
+
+Expose these endpoints to ChatGPT Actions instead of exposing every low-level plugin action:
+
+- `POST /api/assistant/intent` — submit a natural-language utterance or a ChatGPT-planned action list.
+- `GET /api/assistant/inbox` — read assistant outputs, routine results, and approval notes.
+- `GET /api/assistant/routines` — list saved routines.
+- `POST /api/assistant/routines` — create a routine from a natural-language goal.
+- `POST /api/assistant/routines/:routineId/run` — run one routine immediately.
+- `POST /api/assistant/routines/:routineId/pause` — pause a routine.
+- `POST /api/assistant/routines/:routineId/resume` — resume a routine.
+- `POST /api/assistant/routines/:routineId/delete` — soft-delete a routine.
+- `GET /api/assistant/memory` and `POST /api/assistant/memory` — read/write local preference memory.
+- `GET /api/assistant/openapi.json` — minimal OpenAPI schema for a Custom GPT Action.
+
+All `/api/*` routes still require the local controller token.
+
+## Intent modes
+
+`/api/assistant/intent` supports three modes:
+
+- `plan_only`: return the interpreted plan without submitting execution jobs.
+- `plan_then_execute`: plan and submit safe steps; block high-risk steps.
+- `execute`: submit the supplied plan directly through the same policy gate.
+
+The preferred ChatGPT flow is:
+
+1. ChatGPT understands the user request.
+2. ChatGPT asks for missing information or confirmation when needed.
+3. ChatGPT calls `/api/assistant/intent` with either the natural-language utterance or an explicit `plan`.
+4. Forge validates policy, creates durable Execution Jobs, stores an Assistant Inbox item, and returns display text.
+
+## Routine model
+
+A routine stores the user's natural-language goal rather than a traditional GUI rule form:
+
+```json
+{
+  "name": "每日邮件整理",
+  "naturalLanguageGoal": "每天早上 9 点整理过去 24 小时重要邮件，重点关注工作、API、BA、Jira、PR，用中文输出摘要。",
+  "scheduleText": "每天 09:00",
+  "dataSources": ["gmail", "calendar", "tasks"],
+  "output": "assistant_inbox",
+  "allowedActions": ["gmail.list_messages", "gmail.get_message"],
+  "forbiddenActions": ["gmail.send_message", "gmail.trash_message"]
+}
+```
+
+The first version stores the routine and can run it on demand. Automatic time-based scheduling should attach this store to the existing schedule engine in a later iteration.
+
+## Policy defaults
+
+Allowed without extra approval:
+
+- Read Gmail, Calendar, and Tasks.
+- Create a Google Task / reminder.
+- Create a Gmail draft.
+- Create a personal calendar event without attendees.
+
+Requires human approval:
+
+- Send email.
+- Trash email.
+- Cancel calendar event.
+- Reschedule calendar event.
+- Delete task.
+- Scheduled routine writes beyond explicitly allowed draft/reminder behavior.
+
+## Assistant Inbox
+
+Assistant Inbox is the user-facing result surface for routine outputs and intent execution records. ChatGPT can read it and then present the result conversationally, for example: "今天助理整理了什么？"
+
+## Current limitation
+
+The runtime does not embed a full NLP model. ChatGPT Actions should provide structure when precision matters. The local runtime includes conservative intent inference only for routine creation, reminders, and immediate mail-summary collection.

package/docs/operations/checkout-route-integrity.md

@@ -0,0 +1,22 @@
+# Checkout route integrity (P0)
+
+## Fail-closed pre-spawn guard
+
+Before Process Runtime spawns any managed process, an immutable `ResolvedExecutionIdentity`
+must match:
+
+- requested `repoId` / `checkoutId`
+- registered checkout lifecycle and realpath root
+- process `cwd` realpath inside the expected root
+- Git top-level equal to expected root
+- Git common-dir ownership of the registered repository
+- optional branch / expected HEAD from WorkHandle
+
+Mismatch codes include `EXECUTION_IDENTITY_MISMATCH`, `CHECKOUT_ROUTE_MISMATCH`,
+`GIT_TOPLEVEL_MISMATCH`, `GIT_COMMON_DIR_MISMATCH`, `WORK_HANDLE_BRANCH_CHANGED`,
+and `WORK_HANDLE_HEAD_CHANGED`. There is no silent fallback to main or another checkout.
+
+## Legacy WorkContract migration
+
+Legacy contracts may bind only through a unique exact WorkHandle match
+(`resolveLegacyWorkContractIdentity`). Ambiguous or incomplete identity is rejected.