docs: edit server

2 files changed, 44 insertions, 17 deletions

diff --git a/packages/web/src/content/docs/docs/sdk.mdx b/packages/web/src/content/docs/docs/sdk.mdx
index 37d53b304..d3e1eadda 100644
--- a/packages/web/src/content/docs/docs/sdk.mdx
+++ b/packages/web/src/content/docs/docs/sdk.mdx
@@ -8,6 +8,8 @@ export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types
 
 The opencode [JS/TS SDK](https://www.npmjs.com/package/@opencode-ai/sdk) provides a type-safe client for interacting with the opencode server. You can use it to build custom integrations and control opencode programmatically.
 
+[Learn more](/docs/server) about how the opencode server works.
+
 ---
 
 ## Install
@@ -72,6 +74,20 @@ All types are generated from the server's OpenAPI specification and available in
 
 ---
 
+## Errors
+
+The SDK throws typed errors that you can catch and handle:
+
+```typescript
+try {
+  const session = await client.session.get({ id: "invalid-id" })
+} catch (error) {
+  console.error("Failed to get session:", error.message)
+}
+```
+
+---
+
 ## APIs
 
 The SDK exposes all server APIs through a type-safe client interface.
@@ -284,17 +300,3 @@ for await (const event of eventStream) {
   console.log("Event:", event.type, event.properties)
 }
 ```
-
----
-
-## Error handling
-
-The SDK throws typed errors that you can catch and handle:
-
-```typescript
-try {
-  const session = await client.session.get({ id: "invalid-id" })
-} catch (error) {
-  console.error("Failed to get session:", error.message)
-}
-```
diff --git a/packages/web/src/content/docs/docs/server.mdx b/packages/web/src/content/docs/docs/server.mdx
index c16162525..f63adb6c4 100644
--- a/packages/web/src/content/docs/docs/server.mdx
+++ b/packages/web/src/content/docs/docs/server.mdx
@@ -6,11 +6,11 @@ description: Interact with opencode server over HTTP.
 import config from "../../../../config.mjs"
 export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
 
-The `opencode serve` command runs a headless HTTP server that exposes an API that an opencode client, like the TUI, uses. You can use this to create your own opencode client and even control a currently running TUI.
+The `opencode serve` command runs a headless HTTP server that exposes an OpenAPI endpoint that an opencode client can use.
 
 ---
 
-## Usage
+### Usage
 
 ```bash
 opencode serve [--port <number>] [--hostname <string>]
@@ -25,7 +25,32 @@ opencode serve [--port <number>] [--hostname <string>]
 
 ---
 
-## Docs
+### How it works
+
+When you run `opencode` it starts a TUI and a server. Where the TUI is the
+client that talks to the server. The server exposes an OpenAPI 3.1 spec
+endpoint. This endpoint is also used to generate an [SDK](/docs/sdk).
+
+:::tip
+Use the opencode server to interact with opencode programmatically.
+:::
+
+This architecture lets opencode support multiple clients and allows you to interact with opencode programmatically.
+
+You can run `opencode serve` to start a standalone server. If you have the
+opencode TUI running, `opencode serve` will start a new server.
+
+---
+
+#### Connect to an existing server
+
+When you start the TUI it randomly assigns a port and hostname. You can instead pass in the `--hostname` and `--port` [flags](/docs/cli). Then use this to connect to its server.
+
+The [`/tui`](#tui) endpoint can be used to drive the TUI through the server. For example, you can prefill or run a prompt. This setup is used by the opencode [IDE](/docs/ide) plugins.
+
+---
+
+## Spec
 
 The server publishes an OpenAPI 3.1 spec that can be viewed at: