docs: edit providers doc

1 files changed, 59 insertions, 121 deletions

diff --git a/packages/web/src/content/docs/docs/providers.mdx b/packages/web/src/content/docs/docs/providers.mdx
index 7426500d9..565ec3f51 100644
--- a/packages/web/src/content/docs/docs/providers.mdx
+++ b/packages/web/src/content/docs/docs/providers.mdx
@@ -45,72 +45,6 @@ You can customize the base URL for any provider by setting the `baseURL` option.
 
 ---
 
-## Troubleshooting
-
-### Credential Loop Issue
-
-If you're stuck in a credential loop when adding a custom provider (like Cerebras), this usually happens when the provider configuration is incomplete. Here's how to fix it:
-
-1. **Complete the auth setup**: Make sure you've successfully added the credential using `opencode auth login` and selected **Other**.
-
-2. **Configure the provider**: The credential alone isn't enough. You must also configure the provider in your `opencode.json` file with the correct `npm` package, `baseURL`, and models.
-
-3. **Use the correct npm package**: 
-   - For Cerebras: Use `@ai-sdk/cerebras` (not `@ai-sdk/openai-compatible`)
-   - For most other OpenAI-compatible providers: Use `@ai-sdk/openai-compatible`
-
-4. **Example working configuration**:
-   ```json title="opencode.json"
-   {
-     "$schema": "https://opencode.ai/config.json",
-     "model": "cerebras/qwen-3-235b-a22b",
-     "provider": {
-       "cerebras": {
-         "npm": "@ai-sdk/cerebras",
-         "name": "Cerebras",
-         "options": {
-           "baseURL": "https://api.cerebras.ai/v1"
-         },
-         "models": {
-           "qwen-3-235b-a22b": {
-             "name": "Qwen-3-235b-a22b"
-           }
-         }
-       }
-     }
-   }
-   ```
-
-### Global vs Local Configuration
-
-opencode looks for configuration in this order:
-
-1. **Local config**: `./opencode.json` in your current project directory
-2. **Global config**: `~/.local/share/opencode/auth.json` (credentials only)
-
-:::tip
-If you want to use a provider globally, add the provider configuration to a local `opencode.json` file in each project where you want to use it. The credentials from the global auth file will be automatically used.
-:::
-
-**Best practice**: 
-- Store credentials globally using `opencode auth login`
-- Store provider configurations locally in each project's `opencode.json`
-
-### Common Configuration Mistakes
-
-1. **Wrong npm package**: Using `@ai-sdk/openai-compatible` when a specific package exists (like `@ai-sdk/cerebras`)
-
-2. **Missing baseURL**: Always include the correct API endpoint in the `options.baseURL` field
-
-3. **Incomplete model configuration**: Make sure to define at least one model in the `models` object
-
-4. **API key format**: Different providers use different API key prefixes:
-   - OpenAI: `sk-...`
-   - Cerebras: `csk-...`
-   - Anthropic: Uses OAuth (no manual key needed)
-
----
-
 ## Directory
 
 Let's look at some of the providers in detail. If you'd like to add a provider to the
@@ -667,8 +601,6 @@ To add any **OpenAI-compatible** provider that's not listed in `opencode auth lo
 You can use any OpenAI-compatible provider with opencode. Most modern AI providers offer OpenAI-compatible APIs.
 :::
 
-#### Step 1: Add Credentials
-
 1. Run `opencode auth login` and scroll down to **Other**.
 
    ```bash
@@ -682,7 +614,7 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide
    └
    ```
 
-2. Enter a unique ID for the provider (use lowercase, no spaces).
+2. Enter a unique ID for the provider.
 
    ```bash
    $ opencode auth login
@@ -695,7 +627,7 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide
    ```
 
    :::note
-   Choose a memorable ID - you'll use this in your config file.
+   Choose a memorable ID, you'll use this in your config file.
    :::
 
 3. Enter your API key for the provider.
