docs: expand user guides

packages/docs/lsp.mdx

@@ -0,0 +1,105 @@
+---
+title: "LSP"
+description: "Configure language servers and understand LSP support in OpenCode V2."
+---
+
+Language Server Protocol (LSP) integrations can provide code diagnostics,
+symbols, definitions, references, and other language-aware context.
+
+<Warning>
+  OpenCode V2 does not yet have an LSP runtime or built-in language servers.
+  The `lsp` configuration is accepted and preserved, but it does not currently
+  start or download servers, expose an LSP tool, or add diagnostics to file tool
+  results.
+</Warning>
+
+## Built-in servers
+
+There are no built-in LSP servers in the current V2 implementation. Setting
+`lsp` to `true` declares that built-ins should be enabled, but has no runtime
+effect until V2 provides a server registry and LSP runtime.
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": true
+}
+```
+
+## Configuration
+
+The `lsp` field accepts a boolean or an object keyed by server name:
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": {
+    "custom-typescript": {
+      "command": ["typescript-language-server", "--stdio"],
+      "extensions": [".ts", ".tsx"],
+      "env": {
+        "TSS_LOG": "-level verbose"
+      },
+      "initialization": {
+        "preferences": {
+          "importModuleSpecifierPreference": "relative"
+        }
+      }
+    }
+  }
+}
+```
+
+Each enabled server entry has this shape:
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `command` | `string[]` | Yes | Executable followed by any arguments. |
+| `extensions` | `string[]` | No | File extensions associated with the server, including the leading dot. |
+| `disabled` | `boolean` | No | Disables the entry when `true`. |
+| `env` | `Record<string, string>` | No | Environment variables for the server process. The property is named `env`, not `environment`. |
+| `initialization` | `Record<string, unknown>` | No | Server-specific options for the LSP `initialize` request. |
+
+The only entry that may omit `command` is the disable-only form:
+
+```jsonc
+{
+  "lsp": {
+    "typescript": {
+      "disabled": true
+    }
+  }
+}
+```
+
+Server names are arbitrary. The V2 schema permits `extensions` to be omitted,
+including for a custom server, although a future runtime will need a way to
+associate that server with files.
+
+## Disable LSP
+
+Omit `lsp` when no configuration is needed. Set it to `false` to explicitly
+disable the whole integration, including when a lower-priority configuration
+set it to `true` or supplied an object:
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": false
+}
+```
+
+Use `{ "disabled": true }` under a server name to disable one server while
+retaining the object form. `OPENCODE_DISABLE_LSP_DOWNLOAD` is not used by V2;
+V2 currently performs no automatic LSP downloads.
+
+## Current usage
+
+V2 loads and validates the configuration shape for compatibility and future
+integration. It does not currently use LSP when reading, writing, editing, or
+patching files, and those tools do not notify a language server or return LSP
+diagnostics.
+
+For reliable feedback today, have the agent run the project's lint, typecheck,
+test, or compiler commands. Record those commands in an `AGENTS.md` file or a
+skill so the agent knows when and where to run them.