docs: edit mode

packages/web/src/content/docs/docs/config.mdx

@@ -3,12 +3,9 @@ title: Config
 description: Using the opencode JSON config.
 ---
 
-You can configure opencode using a JSON config file that can be placed in:
+You can configure opencode using a JSON config file.
 
-- Globally under `~/.config/opencode/config.json`.
-- Your project root under `opencode.json`. This is safe to be checked into Git and uses the same schema as the global one.
-
-```json
+```json title="opencode config"
 {
   "$schema": "https://opencode.ai/config.json",
   "theme": "opencode",
@@ -18,60 +15,23 @@ You can configure opencode using a JSON config file that can be placed in:
 }
 ```
 
-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.
+This can be used to configure opencode globally or for a specific project.
 
 ---
 
-## Variable substitution
-
-You can use variable substitution in your config files to reference environment variables and file contents.
-
-### Environment variables
-
-Use `{env:VARIABLE_NAME}` to substitute environment variables:
-
-```json title="opencode.json"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "model": "{env:OPENCODE_MODEL}",
-  "provider": {
-    "anthropic": {
-      "api_key": "{env:ANTHROPIC_API_KEY}"
-    }
-  }
-}
-```
-
-If the environment variable is not set, it will be replaced with an empty string.
+### Global
 
-### File contents
+Place your global opencode config in `~/.config/opencode/config.json`. You'll want to use the global config for things like themes, providers, or keybinds.
 
-Use `{file:path/to/file}` to substitute the contents of a file:
-
-```json title="opencode.json"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "instructions": ["{file:./custom-instructions.md}"],
-  "provider": {
-    "openai": {
-      "api_key": "{file:~/.secrets/openai-key}"
-    }
-  }
-}
-```
+---
 
-File paths can be:
+### Per project
 
-- Relative to the config file directory
-- Absolute paths (starting with `/` or `~`)
+You can also add a `opencode.json` in your project. This is useful for configuring providers or modes specific to your project.
 
-This is useful for:
+When opencode starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.
 
-- Keeping sensitive data like API keys in separate files
-- Including large instruction files without cluttering your config
-- Sharing common configuration snippets across multiple config files
+This is also safe to be checked into Git and uses the same schema as the global one.
 
 ---
 
@@ -268,3 +228,58 @@ The `disabled_providers` option accepts an array of provider IDs. When a provide
 - It won't be loaded even if environment variables are set
 - It won't be loaded even if API keys are configured through `opencode auth login`
 - The provider's models won't appear in the model selection list
+
+---
+
+## Variables
+
+You can use variable substitution in your config files to reference environment variables and file contents.
+
+---
+
+### Env vars
+
+Use `{env:VARIABLE_NAME}` to substitute environment variables:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "{env:OPENCODE_MODEL}",
+  "provider": {
+    "anthropic": {
+      "api_key": "{env:ANTHROPIC_API_KEY}"
+    }
+  }
+}
+```
+
+If the environment variable is not set, it will be replaced with an empty string.
+
+---
+
+### Files
+
+Use `{file:path/to/file}` to substitute the contents of a file:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["{file:./custom-instructions.md}"],
+  "provider": {
+    "openai": {
+      "api_key": "{file:~/.secrets/openai-key}"
+    }
+  }
+}
+```
+
+File paths can be:
+
+- Relative to the config file directory
+- Or absolute paths starting with `/` or `~`
+
+These are useful for:
+
+- Keeping sensitive data like API keys in separate files.
+- Including large instruction files without cluttering your config.
+- Sharing common configuration snippets across multiple config files.

packages/web/src/content/docs/docs/modes.mdx

@@ -3,17 +3,33 @@ title: Modes
 description: Different modes for different use cases.
 ---
 
-Modes in opencode allow you to customize the behavior, tools, and prompts for different use cases. You can switch between modes during a session or configure them in your config file.
+Modes in opencode allow you to customize the behavior, tools, and prompts for different use cases.
 
-## Built-in modes
+It comes with two built-in modes: **build** and **plan**. You can customize
+these or configure your own through the opencode config.
 
-opencode comes with two built-in modes:
+:::tip
+Use the plan mode to analyze code and review suggestions without making any code
+changes.
+:::
 
-### Build mode (default)
+You can switch between modes during a session or configure them in your config file.
 
-The default mode with all tools enabled. This is the standard mode for development work where you need full access to file operations and system commands.
+---
+
+## Built-in
+
+opencode comes with two built-in modes.
+
+---
+
+### Build
+
+Build is the **default** mode with all tools enabled. This is the standard mode for development work where you need full access to file operations and system commands.
+
+---
 
-### Plan mode
+### Plan
 
 A restricted mode designed for planning and analysis. In plan mode, the following tools are disabled by default:
 
@@ -24,13 +40,17 @@ A restricted mode designed for planning and analysis. In plan mode, the followin
 
 This mode is useful when you want the AI to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.
 
-## Switching modes
+---
+
+## Switching
 
-You can switch between modes during a session using the `tab` key (or your configured `switch_mode` keybind).
+You can switch between modes during a session using the _Tab_ key. Or your configured `switch_mode` keybind.
 
-## Configuring modes
+---
 
-You can customize modes in your `opencode.json` config file:
+## Configure
+
+You can customize the built-in modes or create your own in the opencode [config](/docs/config).
 
 ```json title="opencode.json"
 {
@@ -52,31 +72,20 @@ You can customize modes in your `opencode.json` config file:
         "edit": false,
         "bash": false
       }
