@wular/coder 0.4.12 → 0.5.0

package/docs/config.md

@@ -1,105 +1,67 @@
+---
+description: Every setting in ~/.coder/config.json and a repository's .coder/config.json.
+---
+
 # Configuration
 
-The Coder configuration reference. Machine defaults live in `~/.coder/config.json`; `.coder/config.json` in a repo overrides them per project. Merge order, later wins:
+`~/.coder/config.json` holds a machine's settings, and `.coder/config.json` in a repo overrides them for that repo. Later wins:
 
 1. Built-in defaults
 2. `~/.coder/config.json`
 3. `<repo>/.coder/config.json`
-4. CLI flags on the dispatch itself (`--engine`, `--model`, `--effort`, `--permissions`)
+4. Flags on the task (`--model`, `--access`)
 
-Read and write values from the CLI (`--workspace` targets the repo file instead of the user file):
+On a Coder server, the workspace's settings take the place of the user file, and a repo can only shorten `chain` or set its own `reviewModel`. The dashboard edits them under **# Settings**; the CLI with `coder config` (`--workspace` writes the repo file):
 
 ```bash
 coder config list
-coder config get <key>
-coder config set chain '["codex", "claude", "custom"]'
-coder config set engines.codex.model sol
+coder config set chain '["codex/sol", "claude/opus"]'
+coder config migrate          # rewrite an older file in the current shape
 ```
 
 ## Full shape
 
 ```json
 {
-  "chain": ["codex", "claude", "custom"],
-  "engines": {
-    "codex": { "model": "sol", "effort": "high", "permissions": "auto", "network": true },
-    "claude": { "model": "opus", "effort": "medium", "permissions": "auto" },
-    "custom": { "model": "qwen" }
-  },
+  "$schema": "https://coder.wular.ai/schema/config.v1.json",
+  "version": 1,
+  "chain": ["codex/sol", "claude/opus", "qwen"],
+  "reviewModel": "codex/astra",
   "models": {
+    "claude": "claude/sonnet/high",
+    "fast": "codex/luna/low",
     "qwen": { "baseUrl": "http://localhost:11434/v1", "model": "qwen2.5-coder:32b" },
-    "fast": { "provider": "codex", "model": "gpt-6-luna" },
-    "big": { "provider": "claude", "model": "opus", "effort": "high" },
-    "astra": { "disabled": true }
-  },
-  "approvals": {
-    "escalationTimeoutMs": 120000,
-    "allowedNetworkHosts": ["localhost", "127.0.0.1", "registry.npmjs.org"]
+    "astra": false
   },
-  "agents": {
-    "review": false,
-    "helper": {
-      "permissions": "read-only",
-      "access": "read"
-    }
-  },
-  "mcp": {
-    "docs": { "command": "npx", "args": ["-y", "docs-mcp"], "tools": ["search"] }
-  }
+  "agents": { "coder": { "model": "sol", "access": "read-only" }, "helper": false },
+  "mcp": { "docs": { "command": "npx", "args": ["-y", "docs-mcp"], "tools": ["search"] } },
+  "network": { "allowedHosts": ["localhost", "registry.npmjs.org"], "readOnlyTasks": true }
 }
 ```
 
