@wular/coder 0.4.13 → 0.5.1

package/docs/flows.md

@@ -1,16 +1,10 @@
-# Flows
-
-Orchestrate many coder tasks with a plain TypeScript file. A flow is code, not config: loops, conditionals, and nesting are just JavaScript, while dispatch, concurrency, journaling, and resume come from the runtime. Every task a flow spawns is a regular coder task, so `coder list`, `coder task steer`, and `coder task stop` work on them like any other.
-
-Like tasks, flows are normally authored by your host agent: you describe the wave, the harness writes the flow file into `.coder/flows/`, and you review or edit it before it runs. The file is the contract; everything below is what goes in it.
+---
+description: Flows, TypeScript files that run many coder tasks with gates and resume.
+---
 
-Watch a run live - progress and overview of its tasks as the wave goes:
-
-```sh
-coder flow stream [run-id]
-```
+# Flows
 
-## A first flow
+A flow is a plain TypeScript file that runs many coder tasks. Loops, conditionals and nesting are JavaScript; dispatch, concurrency, journaling and resume come from the runtime. Each task it starts is a regular task, so `coder list`, `coder task steer` and `coder task stop` work on it. A host agent usually writes the flow into `.coder/flows/` from a description, and a person reviews it before it runs.
 
 ```ts
 // .coder/flows/audit-routes.ts
@@ -26,224 +20,63 @@ export default await pipeline(routes.data.files, file =>
 );
 ```
 
