diff --git a/README.md b/README.md
index 4c18870..c1ce46f 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,8 @@
 <!-- badges: start -->
 ![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
-![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-d7ff64.svg)
+![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)
+![Linter: ruff](https://img.shields.io/badge/linter-ruff-d7ff64.svg)
 ![Security: ruff](https://img.shields.io/badge/security-ruff%20S-orange)
 <!-- badges: end -->
 
@@ -13,24 +14,29 @@ A Python CLI tool for analyzing logs using the GitHub Copilot SDK.
 
 - Accepts logs from a single file or a directory (combined analysis)
 - Supports plain text and JSON log formats
+- Accurate token counting via [tiktoken](https://github.com/openai/tiktoken) (cl100k_base / GPT-4 compatible), with a character-based fallback
+- Large logs chunked automatically to stay within the model's context window
 - Uses Copilot SDK for LLM-powered analysis
 
 ## Usage (MVP)
 
 ```sh
-python -m logpilot.cli analyze <path> [OPTIONS]
+python -m logpilot.cli [--version] analyze <path> [OPTIONS]
 ```
 
+### Global Options
+
+- `--version` : Show the current logpilot version and exit
+
 ### Arguments
 
 - `<path>`: Path to a log file or directory (any extension)
 
 ### Options
 
-- `--version` : Show the current logpilot version and exit
 - `--format [auto|json|text]` : Log format (default: auto)
 - `--output [text|json]` : Output type (default: text)
-- `--max-tokens <int>` : Max tokens per chunk (default: 2048)
+- `--max-tokens <int>` : Max tokens per chunk (default: 2048). Token counts are measured using tiktoken (cl100k_base encoding). Increase this value for larger context windows or decrease it to stay within tighter model limits.
 - `--out-file <path>` : Write output to file (default: stdout)
 - `--recursive` : Recurse into subdirectories (directory mode)
 - `--include <glob>` : Glob pattern(s) to include (repeatable)
@@ -77,8 +83,12 @@ python -m logpilot.cli analyze mylog.txt --model gpt-3.5-turbo
 ## Requirements
 
 - Python 3.9+
-- Typer
-- rich
+- [Typer](https://typer.tiangolo.com/) — CLI framework
+- [rich](https://github.com/Textualize/rich) — terminal output formatting
+- [tiktoken](https://github.com/openai/tiktoken) — accurate token counting (cl100k_base)
+- [tqdm](https://github.com/tqdm/tqdm) — progress bars
+- [orjson](https://github.com/ijl/orjson) — fast JSON parsing
+- [toml](https://github.com/uiri/toml) — TOML config parsing (Python < 3.11 fallback)
 - GitHub Copilot SDK
 
 ## Supported Platforms