From 468201190eacb7b0e573f2ee8a603894db829b1b Mon Sep 17 00:00:00 2001
From: Giuseppe Rota <403432+grota@users.noreply.github.com>
Date: Mon, 29 Sep 2025 13:52:26 +0200
Subject: docs: document model id behavior (#2856)

---
 packages/web/src/content/docs/models.mdx | 33 +++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

(limited to 'packages/web/src/content/docs/models.mdx')

diff --git a/packages/web/src/content/docs/models.mdx b/packages/web/src/content/docs/models.mdx
index efebc5cb4..b3fc4c28f 100644
--- a/packages/web/src/content/docs/models.mdx
+++ b/packages/web/src/content/docs/models.mdx
@@ -100,10 +100,41 @@ You can globally configure a model's options through the config.
 }
 ```
 
-Here we're configuring global settings for two models: `gpt-5` when accessed via the `openai` provider, and `claude-sonnet-4-20250514` when accessed via the `anthropic` provider.
+Here we're configuring global settings for two built-in models: `gpt-5` when accessed via the `openai` provider, and `claude-sonnet-4-20250514` when accessed via the `anthropic` provider.  
+The built-in provider and model names can be found on [Models.dev](https://models.dev).
 
 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:
+
+```jsonc title="opencode.jsonc" {6-20}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "opencode": {
+      "models": {
+        "gpt-5-high": {
+          "id": "gpt-5",
+          "options": {
+            "reasoningEffort": "high",
+            "textVerbosity": "low",
+            "reasoningSummary": "auto"
+          }
+        },
+        "gpt-5-low": {
+          "id": "gpt-5",
+          "options": {
+            "reasoningEffort": "low",
+            "textVerbosity": "low",
+            "reasoningSummary": "auto"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ---
 
 ## Loading models
-- 
cgit v1.2.3

