diff --git a/README.md b/README.md
index 969fbe0..c4ce76b 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,73 @@
-# claude_chat_to_md
+# claude-chat-to-md
 
-Конвертация сессий Claude Code в md-файлы
+Скрипт для конвертации сессий [Claude Code](https://docs.anthropic.com/en/docs/claude-code) в удобный и читаемый формат Markdown, включая диалоги с подагентами (subagents) и результаты вызова инструментов.
 
+Эта версия скрипта была специально адаптирована для вашего окружения:
+- **Поддержка Windows (UTF-8)**: исправлены ошибки чтения/записи файлов на Windows, приводившие к `UnicodeDecodeError`/`UnicodeEncodeError`.
+- **Локальные директории**: скрипт автоматически распознает, если запущен в папке с бэкапом (где лежат `projects` и `sessions`). В противном случае он ищет стандартную папку `~/.claude/projects/`.
 
-https://pypi.org/project/claude-chat-to-md/
\ No newline at end of file
+## Как использовать
+
+Для запуска нужен только Python 3.10+. Никаких сторонних библиотек не требуется.
+
+### Список сессий
+
+Посмотреть список всех доступных разговоров:
+```bash
+python claude_chat_to_md.py --list
+```
+
+### Конвертация одной сессии
+
+Можно использовать индекс (из `--list`), часть ID сессии (UUID) или часть названия:
+```bash
+# По номеру в списке
+python claude_chat_to_md.py 1 -o chat.md
+
+# По префиксу ID
+python claude_chat_to_md.py a1b2c3 -o chat.md
+
+# По куску названия
+python claude_chat_to_md.py "auth middleware" -o chat.md
+
+# Самая последняя сессия
+python claude_chat_to_md.py --latest -o chat.md
+```
+
+### Массовый экспорт
+
+Сконвертировать вообще все доступные разговоры и сохранить их в отдельную папку (например, `exports`):
+```bash
+python claude_chat_to_md.py --all --output-dir exports/
+```
+
+### Фильтры
+
+Можно фильтровать сессии по названию проекта:
+```bash
+python claude_chat_to_md.py --list --project myapp
+python claude_chat_to_md.py --latest --project myapp -o chat.md
+```
+
+## Полный список опций
+
+| Флаг | Описание |
+|---|---|
+| `--list`, `-l` | Вывести список сессий |
+| `--latest` | Выбрать самую последнюю сессию |
+| `--all` | Обработать все сессии |
+| `--project`, `-p` | Фильтр по названию проекта |
+| `--output`, `-o` | Файл для вывода (если не указан — выводит в консоль) |
+| `--output-dir`, `-d` | Папка для вывода (работает вместе с `--all`) |
+| `--no-subagents` | Не включать диалоги подагентов |
+| `--no-tool-results` | Не включать результаты вызова инструментов (оставить только суть) |
+
+## Что внутри Markdown-файла?
+
+- **Ваши запросы** → Секции `## User`
+- **Ответы модели** → Секции `## Assistant`
+- **Результаты инструментов (лог терминала/чтение файлов)** → Скрыты в сворачиваемых блоках `<details>`, чтобы не мешать чтению.
+- **Подагенты (Subagents)** → Вложенные разговоры скрыты под `<details>`.
+- Служебные теги (вроде `<ide_opened_file>`) вырезаны, чтобы текст выглядел аккуратно.
+
+https://pypi.org/project/claude-chat-to-md/