docs: edit commands

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

@@ -3,7 +3,13 @@ title: Commands
 description: Create custom commands for repetitive tasks.
 ---
 
-Define custom commands to automate repetitive coding tasks.
+Custom commands let you specify a prompt you want to run when that command is executed in the TUI.
+
+```bash frame="none"
+/my-command
+```
+
+Custom commands are in addition to the built-in commands like `/init`, `/undo`, `/redo`, `/share`, `/help`. [Learn more](/docs/tui#commands).
 
 ---
 
@@ -34,12 +40,78 @@ Use the command by typing `/` followed by the command name.
 
 ---
 
-## Use arguments
+## Configure
+
+You can add custom commands through the opencode config or by creating markdown files in the `command/` directory.
+
+---
+
+### JSON
+
+Use the `command` option in your opencode [config](/docs/config):
+
+```json title="opencode.jsonc" {4-12}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    // This becomes the name of the command
+    "test": {
+      // This is the prompt that will be sent to the LLM
+      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
+      // This is show as the description in the TUI
+      "description": "Run tests with coverage",
+      "agent": "build",
+      "model": "anthropic/claude-3-5-sonnet-20241022"
+    },
+  }
+}
+```
+
+Now you can run this command in the TUI:
+
+```bash frame="none"
+/test
+```
+
+---
+
+### Markdown
+
+You can also define commands using markdown files. Place them in:
+
+- Global: `~/.config/opencode/command/`
+- Per-project: `.opencode/command/`
+
+```markdown title="~/.config/opencode/command/test.md"
+---
+description: Run tests with coverage
+agent: build
+model: anthropic/claude-3-5-sonnet-20241022
+---
+
+Run the full test suite with coverage report and show any failures.
+Focus on the failing tests and suggest fixes.
+```
+
+The markdown file name becomes the command name. For example, `test.md` lets
+you run:
+
+```bash frame="none"
+/test
+```
+
+---
+
+## Prompt config
+
+The prompts for the custom commands support several special placeholders and syntax.
+
+---
+
+### Arguments
 
 Pass arguments to commands using the `$ARGUMENTS` placeholder.
 
-Create `.opencode/command/component.md`:
-
 ```md title=".opencode/command/component.md"
 ---
 description: Create a new component
@@ -52,16 +124,18 @@ Include proper typing and basic structure.
 Run the command with arguments:
 
 ```bash frame="none"
-"/component Button"
+/component Button
 ```
 
+And `$ARGUMENTS` will be replaced with `Button`.
+
 ---
 
-## Inject shell output
+### Shell output
 
-Use !`command` to inject shell command output into your prompt.
+Use _!`command`_ to inject [bash command](/docs/tui#bash-commands) output into your prompt.
 
-Create `.opencode/command/analyze-coverage.md`:
+For example, to create a custom command that analyzes test coverage:
 
 ```md title=".opencode/command/analyze-coverage.md"
 ---
@@ -74,7 +148,7 @@ Here are the current test results:
 Based on these results, suggest improvements to increase coverage.
 ```
 
-Create `.opencode/command/review-changes.md`:
+Or to review recent changes:
 
 ```md title=".opencode/command/review-changes.md"
 ---
@@ -91,12 +165,10 @@ Commands run in your project's root directory and their output becomes part of t
 
 ---
 
-## Reference files
+### File references
 
 Include files in your command using `@` followed by the filename.
 
-Create `.opencode/command/review-component.md`:
-
 ```md title=".opencode/command/review-component.md"
 ---
 description: Review component
@@ -110,47 +182,90 @@ The file content gets included in the prompt automatically.
 
 ---
 
-## Command properties
+## Options
 
-Configure commands with these optional frontmatter properties:
+Let's look at the configuration options in detail.
 
-- **description**: Brief explanation of what the command does
-- **agent**: Agent to use (defaults to "build")
-- **model**: Specific model to use for this command
-
-Create `.opencode/command/code-review.md`:
-
-```md title=".opencode/command/code-review.md"
----
-description: Code review assistant
-agent: build
-model: anthropic/claude-3-5-sonnet-20241022
 ---
 
-Review the code for best practices and suggest improvements.
+### Template
+
+The `template` option defines the prompt that will be sent to the LLM when the command is executed.
+
+```json title="opencode.json"
+{
+  "command": {
+    "test": {
+      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
+    }
+  }
+}
 ```
 
----
+This is a **required** config option.
-
-## Command directory
-
-Store command files in these locations:
-
-- `.opencode/command/` - Project-specific commands
-- `command/` - Global commands in config directory
-
-Project commands take precedence over global ones.
 
 ---
 
-## Built-in commands
+### Description
 
-opencode includes several built-in commands:
+Use the `description` option to provide a brief description of what the command does.
 
-- `/init` - Initialize project and create AGENTS.md
+```json title="opencode.json"
-- `/undo` - Revert the last changes
+{
-- `/redo` - Restore reverted changes
+  "command": {
-- `/share` - Share the current conversation
+    "test": {
-- `/help` - Show available commands and keybinds
+      "description": "Run tests with coverage"
+    }
+  }
+}
+```
 
-Use `/help` to see all available commands in your setup.
+This is shown as the description in the TUI when you type in the command.
+
+---
+
+### Agent
+
+Use the `agent` config to optionally specify which [agent](/docs/agents) should execute this command.
+
+```json title="opencode.json"
+{
+  "command": {
+    "review": {
+      "agent": "plan"
+    }
+  }
+}
+```
+
+This is an **optional** config option. If not specified, defaults to "build".
+
+---
+
+### Model
+
+Use the `model` config to override the default model for this command.
+
+```json title="opencode.json"
+{
+  "command": {
+    "analyze": {
+      "model": "anthropic/claude-3-5-sonnet-20241022"
+    }
+  }
+}
+```
+
+This is an **optional** config option.
+
+---
+
+## Built-in
+
+opencode includes several built-in commands like `/init`, `/undo`, `/redo`, `/share`, `/help`; [learn more](/docs/tui#commands).
+
+:::note
+Custom commands can override built-in commands.
+:::
+
+If you define a custom command with the same name, it will override the built-in command.

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

@@ -152,6 +152,32 @@ By default, sharing is set to manual mode where you need to explicitly share con
 
 ---
 
+### Commands
+
+You can configure custom commands for repetitive tasks through the `command` option.
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    "test": {
+      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
+      "description": "Run tests with coverage",
+      "agent": "build",
+      "model": "anthropic/claude-3-5-sonnet-20241022"
+    },
+    "component": {
+      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
+      "description": "Create a new component"
+    }
+  }
+}
+```
+
+You can also define commands using markdown files in `~/.config/opencode/command/` or `.opencode/command/`. [Learn more here](/docs/commands).
+
+---
+
 ### Keybinds
 
 You can customize your keybinds through the `keybinds` option.
@@ -220,6 +246,11 @@ You can configure permissions to control what AI agents can do in your codebase
 }
 ```
 
