@ckanner/flywheel 0.27.3 → 0.28.1

package/docs/en/configuration.md

@@ -0,0 +1,193 @@
+# Model profiles, stage bindings, and diagnostics
+
+[English README](../../README.en.md) · [中文](../configuration.md) · [Workflow](workflow.md)
+
+Flywheel loads one complete configuration, expands its model profiles, and resolves each stage's binding before starting. Model selection is explicit configuration. Restart the engine after changing it. This guide describes the 0.28.0 implementation; existing user configuration is not automatically migrated during installation.
+
+## Configuration precedence
+
+The discovery order is:
+
+1. Task directory: `flywheel.config.json`.
+2. Project Git root: `flywheel.config.json`.
+3. Global file: `~/.config/flywheel/flywheel.config.json`.
+4. Embedded defaults.
+
+Flywheel selects the **first complete file**. It does not merge fields, profiles, loops, routes, or channels across those locations. `FLYWHEEL_CONFIG` replaces the global file path only; it does not override an existing task or project file. `XDG_CONFIG_HOME` does not change the current default path.
+
+An unreadable higher-priority file, invalid JSON, or broken symlink is an error, not permission to use a different account's configuration. Inspect the selected source before editing:
+
+```sh
+flywheel config inspect --cwd /absolute/path/to/repo --task-dir /absolute/path/to/repo/docs/my-feature --json
+```
+
+The result includes `source`, `scope`, resolved physical paths, and stage `bindings`. Without `--task-dir`, discovery starts at the selected project and lower levels. Inspection does not create global configuration or task state, read account tokens, or invoke a model.
+
+## Fields and identities
+
+| Field | Meaning | Example |
+|---|---|---|
+| `harness` | Process and tool-loop backend | `dsh`, `kimi`, `codex-pro`; `codex` is the explicit older CLI path |
+| `provider` | Registered DSH SDK LLM adapter ID; applies to DSH bindings | `deepseek-official`, `chatgpt` |
+| `channel` | A configuration label used for credentials, fallback, and accounting | `deepseek-sdk`, `chatgpt-sdk`, `kimi-subscription` |
+| `model` | Exact model identifier passed to the selected backend | `deepseek-flash`, `kimi-code/k3.1-pro`, `gpt-6.1-sol` |
+| `thinking` | Requested reasoning effort | `high` |
+| `profile` | Reusable model fields inside this Flywheel configuration | `flash`, `gpt-review`, `codex-pro` |
+
+A Flywheel model profile is different from a DSH `sdk` or `desktop` profile. The latter chooses the host's plugins and authorization configuration. A channel alias alone does not switch DSH accounts or create a separate subscription or quota pool.
+
+For DSH, the provider resolves from `binding.provider`, then `channels[channel].provider`, then the legacy channel name. Explicit binding and channel provider values must agree. Kimi and Codex use their own login state; a DSH provider cannot be attached to those harnesses and silently ignored.
+
+Only supported effort values should be used. The checked DSH Flash adapter accepts `off/low/high/max`; it has no `medium`. A configuration value names an intended binding, not evidence of account entitlement or measured model performance.
+
+## Start from a complete template
+
+Inspect either bundled example:
+
+```sh
+flywheel template flywheel.config.example.json
+flywheel template flywheel.profiles.example.json
+```
+
+The first uses inline bindings. The second is a complete configuration with reusable profiles. If you choose to create a project configuration, first confirm that no file needs preserving; then export one template from the target Git root. For example, Bash's noclobber option prevents replacing an existing regular file:
+
+```sh
+(set -C; flywheel template flywheel.profiles.example.json > flywheel.config.json)
+```
+
+Do not create a task file containing only a few profiles and expect it to inherit the rest from the project file. An illustrative **fragment**, to incorporate into a complete file, is:
+
+```json
+{
+  "profiles": {
+    "flash": {
+      "harness": "dsh",
+      "provider": "deepseek-official",
+      "channel": "deepseek-sdk",
+      "model": "deepseek-flash",
+      "thinking": "high"
+    }
+  },
+  "routes": {
+    "default": { "profile": "flash" }
+  },
+  "loops": {
+    "intake": { "profile": "flash", "thinking": "low" }
+  },
+  "channels": {
+    "deepseek-sdk": {
+      "harness": "dsh",
+      "provider": "deepseek-official",
+      "env-key": null
+    }
+  }
+}
+```
+
+`loops` binds Plan, Review, Judge, Intake, and Garden. `routes` selects the Execute backend for default/frontend/hard packets. `drivers` selects real or mock drivers; it is not a provider-name mapping. The full default routing table is in the [README](../../README.en.md#default-model-routes).
+
+### Profile override and validation rules
+
+| Input | Effect |
+|---|---|
+| Stage omits a profile field | Inherit that field from the referenced profile |
+| Stage explicitly supplies `model`, `thinking`, `channel`, etc. | Override only that stage |
+| `thinking: ""` | Use the harness's default effort instead of re-inheriting the profile |
+| `resident-session: false` | Explicitly disable the stage's resume request |
+| `judge-panel: null` | Disable the optional second opinion |
+| Missing/empty profile `harness`, `model`, or `channel` | Configuration error |
+| Unknown profile, field, stage name, or harness | Configuration error |
+| A profile references another profile | Unsupported; configuration error |
+| `_note` or `_note_*` | Permitted explanatory metadata, excluded from execution bindings |
+
+`resident-session` belongs on a stage, not in a profile. Currently only Kimi Plan can resume, and only when harness, model, channel, working directory, and thinking match. This restores session history, not a permanently running process. Execution and review calls start fresh sessions.
+
+Legal existing zero values, including `env-key: null`, `retry.jitter: 0`, and `worktree.enabled: false`, remain meaningful. When changing a harness or channel, also inspect any inherited provider. Use `provider: ""` when necessary to clear an explicit value before resolving the newly selected DSH channel.
+
+## Codex Pro and migration
+
+The 0.28.0 embedded hard route uses this binding. This is a **fragment**, not a complete replacement configuration:
+
+```json
+{
+  "routes": {
+    "hard": {
+      "harness": "codex-pro",
+      "model": "gpt-6.1-sol",
+      "channel": "chatgpt-subscription",
+      "thinking": "high"
+    }
+  }
+}
+```
+
+The complete profile template uses `profiles.codex-pro` and references it from `routes.hard`. The npm dependency is exactly `dsh-subagent-codex-pro@0.8.0`. The worker imports its public `dsh-subagent-codex-pro/machine` entry and calls `runMachine` using protocol 1. The plugin itself runs Codex app-server and uses the existing Codex login.
+
+The external tool name `subagent_codex_pro` is not a DSH provider. This route does not create a parent DSH model to make a second delegation. Missing dependencies or invalid receipts fail; they do not trigger an implicit fallback to the older CLI driver.
+
+To migrate an existing configuration, use `config inspect` to locate the effective file. Change the hard route's inline harness or referenced profile from `codex` to `codex-pro`, retain the intended model/channel/thinking, inspect the result, and restart. Keeping `harness: "codex"` explicitly retains the older `codex exec` behavior.
+
+`codex-pro` requires nonempty model and channel values. It does not inherit the old Codex driver's implicit model. Omitted thinking defaults to `high`; `resident-session: true` is rejected. Each execute/review call uses a new ephemeral session.
+
+### Worker environment
+
+| Variable | Purpose |
+|---|---|
+| `FLYWHEEL_DSH_WORKER` | Optional DSH worker override; the npm launcher normally resolves the matching dependency |
+| `FLYWHEEL_DSH_BIN` | DSH command, otherwise `dsh` on PATH |
+| `FLYWHEEL_DSH_PROFILE` | SDK profile, default `sdk`; it must not be `desktop` |
+| `DSH_HOME` | Optional DSH configuration root, interpreted by DSH |
+| `FLYWHEEL_KIMI_BIN` | Kimi CLI override, otherwise `kimi` on PATH |
+| `FLYWHEEL_CODEX_PRO_WORKER` | Optional Codex Pro worker override; normally resolved by npm |
+| `FLYWHEEL_CODEX_BIN` | Codex executable used by the plugin, otherwise `codex` on PATH |
+| `CODEX_HOME` | Existing Codex configuration/login directory, interpreted by Codex |
+
+These settings must be visible to the process starting the engine. The installer does not copy authentication data. The managed GUI launcher records executable paths and the installation-time tool PATH; a terminal export alone does not change an already running desktop process.
+
+### Permissions, receipts, and cleanup
+
+The plugin checks the requested model, working directory, approval policy, and sandbox mode before a turn. Flywheel examines the complete returned policy afterward. Workspace-write permits the workspace and standard Codex temporary directories; extra external write roots, enabled network, or unconfirmed policy make the result ineligible for successful delivery.
+
+**The complete policy check happens after execution. It cannot prevent access already allowed by custom Codex configuration.** An environment requiring a full policy rejection before any turn needs an upstream public pre-turn guard. Kimi's current CLI integration also provides no OS-level sandbox guarantee; a configured permission requirement should not be read as proof of its enforcement.
+
+The `codex-pro-receipt` metric preserves the complete machine receipt, including requested and actual configuration, thread/turn IDs, process outcomes, cleanup, usage, and failures. An accepted effort request is not proof of effective server reasoning effort; `effectiveEffort` remains null.
+
+An abnormal worker exit does not prove the plugin's separately managed processes stopped. If cleanup cannot be confirmed after startup, the engine records the evidence, escalates, and ends the run instead of automatically retrying or falling back. Before resuming, confirm the owned app-server/guardian processes have terminated. See [recovery](workflow.md#7-stop-and-recover-without-losing-evidence).
+
+## Fallback and budgets
+
+Default profiles do not enable automatic paid fallback across channels. An explicitly configured `channels[channel].fallback` is a bounded chain and is used only when error classification and retry policy permit it. A fallback resolves provider and model for the newly selected channel; an omitted harness inherits the current harness.
+
+Metrics retain harness, provider, channel, and model separately. Provider remains null if the driver cannot confirm it. Missing usage and dollar cost remain unknown, including subscription calls. Numeric aggregates are lower bounds of known usage, not a complete bill.
+
+For Codex Pro, only complete usage for the current run enters known token accounting; partial/unknown usage remains in the receipt and counts as unknown calls. The plugin does not provide actual dollar billing. Explicit user pricing plus complete usage can produce an estimate, which remains distinct from the subscription bill.
+
+The default token budget is soft, with a daily limit of 2,000,000 tokens. A soft budget reports uncertainty. A hard budget stops when unknown usage makes compliance unverifiable. Disabling enforcement does not turn off accounting or convert unknown values to zero.
+
+Acceptance commands use a restricted environment. If the project requires additional tool variables such as `GOCACHE` or `GOPATH`, add their names to `verify.env-allowlist` and ensure they exist in the engine's environment. Do not put secret values into task contracts or committed configuration.
+
+## Diagnose without inference
+
+```sh
+flywheel doctor --cwd /absolute/path/to/repo --json
+flywheel doctor --cwd /absolute/path/to/repo --task-dir /absolute/path/to/repo/docs/my-feature --json
+flywheel doctor --cwd /absolute/path/to/repo --task-dir /absolute/path/to/repo/docs/my-feature --probe --json
+```
+
+Without a task, doctor checks all configured bindings. With a task, it validates the Spec/packets and requires Plan, Review, Judge, enabled second opinions, and routes used by the packets; other bindings can be skipped. With no packets yet, it checks the default execution route and reports that preparation must finish. A real run still needs at least one reviewed legal packet.
+
+Local checks cover commands, versions, directories, configuration, and declared nonempty environment variables, without showing their values. `--probe` additionally initializes DSH SDK sessions, verifies accepted configuration, working directory, permissions, and normal shutdown. Identical probes are deduplicated only when their relevant identity and permissions match. The probe budget is 40 seconds plus bounded process cleanup time.
+
+Codex Pro checks actually import the public API and verify exact version 0.8.0/protocol 1, Node compatibility, and the Codex executable. `--probe` does not send a task through this path: account/model/effort and full runtime policy remain unverified. A successful import is not a successful model call.
+
+| Status | Meaning |
+|---|---|
+| `pass` | Evidence supports this individual check only |
+| `fail` | A blocker; overall `ok:false` and exit code 1 |
+| `warn` | A limitation or preparation state requiring interpretation |
+| `unknown` | Not verified, such as entitlement, quota, or real inference |
+| `skipped` | Not required, mock mode, duplicate probe, or an unmet prerequisite |
+
+No probe sends an inference prompt, runs L1/L2/L3, creates a worktree, or writes Flywheel task state. SDK initialization may contact a provider's catalog and write its own cache/session files; read-only here is scoped to Flywheel state and configuration. Recheck in the desktop panel because its PATH/profile/environment may differ from the terminal.
+
+Repository references: [inline defaults](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.config.example.json), [complete profiles](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.profiles.example.json), [design](https://github.com/ckanner/flywheel/blob/main/docs/design.md), and [worker protocol](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/PROTOCOL.md).

package/docs/en/getting-started.md

@@ -0,0 +1,259 @@
+# Install and run your first Flywheel task
+
+[English README](../../README.en.md) · [中文](../getting-started.md) · [Workflow](workflow.md) · [Configuration](configuration.md)
+
+This guide covers **Flywheel 0.28.1**: 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.
+
+The top-level **Flywheel conversation view** below is available from `0.28.1`. Version `0.28.0` uses the composer popup; upgrade the CLI and desktop plugin to the same new version. Merging source or reloading the old version does not change that layout. CLI and task-directory interfaces remain the same.
+
+## 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 and select **Flywheel** in the native view bar alongside Chat and Trajectory. Check that bar's More menu if the entry is not directly visible.
+
+This view controls and observes an already prepared task: progress, intervention, effective models, environment checks, and explicit start/refresh/stop. DSH keeps its chat, trajectory, composer, model selector, and right sidebar. Discuss requirements and prepare contracts through the original chat and skills. The view does not discover tasks started elsewhere; select the same task directory to observe one.
+
+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 SDK worker's temporary permission and tool policy applies only to its child process. It does not edit the desktop profile or remove desktop capabilities. Worker-owned delegation, auxiliary model compaction, and currently the entire web tool are disabled. A native view does not make the worker inherit desktop plugins or merge its history. See the [plugin's lifecycle boundaries](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md#permissions-and-lifecycle-boundaries) for the capability limits and separate work needed to restore retrieval safely.
+
+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 top **Flywheel** view accepts the same two absolute paths. Expand its model-configuration and environment-check section when needed, then use the explicit start, refresh, or stop action. A control response's `ok` means the operation succeeded; task completion is determined by `state.status`. The view displays the last refresh time and does not poll automatically.
+
+Draft paths and fetched snapshots are retained separately for each session across view switches while the host retains that session binding; a plugin reload or desktop restart may require selecting the paths again. Path edits discard old results and reject late replies without stopping the old task. Only one control request is pending per session, and a start or stop locks directory inputs while waiting.
+
+After a start/stop timeout or disconnect, the background task's outcome may be unconfirmed. Keep the same task directory, refresh status, and inspect logs before deciding how to recover. The view disables further starts/stops until that task is successfully reconciled and never retries mutations automatically. A prior snapshot, closing a page, or switching sessions cannot prove the engine stopped. The native trajectory retains its parent-session records; full worker histories are not merged into it.
+
+If the host explicitly confirms rejection before the control process started, such as a missing directory, correct the path or environment and submit again. This requires structured host evidence; error-message text alone cannot establish that a lost request was never executed.
+
+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` |
+| The large composer popup is still present | Published `0.28.0` has the old layout; verify a build containing the conversation-view fix is installed, then reload as directed by DSH |
+| Flywheel is not directly visible in the top bar | Check More, plugin enablement, and the actual installed version; `/flywheel` and CLI remain diagnostic entry points |
+| 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 |
+| Start/stop outcome is unconfirmed | Refresh the same task and inspect logs; timeout/disconnection proves neither no start nor a completed stop, and mutations are not retried automatically |
+
+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).