@moretea-labs/forge 1.5.0-rc.1

package/docs/operations/controller-reliability-runbook.md

@@ -0,0 +1,134 @@
+# Controller reliability and automation runbook
+
+Use this runbook when forge processes are running but tasks do not move, the UI reports readiness that does not match actual execution, or one repository affects another repository's controller resources.
+
+## Interpret readiness in layers
+
+Do not treat a single `ready` value as proof that autonomous delivery is active.
+
+| Layer | What it proves | Typical evidence |
+| --- | --- | --- |
+| Runtime readiness | The complete Canonical Runtime passed release coherence, SQLite, in-process Scheduler, and authenticated MCP end-to-end checks. | `controller_ready.ready` plus diagnostic reason codes |
+| Execution readiness | A suitable executor is authenticated, enabled, and able to start bounded work. | executor preflight and recent run classification |
+| Delivery readiness | The task can be integrated, verified, accepted, and committed without unresolved repository conflicts. | clean selected paths, checks, integration evidence |
+| Automation readiness | At least one enabled **live** schedule or live goal can create execution work. | schedule policy, occurrence status, budget and cooldown |
+
+A shadow schedule is observation-only. It may emit `would_execute` or `shadowed`, but it does not queue or start an Execution Job. A configured provider is also not proof that work is currently running.
+
+## First response sequence
+
+1. Read `controller_ready` and note reason codes, source coherence, queue depth, running workers, active leases, current attention, and plugin summary.
+2. Run `capability_recovery_probe` (and `capability_recovery_plan` when needed) to classify the blocker without mutating state.
+3. If runtime metadata or projection state is degraded, inspect `runtime_maintenance_status` before requesting any external lifecycle action.
+4. Apply `runtime_maintenance_apply` only for a reviewed bounded metadata candidate. It may reconcile local jobs or rebuild projections; it must not perform Runtime lifecycle changes or source-code repair.
+5. Re-run `controller_ready` and `rh_status`, then retry the original operation with the same intent. If source coherence is blocked, follow the external lifecycle handoff for the existing single `forge-runtime`; do not attempt an in-process restart, component restart, second Runtime, or rollout.
+
+## Schedule diagnosis
+
+Use `list_schedules` with occurrences enabled and classify each enabled schedule:
+
+- **shadow**: `policy.shadowMode` is true; no execution should be expected.
+- **live but idle**: live schedule exists, but no occurrence is `created`, `queued`, or `running`.
+- **live and active**: a live schedule has an occurrence in one of those active states.
+- **blocked by policy**: occurrence is suppressed by cooldown, failure threshold, daily budget, dependency, or stop condition.
+
+Do not turn every schedule live. Health snapshots and cleanup previews should normally remain shadow/read-only. Enable live execution only for a bounded action with explicit budget, cooldown, failure limit, and stop conditions.
+
+## Failed-run classification
+
+Classify the last failure before retrying:
+
+- `auth_required`: authenticate the named executor or plugin; do not retry in a loop.
+- `usage_limit` or provider capacity: select an allowed fallback or wait for the provider boundary to clear.
+- interactive stdin / startup timeout: fail fast and relaunch with a non-interactive invocation.
+- canonical Runtime process disappeared: reconcile the run as `unknown`, then inspect Runtime ownership and standalone Recovery evidence before retrying.
+- patch precondition failed: refresh file fingerprints and reapply only selected paths. Never overwrite unrelated dirty work.
+- check failure: separate failures introduced by the current diff from known baseline failures and retain both evidence sets.
+
+A stale health label must not override live run evidence. A run that is producing heartbeats, edits, and test output is active even if an old executor snapshot still says `auth_required`; fix the stale status projection rather than discarding the run.
+
+## Multi-repository resource isolation
+
+High CPU must be attributed to a repository before action. Record the process command, repository root, PID, CPU, and owner controller. A busy MCP process from another repository is a peer-repository incident, not proof that the current repository is unhealthy.
+
+Recommended policy:
+
+- one controller-home repository namespace per registered repository;
+- repository-scoped leases, schedules, local jobs, and cleanup candidates;
+- per-repository CPU/memory diagnostics and watchdog thresholds;
+- no cross-repository process termination from a repository-scoped repair action;
+- explicit operator authorization before terminating a peer repository process.
+
+## Whole-Runtime restart and reconnect contract
+
+`CanonicalForgeRuntime` is the only core lifecycle owner. Repository tools, MCP handlers, Workers, Local Bridge, diagnostics, and tunnels cannot start, stop, restart, adopt, roll out, or roll back a core component. The repository no longer contains Supervisor, KeepAlive, restart-coordinator, or component lifecycle shell entrypoints.
+
+A release change is performed only as an explicitly authorized whole-Runtime operation:
+
+1. validate one immutable release manifest, configuration, database compatibility range, and Worker protocol;
+2. quiesce admission and stop the complete Runtime;
+3. atomically select the candidate as the one active whole release;
+4. let the single Forge Runtime service start `forge-runtime` from that complete release;
+5. require binary whole-Runtime readiness;
+6. on failure, stop the service, restore the previous release and its bound local SQLite backup, then start and verify the complete previous Runtime.
+
+There is no blue-green pair, fixed alternate port, slot adoption, mixed-generation traffic, or component rollback. Release safety comes from pre-activation canaries, immutable artifacts, one atomic active/previous authority, whole-Runtime readiness, and previous-release recovery.
+
+A whole-Runtime restart closes in-flight MCP sockets. Continuity comes from durable request, Work, Job, and evidence identifiers, not from a traffic router or component adoption. Retry the same idempotent request after the endpoint is healthy and continue reading the existing durable state. Recreate or rescan the ChatGPT Connector only after an authentication/schema change or an explicit connector-staleness result.
+
+The standalone Recovery watchdog uses the same service and release contracts. It first attempts a bounded whole-Runtime service restart. After the configured attempts are exhausted, it permits automatic previous-release recovery only with sustained independent failure evidence and an attested previous release. One Recovery lock prevents concurrent restart or rollback storms.
+
+After a restart or automatic recovery, confirm:
+
+1. `controller_ready.ready` is true and all diagnostic evidence belongs to the same Runtime instance and release.
+2. `controller_capabilities` reports the expected tool fingerprint.
+3. The public `/health` and OAuth protected-resource endpoint return valid responses.
+4. Previously accepted Work/Job identifiers remain readable and no mutation was blindly replayed.
+5. No old Worker can renew Leases or commit results under the new Runtime/release fence.
+
+## Cleanup
+
+Run cleanup as preview-first work:
+
+1. Inspect `runtime_cleanup` or the cleanup preview from performance diagnostics.
+2. Select only forge-owned, repo-scoped candidates.
+3. Exclude active worktrees, active local jobs, pending approvals, and processes whose ownership is uncertain.
+4. Apply `runtime_cleanup_apply` with an age threshold and bounded candidate count.
+5. Confirm that the repository projection and active work remain intact.
+
+Temporary directories should have a TTL, but age alone is not sufficient: current leases and worktree registration remain authoritative.
+
+## Plugin degraded states
+
+Distinguish lifecycle from action readiness:
+
+- `enabled + ready`: configured actions can run, subject to confirmation policy.
+- `enabled + degraded`: plugin is selected but missing auth, permission, or provider availability.
+- `disabled`: not part of the current capability set.
+- `ready but not applicable`: tooling exists, but the repository has no matching project or artifact.
+
+For Google Workspace plugins, resolve the specific credential source and required scope. Do not report the whole controller as delivery-ready when a task requires a degraded plugin.
+
+## Board governance
+
+A healthy runtime can still have an unhealthy delivery board. Regularly:
+
+- select one current focus when focus is required;
+- review completed tasks and accept verified work;
+- retry or explicitly unblock failed attempts;
+- archive terminal issues after evidence is retained;
+- keep generated runtime metadata out of long-lived source diffs;
+- clean merged worktrees and delete merged branches.
+
+Do not create more automation work while review, acceptance, and failed-run queues are growing unchecked.
+
+## Exit criteria
+
+Reliability work is complete only when:
+
+- runtime and projection report a coherent state;
+- automation reporting distinguishes shadow, live-idle, and live-active states;
+- targeted checks pass or remaining baseline failures are explicitly documented;
+- selected-path changes are committed without absorbing unrelated work;
+- the feature branch is merged and its worktree is removed;
+- no destructive cleanup or peer-repository process action occurred without authorization.

