diff --git a/README.md b/README.md
index e7de074..8870f26 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,111 @@
 # PriceForge
 
+PriceForge — администратор цен и прайслистов для работы с данными MariaDB.
+
+Текущее состояние проекта:
+- Runtime: **MariaDB-only**
+- Режим запуска: **fail-fast** (если БД недоступна на старте, сервер завершается)
+- Основной интерфейс: `/admin/pricing`
+- Порт по умолчанию: `8084`
+
+## Возможности
+- Администрирование цен компонентов
+- Управление прайслистами (Estimate / Склад / Конкуренты)
+- Импорт складских данных
+- Алерты по ценам и свежести данных
+- Диагностика подключения к БД в UI (online/offline индикатор)
+
+## Требования
+- Go 1.22+
+- MariaDB / MySQL с доступом к рабочей базе (например `RFQ_LOG`)
+
+## Быстрый старт
+
+1. Подготовить конфиг:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+2. Проверить параметры в `config.yaml`:
+- `server.port` (по умолчанию `8084`)
+- `database.host`
+- `database.port`
+- `database.name`
+- `database.user`
+- `database.password`
+
+3. Запустить сервер:
+
+```bash
+make run
+```
+
+или
+
+```bash
+go run ./cmd/pfs
+```
+
+4. Открыть:
+- [http://127.0.0.1:8084/admin/pricing](http://127.0.0.1:8084/admin/pricing)
+
+## Миграции
+
+Запуск миграций:
+
+```bash
+go run ./cmd/pfs -migrate
+```
+
+При обычном запуске SQL-миграции из `migrations/` также проверяются автоматически.
+
+## Сборка
+
+```bash
+make build
+make build-release
+make build-all
+```
+
+Проверка версии:
+
+```bash
+./bin/pfs -version
+```
+
+## Release-артефакты
+
+Скрипт сборки релиза:
+
+```bash
+./scripts/release.sh
+```
+
+Он создает архивы в `releases/<version>/` и файл `SHA256SUMS.txt`.
+
+## Запуск на macOS
+
+После скачивания бинарника может сработать Gatekeeper. Выполните:
+
+```bash
+xattr -d com.apple.quarantine /path/to/pfs-darwin-arm64
+```
+
+После этого бинарник запустится без предупреждения Gatekeeper.
+
+## Основные команды Makefile
+
+```bash
+make run           # запуск dev-сервера
+make build         # локальная сборка
+make build-release # релизная сборка
+make build-all     # кросс-компиляция для Linux/macOS/Windows
+make test          # тесты
+make clean         # очистка артефактов
+```
+
+## Важно
+
+Проект сейчас не использует SQLite в runtime-потоке сервера `pfs`.
+Все ключевые операции выполняются напрямую через MariaDB.