diff --git a/CLAUDE.md b/CLAUDE.md
index 99c2b7f..b583997 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,4 +4,40 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Overview
 
-This is a new, empty project. Update this file as the codebase takes shape.
+Telegram Channel Analyzer Bot — fetches public channel history via Telethon, analyzes with Claude AI (chunked summarization pipeline), delivers reports via aiogram bot.
+
+## Stack
+
+- **Python 3.12**, async throughout
+- **aiogram 3** — Telegram bot interface (commands, inline keyboards, progress messages)
+- **Telethon** — userbot client for reading public channel history
+- **anthropic** (AsyncAnthropic) — Claude API with streaming
+- **pydantic-settings** — config from environment variables
+
+## Architecture
+
+- Both aiogram and Telethon share one asyncio loop (no threads)
+- Telethon client is attached to the bot instance in `__main__.py`
+- Analysis pipeline: Fetch → Chunk (token-bounded) → Summarize each chunk → Synthesize final report
+- Rate limit handling: semaphore(1), 60s cooldown between chunks, retry with backoff on 429
+- Output: Markdown→HTML conversion, split on section boundaries at 4000 chars
+
+## Key Files
+
+- `bot/config.py` — all settings from env vars, `CLAUDE_MODEL` selects the model
+- `bot/services/analyzer.py` — Claude API calls, adaptive thinking only for opus-4-6
+- `bot/services/chunker.py` — `MAX_TOKENS_PER_CHUNK` and `CHARS_PER_TOKEN` control chunking
+- `bot/prompts/` — prompt templates per report type (chunk_summary.py, synthesis.py)
+
+## Running
+
+- Container-based: `Containerfile` + `compose.yml`
+- `--login` flag for interactive Telethon session creation
+- Session persists in `data/` volume
+- `.env` file must not have inline comments (Podman/Docker limitation)
+
+## Common Tasks
+
+- To change chunk size: edit `MAX_TOKENS_PER_CHUNK` in `bot/services/chunker.py`
+- To add a report type: add to `ReportType` enum, add prompts in both `prompts/` files
+- To change model: set `CLAUDE_MODEL` env var; thinking params auto-adapt in `analyzer.py`
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b284020
--- /dev/null
+++ b/README.md
@@ -0,0 +1,104 @@
+# Telegram Channel Analyzer Bot
+
+Telegram bot that analyzes public channels using Claude AI. Fetches channel history via Telethon, chunks messages, summarizes with Claude, and delivers a report back in Telegram.
+
+## Report Types
+
+- **Content Analysis** — topics, tone, themes, content strategy
+- **Content + Stats** — above + posting frequency, engagement patterns
+- **Full Audit** — all above + sentiment, audience insights, recommendations
+
+## Prerequisites
+
+- Telegram Bot token from [@BotFather](https://t.me/BotFather)
+- Telegram API credentials from [my.telegram.org](https://my.telegram.org)
+- Anthropic API key from [console.anthropic.com](https://console.anthropic.com)
+- Docker or Podman
+
+## Setup
+
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+`.env` values (no inline comments):
+```
+BOT_TOKEN=123456:ABC...
+TELEGRAM_API_ID=12345678
+TELEGRAM_API_HASH=abc123def456...
+TELEGRAM_PHONE=+1234567890
+ANTHROPIC_API_KEY=sk-ant-...
+CLAUDE_MODEL=claude-haiku-4-5
+```
+
+Available models: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`
+
+## Run with Docker
+
+```bash
+# Build
+docker build -f Containerfile -t tg-analyzer .
+
+# First run: interactive login to create Telethon session
+docker run -it --env-file .env -v ./data:/app/data tg-analyzer python -m bot --login
+
+# Run the bot
+docker run -d --env-file .env -v ./data:/app/data --name tg-analyzer --restart unless-stopped tg-analyzer
+```
+
+## Run with Podman
+
+```bash
+# Build
+podman build -t tg-analyzer .
+
+# First run: interactive login
+podman run -it --env-file .env -v ./data:/app/data tg-analyzer python -m bot --login
+
+# Run the bot
+podman run -d --env-file .env -v ./data:/app/data --name tg-analyzer tg-analyzer
+```
+
+## Run with Compose
+
+```bash
+# Login first (see above), then:
+podman compose up -d
+# or
+docker compose up -d
+```
+
+## Usage
+
+Send to your bot in Telegram:
+
+```
+/analyze @channel_username
+```
+
+Select a report type from the inline keyboard. The bot will show progress as it fetches and analyzes.
+
+## Project Structure
+
+```
+bot/
+├── __main__.py          # Entrypoint: aiogram + Telethon on shared loop
+├── config.py            # pydantic-settings from env vars
+├── models.py            # ReportType enum, ChannelMessage dataclass
+├── handlers/
+│   ├── start.py         # /start, /help
+│   └── analyze.py       # /analyze + report type selection + progress
+├── services/
+│   ├── fetcher.py       # Telethon: read channel history
+│   ├── chunker.py       # Token-bounded message chunking
+│   ├── analyzer.py      # Claude API: chunk summaries → synthesis
+│   └── formatter.py     # Split report into Telegram-safe HTML messages
+└── prompts/
+    ├── chunk_summary.py # Per-chunk extraction prompts
+    └── synthesis.py     # Final synthesis prompts
+```
+
+## Rate Limits
+
+The bot respects Anthropic API rate limits with automatic retry and cooldown between chunks. On the free/low tier (30K input tokens/min), a large channel may take several minutes.