@wular/coder 0.4.13 → 0.5.0

package/docs/cli/model.md

@@ -7,18 +7,18 @@ manage models: built-ins, aliases, custom endpoints
 Manage the models coder can dispatch to. `add` connects any OpenAI-compatible
 endpoint (Ollama, vLLM, OpenRouter, ...) as the custom engine, alongside the
 built-in codex/claude models. Name your own shortcuts with `alias`
-(e.g. fast -> codex:luna); disable/enable turns any model off and on.
+(e.g. fast -> codex/luna); disable/enable turns any model off and on.
 
-## `model list [--json] [--cwd <cwd>]`
+## `model list [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 list built-ins, custom models, and aliases
 
 List built-in aliases, configured custom models, and user aliases. Only custom
-models are probed.
-
-Use luna or sonnet for mechanical work; sol or opus is the default.
-Use astra or fable for the hardest work; they cost the most.
+models on this machine are probed; --server lists the workspace's.
 
+- `--server <server>` act on the Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
 - `--cwd <cwd>` workspace directory; default current
 
@@ -28,7 +28,7 @@ connect a model
 
 Connect a custom model behind an OpenAI-compatible endpoint (Ollama, LM Studio,
 vLLM, OpenRouter, ...). It currently runs on the codex engine pointed at your
-URL and is usable anywhere a model is: --model <name>, --engine custom, or as an
+URL and is usable anywhere a model is: --model <name> or --model custom/<name>, or as an
 agent default in config. Alias: `coder model setup`.
 
 - `<name>` the name to dispatch it by
@@ -95,13 +95,13 @@ re-enable a disabled model
 
 ## `model alias [name] [spec] [--workspace] [--json] [--cwd <cwd>]`
 
-name a spec, e.g. fast codex:luna
+name a spec, e.g. fast codex/luna
 
-Save an alias for an engine spec, e.g. fast -> codex:luna. An alias may reuse a
-built-in name to override it.
+Save an alias for an engine spec, e.g. fast -> codex/luna. An alias may reuse a
+built-in name to override it; an engine name sets what that bare engine runs.
 
 - `<name>` the alias
-- `<spec>` the engine spec, such as codex:luna
+- `<spec>` the engine spec, such as codex/luna
 - `--workspace` target <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
 - `--cwd <cwd>` workspace directory; default current

package/docs/cli/task.md

@@ -4,12 +4,12 @@
 
 run, follow and steer coding tasks
 
-## `task run [prompt] [--output-schema <output-schema>] [--name <name>] [--agent <agent>] [--append-system <append-system>] [--wait] [--engine <engine>] [--model <model>] [--effort <effort>] [--permissions <permissions>] [--mcp <mcp>] [--connections <connections>] [--add-dir <add-dir>] [--server <server>] [--workspace <workspace>] [--yes] [--background] [--repo <repo>] [--runner <runner>] [--json] [--cwd <cwd>]`
+## `task run [prompt] [--output-schema <output-schema>] [--name <name>] [--agent <agent>] [--append-system <append-system>] [--wait] [--model <model>] [--access <access>] [--mcp <mcp>] [--connections <connections>] [--add-dir <add-dir>] [--server <server>] [--workspace <workspace>] [--yes] [--repo <repo>] [--runner <runner>] [--json] [--cwd <cwd>]`
 
 run a task (background; --wait blocks)
 
 Dispatch a coding task to the configured engine. Backgrounds by default and
-prints a task id; --wait runs in the foreground and prints the answer.
+prints a task id locally or with --server; --wait follows it to the answer.
 Shortcut: `coder run "<text>"`.
 
 Writing a task: one task per focused goal, independent goals as parallel runs.
@@ -21,26 +21,26 @@ Waiting: run `coder task result <task-id> --wait` in its own background shell, o
 per task. Never wait on several tasks in one call, or their approvals and answers
 never reach you one by one.
 
-Use luna or sonnet for mechanical work; sol or opus is the default.
-Use astra or fable for the hardest work; they cost the most.
+Recommended, unless the user prefers otherwise or a model is unavailable:
+- sol or opus by default
+- luna or sonnet for mechanical work
+- opus for public APIs, SDKs and UI design
+- astra or fable for the hardest work; they cost the most
 
 - `<prompt>` the task text
 - `--output-schema <output-schema>` JSON Schema for the task answer
 - `--name <name>` label the task (shown in list/result)
 - `--agent <agent>` run as that agent: its system.md, engine settings, MCP servers and flows; flags override them
 - `--append-system <append-system>` standing instructions appended to Coder's system prompt (kept out of prompt previews)
