diff --git a/docs/concepts/models.md b/docs/concepts/models.md
index d900a21af..75a0b06d3 100644
--- a/docs/concepts/models.md
+++ b/docs/concepts/models.md
@@ -92,15 +92,19 @@ You can switch models for the current session without restarting:
 
 ```
 /model
-/model list
-/model 3
-/model openai/gpt-5.2
 /model status
+/model openai/gpt-5.2
+/model opus
+/models
+/models openai
 ```
 
 Notes:
-- `/model` (and `/model list`) is a compact, numbered picker (model family + available providers).
-- `/model <#>` selects from that picker.
+- `/model` shows a summary of the current model and brief usage instructions.
+- `/model <provider/model>` switches to that exact model.
+- `/model <alias>` switches using a configured alias (for example, `/model opus`).
+- `/models` lists available providers, and `/models <provider>` lists that provider's models.
+- Numeric selection like `/model 3` is not supported.
 - `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
 - Model refs are parsed by splitting on the **first** `/`. Use `provider/model` when typing `/model <ref>`.
 - If the model ID itself contains `/` (OpenRouter-style), you must include the provider prefix (example: `/model openrouter/moonshotai/kimi-k2`).
diff --git a/docs/help/faq.md b/docs/help/faq.md
index 7372a4997..6ddfa88b9 100644
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -1925,13 +1925,9 @@ Use the `/model` command as a standalone message:
 /model gemini-flash
 ```
 
-You can list available models with `/model`, `/model list`, or `/model status`.
+You can view providers with `/models`, list a provider's models with `/models <provider>`, and switch models with `/model <provider/model>` or `/model <alias>`.
 
-`/model` (and `/model list`) shows a compact, numbered picker. Select by number:
-
-```
-/model 3
-```
+Use `/model status` for a detailed view of your current model and auth configuration.
 
 You can also force a specific auth profile for the provider (per session):
 
diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md
index d654cb281..dec06ec5b 100644
--- a/docs/tools/slash-commands.md
+++ b/docs/tools/slash-commands.md
@@ -131,16 +131,19 @@ Examples:
 
 ```
 /model
-/model list
-/model 3
-/model openai/gpt-5.2
-/model opus@anthropic:default
 /model status
+/model openai/gpt-5.2
+/model opus
+/models
+/models openai
 ```
 
 Notes:
-- `/model` and `/model list` show a compact, numbered picker (model family + available providers).
-- `/model <#>` selects from that picker (and prefers the current provider when possible).
+- `/model` shows a summary of the current model plus usage instructions.
+- `/model <provider/model>` switches to that exact model.
+- `/model <alias>` switches using a configured alias (for example, `/model opus`).
+- `/models` lists available providers, and `/models <provider>` lists that provider's models.
+- Numeric selection like `/model 3` is not supported.
 - `/model status` shows the detailed view, including configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
 
 ## Debug overrides