+This allows you to configure explicit approval requirements for sensitive operations:
+
+- `edit` - Controls whether file editing operations require user approval (`"ask"` or `"allow"`)
+- `bash` - Controls whether bash commands require user approval (can be `"ask"`/`"allow"` or a pattern map)
+
 [Learn more about permissions here](/docs/permissions).
 
 ---
@@ -259,13 +290,6 @@ about rules here](/docs/rules).
 
 You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.
 
-The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
-
-- 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
-
-
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
@@ -273,12 +297,11 @@ The `disabled_providers` option accepts an array of provider IDs. When a provide
 }
 ```
 
-The permissions system allows you to configure explicit approval requirements for sensitive operations:
+The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
 
-- `edit` - Controls whether file editing operations require user approval (`"ask"` or `"allow"`)
+- It won't be loaded even if environment variables are set.
-- `bash` - Controls whether bash commands require user approval (can be `"ask"`/`"allow"` or a pattern map)
+- 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.
-[Learn more about permissions here](/docs/permissions).
 
 ---
 

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

@@ -25,6 +25,12 @@ Once you're in the TUI, you can prompt it with a message.
 Give me a quick summary of the codebase.
 ```
 
+---
+
+## File references
+
+You can reference files in your messages using `@`. This does a fuzzy file search in the current working directory.
+
 :::tip
 You can also use `@` to reference files in your messages.
 :::
@@ -33,6 +39,20 @@ You can also use `@` to reference files in your messages.
 How is auth handled in @packages/functions/src/api/index.ts?
 ```
 
+The content of the file is added to the conversation automatically.
+
+---
+
+## Bash commands
+
+Start a message with `!` to run a shell command.
+
+```bash frame="none"
+!ls -la
+```
+
+The output of the command is added to the conversation as a tool result.
+
 ---
 
 ## Commands
@@ -235,18 +255,6 @@ Unshare current session. [Learn more](/docs/share#un-sharing).
 
 ---
 
-## Bash commands
-
-Start a message with `!` to run a shell command.
-
-```bash frame="none"
-!ls -la
-```
-
-The output of the command is added to the conversation as a tool result.
-
----
-
 ## Editor setup
 
 Both the `/editor` and `/export` commands use the editor specified in your `EDITOR` environment variable.
@@ -300,6 +308,8 @@ Popular editor options include:
 - `notepad` - Windows Notepad
 - `subl` - Sublime Text
 
-:::tip
+:::note
-Some editors need command-line arguments to run in blocking mode. The --wait flag makes the editor process block until closed, which is necessary for opencode to function correctly.
+Some editors like VS Code need to be started with the `--wait` flag.
 :::
+
+Some editors need command-line arguments to run in blocking mode. The `--wait` flag makes the editor process block until closed.