Add token counting utilities and update documentation

Features:
- Add benchmark dependency group with tiktoken>=0.4.0 to pyproject.toml
- Export count_tokens, estimate_savings, and compare_formats utilities
- Implement token counting using tiktoken with o200k_base encoding (gpt5/gpt5-mini)

Documentation Updates:
- Add Token Counting & Comparison section to main README with examples
- Update docs/README.md with new utility functions in API reference list
- Add roadmap section announcing planned comprehensive benchmarks
- Add complete Utility Functions section to docs/api.md covering:
  * count_tokens() - Token counting with tiktoken
  * estimate_savings() - JSON vs TOON comparison metrics
  * compare_formats() - Formatted comparison tables
- Add Token Efficiency examples with cost estimation patterns
- Update LLM integration guide with Measuring Token Savings section
- Include cost calculation examples and integration patterns
- Update model references from GPT-4 to gpt5 throughout docs
- Add benchmark disclaimer noting comprehensive benchmarks coming soon

Technical Details:
- Update tokenizer documentation from GPT-4o/GPT-4 to gpt5/gpt5-mini
- Fix TypedDict usage examples in docs/api.md (EncodeOptions uses dict syntax)
- Clarify DecodeOptions is a class while EncodeOptions is a TypedDict
- Add toon-spec/ submodule files (CHANGELOG.md and SPEC.md v1.3)

Author: Justar96

README.md

@@ -10,9 +10,10 @@ Compact, human-readable serialization format for LLM contexts with **30-60% toke
 
 ```bash
 pip install toon_format
+# or (recommended)
+uv add toon_format
 ```
 
-
 ## Quick Start
 
 ```python
@@ -72,6 +73,34 @@ decode("id: 123", {"indent": 2, "strict": True})
 - `indent`: Expected indent size (default: `2`)
 - `strict`: Validate syntax, lengths, delimiters (default: `True`)
 
+### Token Counting & Comparison
+
+Measure token efficiency and compare formats:
+
+```python
+from toon_format import estimate_savings, compare_formats, count_tokens
+
+# Measure savings
+data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+result = estimate_savings(data)
+print(f"Saves {result['savings_percent']:.1f}% tokens")  # Saves 42.3% tokens
+
+# Visual comparison
+print(compare_formats(data))
+# Format Comparison
+# ────────────────────────────────────────────────
+# Format      Tokens    Size (chars)
+# JSON            45             123
+# TOON            28              85
+# ────────────────────────────────────────────────
+# Savings: 17 tokens (37.8%)
+
+# Count tokens directly
+toon_str = encode(data)
+tokens = count_tokens(toon_str)  # Uses tiktoken (gpt5/gpt5-mini)
+```
+
+**Requires tiktoken:** `pip install tiktoken` or `pip install toon-format[benchmark]`
 
 ## Format Specification
 

docs/README.md

@@ -24,6 +24,9 @@ New to TOON? Start here:
 Complete reference for all public functions and classes:
 - `encode()` - Convert Python to TOON
 - `decode()` - Convert TOON to Python
+- `count_tokens()` - Count tokens in text using tiktoken
+- `estimate_savings()` - Compare JSON vs TOON token counts
+- `compare_formats()` - Generate formatted comparison table
 - `EncodeOptions` - Encoding configuration
 - `DecodeOptions` - Decoding configuration
 - `ToonDecodeError` - Error handling
@@ -53,6 +56,15 @@ Best practices for LLM usage:
 - Performance metrics
 - Debugging tips
 
+## Roadmap
+
+The following features are planned for future releases:
+
+- **Comprehensive Benchmarks**: Detailed token efficiency comparisons across various data structures and LLM models (gpt5, gpt5-mini, Claude)
+- **Official Documentation Site**: Dedicated documentation website with interactive examples and tutorials
+
+Stay tuned for updates!
+
 ## External Resources
 
 - [Official TOON Specification](https://github.com/toon-format/spec) - Normative spec
@@ -95,6 +107,28 @@ decode("items[5]: a,b,c", {"strict": False})
 # {'items': ['a', 'b', 'c']}  # Accepts length mismatch
 ```
 
+### Token Efficiency
+
+```python
+from toon_format import estimate_savings, compare_formats
+
+data = {"employees": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+
+# Get savings metrics
+result = estimate_savings(data)
+print(f"Saves {result['savings_percent']:.1f}% tokens")
+
+# Get formatted comparison
+print(compare_formats(data))
+# Format Comparison
+# ────────────────────────────────────────────────
+# Format      Tokens    Size (chars)
+# JSON            45             123
+# TOON            28              85
+# ────────────────────────────────────────────────
+# Savings: 17 tokens (37.8%)
+```
+
 ## Support
 
 - **Bug Reports:** [GitHub Issues](https://github.com/toon-format/toon-python/issues)