docs: edits

10 files changed, 332 insertions, 323 deletions

diff --git a/packages/web/src/content/docs/docs/cli.mdx b/packages/web/src/content/docs/docs/cli.mdx
index af1016152..fce59263f 100644
--- a/packages/web/src/content/docs/docs/cli.mdx
+++ b/packages/web/src/content/docs/docs/cli.mdx
@@ -2,88 +2,119 @@
 title: CLI
 ---
 
-Once installed you can run the OpenCode CLI.
+Running the opencode CLI starts it for the current directory.
 
 ```bash
 opencode
 ```
 
-Or pass in flags. For example, to start with debug logging:
+Or you can start it for a specific working directory.
 
 ```bash
-opencode -d
+opencode /path/to/project
 ```
 
-Or start with a specific working directory.
+---
+
+## Commands
+
+The opencode CLI also has the following commands.
+
+### run
+
+Run opencode in non-interactive mode by passing a prompt directly.
 
 ```bash
-opencode -c /path/to/project
+opencode run [message..]
 ```
 
-## Flags
+This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
+
+```bash "opencode run"
+opencode run Explain the use of context in Go
+```
 
-The OpenCode CLI takes the following flags.
+#### Flags
 
-| Flag              | Short | Description                                              |
-| ----------------- | ----- | -------------------------------------------------------- |
-| `--help`          | `-h`  | Display help                                             |
-| `--debug`         | `-d`  | Enable debug mode                                        |
-| `--cwd`           | `-c`  | Set current working directory                            |
-| `--prompt`        | `-p`  | Run a single prompt in non-interactive mode              |
-| `--output-format` | `-f`  | Output format for non-interactive mode, `text` or `json` |
-| `--quiet`         | `-q`  | Hide spinner in non-interactive mode                     |
-| `--verbose`       |       | Display logs to stderr in non-interactive mode           |
-| `--allowedTools`  |       | Restrict the agent to only use specified tools           |
-| `--excludedTools` |       | Prevent the agent from using specified tools             |
+| Flag              | Short | Description |
+| ----------------- | ----- | --------------------- |
+| `--continue`          | `-c`  | Continue the last session |
+| `--session`          | `-s`  | Session ID to continue |
+| `--share`          |   | Share the session |
+| `--model`          | `-m`  | Mode to use in the form of provider/model |
 
-## Non-interactive
+---
+
+### auth
 
-By default, OpenCode runs in interactive mode.
+Command to manage credentials and login for providers.
+
+```bash
+opencode auth [command]
+```
 
-But you can also run OpenCode in non-interactive mode by passing a prompt directly as a command-line argument. This is useful for scripting, automation, or when you want a quick answer without launching the full TUI.
+#### login
 
-For example, to run a single prompt use the `-p` flag.
+Logs you into a provider and saves them in the credentials file in `~/.local/share/opencode/auth.json`.
 
-```bash "-p"
-opencode -p "Explain the use of context in Go"
+```bash
+opencode auth login
 ```
 
-If you want to run without showing the spinner, use `-q`.
+When opencode starts up it will loads the providers from the credentials file. And if there are any keys defined in your environments or a `.env` file in your project.
+
+#### list
+
+Lists all the authenticated providers as stored in the credentials file.
 
-```bash "-q"
-opencode -p "Explain the use of context in Go" -q
+```bash
+opencode auth list
 ```
 
-In this mode, OpenCode will process your prompt, print the result to standard output, and then exit. All **permissions are auto-approved** for the session.
+Or the short version.
 
-#### Tool restrictions
+```bash
+opencode auth ls
+```
 
-You can control which tools the AI assistant has access to in non-interactive mode.
+#### logout
 
-- `--allowedTools`
+Logs you out of a provider by clearing it from the credentials file.
 
-  A comma-separated list of tools that the agent is allowed to use. Only these tools will be available.
+```bash
+opencode auth logout
+```
 
