From 4d6f380bd1c88a93343f3f576c72f43764dbaee5 Mon Sep 17 00:00:00 2001
From: teknium1 <teknium1@gmail.com>
Date: Sun, 1 Mar 2026 00:28:07 -0800
Subject: [PATCH] docs: update README and CLI documentation for new commands

Enhanced the README and CLI documentation to include the newly added `/compress` and `/usage` commands for managing conversation context and monitoring token usage. Updated log descriptions to clarify the contents of log files and ensured that sensitive information is automatically redacted. This improves user understanding of available features and log management.
---
 README.md         | 15 +++++++++++++--
 docs/cli.md       |  3 +++
 docs/messaging.md |  7 +++++++
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f63bb2f1a..531a3049e 100644
--- a/README.md
+++ b/README.md
@@ -146,7 +146,7 @@ All your settings are stored in `~/.hermes/` for easy access:
 ├── skills/         # Agent-created skills (managed via skill_manage tool)
 ├── cron/           # Scheduled jobs
 ├── sessions/       # Gateway sessions
-└── logs/           # Logs
+└── logs/           # Logs (errors.log, gateway.log — secrets auto-redacted)
 ```
 
 ### Managing Configuration
@@ -293,6 +293,8 @@ See [docs/messaging.md](docs/messaging.md) for advanced WhatsApp configuration.
 | `/status` | Show session info |
 | `/stop` | Stop the running agent |
 | `/sethome` | Set this chat as the home channel |
+| `/compress` | Manually compress conversation context |
+| `/usage` | Show token usage for this session |
 | `/help` | Show available commands |
 | `/<skill-name>` | Invoke any installed skill (e.g., `/axolotl`, `/gif-search`) |
 
@@ -424,6 +426,9 @@ Type `/` to see an autocomplete dropdown of all commands.
 | `/cron` | Manage scheduled tasks |
 | `/skills` | Search, install, inspect, or manage skills from registries |
 | `/platforms` | Show gateway/messaging platform status |
+| `/verbose` | Cycle tool progress display: off → new → all → verbose |
+| `/compress` | Manually compress conversation context |
+| `/usage` | Show token usage for this session |
 | `/quit` | Exit (also: `/exit`, `/q`) |
 | `/<skill-name>` | Invoke any installed skill (e.g., `/axolotl`, `/gif-search`) |
 
@@ -1315,9 +1320,13 @@ Your `~/.hermes/` directory should now look like:
 ├── skills/         # Agent-created skills (auto-created on first use)
 ├── cron/           # Scheduled job data
 ├── sessions/       # Messaging gateway sessions
-└── logs/           # Conversation logs
+└── logs/           # Logs
+    ├── gateway.log     # Gateway activity log
+    └── errors.log      # Errors from tool calls, API failures, etc.
 ```
 
+All log output is automatically redacted -- API keys, tokens, and credentials are masked before they reach disk.
+
 ---
 
 ### Step 7: Add Your API Keys
@@ -1642,6 +1651,8 @@ All variables go in `~/.hermes/.env`. Run `hermes config set VAR value` to set t
 | `~/.hermes/config.yaml` | Your settings |
 | `~/.hermes/.env` | API keys and secrets |
 | `~/.hermes/auth.json` | OAuth provider credentials (managed by `hermes model`) |
+| `~/.hermes/logs/errors.log` | Tool errors, API failures (secrets auto-redacted) |
+| `~/.hermes/logs/gateway.log` | Gateway activity log (secrets auto-redacted) |
 | `~/.hermes/cron/` | Scheduled jobs data |
 | `~/.hermes/sessions/` | Gateway session data |
 | `~/.hermes/hermes-agent/` | Installation directory |
diff --git a/docs/cli.md b/docs/cli.md
index 6c1abc399..0945b48a1 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -73,6 +73,9 @@ The CLI is implemented in `cli.py` and uses:
 | `/history` | Show conversation history |
 | `/save` | Save current conversation to file |
 | `/config` | Show current configuration |
+| `/verbose` | Cycle tool progress display: off → new → all → verbose |
+| `/compress` | Manually compress conversation context (flush memories + summarize) |
+| `/usage` | Show token usage for the current session |
 | `/quit` | Exit the CLI (also: `/exit`, `/q`) |
 
 ## Configuration
diff --git a/docs/messaging.md b/docs/messaging.md
index 9963cfe03..e695308b4 100644
--- a/docs/messaging.md
+++ b/docs/messaging.md
@@ -74,6 +74,13 @@ Sessions reset based on configurable policies:
 
 Send `/new` or `/reset` as a message to start fresh.
 
+### Context Management
+
+| Command | Description |
+|---------|-------------|
+| `/compress` | Manually compress conversation context (saves memories, then summarizes) |
+| `/usage` | Show token usage and context window status for the current session |
+
 ### Per-Platform Overrides
 
 Configure different reset policies per platform: