docs: edit server

2 files changed, 125 insertions, 89 deletions

diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs
index da426e446..fb905c72e 100644
--- a/packages/web/astro.config.mjs
+++ b/packages/web/astro.config.mjs
@@ -9,8 +9,6 @@ import { rehypeHeadingIds } from "@astrojs/markdown-remark"
 import rehypeAutolinkHeadings from "rehype-autolink-headings"
 import { spawnSync } from "child_process"
 
-const github = "https://github.com/sst/opencode"
-
 // https://astro.build/config
 export default defineConfig({
   site: config.url,
@@ -49,7 +47,7 @@ export default defineConfig({
         },
       ],
       editLink: {
-        baseUrl: `${github}/edit/dev/packages/web/`,
+        baseUrl: `${config.github}/edit/dev/packages/web/`,
       },
       markdown: {
         headingLinks: false,
@@ -69,7 +67,13 @@ export default defineConfig({
 
         {
           label: "Usage",
-          items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/server", "docs/github"],
+          items: [
+            "docs/tui",
+            "docs/cli",
+            "docs/ide",
+            "docs/share",
+            "docs/github"
+          ],
         },
 
         {
@@ -79,7 +83,6 @@ export default defineConfig({
             "docs/agents",
             "docs/models",
             "docs/themes",
-            "docs/plugins",
             "docs/keybinds",
             "docs/formatters",
             "docs/permissions",
@@ -87,6 +90,14 @@ export default defineConfig({
             "docs/mcp-servers",
           ],
         },
+
+        {
+          label: "Develop",
+          items: [
+            "docs/server",
+            "docs/plugins",
+          ],
+        },
       ],
       components: {
         Hero: "./src/components/Hero.astro",
diff --git a/packages/web/src/content/docs/docs/server.mdx b/packages/web/src/content/docs/docs/server.mdx
index 90a67e6f4..894c30fdb 100644
--- a/packages/web/src/content/docs/docs/server.mdx
+++ b/packages/web/src/content/docs/docs/server.mdx
@@ -1,130 +1,155 @@
 ---
-title: Server API
-description: Interact with opencode over HTTP using `opencode serve`.
+title: Server
+description: Interact with opencode server over HTTP.
 ---
 
-## Overview
+import config from "../../../../config.mjs"
+export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
 
-`opencode serve` runs a headless HTTP server that exposes the same features as the TUI. The server is intended for automation and remote control.
+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.
 
-## Starting the server
+---
+
+## Usage
 
 ```bash
 opencode serve [--port <number>] [--hostname <string>]
 ```
 
-### Options
+#### Options
 
 | Flag         | Short | Description           | Default     |
 | ------------ | ----- | --------------------- | ----------- |
 | `--port`     | `-p`  | Port to listen on     | `4096`      |
 | `--hostname` | `-h`  | Hostname to listen on | `127.0.0.1` |
 
-## Documentation
+---
 
-The server publishes an OpenAPI 3.1 spec and an interactive explorer at:
+## Docs
+
+The server publishes an OpenAPI 3.1 spec that can be viewed at:
 
 ```
 http://<hostname>:<port>/doc
 ```
 
-Use the spec to generate clients or inspect request and response types. All examples below use `curl` with the default `localhost:4096`.
+For example, `http://localhost:4096/doc`. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.
 
-## API Endpoints
+---
+
+## APIs
+
+The opencode server exposes the following APIs.
+
+---
 
-### App & Config
+### App
 
-| Method | Path                | Description                       | Response |
-| ------ | ------------------- | --------------------------------- | -------- |
-| `GET`  | `/app`              | Get app info                      | [`App`](packages/sdk/js/src/gen/types.gen.ts) |
-| `POST` | `/app/init`         | Initialize the app                | `boolean` |
-| `GET`  | `/config`           | Get config info                   | [`Config`](packages/sdk/js/src/gen/types.gen.ts) |
-| `GET`  | `/config/providers` | List providers and default models | `{ providers: `[`Provider[]`](packages/sdk/js/src/gen/types.gen.ts)`, default: { [key: string]: string } }` |
+| Method | Path        | Description        | Response                                |
+| ------ | ----------- | ------------------ | --------------------------------------- |
+| `GET`  | `/app`      | Get app info       | <a href={typesUrl}><code>App</code></a> |
+| `POST` | `/app/init` | Initialize the app | `boolean`                               |
+
+---
+
+### Config
+
+| Method | Path                | Description                       | Response                                                                                              |
+| ------ | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `GET`  | `/config`           | Get config info                   | <a href={typesUrl}><code>Config</code></a>                                                            |
+| `GET`  | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
+
+---
 
 ### Sessions
 
-| Method   | Path                                     | Description                        | Notes                                      |
-| -------- | ---------------------------------------- | ---------------------------------- | ------------------------------------------ |
-| `GET`    | `/session`                               | List sessions                      | Returns [`Session[]`](packages/sdk/js/src/gen/types.gen.ts)                                            |
-| `GET`    | `/session/:id`                           | Get session                        | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts)                                            |
-| `GET`    | `/session/:id/children`                  | List child sessions                | Returns [`Session[]`](packages/sdk/js/src/gen/types.gen.ts)                                            |
-| `POST`   | `/session`                               | Create session                     | body: `{ parentID?, title? }`, returns [`Session`](packages/sdk/js/src/gen/types.gen.ts)              |
-| `DELETE` | `/session/:id`                           | Delete session                     |                                            |
-| `PATCH`  | `/session/:id`                           | Update session properties          | body: `{ title? }`, returns [`Session`](packages/sdk/js/src/gen/types.gen.ts)                         |
-| `POST`   | `/session/:id/init`                      | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }` |
-| `POST`   | `/session/:id/abort`                     | Abort a running session            |                                            |
-| `POST`   | `/session/:id/share`                     | Share session                      | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts)                                            |
-| `DELETE` | `/session/:id/share`                     | Unshare session                    | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts)                                            |
-| `POST`   | `/session/:id/summarize`                 | Summarize session                  |                                            |
-| `GET`    | `/session/:id/message`                   | List messages in a session         | Returns `{ info: `[`Message`](packages/sdk/js/src/gen/types.gen.ts)`, parts: `[`Part[]`](packages/sdk/js/src/gen/types.gen.ts)`}[]`                                            |
-| `GET`    | `/session/:id/message/:messageID`        | Get message details                | Returns `{ info: `[`Message`](packages/sdk/js/src/gen/types.gen.ts)`, parts: `[`Part[]`](packages/sdk/js/src/gen/types.gen.ts)`}`                                            |
-| `POST`   | `/session/:id/message`                   | Send chat message                  | body matches [`ChatInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L358), returns [`Message`](packages/sdk/js/src/gen/types.gen.ts)                   |
-| `POST`   | `/session/:id/shell`                     | Run a shell command                | body matches [`CommandInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L1007), returns [`Message`](packages/sdk/js/src/gen/types.gen.ts)                |
-| `POST`   | `/session/:id/revert`                    | Revert a message                   | body: `{ messageID }`                      |
-| `POST`   | `/session/:id/unrevert`                  | Restore reverted messages          |                                            |
-| `POST`   | `/session/:id/permissions/:permissionID` | Respond to a permission request    | body: `{ response }`                       |
-
-### Search & Files
-
-| Method | Path                     | Description                  | Response |
-| ------ | ------------------------ | ---------------------------- | -------- |
+| Method   | Path                                     | Description                        | Notes                                                                                                                                                                      |
+| -------- | ---------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET`    | `/session`                               | List sessions                      | Returns <a href={typesUrl}><code>Session[]</code></a>                                                                                                                      |
+| `GET`    | `/session/:id`                           | Get session                        | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                        |
+| `GET`    | `/session/:id/children`                  | List child sessions                | Returns <a href={typesUrl}><code>Session[]</code></a>                                                                                                                      |
+| `POST`   | `/session`                               | Create session                     | body: `{ parentID?, title? }`, returns <a href={typesUrl}><code>Session</code></a>                                                                                         |
+| `DELETE` | `/session/:id`                           | Delete session                     |                                                                                                                                                                            |
+| `PATCH`  | `/session/:id`                           | Update session properties          | body: `{ title? }`, returns <a href={typesUrl}><code>Session</code></a>                                                                                                    |
+| `POST`   | `/session/:id/init`                      | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }`                                                                                                                                 |
+| `POST`   | `/session/:id/abort`                     | Abort a running session            |                                                                                                                                                                            |
+| `POST`   | `/session/:id/share`                     | Share session                      | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                        |
+| `DELETE` | `/session/:id/share`                     | Unshare session                    | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                        |
+| `POST`   | `/session/:id/summarize`                 | Summarize session                  |                                                                                                                                                                            |
+| `GET`    | `/session/:id/message`                   | List messages in a session         | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]`                                                    |
+| `GET`    | `/session/:id/message/:messageID`        | Get message details                | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}`                                                      |
+| `POST`   | `/session/:id/message`                   | Send chat message                  | body matches [`ChatInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L358), returns <a href={typesUrl}><code>Message</code></a>     |
+| `POST`   | `/session/:id/shell`                     | Run a shell command                | body matches [`CommandInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L1007), returns <a href={typesUrl}><code>Message</code></a> |
+| `POST`   | `/session/:id/revert`                    | Revert a message                   | body: `{ messageID }`                                                                                                                                                      |
+| `POST`   | `/session/:id/unrevert`                  | Restore reverted messages          |                                                                                                                                                                            |
+| `POST`   | `/session/:id/permissions/:permissionID` | Respond to a permission request    | body: `{ response }`                                                                                                                                                       |
+
+---
+
+### Files
+
+| Method | Path                     | Description                  | Response                                                                                    |
+| ------ | ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------- |
 | `GET`  | `/find?pattern=<pat>`    | Search for text in files     | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
-| `GET`  | `/find/file?query=<q>`   | Find files by name           | `string[]` (file paths) |
-| `GET`  | `/find/symbol?query=<q>` | Find workspace symbols       | [`Symbol[]`](packages/sdk/js/src/gen/types.gen.ts) |
-| `GET`  | `/file?path=<path>`      | Read a file                  | `{ type: "raw" \| "patch", content: string }` |
-| `GET`  | `/file/status`           | Get status for tracked files | [`File[]`](packages/sdk/js/src/gen/types.gen.ts) |
+| `GET`  | `/find/file?query=<q>`   | Find files by name           | `string[]` (file paths)                                                                     |
+| `GET`  | `/find/symbol?query=<q>` | Find workspace symbols       | <a href={typesUrl}><code>Symbol[]</code></a>                                                |
+| `GET`  | `/file?path=<path>`      | Read a file                  | `{ type: "raw" \| "patch", content: string }`                                               |
+| `GET`  | `/file/status`           | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a>                                                  |
+
+---
 
 ### Logging
 
-| Method | Path   | Description                                                      | Response |
-| ------ | ------ | ---------------------------------------------------------------- | -------- |
-| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }`    | `boolean` |
+| Method | Path   | Description                                                  | Response  |
+| ------ | ------ | ------------------------------------------------------------ | --------- |
+| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` |
+
+---
 
 ### Agents
 
-| Method | Path     | Description              | Response |
-| ------ | -------- | ------------------------ | -------- |
-| `GET`  | `/agent` | List all available agents | [`Agent[]`](packages/sdk/js/src/gen/types.gen.ts) |
+| Method | Path     | Description               | Response                                    |
+| ------ | -------- | ------------------------- | ------------------------------------------- |
+| `GET`  | `/agent` | List all available agents | <a href={typesUrl}><code>Agent[]</code></a> |
+
+---
+
+### TUI
+
+| Method | Path                    | Description                                 | Response               |
+| ------ | ----------------------- | ------------------------------------------- | ---------------------- |
+| `POST` | `/tui/append-prompt`    | Append text to the prompt                   | `boolean`              |
+| `POST` | `/tui/open-help`        | Open the help dialog                        | `boolean`              |
+| `POST` | `/tui/open-sessions`    | Open the session selector                   | `boolean`              |
+| `POST` | `/tui/open-themes`      | Open the theme selector                     | `boolean`              |
+| `POST` | `/tui/open-models`      | Open the model selector                     | `boolean`              |
+| `POST` | `/tui/submit-prompt`    | Submit the current prompt                   | `boolean`              |
+| `POST` | `/tui/clear-prompt`     | Clear the prompt                            | `boolean`              |
+| `POST` | `/tui/execute-command`  | Execute a command (`{ command }`)           | `boolean`              |
+| `POST` | `/tui/show-toast`       | Show toast (`{ title?, message, variant }`) | `boolean`              |
+| `GET`  | `/tui/control/next`     | Wait for the next control request           | Control request object |
+| `POST` | `/tui/control/response` | Respond to a control request (`{ body }`)   | `boolean`              |
 
-### TUI Control
+---
 
-| Method       | Path                   | Description                                 | Response |
-| ------------ | ---------------------- | ------------------------------------------- | -------- |
-| `POST`       | `/tui/append-prompt`   | Append text to the prompt                   | `boolean` |
-| `POST`       | `/tui/open-help`       | Open the help dialog                        | `boolean` |
-| `POST`       | `/tui/open-sessions`   | Open the session selector                   | `boolean` |
-| `POST`       | `/tui/open-themes`     | Open the theme selector                     | `boolean` |
-| `POST`       | `/tui/open-models`     | Open the model selector                     | `boolean` |
-| `POST`       | `/tui/submit-prompt`   | Submit the current prompt                   | `boolean` |
-| `POST`       | `/tui/clear-prompt`    | Clear the prompt                            | `boolean` |
-| `POST`       | `/tui/execute-command` | Execute a command (`{ command }`)           | `boolean` |
-| `POST`       | `/tui/show-toast`      | Show toast (`{ title?, message, variant }`) | `boolean` |
-| `GET`        | `/tui/control/next`    | Wait for the next control request          | Control request object |
-| `POST`       | `/tui/control/response` | Respond to a control request (`{ body }`)   | `boolean` |
+### Auth
 
-### Authentication
+| Method | Path        | Description                                                     | Response  |
+| ------ | ----------- | --------------------------------------------------------------- | --------- |
+| `PUT`  | `/auth/:id` | Set authentication credentials. Body must match provider schema | `boolean` |
 
-| Method | Path        | Description                                                      | Response |
-| ------ | ----------- | ---------------------------------------------------------------- | -------- |
-| `PUT`  | `/auth/:id` | Set authentication credentials. Body must match provider schema  | `boolean` |
+---
 
 ### Events
 
-| Method | Path     | Description                                                                    | Response |
-| ------ | -------- | ------------------------------------------------------------------------------ | -------- |
+| Method | Path     | Description                                                                   | Response                  |
+| ------ | -------- | ----------------------------------------------------------------------------- | ------------------------- |
 | `GET`  | `/event` | Server-sent events stream. First event is `server.connected`, then bus events | Server-sent events stream |
 
-### Documentation
-
-| Method | Path   | Description                           | Response |
-| ------ | ------ | ------------------------------------- | -------- |
-| `GET`  | `/doc`  | OpenAPI 3.1 specification and explorer | HTML page with OpenAPI spec and Swagger UI |
-
-## Example
+---
 
-```bash
-# fetch current app info
-curl http://localhost:4096/app
-```
+### Docs
 
-Use the OpenAPI spec for complete schemas and additional endpoints.
+| Method | Path   | Description                            | Response                                   |
+| ------ | ------ | -------------------------------------- | ------------------------------------------ |
+| `GET`  | `/doc` | OpenAPI 3.1 specification | HTML page with OpenAPI spec |