@ckanner/flywheel 0.27.3 → 0.28.0

package/docs/en/getting-started.md

@@ -0,0 +1,244 @@
+# Install and run your first Flywheel task
+
+[English README](../../README.en.md) · [中文](../getting-started.md) · [Workflow](workflow.md) · [Configuration](configuration.md)
+
+This guide covers the **0.28.0 implementation**: npm installation, the DSH desktop and workers, configuration, preflight, a small task, and recovery. The checked desktop interface baseline is **DSH Mac 0.2.1-rc.5**. Real desktop UI, macOS permissions, authentication, and model inference still need testing on the intended machine.
+
+Before installing, check `npm view @ckanner/flywheel version`. Continue with these instructions once the registry has the version you intend to use. A merged source change or GitHub Release does not establish npm publication, and an older installed release may not include these interfaces.
+
+## 1. Prepare the environment
+
+| Requirement | Why it is needed |
+|---|---|
+| Git with your commit identity | Worktrees and local delivery commits |
+| Node.js 22.18.0 or later and npm | Installer, launchers, and JavaScript workers |
+| DSH Mac and its desktop-supplied `dsh` command | Desktop plugin management and DSH SDK execution |
+| Authenticated Kimi CLI | Default Plan, frontend execution, and optional Garden |
+| Codex executable and existing login | The hard route's Codex Pro plugin runs Codex app-server |
+| DeepSeek and ChatGPT providers in the DSH SDK profile | Default execution, independent Review, and Judge |
+| Go 1.27 or later | Only the Go example below and source builds; not npm binary installation |
+
+Check command locations and versions with `git --version`, `node --version`, `npm --version`, `command -v dsh`, `dsh --version`, `kimi --version`, and `codex --version`. Check the desktop version in About as well. Use the respective tools' documented installation and login flows.
+
+Kimi subscription, ChatGPT subscription, and DeepSeek API access are separate channels. Flywheel does not log in, copy credentials, or replace the desktop application. A task using only the default execution route can skip the hard route at runtime, but it still needs its configured Plan, Execute, Review, and Judge backends.
+
+## 2. Install
+
+From a terminal that can find the desktop's `dsh` command:
+
+```sh
+npx -y @ckanner/flywheel@latest install
+```
+
+For an agent consuming a single JSON result, use the same command with `--json`. The installer installs its exact version globally, resolves the platform binary and workers, installs the ten bundled skills, creates global configuration only if absent, records a GUI launcher, registers the matching DSH plugin, and runs local diagnostics.
+
+`ok:true` means the installation steps completed. `ready:true` means that local doctor found no blocker. For example, missing Kimi can produce `ok:true, ready:false` with the reason in `diagnostic.checks`. Neither result proves real authentication or inference. A failed step retains its partial results so the actual cause can be corrected before retrying.
+
+### Useful options
+
+| Option | Effect |
+|---|---|
+| `--prefix PATH` | Choose the npm global prefix |
+| `--project PATH` | Install skills into an existing project's `.agents/skills` and diagnose that project; CLI installation remains global |
+| `--dsh-bin PATH` | Use the verified desktop DSH command at an explicit path |
+| `--profile NAME` | Desktop plugin target profile, default `desktop`; unrelated to the worker's SDK profile |
+| `--no-dsh` | Skip desktop plugin registration |
+| `--no-global` | Set up the current persistent installation without another global install |
+| `--timeout-ms N` | External install-step timeout; default 600000 ms, range 100–1800000 |
+| `--json` | Emit one structured installation result |
+
+For a user-owned global prefix:
+
+```sh
+npx -y @ckanner/flywheel@latest install --prefix "$HOME/.local"
+export PATH="$HOME/.local/bin:$PATH"
+flywheel version
+```
+
+Add the actual prefix's `bin` directory to your shell configuration for later terminals. Supply `--dsh-bin /absolute/path/to/dsh` if necessary. Do not guess an executable path inside a macOS app bundle.
+
+Plain `npm install --global @ckanner/flywheel` only places package files. Complete user setup explicitly afterward:
+
+```sh
+flywheel setup --no-global
+```
+
+`install` and `setup` share options. Do not use `--no-global` to turn a temporary npx cache into the permanent GUI entry.
+
+## 3. Distinguish desktop and SDK setup
+
+The installer uses the official desktop plugin interface with exact version selection:
+
+```text
+dsh plugin --profile desktop add --save-exact --ignore-scripts @ckanner/dsh-plugin-flywheel@<installed-version>
+```
+
+This is the command shape used internally, not a placeholder to paste literally. An independent npm DSH CLI cannot manage the reserved `desktop` profile. Reload according to the host's instructions; the Flywheel button appears in the desktop input area.
+
+The worker defaults to a separate **`sdk` profile**. A desktop provider installation or login does not prove that the SDK profile has the same configuration or authorization. DeepSeek uses `deepseek-official`; native GPT routing uses the ChatGPT adapter. The checked adapter baseline can be installed with:
+
+```sh
+dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
+```
+
+That is a checked compatibility version, not a claim about the latest adapter. Follow its authorization documentation for the chosen profile and keep `DSH_HOME` consistent. Do not copy tokens into task files or Git.
+
+The hard route uses the installed `dsh-subagent-codex-pro@0.8.0` dependency's public machine API directly. It does not use `subagent_codex_pro` as a native LLM provider or require a parent model to delegate. Its underlying Codex app-server still needs the local Codex command and login.
+
+### Desktop launcher
+
+Setup creates `~/.config/flywheel/npm-launcher` and an installation record with absolute Node/CLI paths, the checked DSH entry, and the installation-time tool PATH. The desktop plugin verifies the managed launcher before using it. A user-specified `flywheelBinary` takes precedence. Missing records can use the legacy PATH lookup; damaged records or modified managed launchers fail visibly.
+
+After moving Node or the npm prefix, or installing previously missing tools, run `flywheel setup --no-global` in a terminal where all required tools are available, preserving your original options. Save custom launcher changes before resolving a conflict. A shell export alone does not update an already running desktop process; recheck from the panel.
+
+## 4. Select configuration and skills
+
+Configuration precedence is task directory, project root, global file, then embedded defaults. The first complete file wins; files do not merge. Existing configuration is preserved during upgrades. Inspect the actual source:
+
+```sh
+flywheel config inspect --cwd /absolute/path/to/repo --json
+flywheel template flywheel.config.example.json
+flywheel template flywheel.profiles.example.json
+```
+
+Use either complete template as a starting point and review it before writing a configuration file. The [configuration guide](configuration.md) covers safe export, fields, profile overrides, channel identity, and migration to `codex-pro`. `loops.plan` controls engine planning; the host's selected conversation model controls initial `flywheel-new` preparation.
+
+The installer includes ten skills. Skills are optional host entry points; the desktop panel and CLI also work independently. To inspect or install them for an existing project:
+
+```sh
+flywheel skills list
+flywheel skills read flywheel-run
+flywheel install-skills --project /absolute/path/to/repo --json
+```
+
+Follow the host's skill-discovery rules. Copying files does not prove the host loaded them. Installer-owned unchanged snapshots can update; modified files, unowned directories, and invalid manifests are preserved and reported as conflicts.
+
+## 5. Run preflight without inference
+
+From the target repository:
+
+```sh
+flywheel doctor --cwd "$PWD" --json
+flywheel doctor --cwd "$PWD" --probe --json
+```
+
+Local checks cover configuration, directories, command availability/version, and declared environment variables. `--probe` also initializes DSH SDK sessions, checks accepted configuration, working directory, permissions, and shutdown. It sends no inference prompt and runs no acceptance command. Provider initialization may query a model catalog and create SDK-owned cache/session files.
+
+Codex Pro additionally verifies that the exact public machine API can be imported and that Node/Codex commands are available. It does not run a model task, prove account entitlement, or pre-check the complete policy. Its full-policy limitation remains a warning; model/effort/authorization remain unknown.
+
+Results use `pass`, `fail`, `warn`, `unknown`, and `skipped`. A fail produces exit code 1. A successful aggregate result only covers the checks performed. No preflight creates Flywheel state, worktrees, or global configuration. Check again in the desktop panel because GUI environment and profile selection may differ.
+
+After contracts exist, narrow the checks to the selected task:
+
+```sh
+flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --probe --json
+```
+
+A task without packets can be inspected during preparation, but a real start still needs at least one reviewed legal packet. Fix schema, directory, provider, or permission failures at their source.
+
+## 6. Prepare a task
+
+### Existing repository
+
+Create or deliberately reuse a task integration branch and independent worktree **before** running `flywheel-new`. Prepare contracts and launch the engine from that same root, using a task path inside it. The [workflow guide](workflow.md) gives the branch commands, model recommendations, draft-PR timing, and exact working directory for each loop.
+
+Use the bundled templates to prepare a real Spec and packets with actual acceptance commands, protected oracles, and recorded dry-run results. Commit the reviewed contracts before starting so packet worktrees can read them from Git. Do not create `state.json` manually.
+
+### Disposable first-run example
+
+For a first installation check, the packaged scaffold creates a separate Go addition task. The initial implementation is intentionally wrong; the executor must fix it and add ordinary tests without changing the frozen acceptance test. This example needs Go 1.27 or later and an unused destination directory.
+
+```sh
+FLYWHEEL_PACKAGE="$(npm root --global)/@ckanner/flywheel"
+bash "$FLYWHEEL_PACKAGE/docs/examples/create-first-task.sh" "$HOME/flywheel-demo"
+cd "$HOME/flywheel-demo"
+git init -b main
+```
+
+For a custom prefix, resolve the package with `npm root --global --prefix "$HOME/.local"` instead. If the CLI is not on PATH, set `FLYWHEEL_BIN` to its absolute path when invoking the script. The scaffold writes files and reads installed templates; it does not invoke models or commit anything.
+
+The scaffold includes `sum.go`, frozen `acceptance/sum_test.go`, `docs/add/spec.md`, a packet, a complete project configuration, and ignore rules for generated/volatile files. Run every L1 command from the packet. For the shipped example:
+
+```sh
+go test ./...
+go test -coverprofile=coverage.out . &&
+  go tool cover -func=coverage.out |
+  awk '$NF != "100.0%" && $NF != "100%" { bad=1 } END { exit bad }'
+```
+
+The initial failures are expected. Record the actual exit codes and summaries in the Spec's dry-run evidence. Review the contracts and frozen boundaries, then commit the scaffold in this new demonstration repository:
+
+```sh
+git add go.mod sum.go acceptance .gitignore flywheel.config.json docs/add
+git diff --cached
+git commit -m "docs: prepare first flywheel task"
+git worktree add -b task/add ../flywheel-demo-add
+cd ../flywheel-demo-add
+```
+
+This disposable scaffold generates contracts before the task worktree is created; for an existing repository, use the preparation order in the preceding section. The real run below uses the new task worktree and its own `docs/add`, so local packet delivery stays on `task/add`.
+
+## 7. Start, observe, stop, and recover
+
+The following commands invoke the real configured backends. Run them from the demo task worktree, or substitute your actual task name:
+
+```sh
+flywheel config inspect --cwd "$PWD" --task-dir "$PWD/docs/add" --json
+flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/add" --probe --json
+flywheel control start --cwd "$PWD" --task-dir "$PWD/docs/add"
+flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/add"
+```
+
+The desktop panel accepts the same two absolute paths. A control response's `ok` means the operation succeeded; task completion is determined by `state.status`. After a startup readiness timeout, query status and read logs before attempting another start.
+
+For a foreground run that pauses before Review, use this instead of background start:
+
+```sh
+flywheel run docs/add --pause-before review
+```
+
+`control start` does not accept `--pause-before`, and pause mode cannot be combined with `--only`. `--only execute` runs the bounded execution/L1 loop; it is not a single model call. `--only review` returns a review result without continuing into Plan or local merge. `--only verify` runs deterministic acceptance without Review/Judge or worktree creation.
+
+Inspect progress:
+
+```sh
+flywheel status docs/add
+tail -n 80 docs/add/orchestrator.log
+git log -5 --oneline
+```
+
+Stop with:
+
+```sh
+flywheel control stop --cwd "$PWD" --task-dir "$PWD/docs/add"
+```
+
+Only resume with `control start` after confirming the previous run ended and addressing its actual error. Retain the original task/worktree paths, reports, and state. A stop result concerns engine lifetime; recorded cleanup uncertainty still needs investigation, especially for Codex Pro's separately managed processes. See [recovery](workflow.md#7-stop-and-recover-without-losing-evidence).
+
+For the first real run, record whether the task reached `completed`, all requirements were covered, frozen acceptance remained unchanged, independent review and reports exist, and the implementation was delivered in local Git. Record actual model identity, latency, and usage separately from preflight. No check in this guide claims those results on your behalf.
+
+## 8. Upgrade and troubleshoot
+
+Stop active tasks and confirm their state, preserve configuration/customizations, then rerun the installation command with the original prefix/project/DSH options. To pin 0.28.0, first confirm that exact version exists in the registry and replace `@latest` with `@0.28.0`. `flywheel setup --no-global` repairs setup for the installed version without selecting a different CLI release.
+
+Existing hard-route configuration remains unchanged after upgrade. To adopt the new plugin route, change the effective hard binding or profile to `harness: "codex-pro"`, preserve model/channel/thinking, inspect it, and restart. Do not use `subagent_codex_pro` as a provider.
+
+| Symptom | First check |
+|---|---|
+| Missing `install` or `control` command | Published version, `flywheel version`, PATH, and any explicit desktop `flywheelBinary` |
+| Install succeeds but `ready:false` | Resolve the specific `diagnostic.checks` blockers |
+| Terminal works but the desktop does not | Managed launcher, explicit override, GUI PATH/profile/environment; rerun setup and check the panel |
+| A configuration edit has no effect | `config inspect` source and higher-priority task/project files; restart the engine |
+| Skill or launcher conflict | Preserve customizations, compare the specific files, and resolve the reported conflict without altering ownership hashes |
+| Worktree creation falls back in-place | Stop if isolation is required; inspect persisted mode and preserve work before recovery |
+| Cleanup is unconfirmed | Inspect task-owned processes and receipts before retrying; elapsed time alone is not proof |
+
+Installation is not one atomic transaction across npm, DSH, and all skills. Correct the reported cause and retry; preserve completed steps and user files. Do not delete whole configuration directories or modify integrity manifests to bypass conflicts.
+
+To uninstall, first stop running tasks, remove the desktop Flywheel plugin through the desktop's supported plugin-management interface, then uninstall the global CLI using the same prefix:
+
+```sh
+npm uninstall --global @ckanner/flywheel
+```
+
+Configuration, task ledgers, modified skills, and worktrees require deliberate separate handling; do not remove them as an incidental cleanup step. Maintainer build and publication procedures are in the [release guide](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md). Normal users do not need npm publishing credentials or GitHub OIDC to install Flywheel.

