docs: add new providers doc, reorg sidebar, edits

5 files changed, 532 insertions, 170 deletions

diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs
index ba4d829c4..2cd03f243 100644
--- a/packages/web/astro.config.mjs
+++ b/packages/web/astro.config.mjs
@@ -62,21 +62,33 @@ export default defineConfig({
       },
       sidebar: [
         "docs",
-        "docs/cli",
-        "docs/ide",
-        "docs/share",
-        "docs/modes",
-        "docs/agents",
-        "docs/rules",
-        "docs/github",
         "docs/config",
-        "docs/models",
-        "docs/themes",
-        "docs/keybinds",
-        // "docs/providers",
+        "docs/providers",
         "docs/enterprise",
-        "docs/mcp-servers",
         "docs/troubleshooting",
+
+        {
+          label: "Usage",
+          items: [
+            "docs/cli",
+            "docs/ide",
+            "docs/share",
+            "docs/github",
+          ]
+        },
+
+        {
+          label: "Configure",
+          items: [
+            "docs/modes",
+            "docs/rules",
+            "docs/agents",
+            "docs/models",
+            "docs/themes",
+            "docs/keybinds",
+            "docs/mcp-servers",
+          ]
+        }
       ],
       components: {
         Hero: "./src/components/Hero.astro",
diff --git a/packages/web/src/content/docs/docs/github.mdx b/packages/web/src/content/docs/docs/github.mdx
index 0a63a3533..8dd3091ab 100644
--- a/packages/web/src/content/docs/docs/github.mdx
+++ b/packages/web/src/content/docs/docs/github.mdx
@@ -1,23 +1,23 @@
 ---
 title: GitHub
-description: Use opencode in GitHub Issues and Pull-Requests
+description: Use opencode in GitHub issues and pull-requests
 ---
 
-opencode integrates directly into your GitHub workflow. Mention `/opencode` or `/oc` in your comment, and opencode will execute tasks within your GitHub Actions runner.
+opencode integrates with your GitHub workflow. Mention `/opencode` or `/oc` in your comment, and opencode will execute tasks within your GitHub Actions runner.
 
 ---
 
 ## Features
 
-- **Triage Issues**: Ask opencode to look into an issue and explain it to you.
-- **Fix and Implement**: Ask opencode to fix an issue or implement a feature. And it will work in a new branch and submits a PR with all the changes.
+- **Triage issues**: Ask opencode to look into an issue and explain it to you.
+- **Fix and implement**: Ask opencode to fix an issue or implement a feature. And it will work in a new branch and submits a PR with all the changes.
 - **Secure**: opencode runs inside your GitHub's runners.
 
 ---
 
 ## Installation
 
-Run the following command in the terminal from your GitHub repo:
+Run the following command in a project that is in a GitHub repo:
 
 ```bash
 opencode github install
@@ -29,10 +29,17 @@ This will walk you through installing the GitHub app, creating the workflow, and
 
 ### Manual Setup
 
-1. Install the GitHub app https://github.com/apps/opencode-agent. Make sure it is installed on the target repository.
-2. Add the following workflow file to `.github/workflows/opencode.yml` in your repo. Set the appropriate `model` and required API keys in `env`.
+Or you can set it up manually.
 
-   ```yml
+1. **Install the GitHub app**
+
+   Head over to [**github.com/apps/opencode-agent**](https://github.com/apps/opencode-agent). Make sure it's installed on the target repository.
+
+2. **Add the workflow**
+
+   Add the following workflow file to `.github/workflows/opencode.yml` in your repo. Make sure to set the appropriate `model` and required API keys in `env`.
+
+   ```yml title=".github/workflows/opencode.yml" {24,26}
    name: opencode
 
    on:
@@ -62,39 +69,49 @@ This will walk you through installing the GitHub app, creating the workflow, and
              # share: true
    ```
 
-3. Store the API keys in secrets. In your organization or project **settings**, expand **Secrets and variables** on the left and select **Actions**. Add the required API keys.
+3. **Store the API keys in secrets**
+
+   In your organization or project **settings**, expand **Secrets and variables** on the left and select **Actions**. And add the required API keys.
 
 ---
 
 ## Configuration
 
-- `model`: The model used by opencode. Takes the format of `provider/model` (**required**)
+- `model`: The model used by opencode. Takes the format of `provider/model`. This is **required**.
 - `share`: Share the session. Sessions are shared by default for public repos.
 
 ---
 
-## Usage Examples
+## Examples
 
-- Explain an issue
+Here are some examples of how you can use opencode in GitHub.
 
-  Leave the following comment on a GitHub issue. `opencode` will read the entire thread, including all comments, and reply with a clear explanation.
+- **Explain an issue**
+
+  Add this comment in a GitHub issue.
 
   ```
   /opencode explain this issue
   ```
 
-- Fix an issue
+  opencode will read the entire thread, including all comments, and reply with a clear explanation.
+
+- **Fix an issue**
 
-  Leave the following comment on a GitHub issue. opencode will create a new branch, implement the changes, and open a PR with the changes.
+  In a GitHub issue, say:
 
   ```
   /opencode fix this
   ```
 
+  And opencode will create a new branch, implement the changes, and open a PR with the changes.
+
 - Review PRs and make changes
 
-  Leave the following comment on a GitHub PR. opencode will implement the requested change and commit it to the same PR.
+  Leave the following comment on a GitHub PR.
 
   ```
   Delete the attachment from S3 when the note is removed /oc
   ```
+
+  opencode will implement the requested change and commit it to the same PR.
diff --git a/packages/web/src/content/docs/docs/index.mdx b/packages/web/src/content/docs/docs/index.mdx
index b6b1ca95a..a43a52412 100644
--- a/packages/web/src/content/docs/docs/index.mdx
+++ b/packages/web/src/content/docs/docs/index.mdx
@@ -105,7 +105,7 @@ $ opencode auth login
 └
 ```
 
-Alternatively, you can select one of the other providers and add their API keys.
+Alternatively, you can select one of the other providers. [Learn more](/docs/providers#directory).
 
 ---
 
diff --git a/packages/web/src/content/docs/docs/models.mdx b/packages/web/src/content/docs/docs/models.mdx
index 488fd12ef..591625f8f 100644
--- a/packages/web/src/content/docs/docs/models.mdx
+++ b/packages/web/src/content/docs/docs/models.mdx
@@ -9,157 +9,47 @@ opencode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.
 
 ## Providers
 
-You can configure providers in your opencode config under the `provider` section.
-
----
-
-### Defaults
-
 Most popular providers are preloaded by default. If you've added the credentials for a provider through `opencode auth login`, they'll be available when you start opencode.
 
----
-
-### Custom
-
-You can add custom providers by specifying the npm package for the provider and the models you want to use.
-
-```json title="opencode.json" {5,9-11}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "moonshot": {
-      "npm": "@ai-sdk/openai-compatible",
-      "options": {
-        "baseURL": "https://api.moonshot.ai/v1"
-      },
-      "models": {
-        "kimi-k2-0711-preview": {}
-      }
-    }
-  }
-}
-```
+Learn more about [providers](/docs/providers).
 
 ---
 
-### Base URL
+## Select a model
 
-You can customize the base URL for any provider by setting the `baseURL` option. This is useful when using proxy services or custom endpoints.
+Once you've configured your provider you can select the model you want by typing in:
 
-```json title="opencode.json" {6}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "anthropic": {
-      "options": {
-        "baseURL": "https://api.anthropic.com/v1"
-      }
-    }
-  }
-}
+```bash frame="none"
+/models
 ```
 
 ---
 
