diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 728b8141a..7606d9a8c 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -108,6 +108,14 @@ These are commands you run from your shell.
 | `hermes sessions prune` | Remove old sessions |
 | `hermes sessions stats` | Show session statistics |
 
+### Insights
+
+| Command | Description |
+|---------|-------------|
+| `hermes insights` | Show usage analytics for the last 30 days |
+| `hermes insights --days 7` | Analyze a custom time window |
+| `hermes insights --source telegram` | Filter by platform |
+
 ---
 
 ## Slash Commands (Inside Chat)
@@ -145,6 +153,7 @@ Type `/` in the interactive CLI to see an autocomplete dropdown.
 | `/save` | Save the current conversation |
 | `/compress` | Manually compress conversation context |
 | `/usage` | Show token usage for this session |
+| `/insights [--days N]` | Show usage insights and analytics (last 30 days) |
 
 ### Media & Input
 
diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md
index e31463e2a..df07739c2 100644
--- a/website/docs/user-guide/cli.md
+++ b/website/docs/user-guide/cli.md
@@ -106,6 +106,7 @@ Type `/` to see an autocomplete dropdown of all available commands.
 | `/save` | Save the current conversation |
 | `/compress` | Manually compress conversation context |
 | `/usage` | Show token usage for this session |
+| `/insights [--days N]` | Show usage insights and analytics (last 30 days) |
 
 ### Skills & Scheduling
 
diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md
index c3a0eb07f..12fec3fd2 100644
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@@ -72,6 +72,7 @@ hermes gateway status       # Check service status
 | `/sethome` | Set this chat as the home channel |
 | `/compress` | Manually compress conversation context |
 | `/usage` | Show token usage for this session |
+| `/insights [days]` | Show usage insights and analytics |
 | `/reload-mcp` | Reload MCP servers from config |
 | `/update` | Update Hermes Agent to the latest version |
 | `/help` | Show available commands |
diff --git a/website/docs/user-guide/sessions.md b/website/docs/user-guide/sessions.md
index cea0b4d3d..92f6e1218 100644
--- a/website/docs/user-guide/sessions.md
+++ b/website/docs/user-guide/sessions.md
@@ -159,6 +159,8 @@ Total messages: 3847
 Database size: 12.4 MB
 ```
 
+For deeper analytics — token usage, cost estimates, tool breakdown, and activity patterns — use [`hermes insights`](/docs/reference/cli-commands#insights).
+
 ## Session Search Tool
 
 The agent has a built-in `session_search` tool that performs full-text search across all past conversations using SQLite's FTS5 engine.