@wular/coder 0.3.18 → 0.4.0

package/docs/config.md

@@ -1,18 +1,19 @@
 # Configuration
 
-The Coder configuration reference. Machine defaults live in `~/.coder/config.json`; a `coder.config.json` at a repo root overrides per project. Merge order, later wins:
+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:
 
 1. Built-in defaults
 2. `~/.coder/config.json`
-3. `<repo>/coder.config.json`
-4. CLI flags on the dispatch itself (`--agent`, `--model`, `--effort`, `--permissions`)
+3. `<repo>/.coder/config.json`
+4. CLI flags on the dispatch itself (`--engine`, `--model`, `--effort`, `--permissions`)
 
 Read and write values from the CLI (`--workspace` targets the repo file instead of the user file):
 
 ```bash
-coder config get [key]
+coder config list
+coder config get <key>
 coder config set chain '["codex", "claude", "custom"]'
-coder config set agents.codex.model terra
+coder config set engines.codex.model sol
 ```
 
 ## Full shape
@@ -20,63 +21,83 @@ coder config set agents.codex.model terra
 ```json
 {
   "chain": ["codex", "claude", "custom"],
-  "agents": {
-    "codex": { "model": "terra", "effort": "high", "permissions": "auto" },
+  "engines": {
+    "codex": { "model": "sol", "effort": "high", "permissions": "auto", "network": true },
     "claude": { "model": "opus", "effort": "medium", "permissions": "auto" },
     "custom": { "model": "qwen" }
   },
   "models": {
     "qwen": { "baseUrl": "http://localhost:11434/v1", "model": "qwen2.5-coder:32b" },
-    "fast": { "provider": "codex", "model": "gpt-5.3-codex-spark" },
+    "fast": { "provider": "codex", "model": "gpt-6-luna" },
     "big": { "provider": "claude", "model": "opus", "effort": "high" },
-    "luna": { "disabled": true }
+    "astra": { "disabled": true }
   },
   "approvals": {
     "escalationTimeoutMs": 120000,
     "allowedNetworkHosts": ["localhost", "127.0.0.1", "registry.npmjs.org"]
+  },
+  "agents": {
+    "review": false,
+    "helper": {
+      "permissions": "read-only",
+      "integrations": {
+        "github": { "allowedTools": "comment" }
+      }
+    }
+  },
+  "mcp": {
+    "docs": { "command": "npx", "args": ["-y", "docs-mcp"], "tools": ["search"] }
   }
 }
 ```
 
 ## `chain`
 
-Fallback order. When an agent can't start (missing binary, auth, quota), the task automatically retries on the next entry. Default `["codex", "claude"]`.
+Fallback order. When an engine can't start (missing binary, auth, quota), the task automatically retries on the next entry. Default `["codex", "claude"]`.
 
-## `agents`
+## `engines`
 
-Per-agent defaults, used when a dispatch doesn't override them:
+Per-engine defaults, used when a dispatch doesn't override them:
 
-| Key | Values |
-| --- | --- |
-| `model` | codex: `spark`, `luna`, `terra`, `sol` · claude: `haiku`, `sonnet`, `opus`, `fable` · custom: any name from `models` |
-| `effort` | `low`, `medium`, `high` |
-| `permissions` | `read-only`, `workspace-write`, `auto` |
+| 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, auto adds policy-answered escalations.
+Permission modes are one surface across all engines: read-only can't modify anything, workspace-write stays inside the repo, and auto enables Codex network access plus policy-answered escalations; `engines.codex.network` overrides network access for every mode when set.
+
+A task reaches only its workspace unless you give it more. Pass `--add-dir <dir>` to `coder run` once for each sibling repo or shared folder the task needs. Relative paths resolve against the workspace and each one must already exist. Read-only tasks can read these directories but never write them, while workspace-write and auto tasks can write them just like the workspace. Claude receives them as `--add-dir` and `permissions.additionalDirectories`, so its OS sandbox follows the same rules. Codex already reads everywhere in read-only, and in the other modes it receives them as extra writable roots in the turn's sandbox policy. The directories are saved on the task, `coder result` lists them, and both `--resume` and steering keep them.
 
 ## `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` agent) | `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` |
+| 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. `spark`) shadows it. See [Models](models.md).
+Every shape also accepts `"disabled": true` to park the entry without deleting it. An entry named after a built-in alias (e.g. `luna`) shadows it. See [Models](models.md).
 
 ## `approvals`
 
 Tunes the `auto` permission mode; ignored by `read-only` and `workspace-write`.
 
