diff --git a/README.md b/README.md
index dcc5cbb..dc7489d 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,8 @@ pnpm --filter web dev               # :5175
 
 См. [`docs/integrate-vps-tracker.md`](docs/integrate-vps-tracker.md) — SSO handoff (`return_to` + `#access_token`), общий `JWT_SECRET`, RBAC `vps:*`.
 
+См. [`docs/integrate-cfdm.md`](docs/integrate-cfdm.md) — то же для Cloudflare Domain Manager (`cfdm:*`, порт Vite `5174`).
+
 Корень:
 
 ```bash
diff --git a/docs/integrate-cfdm.md b/docs/integrate-cfdm.md
new file mode 100644
index 0000000..e8298c9
--- /dev/null
+++ b/docs/integrate-cfdm.md
@@ -0,0 +1,106 @@
+# Интеграция auth-portal ↔ Cloudflare Domain Manager (CFDM)
+
+Единый вход: пользователь логинится на auth-portal, получает JWT, переходит в CFDM с токеном в URL fragment. CFDM API проверяет JWT и права `cfdm:*`.
+
+## Архитектура
+
+```
+Browser → CFDM UI (нет token)
+       → redirect AUTH_PORTAL_URL/?return_to=…/auth/callback
+       → login
+       → redirect return_to#access_token=…
+       → CFDM /auth/callback сохраняет token (cfdm_token)
+       → API Authorization: Bearer …
+```
+
+Общий секрет: `JWT_SECRET` / `AUTH_JWT_SECRET` (HS256). Issuer: `ISSUER` / `AUTH_ISSUER`.
+
+App id в портале: **`cfdm`** (уже в каталоге permissions).
+
+## Локальный запуск
+
+### 1. auth-portal
+
+```bash
+cd auth-portal
+pnpm install
+# JWT_SECRET=dev-secret-change-me
+# RETURN_TO_ALLOWLIST=.shnt.top,localhost,http://localhost:5173,http://localhost:5174
+pnpm --filter @authportal/api dev   # :8080
+pnpm --filter web dev               # :5175
+```
+
+В `apps/web/.env.local`:
+
+```env
+VITE_CFDM_APP_URL=http://localhost:5174
+```
+
+Bootstrap: `admin@shnt.top` / `admin`. В админке выдайте app **cfdm** и permissions `cfdm:*`.
+
+### 2. cloudflare-domain-manager
+
+```bash
+cd cloudflare-domain-manager
+pnpm install
+```
+
+Корень / API:
+
+```env
+AUTH_REQUIRED=true
+AUTH_JWT_SECRET=dev-secret-change-me
+AUTH_ISSUER=https://auth.shnt.top
+AUTH_PORTAL_URL=http://localhost:5175
+```
+
+`apps/web/.env.local`:
+
+```env
+VITE_AUTH_ENABLED=true
+VITE_AUTH_PORTAL_URL=http://localhost:5175
+```
+
+Порт Vite web — см. `apps/web/vite.config.ts` (часто `5174`). Добавьте origin в `RETURN_TO_ALLOWLIST` портала.
+
+```bash
+pnpm --filter api dev
+pnpm --filter web dev
+```
+
+Откройте CFDM → редирект на portal → после логина NavUser показывает имя/email.
+
+## Permissions ↔ API / UI
+
+Иерархия: `admin` ⊃ `write` ⊃ `read` в рамках одной секции.
+
+| Permission | API | UI |
+|------------|-----|-----|
+| `cfdm:domains:read` | GET `/api/v1/domains*`, monitors | `/`, `/domains` |
+| `cfdm:domains:write` | мутации domains, sync | create/edit/sync |
+| `cfdm:dns:read` | GET dns, subdomains | DNS на карточке домена |
+| `cfdm:dns:write` | мутации dns/subdomains | формы DNS |
+| `cfdm:certificates:read` | GET certificates | `/certificates` |
+| `cfdm:certificates:write` | мутации certificates | действия сертификатов |
+| `cfdm:groups:read` | GET groups, service-groups | `/groups` |
+| `cfdm:groups:write` | мутации groups | формы групп |
+| `cfdm:services:read` | GET services, bindings | `/services` |
+| `cfdm:services:write` | мутации services | формы сервисов |
+| `cfdm:settings:admin` | settings, notifications, health-check | `/settings/*` |
+
+Без app `cfdm` в JWT `apps` → **403** на защищённые `/api/v1/*`.
+
+`AUTH_REQUIRED=false` — локальный login (`ADMIN_*`) для тестов/dev без portal; UI `/login`.
+
+## UI аккаунта
+
+SidebarFooter → **NavUser** ([app-shell-1](https://reui.io/preview/base/app-shell-1)): Настройки, Тема, Выйти → portal.
+
+## Troubleshooting
+
+| Симптом | Причина |
+|---------|---------|
+| SSO loop / «Сессия не принята» | разный `JWT_SECRET` или `ISSUER` у portal и CFDM |
+| 403 «Нет доступа к приложению» | у пользователя нет app `cfdm` в portal |
+| 403 «Недостаточно прав» | нет нужного `cfdm:…` permission |
+| return_to rejected | origin CFDM не в `RETURN_TO_ALLOWLIST` |