feat(api): publish v2 reference

packages/docs/api/index.mdx

@@ -0,0 +1,6 @@
+---
+title: "API Reference"
+description: "OpenCode HTTP API."
+---
+
+The endpoint reference is generated from the current OpenCode V2 [OpenAPI specification](/openapi.json).

packages/docs/config.mdx

@@ -0,0 +1,4 @@
+---
+title: "Config"
+description: "Configure OpenCode."
+---

packages/docs/docs.json

@@ -17,11 +17,24 @@
     "tabs": [
       {
         "tab": "Docs",
-        "pages": ["index"]
+        "pages": ["index", "config", "plugins", "troubleshooting"]
       },
       {
         "tab": "SDK",
         "pages": ["sdk/index"]
+      },
+      {
+        "tab": "API",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": ["api/index"]
+          },
+          {
+            "group": "Endpoints",
+            "openapi": "openapi.json"
+          }
+        ]
       }
     ],
     "global": {}

packages/docs/index.mdx

@@ -98,19 +98,19 @@ Standalone binaries are not available in beta.
 
 With OpenCode you can use any LLM provider by configuring its API key.
 
-If you are new to LLM providers, we recommend [OpenCode Zen](https://opencode.ai/docs/zen). It's a curated list of models
-that have been tested and verified by the OpenCode team.
+Run `/connect` in the TUI and select your provider.
 
-1. Run `/connect` in the TUI, select **opencode**, and open [opencode.ai/auth](https://opencode.ai/auth).
+```text
+/connect
+```
 
-   ```text
-   /connect
-   ```
+If you'd like easy access to all the best coding models you can try out
+[OpenCode Console](https://console.opencode.ai).
 
-2. Sign in, add your billing details, and copy your API key.
-3. Paste your API key into the prompt.
+You can also try [OpenCode Go](https://opencode.ai/go) a $10/month subscription
+plan that grants you access to the best open source models.
 
-Alternatively, select another provider. See the current [provider directory](https://opencode.ai/docs/providers#directory).
+See the current [provider directory](https://opencode.ai/docs/providers#directory).
 
 ---
 
@@ -130,54 +130,16 @@ How is authentication handled in @packages/functions/src/api/index.ts
 
 ### Add features
 
-For larger features, start by asking OpenCode to create a plan.
-
-1. **Create a plan**
-
-   Switch to **Plan mode** with `Tab`. Plan mode prevents OpenCode from making changes while it proposes an implementation.
-
-   ```text
-   <TAB>
-   ```
-
-   Describe the feature with enough context to understand the desired behavior.
-
-   ```text
-   When a user deletes a note, flag it as deleted in the database.
-   Create a screen that shows recently deleted notes.
-   From this screen, the user can restore a note or permanently delete it.
-   ```
-
-   <Tip>Give OpenCode plenty of context and examples.</Tip>
-
-2. **Iterate on the plan**
-
-   Give feedback or add more detail after OpenCode proposes a plan.
-
-   ```text
-   Use the attached image as a visual reference for the new screen.
-   ```
-
-   You can drag and drop images into the terminal to add them to your prompt.
-
-3. **Build the feature**
-
-   When the plan looks right, press `Tab` to return to **Build mode** and ask OpenCode to implement it.
-
-   ```text
-   Sounds good. Go ahead and make the changes.
-   ```
-
-### Make changes
-
-For straightforward work, ask OpenCode to make the change directly and include relevant files and examples.
+Ask OpenCode to add a feature by describing the desired behavior and providing relevant context.
 
 ```text
-Add authentication to the /settings route. Follow the approach used in
-@packages/functions/src/notes.ts and implement it in
-@packages/functions/src/settings.ts.
+When a user deletes a note, flag it as deleted in the database.
+Create a screen that shows recently deleted notes.
+From this screen, the user can restore a note or permanently delete it.
 ```
 
+<Tip>Give OpenCode plenty of context and examples.</Tip>
+
 ### Undo changes
 
 Use `/undo` when a change isn't what you wanted.

packages/docs/openapi.json

@@ -1 +0,0 @@
-../sdk/openapi.json

packages/docs/plugins.mdx

@@ -0,0 +1,4 @@
+---
+title: "Plugins"
+description: "Extend OpenCode with plugins."
+---

packages/docs/troubleshooting.mdx

@@ -0,0 +1,177 @@
+---
+title: "Troubleshooting"
+description: "Diagnose OpenCode startup, server, and session issues."
+---
+
+<Tip>
+  You can ask OpenCode to debug itself. Describe the problem and ask it to use this troubleshooting page; it can read the
+  steps below, inspect its service and logs, and help identify the issue.
+</Tip>
+
+OpenCode runs as two processes: the TUI is a client, while a background server owns sessions, plugins, permissions, and
+other application state. Start by determining whether an issue is in the client, the shared server, or a specific project.
+
+## Check the background service
+
+Show the current server status:
+
+```bash
+opencode2 service status
+```
+
+Verify that its API is healthy:
+
+```bash
+opencode2 api get /api/health
+```
+
+If the service is stuck or unhealthy, restart it:
+
+```bash
+opencode2 service restart
+```
+
+From inside the TUI, run `/reload` to restart the managed service and reconnect:
+
+```text
+/reload
+```
+
+You can also stop and start it explicitly:
+
+```bash
+opencode2 service stop
+opencode2 service start
+```
+
+<Note>
+  OpenCode normally discovers or starts the shared background service automatically. The service commands are only needed
+  when diagnosing its lifecycle.
+</Note>
+
+## Run an isolated session
+
+Use standalone mode to run the TUI with a private server that exits with it:
+
+```bash
+opencode2 --standalone
+```
+
+If an issue disappears in standalone mode, it is likely related to the shared background service rather than the TUI or
+project itself.
+
+## Inspect the API
+
+The `api` command uses the same discovery and authentication flow as the TUI. It accepts either an HTTP method and path or
+an OpenAPI operation ID.
+
+See the [API reference](/api) for all endpoints and operation IDs.
+
+Pass a JSON request body with `--data` or `-d`, and add headers with `--header` or `-H`.
+
+<Warning>
+  Running `opencode2 api` may start the background service when no compatible healthy service is available.
+</Warning>
+
+## Read logs
+
+Installed builds write logs to:
+
+```text
+~/.local/share/opencode/log/opencode.log
+```
+
+Follow the log while reproducing the problem:
+
+```bash
+tail -f ~/.local/share/opencode/log/opencode.log
+```
+
+Each line includes a process `run` ID and a `role` field. Use `role=cli` for TUI and command startup, and `role=server` for
+session, provider, plugin, permission, and tool activity.
+
+```bash
+grep 'role=cli' ~/.local/share/opencode/log/opencode.log
+grep 'role=server' ~/.local/share/opencode/log/opencode.log
+grep 'run=8fc3b1d5' ~/.local/share/opencode/log/opencode.log
+```
+
+Increase verbosity for one reproduction:
+
+```bash
+OPENCODE_LOG_LEVEL=DEBUG opencode2
+```
+
+## Service files
+
+The shared server registers itself at:
+
+```text
+~/.local/state/opencode/service.json
+```
+
+Its private service configuration is stored separately at:
+
+```text
+~/.config/opencode/service.json
+```
+
+The database normally lives at:
+
+```text
+~/.local/share/opencode/opencode-next.db
+```
+
+`OPENCODE_DB` can override the database location.
+
+<Warning>
+  Do not delete or edit service files or the database while troubleshooting. Use the service commands to manage the daemon,
+  and make a backup before inspecting persistent data with external tools.
+</Warning>
+
+## Explicit servers
+
+When connecting with `--server`, set `OPENCODE_PASSWORD` if the server requires authentication:
+
+```bash
+OPENCODE_PASSWORD=secret opencode2 --server http://127.0.0.1:4096
+```
+
+The CLI checks the server before opening the TUI and reports whether it is unreachable, requires a password, or rejected
+the supplied password.
+
+## Report an issue
+
+Include the following when reporting a reproducible problem:
+
+- Output from `opencode2 --version`
+- Output from `opencode2 service status`
+- The smallest sequence of steps that reproduces the issue
+- Whether the issue also occurs with `opencode2 --standalone`
+- Relevant log lines, including their `run` and `role` fields
+
+Remove API keys, authorization headers, prompts, file contents, and other sensitive data before sharing logs.
+
+## Local development
+
+When working from the OpenCode repository, run V2 commands from the repository root:
+
+```bash
+bun dev
+```
+
+The local development channel keeps its logs, SQLite database, and service registration separate from installed builds:
+
+```text
+~/.local/share/opencode/log/opencode-local.log
+~/.local/share/opencode/opencode-local.db
+~/.local/state/opencode/service-local.json
+```
+
+Use the same diagnostics through the package development command:
+
+```bash
+bun dev service status
+bun dev service restart
+bun dev api get /api/health
+```