diff --git a/docs/migration-hermes.md b/docs/migration-hermes.md
new file mode 100644
index 0000000..c17b65e
--- /dev/null
+++ b/docs/migration-hermes.md
@@ -0,0 +1,70 @@
+# Миграция Гермес → Simbiot
+
+Скрипт: `scripts/migrate_hermes.py` (t-261001124130). Переносит память, историю
+диалогов и настройки агента с харнеса Гермес (Nous Research) на Simbiot, чтобы
+после установки Simbiot агент отвечал с учётом прежних знаний.
+
+## Что читает из каталога Гермеса (`~/.hermes` или `~hermes_user/.hermes`)
+
+| Источник | Данные | Куда в Simbiot |
+|---|---|---|
+| `memories/MEMORY.md` | §-факты памяти | `OUT/memory/MEMORY.md`, RAG, `policy.identity` |
+| `memories/USER.md` | профиль пользователя | `OUT/memory/USER.md`, RAG, `policy.identity` |
+| `SOUL.md` | персона агента | `OUT/identity.md`, `policy.identity` |
+| `state.db` (sessions/messages, active) | история диалогов | `OUT/history/*.md` + индекс, RAG |
+| `config.yaml` | настройки | `OUT/config-hermes.yaml` (секреты → `<REDACTED>`), маппинг `model` → `SIMBIOT_MODEL` в отчёте |
+| `cron/jobs.json` | фоновые джобы | `OUT/cron-map.json` (эквиваленты: задачи на доске / systemd timer) |
+
+## Запуск
+
+```bash
+# dry-run (по умолчанию): только карта источников и превью, ничего не пишет
+python3 scripts/migrate_hermes.py --hermes /home/hermes/.hermes
+
+# apply + запись персона/памяти в стор ЭТОГО инстанса Simbiot + RAG-индексация:
+python3 scripts/migrate_hermes.py --hermes /home/hermes/.hermes --apply \
+    --harness-dir /root/simbiot-harness --rag-db /root/rag/rag.db
+```
+
+Опции: `--out DIR` (пакет, дефолт `hermes-migration/` в репо),
+`--rag-py`/`--rag-script` (вендор RAG: `/root/rag-venv/bin/python` +
+`/root/rag/rag.py`), `--rag-db PATH` (если не задан — RAG-шаг пропускается).
+
+## Что происходит при `--apply`
+
+1. `OUT/identity.md` — персона+память; в стор целевого инстанса пишется
+   `PolicyChanged` с `policy_hermes_marker` (sha-хеш текста) — **идемпотентно**:
+   повторный прогон со тем же текстом — `skip-duplicate`.
+2. `OUT/history/*.md` — последние ≤40 сессий с реальным диалогом (≥2 сообщений,
+   active=1; крон-сессии только в остаток после живых чатов), кап
+   40 сообщений/сессия, 150 всего; секреты (`sk-…`, `agt_…`, `<digits>:<токен>`,
+   `ghp_…`) замаскированы.
+3. RAG-индексация: `.md`-файлы пакета → целевая база (вендор дедупит по sha).
+4. `OUT/report.json` — полный отчёт: counts, mapping, events, rag, errors.
+
+`.env` целевого инстанса не трогается скриптом: `ROUTER_KEY`/`SIMBIOT_AGENT_NAME`
+и портал-канал (`/etc/coop-reporter.env`: `PORTAL_URL` + `AGENT_TOKEN` agt_…)
+настраиваются при установке (scripts/install.sh, визард).
+
+## Реальный кейс: агент Рита (22.10.2026, 22:19 UTC)
+
+Хост `hermes-rita` (2.28.125.152), источник `/home/hermes/.hermes`
+(135МБ state.db, 936 сессий, 11276 сообщений), портальная БД: agents.id=42
+переведён `harness_type='simbiot'`, `portal_channel=1`, agt-токен репортера
+выпущен, router-ключ Риты из `router_keys` записан в её `.env`.
+
+Результат: 31 файл проиндексирован в RAG (/root/rag/rag.db, 0 ошибок),
+`PolicyChanged applied` (marker `policy-hermes-6c9beed932`, identity 5910
+символов). E2E-проверка: сообщение в канал портала → мин-тик Риты забрал,
+ответ содержит факты ИЗ ПЕРЕНЕСЁННОЙ памяти (видеостек OpenMontage, Edge-TTS
+ru-RU-DmitryNeural) — агент отвечает с учётом истории.
+
+## Ограничения / follow-up
+
+- 10 cron-джобов Гермеса перенесены как карта (`cron-map.json`), не как живые
+  таймеры: включать селективно (watchdog-пинги и протухшие пуллы не переносить) —
+  задача на доске (follow-up t-… по кронам Риты).
+- Полная история (все 936 сессий остаётся в `state.db` Гермеса) не копируется —
+  только активное диалоговое ядро; исходник сохраняется нетронутым.
+- TG-бот нового агента подключается кнопкой на портале (`/set-tg-bot`) — флоу
+  тот же, что для остальных агентов Simbiot.
\ No newline at end of file