docs: Update for human-readable tool summaries and LLM fallback

- README: Add summarizer feature, summarizer.rs module, LLM config
  options (llm_summarize_url, llm_api_key), fix config example to
  show snake_case (both formats accepted)
- ARCHITECTURE: Add summarizer.rs to module dependency graph, update
  tool start flow to show summarization step
- DEVELOPMENT: Add summarizer.rs to project structure, update test
  counts (21 total, 11 in formatting), add summarizer deep dive
  section with examples and LLM fallback docs, add reqwest dependency

Co-Authored-By: DreamLabAI <github@thedreamlab.uk>

Author: John O'Hare

README.md

@@ -39,6 +39,7 @@ claude
 
 - **CLI to Telegram**: Mirror Claude's responses, tool usage, and notifications
 - **Telegram to CLI**: Send prompts from Telegram directly to Claude Code
+- **Human-Readable Summaries**: Tool actions shown as natural language ("Running tests", "Editing config.rs") instead of raw operations, with optional LLM fallback for unknown tools
 - **Stop/Interrupt**: Type `stop` in Telegram to send Escape and halt Claude mid-process
 - **Kill**: Type `kill` to send Ctrl-C and exit Claude entirely
 - **Session Threading**: Each Claude session gets its own Forum Topic
@@ -130,7 +131,8 @@ When Claude requests tool permission, you'll see inline keyboard buttons:
 | `hook.rs` | Claude Code hook event processing |
 | `injector.rs` | tmux command injection (Command::arg, no shell) |
 | `config.rs` | Configuration: env > file > defaults, secure perms |
-| `formatting.rs` | Message formatting, ANSI stripping, chunking |
+| `formatting.rs` | Message formatting, ANSI stripping, tool summaries |
+| `summarizer.rs` | LLM-backed fallback summarizer (optional, for unknown tools) |
 | `types.rs` | Shared types: BridgeMessage, HookEvent, Session |
 | `error.rs` | Error types via thiserror |
 
@@ -198,6 +200,8 @@ export TELEGRAM_MIRROR=true
 # export TELEGRAM_AUTO_DELETE_TOPICS=true   # Delete topics on session end
 # export TELEGRAM_TOPIC_DELETE_DELAY=5      # Minutes before topic deletion
 # export TELEGRAM_BRIDGE_SOCKET=~/.config/claude-telegram-mirror/bridge.sock
+# export CTM_LLM_SUMMARIZE_URL=https://api.anthropic.com/v1/messages
+# export CTM_LLM_API_KEY=sk-ant-...        # For LLM-powered tool summaries
 ```
 
 ### Config File (Alternative)
@@ -206,15 +210,19 @@ export TELEGRAM_MIRROR=true
 
 ```json
 {
-  "botToken": "your-token",
-  "chatId": -1001234567890,
+  "bot_token": "your-token",
+  "chat_id": -1001234567890,
   "enabled": true,
   "verbose": true,
-  "useThreads": true,
-  "autoDeleteTopics": false
+  "use_threads": true,
+  "auto_delete_topics": false,
+  "llm_summarize_url": "https://api.anthropic.com/v1/messages",
+  "llm_api_key": "sk-ant-..."
 }
 ```
 
+Both `snake_case` and `camelCase` field names are accepted.
+
 Environment variables take precedence over config file values.
 
 ### Claude Code Hook Installation

docs/ARCHITECTURE.md

@@ -63,6 +63,9 @@ graph LR
     BRIDGE --> INJ
     BRIDGE --> CONFIG
     BRIDGE --> FMT[formatting.rs]
+    BRIDGE --> SUMM[summarizer.rs]
+
+    SUMM --> FMT
 
     HOOK --> TYPES[types.rs]
     HOOK --> INJ
@@ -113,7 +116,8 @@ sequenceDiagram
     else AgentResponse
         Bridge->>Bot: Send formatted response
     else ToolStart
-        Bridge->>Bot: Send tool preview + Details button
+        Bridge->>Bridge: Summarize tool action
+        Bridge->>Bot: Send human-readable summary + Details button
     else TurnComplete
         Bridge->>Bridge: Check compaction state
     end

docs/DEVELOPMENT.md

@@ -15,7 +15,8 @@
 │   ├── hook.rs             # Claude Code hook processor
 │   ├── injector.rs         # tmux command injection
 │   ├── config.rs           # Configuration loading
-│   ├── formatting.rs       # Message formatting
+│   ├── formatting.rs       # Message formatting + tool summaries
+│   ├── summarizer.rs       # LLM-backed fallback summarizer
 │   ├── types.rs            # Shared type definitions
 │   └── error.rs            # Error types
 ├── scripts/
@@ -68,9 +69,9 @@ cargo test session::tests
 |--------|-------|---------------|
 | `session.rs` | 3 | CRUD, lifecycle, approvals |
 | `socket.rs` | 2 | Server lifecycle, flock double-start prevention |
-| `formatting.rs` | 3 | ANSI stripping, truncation, path shortening |
-| `injector.rs` | 1 | Key whitelist validation |
-| `config.rs` | 2 | Environment loading, validation |
+| `formatting.rs` | 11 | ANSI stripping, truncation, path shortening, tool action summaries (bash/cargo/git, file ops, search, task, unknown), tool result summaries (success, error) |
+| `injector.rs` | 2 | Key whitelist validation, no-target safety |
+| `config.rs` | 2 | Environment loading, config file defaults |
 
 ## Code Quality
 
@@ -98,6 +99,7 @@ graph TB
         RUSQLITE[rusqlite<br/>SQLite bindings]
         GOVERNOR[governor<br/>rate limiting]
         NIX[nix<br/>Unix operations]
+        REQWEST[reqwest<br/>HTTP client for LLM]
     end
 
     subgraph "Serialization"
@@ -170,6 +172,33 @@ Key patterns:
 - Session lookup is cached in-memory with DB fallback
 - Tool input cache auto-expires after 5 minutes
 - Topic deletion is delayed and cancellable
+- Tool actions are summarized in natural language via `summarizer.rs` (rule-based, with optional LLM fallback)
+
+### summarizer.rs - Human-Readable Tool Summaries
+
+The summarizer converts raw tool operations into natural language:
+
+| Tool Action | Summary |
+|------------|---------|
+| `Bash: cargo test` | "Running tests" |
+| `Bash: git push` | "Pushing to remote" |
+| `Edit: /path/to/config.rs` | "Editing config.rs" |
+| `Grep: pattern "auth"` | "Searching for 'auth'" |
+| `Task: {desc: "Explore auth"}` | "Delegating: Explore auth" |
+| `Unknown: CustomTool` | "Using CustomTool" (LLM fallback if configured) |
+
+Two-tier architecture:
+1. **Rule-based** (zero latency): Covers cargo, git, npm, docker, pip, file ops, search, and 15+ system commands
+2. **LLM fallback** (optional): When the rule-based summary is generic ("Using X"), calls a configurable LLM endpoint (Anthropic API or Z.AI proxy) for a better summary. Results are cached (200 entries, 5s timeout)
+
+Configuration:
+```json
+{
+  "llm_summarize_url": "https://api.anthropic.com/v1/messages",
+  "llm_api_key": "sk-ant-..."
+}
+```
+Or via environment: `CTM_LLM_SUMMARIZE_URL`, `CTM_LLM_API_KEY`
 
 ### injector.rs - Shell-Safe Command Execution