diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1f6722f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,121 @@
+# DEMO Shop
+
+Простой учебный проект: магазин с товарами, складами и заказами.
+Сайт + серверная часть (API) в одном проекте.
+
+Рабочий сайт: https://demo.triron.ru
+
+## Что умеет
+
+- Вход и регистрация. Новому человеку дается роль Client.
+- 6 разделов: Товары, Категории, Склады, Остатки, Пользователи, Заказы.
+- Везде можно добавлять, изменять и удалять записи.
+- В заказе можно смотреть товары и добавлять новые.
+- Внизу экрана всплывают короткие сообщения (что сохранилось, где ошибка).
+
+## Что внутри
+
+```
+DEMO/
+  Controllers/      серверные адреса (API), по одному файлу на таблицу
+    AuthController.cs       вход и регистрация
+    ProductsController.cs   товары
+    CategoriesController.cs категории
+    WarehousesController.cs склады
+    StocksController.cs     остатки
+    UsersController.cs      пользователи
+    OrdersController.cs     заказы
+    OrderItemsController.cs товары внутри заказов
+    RolesController.cs      роли
+  Data/
+    AppDbContext.cs        список всех таблиц базы
+    AppDbContextFactory.cs подключение для миграций
+  Models/           классы таблиц: Product, Category, Warehouse,
+                    Stock, User, Role, Order, OrderItem
+  Migrations/       история создания базы (одна общая миграция)
+  wwwroot/          сайт, который видит человек
+    index.html      разметка: вход, меню, таблицы, окно формы
+    style.css       простые стили, светлый дизайн
+    script.js       весь код сайта с понятными комментариями
+  Program.cs        главный файл: запускает все и создает базу
+  appsettings.json  настройки, там строка подключения к базе
+```
+
+База данных: SQLite, файл `DemoDB.db`. Создается сам при первом запуске,
+ничего ставить не надо. При старте сами добавляются роли Admin и Client.
+
+## Как запустить у себя
+
+Нужен только .NET 10 SDK.
+
+```
+cd DEMO
+dotnet restore
+dotnet run
+```
+
+Открыть в браузере: `http://localhost:5000`
+(точный адрес покажет само окно запуска).
+
+База создастся сама. Дальше нажмите "Зарегистрироваться" на сайте.
+
+## Адреса API
+
+Все адреса начинаются одинаково, дальше свое для каждой таблицы.
+
+| Что сделать | Как вызвать | Что отдать |
+|---|---|---|
+| Войти | POST /api/auth/login | логин и пароль |
+| Зарегистрироваться | POST /api/auth/register | логин и пароль |
+| Список товаров | GET /api/products | ничего |
+| Добавить товар | POST /api/products | название, цена, categoryId |
+| Изменить товар | PUT /api/products/5 | то же самое (5 это номер) |
+| Удалить товар | DELETE /api/products/5 | ничего |
+
+Точно так же работают остальные таблицы, только адрес другой:
+
+- /api/categories (поле name)
+- /api/warehouses (поля name, address)
+- /api/stocks (поля productId, warehouseId, quantity)
+- /api/users (поля login, password, roleId)
+- /api/orders (поля userId, date, status)
+- /api/orderitems (поля orderId, productId, quantity, price)
+- /api/roles (поле name)
+
+Статусы заказа: New, Processing, Completed, Cancelled.
+
+## Как это стоит на сервере
+
+- Сервер: Ubuntu 24.04, стоит .NET 10 SDK.
+- Код лежит в /opt/demo (копия этого репозитория).
+- Собранный проект лежит в /opt/demo/publish.
+- Служба называется demo, смотрит на 127.0.0.1:5001.
+- Снаружи сайт отдает nginx через https://demo.triron.ru.
+- Сертификат от Let's Encrypt, продлевается сам.
+
+Проверить что служба жива:
+
+```
+systemctl status demo.service
+curl http://127.0.0.1:5001/api/roles
+```
+
+## Как обновить сайт на сервере
+
+```
+cd /opt/demo
+git pull origin master
+cd DEMO
+dotnet publish -c Release -o /opt/demo/publish
+systemctl restart demo.service
+```
+
+База при этом не теряется, миграции применяются сами.
+
+## Если что-то не работает
+
+1. Служба не запустилась: `journalctl -u demo.service -n 50` покажет ошибку.
+2. Сайт не открывается снаружи: `nginx -t` проверит настройки,
+   `systemctl reload nginx` перезагрузит их.
+3. Ошибка про базу: удалите файл DemoDB.db рядом с запуском
+   и перезапустите, база создастся заново (все данные пропадут).