-| Key | Meaning |
-| --- | --- |
+| Key                   | Meaning                                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
 | `escalationTimeoutMs` | How long an escalated approval waits for an answer before auto-denying and letting the task move on. Default `120000`. |
-| `allowedNetworkHosts` | Hosts (and their subdomains) coders may reach without an approval. Default `[]` — all network access escalates. |
+| `allowedNetworkHosts` | Hosts (and their subdomains) coders may reach without an approval when network sandboxing is active. Default `[]`.     |
+
+`allowedNetworkHosts` is pre-allowed in the Claude sandbox and auto-accepted by the Codex approval policy when `engines.codex.network` is `false`. A bare hostname covers its subdomains; anything else escalates as usual. Listing `localhost`, `127.0.0.1` or `::1` also lets sandboxed Claude commands serve on local ports (macOS), so a task can run a dev server.
+
+Allowlist only hosts you trust: the check is by name, not by the address the name resolves to.
+
+## `agents`
 
-`allowedNetworkHosts` works on both engines — auto-accepted by the codex approval policy, pre-allowed in the claude sandbox. A bare hostname covers its subdomains; anything else escalates as usual.
+Per-agent usage: enable, override, scope. Reference and examples in [Agents](agents/index.md#usage).
 
----
+## `mcp`
 
-Config files are validated strictly: an unknown key or bad value fails with a pointed error instead of being silently ignored.
+Servers tasks can attach with `--mcp <name>`, in the `.mcp.json` entry shape. Reference and CLI in [MCP](mcp.md).

package/docs/dash.md

@@ -0,0 +1,64 @@
+# Dashboard
+
+The dashboard is Coder's web UI at `/dash`. `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.
+
+`coder dash` is short for `coder server serve`:
+
+```sh
+coder dash               # http://localhost:8787
+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.
+
+## Pages
+
+**Agents**: agents from two sources. Give one its own app from its Platforms tab.
+
+- **Dashboard agents** are made in the editor.
+  - **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>/`.
+  - **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.
+
+- **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.
+
+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.
+
+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.
+
+**Settings**: what every task runs with.
+
+- **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**: the user config, as `coder config`, `coder model` and `coder mcp add --user` 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.
+  - **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.
+
+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.
+
+## Platform events
+
+Agents answer GitHub, Slack and other platforms only when the platform can reach the server.
+
+- **Local**: open a tunnel (`ngrok http 8787`, `cloudflared tunnel --url http://localhost:8787`, or VS Code's Ports panel set to Public) and restart with `PUBLIC_URL` set to the tunnel's URL. The tunnel serves only webhooks and app setup callbacks, never the dashboard or `/admin`.
+- **Cloud**: platforms reach it at its own `PUBLIC_URL`.

package/docs/flows.md

@@ -42,9 +42,7 @@ A flow is an ordinary TypeScript module: import the primitives, use top-level `a
 // .coder/flows/verify-wave.ts
 import { task, pipeline, args } from '@wular/coder/flow';
 
-export default await pipeline(args.clusters as string[], c =>
-  task(`Verify cluster ${c}.`),
-);
+export default await pipeline(args.clusters as string[], c => task(`Verify cluster ${c}.`));
 ```
 
 ## The primitives
@@ -55,23 +53,20 @@ Dispatch one coder task and await its result.
 
 ```ts
 const r = await task('Explain the auth module', {
-  model: 'terra',
+  model: 'sol',
   permissions: 'read-only',
 });
 r.output; // final message text
 ```
 
-Options are the same as the `coder run` flags (`agent`, `model`, `effort`, `permissions`, `name`, `system`, `resume`, `cwd` - see `coder run --help`), plus one of its own:
+Options are the same as the `coder run` flags (`engine`, `model`, `effort`, `permissions`, `name`, `system`, `resume`, `cwd`, and `addDirs` for `--add-dir` - see `coder run --help`), plus one of its own:
 
-- `returns` - a zod schema for structured output instead of prose. The runtime injects the format instructions, validates the reply (one corrective retry on mismatch), and the parsed value lands on `r.data`:
+- `returns` - a zod schema for structured output instead of prose. The runtime passes the schema natively, validates the reply (one corrective retry on mismatch), and the parsed value lands on `r.data`:
 
 ```ts
-const r = await task(
-  'List every file that imports the legacy cache API.',
-  {
-    returns: z.object({ files: z.array(z.string()) }),
-  },
-);
+const r = await task('List every file that imports the legacy cache API.', {
+  returns: z.object({ files: z.array(z.string()) }),
+});
 
 r.data.files; // string[], validated
 ```
@@ -117,9 +112,7 @@ Prefer `pipeline` for anything multi-stage: fast items never wait for slow ones.
 Use `Promise.all` for plain parallel batches:
 
 ```ts
-const findings = await Promise.all(
-  areas.map(area => task(`Audit ${area}.`)),
-);
+const findings = await Promise.all(areas.map(area => task(`Audit ${area}.`)));
 ```
 
 ### `args`
@@ -202,6 +195,18 @@ The one rule this buys: **a flow must produce the same prompts on every run**. D
 
 An explicit path (`coder flow run ./scratch/one-off.ts`) bypasses discovery entirely. `coder flow discover` shows every flow discoverable from where you stand.
 
+### Built-in flows
+
+Coder ships a few flows of its own; they resolve after the directories above, so a repo flow of the same name overrides them. `coder flow discover` lists them with scope `builtin`.
+
+- `review`: the `coder review` code review. Args: `pr` (number or GitHub URL), `post` (comment on the PR), `base`/`head`/`since` (as the CLI flags), `engine`/`model`/`effort`. Returns `{ findings, summary }`. `coder flow run review --args '{"pr":42,"post":true}'`
+
+### Flows run by an agent
+
+An [agent](agents/index.md) runs a flow like any script: `coder flow run <name>` from its shell, inside its sandbox. It can run any flow, including one it writes during the task.
+
+The tasks a flow starts can't exceed the agent's `permissions` (`read-only` < `workspace-write` < `auto`). A task without permissions inherits the agent's, and one asking for more fails before it starts. Platform actions, like the `review` flow's comments, run outside the sandbox, so no token enters it.
+
 ## CLI
 
 ```bash

package/docs/mcp.md

@@ -0,0 +1,62 @@
+# MCP
+
+Give tasks tools of your own: an MCP server is saved once under `mcp` in `.coder/config.json`, then attached to a task by name. Nothing attaches unless asked, so the default run stays lean.
+
+```sh
+coder mcp add docs -- npx -y docs-mcp                       # stdio server: the command after --
+coder mcp add linear --url https://mcp.linear.app/mcp        # remote server; OAuth login happens in the engine on first use
+coder run --mcp docs,linear "why do uploads fail after a rename?"
+```
+
+## Adding servers
+
+| Command                                    | Does                                                                                         |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `coder mcp add <name> -- <command> [args]` | Stdio server. `--env K=V,...` sets its environment                                           |
+| `coder mcp add <name> --url <url>`         | Remote server. `--header K=V,...` adds request headers, `--transport sse` for legacy servers |
+| `coder mcp add-json <name> '<entry>'`      | Paste an entry from any `.mcp.json`, Cursor `mcp.json`, or a vendor README as is             |
+| `coder mcp list`, `coder mcp rm <name>`    | List and remove                                                                              |
+
+`add` takes `--tools a,b` to cap what the agent may call; `add-json` accepts a `tools` array in the entry. `add`, `add-json` and `rm` take `--user` to write `~/.coder` instead of the repo. Repo and user maps merge, repo wins on a name.
+
+## Config shape
+
+The entries are the `.mcp.json` convention shared by Claude Code, Cursor, Windsurf and Codex, so anything written for them drops in:
+
+```json
+{
+  "mcp": {
+    "docs": { "command": "npx", "args": ["-y", "docs-mcp"], "tools": ["search"] },
+    "sentry": {
+      "command": "npx",
+      "args": ["-y", "@sentry/mcp-server"],
+      "env": { "SENTRY_TOKEN": "${SENTRY_TOKEN}" }
+    },
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": { "Authorization": "Bearer ${GH_TOKEN}" }
+    }
+  }
+}
+```
+
+| Key                      | Purpose                                                             |
+| ------------------------ | ------------------------------------------------------------------- |
+| `command`, `args`, `env` | Stdio server to spawn                                               |
+| `url`, `headers`, `type` | Remote server; `type` is `http` (streamable HTTP, default) or `sse` |
+| `tools`                  | Allowlist of tool names; omit for every tool the server offers      |
+| `description`            | What the server is for                                              |
+
+`${VAR}` and `${VAR:-default}` in any value expand from the environment when the server starts, so tokens never sit in the file.
+
+## Attaching to a task
+
+`--mcp` on `coder task run` (and `coder run`) takes names, `all`, or an inline JSON array of entries with a `name` field for one-off servers:
+
+```sh
+coder run --mcp docs "..."
+coder run --mcp all "..."
+coder run --mcp '[{"name":"tmp","command":"node","args":["server.js"]}]' "..."
+```
+
+Claude gets the servers through `--mcp-config` with the allowlist as `mcp__<name>__<tool>`; Codex gets them as `mcp_servers.<name>` overrides with `enabled_tools`. Agents attach their integration tools the same way, so an agent never needs an entry here.

package/docs/models.md

@@ -8,27 +8,27 @@ Manage every model Coder can dispatch to. That means the built-in Codex and Clau
 # local Ollama model, no key
 coder model add qwen --base-url http://localhost:11434/v1 --model qwen2.5-coder:32b
 
-# third-party provider via OpenRouter
-coder model add kimi --base-url https://openrouter.ai/api/v1 --model moonshotai/kimi-k2 --env-key OPENROUTER_API_KEY
+# third-party provider via OpenRouter, key read from the environment
+coder model add kimi --base-url https://openrouter.ai/api/v1 --env-key OPENROUTER_API_KEY --model moonshotai/kimi-k2
 ```
 
 `model add` saves the entry, probes the endpoint, and reports anything missing (unreachable URL, unset key env var, no codex). Change one later with `coder model update <name>`, drop it with `coder model remove <name>`. Flags:
 
-| Flag | Meaning |
-| --- | --- |
-| `--base-url <url>` | OpenAI-compatible API base (e.g. `http://localhost:11434/v1`) |
-| `--model <id>` | the provider's model id (e.g. `qwen2.5-coder:32b`) |
-| `--env-key <VAR>` | env var holding the API key; omit for keyless local endpoints |
-| `--workspace` | write to `<repo>/coder.config.json` instead of the user file |
+| Flag               | Meaning                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------- |
+| `--base-url <url>` | OpenAI-compatible API base (e.g. `http://localhost:11434/v1`)                            |
+| `--model <id>`     | the provider's model id (e.g. `qwen2.5-coder:32b`)                                       |
+| `--env-key <VAR>`  | env var holding the API key; omit for keyless local endpoints                            |
+| `--workspace`      | write to `<repo>/.coder/config.json` instead of the user file                            |
 
 ## Use it
 
-Anywhere a model name goes; together they form the `custom` agent:
+Anywhere a model name goes; together they form the `custom` engine:
 
 ```bash
 coder run --model qwen "explain this repo"        # per task
-coder run --agent custom "explain this repo"      # the custom agent (its default model, or the only one)
-coder config set agents.custom.model qwen         # default model for --agent custom
+coder run --engine custom "explain this repo"      # the custom engine (its default model, or the only one)
+coder config set engines.custom.model qwen         # default model for --engine custom
 coder model list                                  # list models + probe their endpoints
 ```
 
@@ -43,23 +43,37 @@ coder config set chain '["codex", "claude", "custom"]'
 Built-ins are just pre-seeded aliases tied to an engine, so `coder model list`
 shows them and your own aliases together, grouped per engine. Disable
 any model name - a built-in, a custom model, an alias, or a raw engine slug
-like `gpt-5.6-terra` - without removing its configuration, then re-enable it
+like `gpt-6-astra` - without removing its configuration, then re-enable it
 when needed; requests for a disabled model fail at dispatch:
 
 ```bash
-coder model disable terra
-coder model enable terra
+coder model disable astra
+coder model enable astra
 ```
 
-Create an alias for an agent spec with `coder model alias fast codex:spark`
+Create an alias for an engine spec with `coder model alias fast codex:luna`
 (effort can ride along: `coder model alias big claude:opus:high`); remove it
 with `coder model unalias fast`. Aliases may reuse a built-in name, so
-`coder model alias spark codex:gpt-x` intentionally overrides the built-in
-`spark`, and `model list` shows the override in its place.
+`coder model alias luna codex:gpt-x` intentionally overrides the built-in
+`luna`, and `model list` shows the override in its place.
 
-`spark` maps to GPT-5.3-Codex-Spark: a fast, less-capable model suited to
-mechanical work. It has its own usage limits and, during research preview, is
-available only on ChatGPT Pro plans.
+The built-ins:
+
+| Alias    | Model                 | Use it for                       | Needs          |
+| -------- | --------------------- | -------------------------------- | -------------- |
+| `luna`   | `gpt-6-luna` (codex)  | mechanical work                  | codex 0.156.1  |
+| `sol`    | `gpt-6.1-sol` (codex) | the default                      | codex 0.159.1  |
+| `astra`  | `gpt-6-astra` (codex) | the hardest work; costs the most | codex 0.154.0  |
+| `sonnet` | `sonnet` (claude)     | mechanical work                  | claude 2.1.197 |
+| `opus`   | `opus` (claude)       | the default                      | claude 2.1.280 |
+| `fable`  | `fable` (claude)      | the hardest work; costs the most | claude 2.1.257 |
+
+A task on an older CLI still runs, with a warning to run `codex update` or
+`claude update`.
+
+Claude aliases pass through to the claude CLI, which resolves them to its
+current model (`opus` is Claude Opus 5.5 today). Any full model id, such as
+`gpt-5.6-sol` or `claude-sonnet-5`, also works as a pass-through.
 
 ## Config shape
 
@@ -70,10 +84,14 @@ engine alias, or a bare disable toggle for any model name):
 ```json
 {
   "models": {
-    "qwen": { "baseUrl": "http://localhost:11434/v1", "model": "qwen2.5-coder:32b", "envKey": "MY_KEY" },
-    "fast": { "provider": "codex", "model": "gpt-5.3-codex-spark" },
+    "qwen": {
+      "baseUrl": "http://localhost:11434/v1",
+      "model": "qwen2.5-coder:32b",
+      "envKey": "MY_KEY"
+    },
+    "fast": { "provider": "codex", "model": "gpt-6-luna" },
     "big": { "provider": "claude", "model": "opus", "effort": "high" },
-    "terra": { "disabled": true }
+    "astra": { "disabled": true }
   }
 }
 ```