-Run it:
-
-```bash
-coder flow run audit-routes --wait
-```
-
-`--wait` streams the run's progress right there; without it the run goes to the background and `coder flow stream` shows the same lines any time. If the run dies mid-wave, `coder flow resume` continues it without re-running finished steps.
-
-## Flows are plain modules
-
-A flow is an ordinary TypeScript module: import the primitives, use top-level `await`, and `export default` the result. `@wular/coder/flow` and `zod` come with Coder, so the repository installs neither. Input comes in through the `args` import (see [`args`](#args)):
-
-```ts
-// .coder/flows/verify-wave.ts
-import { task, pipeline, args } from '@wular/coder/flow';
-
-export default await pipeline(args.clusters as string[], c => task(`Verify cluster ${c}.`));
-```
-
-## The primitives
-
-### `task(prompt, opts?)`
-
-Dispatch one coder task and await its result.
-
-```ts
-const r = await task('Explain the auth module', {
-  model: 'sol',
-  permissions: 'read-only',
-});
-r.output; // final message text
-```
-
-Options are the same as the `coder run` flags (`engine`, `model`, `effort`, `permissions`, `name`, `appendSystem`, `cwd`, and `addDirs` for `--add-dir` - see `coder run --help`), plus one of its own:
-
-- `returns` - a zod schema for structured output instead of prose. The runtime passes the schema natively, validates the reply (one corrective retry on mismatch), and the parsed value lands on `r.data`:
-
-```ts
-const r = await task('List every file that imports the legacy cache API.', {
-  returns: z.object({ files: z.array(z.string()) }),
-});
-
-r.data.files; // string[], validated
-```
-
-Returns `{ taskId, status, output, data?, tokens, model }`. If the task fails, `task()` throws; catch the error to inspect the failed result or retry.
-
-> Note: unlike the SDK's `task.run()`, which returns a task id right away and leaves waiting to you, the flow `task()` waits for the result in one call, and inside a run it is journaled and concurrency-limited.
-
-### `steer(taskId, text, opts?)`
-
-Give a task this run started one more turn on its own thread, under the same task id, and await it. It mirrors `coder task steer --wait`, with the same `model`, `effort` and `permissions` overrides:
-
-```ts
-const draft = await task('Draft the schema for the new orders table.');
-const fixed = await steer(draft.taskId, 'Now add the indexes.');
-```
-
-Returns the same shape as `task()` without `data`, throws if the turn fails, and is journaled like `task()`.
-
-### `gate(cmd, opts?)`
-
-A deterministic shell checkpoint. Gates are never agents: they run the command and return `{ ok, code, output }`. A failing gate does not throw, because a failed gate is a decision point, not an error:
-
-```ts
-const g = await gate('bun tsc');
-if (!g.ok) {
-  // retry with g.output in the prompt, park the item, or bail - your call
-}
-```
-
-The command runs through the shell, so treat it like any shell string: never interpolate task output (or other model-derived text) into it - `gate(`test -n "${r.output}"`)` hands the model shell access. Write fixed commands, or pass model output through a file/env var the command reads.
-
-### `pipeline(items, ...stages)`
-
-The workhorse. Give it a list of items and one or more stage functions; every item moves through the stages independently, as fast as its own work finishes.
-
-```ts
-const results = await pipeline(
-  files, // items
-  file => task(`Fix the tests in ${file}.`), // stage 1
-  (r, file) => gate(`bun test ${file}`), // stage 2
-);
-```
-
-How to read it:
-
-- Stage 1 runs for each file (up to the concurrency limit). The moment `a.ts` finishes stage 1, it enters stage 2, even if `b.ts` is still in stage 1. There is no waiting for the whole batch between stages.
-- Each stage receives `(previousStageResult, originalItem, index)`, so later stages always know which item they are working on.
-- `results` is one entry per item: whatever the last stage returned for it.
-- If a stage throws for an item, that item becomes `null` in the results and skips its remaining stages; the other items are unaffected.
-
-Prefer `pipeline` for anything multi-stage: fast items never wait for slow ones.
-
-Use `Promise.all` for plain parallel batches:
-
-```ts
-const findings = await Promise.all(areas.map(area => task(`Audit ${area}.`)));
-```
-
-### `args`
-
-The flow's input, from `--args '<json>'` or bare `key=value` pairs:
-
-```ts
-import { args } from '@wular/coder/flow';
-
-const items = (args.items ?? []) as string[];
-```
-
-Properties are typed `unknown` - assert or default them as you go, or use the function form below for real types.
-
-To validate and type the input with zod, shape the flow as two exports:
+`coder flow run audit-routes --wait` runs it and streams progress. Without `--wait` it runs in the background and `coder flow stream` follows it. `/flow <name>` in **# Tasks → [New task]** runs one from the dashboard.
 
-- `export const args` - a zod schema for the input
-- `export default` - an async function holding the flow body
+A flow is an ES module with top-level `await`, and its default export is the result. `@wular/coder/flow` and `zod` come with Coder.
 
-The runtime checks the input against the schema first, and only if it passes runs the default function, passing the parsed input as its parameter. (Top-level flows can't get this fail-fast check: importing one already executes it.)
+## Primitives
 
-```ts
-export const args = z.object({ clusters: z.array(z.string()) });
-
-export default async ({ clusters }: z.infer<typeof args>) => {
-  // clusters is string[], validated before any task dispatched
-};
-```
+- **`task(prompt, opts?)`:** runs one task and waits for it.
+  - Options are the `coder run` flags (`model`, `access`, `name`, `appendSystem`, `cwd`, `addDirs`), plus `returns`: a zod schema for structured output, validated with one corrective retry, landing on `r.data`.
+  - Returns `{ taskId, status, output, data?, tokens, model }`, and throws if the task fails.
+  - Unlike the SDK's `task.run()`, it waits, and inside a run it's journaled and concurrency-limited.
+- **`steer(taskId, text, opts?)`:** one more turn on a task this run started, like `coder task steer --wait`. It returns the same shape as `task()` without `data`.
+- **`gate(cmd, opts?)`:** a shell checkpoint returning `{ ok, code, output }`. A failing gate doesn't throw; it's a decision point. Never interpolate model output into `cmd`, because that hands the model a shell. Pass it through a file or environment variable instead.
+- **`pipeline(items, ...stages)`:** moves each item through the stages independently.
+  - An item enters the next stage as soon as it finishes the last one, without waiting for the batch.
+  - Each stage gets `(previous, item, index)`.
+  - The result is the last stage's value per item, or `null` for an item whose stage threw.
+  - Use `Promise.all` for one plain parallel batch.
+- **`args`:** the input, from `--args '<json>'` or `key=value` pairs, typed `unknown`. For a validated, typed input, export a zod schema as `args` and a default async function that receives the parsed value. The runtime checks the input before any task starts.
+- **`flow(name, args?)`:** runs another flow inline, sharing the journal, concurrency and ledger. Nesting is one level deep.
+- **`log(msg)`:** a progress line in the flow log and `coder flow stream`.
 
-### `flow(name, args?)`
+## Limits
 
-Run another flow inline and get its result:
-
-```ts
-const verified = await flow('verify-wave', { clusters });
-```
+- `--concurrency`: tasks at once. Defaults to the machine's CPU count.
+- `--max-tasks`: total tasks per run, a backstop against loops. Defaults to CPU count × 10.
 
-The name resolves like `coder flow run <name>` does (see [Where flows live](#where-flows-live)). Sub-flows share the parent's journal, concurrency, and ledger, and nesting is one level deep: a sub-flow calling `flow()` throws.
-
-### `log(msg)`
-
-Emit a progress line, shown in the flow log and `coder flow stream`:
-
-```ts
-log(`${parked.length} clusters parked`);
-```
-
-## Concurrency and ceilings
-
-Two knobs, sensible defaults, mentioned together because they scale off the same number:
-
-- **`--concurrency`** - tasks running at once. Defaults to the machine's CPU count. Tasks are engine subprocesses doing mostly network waiting, so this is about engine quota and machine load, not about a flow "using up" your cores.
-- **`--max-tasks`** - total tasks one run may dispatch, a backstop against runaway loops. Defaults to CPU count x 10.
-
-Token usage is recorded per model in the run's ledger and shown by `coder flow result`. Bookkeeping, not enforcement.
+Tokens per model go to the run's ledger, shown by `coder flow result`.
 
 ## Resume
 
-Every `task`, `gate`, and `flow` call is recorded in the run's journal along with a fingerprint of its inputs (the prompt or command, plus options).
-
-`coder flow resume <run-id>` simply imports the module again, fresh, and lets it execute top to bottom. Each call is checked against the journal in order:
-
-1. Inputs identical to last time? Return the recorded result instantly; nothing is dispatched.
-2. First call whose inputs differ (or that is new)? It runs for real, and so does everything after it.
-
-What that means in practice:
+Every `task`, `gate` and `flow` call is journaled with a fingerprint of its inputs. `coder flow resume <run-id>` runs the module again from the top:
+- Calls with the same inputs return their recorded results at once.
+- The first changed or new call, and everything after it, runs for real.
 
-- **Crash mid-wave** (quota, network, closed laptop): resume replays the finished steps from the journal in milliseconds and continues from where it stopped.
-- **Edit step 3, resume**: steps 1-2 replay from the journal, step 3 onward runs fresh. Iterating on a half-broken flow costs only the part you changed.
-- **Nothing changed**: the whole run replays from the journal and just returns its result again.
-
-The one rule this buys: **a flow must produce the same prompts on every run**. Do not build prompts from `Date.now()`, `Math.random()`, or unordered directory listings; pass timestamps and seeds in via `--args`. A prompt that differs between runs looks like an edit, and everything after it re-runs.
+So a crash resumes where it stopped, and an edit to step 3 re-runs from step 3. A flow must build the same prompts on every run: no `Date.now()`, `Math.random()` or unordered directory listings in prompts; pass those in with `--args`.
 
 ## Where flows live
 
-`coder flow run <name>` (and `flow(name)` inside a flow) looks for `<name>.ts` or `<name>.mjs` in:
-
-1. `.coder/flows/` walking up from the current directory to the repo root, nearest first. In a monorepo, a flow in `packages/app/.coder/flows/` wins over one at the root when you run from inside `packages/app`.
-2. `~/.coder/flows/` - global flows, available in every workspace.
-
-An explicit path (`coder flow run ./scratch/one-off.ts`) bypasses discovery entirely. `coder flow discover` shows every flow discoverable from where you stand.
-
-### Built-in flows
-
-Coder ships a few flows of its own; they resolve after the directories above, so a repo flow of the same name overrides them. `coder flow discover` lists them with scope `builtin`.
-
-- `review`: the `coder review` code review. Args: `pr` (number or GitHub URL), `post` (comment on the PR), `base`/`head`/`since` (as the CLI flags), `engine`/`model`/`effort`. Returns `{ findings, summary }`. `coder flow run review --args '{"pr":42,"post":true}'`
-
-## CLI
-
-```bash
-coder flow run <name|path> [--wait] [--args '<json>' | key=value...]
-    [--concurrency N] [--max-tasks N] [--json] [--dry-run]
-coder flow list                 # recent runs: id, name, status, tasks, tokens, age
-coder flow discover             # flows runnable here: workspace + global
-coder flow result [run-id]      # progress and result: tasks, gates, token ledger
-                                #   --tail <n|all>: last n step rows (default all; 0 = final result only)
-coder flow stream [run-id]      # replay the progress lines and keep following live
-                                #   --tail <n|all>: replay the last n events (default all)
-coder flow stop [run-id]        # stop a run and its tasks (--keep-tasks to let them finish)
-coder flow resume [run-id]      # continue a stopped or edited run; same flags as run
-coder flow archive <run-id>     # hide a run from the recent list (or --all-stopped)
-coder flow delete <run-id>      # delete a run's record (or --all-archived)
-```
-
-Runs show up in `coder list` alongside tasks, with the run's tasks grouped under it. Any `[run-id]` defaults to the most recent run.
-
-`coder flow run` prints the run id and orchestrates in the background. `--wait` follows the run in the foreground, rendering progress live as tasks start and finish; Ctrl-C detaches and the run keeps going, just like a task. `coder flow stop` is the only way to end a run: it stops the orchestrator and the tasks it still has running (pass `--keep-tasks` to let those finish), leaving the journal ready for `resume`. A finished run's result (the flow's default export) is shown by `coder flow result`.
+`coder flow run <name>` and `flow(name)` look for `<name>.ts` or `<name>.mjs` in:
+1. `.coder/flows/`, from the current directory up to the repo root, nearest first.
+2. `~/.coder/flows/`, in every workspace.
+3. Built-in flows, which a repo flow of the same name overrides.
 
-On a TTY, `--wait` and `flow stream` render a live view (spinner, in-place task rows); when piped, output degrades to plain append-only lines. Styling honors the standard `NO_COLOR` and `FORCE_COLOR` env vars.
+A path runs that file directly. `coder flow discover` lists what's runnable here. The built-in `review` is the `coder review` code review. It takes `pr`, `post`, `base`, `head`, `since`, `model` and `depth` and returns `{ note, body, findings, summary, pr? }`. Posting happens inside the flow; server tasks use the `review` tool instead of running this flow by name.
 
-`--dry-run` executes the script with dispatch stubbed out: it prints every resolved prompt and gate command with placeholder results, so you can review exactly what would be sent before spending tokens.
+## Running
 
-## SDK
+- `--dry-run` executes the flow with dispatch stubbed and prints every resolved prompt and gate command.
+- `--wait` follows in the foreground; Ctrl-C detaches and the run continues.
+- `coder flow stop` is the only way to end a run. It stops its running tasks too (`--keep-tasks` lets them finish) and keeps the journal for `resume`.
+- Runs appear in `coder list` with their tasks grouped under them.
 
-Flows sit on top of the coder SDK, and the SDK is public: everything the CLI does, your own code can do, including running flows programmatically. See [SDK](sdk.md).
+All commands: [`coder flow`](cli/flow.md). From code: the [SDK](sdk.md).
 
-## Design notes
+## Guidance
 
-- **Gates are shell, not agents.** Verification must be deterministic and cheap. An agent judging "did tsc pass" is slower, costlier, and occasionally wrong.
-- **Park, don't die.** A failed item should not kill the wave. Return it as data, keep the rest flowing, fix it manually or in the next run.
-- **Saturation beats phases.** Prefer `pipeline` so fast items never wait for slow ones; reach for `Promise.all` barriers only when a step truly needs all prior results.
-- **The flow executes; you decide.** Keep judgment (what to fix next, whether a spec is ready) in your session, and let flows run the wave you already designed. A flow that invents its own plan mid-run is a flow you cannot review with `--dry-run`.
+- **Gates are shell, not agents:** verification stays deterministic and cheap.
+- **Park, don't die:** return a failed item as data and keep the wave going.
+- **Prefer `pipeline`:** fast items never wait for slow ones.
+- **Judgment stays in the session:** a flow runs the wave already designed. A flow that plans mid-run can't be reviewed with `--dry-run`.

package/docs/models.md

@@ -1,98 +1,68 @@
+---
+description: Built-in Claude and Codex models, custom endpoints, aliases, the chain, and turning models off.
+---
+
 # Models
 
-Manage every model Coder can dispatch to. That means the built-in Codex and Claude aliases, and your own - any OpenAI-compatible URL, like Ollama or llama.cpp on your laptop, a vLLM GPU box, OpenRouter, etc. Custom models work like any built-in: no login, and permissions, steering, and fallback just work.
+Every model a task can run: the built-in Codex and Claude models, aliases, and custom models at any OpenAI-compatible URL, such as Ollama or llama.cpp on a laptop, a vLLM box or OpenRouter. A custom model works like a built-in one: no login, and permissions, steering and fallback all apply.
 
-## Connect a model
+## Pick a model
 
-```bash
-# local Ollama model, no key
-coder model add qwen --base-url http://localhost:11434/v1 --model qwen2.5-coder:32b
+`--model`, an agent's `model`, `chain` and `reviewModel` each take one spec:
+- `<name>`: a built-in, an alias, a custom model, or an engine (`codex`, `claude`) for its model.
+- `<name>/<effort>`: `sol/low`, `fast/high`.
+- `<engine>/<model>`, `<engine>/<model>/<effort>`: `claude/opus`, `codex/gpt-6.1-sol/high`.
 
-# third-party provider via OpenRouter, key read from the environment
-coder model add kimi --base-url https://openrouter.ai/api/v1 --env-key OPENROUTER_API_KEY --model moonshotai/kimi-k2
-```
-
-`model add` saves the entry, probes the endpoint, and reports anything missing (unreachable URL, unset key env var, no codex). Change one later with `coder model update <name>`, drop it with `coder model remove <name>`. Flags:
+Effort is `low`, `medium` or `high`; without one, `medium`, unless the alias sets its own. On a custom chat endpoint it's sent as OpenRouter's `reasoning.effort`.
 
-| Flag               | Meaning                                                       |
-| ------------------ | ------------------------------------------------------------- |
-| `--base-url <url>` | OpenAI-compatible API base (e.g. `http://localhost:11434/v1`) |
-| `--model <id>`     | the provider's model id (e.g. `qwen2.5-coder:32b`)            |
-| `--env-key <VAR>`  | env var holding the API key; omit for keyless local endpoints |
-| `--context-window <tokens>` | the model's context window, filled when the provider reports it; Codex compacts at 90% of it |
-| `--workspace`      | write to `<repo>/.coder/config.json` instead of the user file |
+## The chain
 
-## Use it
-
-Anywhere a model name goes; together they form the `custom` engine:
+`chain` lists models in order, default `["codex/sol", "claude/opus"]`. A task runs its own model (from `--model` or its agent) else the first entry. When a model can't start (missing CLI, sign-in, quota, rate limit), the next one runs; a turn that already did work fails with the reason instead. Within one model, the asker's own subscription and key come before the workspace's. **# Settings → (Models)** shows the chain and what each entry runs on for the viewer.
 
 ```bash
-coder run --model qwen "explain this repo"        # per task
-coder run --engine custom "explain this repo"      # the custom engine (its default model, or the only one)
-coder config set engines.custom.model qwen         # default model for --engine custom
-coder model list                                  # list models + probe their endpoints
+coder config set chain '["codex/sol", "claude/opus", "qwen"]'
 ```
 
-Add `custom` to the fallback chain to make your models a fallback tier, e.g. a local model that takes over when the hosted engines are out of quota:
+## Built-ins and aliases
+
+| Name | Runs | Needs |
+|---|---|---|
+| `luna` | `codex/gpt-6-luna` | codex 0.156.1 |
+| `sol` | `codex/gpt-6.1-sol` | codex 0.159.1 |
+| `astra` | `codex/gpt-6-astra`, the review default | codex 0.154.0 |
+| `sonnet` | `claude/sonnet` | claude 2.1.197 |
+| `opus` | `claude/opus` | claude 2.1.280 |
+| `fable` | `claude/fable` | claude 2.1.257 |
+| `codex`, `claude` | `codex/sol`, `claude/opus` | |
+
+A task on an older CLI still runs, with a warning to update it. Claude names pass to the claude CLI, which resolves them (`opus` is Claude Opus 5.5 today); any full model id also works.
+
+An alias names a spec, and one with a built-in's name overrides it:
 
 ```bash
-coder config set chain '["codex", "claude", "custom"]'
+coder model alias fast codex/luna/low
+coder model alias claude claude/sonnet/high   # --model claude now runs sonnet at high
+coder model unalias claude                    # back to the built-in
+coder model disable astra                     # can't be picked or fallen back to
 ```
 
-## Built-ins, aliases, disabling
+## Connect a model
 
-Built-ins are just pre-seeded aliases tied to an engine, so `coder model list`
-shows them and your own aliases together, grouped per engine. Disable
-any model name - a built-in, a custom model, an alias, or a raw engine slug
-like `gpt-6-astra` - without removing its configuration, then re-enable it
-when needed; requests for a disabled model fail at dispatch:
+Under **# Settings → (Models)** or with `coder model add`:
 
 ```bash
-coder model disable astra
-coder model enable astra
+coder model add qwen --base-url http://localhost:11434/v1 --model qwen2.5-coder:32b
+coder model add kimi --base-url https://openrouter.ai/api/v1 --env-key OPENROUTER_API_KEY --model moonshotai/kimi-k2
 ```
 
-Create an alias for an engine spec with `coder model alias fast codex:luna`
-(effort can ride along: `coder model alias big claude:opus:high`); remove it
-with `coder model unalias fast`. Aliases may reuse a built-in name, so
-`coder model alias luna codex:gpt-x` intentionally overrides the built-in
-`luna`, and `model list` shows the override in its place.
-
-The built-ins:
-
-| Alias    | Model                 | Use it for                       | Needs          |
-| -------- | --------------------- | -------------------------------- | -------------- |
-| `luna`   | `gpt-6-luna` (codex)  | mechanical work                  | codex 0.156.1  |
-| `sol`    | `gpt-6.1-sol` (codex) | the default                      | codex 0.159.1  |
-| `astra`  | `gpt-6-astra` (codex) | the hardest work; costs the most | codex 0.154.0  |
-| `sonnet` | `sonnet` (claude)     | mechanical work                  | claude 2.1.197 |
-| `opus`   | `opus` (claude)       | the default                      | claude 2.1.280 |
-| `fable`  | `fable` (claude)      | the hardest work; costs the most | claude 2.1.257 |
-
-A task on an older CLI still runs, with a warning to run `codex update` or
-`claude update`.
-
-Claude aliases pass through to the claude CLI, which resolves them to its
-current model (`opus` is Claude Opus 5.5 today). Any full model id, such as
-`gpt-5.6-sol` or `claude-sonnet-5`, also works as a pass-through.
-
-## Config shape
-
-Every model command writes the one `models` section of the
-[config](config.md); the entry's shape says what it is (endpoint,
-engine alias, or a bare disable toggle for any model name):
-
-```json
-{
-  "models": {
-    "qwen": {
-      "baseUrl": "http://localhost:11434/v1",
-      "model": "qwen2.5-coder:32b",
-      "envKey": "MY_KEY"
-    },
-    "fast": { "provider": "codex", "model": "gpt-6-luna" },
-    "big": { "provider": "claude", "model": "opus", "effort": "high" },
-    "astra": { "disabled": true }
-  }
-}
-```
+`model add` saves the entry, checks the endpoint, and reports what's missing (unreachable URL, unset key variable, no codex). `coder model update <name>` changes one, `coder model remove <name>` drops it, `coder model list` lists every name and checks endpoints.
+
+| Flag | Meaning |
+|---|---|
+| `--base-url <url>` | OpenAI-compatible API base |
+| `--model <id>` | The provider's model id |
+| `--env-key <VAR>` | The variable holding the API key; omit for keyless local endpoints |
+| `--context-window <tokens>` | Filled in when the provider reports it; Codex compacts at 90% |
+| `--workspace` | Write the repo's `.coder/config.json` instead of the user file |
+
+Entries live in the `models` section of the [config](config.md#models).

package/docs/review.md

@@ -1,6 +1,10 @@
+---
+description: coder review, a read-only review of local changes or a pull request.
+---
+
 # Review
 
-`coder review` runs one read-only review task over local changes or a pull request, checks every finding against the repository, and prints the ones that hold. With `--post` it comments inline on the pull request and keeps one sticky summary; a posted finding is never posted again, even after its line moves. A local review covers everything since the merge-base with the origin default branch, committed or not, and never touches the index or working tree.
+`coder review` runs one read-only review task over local changes or a pull request, checks every finding against the repository, and prints the ones that hold. With `--post` it posts one review on the pull request: the reviewer's one-line title and markdown body, followed by a list and footer built by code, and an inline comment for each new finding. A posted finding is never posted again, even after its line moves. A local review covers everything since the merge-base with the origin default branch, committed or not, and never touches the index or working tree.
 
 ```sh
 coder review                         # local changes since the default branch
@@ -10,21 +14,21 @@ coder review --pr 42 --post          # pull request 42, posted as comments
 
 ## Flags
 
-| Flag                    | Meaning                                                                                                                          | Default                                            |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| `--effort <level>`      | Model reasoning effort and review depth: `low` reports critical and major defects, `medium` any defect, `high` also minor issues | Repository configuration, `medium`                 |
-| `--base <ref>`          | Older side of a local diff                                                                                                       | Merge-base of `HEAD` and the origin default branch |
-| `--head <ref>`          | Newer side of a local diff, commits only                                                                                         | The working tree                                   |
-| `--pr <n \| url>`       | Pull request number in the origin repo, or a GitHub pull request URL                                                             | Local diff                                         |
-| `--since <sha>`         | Keep only pull request hunks changed after this commit                                                                           | Head in the previous sticky summary                |
-| `--path <p>`            | Review only this pathspec; repeatable                                                                                            | Everything                                         |
-| `--exclude <p>`         | Leave this pathspec out; repeatable                                                                                              | Nothing                                            |
-| `--post`                | Post inline comments and update the sticky summary; needs `--pr`                                                                 | Print only                                         |
-| `--md`                  | Print Markdown                                                                                                                   | Enabled unless `--json` is used                    |
-| `--json`                | Print `{ findings, summary, runId }`                                                                                             | Disabled                                           |
-| `--engine <name>`       | Engine for the review task                                                                                                       | Repository configuration                           |
-| `--model <alias\|slug>` | Model for the review task                                                                                                        | Repository configuration                           |
-| `--cwd <dir>`           | Checkout to review                                                                                                               | Current directory                                  |
+| Flag | Meaning | Default |
+| --- | --- | --- |
+| `--base <ref>` | Older side of a local diff | Merge-base of `HEAD` and the origin default branch |
+| `--head <ref>` | Newer side of a local diff, commits only | The working tree |
+| `--pr <n \| url>` | Pull request number in the origin repo, or a GitHub pull request URL | Local diff |
+| `--since <sha>` | Keep only pull request hunks changed after this commit | Head of the last posted review |
+| `--path <p>` | Review only this pathspec, repeatable | Everything |
+| `--exclude <p>` | Leave this pathspec out, repeatable | Nothing |
+| `--post` | Post the review on the pull request as the signed-in `gh` user. Needs `--pr` | Print only |
+| `--run <id>` | With `--post`, post a finished review run instead of reviewing again | Review now |
+| `--md` | Print Markdown | Enabled unless `--json` is used |
+| `--json` | Print `{ title, body, findings, summary, pr?, runId }` | Disabled |
+| `--model <spec>` | [Model spec](models.md#pick-a-model) for the review task | The workspace's `reviewModel` |
+| `--depth <low\|medium\|high>` | What to report: `low` critical and major defects, `medium` any defect a maintainer would act on, `high` also minor issues | `medium` |
+| `--cwd <dir>` | Checkout to review | Current directory |
 
 `--pr` cannot be combined with `--base` or `--head`, and `--json` cannot be combined with `--md`.
 
@@ -34,12 +38,39 @@ The reviewer reads `AGENTS.md`, `CLAUDE.md`, and an optional `.coder/review.md`
 
 ## Submodules
 
-Changed submodules are reviewed file by file under their path. Uninitialized ones, ones missing a needed commit, and nested repositories that are not submodules are skipped with a warning, and submodule findings are never posted inline.
+Changed submodules are reviewed file by file under their path. Uninitialized ones, ones missing a needed commit, and nested repositories that are not submodules are skipped with a warning. Submodule findings are listed in the posted review with their full path, never inline.
 
 ## Exit codes
 
 The command exits `0` when the review completes, even with findings, `1` when the diff, review, or posting fails, `3` when no engine starts, and `4` while a task awaits approval.
 
+## Posted review
+
+One GitHub review per run: the reviewer's title and body, then the findings list headed `Reviewed b34340e: 3 issues` (the compare range on a rerun), each title linked to its inline thread at `file:12` or `file:12-20`. Basic output uses bold severity words and a small Markdown footer linking coder cloud (or coder cli) and the task when present. Inline comments put the bold severity between the title and failure. The CLI and self-hosted servers use basic output, with no images. With nothing found, `Nothing to report.`
+
+Reviews post plain Markdown: bold severity words and a `Posted by` line. A server with `REVIEW_ASSETS` set ([Self-host](self-host.md)) shows themed severity pills and buttons from that path or URL instead. coder.wular.ai sets it to the SVGs its site serves.
+
+- A rerun reviews only commits since the last posted review, and never posts a finding twice. After a force-push it says so.
+- The reviewer sees up to 100 earlier findings on the pull request with their state, never reply text. Only a resolved thread settles one.
+- Posting stops if the pull request moved since it was read: `The pull request moved to <sha7> since this review. Review again.`
+- Model text cannot ping, add HTML, images or links.
+- On a Coder server the review also runs a `Coder review` check on the head commit:
+  - `success`: clean, with no unresolved earlier findings.
+  - `neutral`: findings, earlier findings still unresolved (`no new issues, N unresolved`), or the review itself failed.
+  - `skipped`: the head moved. `cancelled`: stopped or timed out.
+
+  Findings never fail the check. Red means the change is broken, not that Coder had an opinion or an outage. Resolve a thread on GitHub to clear it. Any event on a pull request gets the check. It uses a separate checks-only token, and agent tokens never carry Checks. An installation that has not accepted the Checks permission yet gets reviews without the check. The CLI and local reviews post no check.
+
+## Who posts
+
+- A pull request event or any task on a repository on a Coder server: the agent's `review` tool. The runner drives it with the agent's app token and the review posts as the app. A task started elsewhere, such as from Slack, gets its findings unposted. A `read-only` task posts only on its own event's pull request. The reviewer itself never gets the token.
+- The `review` tool of a task on this machine: the findings come back unposted. Posting them as you takes your approval of `coder review --post --run <id>`.
+- `coder review --pr <n> --post`: posts as the `gh` user signed in here.
+
+A repository's own `.coder/flows/review.ts` replaces the built-in flow but gets neither the app's token nor the checks token, so it cannot post or set checks as the app.
+
+A reviewer runs as the same OS user as its task, so a read-only sandbox stops writes, not reads: files the task's turn holds, including its git credential, are reachable. Only a machine sandbox or a separate user isolates them.
+
 ## From a task
 
-Every task has a `review` tool. It reviews the task's uncommitted changes in the background, or those since `base`, and sends the findings to the task as a message. One review runs at a time, at most 5 per task.
+Every task has a `review` tool. It reviews the task's uncommitted changes in the background, or those since `base`, or a pull request, and sends the findings to the task as a message. One review runs at a time, at most 5 per turn.

package/docs/runners.md

@@ -0,0 +1,49 @@
+---
+description: Runners, the machines tasks run on; kinds, personal and workspace runners, pairing a member's machine, and which runner a task uses.
+---
+
+# Runners
+
+A runner is the machine a task runs on, with its own engine logins. Manage them under **# Settings → (Runners)** or with `coder runner`.
+
+## Kinds
+
+| Kind | Runs tasks on |
+| --- | --- |
+| Server default | What the server's operator set (`RUNNER`, see [Self-host](self-host.md#runners)) |
+| Your machine | A member's own computer, paired once; on a local server, Another machine |
+| Vercel Sandbox | A fresh Vercel machine per task |
+| GitHub Actions | A workflow run in a chosen repository |
+| HTTP runner | Any controller that speaks the runner protocol |
+| Docker on the server | A container on the server's machine; only on a local server |
+
+## Personal or workspace
+
+- **Personal:** runs only its owner's tasks. Any member adds one.
+- **Workspace:** runs every member's tasks. Only owners and admins add one.
+
+Each scope has one default, set with `coder runner default <id>` or **[Make default]**.
+
+## A member's own machine
+
+`coder runner serve` runs the server's tasks on this machine with its own `claude` and `codex` logins, so it needs no engine credential. The server reaches it through any public HTTPS tunnel, such as `cloudflared tunnel --url http://localhost:4100`, `ngrok http 4100` or `tailscale funnel 4100`.
+
+- **Signed in** (`coder auth login`): `coder runner serve --url <tunnel address>`.
+- **Paired from the dashboard:** **# Settings → (Runners) → [Add runner] → Your machine** shows a one-use token valid for 15 minutes. Then `coder runner serve --url <server> --token <token> --runner-url <tunnel address>`.
+
+Each start registers the current tunnel address, so a changing address is fine. The runner calls home every minute and shows offline after five without one. `--workspace` (owners and admins) makes it run every member's tasks. A task's work folder stays across turns and goes when the task is deleted.
+
+## Which runner a task uses
+
+1. The runner the task names (`coder task run --runner`).
+2. Its agent's runner.
+3. The person's own default, on their own tasks and DMs.
+4. The workspace default.
+5. The server default.
+
+A member's machine and an HTTP runner can use their machine's own engine logins. Every other kind needs an engine credential under **# Settings → (Credentials)**.
+
+## GitHub Actions and Vercel Sandbox
+
+- **GitHub Actions:** save the output of `coder server workflow` as `.github/workflows/coder-agent.yml` on the repository's default branch, and save it again after each Coder upgrade. Its token needs Actions read and write on that repository. Job logs appear after GitHub archives them.
+- **Vercel Sandbox:** supply the team and project IDs, or the server's `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID`. Logs stream while the task runs.