Skip to content

docs(www): fix outdated V2 docs #58280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Tarquinen merged 1 commit into from
Oct 23, 2026
Merged

docs(www): fix outdated V2 docs #58280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions services/www/src/docs/content/attachments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
31 changes: 31 additions & 0 deletions services/www/src/docs/content/cli/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions services/www/src/docs/content/cli/config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
83 changes: 49 additions & 34 deletions services/www/src/docs/content/cli/keybinds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -128,51 +130,57 @@ 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` | `<leader>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` | `<leader>b` | Toggle sidebar |
| `terminal.toggle` | `<leader>t` | Toggle terminal pane |
| `session.toggle.scrollbar` | `none` | Toggle session scrollbar |
| `opencode.status` | `<leader>s` | View status |
| `opencode.debug` | `none` | View debug info |
| ID | Default | Description |
| -------------------------- | --------------- | ---------------------------------------- |
| `prompt.editor` | `<leader>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` | `<leader>b` | Toggle sidebar |
| `pane.focus.left` | `<leader>left` | Focus session pane |
| `pane.focus.right` | `<leader>right` | Focus right pane |
| `terminal.select` | `<leader>down` | Select terminal |
| `terminal.toggle` | `<leader>t` | Toggle terminal pane |
| `terminal.close` | `<leader>up` | Close terminal pane |
| `session.toggle.scrollbar` | `none` | Toggle session scrollbar |
| `opencode.status` | `<leader>s` | View status |
| `opencode.debug` | `none` | View debug info |

## Sessions

| ID | Default | Description |
| ------------------------------------- | ----------------------- | ---------------------------------------- |
| `session.export` | `<leader>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` | `<leader>n` | Create a new session |
| `session.list` | `<leader>l` | List all sessions |
Expand All @@ -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 |
Expand Down Expand Up @@ -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.
Expand All @@ -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 |
Expand All @@ -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 |

Expand Down
21 changes: 18 additions & 3 deletions services/www/src/docs/content/compaction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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. |
Expand Down
31 changes: 27 additions & 4 deletions services/www/src/docs/content/migrate-v1.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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`,
Expand Down Expand Up @@ -559,14 +581,15 @@ 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 }
}
]
}
```

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`.

<Callout type="warning">
V1 plugin implementations do not run in V2. Moving a file or renaming its config entry is not enough.
Expand Down
Loading
Loading