From 4f9a08a5cdb7786dfef8efa0a0436a1ac066e3b3 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 12 Jan 2026 06:53:40 +0000
Subject: [PATCH] docs: clarify usage in slash commands

---
 docs/concepts/models.md      | 19 +++++++++++++++++++
 docs/tools/slash-commands.md |  8 +++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/concepts/models.md b/docs/concepts/models.md
index 069a23340..8a352ae38 100644
--- a/docs/concepts/models.md
+++ b/docs/concepts/models.md
@@ -86,6 +86,25 @@ Example allowlist config:
 }
 ```
 
+## Switching models in chat (`/model`)
+
+You can switch models for the current session without restarting:
+
+```
+/model
+/model list
+/model 3
+/model openai/gpt-5.2
+/model status
+```
+
+Notes:
+- `/model` (and `/model list`) is a compact, numbered picker (model family + available providers).
+- `/model <#>` selects from that picker.
+- `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
+
+Full command behavior/config: [Slash commands](/tools/slash-commands).
+
 ## CLI commands
 
 ```bash
diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md
index f18d04579..2e19193f5 100644
--- a/docs/tools/slash-commands.md
+++ b/docs/tools/slash-commands.md
@@ -48,7 +48,7 @@ They run immediately, are stripped before the model sees the message, and the re
 Text + native (when enabled):
 - `/help`
 - `/commands`
-- `/status` (show current status; includes a short usage line when available)
+- `/status` (show current status; includes a short provider usage/quota line when available)
 - `/usage` (alias: `/status`)
 - `/whoami` (show your sender id; alias: `/id`)
 - `/config show|get|set|unset` (persist config to disk, owner-only; requires `commands.config: true`)
@@ -80,6 +80,12 @@ Notes:
 - **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.
 
+## Usage vs cost (what shows where)
+
+- **Provider usage/quota** (example: “Claude 80% left”) shows up in `/status` when provider usage tracking is enabled.
+- **Per-response tokens/cost** is controlled by `/cost on|off` (appended to normal replies).
+- `/model status` is about **models/auth/endpoints**, not usage.
+
 ## Model selection (`/model`)
 
 `/model` is implemented as a directive.