docs: add variants docs (#6516)

Co-authored-by: David Hill <[email protected]>

2 files changed, 83 insertions, 22 deletions

diff --git a/packages/web/src/content/docs/keybinds.mdx b/packages/web/src/content/docs/keybinds.mdx
index 04d03d0d8..79464642f 100644
--- a/packages/web/src/content/docs/keybinds.mdx
+++ b/packages/web/src/content/docs/keybinds.mdx
@@ -43,6 +43,7 @@ OpenCode has a list of keybinds that you can customize through the OpenCode conf
     "model_list": "<leader>m",
     "model_cycle_recent": "f2",
     "model_cycle_recent_reverse": "shift+f2",
+    "variant_cycle": "ctrl+t",
     "command_list": "ctrl+p",
     "agent_list": "<leader>a",
     "agent_cycle": "tab",
diff --git a/packages/web/src/content/docs/models.mdx b/packages/web/src/content/docs/models.mdx
index 2077b8e0b..e070f1e2e 100644
--- a/packages/web/src/content/docs/models.mdx
+++ b/packages/web/src/content/docs/models.mdx
@@ -35,15 +35,13 @@ Consider using one of the models we recommend.
 
 However, there are only a few of them that are good at both generating code and tool calling.
 
-Here are several models that work well with OpenCode, in no particular order. (This is not an exhaustive list):
+Here are several models that work well with OpenCode, in no particular order. (This is not an exhaustive list nor is it necessarily up to date):
 
-- GPT 5.1
+- GPT 5.2
 - GPT 5.1 Codex
+- Claude Opus 4.5
 - Claude Sonnet 4.5
-- Claude Haiku 4.5
-- Kimi K2
-- GLM 4.6
-- Qwen3 Coder
+- Minimax M2.1
 - Gemini 3 Pro
 
 ---
@@ -107,30 +105,88 @@ The built-in provider and model names can be found on [Models.dev](https://model
 
 You can also configure these options for any agents that you are using. The agent config overrides any global options here. [Learn more](/docs/agents/#additional).
 
-You can also define custom models that extend built-in ones and can optionally use specific options by referring to their id:
+You can also define custom variants that extend built-in ones. Variants let you configure different settings for the same model without creating duplicate entries:
 
-```jsonc title="opencode.jsonc" {6-20}
+```jsonc title="opencode.jsonc" {6-21}
 {
   "$schema": "https://opencode.ai/config.json",
   "provider": {
     "opencode": {
       "models": {
-        "gpt-5-high": {
-          "id": "gpt-5",
-          "name": "MyGPT5 (High Reasoning)",
-          "options": {
-            "reasoningEffort": "high",
-            "textVerbosity": "low",
-            "reasoningSummary": "auto",
+        "gpt-5": {
+          "variants": {
+            "high": {
+              "reasoningEffort": "high",
+              "textVerbosity": "low",
+              "reasoningSummary": "auto",
+            },
+            "low": {
+              "reasoningEffort": "low",
+              "textVerbosity": "low",
+              "reasoningSummary": "auto",
+            },
           },
         },
-        "gpt-5-low": {
-          "id": "gpt-5",
-          "name": "MyGPT5 (Low Reasoning)",
-          "options": {
-            "reasoningEffort": "low",
-            "textVerbosity": "low",
-            "reasoningSummary": "auto",
+      },
+    },
+  },
+}
+```
+
+---
+
+## Variants
+
+Many models support multiple variants with different configurations. OpenCode ships with built-in default variants for popular providers.
+
+### Built-in variants
+
+OpenCode ships with default variants for many providers:
+
+**Anthropic**:
+
+- `high` - High thinking budget (default)
+- `max` - Maximum thinking budget
+
+**OpenAI**:
+
+Varies by model but roughly:
+
+- `none` - No reasoning
+- `minimal` - Minimal reasoning effort
+- `low` - Low reasoning effort
+- `medium` - Medium reasoning effort
+- `high` - High reasoning effort
+- `xhigh` - Extra high reasoning effort
+
+**Google**:
+
+- `low` - Lower effort/token budget
+- `high` - Higher effort/token budget
+
+:::tip
+This list is not comprehensive. Many other providers have built-in defaults too.
+:::
+
+### Custom variants
+
+You can override existing variants or add your own:
+
+```jsonc title="opencode.jsonc" {7-18}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "openai": {
+      "models": {
+        "gpt-5": {
+          "variants": {
+            "thinking": {
+              "reasoningEffort": "high",
+              "textVerbosity": "low",
+            },
+            "fast": {
+              "disabled": true,
+            },
           },
         },
       },
@@ -139,6 +195,10 @@ You can also define custom models that extend built-in ones and can optionally u
 }
 ```
 
+### Cycle variants
+
+Use the keybind `variant_cycle` to quickly switch between variants. [Learn more](/docs/keybinds).
+
 ---
 
 ## Loading models