package/docs/en/workflow.md

@@ -0,0 +1,155 @@
+# From requirements to a merged PR
+
+[English README](../../README.en.md) · [中文](../workflow.md) · [Getting started](getting-started.md)
+
+This guide describes the **0.28.0 implementation** and a recommended operating workflow. It does not assert that a particular npm version has been published. Check the registry when installing. The engine's local delivery and the host's GitHub operations are separate responsibilities.
+
+## 1. Choose a model for preparation
+
+Preparation turns a requirement into a Spec, task packets, acceptance commands, boundaries, and recorded dry-run evidence. `flywheel-new` uses the model selected in the host's current conversation. It does not switch that model based on `loops.plan`; that binding controls planning and revisions after the Go engine starts.
+
+For accounts that expose the named models, these are practical starting points:
+
+| Requirement | Preparation model and effort | Reason for the recommendation |
+|---|---|---|
+| Ambiguous requirements, architecture, protocol, or process lifecycle changes | `chatgpt/gpt-6-astra`, `high` | Spend more reasoning on constraints, failure cases, and testable acceptance before execution |
+| A clear repository feature with known boundaries | `chatgpt/gpt-6.1-sol`, `high` | A practical default for making a concrete implementation plan |
+| A small, explicit fix or documentation update | `deepseek-official/deepseek-flash`, `high` | Keep preparation proportional to a narrow task |
+
+These are engineering recommendations, not benchmark results or evidence that one setting is universally best. Confirm the exact model ID and supported effort in the selected account and adapter. The checked DSH Flash adapter accepts `off/low/high/max`, not `medium`. A catalog entry or accepted configuration does not prove that real inference has succeeded.
+
+Use the preparation model to identify risks and improve the contract. Increasing effort cannot repair missing requirements, an invalid test oracle, or an incorrectly chosen working directory. Later execution routes and the independent Review/Judge stages remain explicit configuration; see [Configuration](configuration.md).
+
+## 2. Create the task integration worktree first
+
+For an existing repository, create or deliberately reuse a task branch in its own worktree before invoking `flywheel-new`. The host or user performs this step. Choose unused names and substitute the repository's actual base branch:
+
+```sh
+git status --short
+git fetch origin
+git worktree add -b task/my-feature ../repo-my-feature origin/main
+cd ../repo-my-feature
+git branch --show-current
+```
+
+Inspect the initial status before proceeding. These commands create a new task branch without moving the original checkout's `main`. Do not use forced branch replacement to resolve a naming collision. If a task branch/worktree already exists, inspect its state and reuse it deliberately.
+
+Keep the task at `docs/my-feature` **inside this worktree**. Run preparation and later CLI commands from this root; enter these same absolute paths in the desktop panel. Do not pair the original checkout's task directory with the new worktree's `cwd`, or change the task worktree's branch during a run.
+
+The engine's integration checkout is the supplied `cwd`, not a hardcoded `main` branch. Its packet branches normally use `flywheel/<slug>/<packet-id>` and start from that checkout's HEAD. Successful packet delivery fast-forwards into the branch currently checked out there. This is why choosing a task branch before starting matters.
+
+### Isolation has a fallback
+
+Worktrees isolate working directories and indexes; they are not security sandboxes. The engine normally creates a packet worktree, but a creation failure can record the reason and fall back to **in-place** execution. There is currently no switch that requires successful isolation in every case.
+
+If strict task isolation is required and the log reports `worktree unavailable`, stop and inspect the workspace and recorded mode. Correcting a directory and restarting does not automatically convert an already persisted in-place packet into a new worktree. Preserve its work and resolve the recorded situation explicitly; do not edit `state.json`, delete results, or force-reset a branch to hide it.
+
+## 3. Prepare and review the contracts
+
+In the task worktree, ask the host to run `flywheel-new`, or inspect the bundled templates and prepare the contract files manually:
+
+```sh
+flywheel template --list
+flywheel skills read flywheel-new
+```
+
+A runnable task needs a reviewed `spec.md` and at least one legal `task-packet-*.md`, using the bundled schemas. The preparation should establish:
+
+- Requirement IDs, expected behavior, and scope exclusions.
+- Packet dependencies, execution routes, editable paths, and forbidden paths.
+- Real L1 commands and milestone L2/L3 commands with expected exit codes.
+- Frozen acceptance tests or other oracles, separately protected from implementation tests.
+- Actual dry-run results, with failure output and exit codes where applicable.
+
+Run the stated commands before recording their results. An intentionally failing baseline can be valid evidence; a guessed passing result cannot. Ordinary implementation and regression tests can be added by the executor. Frozen acceptance and configuration must not be rewritten to make an implementation pass.
+
+Review the files, then commit the substantive initial contracts so packet worktrees can obtain them from Git. The following assumes the index has been checked for unrelated staged work:
+
+```sh
+git diff -- docs/my-feature
+git diff --cached --stat
+git add -- docs/my-feature
+git diff --cached
+git commit -m "docs: prepare my-feature contracts"
+```
+
+Stage any additional acceptance fixtures separately after review. Do not create `state.json`; the engine initializes and maintains it. An empty commit does not replace committing the actual contracts.
+
+## 4. Open a task-level Draft PR
+
+Once the reviewed contracts are committed, a Draft PR gives the task a durable review location. The user or authorized host runs the GitHub steps:
+
+```sh
+git push -u origin task/my-feature
+gh pr create --draft --base main --head task/my-feature
+```
+
+Describe the problem, expected outcome, acceptance criteria, and remaining work. Usually one independently deliverable requirement or milestone belongs in one PR. Packets are the engine's internal execution units; the engine does not automatically create a PR for each packet.
+
+Keep the PR in draft while implementation and acceptance are still changing. Opening it early does not imply that it should be merged early.
+
+## 5. Run from the same task worktree
+
+With the current directory still at the task worktree root:
+
+```sh
+flywheel config inspect --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --json
+flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --probe --json
+flywheel control start --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+```
+
+Preflight does not infer with a model or execute acceptance commands. Its unknown and warning results still need interpretation. Starting the real task invokes the configured models. A control response's `ok` describes the operation; final task completion is in `state.status`.
+
+### Working directory by stage
+
+| Stage or entry | Working directory | Responsibility |
+|---|---|---|
+| `flywheel-new` preparation | Task integration worktree | Host creates or reuses it according to the skill |
+| Plan | Task integration worktree | Engine uses the startup root to revise the task contracts |
+| Execute, L1, Review | Current packet candidate workspace, normally its packet worktree | Engine creates, records, and reuses that workspace |
+| L2/L3, Judge | Task integration worktree | Engine checks the integrated milestone |
+| Intake, Garden | Selected task's worktree | Host selects the root; Go writes proposals. DSH/Codex request read-only; default Kimi has no OS-level read-only guarantee |
+| Status, Stop | Original task directory and execution root | Query or stop the existing task without requiring a new worktree, branch switch, or commit |
+
+Every loop does not create its own worktree. The outer task worktree spans the deliverable; a packet workspace spans its execution, acceptance, review, and delivery. Plan commits valid contract revisions in the integration worktree and attempts to fast-forward existing packet worktrees to that checkpoint while preserving implementation work. Conflicts stop for resolution.
+
+`flywheel-verify` runs deterministic acceptance only. With `--packet`, it runs that packet's L1. Without a packet, it checks unfinished packets' L1 and the current milestone's L2/L3. It does **not** call Review or Judge, create worktrees, or perform local delivery. It uses the available candidate workspace and may use the integration checkout when no packet worktree is available.
+
+The bundled skills check task location before preparation, run, resume, and manual loop actions. By default, development starts outside `main`, `master`, a known default branch, or detached HEAD unless the user has explicitly chosen and authorized that location. Direct CLI and GUI actions do not read or execute `SKILL.md`, create the outer task branch, or inherit those host checks. Read-only status and stopping must remain available even when development-entry checks would fail.
+
+## 6. Understand local completion before merging the PR
+
+A packet is delivered only after L1 and independent Review match its current candidate, and Git delivery is confirmed. The engine commits implementation changes, performs `git merge --ff-only` into the integration checkout, persists delivery state, and cleans up only when safe. Failed commits or merges preserve the workspace. Milestone completion additionally requires L2/L3 and Judge.
+
+After the complete task passes, inspect the integrated changes and push them:
+
+```sh
+git status --short
+git log -5 --oneline
+git push origin task/my-feature
+gh pr ready
+gh pr checks
+```
+
+Before merging, review the current PR diff, relevant acceptance evidence, required CI results for the current head, and the effect of the current base branch. Changes after a green run or review may require renewed evidence. If a required CI check cannot run, record the blocker and use the repository's explicitly authorized exception process; do not describe an unavailable check as passed.
+
+Manual merge after those gates is the recommended default. Auto-merge can be appropriate for a repository with an explicit policy, required checks/reviews, protected branches, and a defined class of eligible changes. Enabling it is a host/user decision; Flywheel does not infer that permission from an early Draft PR or a local packet pass.
+
+## 7. Stop and recover without losing evidence
+
+```sh
+flywheel control stop --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+```
+
+Check the stop result and the actual failure before resuming from the **same** root and task path with `control start` or `flywheel-run`. A startup readiness timeout is a reason to query status and logs, not to launch a duplicate run. A stopped engine does not prove that every separately managed process is gone.
+
+Codex Pro retains a machine receipt with configuration, process, cleanup, and usage facts. If cleanup is unconfirmed after the worker started, the engine escalates and stops the current run. It does not automatically try another channel, a transport retry, or a fresh Plan call. Confirm the task-owned plugin/app-server/guardian processes have ended before attempting recovery; a fixed delay is not evidence. Avoid broad process killing that could terminate unrelated sessions.
+
+For a delivery conflict, preserve the packet worktree, inspect Git state, resolve the conflict deliberately, then resume and let the engine revalidate evidence. Do not use forced cleanup or manual state edits as a recovery shortcut. Configuration changes require restarting the engine.
+
+## Reference boundaries
+
+The engine owns local state, bounded loops, verification, and Git delivery. The authorized host/user owns task-branch setup, GitHub pushes and PRs, remote CI policy, PR merge, and publication. Repository visibility and licensing are separate decisions.
+
+Implementation references: [engine](https://github.com/ckanner/flywheel/blob/main/internal/machine/run.go), [Git/worktree operations](https://github.com/ckanner/flywheel/blob/main/internal/verify/verify.go), [design](https://github.com/ckanner/flywheel/blob/main/docs/design.md), and [bundled skills](https://github.com/ckanner/flywheel/tree/main/skills). Additional documentation: [Git worktree](https://git-scm.com/docs/git-worktree) and [GitHub auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request).

package/docs/getting-started.md

@@ -1,6 +1,8 @@
 # Mac 安装与首个 Flywheel 任务
 
-本文适用于 **Flywheel 0.27.3 及以后的完整 npm 发行版**，覆盖 npm 一条命令安装 CLI、worker、DSH 插件与 skills，到配置、启动、观察、停止和恢复一个小任务。DSH 接口目标是已核对的 **Mac 桌面 0.2.1-rc.5**。真实桌面、Seatbelt 和账号调用仍需在自己的 Mac 验收，CI 不能代替这些检查。
+[English](en/getting-started.md) · 简体中文
+
+本文适用于 **Flywheel 0.28.0 及以后的完整 npm 发行版**，覆盖 npm 一条命令安装 CLI、worker、DSH 插件与 skills，到配置、启动、观察、停止和恢复一个小任务。DSH 接口目标是已核对的 **Mac 桌面 0.2.1-rc.5**。真实桌面、Seatbelt 和账号调用仍需在自己的 Mac 验收，CI 不能代替这些检查。
 
 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](releasing.md#3-失败恢复)。
 
@@ -16,15 +18,17 @@
 8. [升级、排错与卸载](#8-升级排错与卸载)
 9. [开发与备用构建](#9-开发与备用构建)
 
+已有业务仓库另见[从需求准备到 PR 合并](workflow.md)：模型选择、任务 worktree、Draft PR 与合并时机。
+
 ## 1. 准备运行环境
 
 | 依赖 | 用途与检查 |
 |---|---|
 | Git，已配置提交身份 | Flywheel 使用 worktree 和本地提交交付；执行 `git --version` |
-| Node.js 22 或更高，npm | 安装 Flywheel 并运行 CLI 启动器／DSH worker；执行 `node --version`、`npm --version` |
+| Node.js 22.18.0 或更高，npm | 安装 Flywheel 并运行 CLI 启动器／DSH worker；执行 `node --version`、`npm --version` |
 | DSH Mac 桌面及其安装的 `dsh` 命令 | 在 About 核对具体版本；执行 `command -v dsh`、`dsh --version` |
 | 已登录的 Kimi CLI | 默认 Plan、frontend、Garden 使用它；执行 `kimi --version`、`kimi --help` |
-| 已登录的 Codex CLI | `hard` 执行路由使用它；执行 `codex --version` |
+| 已登录的 Codex 程序 | Codex Pro 插件在 `hard` 路由中启动其 app-server；执行 `codex --version` |
 | SDK profile 的 DeepSeek 和 ChatGPT provider | 默认实现／评审使用；配置与授权见下一节 |
 | Go 1.27 或更高 | 仅本文的 Go 示例和源码构建需要；npm 安装 Flywheel 不需要 Go 工具链 |
 
@@ -46,7 +50,7 @@ npx -y @ckanner/flywheel@latest install --json
 
 两条命令选择一种即可。安装器按顺序完成：
 
-1. 把本次安装器的精确版本装到 npm 全局目录，解析适合本机的 Go 平台包和同版本 DSH worker，核对 CLI 版本。
+1. 把本次安装器的精确版本装到 npm 全局目录，解析适合本机的 Go 平台包、同版本 DSH／Codex Pro workers 及精确插件依赖 `dsh-subagent-codex-pro@0.8.0`，核对 CLI 版本。
 2. 从 Go 二进制安装全部 10 个 skills；全局配置不存在时生成默认配置，已有配置保留。
 3. 写入 GUI 启动器和安装记录，使用绝对 Node／CLI 路径。
 4. 通过现有桌面 `dsh` 注册精确版本的 Flywheel 插件，并通过 `plugin list` 验证安装结果。
@@ -99,7 +103,7 @@ worker 默认使用独立的 `sdk` profile。桌面已安装 provider，不代
 dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
 ```
 
-随后按该 provider 的文档在对应 profile 完成授权，并保持一致的 `DSH_HOME`。不需要把凭证复制到任务契约或 Git。此处不把 `subagent_codex_pro` 当成原生 LLM provider；困难任务继续走独立 Codex CLI。
+随后按该 provider 的文档在对应 profile 完成授权，并保持一致的 `DSH_HOME`。不需要把凭证复制到任务契约或 Git。此处不把 `subagent_codex_pro` 当成原生 LLM provider。困难任务通过 `codex-pro` worker 直接使用已安装插件的公开 machine API，不需要 DSH 父模型再发一次工具调用。底层 Codex app-server 仍需本机 Codex 与登录；包依赖安装不代替它们。
 
 ### Mac GUI 的自动入口
 
@@ -170,7 +174,7 @@ flywheel doctor --cwd "$PWD" --probe --json
 
 第一条只查有效配置、本地命令版本、目录及已声明环境变量；不会检查凭证文件、发送模型 prompt 或运行 packet 验收。第二条对选中的 DSH 绑定做 SDK 初始化、cwd／沙箱握手及正常关闭；provider 初始化可能联网查询目录，但**没有推理请求**。两者都不创建 Flywheel 状态、运行锁、worktree 或全局配置。
 
-结果按 pass／fail／warn／unknown／skipped 展示；有 fail 时退出码 1，JSON 仍完整可读。即使 `ok:true`，unknown 的账号授权、订阅额度与实际推理仍未验证。Kimi/Codex 在这里只检查命令，不会自动登录或试调用。DSH 同一账号、模型、effort、目录和权限只探测一次，总预算 40 秒另加清理窗口；超时后明确失败。
+结果按 pass／fail／warn／unknown／skipped 展示；有 fail 时退出码 1，JSON 仍完整可读。即使 `ok:true`，unknown 的账号授权、订阅额度与实际推理仍未验证。Kimi/Codex 在这里只检查命令；Codex Pro 额外实际导入精确版本的公开 API，不会自动登录或试调用。Codex Pro 的完整沙箱策略只能事后审查，所以对应 sandbox 项会显示 warn，模型／配置／认证保持 unknown；`--probe` 也不会为它发送推理。DSH 同一账号、模型、effort、目录和权限只探测一次，总预算 40 秒另加清理窗口；超时后明确失败。
 
 未指定任务时检查全部配置绑定，可能包括首个任务用不到的 Codex hard 路由。准备好任务后可把范围缩小为所需的 Plan／Execute route／Review／Judge（以及显式启用的 judge-panel）：
 
@@ -184,6 +188,8 @@ flywheel doctor --cwd "$PWD" --task-dir docs/add --probe --json
 
 ## 6. 准备首个小任务
 
+已有业务仓库应先建立任务集成分支和独立 worktree，再生成契约；启动时的 `cwd` 指向该 worktree。完整步骤见[从需求准备到 PR 合并](workflow.md)，下面的小仓库示例用于首次运行验收。
+
 首次建议使用单独的小仓库，便于分清安装问题和业务代码问题。npm 包附带的准备脚本会创建一个 Go 加法函数任务：初始实现故意错误，执行者需修复实现并补普通单测；独立 acceptance 测试不可修改。本示例需要 Go 1.27 或更高。
 
 ```sh
@@ -226,7 +232,7 @@ git commit -m "docs: prepare first flywheel task"
 
 Git 提交身份必须已经按自己的设置配置。此时不应创建 `state.json`，它由引擎初始化。coverage 输出已被忽略，所以验收运行不会把生成物误判为候选代码漂移。
 
-对于已有业务仓库，可以通过 `flywheel-new` 生成并审阅契约，或者用 `flywheel template --list` 查看模板后手工准备。示例 auth 模板不是通用可运行任务，其中路径和验收命令必须改为真实项目的命令。不要照抄后直接启动。
+对于已有业务仓库，`flywheel-new` 使用当前 DSH 会话的模型生成契约；复杂需求建议选已授权的 `gpt-6-astra`、`high`，简单明确任务可沿用 Flash。它不会自动读取 `loops.plan` 来换模型，后者控制引擎运行后的 Kimi 规划／修订。可以通过 `flywheel-new` 生成并审阅契约，或者用 `flywheel template --list` 查看模板后手工准备。示例 auth 模板不是通用可运行任务，其中路径和验收命令必须改为真实项目的命令。不要照抄后直接启动。
 
 ## 7. 启动、观察、停止与恢复
 
@@ -276,7 +282,9 @@ flywheel control start --task-dir "$PWD/docs/add" --cwd "$PWD"
 npx -y @ckanner/flywheel@latest install
 ```
 
-自定义 prefix、项目 skills 或 DSH 入口时保留原参数。想固定某个已发布版本，可把 `@latest` 换成该精确版本，例如在 registry 确认 0.27.3 已发布后使用 `@0.27.3`；安装器始终为 CLI、平台包、worker 和桌面插件选择本次安装器的同一版本。已安装包的配置修复可用 `flywheel setup --no-global`，它不会将 CLI 升级到别的版本。
+自定义 prefix、项目 skills 或 DSH 入口时保留原参数。想固定某个已发布版本，可把 `@latest` 换成该精确版本，例如在 registry 确认 0.28.0 已发布后使用 `@0.28.0`；安装器始终为 CLI、平台包、worker 和桌面插件选择本次安装器的同一版本。已安装包的配置修复可用 `flywheel setup --no-global`，它不会将 CLI 升级到别的版本。
+
+从 0.27.x 升级到本版后，要使用新的默认插件路径，应在有效配置的 `routes.hard`（或其 profile）设置 `"harness": "codex-pro"`，保留所选 model／thinking／channel。先用 `config inspect` 找到实际配置来源；不要把 external subagent 的工具名写成 DSH provider。
 
 安装后对照新模板审阅需要迁移的配置，按宿主提示重新载入，运行 doctor，再用小任务验证。已有配置不会自动覆盖；特别检查任务级文件是否遮住了刚修改的项目或全局设置。安装不是跨 npm、DSH 与全部 skills 的单个事务：失败时报告已完成步骤，不擅自回退包管理器或删除用户文件。修正原因后重跑会重新核对版本与内容。
 
@@ -323,7 +331,7 @@ npm uninstall --global @ckanner/flywheel
 
 ## 9. 开发与备用构建
 
-以下用于贡献代码、检查未发布分支或离线备份；普通用户使用 npm 安装。需要 Git、Go 1.27 或更高、Node.js 22 或更高：
+以下用于贡献代码、检查未发布分支或离线备份；普通用户使用 npm 安装。需要 Git、Go 1.27 或更高、Node.js 22.18.0 或更高：
 
 ```sh
 git clone https://github.com/ckanner/flywheel.git