-- `--wait` run in the foreground and block until the answer is ready
-- `--engine <engine>` engine to use; custom runs your configured custom models (default: first in the chain)
-- `--model <model>` luna/sol/astra (codex) · sonnet/opus/fable (claude) · a custom model (coder model list)
-- `--effort <effort>` reasoning effort
-- `--permissions <permissions>` read-only · workspace-write · auto (default: auto)
+- `--wait` follow the task until the answer is ready
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high)
+- `--access <access>` read-only also restricts platforms and connections; auto lets the engine review what leaves the sandbox (default: auto)
 - `--mcp <mcp>` attach MCP servers from `mcp` in .coder/config.json by name (or all), or an inline JSON array [{"name","command","args","env","tools"}]; none by default, all adds your engine's own MCP servers
 - `--connections <connections>` use only these connections (coder connection list), within the agent's
-- `--add-dir <add-dir>` give the task another directory beyond --cwd (repeatable); read-only can only read it, other modes can also write
-- `--server <server>` run the task on your Coder server and follow it here (--background prints its id)
+- `--add-dir <add-dir>` give the task another directory beyond --cwd (repeatable); read-only can only read it, auto can also write
+- `--server <server>` run the task on your Coder server and print its id (--wait follows it)
 - `--workspace <workspace>` with --server: the workspace to run in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
-- `--background` with --server: print the task id instead of following it
 - `--repo <repo>` with --server: check out a repo from the workspace's installs
 - `--runner <runner>` with --server: where it runs (a runner kind or a registered runner)
 - `--json` JSON output
@@ -77,7 +77,7 @@ move to --archived. Shortcut: `coder list`.
 - `--limit <limit>` tasks per page (default: 50; all for every task)
 - `--cursor <cursor>` continue from the previous page cursor
 - `--dir <dir>` only tasks launched in that workspace
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -102,7 +102,7 @@ tasks in one call, or their approvals and answers never reach you one by one.
 - `--wait` block until the task finishes or needs an approval, then print
 - `--turns` every turn's answer (a steered task accretes turns)
 - `--tail <tail>` include the last n progress-log steps (default: 0, final result only)
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -136,7 +136,7 @@ following, and `next`: the command that continues it while the task runs.
 - `--tail <tail>` replay the last n log lines first (default: 1)
 - `--trim <trim>` budget for tool output and thinking (default: 1200 chars, 12 lines)
 - `--from <from>` return the log from event n on instead of following it
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -147,22 +147,21 @@ coder task watch  # follow the most recent task to completion
 coder task watch <task-id> --from 0 --json  # the log so far, and the command that continues it
 ```
 
-## `task steer [task-id] [text] [--wait] [--model <model>] [--effort <effort>] [--permissions <permissions>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+## `task steer [task-id] [text] [--wait] [--model <model>] [--access <access>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 continue a task's thread
 
 Continue a task's thread with new instructions. They are injected into a live Codex or
 Claude turn at its next tool boundary and queued across a startup or completion race.
 A stopped, finished, or archived task resumes on the same task id. It reuses the
-task's engine, model, and permissions unless overridden.
+task's engine, model, and access unless overridden.
 
 - `<task-id>` the task to continue
 - `<text>` the follow-up instructions
 - `--wait` run in the foreground and block until the answer is ready
-- `--model <model>` override the task's model for this follow-up
-- `--effort <effort>` override the task's reasoning effort
-- `--permissions <permissions>` read-only · workspace-write · auto
-- `--server <server>` act on your Coder server
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high) for this follow-up
+- `--access <access>` lower the task's access for this follow-up
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -172,7 +171,7 @@ task's engine, model, and permissions unless overridden.
 coder task steer task-abc "now add tests"  # continue that task with a follow-up
 ```
 
-## `task ask [task-id] [question] [--model <model>] [--effort <effort>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+## `task ask [task-id] [question] [--model <model>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 ask about a task without interrupting it
 
@@ -183,9 +182,8 @@ running or stopped. To change what the task does, use `coder task steer`.
 
 - `<task-id>` the task to ask about
 - `<question>` the question
-- `--model <model>` sidecar model (default: the task's own)
-- `--effort <effort>` sidecar reasoning effort
-- `--server <server>` act on your Coder server
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high) for the sidecar (default: the task's own)
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -202,7 +200,7 @@ interrupt a running task
 Interrupt a running task and mark it cancelled.
 
 - `<task-id>` the task to stop
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -219,7 +217,7 @@ brings it back.
 
 - `<task-id>` the task to archive
 - `--all-stopped` archive every stopped (finished) task
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -234,7 +232,7 @@ delete every archived task at once. A running task must be stopped first.
 
 - `<task-id>` the task to delete
 - `--all-archived` delete every archived task
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -248,7 +246,7 @@ List pending approvals across all tasks, --denied the denied ones (still answera
 
 - `<task-id>` one task (default: approvals of every task)
 - `--denied` denied approvals instead of pending ones
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output
@@ -266,7 +264,7 @@ Approval ids are unique, so the task id is optional.
 - `<approval-id>` the approval to answer
 - `--deny` reject the request instead of accepting
 - `--reason <reason>` why it is denied; the task reads it
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the Coder server
 - `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
 - `--yes` with --server: connect to a server used for the first time without asking
 - `--json` JSON output

package/docs/config.md

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

package/docs/connections.md

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

package/docs/dash.md

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