editing docs

www/astro.config.mjs

@@ -29,6 +29,9 @@ export default defineConfig({
 			editLink: {
 				baseUrl: `${github}/edit/master/www/`,
 			},
+			markdown: {
+				headingLinks: false,
+			},
 			logo: {
 				light: "./src/assets/logo-light.svg",
 				dark: "./src/assets/logo-dark.svg",

www/src/content/docs/docs/cli.mdx

@@ -2,75 +2,88 @@
 title: CLI
 ---
 
-## Usage
+Once installed you can run the OpenCode CLI.
 
 ```bash
-# Start OpenCode
 opencode
+```
+
+Or pass in flags. For example, to start with debug logging:
 
-# Start with debug logging
+```bash
 opencode -d
+```
+
+Or start with a specific working directory.
 
-# Start with a specific working directory
+```bash
 opencode -c /path/to/project
 ```
 
-## Non-interactive Prompt Mode
+## Flags 
 
-You can 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.
+The OpenCode CLI takes the following flags.
 
-```bash
-# Run a single prompt and print the AI's response to the terminal
+| 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 |
+
+## Non-interactive
+
+By default, OpenCode runs in interactive mode.
+
+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.
+
+For example, to run a single prompt use the `-p` flag.
+
+```bash "-p"
 opencode -p "Explain the use of context in Go"
+```
 
-# Get response in JSON format
-opencode -p "Explain the use of context in Go" -f json
+If you want to run without showing the spinner, use `-q`.
 
-# Run without showing the spinner
+```bash "-q"
 opencode -p "Explain the use of context in Go" -q
+```
 
-# Enable verbose logging to stderr
-opencode -p "Explain the use of context in Go" --verbose
+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.
 
-# Restrict the agent to only use specific tools
-opencode -p "Explain the use of context in Go" --allowedTools=view,ls,glob
+#### Tool restrictions
 
-# Prevent the agent from using specific tools
-opencode -p "Explain the use of context in Go" --excludedTools=bash,edit
-```
+You can control which tools the AI assistant has access to in non-interactive mode.
 
-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.
+- `--allowedTools`
 
-### Tool Restrictions
+  A comma-separated list of tools that the agent is allowed to use. Only these tools will be available.
 
-You can control which tools the AI assistant has access to in non-interactive mode:
+  ```bash "--allowedTools"
+  opencode -p "Explain the use of context in Go" --allowedTools=view,ls,glob
+  ```
 
-- `--allowedTools`: Comma-separated list of tools that the agent is allowed to use. Only these tools will be available.
-- `--excludedTools`: Comma-separated list of tools that the agent is not allowed to use. All other tools will be available.
+- `--excludedTools`
 
-These flags are mutually exclusive - you can use either `--allowedTools` or `--excludedTools`, but not both at the same time.
+  Comma-separated list of tools that the agent is not allowed to use. All other tools will be available.
 
-### Output Formats
+  ```bash "--excludedTools"
+  opencode -p "Explain the use of context in Go" --excludedTools=bash,edit
+  ```
 
-OpenCode supports the following output formats in non-interactive mode:
+These flags are mutually exclusive. So you can either use `--allowedTools` or `--excludedTools`, but not both.
 
-| Format | Description                            |
-| ------ | -------------------------------------- |
-| `text` | Plain text output (default)            |
-| `json` | Output wrapped in a JSON object        |
+#### Output formats
 
-The output format is implemented as a strongly-typed `OutputFormat` in the codebase, ensuring type safety and validation when processing outputs.
+In non-interactive mode, you can also set the CLI to return as JSON using `-f`.
 
-## Command-line Flags
+```bash "-f json"
+opencode -p "Explain the use of context in Go" -f json
+```
 
-| Flag              | Short | Description                                                |
-| ----------------- | ----- | ---------------------------------------------------------- |
-| `--help`          | `-h`  | Display help information                                   |
-| `--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, 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               |
+By default, this is set to `text`, to return plain text.

www/src/content/docs/docs/config.mdx

@@ -2,32 +2,18 @@
 title: Config
 ---
 
-OpenCode looks for configuration in the following locations:
+You can configure OpenCode using the OpenCode config. It can be places in:
 
 - `$HOME/.opencode.json`
 - `$XDG_CONFIG_HOME/opencode/.opencode.json`
-- `./.opencode.json` (local directory)
 
-## Environment variables
-
-You can configure OpenCode using environment variables:
-
-| Environment Variable       | Purpose                                                |
-| -------------------------- | ------------------------------------------------------ |
-| `ANTHROPIC_API_KEY`        | For Claude models                                      |
-| `OPENAI_API_KEY`           | For OpenAI models                                      |
-| `GEMINI_API_KEY`           | For Google Gemini models                               |
-| `GROQ_API_KEY`             | For Groq models                                        |
-| `AWS_ACCESS_KEY_ID`        | For AWS Bedrock (Claude)                               |
-| `AWS_SECRET_ACCESS_KEY`    | For AWS Bedrock (Claude)                               |
-| `AWS_REGION`               | For AWS Bedrock (Claude)                               |
-| `AZURE_OPENAI_ENDPOINT`    | For Azure OpenAI models                                |
-| `AZURE_OPENAI_API_KEY`     | For Azure OpenAI models (optional when using Entra ID) |
-| `AZURE_OPENAI_API_VERSION` | For Azure OpenAI models                                |
+Or in the current directory, `./.opencode.json`.
 
 ## OpenCode config
 
-```json
+The config file has the following structure.
+
+```json title=".opencode.json"
 {
   "data": {
     "directory": ".opencode"
@@ -82,3 +68,21 @@ You can configure OpenCode using environment variables:
   "debugLSP": false
 }
 ```
+
+## Environment variables
+
+For the providers, you can also specify the keys using environment variables.
+
+| 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 |
+

www/src/content/docs/docs/index.mdx

@@ -1,16 +1,33 @@
 ---
-title: Get started
+title: Intro
 ---
 
+OpenCode is an AI coding agent built natively for the terminal. It features:
+
+- 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
+
 ## Installation
 
+```bash
+npm i -g opencode
+```
+
+If you don't have NPM installed, you can also install the OpenCode binary through the following.
+
 #### Using the install script
 
 ```bash
-# Install the latest version
 curl -fsSL https://opencode.ai/install | bash
+```
 
-# Install a specific version
+Or install a specific version.
+
+```bash
 curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash
 ```
 
@@ -20,13 +37,17 @@ curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash
 brew install sst/tap/opencode
 ```
 
-#### Using AUR (Arch Linux)
+#### Using AUR in Arch Linux
+
+With yay.
 
 ```bash
-# Using yay
 yay -S opencode-bin
+```
+
+Or with paru.
 
-# Using paru
+```bash
 paru -S opencode-bin
 ```
 

www/src/content/docs/docs/lsp-servers.mdx

@@ -2,19 +2,22 @@
 title: LSP servers
 ---
 
-OpenCode integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.
+OpenCode integrates with _Language Server Protocol_, or LSP to improve how the LLM interacts with your codebase.
 
-### LSP Features
+LSP servers for different languages give the LLM:
 
-- **Multi-language Support**: Connect to language servers for different programming languages
-- **Diagnostics**: Receive error checking and linting information
-- **File Watching**: Automatically notify language servers of file changes
+- **Diagnostics**: These include things like errors and lint warnings. So the LLM can generate code that has fewer mistakes without having to run the code.
+- **Quick actions**: The LSP can allow the LLM to better navigate the codebase through features like _go-to-definition_ and _find references_.
 
-### Configuring LSP
+## Auto-detection
 
-Language servers are configured in the configuration file under the `lsp` section:
+By default, OpenCode will **automatically detect** the languages used in your project and add the right LSP servers.
 
-```json
+## Manual configuration
+
+You can also manually configure LSP servers by adding them under the `lsp` section in your OpenCode config.
+
+```json title=".opencode.json"
 {
   "lsp": {
     "go": {
@@ -28,12 +31,4 @@ Language servers are configured in the configuration file under the `lsp` sectio
     }
   }
 }
-
-### LSP Integration with AI
-
-The AI assistant can access LSP features through the `diagnostics` tool, allowing it to:
-
-- Check for errors in your code
-- Suggest fixes based on diagnostics
-
-While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.
+```

www/src/content/docs/docs/mcp-servers.mdx

@@ -2,31 +2,40 @@
 title: MCP servers
 ---
 
-OpenCode implements the Model Context Protocol (MCP) to extend its capabilities through external tools. MCP provides a standardized way for the AI assistant to interact with external services and tools.
+You can add external tools to OpenCode using the _Model Context Protocol_, or MCP. OpenCode supports both:
 
-### MCP Features
+- Local servers that use standard input/output, `stdio`
+- Remote servers that use server-sent events `sse`
 
-- **External Tool Integration**: Connect to external tools and services via a standardized protocol
-- **Tool Discovery**: Automatically discover available tools from MCP servers
-- **Multiple Connection Types**:
-  - **Stdio**: Communicate with tools via standard input/output
-  - **SSE**: Communicate with tools via Server-Sent Events
-- **Security**: Permission system for controlling access to MCP tools
+## Add MCP servers
 
-### Configuring MCP Servers
+You can define MCP servers in your OpenCode config under the `mcpServers` section:
 
-MCP servers are defined in the configuration file under the `mcpServers` section:
+### Local
 
-```json
+To add a local or `stdio` MCP server.
+
+```json title=".opencode.json" {4}
 {
   "mcpServers": {
-    "example": {
+    "local-example": {
       "type": "stdio",
       "command": "path/to/mcp-server",
       "env": [],
       "args": []
-    },
-    "web-example": {
+    }
+  }
+}
+```
+
+### Remote
+
+To add a remote or `sse` MCP server.
+
+```json title=".opencode.json" {4}
+{
+  "mcpServers": {
+    "remote-example": {
       "type": "sse",
       "url": "https://example.com/mcp",
       "headers": {
@@ -37,6 +46,6 @@ MCP servers are defined in the configuration file under the `mcpServers` section
 }
 ```
 
-### MCP Tool Usage
+## Usage
 
-Once configured, MCP tools are automatically available to the AI assistant alongside built-in tools. They follow the same permission model as other tools, requiring user approval before execution.
+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.

www/src/content/docs/docs/models.mdx

@@ -2,87 +2,33 @@
 title: Models
 ---
 
-## Supported AI Models
+OpenCode uses the [AI SDK](https://ai-sdk.dev/) to have the support for **all the AI models**.
 
-OpenCode supports a variety of AI models from different providers:
+Start by setting the [keys for the providers](/docs/config) you want to use in your OpenCode config.
 
-### OpenAI
+## Model select
 
-- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
-- GPT-4.5 Preview
-- GPT-4o family (gpt-4o, gpt-4o-mini)
-- O1 family (o1, o1-pro, o1-mini)
-- O3 family (o3, o3-mini)
-- O4 Mini
+You can now select the model you want from the menu by hitting `Ctrl+O`.
 
-### Anthropic
+## Multiple models
 
-- Claude 3.5 Sonnet
-- Claude 3.5 Haiku
-- Claude 3.7 Sonnet
-- Claude 3 Haiku
-- Claude 3 Opus
+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.
 
-### Google
-
-- Gemini 2.5
-- Gemini 2.5 Flash
-- Gemini 2.0 Flash
-- Gemini 2.0 Flash Lite
-
-### AWS Bedrock
-
-- Claude 3.7 Sonnet
-
-### Groq
-
-- Llama 4 Maverick (17b-128e-instruct)
-- Llama 4 Scout (17b-16e-instruct)
-- QWEN QWQ-32b
-- Deepseek R1 distill Llama 70b
-- Llama 3.3 70b Versatile
-
-### Azure OpenAI
-
-- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
-- GPT-4.5 Preview
-- GPT-4o family (gpt-4o, gpt-4o-mini)
-- O1 family (o1, o1-mini)
-- O3 family (o3, o3-mini)
-- O4 Mini
-
-### Google Cloud VertexAI
-
-- Gemini 2.5
-- Gemini 2.5 Flash
-
-## Using Bedrock Models
-
-To use bedrock models with OpenCode you need three things.
-
-1. Valid AWS credentials (the env vars: `AWS_SECRET_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_REGION`)
-2. Access to the corresponding model in AWS Bedrock in your region.
-    a. You can request access in the AWS console on the Bedrock -> "Model access" page.
-3. A correct configuration file. You don't need the `providers` key. Instead you have to prefix your models per agent with `bedrock.` and then a valid model. For now only Claude 3.7 is supported.
-
-```json
+```json title=".opencode.json"
 {
   "agents": {
     "primary": {
-      "model": "bedrock.claude-3.7-sonnet",
-      "maxTokens": 5000,
-      "reasoningEffort": ""
+      "model": "gpt-4",
+      "maxTokens": 5000
     },
     "task": {
-      "model": "bedrock.claude-3.7-sonnet",
-      "maxTokens": 5000,
-      "reasoningEffort": ""
+      "model": "gpt-3.5-turbo",
+      "maxTokens": 5000
     },
     "title": {
-      "model": "bedrock.claude-3.7-sonnet",
-      "maxTokens": 80,
-      "reasoningEffort": ""
+      "model": "gpt-3.5-turbo",
+      "maxTokens": 80
     }
-  },
+  }
 }
 ```

www/src/content/docs/docs/shortcuts.mdx

@@ -4,7 +4,9 @@ sidebar:
   label: Shortcuts
 ---
 
-### Global Shortcuts
+Below are a list of keyboard shortcuts that OpenCode supports.
+
+## Global
 
 | Shortcut | Action                                                  |
 | -------- | ------------------------------------------------------- |
@@ -17,7 +19,7 @@ sidebar:
 | `Ctrl+O` | Toggle model selection dialog                           |
 | `Esc`    | Close current overlay/dialog or return to previous mode |
 
-### Chat Page Shortcuts
+## Chat pane
 
 | Shortcut | Action                                  |
 | -------- | --------------------------------------- |
@@ -26,7 +28,7 @@ sidebar:
 | `i`      | Focus editor (when not in writing mode) |
 | `Esc`    | Exit writing mode and focus messages    |
 
-### Editor Shortcuts
+## Editor view
 
 | Shortcut            | Action                                    |
 | ------------------- | ----------------------------------------- |
@@ -35,7 +37,7 @@ sidebar:
 | `Ctrl+E`            | Open external editor                      |
 | `Esc`               | Blur editor and focus messages            |
 
-### Session Dialog Shortcuts
+## Session dialog
 
 | Shortcut   | Action           |
 | ---------- | ---------------- |
@@ -44,7 +46,7 @@ sidebar:
 | `Enter`    | Select session   |
 | `Esc`      | Close dialog     |
 
-### Model Dialog Shortcuts
+## Model dialog
 
 | Shortcut   | Action            |
 | ---------- | ----------------- |
@@ -54,7 +56,7 @@ sidebar:
 | `→` or `l` | Next provider     |
 | `Esc`      | Close dialog      |
 
-### Permission Dialog Shortcuts
+## Permission dialog
 
 | Shortcut                | Action                       |
 | ----------------------- | ---------------------------- |
@@ -64,9 +66,3 @@ sidebar:
 | `a`                     | Allow permission             |
 | `A`                     | Allow permission for session |
 | `d`                     | Deny permission              |
-
-### Logs Page Shortcuts
-
-| Shortcut           | Action              |
-| ------------------ | ------------------- |
-| `Backspace` or `q` | Return to chat page |

www/src/content/docs/docs/themes.mdx

@@ -2,13 +2,13 @@
 title: Themes
 ---
 
-OpenCode supports multiple themes for customizing the appearance of the terminal interface.
+OpenCode supports most common terminal themes and you can create your own custom theme.
 
-### Available Themes
+## Built-in themes
 
 The following predefined themes are available:
 
-- `opencode` (default)
+- `opencode`
 - `catppuccin`
 - `dracula`
 - `flexoki`
@@ -17,13 +17,15 @@ The following predefined themes are available:
 - `onedark`
 - `tokyonight`
 - `tron`
-- `custom` (user-defined)
+- `custom`
 
-### Setting a Theme
+Where `opencode` is the default theme and `custom` let's you define your own theme.
 
-You can set a theme in your `.opencode.json` configuration file:
+## Setting a theme
 
-```json
+You can set your theme in your OpenCode config.
+
+```json title=".opencode.json"
 {
   "tui": {
     "theme": "monokai"
@@ -31,11 +33,11 @@ You can set a theme in your `.opencode.json` configuration file:
 }
 ```
 
-### Custom Themes
+## Create a theme
 
-You can define your own custom theme by setting the `theme` to `"custom"` and providing color definitions in the `customTheme` map:
+You can create your own custom theme by setting the `theme: custom` and providing color definitions through the `customTheme`.
 
-```json
+```json title=".opencode.json"
 {
   "tui": {
     "theme": "custom",
@@ -49,23 +51,25 @@ You can define your own custom theme by setting the `theme` to `"custom"` and pr
 }
 ```
 
-#### Color Definition Formats
+#### Color keys
 
-Custom theme colors support two formats:
+You can define any of the following color keys in your `customTheme`.
 
-1. **Simple Hex String**: A single hex color string (e.g., `"#aabbcc"`) that will be used for both light and dark terminal backgrounds.
+| Type | Color keys |
+| --- | --- |
+| Base colors | `primary`, `secondary`, `accent` |
+| Status colors | `error`, `warning`, `success`, `info` |
+| Text colors | `text`, `textMuted`, `textEmphasized` |
+| Background colors | `background`, `backgroundSecondary`, `backgroundDarker` |
+| Border colors | `borderNormal`, `borderFocused`, `borderDim` |
+| Diff view colors | `diffAdded`, `diffRemoved`, `diffContext`, etc. |
 
-2. **Adaptive Object**: An object with `dark` and `light` keys, each holding a hex color string. This allows for adaptive colors based on the terminal's background.
+You don't need to define all the color keys. Any undefined colors will fall back to the default `opencode` theme colors.
 
-#### Available Color Keys
+#### Color definitions
 
-You can define any of the following color keys in your `customTheme`:
+Color keys can take:
 
-- Base colors: `primary`, `secondary`, `accent`
-- Status colors: `error`, `warning`, `success`, `info`
-- Text colors: `text`, `textMuted`, `textEmphasized`
-- Background colors: `background`, `backgroundSecondary`, `backgroundDarker`
-- Border colors: `borderNormal`, `borderFocused`, `borderDim`
-- Diff view colors: `diffAdded`, `diffRemoved`, `diffContext`, etc.
+1. **Hex string**: A single hex color string, like `"#aabbcc"`, that'll be used for both light and dark terminal backgrounds.
 
-You don't need to define all colors. Any undefined colors will fall back to the default "opencode" theme colors.
+2. **Light and dark colors**: An object with `dark` and `light` hex colors that'll be set based on the terminal's background.