-    },
-    "review": {
-      "prompt": "{file:./prompts/code-review.txt}",
-      "tools": {
-        "write": false,
-        "edit": false,
-        "bash": false,
-        "read": true,
-        "grep": true,
-        "glob": true
-      }
     }
   }
 }
 ```
 
-## Mode configuration options
+Let's look at these options in detail.
 
-Each mode can be configured with the following options:
+---
 
-### `model`
+### Model
 
-Override the default model for this mode. Useful for using different models optimized for different tasks (e.g., a faster model for planning, a more capable model for implementation).
+Use the `model` config to override the default model for this mode. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.
 
-```json
+```json title="opencode.json"
 {
   "mode": {
     "plan": {
@@ -86,11 +95,13 @@ Override the default model for this mode. Useful for using different models opti
 }
 ```
 
-### `prompt`
+---
+
+### Prompt
 
-Specify a custom system prompt file for this mode. The prompt file should contain instructions specific to the mode's purpose.
+Specify a custom system prompt file for this mode with the `prompt` config. The prompt file should contain instructions specific to the mode's purpose.
 
-```json
+```json title="opencode.json"
 {
   "mode": {
     "review": {
@@ -100,9 +111,14 @@ Specify a custom system prompt file for this mode. The prompt file should contai
 }
 ```
 
-### `tools`
+This path is relative to where the config file is located. So this works for
+both the global opencode config and the project specific config.
+
+---
 
-Control which tools are available in this mode. You can enable or disable specific tools by setting them to `true` or `false`.
+### Tools
+
+Control which tools are available in this mode with the `tools` config. You can enable or disable specific tools by setting them to `true` or `false`.
 
 ```json
 {
@@ -121,11 +137,35 @@ Control which tools are available in this mode. You can enable or disable specif
 }
 ```
 
-## Creating custom modes
+If no tools are specified, all tools are enabled by default.
+
+---
 
-You can create your own custom modes by adding them to the `mode` configuration. For example, a documentation mode that focuses on reading and analysis:
+#### Available tools
 
-```json title="opencode.json"
+Here are all the tools can be controlled through the mode config.
+
+| Tool        | Description             |
+| ----------- | ----------------------- |
+| `bash`      | Execute shell commands  |
+| `edit`      | Modify existing files   |
+| `write`     | Create new files        |
+| `read`      | Read file contents      |
+| `grep`      | Search file contents    |
+| `glob`      | Find files by pattern   |
+| `list`      | List directory contents |
+| `patch`     | Apply patches to files  |
+| `todowrite` | Manage todo lists       |
+| `todoread`  | Read todo lists         |
+| `webfetch`  | Fetch web content       |
+
+---
+
+## Custom modes
+
+You can create your own custom modes by adding them to the `mode` configuration. For example, a documentation mode that focuses on reading and analysis.
+
+```json title="opencode.json" {4-14}
 {
   "$schema": "https://opencode.ai/config.json",
   "mode": {
@@ -144,30 +184,16 @@ You can create your own custom modes by adding them to the `mode` configuration.
 }
 ```
 
-## Available tools
-
-The following tools can be controlled in mode configurations:
-
-| Tool        | Description             |
-| ----------- | ----------------------- |
-| `bash`      | Execute shell commands  |
-| `edit`      | Modify existing files   |
-| `write`     | Create new files        |
-| `read`      | Read file contents      |
-| `grep`      | Search file contents    |
-| `glob`      | Find files by pattern   |
-| `list`      | List directory contents |
-| `patch`     | Apply patches to files  |
-| `todowrite` | Manage todo lists       |
-| `todoread`  | Read todo lists         |
-| `webfetch`  | Fetch web content       |
+---
 
-## Use cases
+### Use cases
 
-Here are some common use cases for different modes:
+Here are some common use cases for different modes.
 
 - **Build mode**: Full development work with all tools enabled
 - **Plan mode**: Analysis and planning without making changes
 - **Review mode**: Code review with read-only access plus documentation tools
 - **Debug mode**: Focused on investigation with bash and read tools enabled
 - **Docs mode**: Documentation writing with file operations but no system commands
+
+You might also find different models are good for different use cases.