@wular/coder 0.4.13 → 0.5.0

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?)` - one page, `{ items, next? }`; pass `next` as `cursor`                                                                                                                                                                                                                                    |
-| `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).

package/docs/self-host.md

@@ -1,6 +1,10 @@
+---
+description: Running a Coder server with its database, sign-in, apps and runners.
+---
+
 # Self-hosting
 
-Run your own instance of the Coder server. A server holds the agents and their platform apps, every task with its output, and the dashboard. Platforms deliver events to it, runners report back to it, and the CLI and SDK reach it with `--server`. The hosted service at `coder.wular.ai` is the default.
+A self-hosted Coder server holds the agents and their platform apps, every task with its output, and the dashboard. Platforms deliver events to it, runners report back to it, and the CLI and SDK reach it with `--server`. The hosted service at `coder.wular.ai` is the default.
 
 ## Deploy
 
@@ -8,42 +12,42 @@ One server, one database, any number of agents, running on Bun. The server is co
 
 Required variables carry a *.
 
-| Variable                                   | Type                                                                       | Default                                         | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PUBLIC_URL`<sup><b>*</b></sup>            | url without a path                                                         |                                                 | The address platforms and browsers reach the server at. Written into every app as its webhook and callback address, and the only origin sign-in trusts. Inferred on Vercel; `serve` defaults to `http://localhost:<port>`                                                                                                                                                                                                                           |
-| `DATABASE_URL` or `POSTGRES_URL`           | url                                                                        |                                                 | Postgres. Everything lives in a `coder` schema, so the database can be shared with other apps. Run the database setup command below before the first start and after upgrades. Without it `coder server serve` runs the local dashboard; `--memory` selects a throwaway test server. Statements are prepared on each connection, so a query costs one round trip; add `?prepare=false` to the URL for a pooler that cannot keep prepared statements |
-| `SERVER_ENCRYPTION_KEY`<sup><b>*</b></sup> | base64 32 bytes                                                            |                                                 | Encrypts app keys, tokens, and engine credentials at rest (`openssl rand -base64 32`), and derives the session cookie key and the sign-in client key with HKDF. Required with Postgres                                                                                                                                                                                                                                                              |
-| `AUTH_WULAR_URL`                           | url                                                                        | `https://auth.wular.ai`                         | Wular Auth OpenID issuer, the only identity provider, including for a self-hosted Wular Auth deployment                                                                                                                                                                                                                                                                                                                                             |
-| `RUNNER`                                   | `local`\| `local-docker` \| `vercel-sandbox` \| `github-actions` \| `http` | `local`, `vercel-sandbox` on Vercel             | Where tasks execute. `local` and `local-docker` run them on the server's own machine and work with the memory store, and are refused on Vercel. The other three run them elsewhere and need Postgres. Members' own machines add to this ([Your own machine](#your-own-machine))                                                                                                                                                                     |
-| `RUNNER_CONFIG`                            | JSON                                                                       | `{}`                                            | Options for the chosen runner ([Runners](#runners)). Required for `http` and `github-actions`                                                                                                                                                                                                                                                                                                                                                       |
-| `SERVER_ENCRYPTION_KEY_PREVIOUS`           | base64 32 bytes                                                            |                                                 | The old key, accepted until `coder server rotate-key` has re-sealed everything. While set, its sign-in key stays published and its session cookies still open, so rotation keeps everyone signed in                                                                                                                                                                                                                                                 |
-| `PORT`                                     | number                                                                     | `8787`, or the port of a localhost `PUBLIC_URL` | Listen port                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `HOST`                                     | address                                                                    | `127.0.0.1` without a database, else all        | Listen address. A local server listens on loopback only ([Modes](#modes))                                                                                                                                                                                                                                                                                                                                                                           |
-| `ADMIN_TOKEN`                              | string                                                                     | minted and printed per run                      | Local and memory servers. The bearer the CLI and dashboard use, accepted from loopback only. Ignored with Postgres                                                                                                                                                                                                                                                                                                                                  |
-| `CODER_CACHE_HOME`                         | path                                                                       | OS cache directory for `wular-coder`            | Archived tasks, flows and usage                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `WORK_DIR`                                 | path                                                                       | `~/.coder/state/global/server-tasks`            | Where the local runner keeps each task's work folder: its working directory, or its checkout with a repository. The folder stays across turns and goes with `task delete`                                                                                                                                                                                                                                                                           |
-| `SERVER_NAME`                              | string                                                                     | `Coder`                                         | What the dashboard calls this server, in its sidebar server menu                                                                                                                                                                                                                                                                                                                                                                                    |
-| `ISSUES_URL`                               | URL                                                                        | `https://github.com/muzam1l/coder/issues/new`   | Where the dashboard sends bug reports from its Report issue button                                                                                                                                                                                                                                                                                                                                                                                  |
-| `SERVER_LIMITS`                            | JSON                                                                       | `{}`                                            | Request rates and task slots ([Limits and monitoring](#limits-and-monitoring))                                                                                                                                                                                                                                                                                                                                                                      |
-| `CLAUDE_SUBSCRIPTIONS`                     | `1`                                                                        | off                                             | Offer "Sign in with Claude" for personal credentials                                                                                                                                                                                                                                                                                                                                                                                                |
-| `CODEX_SUBSCRIPTIONS`                      | `1`                                                                        | off                                             | Offer "Sign in with Codex" for personal credentials                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `MAX_TASKS`                                | number                                                                     | unset                                           | Optional deployment-wide runner slot cap, in addition to `limits.concurrentTasks`                                                                                                                                                                                                                                                                                                                                                                   |
-| `MAX_QUEUED`                               | number                                                                     | `1000`                                          | Tasks a workspace may have waiting                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `TASK_TIMEOUT`                             | ms                                                                         | `1800000` (30 minutes)                          | Longest a task may run                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `TASK_STALL`                               | ms                                                                         | `300000` (5 minutes)                            | Silence before the runner is asked whether the task is still alive                                                                                                                                                                                                                                                                                                                                                                                  |
-| `TASK_ATTEMPTS`                            | number                                                                     | `2`                                             | Times a runner start is retried                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `SERVER_INTEGRATIONS`                      | comma-separated ids                                                        | every platform                                  | The platforms this server offers, from `github`, `slack` and `linear`. Others get no webhook, catalog entry or app creation. An unknown id stops the server                                                                                                                                                                                                                                                                                         |
-| `SERVER_OPERATORS`                         | comma-separated Wular Auth user ids                                        | none                                            | Postgres servers. Who may open the operator area. Only this variable grants it                                                                                                                                                                                                                                                                                                                                                                      |
+| Variable | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `PUBLIC_URL`<sup><b>*</b></sup> | url without a path |  | The address platforms and browsers reach the server at. Written into every app as its webhook and callback address, and the only origin sign-in trusts. Inferred on Vercel; `serve` defaults to `http://localhost:<port>` |
+| `DATABASE_URL` or `POSTGRES_URL` | url |  | Postgres. Everything lives in a `coder` schema, so the database can be shared with other apps. Run the database setup command below before the first start and after upgrades. Without it `coder server serve` runs the local dashboard; `--memory` selects a throwaway test server. Statements are prepared on each connection, so a query costs one round trip; add `?prepare=false` to the URL for a pooler that cannot keep prepared statements |
+| `SERVER_ENCRYPTION_KEY`<sup><b>*</b></sup> | base64 32 bytes |  | Encrypts app keys, tokens, and engine credentials at rest (`openssl rand -base64 32`), and derives the session cookie key and the sign-in client key with HKDF. Required with Postgres |
+| `AUTH_WULAR_URL` | url | `https://auth.wular.ai` | Wular Auth OpenID issuer, the only identity provider, including for a self-hosted Wular Auth deployment |
+| `RUNNER` | `local` \| `local-docker` \| `vercel-sandbox` \| `github-actions` \| `http` | `local`, `vercel-sandbox` on Vercel | Where tasks execute. `local` and `local-docker` run them on the server's own machine and work with the memory store, and are refused on Vercel. The other three run them elsewhere and need Postgres. Members' own machines add to this ([Runners](runners.md)) |
+| `RUNNER_CONFIG` | JSON | `{}` | Options for the chosen runner ([Runners](#runners)). Required for `http` and `github-actions` |
+| `SERVER_ENCRYPTION_KEY_PREVIOUS` | base64 32 bytes |  | The old key, accepted until `coder server rotate-key` has re-sealed everything. While set, its sign-in key stays published and its session cookies still open, so rotation keeps everyone signed in |
+| `PORT` | number | `8787`, or the port of a localhost `PUBLIC_URL` | Listen port |
+| `HOST` | address | `127.0.0.1` without a database, else all | Listen address. A local server listens on loopback only ([Modes](#modes)) |
+| `ADMIN_TOKEN` | string | minted and printed per run | Local and memory servers. The bearer the CLI and dashboard use, accepted from loopback only. Ignored with Postgres |
+| `CODER_CACHE_HOME` | path | OS cache directory for `wular-coder` | Archived tasks, flows and usage |
+| `WORK_DIR` | path | `~/.coder/state/global/server-tasks` | Where the local runner keeps each task's work folder: its working directory, or its checkout with a repository. The folder stays across turns and goes with `task delete` |
+| `SERVER_NAME` | string | `Coder` | What the dashboard calls this server, in its sidebar server menu |
+| `ISSUES_URL` | URL | `https://github.com/muzam1l/coder/issues/new` | Where the dashboard sends bug reports from its Report issue button |
+| `SERVER_LIMITS` | JSON | `{}` | Request rates and task slots ([Limits and monitoring](#limits-and-monitoring)) |
+| `CLAUDE_SUBSCRIPTIONS` | `1` | off | Offer **[Sign in with Claude]** for personal credentials |
+| `CODEX_SUBSCRIPTIONS` | `1` | off | Offer **[Sign in with Codex]** for personal credentials |
+| `MAX_TASKS` | number | unset | Optional deployment-wide runner slot cap, in addition to `limits.concurrentTasks` |
+| `MAX_QUEUED` | number | `1000` | Tasks a workspace may have waiting |
+| `TASK_TIMEOUT` | ms | `1800000` (30 minutes) | Longest a task may run |
+| `TASK_STALL` | ms | `300000` (5 minutes) | Silence before the runner is asked whether the task is still alive |
+| `TASK_ATTEMPTS` | number | `2` | Times a runner start is retried |
+| `SERVER_INTEGRATIONS` | comma-separated ids | every platform | The platforms this server offers, from `github`, `slack` and `linear`. Others get no webhook, catalog entry or app creation. An unknown id stops the server |
+| `SERVER_OPERATORS` | comma-separated Wular Auth user ids | none | Postgres servers. Who may open the operator area. Only this variable grants it |
 
 Settings, sign-in, pairings and live tasks live in ~/.coder (CODER_HOME). Archived tasks, flows and usage live in the OS cache directory, ~/Library/Caches/wular-coder on macOS, ~/.cache/wular-coder on Linux (CODER_CACHE_HOME overrides). Nothing is ever pruned.
 
 ### Modes
 
-| Started with   | Mode                                                                                   |
-| -------------- | -------------------------------------------------------------------------------------- |
-| `DATABASE_URL` | Cloud: sign-in with Wular Auth, workspaces, Postgres                                   |
-| `--memory`     | Test server: everything in memory, the admin token, and a "not for production" warning |
-| neither        | Local: the [dashboard](dash.md) for this machine's CLI, on loopback only               |
+| Started with | Mode |
+| --- | --- |
+| `DATABASE_URL` | Cloud: sign-in with Wular Auth, workspaces, Postgres |
+| `--memory` | Test server: everything in memory, the admin token, and a "not for production" warning |
+| neither | Local: the [dashboard](dash.md) for this machine's CLI, on loopback only |
 
 A memory server refuses to start on Vercel. Without a database, a connection from another machine reaches only the platform endpoints (`/hooks/`, `/create/`, `/install/`, `/connect/`), so `--host 0.0.0.0` lets platforms reach a memory server directly while the dashboard and `/admin` stay on this machine.
 
@@ -74,7 +78,7 @@ Completed tasks, their logs and usage remain until a task is explicitly deleted.
 
 Before the first start and each upgrade, set `DATABASE_URL` and run `npx --yes --package=drizzle-kit@0.31.11 --package=drizzle-orm@0.45.2 --package=postgres@3.4.9 drizzle-kit push --config=./node_modules/@wular/coder/dist/schema.config.js` from the directory where Coder is installed. Run it as a deploy step for serverless hosts.
 
-### Your own host
+### A plain host
 
 Install Bun and `@wular/coder`, set the variables above, set up the database as above, then run `coder server serve`. The command starts the server under Bun, listens on `PORT` (default 8787), and answers `/health`. Keep it alive with whatever supervises processes on that host. It listens on every interface, as containers and load balancers need; behind a proxy on the same machine, `--host 127.0.0.1` keeps it private. From code, `server.serve()` and `server.rotateKey()` do the same.
 
@@ -84,13 +88,13 @@ Open `PUBLIC_URL` and sign in with Wular Auth. Workspaces and roles come from Wu
 
 Add an engine [credential](#credentials), or the first task will only reply with a link asking for one.
 
-Create the built-in agent's apps once per server with `coder server app create <integration>`, such as `github` or `linear`, run where the server's `DATABASE_URL` and `PUBLIC_URL` are set. Each opens a one-time page that posts the app's manifest to the platform; `--org <org>` creates the GitHub App under an organization you admin. These apps are public and shared by every workspace, and the app's credentials go straight to the server. Linear apps need public distribution turned on before other workspaces can add them.
+Create the built-in agent's apps once per server with `coder server app create <integration>`, such as `github` or `linear`, run where the server's `DATABASE_URL` and `PUBLIC_URL` are set. Each opens a one-time page that posts the app's manifest to the platform; `--org <org>` creates the GitHub App under an organization the caller administers. These apps are public and shared by every workspace, and the app's credentials go straight to the server. Linear apps need public distribution turned on before other workspaces can add them.
 
 ## Apps and installs
 
-An agent's handle on a platform is its app. The built-in agent `coder` uses shared apps on GitHub and Linear; create its Slack app in your workspace from its Platforms tab by pasting a Slack configuration refresh token. A custom agent gets its own app from its Platforms tab in the dashboard, under your own GitHub account or an organization whose apps you manage. Private apps install only on their owner; an app made public on its platform installs on any account.
+An agent's handle on a platform is its app. The built-in agent `coder` uses shared apps on GitHub and Linear; create its Slack app in the Slack workspace from **# Agents → coder → (Platforms)** by pasting a Slack configuration refresh token. A custom agent gets its own app from **# Agents → *agent* → (Platforms)** in the dashboard, under the member's own GitHub account or an organization whose apps they manage. Private apps install only on their owner; an app made public on its platform installs on any account.
 
-Installs start from the dashboard. "Connect GitHub" adds the shared GitHub app, and the Platforms tab creates or installs an agent's workspace app. The server binds an install to the workspace that started it with a one-time, expiring state. On GitHub it also requires the installer to authorize the app and checks that the installation appears in their own `GET /user/installations`; on Slack it uses "Add to Slack" OAuth keyed by team. An install started on GitHub asks the installer to sign in and binds only if they are a member of the app's workspace. An install belongs to exactly one workspace, and webhooks route by installation. Removing or suspending an install on the platform stops it.
+Installs start from the dashboard. **[Connect GitHub]** adds the shared GitHub app, and **# Agents → *agent* → (Platforms)** creates or installs an agent's workspace app. The server binds an install to the workspace that started it with a one-time, expiring state. On GitHub it also requires the installer to authorize the app and checks that the installation appears in their own `GET /user/installations`; on Slack it uses **[Add to Slack]** OAuth keyed by team. An install started on GitHub asks the installer to sign in and binds only if they are a member of the app's workspace. An install belongs to exactly one workspace, and webhooks route by installation. Removing or suspending an install on the platform stops it.
 
 Operators set up the shared apps in the dashboard's Operator area at `/dash/<workspace>/operator`, one per platform, named `SERVER_NAME` or Wular unless they pick a name, and every operator action lands in its audit log. Entering it asks for a fresh Wular Auth sign-in and lasts an hour, or 15 minutes without activity; on local and memory servers the admin token holder is the operator.
 
@@ -102,7 +106,7 @@ Credentials are subscriptions and API keys. A subscription is a member's own Cla
 
 Each engine uses its subscription, else its key (`ANTHROPIC_API_KEY` for Claude, `OPENAI_API_KEY` for Codex), the requester's own before the workspace's; a custom model uses the variable it names. Tasks with no known requester use the workspace's only, and without a credential the agent replies with a link to the Credentials page.
 
-From a terminal, `coder credentials` adds, lists, removes and signs in credentials; it reads secrets from the environment or stdin and never prints them.
+Manage them under **# Settings → (Credentials)** or with `coder credentials add`, `list`, `login` and `remove`, which read secrets from the environment or stdin and never print them.
 
 ## Tasks
 
@@ -110,42 +114,46 @@ A task starts from the dashboard, `coder task run --server`, or a platform event
 
 A task is a conversation: steer it or ask it a question while it runs, and continue it once it has finished. Its output streams over Server-Sent Events, and a repo task's result includes the diff of its changes. The CLI's task commands take `--server` to do the same as the dashboard. A repo's own `.coder/config.json` can only narrow the workspace's config.
 
+Only the requester of a 1:1 DM task and the workspace's owners and admins see it, in the dashboard, CLI, SDK and API. Its requester steers it, and admins can view, stop and delete it. When the requester hasn't connected that platform account, only admins see it.
+
 ## Sign-in and workspaces
 
 Wular Auth is the only identity provider. Coder is an OpenID Connect client with no accounts of its own and signs its requests with a key derived from `SERVER_ENCRYPTION_KEY`, so there is no client secret to register. Sessions refresh themselves as Wular Auth's tokens expire, and signing out also ends the Wular Auth session.
 
-Workspaces come from Wular Auth, where members and roles are managed; the members page links there. Wular Auth sends an account in no workspace through its onboarding before it signs them in to Coder. Apps, installations, tasks, and credentials all belong to the selected workspace. Every member may see and use everything in the workspace; only owners and admins change workspace credentials.
+Workspaces come from Wular Auth, where members and roles are managed; the members page links there. Wular Auth sends an account in no workspace through its onboarding before it signs them in to Coder. Apps, installations, tasks, and credentials all belong to the selected workspace. Every member may see and use everything in the workspace except another member's [DM tasks](#tasks); only owners and admins change workspace credentials.
 
 From a terminal, `coder auth login` signs in with Wular Auth (`--device` shows a code to approve elsewhere) and keeps the session in `~/.coder/session.json`. Its tokens are issued for this server only. `--workspace <slug>` picks a workspace and `--server <url>` another instance. Servers must use HTTPS unless they are loopback, and the CLI confirms a new origin the first time it sees it (`--yes` acknowledges it in scripts).
 
-A platform user who addresses an agent must be linked to a member of the workspace that owns the install, or trusted by the platform there, such as a GitHub user with write access to the repository; trusted users get the workspace's connections only. Anyone else gets a link the first time they ask: on Slack a private one-time link, on GitHub a link that signs them in with the app's own GitHub authorization, so no secret appears in a public comment. Write actions on GitHub also need the person's write access to the repository, checked with GitHub. Installing an app links the installer the same way. A trigger with `"actAs": "requester"` runs its tasks with the requester's own GitHub token, kept encrypted and refreshed.
+Anyone the platform lets write where they ask, such as a GitHub user with write access to the repository, starts and steers tasks. Installing an app connects the installer.
 
 ## Runners
 
+What members and admins do with runners, such as pairing their own machine and choosing defaults, is in [Runners](runners.md). This section is the operator's side.
+
 `RUNNER_CONFIG` is a JSON object read by the chosen runner. Every field is optional unless marked.
 
-| Runner           | Field               | Default                               | Purpose                                                                                                                           |
-| ---------------- | ------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `local`          |                     |                                       | none                                                                                                                              |
-| `local-docker`   | `image`             | `ghcr.io/muzam1l/coder-runner:latest` | Image the task runs in                                                                                                            |
-|                  | `memory`            | `4g`                                  | `--memory`                                                                                                                        |
-|                  | `cpus`              | `2`                                   | `--cpus`                                                                                                                          |
-|                  | `pidsLimit`         | `512`                                 | `--pids-limit`                                                                                                                    |
-|                  | `network`           | `bridge`                              | `--network`                                                                                                                       |
-| `vercel-sandbox` | `image`             | the SDK's default image               | Image the task starts from                                                                                                        |
-|                  | `token`             | deployment OIDC                       | Vercel access token for Sandbox; install `@vercel/sandbox` in the adapter app                                                     |
-|                  | `team`              | `VERCEL_TEAM_ID`                      | Team ID for access-token authentication                                                                                           |
-|                  | `projectId`         | `VERCEL_PROJECT_ID`                   | Project ID for access-token authentication                                                                                        |
-|                  | `region`            | the database's region                 | Sandbox region; inferred from an AWS region in the database host, else Vercel's default                                           |
-|                  | `timeoutMs`         | `1800000`                             | Sandbox lifetime                                                                                                                  |
-|                  | `vcpus`             | `1`                                   | Sandbox size                                                                                                                      |
-| `github-actions` | `token` (required)  |                                       | GitHub token that may dispatch the workflow and read its status                                                                   |
-|                  | `repo`              | the event's repository                | `owner/name` holding the workflow                                                                                                 |
-|                  | `workflow`          | `coder-agent.yml`                     | Workflow file to dispatch (`coder server workflow` prints it)                                                                     |
-|                  | `ref`               | the repository's default branch       | Branch to dispatch on                                                                                                             |
-| `http`           | `url` (required)    |                                       | Your controller's base URL; it implements `POST /start`, `POST /messages/<handle>`, `GET /status/<handle>`, `POST /stop/<handle>` |
-|                  | `secret` (required) |                                       | Shared secret that signs every request over body, timestamp, and nonce                                                            |
-|                  | `headers`           | `{}`                                  | Extra headers sent with every request                                                                                             |
+| Runner | Field | Default | Purpose |
+| --- | --- | --- | --- |
+| `local` |  |  | none |
+| `local-docker` | `image` | `ghcr.io/muzam1l/coder-runner:latest` | Image the task runs in |
+|  | `memory` | `4g` | `--memory` |
+|  | `cpus` | `2` | `--cpus` |
+|  | `pidsLimit` | `512` | `--pids-limit` |
+|  | `network` | `bridge` | `--network` |
+| `vercel-sandbox` | `image` | the SDK's default image | Image the task starts from |
+|  | `token` | deployment OIDC | Vercel access token for Sandbox; install `@vercel/sandbox` in the adapter app |
+|  | `team` | `VERCEL_TEAM_ID` | Team ID for access-token authentication |
+|  | `projectId` | `VERCEL_PROJECT_ID` | Project ID for access-token authentication |
+|  | `region` | the database's region | Sandbox region; inferred from an AWS region in the database host, else Vercel's default |
+|  | `timeoutMs` | `1800000` | Sandbox lifetime |
+|  | `vcpus` | `1` | Sandbox size |
+| `github-actions` | `token` (required) |  | GitHub token that may dispatch the workflow and read its status |
+|  | `repo` | the event's repository | `owner/name` holding the workflow |
+|  | `workflow` | `coder-agent.yml` | Workflow file to dispatch (`coder server workflow` prints it) |
+|  | `ref` | the repository's default branch | Branch to dispatch on |
+| `http` | `url` (required) |  | The controller's base URL; it implements `POST /start`, `POST /messages/<handle>`, `GET /status/<handle>`, `POST /stop/<handle>` |
+|  | `secret` (required) |  | Shared secret that signs every request over body, timestamp, and nonce |
+|  | `headers` | `{}` | Extra headers sent with every request |
 
 `local-docker` and `github-actions` run in the runner image, which holds the engines and tools. A custom `image` needs `node`, `bun`, `git`, `curl`, `tar`, `claude`, `codex` and `github-mcp-server`.
 
@@ -153,38 +161,28 @@ A platform user who addresses an agent must be linked to a member of the workspa
 
 On `vercel-sandbox` each task uses the universal image's engines without their own sandbox, and its machine stops when the task ends. Repository snapshots hold the checkout and its installed dependencies. The default is 1 CPU and 2 GB memory; `vcpus` selects a larger machine.
 
-Access-token authentication needs a token, team ID and project ID. Settings → Runners accepts the IDs directly, or the adapter app can supply `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID`. The firewall injects engine API keys into provider requests, and the task sees a placeholder. Below `auto`, a task's machine reaches only this server, its engine, integrations, connections, MCP servers and `allowedNetworkHosts`.
+Access-token authentication needs a token, team ID and project ID. **# Settings → (Runners)** accepts the IDs directly, or the adapter app can supply `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID`. The firewall injects engine API keys into provider requests, and the task sees a placeholder. Below `auto`, a task's machine reaches only this server, its engine, integrations, connections, MCP servers and `network.allowedHosts`.
 
 For GitHub Actions, save the output of `coder server workflow` as `.github/workflows/coder-agent.yml` on the workflow repository's default branch. Save it again after each Coder upgrade. It accepts `task`, `server`, `token`, `mode` and `tarball`, names each run `Coder agent <task ID>`, and runs the task in the runner image with the callback URL and attempt token in the environment. The workflow token needs repository Actions read and write; a classic token for a private repository needs `repo`. A result returns through the authenticated task callback. No result artifact is required.
 
 Every runner sends the task's log to the server while it runs, and the dashboard shows the stored log.
 
-The server stores steer, ask, approval and cancel messages before delivering them. Local workers receive them over a private Unix socket; HTTP controllers use the same signed requests as task starts, Docker uses the daemon's exec channel, and Vercel Sandbox uses `runCommand`. Workers acknowledge the applied sequence and save it across restarts. Unacknowledged messages retry on server events and the sweep, with backoff. A reconnect fetches pending messages once.
-
-A runner adapter declares delivery support through its optional `push` method. The start environment tells the worker which mode to use. GitHub Actions has no inbound delivery channel, so it checks every four seconds with one indexed query that returns immediately. Four seconds balances interactive response time and request volume. All workers send a separate heartbeat every 30 seconds; idle push workers make no message requests after reconnect.
-
-### Your own machine
-
-A member runs the server's tasks on their own machine with `coder runner serve`. It uses the machine's own `claude` and `codex` logins, so no credential is needed. Expose its port with any tunnel, such as `cloudflared tunnel --url http://localhost:4100`, `ngrok http 4100`, `tailscale funnel 4100` or a public VS Code port, and pass the tunnel's address with `--url`. Each start registers the current address with the server as you (`coder auth login`), and stopping marks the runner offline, so a changing tunnel address is fine. Every request to it is signed with its own secret, kept in `~/.coder/runners.json`. Each task keeps one work folder in `~/.coder/state/global/server-tasks/<task id>/work` across turns; deleting the task removes it at the runner's next registration, within a minute while it runs.
-
-A runner runs only its owner's tasks. An owner or admin can register one with `--workspace` for every member. A task runs on the runner it names, else its agent's runner, the requester's default, the workspace default, then `RUNNER`. Choose a default with `coder runner default <id>`. `coder runner list`, `rename` and `remove`, and the dashboard's Settings, manage them.
-
 ## Security
 
-The server only verifies, dedupes, and dispatches; agents run in the runner with one checkout, one short-lived platform token, and one engine credential. `permissions` is enforced by the engine sandbox, on `vercel-sandbox` by the machine and its firewall, `tools` by the app's permissions and the MCP allowlist. App credentials are encrypted at rest.
+The server only verifies, dedupes, and dispatches; agents run in the runner with one checkout, one short-lived platform token, and one engine credential. `access` is enforced by the engine sandbox, on `vercel-sandbox` by the machine and its firewall, `tools` by the app's permissions and the MCP allowlist. App credentials are encrypted at rest.
 
 ## Limits and monitoring
 
 `SERVER_LIMITS` is a JSON object stored under `limits` in the server config. Each value is a positive integer. Unset keys use these defaults.
 
-| Config key                  | Default | Purpose                                                                                                  |
-| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
-| `limits.principalPerMinute` | `300`   | Requests per minute for each signed-in user, the memory server's admin token, or an authenticated runner |
-| `limits.ipPerMinute`        | `60`    | Requests per minute for each unauthenticated IP                                                          |
-| `limits.authPerMinute`      | `20`    | Sign-in, token and login requests per minute for each IP, on top of `ipPerMinute`                        |
-| `limits.registerPerMinute`  | `10`    | Runner registrations per minute for each IP; includes pairing and returning-runner heartbeats            |
-| `limits.pairingPerMinute`   | `5`     | Pairing tokens per minute for each principal at `/admin/runners/pair`                                    |
-| `limits.concurrentTasks`    | `10`    | Active task slots per workspace in cloud mode, or per server in local and memory modes                   |
+| Config key | Default | Purpose |
+| --- | --- | --- |
+| `limits.principalPerMinute` | `300` | Requests per minute for each signed-in user, the memory server's admin token, or an authenticated runner |
+| `limits.ipPerMinute` | `60` | Requests per minute for each unauthenticated IP |
+| `limits.authPerMinute` | `20` | Sign-in, token and login requests per minute for each IP, on top of `ipPerMinute` |
+| `limits.registerPerMinute` | `10` | Runner registrations per minute for each IP; includes pairing and returning-runner heartbeats |
+| `limits.pairingPerMinute` | `5` | Pairing tokens per minute for each principal at `/admin/runners/pair` |
+| `limits.concurrentTasks` | `10` | Active task slots per workspace in cloud mode, or per server in local and memory modes |
 
 For example, `SERVER_LIMITS='{"principalPerMinute":300,"ipPerMinute":60,"authPerMinute":20,"registerPerMinute":10,"pairingPerMinute":5,"concurrentTasks":10}'` sets every default explicitly. All `/admin/*`, `/runners/*`, sign-in and pairing requests use the same token-bucket implementation. A bucket starts full and refills continuously over a minute. A refused request returns `429`, a readable JSON `error` and `Retry-After` in seconds. Buckets and counters belong to each server process and reset on restart; serverless instances keep their own buckets.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wular/coder",
-  "version": "0.4.13",
-  "description": "Delegating coding-agent runtime",
+  "version": "0.5.0",
+  "description": "The runtime for agents, your rules, any model, everywhere.",
   "type": "module",
   "main": "./dist/sdk.js",
   "types": "./dist/sdk.d.ts",
@@ -34,7 +34,7 @@
     "version-bump:patch": "node scripts/bump.mjs patch",
     "version-bump:minor": "node scripts/bump.mjs minor",
     "version-bump:major": "node scripts/bump.mjs major",
-    "format": "prettier --write \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" \"*.md\" \"docs/**/*.md\""
+    "format": "prettier --write \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" \"*.md\""
   },
   "files": [
     "bin",
@@ -70,14 +70,13 @@
     "@types/node": "^26.1.2",
     "@wular/pnext": "0.1.9",
     "chat": "4.41.1",
-    "contextjsx": "0.2.3",
+    "contextjsx": "0.2.6",
     "drizzle-kit": "0.31.11",
     "drizzle-orm": "0.45.2",
     "jose": "6.2.12",
     "openid-client": "6.8.8",
     "postgres": "3.4.9",
     "preact": "10.29.2",
-    "preact-render-to-string": "6.7.0",
     "prettier": "^3.6.2",
     "tsdown": "^0.22.13",
     "typescript": "^5.9.3",

package/plugins/agents/skills/coder/SKILL.md

@@ -13,7 +13,7 @@ You dispatch coding tasks through the `coder` runtime instead of implementing th
 
 ## Overview
 
-Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible or local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant. Every task runs sandboxed under unified permissions (read-only, workspace-write, auto), is steerable mid-run, and falls back down the configured chain when an engine cannot start.
+Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible or local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant. Every task runs sandboxed under one access setting (read-only or auto), is steerable mid-run, and falls back down the configured chain when an engine cannot start.
 
 ## Setup
 
@@ -21,7 +21,7 @@ If `coder` is not on PATH, install it yourself without asking: `npm install -g @
 
 ## Use Coder over MCP
 
-Each coder command is also an MCP tool with the same arguments, such as `task/run` or `flow/run`; `load_skill` loads a guide.
+Each coder command is also an MCP tool with the same arguments, such as `task/run` or `flow/run`; `load_skill` loads a doc.
 
 Setup: `coder setup-host` adds the server. By hand:
 
@@ -35,7 +35,7 @@ Restart running sessions after adding it.
 ## Using the CLI
 
 - The CLI is the reference. `coder --help` and every subcommand's `--help` list the flags and exit codes, and each command prints the recommended next step when it returns. Follow it.
-- `coder docs` lists the deeper guides; `coder docs <topic>` prints one.
+- `coder docs` lists the docs; `coder docs <topic>` prints one.
 - Wait on each task with `coder task result <task-id> --wait` in its own background shell, one per task, never several tasks in one call, so each approval and answer reaches you.
 - If your harness sandboxes or gates terminal commands (Codex does both), run every `coder` command with escalated permissions; the runtime is a supervisor with its own sandbox and approval policy.
 

package/plugins/claude/skills/dispatch/SKILL.md

@@ -13,7 +13,7 @@ You dispatch coding tasks through the `coder` runtime instead of implementing th
 
 ## Overview
 
-Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible or local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant. Every task runs sandboxed under unified permissions (read-only, workspace-write, auto), is steerable mid-run, and falls back down the configured chain when an engine cannot start.
+Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible or local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant. Every task runs sandboxed under one access setting (read-only or auto), is steerable mid-run, and falls back down the configured chain when an engine cannot start.
 
 ## Setup
 
@@ -21,7 +21,7 @@ If `coder` is not on PATH, install it yourself without asking: `npm install -g @
 
 ## Use Coder over MCP
 
-Each coder command is also an MCP tool with the same arguments, such as `task/run` or `flow/run`; `load_skill` loads a guide.
+Each coder command is also an MCP tool with the same arguments, such as `task/run` or `flow/run`; `load_skill` loads a doc.
 
 Setup: `coder setup-host` adds the server. By hand:
 
@@ -35,7 +35,7 @@ Restart running sessions after adding it.
 ## Using the CLI
 
 - The CLI is the reference. `coder --help` and every subcommand's `--help` list the flags and exit codes, and each command prints the recommended next step when it returns. Follow it.
-- `coder docs` lists the deeper guides; `coder docs <topic>` prints one.
+- `coder docs` lists the docs; `coder docs <topic>` prints one.
 - Run each `coder task result <task-id> --wait` as its own background Bash call (run_in_background), one per task, never several tasks in one call, so each approval and answer re-invokes you.
 
 ## Running tasks

package/plugins/cursor/README.md

@@ -13,7 +13,7 @@
 - **Clean context.** Your conversation stays about intent and orchestration; implementation details live in the subagents.
 - **Fast dispatch.** Handoffs are instant, and light enough to spin up a large number of subagents at once.
 - **Steerable tasks.** Full visibility into every task, from live progress to mid-run course corrections.
-- **Unified permissions.** Three modes across all engines: _Read-only_, _Workspace-write_, and _Auto_.
+- **One access setting.** _Auto_ or _Read-only_, the same on every engine.
 
 ## Get started
 
@@ -58,8 +58,8 @@ Machine defaults live in `~/.coder/config.json`; a `coder.config.json` in a repo
 {
   "chain": ["codex", "claude"],
   "engines": {
-    "codex": { "model": "sol", "effort": "high", "permissions": "auto" },
-    "claude": { "model": "opus", "effort": "medium", "permissions": "auto" }
+    "codex": { "model": "sol", "effort": "high" },
+    "claude": { "model": "opus", "effort": "medium" }
   },
   "models": {
     "qwen": { "baseUrl": "http://localhost:11434/v1", "model": "qwen2.5-coder:32b" }