-### OpenRouter
+## Recommended models
 
-Many OpenRouter models are preloaded by default - you can customize these or add your own.
+There are a lot of models out there, with new models coming out every week.
 
-Here's an example of specifying a provider
+:::tip
+Consider using one of the models we recommend.
+:::
 
-```json title="opencode.json"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "openrouter": {
-      "models": {
-        "moonshotai/kimi-k2": {
-          "options": {
-            "provider": {
-              "order": ["baseten"],
-              "allow_fallbacks": false
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
+However, there are a only a few of them that are good at both generating code and tool calling.
 
-You can also add additional models
+Here are the ones we recommend with opencode:
 
-```json title="opencode.json"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "openrouter": {
-      "models": {
-        "somecoolnewmodel": {},
-      }
-    }
-  }
-}
-```
+- Claude Sonnet 4
+- Claude Opus 4
+- Kimi K2
+- Qwen3 Coder
+- GPT 4.1
+- Gemini 2.5 Pro
 
 ---
 
-### Local
-
-You can configure local model like ones served through LM Studio or Ollama. To
-do so, you'll need to specify a couple of things.
-
-Here's an example of configuring a local model from LM Studio:
-
-```json title="opencode.json" {4-15}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "lmstudio": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "LM Studio (local)",
-      "options": {
-        "baseURL": "http://127.0.0.1:1234/v1"
-      },
-      "models": {
-        "google/gemma-3n-e4b": {
-          "name": "Gemma 3n-e4b (local)"
-        }
-      }
-    }
-  }
-}
-```
-
-In this example:
-
-- `lmstudio` is the custom provider ID. We'll use this later.
-- `npm` specifies the package to use for this provider. Here, `@ai-sdk/openai-compatible` is used for any OpenAI-compatible API.
-- `name` is the display name for the provider in the UI.
-- `options.baseURL` is the endpoint for the local server.
-- `models` is a map of model IDs to their configurations. The model name will be displayed in the model selection list.
-
-Similarly, to configure a local model from Ollama:
-
-```json title="opencode.json" {5,7}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "ollama": {
-      "npm": "@ai-sdk/openai-compatible",
-      "options": {
-        "baseURL": "http://localhost:11434/v1"
-      },
-      "models": {
-        "llama2": {}
-      }
-    }
-  }
-}
-```
+## Set a default
 
-To set one of these as the default model, you can set the `model` key at the
-root.
+To set one of these as the default model, you can set the `model` key in your
+opencode config.
 
 ```json title="opencode.json" {3}
 {
@@ -168,17 +58,9 @@ root.
 }
 ```
 
-Here the full ID is `provider_id/model_id`, where `provider_id` is the key in the `provider` list we set above and `model_id` is the key from the `provider.models` list.
-
----
-
-## Select a model
-
-If you have multiple models, you can select the model you want by typing in:
+Here the full ID is `provider_id/model_id`.
 
-```bash frame="none"
-/models
-```
+If you've configured a [custom provider](/docs/providers#custom), the `provider_id` is key from the `provider` part of your config, and the `model_id` is the key from `provider.models`.
 
 ---
 
diff --git a/packages/web/src/content/docs/docs/providers.mdx b/packages/web/src/content/docs/docs/providers.mdx
index 6a82f43e3..314acf7c5 100644
--- a/packages/web/src/content/docs/docs/providers.mdx
+++ b/packages/web/src/content/docs/docs/providers.mdx
@@ -5,3 +5,454 @@ description: Using any LLM provider in opencode.
 
 opencode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support for **75+ LLM providers** and it supports running local models.
 
+To add a provider you need to:
+
+1. Add the API keys for the provider using `opencode auth login`.
+2. Configure the provider in your opencode config.
+
+---
+
+### Credentials
+
+When you add a provider's API keys with `opencode auth login`, they are stored
+in `~/.local/share/opencode/auth.json`.
+
+---
+
+### Config
+
+You can customize the providers through the `provider` section in your opencode
+config.
+
+---
+
+#### Base URL
+
+You can customize the base URL for any provider by setting the `baseURL` option. This is useful when using proxy services or custom endpoints.
+
+```json title="opencode.json" {6}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "anthropic": {
+      "options": {
+        "baseURL": "https://api.anthropic.com/v1"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Directory
+
+Let's look at some of the providers in detail. If you'd like to add a provider to the
+list, feel free to open a PR.
+
+---
+
+### Amazon Bedrock
+
+To use Amazon Bedrock with opencode:
+
+1. Head over to the **Model catalog** in the Amazon Bedrock console and request
+   access to the models you want.
+   
+   :::tip
+   You need to have access to the model you want in Amazon Bedrock.
+   :::
+
+1. You'll need either to set one of the following environment variables:
+
+   - `AWS_ACCESS_KEY_ID`: You can get this by creating an IAM user and generating
+     an access key for it.
+   - `AWS_PROFILE`: First login through AWS IAM Identity Center (or AWS SSO) using
+     `aws sso login`. Then get the name of the profile you want to use.
+   - `AWS_BEARER_TOKEN_BEDROCK`: You can generate a long-term API key from the
+   Amazon Bedrock console.
+   
+   Once you have one of the above, set it while running opencode.
+   
+   ```bash
+   AWS_ACCESS_KEY_ID=XXX opencode
+   ```
+   
+   Or add it to a `.env` file in the project root.
+   
+   ```bash title=".env"
+   AWS_ACCESS_KEY_ID=XXX
+   ```
+   
+   Or add it to your bash profile.
+   
+   ```bash title="~/.bash_profile"
+   export AWS_ACCESS_KEY_ID=XXX
+   ```
+
+2. Run the `/models` command to select the model you want.
+
+---
+
+### Anthropic
+
+We recommend signing up for [Claude Pro](https://www.anthropic.com/news/claude-pro) or [Max](https://www.anthropic.com/max), it's the most cost-effective way to use opencode.
+
+Once you've singed up, run `opencode auth login` and select Anthropic.
+
+```bash
+$ opencode auth login
+
+┌  Add credential
+│
+◆  Select provider
+│  ● Anthropic (recommended)
+│  ○ OpenAI
+│  ○ Google
+│  ...
+└
+```
+
+This will ask you login with your Anthropic account in your browser. Now all the
+the Anthropic models should be available when you use the `/models` command.
+
+---
+
+### GitHub Copilot
+
+To use your GitHub Copilot subscription with opencode:
+
+:::note
+Some models might need a [Pro+
+subscription](https://github.com/features/copilot/plans) to use.
+:::
+
+1. Run `opencode auth login` and select GitHub Copilot.
+
+   ```bash
+   $ opencode auth login
+   ┌  Add credential
+   
+   │
+   ◇  Select provider
+   │  GitHub Copilot
+   │
+   ◇   ──────────────────────────────────────────────╮
+   │                                                 │
+   │  Please visit: https://github.com/login/device  │
+   │  Enter code: 8F43-6FCF                          │
+   │                                                 │
+   ├─────────────────────────────────────────────────╯
+   │
+   ◓  Waiting for authorization...
+   ```
+
+2. Navigate to [github.com/login/device](https://github.com/login/device) and enter the code.
+
+3. Now run the `/models` command to select the model you want.
+
+---
+
+### Groq
+
+1. Head over to the [Groq console](https://console.groq.com/), click **Create API Key**, and copy the key.
+
+2. Run `opencode auth login` and select Groq.
+
+   ```bash
+   $ opencode auth login
+
+   ┌  Add credential
+   │
+   ◆  Select provider
+   │  ● Groq
+   │  ...
+   └
+   ```
+   
+3. Enter the API key for the provider.
+
+   ```bash
+   $ opencode auth login
+
+   ┌  Add credential
+   │
+   ◇  Select provider
+   │  Groq
+   │
+   ◇  Enter your API key
+   │  _
+   └
+   ```
+
+4. Run the `/models` command to select the one you want.
+
+---
+
+### LM Studio
+
+You can configure opencode to use local models through LM Studio.
+
+```json title="opencode.json" "lmstudio" {5, 6, 8, 10-14}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "lmstudio": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "LM Studio (local)",
+      "options": {
+        "baseURL": "http://127.0.0.1:1234/v1"
+      },
+      "models": {
+        "google/gemma-3n-e4b": {
+          "name": "Gemma 3n-e4b (local)"
+        }
+      }
+    }
+  }
+}
+```
+
+In this example:
+
+- `lmstudio` is the custom provider ID. This can be any string you want.
+- `npm` specifies the package to use for this provider. Here, `@ai-sdk/openai-compatible` is used for any OpenAI-compatible API.
+- `name` is the display name for the provider in the UI.
+- `options.baseURL` is the endpoint for the local server.
+- `models` is a map of model IDs to their configurations. The model name will be displayed in the model selection list.
+
+---
+
+### Ollama
+
+You can configure opencode to use local models through Ollama.
+
+```json title="opencode.json" "ollama" {5, 6, 8, 10-14}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama (local)",
+      "options": {
+        "baseURL": "http://localhost:11434/v1"
+      },
+      "models": {
+        "llama2": {
+          "name": "Llama 2"
+        }
+      }
+    }
+  }
+}
+```
+
+In this example:
+
+- `ollama` is the custom provider ID. This can be any string you want.
+- `npm` specifies the package to use for this provider. Here, `@ai-sdk/openai-compatible` is used for any OpenAI-compatible API.
+- `name` is the display name for the provider in the UI.
+- `options.baseURL` is the endpoint for the local server.
+- `models` is a map of model IDs to their configurations. The model name will be displayed in the model selection list.
+
+---
+
+### OpenAI
+
+https://platform.openai.com/api-keys
+
+1. Head over to the [OpenAI Platform console](https://platform.openai.com/api-keys), click **Create new secret key**, and copy the key.
+
+2. Run `opencode auth login` and select OpenAI.
+
+   ```bash
+   $ opencode auth login
+
+   ┌  Add credential
+   │
+   ◆  Select provider
+   │  ● OpenAI
+   │  ...
+   └
+   ```
+   
+3. Enter the API key for the provider.
+
+   ```bash
+   $ opencode auth login
+
+   ┌  Add credential
+   │
+   ◇  Select provider
+   │  OpenAI
+   │
+   ◇  Enter your API key
+   │  _
+   └
+   ```
+
+4. Run the `/models` command to select the one you want.
+
+---
+
+### OpenRouter
+
+1. Head over to the [OpenRouter dashboard](https://openrouter.ai/settings/keys), click **Create API Key**, and copy the key.
+
+2. Run `opencode auth login` and select OpenRouter.
+
+   ```bash
+   $ opencode auth login
+
+   ┌  Add credential
+   │
+   ◆  Select provider
+   │  ● OpenRouter
+   │  ○ Anthropic
+   │  ○ Google
+   │  ...
+   └
+   ```
+   
+3. Enter the API key for the provider.
+
+   ```bash
+   $ opencode auth login
+
+   ┌  Add credential
+   │
+   ◇  Select provider
+   │  OpenRouter
+   │
+   ◇  Enter your API key
+   │  _
+   └
+   ```
+
+4. Many OpenRouter models are preloaded by default, run the `/models` command to select the one you want.
+
+   You can also add additional models through your opencode config.
+   
+   ```json title="opencode.json" {6}
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "provider": {
+       "openrouter": {
+         "models": {
+           "somecoolnewmodel": {},
+         }
+       }
+     }
+   }
+   ```
+
+5. You can also customize them through your opencode config. Here's an example of specifying a provider
+   
+   ```json title="opencode.json"
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "provider": {
+       "openrouter": {
+         "models": {
+           "moonshotai/kimi-k2": {
+             "options": {
+               "provider": {
+                 "order": ["baseten"],
+                 "allow_fallbacks": false
+               }
+             }
+           }
+         }
+       }
+     }
+   }
+   ```
+
+---
+
+### Custom
+
+To add any **OpenAI-compatible** provider that's not listed in `opencode auth login`:
+
+:::tip
+You can use any OpenAI-compatible provider with opencode.
+:::
+
+1. Scroll down to **Other**.
+
+   ```bash
+   $ opencode auth login
+   
+   ┌  Add credential
+   │
+   ◆  Select provider
+   │  ...
+   │  ● Other
+   └
+   ```
+
+2. Enter the ID for the provider.
+
+   ```bash
+   $ opencode auth login
+   
+   ┌  Add credential
+   │
+   ◆  Select provider
+   │  ...
+   │  ● Other
+   │
+   ◇  Enter provider id
+   │  _
+   └
+   ```
+
+   You can use any ID you want, we'll use this later in the opencode config.
+
+3. Add the API keys for the provider.
+
+   ```bash
+   $ opencode auth login
+ 
+   ┌  Add credential
+   │
+   ◇  Select provider
+   │  Other
+   │
+   ◇  Enter provider id
+   │  coolnewprovider
+   │
+   ▲  This only stores a credential for coolnewprovider - you will need configure it in opencode.json, check the docs for examples.
+   │
+   ◆  Enter your API key
+   │  _
+   └
+   ```
+
+4. Configure the provider in your [opencode config](/docs/config).
+
+   ```json title="opencode.json" "coolnewprovider" {7,9-11}
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "provider": {
+       "coolnewprovider": {
+         "npm": "@ai-sdk/openai-compatible",
+         "options": {
+           "baseURL": "https://api.newaicompany.com/v1"
+         },
+         "models": {
+           "newmodel-m1-0711-preview": {}
+         }
+       }
+     }
+   }
+   ```
+
+   A couple of things to note here:
+
+   - We are using the provider ID we entered earlier, `coolnewprovider` in
+   this example.
+   - The `baseURL` is the OpenAI-compatible endpoint for the provider.
+   - And we are listing the models we want to use. This will show up when we run
+     the `/models` command.
+