diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md
index 3ab4bbc7d..8a1c81d8a 100644
--- a/docs/gateway/authentication.md
+++ b/docs/gateway/authentication.md
@@ -114,7 +114,9 @@ clawdbot doctor
 
 ### Per-session (chat command)
 
-Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:claude-cli`, `anthropic:default`). Use `/model status` to see candidates + which one is next.
+Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:claude-cli`, `anthropic:default`).
+
+Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
 
 ### Per-agent (CLI override)
 
diff --git a/docs/start/faq.md b/docs/start/faq.md
index 93500055f..825c42ebe 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -887,7 +887,9 @@ For background processes (from the exec tool), you can ask the agent to run:
 process action:kill sessionId:XXX
 ```
 
-Slash commands only run when the **entire** message is the command (must start with `/`). Inline text like `hello /status` is ignored.
+Slash commands overview: see [Slash commands](/tools/slash-commands).
+
+Most commands must be sent as a **standalone** message that starts with `/`, but a few shortcuts (like `/status`) also work inline for allowlisted senders.
 
 ### Why does it feel like the bot “ignores” rapid‑fire messages?
 
diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md
index 6f552d49f..f18d04579 100644
--- a/docs/tools/slash-commands.md
+++ b/docs/tools/slash-commands.md
@@ -6,10 +6,18 @@ read_when:
 ---
 # Slash commands
 
-Commands are handled by the Gateway. Send them as a **standalone** message that starts with `/`.
-Inline text like `hello /status` is ignored for commands.
+Commands are handled by the Gateway. Most commands must be sent as a **standalone** message that starts with `/`.
 
-Directives (`/think`, `/verbose`, `/reasoning`, `/elevated`) are parsed even when inline and are stripped from the message before the model sees it.
+There are two related systems:
+
+- **Commands**: standalone `/...` messages.
+- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue`.
+  - Directives are stripped from the message before the model sees it.
+  - In normal chat messages (not directive-only), they are treated as “inline hints” and do **not** persist session settings.
+  - In directive-only messages (the message contains only directives), they persist to the session and reply with an acknowledgement.
+
+There are also a few **inline shortcuts** (allowlisted/authorized senders only): `/help`, `/commands`, `/status` (`/usage`), `/whoami` (`/id`).
+They run immediately, are stripped before the model sees the message, and the remaining text continues through the normal flow.
 
 ## Config
 
@@ -69,8 +77,28 @@ Notes:
 - `/verbose` is meant for debugging and extra visibility; keep it **off** in normal use.
 - `/reasoning` (and `/verbose`) are risky in group settings: they may reveal internal reasoning or tool output you did not intend to expose. Prefer leaving them off, especially in group chats.
 - **Fast path:** command-only messages from allowlisted senders are handled immediately (bypass queue + model).
-- **Inline shortcuts:** `/help`, `/commands`, `/status` (`/usage`), `/whoami` (`/id`) are also parsed when embedded in text. They run immediately, are stripped before the model sees the message, and the remaining text continues through the normal flow.
-- Unauthorized command-only messages are silently ignored.
+- **Inline shortcuts (allowlisted senders only):** `/help`, `/commands`, `/status` (`/usage`), `/whoami` (`/id`) also work when embedded in text.
+- Unauthorized command-only messages are silently ignored, and inline `/...` tokens are treated as plain text.
+
+## Model selection (`/model`)
+
+`/model` is implemented as a directive.
+
+Examples:
+
+```
+/model
+/model list
+/model 3
+/model openai/gpt-5.2
+/model opus@anthropic:claude-cli
+/model status
+```
+
+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 status` shows the detailed view, including configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
 
 ## Debug overrides