package/docs/operations/environment-hardening.md

@@ -0,0 +1,50 @@
+# Environment and DX hardening
+
+forge supports two local development profiles:
+
+1. **Full Bun profile** — required for the exhaustive `bun:test` suite and Bun-native scripts.
+2. **Portable Node profile** — supports install, CLI launch, typecheck, runtime smoke checks, and Node smoke tests when Bun is not available.
+
+## Commands
+
+```bash
+npm run check:env
+npm run check:type -- --pretty false
+npm test
+npm run check:ci:portable
+```
+
+`npm test` now uses `scripts/run-tests-portable.sh`. When Bun is installed it runs the full Bun test suite. When Bun is missing it runs `tests/node/*.test.mjs` and prints a clear warning that exhaustive tests still require Bun.
+
+## Full CI
+
+```bash
+bash scripts/check-ci.sh
+```
+
+Full CI still requires Bun because the repository test suite imports `bun:test` in many files. To run a Node-only gate instead:
+
+```bash
+FORGE_ALLOW_NODE_ONLY=1 bash scripts/check-ci.sh
+```
+
+## Installation runtime selection
+
+`install.sh` supports:
+
+```bash
+FORGE_INSTALL_RUNTIME=auto ./install.sh
+FORGE_INSTALL_RUNTIME=node ./install.sh
+FORGE_INSTALL_RUNTIME=bun ./install.sh
+```
+
+`auto` uses Bun when available and falls back to Node.js 20+ with npm when Bun is missing.
+
+## Dev container
+
+```bash
+docker build -f Dockerfile.dev -t forge-dev .
+docker run --rm -it -v "$PWD:/workspace" forge-dev bash
+```
+
+The dev container includes Node, npm, Bun, bash, git, and OpenSSH client so CI and local smoke commands behave consistently across machines.

