docs: Diplodoc setup + полное руководство интеграции по API

Новая документация-as-code на платформе Diplodoc (Yandex open-source) с
YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно.

Что добавлено:
- package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar
- index.md — главная страница с tabs для разных audiences
- README.md — инструкция для contributors

Раздел integration/api/ — 11 страниц про интеграцию consumers:
- index — обзор + глоссарий
- auth — Keycloak service accounts, scope mapping
- read-endpoints — GET /dictionaries, list/by-key, spatial filters
- events — Kafka outbox топики, partition keys, idempotency, DLQ
- webhooks — HMAC, SSRF guard, retry policy, test ping endpoint
- bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export
- x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview
- caching — TTL / push / snapshot strategies, hybrid pattern
- errors — full error code reference (validation/auth/conflict/server), retry strategy
- best-practices — 33 numbered rules для consumers
- bundle-cuod — все 40 справочников с FK графом и сценариями

Обновлены:
- ops/README.md — link на новую integration/api/, убран inline <br>
- ops/slo.md — broken cross-repo links заменены на text references

Build:
  cd docs && pnpm install && pnpm build
  → ./_dist (20 HTML files, 7.1M)
  pnpm serve  # → http://localhost:8088

CI deploy job для GitLab Pages — в roadmap (см. docs/README.md).

Существующий tech/api-integration.md оставлен в toc как legacy
(содержимое мигрировано + расширено в integration/api/).

docs/README.md

@@ -0,0 +1,109 @@
+# Ordinis docs (Diplodoc / YFM)
+
+Документация Ordinis НСИ ЦУОД ОДХ построена через **Diplodoc** (open-source
+documentation platform от Yandex). Markdown source — YFM (Yandex Flavored
+Markdown) с расширениями для tabs, notes, includes, mermaid диаграмм.
+
+## Структура
+
+```
+docs/
+├── package.json           # @diplodoc/cli + scripts
+├── .yfm                   # Diplodoc config (langs, plugins)
+├── toc.yaml               # Содержание / навигация (рендерится в sidebar)
+├── index.md               # Главная страница
+├── integration/           # Интеграция по API
+│   ├── api/               # Главы для consumers
+│   │   ├── index.md       # Обзор
+│   │   ├── auth.md        # Keycloak / JWT
+│   │   ├── read-endpoints.md
+│   │   ├── events.md      # Kafka outbox
+│   │   ├── webhooks.md
+│   │   ├── bitemporal.md
+│   │   ├── x-references.md
+│   │   ├── caching.md
+│   │   ├── errors.md
+│   │   ├── best-practices.md
+│   │   └── bundle-cuod.md
+│   └── altum-imaging-order.md   # Прикладной сценарий
+├── ops/                   # Operator runbook
+│   ├── README.md
+│   ├── slo.md
+│   ├── outbox-dlq.md
+│   ├── db-migrations.md
+│   ├── vault-unseal.md
+│   └── kafka-restart.md
+├── status/                # State snapshots (исключено из build)
+│   └── *-state.md
+└── tech/                  # Legacy технические страницы
+    └── api-integration.md
+```
+
+## Сборка
+
+Требуется Node 18+.
+
+```bash
+cd docs
+pnpm install
+pnpm build           # → ./_dist (HTML)
+pnpm serve           # → http://localhost:8088
+# либо одной командой:
+pnpm dev
+```
+
+Build output (`_dist/`) — статический HTML, можно деплоить в:
+- GitLab Pages
+- S3 + CloudFront
+- nginx/ingress на cluster.142
+
+## Автор содержимого
+
+| Раздел | Owner |
+|---|---|
+| `/` (index, integration/api/*) | zimin.an@nstart.space |
+| `ops/*` | on-call rotation team |
+| `integration/altum-imaging-order.md` | Альтум team contact |
+
+## Что не committable
+
+- `_dist/` — build output (gitignore'нут)
+- `node_modules/` — dependencies (gitignore'нут)
+
+## Deployment
+
+В roadmap — GitLab CI job `build-docs`:
+
+```yaml
+build-docs:
+  stage: build
+  image: node:18
+  script:
+    - cd docs
+    - pnpm install --frozen-lockfile
+    - pnpm build
+  artifacts:
+    paths: [docs/_dist]
+    expire_in: 1 week
+  rules:
+    - changes: ["docs/**/*"]
+```
+
+Затем deploy в GitLab Pages либо как отдельный k8s deployment с nginx.
+
+## YFM extensions используются
+
+- `{% list tabs %}` — табы для switching между audiences
+- `{% note info|warning|tip %}` — выделенные блоки
+- `mermaid` code blocks — диаграммы (graph LR, gantt)
+- Cross-links в `toc.yaml` — sidebar navigation
+- `varsPreset: external` — для shared includes (TBD when нужно)
+
+## Roadmap
+
+- [ ] CI job `build-docs` в `.gitlab-ci.yml`
+- [ ] GitLab Pages deployment
+- [ ] Search через Diplodoc search plugin
+- [ ] EN translation (i18n via `langs:` в `.yfm`)
+- [ ] Includes для shared snippets (auth examples, error tables)
+- [ ] Versioning — separate doc trees per Ordinis major version