-  ```bash "--allowedTools"
-  opencode -p "Explain the use of context in Go" --allowedTools=view,ls,glob
-  ```
+---
 
-- `--excludedTools`
+### upgrade
 
-  Comma-separated list of tools that the agent is not allowed to use. All other tools will be available.
+Updates opencode to the latest version or a specific version.
 
-  ```bash "--excludedTools"
-  opencode -p "Explain the use of context in Go" --excludedTools=bash,edit
-  ```
+```bash
+opencode upgrade [target]
+```
 
-These flags are mutually exclusive. So you can either use `--allowedTools` or `--excludedTools`, but not both.
+To upgrade to the latest version.
 
-#### Output formats
+```bash
+opencode upgrade
+```
 
-In non-interactive mode, you can also set the CLI to return as JSON using `-f`.
+To upgrade to a specific version.
 
-```bash "-f json"
-opencode -p "Explain the use of context in Go" -f json
+```bash
+opencode upgrade v0.1.48
 ```
 
-By default, this is set to `text`, to return plain text.
+---
+
+## Flags
+
+The opencode CLI takes the following flags.
+
+| Flag              | Short | Description |
+| ----------------- | ----- | --------------------- |
+| `--help`          | `-h`  | Display help |
+| `--version`       |       | Print version number |
+| `--print-logs`    |       | Print logs to stderr |
diff --git a/packages/web/src/content/docs/docs/config.mdx b/packages/web/src/content/docs/docs/config.mdx
index 9617612d0..74b450660 100644
--- a/packages/web/src/content/docs/docs/config.mdx
+++ b/packages/web/src/content/docs/docs/config.mdx
@@ -2,86 +2,28 @@
 title: Config
 ---
 
-You can configure OpenCode using the OpenCode config. It can be places in:
+You can configure opencode using a JSON config file that can be placed in:
 
-- `$HOME/.opencode.json`
-- `$XDG_CONFIG_HOME/opencode/.opencode.json`
+- Globally under `~/.config/opencode/config.json`.
+- Your project root under `opencode.json`. This is safe to checked into Git and uses the same schema as the global one.
 
-Or in the current directory, `./.opencode.json`.
-
-## OpenCode config
-
-The config file has the following structure.
-
-```json title=".opencode.json"
+```json
 {
-  "data": {
-    "directory": ".opencode"
-  },
-  "providers": {
-    "openai": {
-      "apiKey": "your-api-key",
-      "disabled": false
-    },
-    "anthropic": {
-      "apiKey": "your-api-key",
-      "disabled": false
-    },
-    "groq": {
-      "apiKey": "your-api-key",
-      "disabled": false
-    },
-    "openrouter": {
-      "apiKey": "your-api-key",
-      "disabled": false
-    }
-  },
-  "agents": {
-    "primary": {
-      "model": "claude-3.7-sonnet",
-      "maxTokens": 5000
-    },
-    "task": {
-      "model": "claude-3.7-sonnet",
-      "maxTokens": 5000
-    },
-    "title": {
-      "model": "claude-3.7-sonnet",
-      "maxTokens": 80
-    }
-  },
-  "mcpServers": {
-    "example": {
-      "type": "stdio",
-      "command": "path/to/mcp-server",
-      "env": [],
-      "args": []
-    }
-  },
-  "lsp": {
-    "go": {
-      "disabled": false,
-      "command": "gopls"
-    }
-  },
-  "debug": false,
-  "debugLSP": false
+  "$schema": "https://opencode.ai/config.json",
+  "theme": "opencode",
+  "model": "anthropic/claude-sonnet-4-20250514",
+  "autoshare": false,
+  "autoupdate": true
 }
 ```
 
-## Environment variables
+In most cases, you'll want to use the global config for things like themes, providers, or keybinds. Having a config per project is useful if you are using different providers for your company.
+
+When opencode starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.
+
+
+## Schema
 
-For the providers, you can also specify the keys using environment variables.
+The config file has a schema that's defined in [**`opencode.ai/config.json`**](https://opencode.ai/config.json).
 