package/docs/review.md

@@ -0,0 +1,41 @@
+# Review
+
+`coder review` runs one read-only review task over local changes or a pull request, checks every finding against the repository, and prints the ones that hold. With `--post` it comments inline on the pull request and keeps one sticky summary. A local review covers everything since the merge-base with the origin default branch, committed or not, and never touches the index or working tree.
+
+```sh
+coder review                         # local changes since the default branch
+coder review --base main --path src  # only src, against main
+coder review --pr 42 --post          # pull request 42, posted as comments
+```
+
+## Flags
+
+| Flag                    | Meaning                                                                                                                          | Default                                            |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `--effort <level>`      | Model reasoning effort and review depth: `low` reports critical and major defects, `medium` any defect, `high` also minor issues | Repository configuration, `medium`                 |
+| `--base <ref>`          | Older side of a local diff                                                                                                       | Merge-base of `HEAD` and the origin default branch |
+| `--head <ref>`          | Newer side of a local diff, commits only                                                                                         | The working tree                                   |
+| `--pr <n \| url>`       | Pull request number in the origin repo, or a GitHub pull request URL                                                             | Local diff                                         |
+| `--since <sha>`         | Keep only pull request hunks changed after this commit                                                                           | Head in the previous sticky summary                |
+| `--path <p>`            | Review only this pathspec; repeatable                                                                                            | Everything                                         |
+| `--exclude <p>`         | Leave this pathspec out; repeatable                                                                                              | Nothing                                            |
+| `--post`                | Post inline comments and update the sticky summary; needs `--pr`                                                                 | Print only                                         |
+| `--md`                  | Print Markdown                                                                                                                   | Enabled unless `--json` is used                    |
+| `--json`                | Print `{ findings, summary, runId }`                                                                                             | Disabled                                           |
+| `--engine <name>`       | Engine for the review task                                                                                                       | Repository configuration                           |
+| `--model <alias\|slug>` | Model for the review task                                                                                                        | Repository configuration                           |
+| `--cwd <dir>`           | Checkout to review                                                                                                               | Current directory                                  |
+
+`--pr` cannot be combined with `--base` or `--head`, and `--json` cannot be combined with `--md`.
+
+## Repository rules
+
+The reviewer reads `AGENTS.md`, `CLAUDE.md`, and an optional `.coder/review.md` from the base commit, so a change cannot rewrite its own rules. Each file is capped at 32,000 characters.
+
+## Submodules
+
+Changed submodules are reviewed file by file under their path. Uninitialized ones, ones missing a needed commit, and nested repositories that are not submodules are skipped with a warning, and submodule findings are never posted inline.
+
+## Exit codes
+
+The command exits `0` when the review completes, even with findings, `1` when the diff, review, or posting fails, `3` when no engine starts, and `4` while a task awaits approval.