From 1b0c1302e630f9de795652238f5c838ddd1ddfb3 Mon Sep 17 00:00:00 2001 From: DS <78942835+Tarquinen@users.noreply.github.com> Date: Thu, 22 Oct 2026 22:02:38 -0400 Subject: [PATCH] docs(www): fix outdated V2 docs (#58280) --- services/www/src/docs/content/attachments.mdx | 20 +++-- .../www/src/docs/content/cli/commands.mdx | 31 +++++++ services/www/src/docs/content/cli/config.mdx | 6 +- .../www/src/docs/content/cli/keybinds.mdx | 83 +++++++++++-------- services/www/src/docs/content/compaction.mdx | 21 ++++- services/www/src/docs/content/migrate-v1.mdx | 31 ++++++- services/www/src/docs/content/plugins.mdx | 16 ++-- services/www/src/docs/content/providers.mdx | 4 +- 8 files changed, 153 insertions(+), 59 deletions(-) diff --git a/services/www/src/docs/content/attachments.mdx b/services/www/src/docs/content/attachments.mdx index 36caace2e88..6a7342b7679 100644 --- a/services/www/src/docs/content/attachments.mdx +++ b/services/www/src/docs/content/attachments.mdx @@ -57,16 +57,20 @@ HTTP and HTTPS attachment URLs are not supported. See the generated Current V2 sessions make these attachment types visible to the model: -| Input | Model receives | Example | -| ----------------------- | -------------------------------------------------------------- | ------------------ | -| UTF-8 text file | Filename and decoded text | `README.md` | -| Directory | Non-recursive listing of immediate files and directories | `file:///home/me/` | -| PNG, JPEG, GIF, or WebP | Image media | `diagram.png` | +| Input | Model receives | Example | +| ----------------------- | -------------------------------------------------------- | ------------------ | +| UTF-8 text file | Filename and decoded text | `README.md` | +| Directory | Non-recursive listing of immediate files and directories | `file:///home/me/` | +| PNG, JPEG, GIF, or WebP | Image media | `diagram.png` | +| PDF | Document media | `report.pdf` | -SVG is treated as text. PDF, AVIF, BMP, audio, video, and other binary prompt +PDFs need a model with PDF input. If the model does not support an attachment's +type, OpenCode sends a short note in its place. + +SVG is treated as text. AVIF, BMP, audio, video, and other binary prompt attachments are not included in the model request. Convert an unsupported -binary to text or a supported image first; for example, export a PDF page as -`page-1.png` before attaching it. +binary to text or a supported image first; for example, convert a BMP image to +PNG before attaching it. OpenCode reads each attachment before admitting the prompt. It rejects invalid URLs, unreadable paths, paths other than files or directories, and decoded diff --git a/services/www/src/docs/content/cli/commands.mdx b/services/www/src/docs/content/cli/commands.mdx index 8ab2bb3d3db..751a12574c6 100644 --- a/services/www/src/docs/content/cli/commands.mdx +++ b/services/www/src/docs/content/cli/commands.mdx @@ -62,6 +62,18 @@ Run with a specific agent. $ opencode run --agent build "Fix the failing test" ``` +Continue a specific session. + +```bash +$ opencode run --session ses_4f2a1c "Check edge cases" +``` + +Auto-approve permissions that are not explicitly denied. + +```bash +$ opencode run --auto "Fix the failing test" +``` + View all subcommands and flags. ```bash @@ -88,6 +100,12 @@ Start with a model and an initial prompt. $ opencode mini --model anthropic/claude-sonnet-4-5 --prompt "Summarize this repository" ``` +Continue a specific session. + +```bash +$ opencode mini --session ses_4f2a1c +``` + View all subcommands and flags. ```bash @@ -182,6 +200,13 @@ Switch the active account for an integration. $ opencode auth switch anthropic work ``` +Export saved credentials and import them on another machine. The file contains secrets. + +```bash +$ opencode auth export anthropic > credentials.json +$ opencode auth import credentials.json +``` + View all subcommands and flags. ```bash @@ -328,6 +353,12 @@ Print JSON instead of a report. $ opencode stats --json ``` +Show only the current project. + +```bash +$ opencode stats --project . +``` + View all subcommands and flags. ```bash diff --git a/services/www/src/docs/content/cli/config.mdx b/services/www/src/docs/content/cli/config.mdx index d47ac65c98d..06c24ed2557 100644 --- a/services/www/src/docs/content/cli/config.mdx +++ b/services/www/src/docs/content/cli/config.mdx @@ -32,8 +32,10 @@ There is no project-local CLI settings file. Add the published JSON Schema for v } ``` -OpenCode adds `$schema` when it creates or migrates this file. Unknown settings are rejected, and valid edits reload -while the TUI is running. +OpenCode adds `$schema` when it creates or migrates this file. Valid edits reload while the TUI is running. + +Unknown settings are ignored, but an invalid value makes OpenCode ignore the whole file and use defaults, so keep +`$schema` for editor validation. Valid `OPENCODE_CLI_CONFIG_CONTENT` overrides still apply. ## Inline config diff --git a/services/www/src/docs/content/cli/keybinds.mdx b/services/www/src/docs/content/cli/keybinds.mdx index 9f94c5f240b..e579dbbda1a 100644 --- a/services/www/src/docs/content/cli/keybinds.mdx +++ b/services/www/src/docs/content/cli/keybinds.mdx @@ -76,7 +76,8 @@ Use an object for event behavior: } ``` -Unknown command IDs are rejected. +Unknown command IDs are ignored. An invalid binding makes OpenCode ignore the whole file; see +[CLI settings](/cli/config). ## Application @@ -97,6 +98,7 @@ Unknown command IDs are rejected. | `opencode.settings` | `none` | Open settings | | `server.pair` | `none` | Pair device | | `service.restart` | `none` | Restart service | +| `location.reload` | `none` | Reload configuration | ## Mini @@ -128,44 +130,49 @@ Right-click a file in the sidebar or its diff heading for **Mark complete** (or The shifted `diff.help` alternatives support terminals that report the Shift modifier when you press `?`. -| ID | Default | Description | -| ----------------------- | ------------------- | ---------------------------------------- | -| `diff.open` | `none` | Open diff viewer | -| `diff.close` | `escape,q` | Close diff viewer | -| `diff.down` | `j,down` | Move diff viewer down | -| `diff.up` | `k,up` | Move diff viewer up | -| `diff.page.down` | `pagedown,ctrl+f` | Page diff viewer down | -| `diff.page.up` | `pageup,ctrl+b` | Page diff viewer up | -| `diff.half_page.down` | `ctrl+d` | Scroll diff viewer down half a page | -| `diff.half_page.up` | `ctrl+u` | Scroll diff viewer up half a page | -| `diff.first` | `gg,home` | Go to the start of the diff | -| `diff.last` | `shift+g,end` | Go to the end of the diff | -| `diff.next_hunk` | `]` | Jump to next diff hunk | -| `diff.previous_hunk` | `[` | Jump to previous diff hunk | -| `diff.next_file` | `n,alt+down` | Jump to next diff file | -| `diff.previous_file` | `p,alt+up` | Jump to previous diff file | -| `diff.toggle_file_tree` | `b` | Toggle diff viewer file tree | -| `diff.single_patch` | `s` | Toggle single patch view | -| `diff.switch_source` | `d` | Choose the diff review scope | -| `diff.toggle_view` | `v` | Toggle diff viewer split or unified view | -| `diff.mark_reviewed` | `m` | Toggle selected diff file reviewed | -| `diff.help` | `?,shift+?,shift+/` | Show more diff viewer shortcuts | +| ID | Default | Description | +| ------------------------ | ------------------- | ---------------------------------------- | +| `diff.open` | `none` | Open diff viewer | +| `diff.close` | `escape,q` | Close diff viewer | +| `diff.down` | `j,down` | Move diff viewer down | +| `diff.up` | `k,up` | Move diff viewer up | +| `diff.page.down` | `pagedown,ctrl+f` | Page diff viewer down | +| `diff.page.up` | `pageup,ctrl+b` | Page diff viewer up | +| `diff.half_page.down` | `ctrl+d` | Scroll diff viewer down half a page | +| `diff.half_page.up` | `ctrl+u` | Scroll diff viewer up half a page | +| `diff.first` | `gg,home` | Go to the start of the diff | +| `diff.last` | `shift+g,end` | Go to the end of the diff | +| `diff.next_hunk` | `]` | Jump to next diff hunk | +| `diff.previous_hunk` | `[` | Jump to previous diff hunk | +| `diff.next_file` | `n,alt+down` | Jump to next diff file | +| `diff.previous_file` | `p,alt+up` | Jump to previous diff file | +| `diff.toggle_file_tree` | `b` | Toggle diff viewer file tree | +| `diff.single_patch` | `s` | Toggle single patch view | +| `diff.switch_source` | `d` | Choose the diff review scope | +| `diff.toggle_view` | `v` | Toggle diff viewer split or unified view | +| `diff.toggle_fullscreen` | `f` | Toggle diff viewer full screen | +| `diff.mark_reviewed` | `m` | Toggle selected diff file reviewed | +| `diff.help` | `?,shift+?,shift+/` | Show more diff viewer shortcuts | The retired `diff.toggle`, `diff.expand`, `diff.expand_all`, `diff.collapse`, and `diff.switch_focus` configuration entries are still accepted, but no longer register shortcuts. ## Appearance And Navigation -| ID | Default | Description | -| -------------------------- | ----------- | ---------------------------------------- | -| `prompt.editor` | `e` | Open external editor | -| `theme.switch` | `none` | List available themes | -| `theme.switch_mode` | `none` | Switch between light and dark theme mode | -| `theme.mode.lock` | `none` | Lock or unlock theme mode | -| `session.sidebar.toggle` | `b` | Toggle sidebar | -| `terminal.toggle` | `t` | Toggle terminal pane | -| `session.toggle.scrollbar` | `none` | Toggle session scrollbar | -| `opencode.status` | `s` | View status | -| `opencode.debug` | `none` | View debug info | +| ID | Default | Description | +| -------------------------- | --------------- | ---------------------------------------- | +| `prompt.editor` | `e` | Open external editor | +| `theme.switch` | `none` | List available themes | +| `theme.switch_mode` | `none` | Switch between light and dark theme mode | +| `theme.mode.lock` | `none` | Lock or unlock theme mode | +| `session.sidebar.toggle` | `b` | Toggle sidebar | +| `pane.focus.left` | `left` | Focus session pane | +| `pane.focus.right` | `right` | Focus right pane | +| `terminal.select` | `down` | Select terminal | +| `terminal.toggle` | `t` | Toggle terminal pane | +| `terminal.close` | `up` | Close terminal pane | +| `session.toggle.scrollbar` | `none` | Toggle session scrollbar | +| `opencode.status` | `s` | View status | +| `opencode.debug` | `none` | View debug info | ## Sessions @@ -173,6 +180,7 @@ The retired `diff.toggle`, `diff.expand`, `diff.expand_all`, `diff.collapse`, an | ------------------------------------- | ----------------------- | ---------------------------------------- | | `session.export` | `x` | Export session to editor | | `session.copy` | `none` | Copy session transcript | +| `session.copy.id` | `none` | Copy session ID | | `session.move` | `none` | Move session | | `session.new` | `n` | Create a new session | | `session.list` | `l` | List all sessions | @@ -198,6 +206,7 @@ The retired `diff.toggle`, `diff.expand`, `diff.expand_all`, `diff.collapse`, an | `queued_prompt.undo` | `ctrl+u` | Undo queued prompt | | `queued_prompt.delete` | `ctrl+d` | Delete queued prompt | | `session.toggle.exploration_grouping` | `none` | Toggle related tool call grouping | +| `session.verbosity.cycle` | `none` | Cycle transcript verbosity | | `session.child.first` | `down` | Toggle subagent picker | | `session.child.next` | `right` | Go to next child session | | `session.child.previous` | `left` | Go to previous child session | @@ -335,6 +344,9 @@ The retired `diff.toggle`, `diff.expand`, `diff.expand_all`, `diff.collapse`, an | `composer.shell.down` | `down` | Next shell | | `composer.shell.select` | `return` | View shell output | | `composer.shell.kill` | `ctrl+d` | Kill shell command | +| `composer.terminal.up` | `up,k` | Previous terminal | +| `composer.terminal.down` | `down,j` | Next terminal | +| `composer.terminal.select` | `return` | Select terminal | Select a running command in the **Shell** tab and press **Enter**, or click it, to view captured stdout and stderr. Use **↑/↓**, **Page Up/Down**, or **Home** to scroll, **End** to follow new output, and **Esc** to return without stopping the command. @@ -352,6 +364,8 @@ The viewer shows recent output and stays open after exit; output redirected to a | `dialog.select.end` | `end` | Move to last dialog item | | `dialog.select.submit` | `return` | Submit selected dialog item | | `dialog.prompt.submit` | `return` | Submit dialog prompt | +| `dialog.integration.rename` | `ctrl+r` | Rename integration account | +| `dialog.integration.delete` | `ctrl+d` | Delete integration account | | `dialog.worktree.generate` | `tab` | Generate worktree name | | `dialog.move_session.new` | `ctrl+a` | New worktree | | `dialog.move_session.move` | `ctrl+m` | Move session to worktree | @@ -365,6 +379,7 @@ The viewer shows recent output and stays open after exit; output redirected to a | `permission.prompt.fullscreen` | `ctrl+f` | Toggle permission prompt fullscreen | | `plugins.toggle` | `return` | Toggle plugin | | `dialog.mcp.toggle` | `space` | Toggle MCP server | +| `dialog.plugins.error` | `space` | View plugin error | | `dialog.plugins.update` | `ctrl+u` | Update plugin from plugin dialog | | `dialog.plugins.check` | `ctrl+r` | Check for plugin updates | diff --git a/services/www/src/docs/content/compaction.mdx b/services/www/src/docs/content/compaction.mdx index aa9c7f6bc10..40c989039f4 100644 --- a/services/www/src/docs/content/compaction.mdx +++ b/services/www/src/docs/content/compaction.mdx @@ -88,10 +88,25 @@ Add `compaction` to any [OpenCode configuration file](/config): `keep.tokens` and `buffer` accept non-negative integers. +## Model + +By default OpenCode writes the summary itself, using the session's model. Set +`agents.compaction.model` to use another model for summaries: + +```jsonc title="opencode.jsonc" +{ + "$schema": "https://opencode.ai/config.json", + "agents": { + "compaction": { "model": "anthropic/claude-sonnet-5-5" }, + }, +} +``` + +If that model cannot be resolved, OpenCode falls back to the session's model. + ## Providers -By default OpenCode writes the summary itself, using the session's model. Some -providers can compact the conversation on their side instead. Enable it per +Some providers can compact the conversation on their side instead. Enable it per provider or model with `settings.compaction`: ```jsonc title="opencode.jsonc" @@ -153,7 +168,7 @@ session's baseline; see [Instructions](/instructions). | Limit | Result | | --- | --- | -| Model | Compaction uses the session's model. There is no separate compaction model. | +| Model | Summary compaction honors `agents.compaction.model`; otherwise it uses the session's model. Native compaction always uses the session's model. | | History | Compaction needs older conversation to replace. It cannot create room when a request is mostly fixed instructions and tool schemas. | | Size | If the conversation to compact is itself too long, OpenCode sends a shortened text version and may leave out the oldest exchanges. | | Recovery | A request rejected as too long is compacted and retried once. A second rejection is returned as an error. | diff --git a/services/www/src/docs/content/migrate-v1.mdx b/services/www/src/docs/content/migrate-v1.mdx index e1b22c3f4fa..6befce6da6c 100644 --- a/services/www/src/docs/content/migrate-v1.mdx +++ b/services/www/src/docs/content/migrate-v1.mdx @@ -176,8 +176,30 @@ V2 config: ``` `prompt` becomes `system`, `disable` becomes `disabled`, and a separate `variant` joins the model reference after `#`. -`temperature`, `top_p`, and provider-specific `options` move under `request.body`. `maxSteps` becomes `steps`. Entries from -the old `mode` map become primary agents. +`maxSteps` becomes `steps`. Entries from the old `mode` map become primary agents. + +Agent [`request.body`](/agents#request) is kept but not sent to the model, so V1 `temperature`, `top_p`, and `options` +have no effect there. Set them on a model variant instead. DeepSeek only applies `temperature` with thinking off, so +this variant turns thinking off too: + +```jsonc title="opencode.jsonc" +{ + "providers": { + "opencode": { + "models": { + "deepseek-v4.1-flash": { + "variants": [{ "id": "review", "body": { "thinking": { "type": "disabled" }, "temperature": 0.2 } }], + }, + }, + }, + }, + "agents": { + "reviewer": { "model": "opencode/deepseek-v4.1-flash#review" }, + }, +} +``` + +Use `body` for provider JSON fields and `settings` for provider package options. See [model options](/models#options). ### Snapshots @@ -477,7 +499,7 @@ When converting the frontmatter to native V2 fields: - Rename `prompt` to `system` when it appears in JSON configuration; file bodies do not need a `system` field. - Rename `disable` to `disabled` and `permission` to `permissions`. - Join `model` and `variant` as `provider/model#variant`. -- Move `temperature`, `top_p`, and provider-specific options under `request.body`. +- Set sampling and provider options on a model variant, as shown [above](#agents-and-modes). V1 agent frontmatter is deprecated but still translated automatically. Each file is read as one format. A file that uses any of `permissions`, `request`, `system`, or `disabled` is read as V2, and V1 fields in it, such as `name`, @@ -559,7 +581,7 @@ Rename `plugin` to `plugins`. Replace a package-and-options tuple with an object "plugins": [ "opencode-example-plugin", { - "package": "./plugin/local.ts", + "package": "./plugin/local", "options": { "enabled": true } } ] @@ -567,6 +589,7 @@ Rename `plugin` to `plugins`. Replace a package-and-options tuple with an object ``` V2 discovers local plugins from both `.opencode/plugin/` and `.opencode/plugins/`; use `.opencode/plugins/` for V2 files. +Configured local paths must be directories, so move the ported plugin to `./plugin/local/index.ts`. V1 plugin implementations do not run in V2. Moving a file or renaming its config entry is not enough. diff --git a/services/www/src/docs/content/plugins.mdx b/services/www/src/docs/content/plugins.mdx index 4901d3d17c4..9356cd1ca49 100644 --- a/services/www/src/docs/content/plugins.mdx +++ b/services/www/src/docs/content/plugins.mdx @@ -14,8 +14,8 @@ Add published packages, versioned packages, scoped packages, or local plugin dir "opencode-acme-plugin@1.2.0", "@acme/opencode-plugin", "./plugins/local", - "../shared/plugin.ts", - "/absolute/path/plugin.ts", + "../shared/plugin", + "/absolute/path/plugin", "file:///home/me/plugins/local", { "package": "@acme/opencode-plugin", @@ -28,8 +28,12 @@ Add published packages, versioned packages, scoped packages, or local plugin dir } ``` -Relative paths resolve from the config file containing the entry. Plugin arrays from applicable config files are applied -from lowest to highest precedence instead of replacing one another. +Relative paths resolve from the config file containing the entry. + +Configured local paths must be directories. OpenCode loads the directory's `server` or `index` module, such as +`index.ts`. A path to a single file is skipped. + +Plugin arrays from applicable config files are applied from lowest to highest precedence instead of replacing one another. ```text ~/.config/opencode/opencode.jsonc @@ -56,8 +60,8 @@ Global plugins use the same discovery layout under the OpenCode config directory ~/.config/opencode/plugins/ ``` -A `plugins/` directory beside a project-root `opencode.json(c)` is not discovered automatically; configure its files -explicitly or move it under `.opencode/`. +A `plugins/` directory beside a project-root `opencode.json(c)` is not discovered automatically; configure its plugin +directories explicitly or move it under `.opencode/`. ```jsonc title="opencode.jsonc" { diff --git a/services/www/src/docs/content/providers.mdx b/services/www/src/docs/content/providers.mdx index 604b748b020..d2a69e80c35 100644 --- a/services/www/src/docs/content/providers.mdx +++ b/services/www/src/docs/content/providers.mdx @@ -134,7 +134,7 @@ Both fields can also be set on a model or variant when only part of a provider's ## Timeouts -HTTP requests wait up to five minutes for response headers and up to five minutes between streamed response chunks. +HTTP requests wait up to five minutes for response headers and up to fifteen minutes between streamed response chunks. Set the provider's `settings.headerTimeout` or `settings.chunkTimeout` to a number of milliseconds to change a limit, or to `false` to disable it. `settings.timeout` additionally bounds the whole request from send until the response completes; it has no default. These configuration settings apply provider-wide, not per model or variant. On a @@ -556,7 +556,7 @@ OpenRouter account, then refer to models with the full OpenRouter model ID after ```jsonc title="opencode.jsonc" { "$schema": "https://opencode.ai/config.json", - "model": "openrouter/anthropic/claude-sonnet-4", + "model": "openrouter/anthropic/claude-sonnet-5.5", } ```