package/docs/operations/features.md

@@ -0,0 +1,45 @@
+# Features and Setup Levels
+
+Forge is useful without coding agents or external plugins. Start with the core workflow, then add integrations only when a task requires them.
+
+## Core features
+
+These features are part of the default local setup:
+
+- repository registration with stable `repoId` and `checkoutId` identities;
+- bounded repository inspection and context collection;
+- five preferred ChatGPT facade tools: `rh_status`, `rh_access`, `rh_inbox`, `rh_context`, and `rh_work`, plus a stable repair-capable default MCP schema;
+- Direct Edit sessions with path limits, SHA preconditions, revisions, savepoints, diffs, checks, and rollback;
+- durable Issue → Task → Run state and resumable evidence;
+- named verification checks instead of arbitrary remote shell access;
+- local Controller UI and append-only activity/evidence records;
+- runtime storage isolation under Controller Home;
+- multi-repository routing and explicit target selection;
+- release gates, tracked-file hygiene, and public export checks.
+
+## Optional features
+
+| Integration | What it adds | Requirement |
+| --- | --- | --- |
+| Codex / Claude | Delegated implementation for work too large for Direct Edit | Install and authenticate the corresponding CLI; explicitly enable the dev runner. |
+| GitHub | Issue/Project synchronization, PR workflows, cloud-agent sessions | Authenticated `gh` and repository permission. |
+| Tailscale / Cloudflare | Stable HTTPS endpoint for ChatGPT MCP | Tunnel client and appropriate account/domain configuration. |
+| Browser | Playwright navigation, screenshots, and bounded browser evidence | Browser binaries and allowed domains. |
+| CodeGraph | Additional code relationships and impact navigation | CodeGraph CLI; native Windows automatic setup is not yet enabled. |
+| Google Workspace | Gmail and Calendar assistant actions | Explicit OAuth setup and plugin permission. |
+| Schedules and findings | Supervised recurring checks and candidate findings | Canonical Forge Runtime running; live actions remain policy-gated. |
+
+## 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.
+
+## Execution choices
+
+- Use Direct Edit for small or well-bounded changes.
+- Use durable Tasks when work must survive sessions, has dependencies, or needs formal review evidence.
+- Delegate to an Agent only when investigation or implementation breadth justifies it.
+- Use named checks to verify results before acceptance.
+
+## Authorization boundaries
+
+Reading and local bounded checks can be automatic. Repository mutations, destructive cleanup, external side effects, remote Git operations, GitHub changes, email actions, and publication remain explicitly policy-gated. Connecting ChatGPT does not grant unrestricted shell or filesystem access.

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

