@wular/coder 0.4.12 → 0.5.0

package/docs/models.md

@@ -1,97 +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                            |
-| `--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`, or `/review <pr>` in the dashboard's **# Tasks → [New task]**, 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.
 
 ```sh
 coder review                         # local changes since the default branch
@@ -10,21 +14,20 @@ 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 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 |
+| `--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`.
 
@@ -42,4 +45,4 @@ The command exits `0` when the review completes, even with findings, `1` when th
 
 ## 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`, 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.

package/docs/sdk.md

@@ -1,74 +1,61 @@
+---
+description: The @wular/coder SDK, every CLI command as a typed function.
+---
+
 # SDK
 
-Everything the CLI does, as a library. The SDK mirrors the CLI exactly: every command group is a namespace, every subcommand a function, with the same names and the same options (`coder --help` is the reference for both). TypeScript users install `zod` alongside it for the schema types.
+The SDK is the CLI as a library: the same commands, names and options. `coder --help` is the reference for both.
+
+## Rules
+
+- **Names.** A command group is a namespace and a subcommand a function: `coder task steer` is `task.steer`, `coder model alias` is `model.alias`. Top-level commands are functions: `setupHost`, `upgrade`, `docs`. Exceptions:
+  - `task watch` is `task.stream`, an async iterable of progress events.
+  - `connection rm` is `connection.remove`.
+  - `review` is `review.run`.
+  - `server rotate-key` is `server.rotateKey`.
+  - `agent run --task` is `agent.runTask`, for runners, not application code.
+- **Arguments.** Positional arguments come first, in CLI order. Flags become one options object in camelCase: `--max-tasks` is `maxTasks`, `--output-schema` is `outputSchema`.
+- **Models.** `model` takes the same spec as `--model`: `sol`, `sol/low`, `claude/opus` or `codex/gpt-6.1-sol/high`.
+- **Server.** Every command that takes `--server` accepts `{ server: true | url, organization?, token?, yes? }`:
+  - `server` falls back to `CODER_SERVER`, then the hosted service.
+  - `organization` is the workspace slug and overrides the saved one.
+  - Authentication comes from `auth.login()` or `token`.
+  - `yes: true` accepts a new server origin in non-interactive code.
+- **Results.** Functions never print and never call `process.exit`. Results are typed values. `task.list` returns one page, `{ items, next? }`; pass `next` back as `cursor`.
+- **Errors.** Failures throw `CoderError`, whose `code` says what went wrong:
+  - `'chain-exhausted'`: every engine failed to start. It carries the fallback payload and `fallback.instructions`, and is the CLI's exit code 3.
+  - `'approval-pending'`: carries the approval to answer.
+  - `'login-failed'`.
+  - `'server'`: carries the HTTP `status`.
+  - The option errors the CLI reports.
+- **Hosting.** `server.handler(env)` serves Coder on serverless hosts; see [Self-host](self-host.md#deploy).
+
+## Examples
+
+A task with a JSON answer, then its result:
 
 ```ts
 import coder from '@wular/coder';
-// or pick namespaces: import { task, flow, model, config, auth, agent, server } from '@wular/coder';
 
-const { taskId } = await coder.task.run('Explain this repo', {
-  model: 'sol',
+const { taskId } = await coder.task.run('List the API routes', {
+  model: 'claude/opus',
+  outputSchema: { type: 'object', properties: { routes: { type: 'array' } } },
 });
-
 const res = await coder.task.result(taskId, { wait: true });
-
-console.log(res.result?.finalMessage);
 ```
 
-`task.run(prompt, { outputSchema })` takes a JSON Schema for the answer; the CLI takes the same JSON with `coder task run --output-schema '<schema>' "<prompt>"`. The schema is sent to the engine natively (Codex, Claude, custom endpoints) and never written into the stored prompt; only an endpoint that rejects schemas gets it as prompt text. A continuation keeps the task's schema unless given a new one.
-
-SDK functions never print and never call `process.exit`; results come back as typed values and failures as a typed `CoderError` whose `code` says what went wrong. The case the CLI maps to exit code 3 (every engine in the chain failed to start) is `code: 'chain-exhausted'`, carrying the same fallback payload and its self-contained `fallback.instructions`; a task blocked on a permission is `'approval-pending'`, carrying the approval to answer.
-
-## CLI to SDK mapping
-
-| CLI                                                                                    | SDK                                                                                                                                                                                                                                                   |
-| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `coder run "<text>"`                                                                   | `task.run(prompt, opts?)`; `connections` narrows the task's connections                                                                                                                                                                              |
-| `coder list`                                                                           | `task.list(opts?)`                                                                                                                                                                                                                                    |
-| `coder result [id] [--wait] [--tail N] [--turns]`                                      | `task.result(id?, { wait?, tail? })` - returns `turns` (one entry per finished turn) alongside `result`                                                                                                                                               |
-| `coder task steer <id> "<text>"`                                                       | `task.steer(id, text, { model?, effort?, permissions?, wait? })` - live, or resumes a finished or archived task on the same id                                                                                                                        |
-| `coder task ask <id> "<question>"`                                                     | `task.ask(id, question, { model?, effort? })` - read-only sidecar answer; the task's thread is never touched                                                                                                                                          |
-| `coder task stop <id>`                                                                 | `task.stop(id)`                                                                                                                                                                                                                                       |
-| `coder task watch [id] [--tail N]`                                                     | `task.stream(id?, { tail? })` - async iterable of progress events                                                                                                                                                                                     |
-| `coder task approvals [id]`                                                            | `task.approvals(id?)`                                                                                                                                                                                                                                 |
-| `coder task approve <id> <appr>`                                                       | `task.approve(id, approvalId, { deny? })`                                                                                                                                                                                                             |
-| `coder task archive / delete <id>`                                                     | `task.archive(id)` / `task.delete(id)`                                                                                                                                                                                                                |
-| `coder flow run / list / discover / result / watch / stop / resume / archive / delete` | the matching `flow.*` function; `flow.run(nameOrPath, { args?, concurrency?, maxTasks? })`, `flow.stream(id?)` for `watch`                                                                                                                            |
-| `coder model add / update / remove / list / alias / unalias / disable / enable`        | the matching `model.*` function                                                                                                                                                                                                                       |
-| `coder config get / set`                                                               | `config.get(key?)` / `config.set(key, value)`                                                                                                                                                                                                         |
-| `coder connection add / list / rm / reconnect / approve`                               | `connection.add(name, { env?, url?, command?, key?, askKey?, header?, access?, me?, credential?, onAuthorize?, server? })` / `connection.list()` / `connection.remove(name)` / `connection.reconnect(name, { key?, askKey?, onAuthorize? })` / `connection.approve(name, { agent? })`, all with `{ server? }` |
-| `coder setup-host [hosts...]`                                                          | `setupHost(hosts?)`                                                                                                                                                                                                                                   |
-| `coder upgrade`                                                                        | `upgrade({ cliOnly?, pluginsOnly? })`                                                                                                                                                                                                                 |
-| `coder docs [topic]`                                                                   | `docs(topic?)`                                                                                                                                                                                                                                        |
-| `coder review [--base] [--head] [--pr] [--since] [--post]`                             | `review.run({ base?, head?, pr?, since?, post?, engine?, model?, effort? })` - returns `{ findings, summary, runId }`                                                                                                                                 |
-| `coder auth login [--server] [--workspace] [--device] [--yes]`                         | `auth.login({ server?, organization?, device?, yes?, onCode?, open?, save? })` - the same Wular Auth sign-in; `open` gets the browser URL, `device` switches to the code flow; pass the workspace slug as `organization` when the account has several |
-| `coder auth logout / status`                                                           | `auth.logout({ server? })` / `auth.status()` - the saved sessions, never their tokens                                                                                                                                                                 |
-| `coder task <verb> --server [url]`                                                     | every `task.*` above with `{ server: true \| url, organization?, token?, yes? }` - acts on your server's tasks instead of local tasks                                                                                                                 |
-| `coder agent list / show <id> / init [id] / push [id]`                                 | `agent.list({ server? })` / `agent.show(id, { server? })` / `agent.init(id)` / `agent.push(id?, { cwd?, server? })`                                                                                                                                  |
-| `coder agent integrations list / show <id>`                                            | `agent.integrations.list()` / `agent.integrations.show(id)`                                                                                                                                                                                           |
-| `coder agent run <agent> <event.json> [--server]`                                      | `agent.run(agent, event, { server?, wait?, flow?, cwd? })` - local, tools off; with `server`, a real task                                                                                                                                             |
-| `coder agent run --task <id>`                                                          | `agent.runTask(id, options?)` - the runner form, not for application code                                                                                                                                                                             |
-| `coder credentials list / add / remove`                                                | `credentials.list()` / `.add({ env, value?, workspace?, noCheck? })` / `.remove(name, { workspace? })`, all with `{ server? }`                                                                                                                       |
-| `coder agent usage [--since] [--by]`                                                   | `agent.usage({ since?, by?, server?, cwd? })`                                                                                                                                                                                                         |
-| `coder server serve / rotate-key`                                                                        | `server.serve(options?)` / `server.rotateKey(options?)`; `server.handler(env)` for serverless hosts, see [Self-hosting](self-host.md#deploy)                                                                                                                                                                                                                 |
-
-Options objects take the same names as the CLI flags, camelCased (`--max-tasks` becomes `maxTasks`, `--server` becomes `server`). Every server option accepts `organization`, the `--workspace` flag's slug, which overrides the saved workspace for that call. `server` falls back to `CODER_SERVER`, then the hosted service; authentication comes from `auth.login()`, or from `token` when supplied; `yes: true` acknowledges the first use of a new server origin in non-interactive code.
+The schema goes to the engine natively and never into the stored prompt. A continuation keeps it unless given a new one.
 
-## Examples
-
-Dispatch a wave and wait for all of it:
+A wave of read-only tasks:
 
-```js
+```ts
 import { task } from '@wular/coder';
 
-const ids = await Promise.all(areas.map(a => task.run(`Audit ${a}`, { permissions: 'read-only' })));
-
+const ids = await Promise.all(areas.map(a => task.run(`Audit ${a}`, { access: 'read-only' })));
 const results = await Promise.all(ids.map(({ taskId }) => task.result(taskId, { wait: true })));
 ```
 
-Follow a task live. Every event carries a `kind` such as `assistant`, `reasoning`,
-`tool`, `tool-result`, `usage`, `status`, `steer`, or `error`, plus the fields
-that kind implies (`tool`, `exitCode`, `durationMs`, `tokens`):
+Following a task live. Each event has a `kind`, such as `assistant`, `tool`, `usage` or `error`:
 
 ```ts
 for await (const event of task.stream(taskId)) {
@@ -76,29 +63,18 @@ for await (const event of task.stream(taskId)) {
 }
 ```
 
-Run a flow from your own tooling:
+A task on the Coder server:
 
 ```ts
-import { flow } from '@wular/coder';
-
-const run = await flow.run('fix-tests', { args: { files } });
-console.log(run.result, run.tokens);
+await task.steer(id, 'Also cover the retry path', { server: true });
 ```
 
-If you need a wave with gates, journaling, and resume, write a [flow](flows.md) instead of hand-rolling it on `task.*`; the flow runtime is exactly this SDK plus those services.
-
-## Errors
-
-`CoderError.code` says what went wrong: `'chain-exhausted'` (every engine failed to start, with the fallback payload and `fallback.instructions`), `'approval-pending'` (the approval to answer), `'login-failed'`, `'server'` (with the HTTP `status` the server answered), and the option errors the CLI reports the same way.
-
-## Runners
-
-`runner.list(options?)` returns `{ items, catalog }`. Each catalog spec describes a kind, its fields and whether this server can offer it. Rows contain a personal or workspace scope, an effective default, presence and non-secret config. Secret fields are sealed in storage and never returned.
+A flow:
 
-Use `runner.add({ kind, name, scope, config }, options?)` to connect an HTTP, GitHub Actions, Vercel Sandbox or local Docker runner. `runner.update(id, { name?, default?, config? }, options?)` updates it, preserving omitted secret fields. `runner.default(id, options?)` makes it the default within its scope. `runner.test(id, options?)` returns `{ ok, detail, ms }` within five seconds, and `runner.remove(id, options?)` removes a record. The built-in server runner cannot be renamed or removed.
-
-`runner.pair({ name?, scope }, options?)` returns a single-use token valid for 15 minutes and a `coder runner serve --url <server> --token <token>` command. Expose the runner port through a tunnel and set `CODER_RUNNER_URL` to that tunnel's HTTPS address, or add `--runner-url <address>`. The pairing fixes the member and workspace that own the resulting HTTP record. The runner generates and saves its own signing secret, calls home every minute, and marks itself offline on shutdown. Serving without a token still registers through the signed-in member's client.
+```ts
+import { flow } from '@wular/coder';
 
-Tasks choose a named runner first, then the agent definition's `runner`, the requester's default, the workspace default and the built-in server default. Explicit names must resolve to a visible record or the built-in ID. Local kinds are available only on a local server, and Docker also requires its executable on PATH. Vercel access-token runners use the server's `VERCEL_PROJECT_ID` and, when no team field is provided, `VERCEL_TEAM_ID` for the SDK's project context.
+const run = await flow.run('fix-tests', { args: { files } });
+```
 
-The matching CLI commands are `coder runner add <kind>`, `list`, `default <id>`, `test <id>` and `remove <id>`. Repeat `--field key=value` when adding a runner. Secret fields use an environment reference such as `--field token=env:GITHUB_TOKEN`. `--scope` accepts `personal` or `workspace`; a workspace record requires an owner or admin. `coder runner add local` prints a pairing command.
+For gates, journaling and resume, write a [flow](flows.md) instead of looping over `task.*`. Runners are in [Runners](runners.md).