diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md
index 83cbfeecf2..9a27a71312 100644
--- a/website/docs/reference/slash-commands.md
+++ b/website/docs/reference/slash-commands.md
@@ -63,7 +63,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
 | Command | Description |
 |---------|-------------|
 | `/help` | Show this help message |
-| `/usage` | Show token usage for the current session |
+| `/usage` | Show token usage, cost breakdown, and session duration |
 | `/insights` | Show usage insights and analytics (last 30 days) |
 | `/platforms` | Show gateway/messaging platform status |
 | `/paste` | Check clipboard for an image and attach it |
@@ -104,7 +104,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
 | `/compress` | Manually compress conversation context. |
 | `/title [name]` | Set or show the session title. |
 | `/resume [name]` | Resume a previously named session. |
-| `/usage` | Show token usage for the current session. |
+| `/usage` | Show token usage, estimated cost breakdown (input/output), context window state, and session duration. |
 | `/insights [days]` | Show usage analytics. |
 | `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display. |
 | `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | Control spoken replies in chat. `join`/`channel`/`leave` manage Discord voice-channel mode. |
diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md
index 0211ae36ba..a33ed295e4 100644
--- a/website/docs/user-guide/cli.md
+++ b/website/docs/user-guide/cli.md
@@ -50,6 +50,35 @@ hermes -w -q "Fix issue #123"     # Single query in worktree
 
 The welcome banner shows your model, terminal backend, working directory, available tools, and installed skills at a glance.
 
+### Status Bar
+
+A persistent status bar sits above the input area, updating in real time:
+
+```
+ ⚕ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m
+```
+
+| Element | Description |
+|---------|-------------|
+| Model name | Current model (truncated if longer than 26 chars) |
+| Token count | Context tokens used / max context window |
+| Context bar | Visual fill indicator with color-coded thresholds |
+| Cost | Estimated session cost (or `n/a` for unknown/zero-priced models) |
+| Duration | Elapsed session time |
+
+The bar adapts to terminal width — full layout at ≥ 76 columns, compact at 52–75, minimal (model + duration only) below 52.
+
+**Context color coding:**
+
+| Color | Threshold | Meaning |
+|-------|-----------|---------|
+| Green | < 50% | Plenty of room |
+| Yellow | 50–80% | Getting full |
+| Orange | 80–95% | Approaching limit |
+| Red | ≥ 95% | Near overflow — consider `/compress` |
+
+Use `/usage` for a detailed breakdown including per-category costs (input vs output tokens).
+
 ### Session Resume Display
 
 When resuming a previous session (`hermes -c` or `hermes --resume <id>`), a "Previous Conversation" panel appears between the banner and the input prompt, showing a compact recap of the conversation history. See [Sessions — Conversation Recap on Resume](sessions.md#conversation-recap-on-resume) for details and configuration.