-| Environment Variable       | Models                                     |
-| -------------------------- | ------------------------------------------ |
-| `ANTHROPIC_API_KEY`        | Claude                                     |
-| `OPENAI_API_KEY`           | OpenAI                                     |
-| `GEMINI_API_KEY`           | Google Gemini                              |
-| `GROQ_API_KEY`             | Groq                                       |
-| `AWS_ACCESS_KEY_ID`        | Amazon Bedrock                             |
-| `AWS_SECRET_ACCESS_KEY`    | Amazon Bedrock                             |
-| `AWS_REGION`               | Amazon Bedrock                             |
-| `AZURE_OPENAI_ENDPOINT`    | Azure OpenAI                               |
-| `AZURE_OPENAI_API_KEY`     | Azure OpenAI, optional when using Entra ID |
-| `AZURE_OPENAI_API_VERSION` | Azure OpenAI                               |
+Your editor should be able to validate and autocomplete based on the schema.
diff --git a/packages/web/src/content/docs/docs/index.mdx b/packages/web/src/content/docs/docs/index.mdx
index e6f71be19..66ccbc9b7 100644
--- a/packages/web/src/content/docs/docs/index.mdx
+++ b/packages/web/src/content/docs/docs/index.mdx
@@ -2,57 +2,85 @@
 title: Intro
 ---
 
-OpenCode is an AI coding agent built natively for the terminal. It features:
+import { Tabs, TabItem } from '@astrojs/starlight/components';
 
-- Native TUI for a smoother, snappier experience
-- Uses LSPs to help the LLM make fewer mistakes
-- Opening multiple conversations with the same project
-- Use of any model through the AI SDK
-- Tracks and visualizes all the file changes
-- Editing longer messages with Vim
+[**opencode**](/) is an AI coding agent built for the terminal. It features:
 
