docs: clarify LSP and formatter opt-in config (#25502)

3 files changed, 83 insertions, 19 deletions

diff --git a/packages/web/src/content/docs/config.mdx b/packages/web/src/content/docs/config.mdx
index 14eefdd81..8568ffbb9 100644
--- a/packages/web/src/content/docs/config.mdx
+++ b/packages/web/src/content/docs/config.mdx
@@ -575,7 +575,16 @@ Notice that this only works if it was not installed using a package manager such
 
 ### Formatters
 
-You can configure code formatters through the `formatter` option.
+You can enable and configure code formatters through the `formatter` option. Omit it to keep formatters disabled.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": true
+}
+```
+
+Use an object to keep built-ins enabled while configuring overrides or custom formatters.
 
 ```json title="opencode.json"
 {
@@ -599,6 +608,34 @@ You can configure code formatters through the `formatter` option.
 
 ---
 
+### LSP Servers
+
+You can enable and configure LSP servers through the `lsp` option. Omit it to keep LSP disabled.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": true
+}
+```
+
+Use an object to keep built-ins enabled while configuring overrides or custom LSP servers.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": {
+    "typescript": {
+      "disabled": true
+    }
+  }
+}
+```
+
+[Learn more about LSP servers here](/docs/lsp).
+
+---
+
 ### Permissions
 
 By default, opencode **allows all operations** without requiring explicit approval. You can change this using the `permission` option.
diff --git a/packages/web/src/content/docs/formatters.mdx b/packages/web/src/content/docs/formatters.mdx
index dbee49dca..ec7a965d2 100644
--- a/packages/web/src/content/docs/formatters.mdx
+++ b/packages/web/src/content/docs/formatters.mdx
@@ -3,7 +3,7 @@ title: Formatters
 description: OpenCode uses language specific formatters.
 ---
 
-OpenCode automatically formats files after they are written or edited using language-specific formatters. This ensures that the code that is generated follows the code styles of your project.
+OpenCode can format files after they are written or edited using language-specific formatters. Formatters are disabled by default; enable them in your config before OpenCode will run them.
 
 ---
 
@@ -40,25 +40,36 @@ OpenCode comes with several built-in formatters for popular languages and framew
 | uv                   | .py, .pyi                                                                                                | `uv` command available                                                                                |
 | zig                  | .zig, .zon                                                                                               | `zig` command available                                                                               |
 
-So if your project has `prettier` in your `package.json`, OpenCode will automatically use it.
+When formatters are enabled, OpenCode will use `prettier` for matching files if your project has `prettier` in `package.json`.
 
 ---
 
 ## How it works
 
-When OpenCode writes or edits a file, it:
+When OpenCode writes or edits a file and formatters are enabled, it:
 
 1. Checks the file extension against all enabled formatters.
 2. Runs the appropriate formatter command on the file.
-3. Applies the formatting changes automatically.
+3. Applies the formatting changes.
 
-This process happens in the background, ensuring your code styles are maintained without any manual steps.
+This process happens in the background for enabled formatters.
 
 ---
 
 ## Configure
 