@@ -0,0 +1,45 @@
+# 功能与配置层级
+
+Forge 不依赖编码 Agent 或外部插件也能使用。先完成核心工作流，再按实际任务启用集成能力。
+
+## 核心功能
+
+默认本地配置包含：
+
+- 用稳定 `repoId`、`checkoutId` 注册和选择仓库；
+- 有边界的仓库读取与上下文聚合；
+- 五个首选 ChatGPT facade：`rh_status`、`rh_access`、`rh_inbox`、`rh_context`、`rh_work`，以及固定、可修复的默认 MCP 工具面；
+- Direct Edit：路径限制、SHA 前置条件、多 revision、savepoint、diff、检查和回滚；
+- 可恢复的 Issue → Task → Run 状态与执行证据；
+- 命名检查，而不是向远端开放任意 shell；
+- 本地 Controller UI 和追加式活动/证据记录；
+- Controller Home 运行态隔离；
+- 多仓库显式路由；
+- 发布门禁、tracked-file 卫生检查和公共导出。
+
+## 可选能力
+
+| 集成 | 增加的能力 | 需要的环境 |
+| --- | --- | --- |
+| Codex / Claude | 处理超出 Direct Edit 范围的复杂实现 | 安装并登录对应 CLI，显式开启 dev runner。 |
+| GitHub | Issue/Project 同步、PR、云端 Agent | 已认证的 `gh` 和仓库权限。 |
+| Tailscale / Cloudflare | 为 ChatGPT MCP 提供稳定 HTTPS 地址 | 隧道客户端及对应账号/域名。 |
+| Browser | Playwright 浏览、截图和证据 | 浏览器 binary 与允许访问的域名。 |
+| CodeGraph | 代码关系和影响范围导航 | CodeGraph CLI；Windows 原生暂不自动配置。 |
+| Google Workspace | Gmail、Calendar 助手能力 | 显式 OAuth 与插件权限。 |
+| Schedule / Finding | 受监督的周期检查和候选发现 | Canonical Forge Runtime 持续运行，真实动作仍受策略控制。 |
+
+## 工具暴露
+
+默认 `advanced` 暴露固定、可修复且不超过 128 个工具的 schema；`core` 是同一 schema 的兼容别名。`full` 会暴露全部历史定义，只用于旧集成或深度兼容诊断。五个工作流 facade 位于强类型原子工具和内部 handler 之上，capability 元数据按领域对现有能力分组。当前 MCP transport 尚不支持会话内动态加载领域 schema，因此分组不会删除或隐藏这些强类型工具。
+
+## 如何选择执行方式
+
+- 小而明确的修改优先 Direct Edit。
+- 需要跨会话、存在依赖或需要正式证据时使用持久 Task。
+- 只有调查或实现范围确实较大时才委派 Agent。
+- 接受结果前运行命名检查并审查 diff。
+
+## 授权边界
+
+读取和本地有界检查可以自动执行；仓库写入、破坏性清理、外部副作用、远程 Git、GitHub 变更、邮件动作和发布仍需策略授权。连接 ChatGPT 不代表获得任意 shell 或任意文件系统权限。

package/docs/operations/github-repository.md