-## Installation
-
-```bash
-npm i -g opencode
-```
+- A responsive, native, themeable terminal UI.
+- Automatically loads the right LSPs, so the LLMs make fewer mistakes.
+- Have multiple agents working in parallel on the same project.
+- Create shareable links to any session for reference or to debug.
+- Log in with Anthropic to use your Claude Pro or Claude Max account.
+- Supports 75+ LLM providers through [Models.dev](https://models.dev), including local models.
 
-If you don't have NPM installed, you can also install the OpenCode binary through the following.
+## Installation
 
-#### Using the install script
+<Tabs>
+  <TabItem label="npm">
+  ```bash
+  npm install -g opencode-ai
+  ```
+  </TabItem>
+  <TabItem label="Bun">
+  ```bash
+  bun install -g opencode-ai
+  ```
+  </TabItem>
+  <TabItem label="pnpm">
+  ```bash
+  pnpm install -g opencode-ai
+  ```
+  </TabItem>
+  <TabItem label="Yarn">
+  ```bash
+  yarn global add opencode-ai
+  ```
+  </TabItem>
+</Tabs>
+
+You can also install the opencode binary through the following.
+
+##### Using the install script
 
 ```bash
 curl -fsSL https://opencode.ai/install | bash
 ```
 
-Or install a specific version.
+##### Using Homebrew on macOS
 
 ```bash
-curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash
+brew install sst/tap/opencode
 ```
 
-#### Using Homebrew on macOS and Linux
+##### Using Paru on Arch Linux
 
 ```bash
-brew install sst/tap/opencode
+paru -S opencode-bin
 ```
 
-#### Using AUR in Arch Linux
+## Providers
 
-With yay.
+We recommend signing up for Claude Pro or Max, running `opencode auth login` and selecting Anthropic. It's the most cost-effective way to use opencode.
 
 ```bash
-yay -S opencode-bin
+$ opencode auth login
+
+┌  Add credential
+│
+◆  Select provider
+│  ● Anthropic (recommended)
+│  ○ OpenAI
+│  ○ Google
+│  ○ Amazon Bedrock
+│  ○ Azure
+│  ○ DeepSeek
+│  ○ Groq
+│  ...
+└
 ```
 
-Or with paru.
+opencode is powered by the provider list at [Models.dev](https://models.dev), so you can use `opencode auth login` to configure API keys for any provider you'd like to use. This is stored in `~/.local/share/opencode/auth.json`.
 
-```bash
-paru -S opencode-bin
-```
+The Models.dev dataset is also used to detect common environment variables like `OPENAI_API_KEY` to autoload that provider.
 
-#### Using Go
-
-```bash
-go install github.com/sst/opencode@latest
-```
+If there are additional providers you want to use you can submit a PR to the [Models.dev repo](https://github.com/sst/models.dev). You can also [add them to your config](/docs/config) for yourself.
diff --git a/packages/web/src/content/docs/docs/keybinds.mdx b/packages/web/src/content/docs/docs/keybinds.mdx
new file mode 100644
index 000000000..ba18fd25c
--- /dev/null
+++ b/packages/web/src/content/docs/docs/keybinds.mdx
@@ -0,0 +1,48 @@
+---
+title: Keybinds
+---
+
+opencode has a list of keybinds that you can customize through the opencode config.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "keybinds": {
+    "leader": "ctrl+x",
+    "help": "<leader>h",
+    "editor_open": "<leader>e",
+    "session_new": "<leader>n",
+    "session_list": "<leader>l",
+    "session_share": "<leader>s",
+    "session_interrupt": "esc",
+    "session_compact": "<leader>c",
+    "tool_details": "<leader>d",
+    "model_list": "<leader>m",
+    "theme_list": "<leader>t",
+    "project_init": "<leader>i",
+    "input_clear": "ctrl+c",
+    "input_paste": "ctrl+v",
+    "input_submit": "enter",
+    "input_newline": "shift+enter,ctrl+j",
+    "history_previous": "up",
+    "history_next": "down",
+    "messages_page_up": "pgup",
+    "messages_page_down": "pgdown",
+    "messages_half_page_up": "ctrl+alt+u",
+    "messages_half_page_down": "ctrl+alt+d",
+    "messages_previous": "ctrl+alt+k",
+    "messages_next": "ctrl+alt+j",
+    "messages_first": "ctrl+g",
+    "messages_last": "ctrl+alt+g",
+    "app_exit": "ctrl+c,<leader>q"
+  }
+}
+```
+
+## Leader key
+
+opencode uses a `leader` key for most keybinds. This avoids conflicts in your terminal.
+
+By default, `ctrl+x` is the leader key and most actions require you to first press the leader key and then the shortcut. For example, to start a new session you first press `ctrl+x` and then press `n`.
+
+You don't need to use a leader key for your keybinds but we recommend doing so.
diff --git a/packages/web/src/content/docs/docs/lsp-servers.mdx b/packages/web/src/content/docs/docs/lsp-servers.mdx
index cd259dea7..b409c8bee 100644
--- a/packages/web/src/content/docs/docs/lsp-servers.mdx
+++ b/packages/web/src/content/docs/docs/lsp-servers.mdx
@@ -2,7 +2,7 @@
 title: LSP servers
 ---
 
-OpenCode integrates with _Language Server Protocol_, or LSP to improve how the LLM interacts with your codebase.
+opencode integrates with _Language Server Protocol_, or LSP to improve how the LLM interacts with your codebase.
 
 LSP servers for different languages give the LLM:
 
@@ -11,13 +11,13 @@ LSP servers for different languages give the LLM:
 
 ## Auto-detection
 
-By default, OpenCode will **automatically detect** the languages used in your project and add the right LSP servers.
+By default, opencode will **automatically detect** the languages used in your project and add the right LSP servers.
 
 ## Manual configuration
 
-You can also manually configure LSP servers by adding them under the `lsp` section in your OpenCode config.
+You can also manually configure LSP servers by adding them under the `lsp` section in your opencode config.
 
-```json title=".opencode.json"
+```json title="opencode.json"
 {
   "lsp": {
     "go": {
diff --git a/packages/web/src/content/docs/docs/mcp-servers.mdx b/packages/web/src/content/docs/docs/mcp-servers.mdx
index 28c6d2ab2..6bb1557a3 100644
--- a/packages/web/src/content/docs/docs/mcp-servers.mdx
+++ b/packages/web/src/content/docs/docs/mcp-servers.mdx
@@ -2,27 +2,33 @@
 title: MCP servers
 ---
 
-You can add external tools to OpenCode using the _Model Context Protocol_, or MCP. OpenCode supports both:
+You can add external tools to opencode using the _Model Context Protocol_, or MCP. opencode supports both:
 
-- Local servers that use standard input/output, `stdio`
-- Remote servers that use server-sent events `sse`
+- Local servers
+- And remote servers
 
-## Add MCP servers
+Once added, MCP tools are automatically available to the LLM alongside built-in tools.
 
-You can define MCP servers in your OpenCode config under the `mcpServers` section:
+---
+
+## Configure
+
+You can define MCP servers in your opencode config under `mcp`.
 
 ### Local
 
-To add a local or `stdio` MCP server.
+Add a local MCP servers under `mcp.localmcp`.
 
-```json title=".opencode.json" {4}
+```json title="opencode.json"
 {
-  "mcpServers": {
-    "local-example": {
-      "type": "stdio",
-      "command": "path/to/mcp-server",
-      "env": [],
-      "args": []
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "localmcp": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command"],
+      "environment": {
+        "MY_ENV_VAR": "my_env_var_value"
+      }
     }
   }
 }
@@ -30,22 +36,16 @@ To add a local or `stdio` MCP server.
 
 ### Remote
 
-To add a remote or `sse` MCP server.
+Add a remote MCP servers under `mcp.remotemcp`.
 
-```json title=".opencode.json" {4}
+```json title="opencode.json"
 {
-  "mcpServers": {
-    "remote-example": {
-      "type": "sse",
-      "url": "https://example.com/mcp",
-      "headers": {
-        "Authorization": "Bearer token"
-      }
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "remotemcp": {
+      "type": "remote",
+      "url": "https://my-mcp-server.com"
     }
   }
 }
 ```
-
-## Usage
-
-Once added, MCP tools are automatically available to the LLM alongside built-in tools. They follow the same permission model; requiring user approval before execution.
diff --git a/packages/web/src/content/docs/docs/models.mdx b/packages/web/src/content/docs/docs/models.mdx
index c40216695..d3ddd2cb0 100644
--- a/packages/web/src/content/docs/docs/models.mdx
+++ b/packages/web/src/content/docs/docs/models.mdx
@@ -2,33 +2,88 @@
 title: Models
 ---
 
-OpenCode uses the [AI SDK](https://ai-sdk.dev/) to have the support for **all the AI models**.
+opencode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support for **75+ LLM providers** and it supports running local models.
 
-Start by setting the [keys for the providers](/docs/config) you want to use in your OpenCode config.
+---
+
+## Providers
 
-## Model select
+You can configure providers in your opencode config under the `provider` section.
 
-You can now select the model you want from the menu by hitting `Ctrl+O`.
+### Defaults
 
-## Multiple models
+Most popular providers are preloaded by default. If you've added the credentials for a provider through `opencode auth login`, they'll be available when you start opencode.
 
-You can also use specific models for specific tasks. For example, you can use a smaller model to generate the title of the conversation or to run a sub task.
+### Custom
 
-```json title=".opencode.json"
+You can add custom providers by specifying the npm package for the provider and the models you want to use.
+
+```json title="opencode.json" {5,9-11}
 {
-  "agents": {
-    "primary": {
-      "model": "gpt-4",
-      "maxTokens": 5000
-    },
-    "task": {
-      "model": "gpt-3.5-turbo",
-      "maxTokens": 5000
-    },
-    "title": {
-      "model": "gpt-3.5-turbo",
-      "maxTokens": 80
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "openrouter": {
+      "npm": "@openrouter/ai-sdk-provider",
+      "name": "OpenRouter",
+      "options": {},
+      "models": {
+        "anthropic/claude-3.5-sonnet": {
+          "name": "Claude 3.5 Sonnet"
+        }
+      }
     }
   }
 }
 ```
+
+### Local
+
+To configure a local model, specify the npm package to use and the `baseURL`.
+
+```json title="opencode.json" {5,7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "baseURL": "http://localhost:11434/v1"
+      },
+      "models": {
+        "llama2": {}
+      }
+    }
+  }
+}
+```
+
+---
+
+## Select a model
+
+If you have multiple models, you can select the model you want by typing in:
+
+```bash frame="none"
+/models
+```
+
+---
+
+## Loading models
+
+When opencode starts up, it checks for the following:
+
+1. The model list in the opencode config.
+
+   ```json title="opencode.json" {4}
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "model": "anthropic/claude-sonnet-4-20250514"
+   }
+   ```
+
+   The format here is `provider/model`.
+
+2. The last used model.
+
+3. The first model using an internal priority.
diff --git a/packages/web/src/content/docs/docs/shortcuts.mdx b/packages/web/src/content/docs/docs/shortcuts.mdx
deleted file mode 100644
index dd866e0f3..000000000
--- a/packages/web/src/content/docs/docs/shortcuts.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Keyboard shortcuts
-sidebar:
-  label: Shortcuts
----
-
-Below are a list of keyboard shortcuts that OpenCode supports.
-
-## Global
-
-| Shortcut | Action                                                  |
-| -------- | ------------------------------------------------------- |
-| `Ctrl+C` | Quit application                                        |
-| `Ctrl+?` | Toggle help dialog                                      |
-| `?`      | Toggle help dialog (when not in editing mode)           |
-| `Ctrl+L` | View logs                                               |
-| `Ctrl+A` | Switch session                                          |
-| `Ctrl+K` | Command dialog                                          |
-| `Ctrl+O` | Toggle model selection dialog                           |
-| `Esc`    | Close current overlay/dialog or return to previous mode |
-
-## Chat pane
-
-| Shortcut | Action                                  |
-| -------- | --------------------------------------- |
-| `Ctrl+N` | Create new session                      |
-| `Ctrl+X` | Cancel current operation/generation     |
-| `i`      | Focus editor (when not in writing mode) |
-| `Esc`    | Exit writing mode and focus messages    |
-
-## Editor view
-
-| Shortcut            | Action                                    |
-| ------------------- | ----------------------------------------- |
-| `Ctrl+S`            | Send message (when editor is focused)     |
-| `Enter` or `Ctrl+S` | Send message (when editor is not focused) |
-| `Ctrl+E`            | Open external editor                      |
-| `Esc`               | Blur editor and focus messages            |
-
-## Session dialog
-
-| Shortcut   | Action           |
-| ---------- | ---------------- |
-| `↑` or `k` | Previous session |
-| `↓` or `j` | Next session     |
-| `Enter`    | Select session   |
-| `Esc`      | Close dialog     |
-
-## Model dialog
-
-| Shortcut   | Action            |
-| ---------- | ----------------- |
-| `↑` or `k` | Move up           |
-| `↓` or `j` | Move down         |
-| `←` or `h` | Previous provider |
-| `→` or `l` | Next provider     |
-| `Esc`      | Close dialog      |
-
-## Permission dialog
-
-| Shortcut                | Action                       |
-| ----------------------- | ---------------------------- |
-| `←` or `left`           | Switch options left          |
-| `→` or `right` or `tab` | Switch options right         |
-| `Enter` or `space`      | Confirm selection            |
-| `a`                     | Allow permission             |
-| `A`                     | Allow permission for session |
-| `d`                     | Deny permission              |
diff --git a/packages/web/src/content/docs/docs/themes.mdx b/packages/web/src/content/docs/docs/themes.mdx
index 1a2d8c2ee..ac8f489cb 100644
--- a/packages/web/src/content/docs/docs/themes.mdx
+++ b/packages/web/src/content/docs/docs/themes.mdx
@@ -2,74 +2,47 @@
 title: Themes
 ---
 
-OpenCode supports most common terminal themes and you can create your own custom theme.
+opencode will support most common terminal themes and you'll soon be able to create your own custom theme.
 
-## Built-in themes
+---
 
-The following predefined themes are available:
+## Built-in
 
-- `opencode`
-- `catppuccin`
-- `dracula`
-- `flexoki`
-- `gruvbox`
-- `monokai`
-- `onedark`
-- `tokyonight`
-- `tron`
-- `custom`
+The following built-in themes are available:
 
-Where `opencode` is the default theme and `custom` let's you define your own theme.
+- `opencode`
 
-## Setting a theme
+  ![opencode theme](../../../assets/themes/opencode.png)
 
-You can set your theme in your OpenCode config.
+- `ayu`
 
-```json title=".opencode.json"
-{
-  "tui": {
-    "theme": "monokai"
-  }
-}
-```
+  ![ayu theme](../../../assets/themes/ayu.png)
 
-## Create a theme
+- `everforest`
 
-You can create your own custom theme by setting the `theme: custom` and providing color definitions through the `customTheme`.
+  ![everforest theme](../../../assets/themes/everforest.png)
 
-```json title=".opencode.json"
-{
-  "tui": {
-    "theme": "custom",
-    "customTheme": {
-      "primary": "#ffcc00",
-      "secondary": "#00ccff",
-      "accent": { "dark": "#aa00ff", "light": "#ddccff" },
-      "error": "#ff0000"
-    }
-  }
-}
-```
+- `tokyonight`
 
-#### Color keys
+  ![tokyonight theme](../../../assets/themes/tokyonight.png)
 
-You can define any of the following color keys in your `customTheme`.
+---
 
-| Type              | Color keys                                              |
-| ----------------- | ------------------------------------------------------- |
-| Base colors       | `primary`, `secondary`, `accent`                        |
-| Status colors     | `error`, `warning`, `success`, `info`                   |
-| Text colors       | `text`, `textMuted`                                     |
-| Background colors | `background`, `backgroundSubtle`, `backgroundElement`   |
-| Border colors     | `border`, `borderActive`, `borderSubtle`                |
-| Diff view colors  | `diffAdded`, `diffRemoved`, `diffContext`, etc.         |
+## Configure
 
-You don't need to define all the color keys. Any undefined colors will fall back to the default `opencode` theme colors.
+To select a theme, type in:
 
-#### Color definitions
+```bash frame="none"
+/themes
+```
 
-Color keys can take:
+Your selected theme will be used the next time you start opencode.
 
-1. **Hex string**: A single hex color string, like `"#aabbcc"`, that'll be used for both light and dark terminal backgrounds.
+You can also configure it in your opencode config.
 
-2. **Light and dark colors**: An object with `dark` and `light` hex colors that'll be set based on the terminal's background.
+```json title="opencode.json" {3}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "theme": "tokyonight"
+}
+```
diff --git a/packages/web/src/content/docs/index.mdx b/packages/web/src/content/docs/index.mdx
index 176520ec5..1f735db21 100644
--- a/packages/web/src/content/docs/index.mdx
+++ b/packages/web/src/content/docs/index.mdx
@@ -1,5 +1,5 @@
 ---
-title: OpenCode
+title: opencode
 description: The AI coding agent built for the terminal.
 template: splash
 hero:
@@ -8,5 +8,5 @@ hero:
   image:
     dark: ../../assets/logo-dark.svg
     light: ../../assets/logo-light.svg
-    alt: OpenCode logo
+    alt: opencode logo
 ---