diff --git a/README.md b/README.md
index e69de29..1d35ab5 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,131 @@
+# greek_lang
+
+Проект для изучения греческого языка: перевод слов между языками (греческий, русский, английский) с помощью OpenAI, сохранение в базе данных (PostgreSQL) вместе с транскрипцией, описанием, примерами, категорией и аудио‑произношением (генерация через Google TTS). Также включает телеграм‑бота (aiogram) с хранением состояния в Redis.
+
+## Возможности
+- Перевод слова между языками ru/en/el (ISO‑639‑1) через OpenAI.
+- Автогенерация и сохранение:
+  - леммы, транскрипции (IPA), перевода, описания;
+  - части речи, семантической категории, примера и его перевода;
+  - краткой этимологии;
+  - аудио‑файла произношения (aiogTTS).
+- Сохранение результатов в PostgreSQL (SQLAlchemy + Alembic миграции).
+- Телеграм‑бот на aiogram с Redis FSM‑хранилищем.
+- Конфигурация через .env и pydantic‑settings; инициализация зависимостей через dependency_injector.
+
+## Требования
+- Python 3.13+
+- PostgreSQL 14+
+- Redis 6+
+- OpenAI API ключ
+
+Рекомендуется менеджер зависимостей uv и утилита go-task (для Taskfile.yml).
+
+## Установка
+1. Клонируйте репозиторий:
+   git clone <repo-url>
+   cd greek_lang
+
+2. Установите зависимости (через uv):
+   - Обновить/синхронизировать зависимости: uv sync
+   - Обновить lockfile: uv lock --upgrade && uv sync
+
+3. Создайте файл .env в корне проекта (см. пример ниже).
+
+## Настройка окружения (.env)
+Значения по умолчанию указаны в скобках. Переменные без значения обязательны к заполнению.
+
+# OpenAI
+API_KEY=sk-...
+
+# Telegram Bot
+TG_TOKEN=123456:ABC...
+
+# Логи (опционально: отправка ошибок в Telegram)
+LOG_TELEGRAM_BOT_TOKEN=123456:DEF...   # опционально
+LOG_TELEGRAM_CHAT_ID=123456789         # опционально
+
+# PostgreSQL
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_NAME=greek_lang
+DB_USER=greek_lang
+DB_PASSWORD=greek_lang
+DB_POOL_SIZE=20
+DB_POOL_MAX_OVERFLOW=5
+DB_CONNECT_WAIT_TIMEOUT_SECONDS=5
+DB_DEBUG=false
+
+# Redis
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_USERNAME=
+REDIS_PASSWORD=
+REDIS_POOL_SIZE=100
+
+Примечания:
+- Переменные считываются классами конфигурации из src/greek_lang/configs/*.py.
+- Для Alembic миграций можно переопределить URL через переменную окружения ALEMBIC_DB_URL. Если не задано, Alembic сам соберёт URL из .env.
+
+## Инициализация базы и миграции
+Alembic уже сконфигурирован (см. src/greek_lang/database/migrations/ и alembic.ini).
+
+- Применить миграции к последней версии:
+  alembic -c src/greek_lang/database/alembic.ini upgrade head
+
+- Откатить на один шаг:
+  alembic -c src/greek_lang/database/alembic.ini downgrade -1
+
+- Использовать конкретный URL БД (в обход .env):
+  ALEMBIC_DB_URL="postgresql://user:pass@host:5432/dbname" \
+  alembic -c src/greek_lang/database/alembic.ini upgrade head
+
+## Использование
+### CLI переводчик
+Пример запуска CLI для перевода одного слова:
+
+python -m cli.translate "έμπορος" -s el -t ru
+
+- -s/--source: исходный язык (ru|en|el), по умолчанию el
+- -t/--target: язык перевода (ru|en|el), по умолчанию ru
+
+При запуске создаются контейнеры зависимостей, выполняется запрос к OpenAI, генерируется аудио‑произношение и всё сохраняется в таблицу glossary_word.
+
+### Телеграм‑бот
+Убедитесь, что Redis и .env настроены. Затем запустите бота:
+
+python -m greek_lang.tg_bot
+
+Бот удалит вебхук и начнёт polling. Команда /start ответит тестовым сообщением (заглушка). В коде предусмотрена интеграция Redis FSM‑хранилища и готовность к добавлению диалогов (aiogram-dialog).
+
+## Архитектура (кратко)
+- Контейнеры зависимостей: src/greek_lang/container.py и под‑контейнеры для конфигов, БД, OpenAI, Redis.
+- Конфигурация: pydantic‑settings, .env читается из корня проекта (src/greek_lang/configs/__init__.py).
+- Перевод: src/greek_lang/translator.py — orchestration: OpenAI → TTS → вставка/обновление в БД (UPSERT по term).
+- OpenAI: src/greek_lang/openai_manager — типизированный парсинг ответа через client.beta.chat.completions.parse в модель WordInfo.
+- БД: SQLAlchemy 2.0, Alembic миграции; сущности в glossaries/models.py и openai_manager/models.py.
+- Аудио: aiogTTS, генерация в BytesIO, хранение в столбце LargeBinary.
+- Логи: JSON‑логгер, опциональная отправка ошибок в Telegram.
+
+## Разработка
+- Линт/типы через go-task (см. Taskfile.yml):
+  - Запуск проверок: task check
+  - Только mypy: task mypy
+  - Ruff lint/format: task ruff-check / task ruff-fix / task ruff-format
+  - Обновить зависимости: task deps-update
+  - Очистить кэши: task clean
+
+- Установка dev‑зависимостей (uv):
+  uv sync --group dev
+
+Примечание: В pyproject.toml определён entry point [project.scripts], но пока не реализована функция greek_lang:main. Используйте вызовы модулей через python -m как указано выше.
+
+## Частые проблемы
+- Нет доступа к OpenAI: проверьте переменную API_KEY и сетевые ограничения.
+- Ошибка подключения к Postgres: проверьте DB_HOST/DB_PORT/DB_USER/DB_PASSWORD и что БД создана.
+- Alembic не видит URL: либо задайте ALEMBIC_DB_URL, либо убедитесь, что .env заполнен корректно.
+- Redis недоступен: проверьте REDIS_* переменные и доступность сервиса.
+
+## Лицензия
+Не указана. При необходимости добавьте раздел с выбранной лицензией.