diff --git a/README.md b/README.md
index b012670..07b2b6a 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,40 @@
-# brojs-task-69b1a07c67bbf488a1177da4
+# текстовая игра на основе llm + interrupt
 
-BroJS task solution: текстовая игра на основе llm + interrupt
\ No newline at end of file
+Минимальный пример AI-agent с потоковой выдачей ответа.
+
+## Что внутри
+
+- `stream_agent.py` - агент с синхронным и потоковым режимом.
+- `test_stream_agent.py` - быстрые проверки stream-логики без внешнего API.
+- `requirements.txt` - зависимости для запуска.
+
+## Установка
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Запуск
+
+Оффлайн-режим без ключей:
+
+```bash
+python stream_agent.py "Объясни, что такое stream режим"
+```
+
+С OpenAI-compatible API:
+
+```bash
+export OPENAI_API_KEY=your_key
+export OPENAI_BASE_URL=https://openrouter.ai/api/v1
+export OPENAI_MODEL=openai/gpt-oss-20b:free
+python stream_agent.py "Напиши короткий план проекта"
+```
+
+## Тесты
+
+```bash
+python -m pytest
+```