@@ -0,0 +1,60 @@
+# GitHub Repository Maintenance Baseline
+
+This document records the intended public GitHub configuration for Forge. The repository should remain useful from the README alone, while detailed behavior stays versioned under `docs/`.
+
+## Repository metadata
+
+- **Description:** `Local-first action assistant for durable, reviewable software work.`
+- **Homepage:** `https://github.com/moretea-labs/forge/wiki`
+- **Topics:** `ai-agents`, `ai-assistant`, `chatgpt`, `mcp`, `local-first`, `developer-tools`, `automation`, `agentic-workflow`, `typescript`
+- **Features:** Issues, Discussions, Wiki, security policy, and Private Vulnerability Reporting enabled.
+- **License:** MIT, with `NOTICE` and third-party notices preserved.
+
+The README should keep a clear product statement, release/CI/license badges, npm-first Quick Start, architecture entry point, official-provider table, safety boundary, and direct links to docs/support/contributing.
+
+## Main branch protection
+
+`main` keeps linear history, blocks force-pushes and deletion, and requires the always-running `Main gate` check to pass. The Windows smoke workflow remains path-scoped: it runs when Windows/portable-runtime surfaces change and is additional evidence rather than a globally required check that would stay absent on documentation-only changes.
+
+Forge also uses maintainer automation that can legitimately integrate reviewed local work directly. Do not add a blanket mandatory human-review rule that disables that workflow without first migrating the automation to pull requests. External contributors should use pull requests; maintainer direct integration remains subject to required checks and release gates.
+
+## Release protection
+
+- Protect `v*` release tags from accidental mutation/deletion where the repository ruleset supports it.
+- Use the GitHub `npm-publish` environment for npm publication.
+- Use npm Trusted Publishing/OIDC from `.github/workflows/release.yml`; do not store a long-lived npm token when OIDC is available.
+- Package version, exact Git tag, npm dist-tag, and GitHub Release must agree.
+- Release candidates publish to npm `next`; stable releases publish to `latest`.
+- A release is not complete until npm registry state and the GitHub Release are both verified after the tag workflow finishes.
+
+## Community surface
+
+Keep these files current:
+
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+- `SUPPORT.md`
+- `CODE_OF_CONDUCT.md`
+- issue forms and pull-request template
+- `.github/release.yml` release-note categories
+
+Use Issues for reproducible defects and scoped feature requests. Use Discussions for open-ended usage questions. Security vulnerabilities belong in Private Vulnerability Reporting, never in a public issue.
+
+## Documentation ownership
+
+The GitHub Wiki is a presentation target. Versioned source lives under `docs/wiki/`. Deeper engineering detail remains under `docs/architecture/current/` and `docs/operations/`.
+
+Public documentation must distinguish current facts from historical evidence. Avoid hard-coding “next release” versions in operational runbooks; derive versions from `package.json` so routine releases do not leave stale docs behind.
+
+## Maintenance cadence
+
+For every release candidate:
+
+1. review the README and installation claims;
+2. run public-doc, open-source, package, and release-surface gates;
+3. check repository metadata, topics, security reporting, Issues/Discussions, and release notes;
+4. verify official provider pins and fresh-install behavior when the catalog changed;
+5. push the exact release revision and wait for required checks;
+6. publish the exact version tag;
+7. verify GitHub Release and npm dist-tags independently;
+8. keep the release notes concise, user-facing, and linked to upgrade/support documentation.

package/docs/operations/gmail-assistant-routines.md

