diff --git a/docs/README.md b/docs/README.md
index 235249d..08e96eb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,6 +23,7 @@ Pipu Music — self-hosted музыкальный сервис (веб + Android
 | [testing.md](testing.md) | Стратегия тестирования |
 | [ci-cd.md](ci-cd.md) | Gitea Actions: проверки и релиз по тегу |
 | [install-guide.md](install-guide.md) | **Пошагово:** установка сервера на домен с HTTPS, подключение веба и Android |
+| [admin-guide.md](admin-guide.md) | **Администратору:** пользователи, хранилища, очередь, волна, обновления, бэкапы, диагностика |
 | [deployment.md](deployment.md) | Справочник по развёртыванию: сервисы, каталоги, переменные, бэкапы |
 | [conventions.md](conventions.md) | Соглашения по коду, git, версиям |
 | [roadmap.md](roadmap.md) | Этапы разработки и критерии готовности |
diff --git a/docs/admin-guide.md b/docs/admin-guide.md
new file mode 100644
index 0000000..6a8e667
--- /dev/null
+++ b/docs/admin-guide.md
@@ -0,0 +1,133 @@
+# Руководство администратора
+
+Повседневная работа с сервером после установки ([install-guide.md](install-guide.md)): пользователи, музыка,
+очередь на добавление, «Моя волна», обновления, бэкапы и диагностика. Все команды — из каталога
+`/opt/pipu-music/deploy`. Справочник по сервисам и переменным — [deployment.md](deployment.md).
+
+## 1. Первый вход
+
+1. Логин `admin`. Пароль — `BOOTSTRAP_ADMIN_PASSWORD` из `.env`, а если он не задан — сгенерированный, его
+   печатает лог один раз: `docker compose logs api | grep -i bootstrap`.
+2. Сервер сразу попросит сменить логин и пароль администратора (пароль ≥ 12 символов). До этого остальные
+   разделы недоступны.
+3. Подключите хранилище с музыкой (раздел 3) — после первого скана появятся библиотека, поиск и «Моя волна».
+
+## 2. Пользователи и роли
+
+«Администрирование → Пользователи».
+
+| Роль | Что может |
+|---|---|
+| Пользователь | Слушать, искать, собирать коллекцию, «Моя волна» |
+| Модератор | Плюс: заводить пользователей и сбрасывать им пароли, смотреть статус библиотеки, предлагать треки |
+| Администратор | Всё: хранилища, сканы, очередь на добавление, настройки сервера, роли, аудит |
+
+Полная матрица прав — [auth-and-roles.md](auth-and-roles.md#матрица-прав).
+
+- **Новый пользователь:** «Создать» → логин, имя, роль. Сервер выдаёт **временный пароль** — он показывается один
+  раз, передайте его человеку. При первом входе пароль придётся сменить.
+- **Забыл пароль:** «Сбросить пароль» — новый временный пароль, все сессии пользователя завершаются.
+- **Заблокировать** — вход запрещён, история и лайки сохраняются; **удалить** — безвозвратно вместе с историей.
+- Последнего администратора нельзя понизить, заблокировать или удалить.
+- **Аудит** («Администрирование → Аудит»): кто, когда и что сделал — создание пользователей, смена ролей, сбросы
+  паролей, изменения хранилищ и настроек, решения по очереди.
+
+## 3. Хранилища и библиотека
+
+«Администрирование → Хранилища».
+
+- **Папка на сервере** — каталог хоста из `LIBRARY_HOST` в `.env` (например, смонтированный диск `/mnt/music`);
+  в форме указывается путь внутри него. **NFS** — сервер и экспорт; монтирует `storage-agent`.
+- «Проверить» — доступ к хранилищу, число найденных аудиофайлов.
+- **Шаблоны путей** («Шаблоны»): как из пути файла получить исполнителя, альбом, год и номер трека, если в тегах
+  пусто. «Предпросмотр» показывает разбор реальных путей до сохранения. Что важнее — теги или путь, задаётся
+  в карточке хранилища (по умолчанию теги).
+- **Скан:** обычный — только новые и изменённые файлы (по расписанию — интервал в карточке хранилища — и после
+  изменения настроек), «Полный» — перечитать всё. Удалённые с диска файлы помечаются отсутствующими, а не стираются из истории.
+- «Администрирование → Библиотека» — счётчики, прогресс скана и аудиоанализа, файлы с ошибками чтения
+  (битые файлы, неизвестные форматы) и «Переиндексировать поиск» — если поиск выдаёт устаревшее (обычно не нужно:
+  индекс обновляется сам и пересобирается при старте api).
+- **Аудиоанализ** (темп, энергия, настроение — для «Моей волны») идёт в фоне: на 10 тыс. треков — несколько часов
+  при 4 ядрах (`analyzer` в `compose.yaml`, `--workers`). Волна работает и до его окончания, но точнее — после.
+
+## 4. Очередь на добавление
+
+Модераторы и администраторы предлагают треки («Предложить треки»), администратор решает, что попадёт
+в библиотеку. Подробно — [uploads.md](uploads.md).
+
+- **Куда пишутся файлы:** у хранилища включите «Принимать загрузки» и задайте **шаблон раскладки** — «Подобрать»
+  предложит шаблон по уже лежащим файлам, «Проверить» убедится, что из пути, построенного шаблоном, сканер
+  получит те же исполнителя, альбом и номер трека. Хранилище по умолчанию — в «Настройках сервера».
+- **Рассмотрение** («Очередь на добавление»): прослушать, поправить метаданные (в том числе сразу для всего
+  альбома), одобрить или отклонить с причиной — автор её увидит. Итоговый путь пересчитывается при правке.
+  Отметка «возможный дубль» — со ссылкой на похожий трек библиотеки; точные копии отсекаются ещё до загрузки.
+- **Импорт:** одобренный файл записывается в хранилище только под окончательным именем, с проверкой контрольной
+  суммы; кроме самих аудиофайлов (и папок для них) на диск ничего не пишется.
+- **Квота** («Настройки сервера»): общий лимит очереди (10 ГБ по умолчанию), лимит на одного модератора
+  (выключен) и максимальный размер файла (2 ГБ). Отклонённые файлы и дубли место не занимают; снижение лимита ниже
+  занятого не удаляет загрузки, просто новые не принимаются.
+
+## 5. «Моя волна»
+
+- «Администрирование → Библиотека → Моя волна за 7 дней»: сколько треков выдано, доля дослушанных до конца,
+  ранних скипов и лайков на 100 треков. Ориентир — ранних скипов меньше 30%.
+- Таблица по **версиям модели**: `heuristic-v1` — эвристика, `heuristic-v1+cf` — она же с коллаборативной
+  фильтрацией (ALS), `lgbm-…` — обученный ранжировщик. По ней видно, стало ли лучше после смены модели.
+- Обучение — каждую ночь в 3:00 UTC: ALS по прослушиваниям, бандит по источникам
+  кандидатов, ранжировщик по показам волны. Новая модель включается, только если по проверке на последней неделе
+  не хуже текущей. Ранжировщику нужно ~20 тыс. показов с известным исходом — до этого работает эвристика.
+- Новые пользователи с почти пустой историей проходят **онбординг вкуса**: выбирают исполнителей и жанры
+  библиотеки. Пропуск тоже запоминается.
+
+## 6. Обновление
+
+```bash
+./update.sh
+```
+
+Скрипт делает копию базы, переключается на последний релиз, собирает образы, перезапускает сервисы и ждёт
+готовности; миграции применяются при старте api. Конкретная версия — `./update.sh v1.0.0`; откат на старую версию
+требует `PIPU_ALLOW_DOWNGRADE=1` (миграции не откатываются — сначала проверьте совместимость). Перед обновлением
+прочитайте заметки к релизу на странице релизов Gitea.
+
+Android-приложение обновляется само: при запуске оно сверяется с сервером и предлагает новый APK.
+
+## 7. Бэкапы и восстановление
+
+- Каждую ночь (`BACKUP_HOUR`, по умолчанию 3:30 UTC) контейнер `backup` делает копию базы в
+  `/srv/pipu/backups/daily` (14 последних) и раз в неделю — в `weekly` (8 последних).
+- Раз в неделю копия **проверяется восстановлением** во временную базу. Результат:
+  `docker compose logs backup | tail`; при ошибке в логе — «ПРОВЕРКА НЕ ПРОЙДЕНА».
+- Копия сейчас: `docker compose run --rm backup once`.
+- Восстановление: `./restore.sh` — список копий, `./restore.sh daily/<файл>` — восстановить. Прежняя база
+  остаётся рядом как `pipu_before_restore_<время>`; убедившись, что всё в порядке, удалите её:
+  `docker compose exec postgres dropdb -U pipu pipu_before_restore_<время>`.
+- В копию входит всё, что нельзя пересоздать: пользователи, история, лайки, состояние плеера, очередь на добавление,
+  результаты аудиоанализа и модели волны. Поиск, обложки и транскоды восстанавливаются сами.
+- **Сама музыка не бэкапится** приложением — это ваш диск или NFS. Каталог бэкапов тоже лежит на сервере:
+  копируйте `/srv/pipu/backups` на другую машину, например `rsync` по cron.
+
+## 8. Наблюдение
+
+| Что | Как |
+|---|---|
+| Сервер жив и готов | `curl -s https://music.example.com/readyz` → все зависимости `ok` |
+| Состояние сервисов | `docker compose ps` |
+| Логи | `docker compose logs -f --tail=100 api` (или `recommender`, `analyzer`, `storage-agent`, `backup`) |
+| Место на диске | `df -h /srv/pipu`; больше всего занимают `cache/transcode` (чистится сам) и `backups` |
+| Версия | `grep PIPU_VERSION .env`, `GET /api/v1/server-info`; Android — внизу вкладки «Профиль» |
+| Нагрузка | `tests/load/smoke.js` — см. [testing.md](testing.md#нагрузочный-smoke) |
+
+## 9. Частые ситуации
+
+| Ситуация | Что делать |
+|---|---|
+| Трек не находится поиском | Есть ли он в «Библиотеке» (скан завершён, файл не в «ошибках»); затем «Переиндексировать поиск» |
+| Неверный исполнитель или альбом | Поправьте теги файла или шаблон путей и запустите скан |
+| Хранилище в статусе «Ошибка» | Текст ошибки на карточке; диск смонтирован (`findmnt`), NFS доступен с сервера; «Проверить» |
+| Волна однообразная | Идёт ли аудиоанализ («Библиотека → Аудиоанализ»); чем больше прослушиваний, тем точнее волна |
+| Загрузка застряла в «Обработке» | `docker compose logs api | grep upload`; повторный импорт — «Одобрить» ещё раз |
+| Пользователь не может войти | Не заблокирован ли; «Сбросить пароль» |
+| Сервис перезапускается по кругу | `docker compose logs <сервис>`; часто — закончилось место на диске |
+
+Остальное — [install-guide.md](install-guide.md#12-если-что-то-не-работает).