diff --git a/Makefile b/Makefile
index a06232b..d3626b8 100644
--- a/Makefile
+++ b/Makefile
@@ -8,9 +8,6 @@ up:
 	GIT_COMMIT=$$(git rev-parse --short HEAD) docker compose up --build -d --force-recreate
 	docker compose logs -f
 
-migrate:
-	docker exec -it tgex-backend-backend-1 .venv/bin/alembic upgrade head
-
 migrate-init:
 	export $$(cat .env | xargs) && aerich init-db
 
diff --git a/README.md b/README.md
index 6b7992a..17f542a 100644
--- a/README.md
+++ b/README.md
@@ -3,23 +3,43 @@
 ## Быстрый старт
 
 ```bash
-# Создать .env
-make env
+# Установить зависимости
+uv sync
 
-# Запустить
+# Скопировать примеры конфигов
+cp docker-compose.yml.example docker-compose.yml
+cp .env.example .env
+
+# Поднять Postgres и сервисы
 make up
 
-# Применить миграции
-make migrate
+# (первый запуск) проинициализировать базу и таблицы aerich
+make migrate-init
+
+# Применить актуальные миграции
+make migrate-up
 ```
 
 Открыть:
 - API: http://localhost:8000
-- Docs: http://localhost:8000/docs
+- Swagger: http://localhost:8000/docs
 
-## Команды
+## Полезные команды
 
-- `make test` - запустить тесты
-- `make up` - поднять приложение
-- `make migrate` - применить миграции БД
-- `make down` - остановить контейнеры
+```bash
+make up             # поднять приложение и Postgres
+make down           # остановить контейнеры
+make migrate-init   # однократная инициализация базы (aerich init-db)
+make migrate-up     # применить миграции (aerich upgrade)
+make migrate-create # сгенерировать новую миграцию (aerich migrate)
+make test           # pytest
+uv run ruff check . # линтер
+uv run mypy .       # типизация
+```
+
+## Архитектура
+
+- FastAPI + PostgreSQL + Tortoise ORM, aiogram 3.x для бота
+- Слои: `domain` (модели/правила), `usecase` (бизнес-логика), `adapter` (БД/бот/JWT), `controller` (HTTP + Telegram), `dto`
+- Все use case оборачиваются в `self.database.transaction()` и проверяют права через `domain.WorkspacePermissions`
+- Миграции и схема БД управляются aerich (`migrations/models`)