@@ -0,0 +1,186 @@
+# Durable Gmail Assistant Routines
+
+Gmail Assistant Routines use the existing Repository Schedule Engine and durable Execution Jobs. They do not introduce a second cron service.
+
+## Execution flow
+
+1. Creating a confirmed Assistant Routine persists the Routine and creates one Repository Schedule.
+2. The Schedule stores an IANA timezone, a five-field local cron expression, and a bounded catch-up window.
+3. A due occurrence creates one `assistant_routine_execute` Runtime Job with an exclusive Routine resource claim.
+4. The Runtime Job reads Gmail incrementally, hydrates bounded message bodies, advances the per-Routine cursor, analyzes the bounded message set, creates structured action proposals, and writes a final Assistant Inbox report.
+5. Proposals either remain pending for explicit approval or match a previously authorized Standing Grant.
+6. Every approved or Standing-Grant action runs as a separate durable plugin Job. Schedule execution never becomes remote-write authorization.
+7. Sending mail and moving mail to Trash retain their existing strong-confirmation requirements and are never Standing-Grant eligible.
+
+## Google OAuth setup
+
+Create a Google OAuth client with this loopback redirect URI:
+
+```text
+http://127.0.0.1:8766/oauth/google/callback
+```
+
+Expose the client configuration only through the managed secret environment:
+
+- `FORGE_GOOGLE_CLIENT_ID`
+- `FORGE_GOOGLE_CLIENT_SECRET`
+
+The `FORGE_GOOGLE_WORKSPACE_CLIENT_ID` and `FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET` aliases are also supported.
+
+Call `workspace_auth_login_prepare` for `gmail` or `google-workspace`, then open the returned authorization URL. The request uses OAuth Authorization Code flow with PKCE, a random one-time state, a ten-minute expiry, and a loopback-only callback. Redirect URIs outside `127.0.0.1` or `localhost`, unexpected callback paths, and scopes outside the Gmail/Calendar/Tasks allowlist are rejected.
+
+The callback exchanges the authorization code and stores only the refresh token in macOS Keychain. Access and refresh tokens are never returned through MCP, written to repository files, or written to normal Controller runtime state. The transient PKCE verifier is stored under Controller Home with restrictive permissions and is redacted after the callback is consumed.
+
+The current secure persistence backend is macOS Keychain. Non-macOS hosts must provide a supported credential-store adapter or use managed environment credentials.
+
+## Credential refresh and readiness
+
+A configured access token is not considered provider-verified until a real Google API request succeeds. Before that first successful probe, health reports `live_token_unverified`.
+
+After OAuth setup, Controller restarts can reload the refresh token from Keychain. When no valid cached access token exists, or Gmail returns HTTP 401/403, the provider performs one refresh-token exchange and at most one request retry. A failed refresh is classified as `PLUGIN_AUTH_FAILED`; the Routine Run becomes `auth_required` and Assistant Inbox requests reauthorization.
+
+Managed environment credentials remain compatible:
+
+- `FORGE_GMAIL_ACCESS_TOKEN`
+- `FORGE_GMAIL_REFRESH_TOKEN`
+- `FORGE_GMAIL_CLIENT_ID`
+- `FORGE_GMAIL_CLIENT_SECRET`
+- `FORGE_GOOGLE_WORKSPACE_ACCESS_TOKEN`
+- `FORGE_GOOGLE_WORKSPACE_REFRESH_TOKEN`
+- `FORGE_GOOGLE_WORKSPACE_CLIENT_ID`
+- `FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET`
+
+## Scheduling semantics
+
+Routine schedule text is normalized when the Routine is created. The first implementation recognizes daily and weekday expressions with an optional `HH:mm` or Chinese `点/时` form. Examples:
+
+- `每天 09:00`
+- `每周一 08:30`
+- `Monday 07:00`
+
+The normalized Schedule preserves the IANA timezone, so daylight-saving transitions remain aligned to local wall-clock time. Missed runs catch up at most once inside the configured window because the occurrence key is derived from the local scheduled minute rather than the actual wake-up minute.
+
+## Gmail History cursor
+
+Each Routine stores an independent cursor under `.forge/assistant/gmail-cursors.json`:
+
+- last successful collection time
+- bounded processed-message ID set
+- Gmail `historyId`
+- a bounded History or query continuation token while a backlog is still being drained
+
+After the initial query, Gmail History is the primary incremental source. An expired History ID falls back to a five-minute-overlap Gmail query. Collection reads at most five pages, 100 IDs, and 50 full messages per run. If the page or hydration limit is reached, the history cursor does not advance; a continuation token or the original window is retained so the next run drains the remaining messages without loss.
+
+## Optional model analysis
+
+The model layer is optional. When it is disabled, unavailable, times out, or returns malformed output, the Routine completes with the deterministic rules engine rather than failing.
+
+Configure an OpenAI-compatible endpoint with:
+
+- `FORGE_ASSISTANT_MODEL_PROVIDER=openai-compatible`
+- `FORGE_ASSISTANT_MODEL_ENDPOINT`
+- `FORGE_ASSISTANT_MODEL`
+- `FORGE_ASSISTANT_MODEL_API_KEY`
+
+For the exact official hosts, provider-specific keys are also supported:
+
+- `api.openai.com` may use `OPENAI_API_KEY`
+- `api.deepseek.com` may use `FORGE_DEEPSEEK_API_KEY` or `DEEPSEEK_API_KEY`
+
+A custom endpoint never receives `OPENAI_API_KEY` or a DeepSeek key. It must use the dedicated `FORGE_ASSISTANT_MODEL_API_KEY`. Endpoints must use HTTPS, except loopback HTTP used for a local model.
+
+Optional budgets:
+
+- `FORGE_ASSISTANT_MODEL_TIMEOUT_MS`
+- `FORGE_ASSISTANT_MODEL_MAX_MESSAGES`
+- `FORGE_ASSISTANT_MODEL_MAX_INPUT_CHARS`
+- `FORGE_ASSISTANT_MODEL_MAX_OUTPUT_TOKENS`
+
+The provider requests strict structured JSON, validates the result locally, and maps only these proposal types:
+
+- Gmail draft creation
+- Google Task creation
+- Gmail archive
+- Gmail mark read or unread
+
+Email contents are untrusted input. Instructions in an email, quoted thread, signature, link, or attachment description cannot expand the action allowlist or request tools, credentials, files, commands, or additional permissions. Security, authentication, billing, incident, production, quota, and repository-permission messages are protected from model-generated archive actions.
+
+The deterministic fallback also uses Gmail's `CATEGORY_PROMOTIONS` label as a high-confidence archive signal (`0.98`) for non-protected messages. Marketing/newsletter keyword matches remain a lower-confidence fallback (`0.7`). The protected-message veto wins over both signals, so a security, authentication, billing, production, incident, quota, or permission-related message is never proposed for automatic archive merely because Gmail classified it as Promotions.
+
+Use `assistant_model_readiness` or `GET /api/assistant/model` to inspect the redacted configuration and budgets. Model credentials and raw secrets are never returned.
+
+## Action proposals and approval
+
+Routine analysis persists structured proposals under `.forge/assistant/action-proposals.json`. Each proposal records:
+
+- Routine and Run identity
+- target plugin/action and bounded arguments
+- supporting Gmail message IDs
+- sender/subject context and protected-message status
+- reason, confidence, risk, expiry, and execution status
+- the separate Execution Job created after approval
+
+Use `assistant_action_proposals` to list or inspect proposals. Use `assistant_action_proposal_resolve` with `decision=approve` or `decision=reject`. MCP approval requires `confirm_authorization=true`; strong-confirmation actions also require the action's exact confirmation text. Local Controller exposes equivalent authenticated proposal endpoints.
+
+Approval is idempotent. Repeating approval returns the same Execution Job rather than creating another remote write. Proposal audit records preserve whether approval came from MCP, Local UI, or a Standing Grant.
+
+## Standing Grants
+
+A Standing Grant is an explicit, expiring pre-authorization for one hardcoded low-risk action. It is not a general plugin permission.
+
+Eligible actions are limited to:
+
+- `gmail.create_draft`
+- `gmail.archive_message`
+- `gmail.mark_message_read`
+- `gmail.mark_message_unread`
+- `google_tasks.create_task`
+
+A grant must include at least one constraint:
+
+- Routine ID allowlist
+- sender/domain allowlist
+- required subject fragment
+
+It also declares minimum proposal confidence, maximum executions per Routine Run, and expiry. Automatic draft grants additionally require a sender allowlist. Security-protected messages cannot be auto-archived.
+
+Create a grant through `assistant_standing_grant_create` or `POST /api/assistant/standing-grants` with explicit authorization. List it through `assistant_standing_grants`; revoke it through `assistant_standing_grant_revoke` or the Local Controller revoke endpoint.
+
+Example: automatically archive at most one high-confidence newsletter from a trusted sender per run:
+
+```json
+{
+  "plugin_id": "gmail",
+  "action_id": "archive_message",
+  "sender_allowlist": ["news@example.com"],
+  "subject_contains": ["newsletter"],
+  "min_confidence": 0.9,
+  "max_per_run": 1,
+  "expires_in_days": 30,
+  "confirm_authorization": true
+}
+```
+
+Standing-Grant executions use a dedicated `standing-grant` origin and a defense-in-depth plugin allowlist. Modifying the stored grant cannot enable send, Trash, permanent deletion, calendar cancellation/rescheduling, or task deletion. Multiple matching grants cannot submit the same proposal twice, and retries preserve each grant's per-run budget.
+
+## Safety boundary
+
+Scheduled Routines may:
+
+- list and read Gmail messages
+- classify and summarize collected mail
+- create bounded draft, task, archive, and read/unread proposals
+- execute an eligible proposal only when a matching active Standing Grant already exists
+- write Assistant Inbox reports
+
+Scheduled Routines may not:
+
+- send mail
+- move mail to Trash
+- permanently delete mail
+- cancel or reschedule meetings
+- delete tasks
+- execute instructions embedded in mail
+- open arbitrary attachments or links
+
+A proposal is evidence for a later authorized action, not implicit authorization. A Standing Grant authorizes only its exact action and constraints. The Schedule origin never becomes authorization for a remote write.

