@wular/coder 0.4.13 → 0.5.1

package/docs/agents/coder.md

@@ -1,10 +1,14 @@
+---
+description: The built-in coder agent, its install links and its shared apps.
+---
+
 # The `coder` agent
 
 The built-in agent. On the hosted service it has an install link per platform; self-hosters create its shared apps once per server with `coder server app create <integration>` ([Self-hosting](../self-host.md#after-the-first-start)). Tune or disable it under `agents.coder` in `.coder/config.json` ([Usage](index.md#usage)).
 
 ## On GitHub
 
-- A pull request opening, updating, or becoming ready runs the [review flow](../review.md) read-only and posts inline comments with a sticky summary. Reruns update the summary and never repeat a finding, and a new push replaces a review that has not started yet.
+- A pull request opening, updating, or becoming ready gets a read-only [review](../review.md) through the agent's `review` tool, posted as one GitHub review with inline comments. Reruns never repeat a finding.
 - A review request for the agent does the same.
 - A mention (`@<app>` from a repository owner or member), in the conversation or in a finding's thread, answers from the diff and the repository, or makes the requested change on a branch and links the pull request.
 - An issue opening or edit reads the issue and the repository, then answers, makes the change and links the pull request, or asks one clarifying question.

package/docs/agents/index.md

@@ -1,36 +1,35 @@
-# Agents
-
-An agent is a reusable teammate. Its `system.md` holds the standing instructions every task starts from: who it is, what it knows, how it answers. Its definition adds engine, model, effort and permissions defaults, the MCP servers it attaches and the [flows](../flows.md) it may run. Run it from the CLI with `coder task run --agent <id> "…"`, where flags override the defaults, from the [dashboard](../dash.md), or from platform events like a Slack DM or a GitHub pull request.
+---
+description: Agents, their system.md and agent.json, platform apps, events and settings.
+---
 
-Connected to a platform, an agent listens for the events it names. Each event runs as a task with the agent's instructions, the event as its request, and the platform tools of every installation of the agent's apps; a GitHub event also checks out its repository, and any task can clone the agent's GitHub repositories. The reply goes back to the thread. Later messages in that conversation, from anyone, steer its task while it runs and resume it once it has finished. A bigger task can run a flow instead, with the event as its `args`.
+# Agents
 
-On each platform an agent is its own app, a GitHub App or a Slack app for example, so it has its own handle and permissions and runs only where it is installed. Agents run on a Coder server: the hosted one, [your own](../self-host.md), or this machine's [dashboard](../dash.md).
+An agent is a reusable teammate. Its `system.md` holds the instructions every task starts from. Its definition adds a default model and MCP servers. It runs from the CLI (`coder task run --agent <id> "…"`, flags override the defaults), from the [dashboard](../dash.md), or from platform events such as a Slack DM or a GitHub pull request.
 
-## Connections
+On each platform an agent is its own app, such as a GitHub App or a Slack app, with its own handle and permissions, and it runs only where installed.
+- Each event it listens for runs as a task with the agent's instructions, the event as the request, and the platform tools of every installation of its apps.
+- A GitHub event also checks out its repository.
+- The reply goes back to the thread.
+- Later messages in that conversation, from anyone, steer the task while it runs and resume it once it has finished.
 
-A connection gives tasks access to an MCP service, your own account on an integration, or an API key passed as one environment variable, such as `GROQ_API_KEY`. Add one under Settings → Connections or with `coder connection add`; an API key is kept as a credential, so rotating the credential rotates the connection. Tasks started by members receive workspace connections and that member’s own connections, narrowed by the agent’s Connections setting and `coder task run --connections`; outsider events receive none. A connection's access is Default, which follows the agent's, Read-only or Read-write. Read-only gives the engine only the tools the server marks read-only.
+Agents run on a Coder server: the hosted one, a [self-hosted](../self-host.md) one, or this machine's [dashboard](../dash.md). Tasks get the workspace's [connections](../connections.md), narrowed by the agent's Connections setting.
 
 ## Built-in agent
 
-[`coder`](coder.md) answers engineering questions, reviews pull requests, and makes requested changes. It is on by default wherever its apps are installed; tune or disable it under `agents.coder` in `.coder/config.json` ([Usage](#usage)).
-
-## Your own agents
+[`coder`](coder.md) answers engineering questions, reviews pull requests and makes requested changes. It's on wherever its apps are installed; tune or disable it under `agents.coder` ([Usage](#usage)).
 
-An agent comes from one of two sources:
+## Defining an agent
 
-- **Dashboard**: made in the agent editor on the [dashboard](../dash.md).
-- **Repository**: `coder agent init` scaffolds one, asking its id, platforms, events and access. It is a folder `.coder/agents/<id>/` with an `agent.json` and a `system.md`. A folder in `$CODER_HOME/agents/<id>/` (default `~/.coder/agents`) is yours in every repo, and a repo's folder of the same id wins.
+- **Dashboard:** **# Agents → [New agent]**.
+- **Repository:** `coder agent init` scaffolds `.coder/agents/<id>/` with an `agent.json` and a `system.md`. A folder in `$CODER_HOME/agents/<id>/` (default `~/.coder/agents`) applies in every repo, and a repo's folder of the same id wins.
 
-Here is a helper that answers in Slack and on GitHub issues:
-
-`.coder/agents/helper/agent.json`
+`.coder/agents/helper/agent.json`:
 
 ```json
 {
   "name": "Helper",
   "description": "Answers engineering questions about acme/app.",
-  "permissions": "read-only",
-  "access": "read",
+  "access": "read-only",
   "integrations": {
     "slack": { "events": { "mention": true, "channel": { "match": "^help\\b" } } },
     "github": { "events": ["mention"] }
@@ -38,89 +37,61 @@ Here is a helper that answers in Slack and on GitHub issues:
 }
 ```
 
-`.coder/agents/helper/system.md`
+`.coder/agents/helper/system.md`:
 
 ```md
 You answer questions about acme/app from its source. Cite file paths.
-If asked to change code, describe the change and stop; never promise a PR.
 ```
 
-From there:
-
-1. Get the agent to a server. A local server reads it from the repo on disk. A cloud server imports it from the dashboard and again on each push to the agents repo once the agent's GitHub App is installed there; `coder agent push` uploads it without a repo.
-2. On the dashboard, the agent's Platforms tab creates its app on each platform it uses and installs it; the app's credentials go straight to the server. An app is private, installable only by its owner, or public where the platform allows it (GitHub, Linear), installable by any account. An install started on the platform signs the installer in to Coder and binds to the app's workspace when they are a member.
-3. Events now reach the server, a task runs on its runner, and the reply is posted back. `coder agent run helper <event.json> --server --wait` fires one by hand; without `--server` it runs offline, platform tools off, reply printed. `--server` means `CODER_SERVER`, else the hosted service; give it a URL to pick another.
-
-Only pushes to the agents repo's configured branch are imported, and each changed definition becomes a new version. An app created before push events existed needs the `push` event enabled once in its GitHub App settings.
-
-### Definition
+Then:
+1. **Get it to a server.** A local server reads the repo. A cloud server imports it from the dashboard, then on each push to the agents repo's branch once its GitHub App is installed there, as a new version. `coder agent push` uploads it without a repo.
+2. **Install it.** **# Agents → *agent* → (Platforms)** creates and installs its app on each platform. An app is private, or public where the platform allows it (GitHub, Linear). An install started on the platform signs the installer in to Coder, and binds to the app's workspace when they're a member.
+3. **Try it.** `coder agent run helper <event.json> --server --wait` fires one event. Without `--server` it runs offline, with platform tools off.
 
-`agent.json`. The folder name is the id; the built-in id `coder` is reserved.
+| Key | Values | Purpose |
+| --- | --- | --- |
+| `name`, `description` | Text | App name and handle; the description joins the prompt |
+| `model` | A [model spec](../models.md#pick-a-model) | Default model |
+| `integrations.<id>.events` | A list of [events](#integrations), or a map of event → `true` or `{ "match" }` | `match` is a regex the event text must pass |
+| `access` | `read-only`, or `auto` (default) | Its tasks, platforms, connections and app permissions; a task, flow or connection can only lower it |
+| `mcp` | MCP servers in the [`.mcp.json` shape](../connections.md#mcp-servers-in-config) | Servers every task of the agent attaches |
 
-| Key                         | Values                                                                                                                                                                                                  | Purpose                                                                                                                                                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`, `description`       | Text                                                                                                                                                                                                    | App name and handle; the description is added to the prompt                                                                                                                                                                |
-| `engine`, `model`, `effort` | As in `coder task run`                                                                                                                                                                                  | Engine defaults                                                                                                                                                                                                            |
-| `permissions`               | `auto` (default), `workspace-write`, `read-only`                                                                                                                                                        | Sandbox mode inside the checkout, also for the tasks its [flows](../flows.md) start; only `auto` asks a person ([escalations](../access.md#escalations))                                                                   |
-| `integrations.<id>.events`  | Event names from the [integration](#integrations): a list, or a map of event → `true`, a flow name (repo `.coder/flows` or built-in such as `review`), or `{ "flow", "match", "permissions", "actAs" }` | A list or `true` runs the agent, a flow name runs that flow, `match` is a regex the event text must pass, `permissions` overrides the agent's for this event, `"actAs": "requester"` uses the requester's own GitHub token |
-| `access`                    | `read` (Read-only) or `write` (Read-write, default)                                                                                                                                                     | What it may do on its platforms and connections; also its apps' permissions                                                                                                                                                |
-| `mcp`                       | A map of MCP servers in the `.mcp.json` entry shape, as in [MCP](../mcp.md)                                                                                                                             | Servers every task of the agent attaches                                                                                                                                                                                   |
+The folder name is the id; `coder` is reserved.
 
 ## Usage
 
-How a repo runs an agent goes under `agents` in its `.coder/config.json` ([Configuration](../config.md)), one entry per agent id. No entry or `true` runs the agent as defined, `false` disables it, an object overrides it:
+A repo's `.coder/config.json` sets how it runs each agent under `agents`. No entry or `true` runs it as defined, `false` disables it, and an object overrides it:
 
 ```json
-{
-  "agents": {
-    "coder": { "model": "sol" },
-    "helper": { "integrations": { "slack": { "allowedEvents": ["mention"] } } }
-  }
-}
+{ "agents": { "coder": { "model": "sol" }, "helper": { "integrations": { "slack": { "allowedEvents": ["mention"] } } } } }
 ```
 
-| Key                                        | Values             | Purpose                                                            |
-| ------------------------------------------ | ------------------ | ------------------------------------------------------------------ |
-| `engine`, `model`, `effort`, `permissions` | As above           | Override the definition                                            |
-| `connections`                              | Connection id list | Narrow `agents.<id>.connections`; omit for all granted connections |
-| `access`                                   | `read`             | Lower the definition's access to Read-only                         |
-| `integrations.<id>.allowedEvents`          | Event names        | Cap the definition's events; omit to allow all it asks for         |
-| `disabled`                                 | `true`             | Disable the agent and keep its other settings                      |
-
-Unknown ids, integrations, events, and keys fail validation. Usage is read from the repo the event came from.
+| Key | Purpose |
+| --- | --- |
+| `model` | Replace the definition's model |
+| `connections` | Narrow the connections; omit for all granted |
+| `access` | `read-only` lowers it |
+| `integrations.<id>.allowedEvents` | Cap the definition's events |
+| `disabled` | `true` disables it and keeps its settings |
 
-Disable or Enable any agent, built-in ones included, in its Settings › Manage in the dashboard. A disabled agent answers no platform events and starts no tasks in that workspace; its apps, versions, settings and past tasks stay, and other workspaces are unaffected.
-
-## CLI
-
-| Command                                                             | Purpose                                                                |
-| ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `coder agent list [--server [url]]`                                 | List agents, with active versions on a server                          |
-| `coder agent show <id> [--server [url]]`                            | One agent in full: settings, access, integrations, events              |
-| `coder agent init [id]`                                             | Scaffold an agent folder; interactive without flags                    |
-| `coder agent push [id] [--server [url]]`                            | Upload one agent, or all of them, without a source repo                |
-| `coder agent run <agent> <event.json> [--server [url] [--wait]]`    | Run a recorded event through an agent, on a server or offline          |
-| `coder agent usage [--since 7d] [--by agent\|installation\|engine]` | Aggregate usage of this machine's tasks, or a server's with `--server` |
-| `coder agent integrations <list\|show <id>>`                        | Integrations with their events and tool presets                        |
-| `coder task run --agent <id> "…"`                                   | Run an agent's definition locally; flags override it                   |
+Unknown ids, integrations, events and keys fail validation. Usage comes from the repo the event came from. **# Agents → *agent* → (Settings) → (Manage) → [Disable]** stops any agent, built-in ones included, in that workspace only. Commands: [`coder agent`](../cli/agent.md).
 
 ## Integrations
 
-An integration gives an agent two things:
-
-1. **Chat.** The agent's own app on the platform. Its events start tasks, and the reply goes back to the same thread. Linked workspace members can address an agent, and so can anyone the platform lets write there (on GitHub, write access to the repository); they get the workspace's connections only.
-2. **Platform tools.** Actions beyond replying, through each platform's MCP server, one per installation of the agent's apps. They run outside the agent's sandbox, with a token for that installation in the agent's access mode; the agent can read that token during its turn. Read-only exposes only tools the platform server marks read-only; Read-write exposes all its tools. The prompt lists the servers; the engine loads a server's tools when it needs them. Replies, reactions and history work in both modes.
-
-| Platform | App                                                                                                                         | Events                                        | Tools                                                                                                         |
-| -------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| GitHub   | A [GitHub App](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) per agent      | `mention`, `pull_request`, `issue`, `comment` | GitHub's [MCP server](https://github.com/github/github-mcp-server); `read` runs it read-only                  |
-| Slack    | A [Slack app](https://api.slack.com/reference/manifests) per agent                                                          | `mention`, `dm`, `channel`, `command`         | [Slack MCP server](https://github.com/korotovsky/slack-mcp-server), pinned to v1.3.0 with SHA256 verification |
-| Linear   | Your [Linear OAuth app](https://linear.app/developers/agents), with webhooks to `<PUBLIC_URL>/hooks/linear?app=<client id>` | `mention`: an agent session                   | [Official Linear MCP server](https://linear.app/docs/mcp) at `https://mcp.linear.app/mcp`                     |
+An integration gives an agent two things on a platform:
 
-On Slack, `dm` takes every message in direct and group DMs with the agent, and `channel` every message in channels it is in, up to Slack's 30,000 events per workspace per app per hour. A Slack app's Home tab shows the agent and how to use it, and links to this server's tasks and agents unfurl into a short card.
+- **Chat:** the agent's own app. Its events start tasks, one per issue, pull request or Slack thread, and each reply goes to the thread that asked. Anyone the platform lets write there can address it (on GitHub, write access to the repository).
+- **Platform tools:** each platform's MCP server, one per installation, outside the agent's sandbox, at the agent's access. Read-only exposes only the tools the server marks read-only. Who they act as: [Connections](../connections.md#workspace-or-personal).
 
-When an agent's app needs other events, permissions or settings, publishing the agent brings it up to date. Coder updates a Slack app itself and lists the changes to make on GitHub and Linear, and **Update on <platform>** in the handle's menu on the Platforms tab does the same later.
+| Platform | App | Events | Workspace | Personal |
+| --- | --- | --- | --- | --- |
+| GitHub | A GitHub App per agent | `mention`, `pull_request`, `issue`, `comment` | [`github-mcp-server`](https://github.com/github/github-mcp-server) on the installation token | The same, on the person's token |
+| Slack | A Slack app per agent | `mention`, `dm`, `channel`, `command` | [Slack MCP Server](https://github.com/korotovsky/slack-mcp-server) on the bot token: the bot's channels, no search | [Slack MCP](https://docs.slack.dev/ai/slack-mcp-server) on the person's token, with search |
+| Linear | A Linear OAuth app, webhooks to `<PUBLIC_URL>/hooks/linear?app=<client id>` | `mention`, `issue`, `comment` | [Linear's MCP](https://linear.app/docs/mcp) on the app's token | The same, on the person's token |
 
-`coder agent integrations show <id>` lists each event and each preset's exact tools or scopes. A host turns platforms off with `SERVER_INTEGRATIONS` ([Self-hosting](../self-host.md)).
+- **Slack:** `dm` takes every message in direct and group DMs, and `channel` every message in the agent's channels, up to Slack's 30,000 events per workspace per app per hour.
+- **Linear:** `mention` takes a comment naming `@<app>`, `issue` issues people create or change, and `comment` every other comment by a person; replies go in the asking comment's thread. All need Issues and Comments ticked in the app's webhook settings.
+- **Slack:** the app's Home tab shows the agent and how to use it, and links to this server's tasks and agents unfurl into a short card.
+- **Every platform:** an edited message counts like a new one, unless it already started or steered a turn. A message the agent must answer gets 👀 until the first reply.
 
-Need another integration or a missing event or tool? [Open an issue](https://github.com/muzam1l/coder/issues).
+Publishing an agent updates its apps' events and permissions: Coder updates a Slack app itself, and lists the changes for GitHub and Linear (**[Update on *platform*]** later). `coder agent integrations show <id>` lists each event's and preset's tools. A host limits the platforms it offers with `SERVER_INTEGRATIONS` ([Self-host](../self-host.md)).

package/docs/approvals.md

@@ -0,0 +1,47 @@
+---
+description: Access levels, approvals in the CLI and in threads, who sees a task, and the sandbox.
+---
+
+# Approvals
+
+Tasks, agents and connections run `auto` (default) or `read-only`. An `auto` task changes code and uses every tool, and the engine's reviewer decides what leaves the sandbox. A `read-only` task changes nothing and uses only read-only tools. The strictest wins: a read-only agent, parent task or connection makes the task read-only.
+
+```bash
+coder task run --access read-only "audit the auth module"
+coder agent settings triage --access read-only
+```
+
+In the dashboard, pick it under **# Tasks → [New task]**, and per connection under **# Settings → (Connections)**.
+
+## Approvals
+
+When the reviewer refuses a step, the task tries another way or asks for approval, with the reason and the exact commands. The request shows as **Approval needed** in `coder task result`, on the task's page in **# Tasks**, and in the conversation the task came from. `--wait` exits with code 4.
+
+```bash
+coder task approvals                             # open requests
+coder task approve <id>                          # the task retries
+coder task approve <id> --deny --reason "<why>"  # the task reads why
+coder task approvals --denied                    # denied, still answerable
+```
+
+In a conversation, anyone with write access answers: **[Approve]** or **[Deny]** on Slack, a select on Linear, `/approve <id>` or `/deny <id> <why>` on GitHub and Linear. Approved commands stay approved for the rest of the task. Only `auto` tasks ask.
+
+## Agents in a thread
+
+Ask an agent on Slack, GitHub or Linear to start work and follow it; results come back to the thread. It acts as its own app, or as the person asking through their personal connection ([Connections](connections.md#workspace-or-personal)).
+
+- **At once**: starting, steering and stopping its tasks, and changing its own model and effort.
+- **After [Approve] in the thread**: its other settings, workspace model changes and the default runner. Agent changes need a connected member, workspace changes an admin, personal ones the person who asked. A member can **[Ask an admin]**.
+- **In the dashboard**: connections, credentials, models, runners, new agents and deletes. The agent replies with a filled-in link, so no key passes through it.
+
+The tasks it starts get its repositories, connections and access, or less. It answers their approvals; what it can't approve comes to the thread.
+
+## Who sees a task
+
+On a Coder server, owners and admins see every task, and each member sees their own. Tasks from the dashboard, the CLI and public channels, repositories or teams show to every member. Tasks from DMs and private places show to members who can see that place, through their connected account; unknown privacy counts as private. A task started by another task follows it.
+
+Whoever sees a task can steer, stop and delete it; a DM task only its author steers. Slack and GitHub membership changes show at once, Linear's on its next activity after a day.
+
+## Sandbox
+
+Each task gets a scratch folder, `$TMPDIR/coder/<task-id>`, for temp files, package caches and git writes; `coder task delete` removes it. Hosts in [`network.allowedHosts`](config.md#full-shape) are reachable without review.

package/docs/cli/agent.md

@@ -12,7 +12,7 @@ list local or server-owned agents
 
 Without --server, one row per built-in and workspace agent. With --server, list the agent records and current versions owned by that Coder server.
 
-- `--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
@@ -20,12 +20,12 @@ Without --server, one row per built-in and workspace agent. With --server, list
 
 ## `agent show [id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
-one agent in full: settings, integrations, events, tools
+one agent in full: settings, integrations, events, tools, installations
 
-Describe one agent as it will run here, or its active version on a server: its settings, access and per-integration events.
+Describe one agent as it will run here, or its active version on a server. It lists its settings, access and per-integration events, and on a server its installations.
 
 - `<id>` the agent
-- `--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
@@ -35,7 +35,30 @@ Describe one agent as it will run here, or its active version on a server: its s
 coder agent show coder  # what the built-in agent listens to and may do
 ```
 
-## `agent init [id] [--integrations <integrations>] [--events <events>] [--access <access>] [--name <name>] [--description <description>] [--permissions <permissions>] [--match <match>] [--yes] [--json] [--cwd <cwd>]`
+## `agent settings [id] [--model <model>] [--access <access>] [--connections <connections>] [--events <events>] [--instructions <instructions>] [--match <match>] [--server <server>] [--yes] [--json]`
+
+change an agent's settings on your Coder server
+
+Set the model, access, connections or events of an agent in the
+saved workspace, or publish its next version with new instructions or matches.
+Settings you leave out stay as they are.
+
+- `<id>` the agent
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high)
+- `--access <access>` read-only or auto, at most its definition
+- `--connections <connections>` the connections its tasks may use, by id
+- `--events <events>` the events it answers on a platform
+- `--instructions <instructions>` its system prompt, published as its next version
+- `--match <match>` start tasks only for event text matching a regex, as event=regex pairs
+- `--server <server>` act on your Coder server, in the saved workspace
+- `--yes` connect to a server used for the first time without asking
+- `--json` JSON output
+
+```sh
+coder agent settings helper --model sonnet  # a cheaper model for a simple agent
+```
+
+## `agent init [id] [--integrations <integrations>] [--events <events>] [--access <access>] [--name <name>] [--description <description>] [--match <match>] [--yes] [--json] [--cwd <cwd>]`
 
 scaffold an agent folder in .coder/agents
 
@@ -44,10 +67,9 @@ Create .coder/agents/<id>/ with an agent.json built from the integration catalog
 - `<id>` the agent id: its folder under .coder/agents
 - `--integrations <integrations>` platforms the agent listens to (see coder agent integrations list)
 - `--events <events>` events that start tasks, applied to each integration that has them (default: mention)
-- `--access <access>` read or write, on its platforms and connections (default: write)
+- `--access <access>` read-only or auto, for its tasks, platforms and connections (default: auto)
 - `--name <name>` display name used in replies (default: the id)
 - `--description <description>` one line for agent list
-- `--permissions <permissions>` engine permission mode (default: auto)
 - `--match <match>` start tasks only for event text matching a regex, as event=regex pairs
 - `--yes` skip the questions and take the defaults
 - `--json` JSON output
@@ -55,7 +77,7 @@ Create .coder/agents/<id>/ with an agent.json built from the integration catalog
 
 ```sh
 coder agent init  # answer the questions, id included
-coder agent init triage --integrations github --events issue,mention --access read  # no questions
+coder agent init triage --integrations github --events issue,mention --access read-only  # no questions
 ```
 
 ## `agent push [id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
@@ -65,7 +87,7 @@ upload workspace agents to a Coder server
 Upload one workspace agent, or every agent in .coder/agents when no id is given. The server creates a new immutable version only when its definition, prompt, or files changed.
 
 - `<id>` the agent (default: every workspace agent)
-- `--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
@@ -75,7 +97,7 @@ Upload one workspace agent, or every agent in .coder/agents when no id is given.
 coder agent push helper  # upload helper
 ```
 
-## `agent run [agent] [file] [--server <server>] [--workspace <workspace>] [--yes] [--wait] [--flow <flow>] [--task <task>] [--json] [--cwd <cwd>]`
+## `agent run [agent] [file] [--server <server>] [--workspace <workspace>] [--yes] [--wait] [--task <task>] [--json] [--cwd <cwd>]`
 
 run a recorded event through an agent, offline or on a server
 
@@ -87,7 +109,6 @@ Run a recorded platform event (AgentEvent JSON) through an agent. With --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
 - `--wait` with --server: follow the task log here until it finishes, then print the reply
-- `--flow <flow>` override the matched flow
 - `--task <task>` a runner's form: run that server task here
 - `--json` JSON output
 - `--cwd <cwd>` workspace directory; default current
@@ -103,7 +124,7 @@ aggregate usage by agent, installation, or engine
 
 - `--since <since>` period such as 7d or 24h, or milliseconds since epoch
 - `--by <by>` agent, installation, or engine
-- `--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
@@ -127,7 +148,7 @@ One row per integration: its id, the events an agent can wire, and every tool it
 
 events and tools of one integration
 
-Describe one integration: each event with what triggers it, and the tools each preset (read, write) allows.
+Describe one integration: each event with what triggers it, and the tools each access (read-only, auto) allows.
 
 - `<id>` the integration
 - `--json` JSON output

package/docs/cli/auth.md

@@ -10,7 +10,7 @@ sign in through the browser
 
 Sign in with Wular Auth in your browser. The CLI keeps the tokens in ~/.coder/session.json, and commands that talk to a server then act as you.
 
-- `--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
 - `--device` show a code to approve on another device; the default without a local browser

package/docs/cli/connection.md

@@ -2,72 +2,73 @@
 
 # connection
 
-platform accounts, API keys and MCP servers tasks use
+platform accounts and MCP servers tasks use
 
-Connections give tasks access to a service without a handle: a platform account, an API key tasks read from the environment, or an MCP server. They live in ~/.coder, or on your Coder server with --server, and every task of yours may use them unless its agent or `coder task run --connections` narrows the set.
+Connections give tasks access to a service through a platform account or an MCP server. They live in ~/.coder, or on the Coder server with --server, and tasks may use them unless an agent or `coder task run --connections` narrows the set.
 
-## `connection add <name> [--command <command>] [--env <env>] [--url <url>] [--header <header>] [--key] [--auth <auth>] [--access <access>] [--tools <tools>] [--credential <credential>] [--me] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+## `connection add <name> [--command <command>] [--env <env>] [--url <url>] [--header <header>] [--key] [--auth <auth>] [--access <access>] [--tools <tools>] [--credential <credential>] [--personal] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
-connect a platform account, an API key or an MCP server
+connect a platform account or an MCP server
 
-Connect a platform account by its name (OAuth in the browser), an API key that tasks read from --env, or an MCP server at --url or started by the command after `--`. An API key is kept as a credential. A credential already holding the variable is used, else the value comes from that variable here, or from stdin or a prompt. A remote MCP server is checked for OAuth, open access or a key; a needed key is read from stdin or a prompt. With --key, the key goes in --header (default Authorization) or --env. Signing in needs --server.
+Connect a platform account by its name (OAuth in the browser), or an MCP server at --url or started by the command after `--`. Platform accounts are personal and take no scope flag; MCP servers default to workspace scope, with --personal for personal scope. A remote MCP server is checked for OAuth, open access or a key; a needed key is read from stdin or a prompt. With --key, the key goes in --header (default Authorization) or --env. Signing in needs --server.
 
 - `<name>` the connection name; a platform name connects that account
 - `--command <command>` a stdio MCP server to start; on the command line, the words after `--`
-- `--env <env>` the API key variable, or where a stdio server reads its key
+- `--env <env>` the task-secret variable, or where a stdio server reads its key
 - `--url <url>` a remote MCP server (streamable HTTP by default)
 - `--header <header>` the header a remote server reads its key from (default: Authorization)
 - `--key` read a key from stdin or a prompt, never from a flag value
 - `--auth <auth>` override MCP authentication (default: detected for --url, none for a command)
-- `--access <access>` read keeps only read-only tools (default: the agent's mode, write for API keys)
+- `--access <access>` read-only keeps only read-only tools (default: auto, which follows the task)
 - `--tools <tools>` tool allowlist; a read-only stdio server needs one
-- `--credential <credential>` the credential an API key connection reads
-- `--me` your own connection instead of the workspace's
-- `--server <server>` act on your Coder server
+- `--credential <credential>` the credential a task secret reads
+- `--personal` a personal connection instead of 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
 
 ```sh
-GROQ_API_KEY=gsk_... coder connection add groq --env GROQ_API_KEY  # an API key from this shell
-pbpaste | coder connection add docs --key --env DOCS_TOKEN --access write -- npx -y docs-mcp  # a stdio server with its key from stdin
-coder connection add github --me --server  # your GitHub account on your Coder server
+pbpaste | coder connection add docs --key --env DOCS_TOKEN -- npx -y docs-mcp  # a stdio server with its key from stdin
+coder connection add github --server  # a member's GitHub account on the Coder server
 ```
 
 ## `connection list [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 list connections and the MCP servers this repository declares
 
-Your connections, and the MCP servers this repository and its agents declare with whether each is approved on this machine.
+Every workspace connection and every member's own, with its status. In a task, one it is not granted is disabled, and one it has names its tool search server. On this machine, also the MCP servers this repository and its agents declare, with whether each is approved here.
 
-- `--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
 - `--cwd <cwd>` workspace directory; default current
 
-## `connection rm <name> [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+## `connection rm <name> [--personal] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 remove a connection
 
-Remove a connection. The credential an API key connection reads stays.
+Remove a connection. The credential a task secret reads stays. With --personal, the asking member's own connection of that name.
 
 - `<name>` the connection
-- `--server <server>` act on your Coder server
+- `--personal` the asking member's own connection instead of 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
 
-## `connection reconnect <name> [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+## `connection reconnect <name> [--personal] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 give a connection a new key, or sign in again
 
-Give a key connection its new key, read from stdin or a prompt, or sign in to an OAuth connection again in the browser. The credential an API key connection reads gets the new value, so every connection reading it rotates.
+Give a key connection its new key, read from stdin or a prompt, or sign in to an OAuth connection again in the browser. The credential a task secret reads gets the new value, so every connection reading it rotates. With --personal, the asking member's own connection of that name.
 
 - `<name>` the connection
-- `--server <server>` act on your Coder server
+- `--personal` the asking member's own connection instead of 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

package/docs/cli/index.md

@@ -2,7 +2,7 @@
 
 # coder CLI
 
-Delegate a coding task to the best available engine and steer it while it runs.
+Coder turns any model into an agent you own: tasks on this machine, from your code, or always on in Coder Cloud.
 
 - [task](task.md): run, follow and steer coding tasks
 - [flow](flow.md): orchestrate many coder tasks from one TypeScript file
@@ -12,9 +12,9 @@ Delegate a coding task to the best available engine and steer it while it runs.
 - [runner](runner.md): run your server's tasks on this machine
 - [auth](auth.md): sign in to Coder and manage saved server sessions
 - [model](model.md): manage models: built-ins, aliases, custom endpoints
-- [connection](connection.md): platform accounts, API keys and MCP servers tasks use
+- [connection](connection.md): platform accounts and MCP servers tasks use
 
-## `review [--base <base>] [--head <head>] [--pr <pr>] [--since <since>] [--path <path>] [--exclude <exclude>] [--post] [--md] [--engine <engine>] [--model <model>] [--effort <effort>] [--json] [--cwd <cwd>]`
+## `review [--base <base>] [--head <head>] [--pr <pr>] [--since <since>] [--path <path>] [--exclude <exclude>] [--post] [--run <run>] [--md] [--model <model>] [--depth <depth>] [--json] [--cwd <cwd>]`
 
 review changed code with a built-in flow
 
@@ -22,7 +22,7 @@ Review changed code with a read-only agent. Every reported finding is checked
 against the repository. Runs the built-in `review` flow. A local review covers
 everything since the merge-base with the origin default branch, including
 uncommitted and untracked files. Changed submodules are reviewed file by file.
-PR reviews can post deduplicated inline comments.
+PR reviews can post one review with inline comments, never repeating a finding.
 
 Related: `coder flow watch`, `coder docs review`.
 
@@ -32,11 +32,11 @@ Related: `coder flow watch`, `coder docs review`.
 - `--since <since>` keep only PR files and hunks changed since this commit
 - `--path <path>` review only this path, relative to cwd (repeatable)
 - `--exclude <exclude>` leave this path out, relative to cwd (repeatable)
-- `--post` post deduplicated inline comments and sticky PR summary
+- `--post` post the review on the pull request, as the signed-in gh user
+- `--run <run>` with --post, post this finished review run instead of reviewing again
 - `--md` markdown output (the default)
-- `--engine <engine>` codex, claude, or custom
-- `--model <model>` model for the review task
-- `--effort <effort>` reasoning effort and review depth (default: medium depth)
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high) for the review task (default: reviewModel)
+- `--depth <depth>` what to report: low only critical and major, high nits too (default: medium)
 - `--json` JSON output
 - `--cwd <cwd>` workspace directory; default current
 
@@ -45,6 +45,8 @@ coder review  # review the branch plus uncommitted work
 coder review --base main  # review everything since main locally
 coder review --path src --exclude src/gen  # review src without generated code
 coder review --pr 42 --post  # review and post to pull request 42
+coder review --depth high  # report nits too
+coder review --post --run <id>  # post a finished review run
 ```
 
 ## `config [action] [key] [value] [--workspace] [--json] [--cwd <cwd>]`
@@ -52,10 +54,11 @@ coder review --pr 42 --post  # review and post to pull request 42
 read or write config
 
 Read or write configuration. `list` prints the effective config; get/set/unset
-target a dotted key (e.g. engines.codex.model). Writes go to ~/.coder/config.json.
+target a dotted key (e.g. chain); migrate rewrites the file at this Coder's config
+version. Writes go to ~/.coder/config.json.
 
-- `<action>` list, get, set or unset
-- `<key>` a dotted key, such as engines.codex.model
+- `<action>` list, get, set, unset or migrate
+- `<key>` a dotted key, such as chain or reviewModel
 - `<value>` with set: the value; JSON, or a comma list
 - `--workspace` target <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
@@ -63,8 +66,9 @@ target a dotted key (e.g. engines.codex.model). Writes go to ~/.coder/config.jso
 
 ```sh
 coder config list  # print the effective config
-coder config set chain codex,claude  # set the engine fallback chain
-coder config get engines.codex.model  # read one value
+coder config set chain codex/sol,claude/opus  # the default model, then its fallbacks
+coder config get reviewModel  # read one value
+coder config migrate --workspace  # rewrite the repo file at config version 1
 ```
 
 ## `setup-host [hosts] [--json] [--cwd <cwd>]`
@@ -131,7 +135,7 @@ serve Coder's commands as MCP tools over stdio
 
 Serve Coder's commands as MCP tools over stdio, so a harness can run them.
 
-Commands return their JSON payloads and next steps. Load guides with load_skill;
+Commands return their JSON payloads and next steps. Load docs with load_skill;
 blocking commands keep their CLI flags and behavior, subject to the client's tool timeout.
 
 ```sh