-You can customize formatters through the `formatter` section in your OpenCode config.
+You can enable and customize formatters through the `formatter` section in your OpenCode config.
+
+To enable all built-in formatters, set `formatter` to `true`.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": true
+}
+```
+
+Use an object to keep built-ins enabled while configuring overrides or custom formatters.
 
 ```json title="opencode.json"
 {
@@ -72,7 +83,7 @@ Each formatter configuration supports the following:
 | Property      | Type     | Description                                             |
 | ------------- | -------- | ------------------------------------------------------- |
 | `disabled`    | boolean  | Set this to `true` to disable the formatter             |
-| `command`     | string[] | The command to run for formatting                       |
+| `command`     | string[] | The command to run for formatting. Required for custom formatters; optional for built-ins. |
 | `environment` | object   | Environment variables to set when running the formatter |
 | `extensions`  | string[] | File extensions this formatter should handle            |
 
@@ -82,7 +93,7 @@ Let's look at some examples.
 
 ### Disabling formatters
 
-To disable **all** formatters globally, set `formatter` to `false`:
+If `formatter` is omitted, all formatters are disabled. To disable all formatters after another config enabled them, set `formatter` to `false`:
 
 ```json title="opencode.json" {3}
 {
@@ -108,7 +119,7 @@ To disable a **specific** formatter, set `disabled` to `true`:
 
 ### Custom formatters
 
-You can override the built-in formatters or add new ones by specifying the command, environment variables, and file extensions:
+You can configure built-in formatters with options like `environment` or `extensions`. To add a custom formatter, specify a `command` and `extensions`:
 
 ```json title="opencode.json" {4-14}
 {
diff --git a/packages/web/src/content/docs/lsp.mdx b/packages/web/src/content/docs/lsp.mdx
index ad6a4644d..5854fe1f1 100644
--- a/packages/web/src/content/docs/lsp.mdx
+++ b/packages/web/src/content/docs/lsp.mdx
@@ -3,7 +3,7 @@ title: LSP Servers
 description: OpenCode integrates with your LSP servers.
 ---
 
-OpenCode integrates with your Language Server Protocol (LSP) to help the LLM interact with your codebase. It uses diagnostics to provide feedback to the LLM.
+OpenCode can integrate with your Language Server Protocol (LSP) to help the LLM interact with your codebase. It uses diagnostics to provide feedback to the LLM.
 
 ---
 
@@ -48,7 +48,7 @@ OpenCode comes with several built-in LSP servers for popular languages:
 | yaml-ls            | .yaml, .yml                                                         | Auto-installs Red Hat yaml-language-server                   |
 | zls                | .zig, .zon                                                          | `zig` command available                                      |
 
-LSP servers are automatically enabled when one of the above file extensions are detected and the requirements are met.
+When LSP is enabled, servers start when one of the above file extensions is detected and the requirements are met.
 
 :::note
 You can disable automatic LSP server downloads by setting the `OPENCODE_DISABLE_LSP_DOWNLOAD` environment variable to `true`.
@@ -58,7 +58,7 @@ You can disable automatic LSP server downloads by setting the `OPENCODE_DISABLE_
 
 ## How It Works
 
-When opencode opens a file, it:
+When LSP is enabled and opencode opens a file, it:
 
 1. Checks the file extension against all enabled LSP servers.
 2. Starts the appropriate LSP server if not already running.
@@ -67,7 +67,18 @@ When opencode opens a file, it:
 
 ## Configure
 
-You can customize LSP servers through the `lsp` section in your opencode config.
+You can enable and customize LSP servers through the `lsp` section in your opencode config.
+
+To enable all built-in LSP servers, set `lsp` to `true`.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": true
+}
+```
+
+Use an object to keep built-ins enabled while configuring overrides or custom servers.
 
 ```json title="opencode.json"
 {
@@ -76,7 +87,9 @@ You can customize LSP servers through the `lsp` section in your opencode config.
 }
 ```
 
-Each LSP server supports the following:
+Each configured LSP server entry supports the following:
+
+Server entries need `command` unless they only disable a server.
 
 | Property         | Type     | Description                                       |
 | ---------------- | -------- | ------------------------------------------------- |
@@ -94,11 +107,12 @@ Let's look at some examples.
 
 Use the `env` property to set environment variables when starting the LSP server:
 
-```json title="opencode.json" {5-7}
+```json title="opencode.json" {5-8}
 {
   "$schema": "https://opencode.ai/config.json",
   "lsp": {
     "rust": {
+      "command": ["rust-analyzer"],
       "env": {
         "RUST_LOG": "debug"
       }
@@ -113,11 +127,13 @@ Use the `env` property to set environment variables when starting the LSP server
 
 Use the `initialization` property to pass initialization options to the LSP server. These are server-specific settings sent during the LSP `initialize` request:
 
-```json title="opencode.json" {5-9}
+```json title="opencode.json" {5-13}
 {
   "$schema": "https://opencode.ai/config.json",
   "lsp": {
-    "typescript": {
+    "custom-lsp": {
+      "command": ["custom-lsp-server", "--stdio"],
+      "extensions": [".custom"],
       "initialization": {
         "preferences": {
           "importModuleSpecifierPreference": "relative"
@@ -136,7 +152,7 @@ Initialization options vary by LSP server. Check your LSP server's documentation
 
 ### Disabling LSP servers
 
-To disable **all** LSP servers globally, set `lsp` to `false`:
+If `lsp` is omitted, all LSP servers are disabled. To disable all LSP servers after another config enabled them, set `lsp` to `false`:
 
 ```json title="opencode.json" {3}
 {