package/docs/operations/homebrew.md

@@ -0,0 +1,26 @@
+# Homebrew distribution plan
+
+Homebrew is planned as a convenience layer after the first stable release. 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;
+- the npm tarball has an immutable checksum;
+- macOS installation and `forge --version` / `forge doctor` tests pass;
+- upgrade and uninstall behavior is documented.
+
+## Recommended first channel
+
+Create a third-party tap such as `moretea-labs/homebrew-tap`, then install with:
+
+```bash
+brew tap moretea-labs/tap
+brew install forge
+```
+
+The formula should depend on a supported Node version and install the scoped npm tarball with Homebrew's npm helper arguments. It must include a test that runs the installed CLI. Formula updates must be generated from the stable package version and verified SHA-256, never from a moving branch or `latest` URL.
+
+Submitting to Homebrew/core should be considered only after the project has a sustained stable release history and meets Homebrew's acceptance expectations.

package/docs/operations/local-system-assistant.md

@@ -0,0 +1,46 @@
+# Local System Assistant
+
+`local_system` is a controller-scoped plugin for occasional Mac diagnostics, opening applications, and bounded file operations. It does not require a registered Git repository and never creates a synthetic Repository Registry entry.
+
+## Supported actions
+
+- Read bounded CPU, process, memory, and memory-pressure snapshots.
+- Inspect one process by PID.
+- Open a macOS application by name or bundle ID.
+- Reveal an authorized file in Finder or open it with the default application.
+- List directories, read text, create directories, copy, move, and rename files below authorized roots.
+
+## Safety boundaries
+
+- No arbitrary shell, `sudo`, file deletion, or Accessibility-based clicking.
+- A directory must first be authorized with `authorize_target` and an expiring `target_key`; grants are capped at 24 hours.
+- File paths are relative to the authorized root.
+- Lexical traversal and symlink escape are both rejected.
+- Copy, move, and rename never overwrite existing destinations.
+- Diagnostics, directory listings, and text reads need no confirmation. Target authorization, opening applications, and file writes use normal authorization.
+
+## Using it from ChatGPT
+
+No `repo_id` is required:
+
+```text
+List the local_system plugin capabilities.
+Show current CPU and memory pressure.
+Open Xcode.
+Authorize ~/Documents/Reports as reports for 60 minutes.
+Read summary.txt from reports.
+```
+
+ChatGPT uses the existing `list_plugins`, `get_plugin`, and `plugin_action_execute` tools. No new MCP tool or reconnect is required.
+
+Plugin state, jobs, target grants, and evidence live under `controllerHome/system/`, outside the Repository Registry.
+
+## iOS automation notes
+
+The iOS smoke review now waits for Simulator readiness, uses build-specific DerivedData, selects the application product deterministically, waits after launch, and records simulator ownership. Supported cleanup policies are:
+
+- `keep`
+- `shutdown_on_success`
+- `shutdown_always`
+
+Only a simulator started by the current work is eligible for automatic shutdown. Screenshots and logs produce readable Artifact references.