@@ -712,19 +644,60 @@ You can use any OpenAI-compatible provider with opencode. Most modern AI provide
    └
    ```
 
-#### Step 2: Configure Provider
+4. Create or update your `opencode.json` file in your project directory:
+
+   ```json title="opencode.json" "\"myprovider\"" {5-15}
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "provider": {
+       "myprovider": {
+         "npm": "@ai-sdk/openai-compatible",
+         "name": "My AI ProviderDisplay Name",
+         "options": {
+           "baseURL": "https://api.myprovider.com/v1"
+         },
+         "models": {
+           "my-model-name": {
+             "name": "My Model Display Name"
+           }
+         }
+       }
+     }
+   }
+   ```
+
+   Here are the configuration options:
+   
+   - **npm**: AI SDK package to use, `@ai-sdk/openai-compatible` for OpenAI-compatible providers
+   - **name**: Display name in UI.
+   - **models**: Available models.
+   - **options.baseURL**: API endpoint URL.
+   - **options.apiKey**: Optionally set the API key, if not using auth.
+   - **options.headers**: Optionally set custom headers.
+
+   More on the advanced options in the example below.
+
+5. Run the `/models` command and your custom provider and models will appear in the selection list.
+
+---
+
+##### Example
 
-Create or update your `opencode.json` file in your project directory:
+Here's an example setting the `apiKey` and `headers` options.
 
-```json title="opencode.json" "myprovider" {5-15}
+```json title="opencode.json" {9,11}
 {
   "$schema": "https://opencode.ai/config.json",
   "provider": {
     "myprovider": {
       "npm": "@ai-sdk/openai-compatible",
-      "name": "My AI Provider",
+      "name": "My AI ProviderDisplay Name",
       "options": {
-        "baseURL": "https://api.myprovider.com/v1"
+        "baseURL": "https://api.myprovider.com/v1",
+        "apiKey": "{env:ANTHROPIC_API_KEY}",
+        "headers": {
+          "Authorization": "Bearer custom-token"
+        }
       },
       "models": {
         "my-model-name": {
@@ -736,15 +709,7 @@ Create or update your `opencode.json` file in your project directory:
 }
 ```
 
-#### Configuration Options
-
-| Field | Description | Required |
-|-------|-------------|----------|
-| `npm` | AI SDK package to use | ✅ |
-| `name` | Display name in UI | ✅ |
-| `options.baseURL` | API endpoint URL | ✅ |
-| `models` | Available models | ✅ |
-| `options.apiKey` | API key (if not using auth) | ❌ |
+We are setting the `apiKey` using the `env` variable syntax, [learn more](/docs/config#env-vars).
 
 #### Common Examples
 
@@ -789,46 +754,19 @@ Create or update your `opencode.json` file in your project directory:
   }
 }
 ```
+---
 
-**Local API (with custom headers):**
-```json title="opencode.json"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "local": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "Local API",
-      "options": {
-        "baseURL": "http://localhost:8000/v1",
-        "headers": {
-          "Authorization": "Bearer custom-token"
-        }
-      },
-      "models": {
-        "local-model": {
-          "name": "Local Model"
-        }
-      }
-    }
-  }
-}
-```
-
-#### Step 3: Select Model
-
-Run the `/models` command to select your custom provider's model:
+## Troubleshooting
 
-```bash
-$ opencode
-> /models
-```
+If you are having trouble with configuring a provider, check the following:
 
-Your custom provider and models will appear in the selection list.
+1. **Check the auth setup**: Run `opencode auth list` to see if the credentials
+   for the provider are added to your config.
 
-#### Tips
+   This doesn't apply to providers like Amazon Bedrock, that rely on environment variables for their auth.
 
-- **Provider ID**: Use lowercase letters and hyphens only (e.g., `my-provider`)
-- **Model names**: Use the exact model ID from the provider's API documentation
-- **Base URL**: Always include the full path (usually ending in `/v1`)
-- **Testing**: Start with one model to test the configuration before adding more
+2. For custom providers, check the opencode config and:
 
+   - Make sure the provider ID used in `opencode auth login` matches the ID in your opencode config.
+   - The right npm package is used for the provider. For example, use `@ai-sdk/cerebras` for Cerebras. And for all other OpenAI-compatible providers, use `@ai-sdk/openai-compatible`.
+   - Check correct API endpoint is used in the `options.baseURL` field.