Update docs for token savings counter (v0.2.4)

Documents _meta.tokens_saved and _meta.total_tokens_saved fields,
token_tracker.py in architecture file tree, and the live counter
feature in TOKEN_SAVINGS.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jgravelle

ARCHITECTURE.md

@@ -25,7 +25,8 @@ jcodemunch-mcp/
 │   │
 │   ├── storage/
 │   │   ├── __init__.py
-│   │   └── index_store.py           # CodeIndex, IndexStore: save/load, incremental indexing
+│   │   ├── index_store.py           # CodeIndex, IndexStore: save/load, incremental indexing
+│   │   └── token_tracker.py         # Persistent token savings counter (~/.code-index/_savings.json)
 │   │
 │   ├── summarizer/
 │   │   ├── __init__.py
@@ -175,11 +176,15 @@ All tool responses include metadata:
     "timing_ms": 42,
     "repo": "owner/repo",
     "symbol_count": 387,
-    "truncated": false
+    "truncated": false,
+    "tokens_saved": 2450,
+    "total_tokens_saved": 184320
   }
 }
 ```
 
+`tokens_saved` and `total_tokens_saved` are included on all retrieval and search tools. The running total is persisted to `~/.code-index/_savings.json` across sessions.
+
 ---
 
 ## Search Algorithm

SPEC.md

@@ -224,7 +224,7 @@ Recursive directory walk with the full security pipeline.
 
 ## Response Envelope
 
-All tools return a `_meta` object with timing and context:
+All tools return a `_meta` object with timing, context, and token savings:
 
 ```json
 {
@@ -233,11 +233,18 @@ All tools return a `_meta` object with timing and context:
     "repo": "owner/repo",
     "symbol_count": 387,
     "truncated": false,
-    "content_verified": true
+    "content_verified": true,
+    "tokens_saved": 2450,
+    "total_tokens_saved": 184320
   }
 }
 ```
 
+- **`tokens_saved`**: Tokens saved by this specific call (raw file bytes vs response bytes, divided by 4)
+- **`total_tokens_saved`**: Cumulative tokens saved across all tool calls, persisted to `~/.code-index/_savings.json`
+
+Present on: `get_file_outline`, `get_symbol`, `get_symbols`, `get_repo_outline`, `search_symbols`.
+
 ---
 
 ## Error Handling

TOKEN_SAVINGS.md

@@ -46,8 +46,26 @@ jCodeMunch indexes a repository once and allows agents to retrieve **exact symbo
 
 jCodeMunch shifts the workflow from:
 
-**“Read everything to find something”**
+**”Read everything to find something”**
 to
-**“Find something, then read only that.”**
+**”Find something, then read only that.”**
+
+---
+
+## Live Token Savings Counter
+
+Every tool response includes real-time savings data in the `_meta` field:
+
+```json
+“_meta”: {
+  “tokens_saved”: 2450,
+  “total_tokens_saved”: 184320
+}
+```
+
+- **`tokens_saved`**: Tokens saved by the current call (raw file bytes vs response bytes ÷ 4)
+- **`total_tokens_saved`**: Cumulative total across all calls, persisted to `~/.code-index/_savings.json`
+
+No extra API calls or file reads — computed using fast `os.stat` only.
 
 ---