package/docs/operations/local-system-assistant.zh-CN.md

@@ -0,0 +1,46 @@
+# 本机系统助手
+
+`local_system` 是 Controller 级插件，用于偶尔处理本机诊断、打开应用和受控文件操作。它不要求注册 Git 仓库，也不会创建假的仓库记录。
+
+## 可以做什么
+
+- 查看有边界的 CPU、进程、内存与内存压力快照。
+- 查看指定 PID 的进程信息。
+- 按应用名称或 Bundle ID 打开 macOS 应用。
+- 在 Finder 中显示已授权文件，或用默认应用打开文件。
+- 在已授权目录中列目录、读取文本、新建目录、复制、移动和重命名文件。
+
+## 安全边界
+
+- 没有任意 shell、`sudo`、删除文件或辅助功能点击能力。
+- 目录必须先通过 `authorize_target` 授权，并使用有期限的 `target_key`；最长有效期 24 小时。
+- 所有文件路径必须是目标目录下的相对路径。
+- 系统同时检查路径穿越和符号链接逃逸。
+- 复制、移动和重命名默认拒绝覆盖已有文件。
+- 诊断、列目录和读取文本不需要确认；授权目录、打开应用和文件写操作需要正常授权。
+
+## 在 ChatGPT 中使用
+
+无需传入 `repo_id`：
+
+```text
+列出 local_system 插件能力。
+查看当前 CPU 和内存压力。
+打开 Xcode。
+授权 ~/Documents/Reports 为 reports，使用 60 分钟。
+读取 reports 下的 summary.txt。
+```
+
+ChatGPT 会通过现有 `list_plugins`、`get_plugin` 和 `plugin_action_execute` 工具调用插件，因此不需要重新连接或增加新的 MCP 工具。
+
+插件状态、任务、授权目标和证据存放在 `controllerHome/system/`，不会写入 Repository Registry。
+
+## iOS 自动化说明
+
+iOS smoke review 现在会等待 Simulator 完全启动，使用每次构建独立的 DerivedData，确定性选择 App 产物，在启动后等待页面稳定，并记录模拟器是否由本次任务启动。可以使用：
+
+- `cleanup_policy=keep`
+- `cleanup_policy=shutdown_on_success`
+- `cleanup_policy=shutdown_always`
+
+系统只会自动关闭由当前任务启动的模拟器，不会关闭原本已经运行的设备。截图和日志会生成可读取的 Artifact 引用。