diff --git a/README-dev.md b/README-dev.md
new file mode 100644
index 0000000..0150376
--- /dev/null
+++ b/README-dev.md
@@ -0,0 +1,39 @@
+# Разработчику — работа с репозиторием neon-bar86.ru
+
+Репозиторий: `git.merrow.dev/merrow/neon-bar86.ru` (Gitea).
+Стек: `site/` — сайт (Vite + nginx), `crm/` — CRM API (чистый Python; в проде PostgreSQL, в тестах SQLite).
+
+## Первый раз
+
+1. Сгенерируй SSH-ключ и добавь публичный ключ в Gitea: Настройки → **SSH / GPG ключи**.
+2. Склонируй:
+   ```bash
+   git clone ssh://git@git.merrow.dev:22022/merrow/neon-bar86.ru.git
+   ```
+3. Проверь локально, что тесты идут (Docker не нужен — тесты работают на SQLite):
+   ```bash
+   cd crm
+   py -m pytest tests -q        # Windows; на Linux/macOS: python3 -m pytest tests -q
+   ```
+   Ожидается `27 passed`. Каталог `crm/data/` создастся сам — он в `.gitignore`.
+
+## Работа над фичей
+
+```bash
+git switch main && git pull
+git switch -c feature/<краткое-имя>
+# ...код...
+cd crm && py -m pytest tests -q        # локальный прогон перед пушем
+git add -A && git commit -m "кратко: что сделано"
+git push -u origin feature/<имя>
+```
+
+- Пуш ветки запускает **тесты** в CI: репо → **Действия** (Actions) — смотри статус, красный = чини.
+- **Деплой на сайт делает девопс** — код попадает на прод только через `main`.
+
+## Правила
+
+- В `main` напрямую не пушим: через Pull Request («Запрос на слияние») или по согласованию с девопсом.
+- Секреты и данные не коммитим: `.env`, `crm/media/`, `crm/data/` — в `.gitignore`; `git add -f` для них запрещён.
+- Новая логика CRM — с тестом в `crm/tests/` (тесты крутят настоящий сервер на SQLite, см. соседние тесты как образец).
+- Помни: состав/цена заказа валидируются **только по каталогу CRM** — данным клиента на фронте верить нельзя.
diff --git a/README-devops.md b/README-devops.md
new file mode 100644
index 0000000..7169cb0
--- /dev/null
+++ b/README-devops.md
@@ -0,0 +1,67 @@
+# Девопсу — ревью и деплой neon-bar86.ru
+
+Прод: VPS `neon-bar86.ru`, каталог `/opt/apps/neon-bar86.ru`, контейнеры `neon-site` (8080) / `neon-crm` (47613) / `neon-db` (PostgreSQL).
+Наружу смотрит Caddy: `neon-bar86.ru` → 8080, `crm.neon-bar86.ru` → 47613.
+
+## Ревью фичи
+
+1. Разработчик пушит ветку `feature/*` — CI автоматически гоняет тесты (репо → **Действия**).
+2. Ревью: PR в Gitea (**Запросы на слияние**), либо локально:
+   ```bash
+   git fetch origin
+   git diff main origin/feature/<имя>
+   ```
+3. Слияние — через кнопку в PR, либо локально:
+   ```bash
+   git switch main && git pull
+   git merge --no-ff origin/feature/<имя>
+   git push
+   ```
+   **Пуш в `main` = автодеплой.**
+
+## Что делает пайплайн при пуше в main
+
+1. Тесты CRM (SQLite, изолированный каталог данных).
+2. На VPS по шагам:
+   - **pg_dump бэкап БД** → `backups/` (хранится 7 последних) — данные обратимы всегда;
+   - `git fetch` + `git reset --hard origin/main` — код с сервера = код в репо (`.env`, `crm/media`, `crm/data`, `backups` защищены `.gitignore` и не трогаются);
+   - pre-flight `docker compose config -q` — сломанный compose/env падает ДО троганья контейнеров;
+   - `docker compose up -d --build`;
+   - health-check `/api/healthz` через сайт — не поднялось, прогон красный.
+
+БД живёт в docker-томе `pgdata` — деплой кода её не касается ни при каком исходе.
+
+## Проверка после деплоя
+
+```bash
+curl -s https://neon-bar86.ru/api/healthz          # {"ok": true}
+# сайт и CRM открываются, логин в панель работает
+ssh neon@neon-bar86.ru "docker ps"                 # три контейнера Up (healthy)
+```
+
+## Ручной передеплой (без изменений кода)
+
+```bash
+git commit --allow-empty -m "redeploy" && git push
+```
+
+## Откат
+
+- **Код**: `git revert <sha> && git push` — пайплайн задеплоит старую версию.
+- **Данные** (дампы на VPS, `backups/`):
+  ```bash
+  gunzip -c backups/<файл>.sql.gz | docker exec -i neon-db psql -U $POSTGRES_USER -d $POSTGRES_DB
+  ```
+  ⚠ Перезаписывает базу — сначала диагностика и стоп, затем восстановление.
+
+## Диагностика на VPS
+
+```bash
+ssh neon@neon-bar86.ru
+docker ps                          # статусы контейнеров
+docker logs neon-crm --tail 30     # почему не поднялся CRM
+df -h /                            # диск ~82% — следить
+docker image prune -f              # чистка dangling-образов
+```
+
+Лог деплоев — репо → **Действия**; лог CRM/Caddy — на сервере. Секреты только в `.env` на VPS и в secrets репозитория (Действия не печатают их в лог).