-## `chain`
-
-Fallback order. When an engine can't start (missing binary, auth, quota), the task automatically retries on the next entry. Default `["codex", "claude"]`.
-
-## `conversationCompactTokens`
-
-Context size in tokens at which a platform conversation's task, such as a Slack thread or a pull request, continues from a summary plus its recent messages. Default `70000`.
-
-## `engines`
-
-Per-engine defaults, used when a dispatch doesn't override them:
+Every value that names a model is a [model spec](models.md#pick-a-model): `sol`, `sol/low`, `claude/opus` or `codex/gpt-6.1-sol/high`. A spec without an effort runs at `medium`.
 
-| Key           | Values                                                                                                                                        |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `model`       | codex: `luna`, `sol` (default), `astra` · claude: `sonnet`, `opus` (default), `fable` · custom: any name from `models` · or any full model id |
-| `effort`      | `low`, `medium`, `high`                                                                                                                       |
-| `permissions` | `read-only`, `workspace-write`, `auto`                                                                                                        |
-
-Permission modes are one surface across all engines: read-only can't modify anything, workspace-write stays inside the repo, and auto enables Codex network access plus policy-answered escalations; `engines.codex.network` overrides network access for every mode when set.
-
-A task reaches only its workspace unless you give it more. Pass `--add-dir <dir>` to `coder run` once for each sibling repo or shared folder the task needs. Relative paths resolve against the workspace and each one must already exist. Read-only tasks can read these directories but never write them, while workspace-write and auto tasks can write them just like the workspace. Claude receives them as `--add-dir` and `permissions.additionalDirectories`, so its OS sandbox follows the same rules. Codex already reads everywhere in read-only, and in the other modes it receives them as extra writable roots in the turn's sandbox policy. The directories are saved on the task, `coder result` lists them, and steering keeps them.
+| Key | Meaning | Default |
+|---|---|---|
+| `version` | The config's format; Coder writes it | `1` |
+| `chain` | Models in order. The first runs a task with no model of its own; the next ones take over when a model can't start (missing CLI, sign-in, quota, rate limit). A task's or agent's model goes first and the rest follow. | `["codex/sol", "claude/opus"]` |
+| `reviewModel` | The model `coder review` and the `review` tool use | `"codex/astra"` |
+| `models` | Names a spec can use: an alias (a spec string), `false` to turn a name off, or an endpoint (below) | built-in aliases |
+| `agents` | How this repo runs each agent: [Usage](agents/index.md#usage) | |
+| `mcp` | Servers a task attaches with `--mcp`: [Connections](connections.md#mcp-servers-in-config) | |
+| `network.allowedHosts` | Hosts, with their subdomains, that auto tasks reach without review ([Approvals](approvals.md)) | `[]` |
+| `network.readOnlyTasks` | Read-only tasks also reach `allowedHosts`, on every engine | `false` |
 
 ## `models`
 
-One namespace for every model you can name as `--model`, keyed by that name. An entry's shape decides what it is:
-
-| Shape                                                   | Meaning                                                                                                | Managed by                      |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------- |
-| `{ "baseUrl", "model", "envKey"?, "wireApi"? }`         | custom OpenAI-compatible endpoint (the `custom` engine)                                                | `coder model add/update/remove` |
-| `{ "provider": "codex"\|"claude", "model", "effort"? }` | alias onto a built-in engine                                                                           | `coder model alias/unalias`     |
-| `{ "disabled": true }`                                  | bare toggle turning off any model name (built-in, entry from another config layer, or raw engine slug) | `coder model disable/enable`    |
-
-Every shape also accepts `"disabled": true` to park the entry without deleting it. An entry named after a built-in alias (e.g. `luna`) shadows it. See [Models](models.md).
-
-## `approvals`
-
-Tunes the `auto` permission mode; ignored by `read-only` and `workspace-write`.
-
-| Key                   | Meaning                                                                                                                |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `escalationTimeoutMs` | How long an escalated approval waits for an answer before auto-denying and letting the task move on. Default `120000`. |
-| `allowedNetworkHosts` | Hosts (and their subdomains) coders may reach without an approval when network sandboxing is active. Default `[]`.     |
-
-`allowedNetworkHosts` is pre-allowed in the Claude sandbox and auto-accepted by the Codex approval policy when `engines.codex.network` is `false`. A bare hostname covers its subdomains; anything else escalates as usual. Listing `localhost`, `127.0.0.1` or `::1` also lets sandboxed Claude commands serve on local ports (macOS), so a task can run a dev server. On `vercel-sandbox` they also open the firewall of tasks below `auto`.
-
-Allowlist only hosts you trust: the check is by name, not by the address the name resolves to.
+- **Alias:** `"fast": "codex/luna/low"`. Built-in aliases are `luna`, `sol`, `astra`, `sonnet`, `opus`, `fable`, and the engine names `codex` (sol) and `claude` (opus). An alias of the same name overrides one, so `"claude": "claude/sonnet/high"` makes `--model claude` run sonnet at high. `coder model alias` and `unalias`.
+- **Off:** `"astra": false`. The name can't be picked or fallen back to. `coder model disable` and `enable`.
+- **Endpoint:** `{ "baseUrl", "model", "envKey"?, "wireApi"?, "contextWindow"?, "disabled"? }`, an OpenAI-compatible model where `model` is the provider's id. `coder model add`, `update` and `remove`; [Models](models.md#connect-a-model).
 
-## `agents`
+## Versions
 
-Per-agent usage: enable, override, scope. Reference and examples in [Agents](agents/index.md#usage).
+An older file (no `version`, or a lower one) is brought up to date when it loads. The user file is rewritten, with the old one kept as `config.json.bak`. A repo file is updated in memory only, since teammates may run an older Coder; `coder config migrate --workspace` rewrites it. A file from a newer Coder is refused with the upgrade command.
 
-## `mcp`
+## Extra directories
 
-Servers tasks can attach with `--mcp <name>`, in the `.mcp.json` entry shape. Reference and CLI in [MCP](mcp.md).
+A task reaches only its workspace unless given more: `--add-dir <dir>` on `coder task run`, once per folder. Each one must exist. Read-only tasks read them, auto tasks also write them, and steering keeps them.

package/docs/connections.md

@@ -0,0 +1,80 @@
+---
+description: Platform and MCP server connections, workspace and personal scopes, and MCP config.
+---
+
+# Connections
+
+A connection gives tasks tools: a platform (GitHub, Slack, Linear and the other native integrations) or an MCP server. Keys that tasks read as environment variables are task secrets, under **# Settings → (Credentials)**, not connections.
+
+## Workspace or personal
+
+Every connection has one scope. Its token decides whose name its actions carry; the platform sets that, not Coder.
+- **Workspace:** the workspace's own identity. On a platform, the agent's installed app; on an MCP server, the account an admin connected it with. Every turn gets it.
+- **Personal:** one member's own account. Only that member's turns get it, and its first use in a task asks them to approve.
+
+For workspace Acme, agent Coder, and member Ada:
+
+| | Workspace | Ada's personal |
+|---|---|---|
+| Slack | `slack`: Coder's bot. Reads the channels it's in, can't search, posts as Coder. | `slack-user`: Ada's account. Searches everything Ada can see; acts as Ada. |
+| GitHub | `github-acme`: the app's installation on `acme`. Comments as `coder-cloud-ai[bot]`. | `github-user`: Ada's sign-in. A pull request shows Ada as its author. |
+| Linear | `linear-acme`: the app. "My issues" are the app's. | `linear-user`: Ada's sign-in. "My issues" are hers. |
+| Notion (MCP) | `notion`: a Notion MCP token from Acme's workspace owner. | `notion-user`: Ada's own Notion sign-in. |
+
+- A platform's workspace side is the installed app, managed under **# Agents → *agent* → (Platforms)**. Members add only personal platform connections.
+- An MCP server can be workspace, personal, or both. An admin adds a workspace one; each member adds their own.
+- Another member's turns get the workspace servers and their own, never Ada's.
+- Every member sees every connection's name, scope, owner and status, never its secret.
+
+## In a task
+
+Each turn's tool search lists the servers that turn can use, each with its scope, and each call names its server. Workspace is the default. A personal server is for acting as the person, or for what only their account reaches, such as Slack search. Without one, the agent replies with that person's `connection/add` link. A message from anyone else during a turn ends the personal access until the owner's next turn.
+
+The agent's Connections setting and `coder task run --connections` narrow the list. Access is Auto (default) or Read-only; the strictest of the connection's, the agent's and the task's applies, and Read-only keeps only the tools a server marks read-only.
+
+## Statuses
+
+- `connected`: works.
+- `needs-auth`: its owner signs in or reconnects in the dashboard; the result carries the link.
+- `disabled`: exists, but this agent isn't granted it.
+- `failed`: the server didn't start this turn.
+
+## Adding one
+
+- **Thread:** the agent replies with a filled-in link.
+- **Dashboard:** **# Settings → (Connections) → [Add connection]**.
+- **CLI:**
+
+```sh
+coder connection add github --server                                              # a member's own GitHub
+coder connection add notion --url https://mcp.notion.com/mcp --server              # workspace MCP server (admins)
+coder connection add notion --personal --url https://mcp.notion.com/mcp --server   # a member's own
+coder connection add docs -- npx -y docs-mcp                                      # stdio server: the command after --
+```
+
+- A remote server's sign-in is detected: OAuth (needs `--server`), open access, or a key. A key is read from stdin or a prompt, or with `--key`, into `--header` (default `Authorization`) or, for a stdio server, `--env`. `--auth` overrides the detection.
+- `--access read-only` keeps only read-only tools; a read-only stdio server needs `--tools a,b`.
+
+## MCP servers in config
+
+An `mcp` entry in `.coder/config.json` or `~/.coder/config.json` is a server a task attaches by name with `--mcp`; nothing attaches unless asked. Entries use the `.mcp.json` shape of Claude Code, Cursor and Codex, plus `tools` and `description`. The repo's entry wins on a name. Coder itself as an MCP server in a host: [In your local harness](../README.md#in-your-local-harness).
+
+```json
+{
+  "mcp": {
+    "docs": { "command": "npx", "args": ["-y", "docs-mcp"], "tools": ["search"] },
+    "sentry": { "command": "npx", "args": ["-y", "@sentry/mcp-server"], "env": { "SENTRY_TOKEN": "${SENTRY_TOKEN}" } }
+  }
+}
+```
+
+| Key | Purpose |
+|---|---|
+| `command`, `args`, `env` | Stdio server to start |
+| `url`, `headers` | Remote server, streamable HTTP |
+| `tools` | Allowed tool names; omit for all |
+| `description` | What the server is for |
+
+- A repository's servers need local approval: `coder connection approve <name>`.
+- `${VAR}` and `${VAR:-default}` expand from the environment, except in a repository remote entry's URL and headers; use a connection for credentials.
+- `--mcp` takes names, `all` (also the engine's own MCP servers), or inline JSON: `coder run --mcp '[{"name":"tmp","command":"node","args":["server.js"]}]' "…"`.

package/docs/dash.md

@@ -1,8 +1,14 @@
+---
+description: The dashboard's pages and what each manages; coder dash runs it locally.
+---
+
 # Dashboard
 
 The dashboard is Coder's web UI at `/dash`, which opens the current workspace at `/dash/<workspace>`. `coder dash` runs it on this machine as a UI over the CLI's own config, agents and tasks, with no account and no database.
 
-To self-host your own Coder in the cloud, see [Self-hosting](self-host.md). There the same dashboard serves a workspace.
+Self-hosted Coder serves the same dashboard per workspace; see [Self-host](self-host.md).
+
+Paths name what to click: **# Page** in the sidebar, **(Tab)**, **[Button]**. **# Settings → (Models)** opens the Models tab of Settings.
 
 `coder dash` is short for `coder server serve`:
 
@@ -14,47 +20,45 @@ coder dash --port 3100
 ## Sign-in
 
 - **Local**: `coder dash` prints a dashboard link that carries its admin token (`/dash#token=…`), new on each start unless `ADMIN_TOKEN` is set. The dashboard answers only on `localhost`, `127.0.0.1` and `[::1]` at its port.
-- **Cloud**: members sign in with Wular Auth and switch workspaces from the menu. Members are managed in Wular Auth, and Settings links there.
+- **Cloud**: members sign in with Wular Auth and switch workspaces from the menu. Members are managed in Wular Auth, and **# Settings** links there.
 
 ## Pages
 
-**Agents**: agents from two sources. Give one its own app from its Platforms tab. Its Usage tab lists the platform events it failed to handle in the last day.
+**Agents**: agents from two sources; `coder agent list` lists them. Give one its own app from **# Agents → *agent* → (Platforms)**; its **(Usage)** lists the platform events it failed to handle in the last day.
 
-- **Dashboard agents** are made in the editor.
+- **Dashboard agents** are made in the editor, **# Agents → [New agent]**.
   - **Local**: saved in `~/.coder/agents/<id>/`.
   - **Cloud**: kept in the workspace; every change is a new version.
-- **Repository agents** come from a repo's `.coder/agents/<id>/`.
+- **Repository agents** come from a repo's `.coder/agents/<id>/`, which `coder agent init` scaffolds.
   - **Local**: read from the repo the server runs in; edits are written back there.
   - **Cloud**: imported from GitHub on each push to the repo's branch, through the agent's app.
 
-**Tasks**: start, watch, steer, ask, stop, approve and continue tasks, and run flows and reviews. On a local server a task can run in any folder on the machine; recent folders are offered first. Repository… clones an https or ssh git URL with the machine's own git logins into `~/.coder/checkouts` and runs the task there.
+**Tasks**: start, watch, steer, ask, stop, approve and continue tasks, and run flows and reviews from **[New task]**; `coder task` does the same. On a local server a task can run in any folder on the machine; recent folders are offered first. **[Repository…]** clones an https or ssh git URL with the machine's own git logins into `~/.coder/checkouts` and runs the task there.
 
 - **Local**: every task on this machine, including those started with `coder task run`.
-- **Cloud**: the workspace's tasks, from the dashboard, `coder task run --server` and platform events.
+- **Cloud**: the workspace's tasks, from the dashboard, `coder task run --server` and platform events. A task from a 1:1 DM shows only to its requester and to owners and admins. Its requester steers it; admins can view, stop and delete it.
 
-Local dashboard tasks open as soon as their worker starts. If the engine then fails to start, the task shows the failure and its output. `coder task run` still waits for startup and tries the next engine in its chain.
+Local dashboard tasks open as soon as their worker starts. If the engine then fails to start, the task shows the failure and its output. `coder task run` still waits for startup and tries the next model in its chain.
 
 Archiving hides a task from the default list. A running task keeps running, and steering an archived task brings it back.
 
-**Usage**: tasks, runner time and tokens per day, and the top agents.
+**Usage**: tasks, runner time and tokens per day, and the top agents; `coder agent usage --server` in a terminal.
 
 **Settings**: what every task runs with.
 
+- **Connections**: one row per service, its workspace side and the member's own: platform apps and sign-ins, and MCP servers, as `coder connection add` adds them.
 - **Credentials**: the engine logins tasks run with.
-  - **Local**: this machine's `claude` and `codex` logins, with Sign in and Sign out running each CLI's own commands here.
-  - **Cloud**: encrypted personal and workspace [credentials](self-host.md#credentials).
-- **Engines**, **Models** and **MCP**: engine defaults, models and MCP servers.
+  - **Local**: this machine's `claude` and `codex` logins, with **[Sign in]** and **[Sign out]** running each CLI's own commands here.
+  - **Cloud**: encrypted personal and workspace [credentials](self-host.md#credentials), as `coder credentials add` adds them.
+- **Models**: the chain and the review model, each a model and an effort, then aliases and custom models.
   - **Local**: the user config, as `coder config` and `coder model` edit it.
   - **Cloud**: the workspace's config, which a repo's own `.coder/config.json` can only narrow.
-- **Runners**: where tasks run, each with its own engine logins.
+- **Runners**: where tasks run, each with its own engine logins; `coder runner add` adds one.
   - **Local**: this machine.
-  - **Cloud**: the server's default runner plus the [runners](self-host.md#runners) you add. Personal runners are yours; workspace runners need an owner or admin. Secrets are encrypted.
-
-Add a runner from the catalog in Settings → Runners. Your own machine pairs with one command, `coder runner serve --url <server> --token <token>`, behind a public HTTPS tunnel (`--runner-url`). The token lasts 15 minutes and works once. A paired machine calls home every minute and shows offline after five without one. Local and Docker kinds exist only on a local server.
-
-A task runs on the runner it names, else its agent's runner, your default, the workspace default, then the server's own.
+  - **Cloud**: the server's default runner plus the [runners](runners.md) members add. Workspace runners need an owner or admin. Secrets are encrypted.
+- **Advanced**: the network: hosts tasks reach without review, and whether read-only tasks reach them too.
 
-For GitHub Actions, save `coder server workflow` as `.github/workflows/coder-agent.yml` and select that file in the runner form. Its worker command is `coder agent run --task`; the task result comes back through the server callback. Job logs appear after GitHub archives them when the job finishes. For Vercel Sandbox, supply the team and project IDs, or set `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID` on the server. Sandbox logs stream while the task runs. See [runner setup](self-host.md#runners) for authentication and workflow inputs.
+Adding runners, pairing a member's machine and which runner a task uses: [Runners](runners.md).
 
 ## Platform events
 

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`, `system`, `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 `{ findings, summary }`.
 
-`--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`.