feat(sprint6c+sprint7): терминология, сверка примеров с кодом, мульти-RAG (часть A)

Спринт 6c — терминология и сверка документации с реальным кодом:
- Словарь терминов в static/docs.html: «маршрутизатор» вместо «роутер»,
  «защитное условие» вместо «guard», «пошаговая ветка» вместо «многошаговая».
  Разделены концепты «намерение» (intent) и «ветка» (branch) с пометкой,
  что в коде они хранятся как одна сущность 1:1.
- Песочница: «Решение маршрутизатора» виден всегда (зелёный/жёлтый),
  счётчик переключений «N из 3» отдельной плашкой, бейджи под словарь.
- Настройки: «Условия перехода» → «Защитные условия (guards, JSON)».
- GRAPH_ARCHITECTURE_v4.md: имена полей thread_state и слоты приведены
  к реальной БД (db/models/thread_state.py) и таксономии промптов шагов
  (prompts/intents/new_booking/steps/). Ссылки на *_v2 примеры. На v3
  поставлена шапка «устарело».
- 4 примера переписаны как *_v2: реальные current_intent_code/
  current_step_code/slots_json, реальные allowed_next без двойных переходов,
  реальная таксономия слотов name/reason/specialist/preferred_time/confirmed.
  Удалены вымышленные CRM tool calls и слоты, которых нет в коде.
- static/example.html — параметризованная страница с навигацией между
  4 примерами; роут GET /api/docs/examples/{name} в main.py отдаёт
  markdown без дублирования файлов.
- Редактирование документов в Отладке: GET/PUT /documents/{id}/raw,
  textarea с переразметкой и обновлением Chroma при сохранении.

Спринт 7, часть A — мульти-RAG через подписку ветка↔документы:
- Миграция: таблица intent_documents (M:N), модель IntentDocument,
  индекс по document_id для обратного поиска.
- API: GET/PUT /intents/{code}/documents и GET/PUT /documents/{id}/intents
  с PUT-семантикой «полный список», атомарно. Сервис
  services/intent_document_service.py.
- Retrieval-фильтр в chat_service: подтягивает document_ids активной
  ветки и передаёт в vectorstore.query(). Дефолт пустой подписки —
  document_ids=[] (= 0 чанков), не «вся коллекция»: пустая подписка
  означает «ветка не настроена», подмешивать случайное хуже, чем
  ничего. vectorstore.query() различает None (нет фильтра) и [] (0).
- UI Настроек: блок «Документы базы знаний» в правом сайдбаре,
  всегда видим независимо от вкладки, сортировка по имени, счётчик
  «N из M», PUT при сохранении.
- UI Отладки: третья кнопка «привязка» рядом с «удалить» —
  раскрывашка со списком веток (галочки), быстрая привязка прямо
  на странице загрузки.
- Песочница: блок «Срез RAG» с подпиской/найдено, ворнинг при пустой
  подписке. Поле rag_subscription в QueryResponse и ChatResponse.
- Системный промпт страницы Отладки переехал в обычную ветку _debug
  («Страница отладки»). Удалён prompts/system_prompt.md и логика
  DEFAULT_SYSTEM_PROMPT в llm_client. routers/query.py подтягивает
  активный конфиг ветки _debug и её подписки. Дефолт пустой подписки
  для _debug — None (вся коллекция), не [] как для пациентских — чтобы
  Отладка работала «из коробки». На странице Отладки info-bar показывает
  активную версию и счётчик подписок, ссылка → Настройки.
- Тест-блок «Тест-вопрос» в центре Настроек: расширил /query
  параметрами intent_code (default _debug), system_prompt (override
  для теста черновика из textarea), disable_rag (для _router).
  Редактор промпта обёрнут в <details open> — можно свернуть до
  одной строки. Под ним — три колонки результата (RAG / промпт /
  ответ). Для _router показывается подсказка про отсутствие RAG.

Документы:
- data/datasets/*.md — наработки по 6 веткам (рабочие материалы оператора).
- docs/BRANCH_MAP_AND_PROMPTS_v1.md, docs/OPTIMIZATION_CONVERSION_v1.md,
  docs/guides/state_machine_and_slots.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/SPRINTS.md

@@ -395,26 +395,69 @@
 
 ---
 
-## Спринт 7. Мульти-RAG (вариант Б из v2: подписка ветки на разделы вики)
+## Спринт 6c. Терминология: словарь, документация, UI, страницы примеров
 
 ### Цель
-Дать каждой ветке собственный срез базы знаний, чтобы детская wiki не засоряла ответы по записи, а скрипты возражений — ответы по ценам. Согласно `GRAPH_ARCHITECTURE_v2.md` §6 — **Вариант Б** предпочтительнее отдельных коллекций: одна общая коллекция + фильтр по разделам вики в метаданных чанков. Делаем **до** мини-eval, чтобы наборы в Спринте 8 проверяли поведение уже с реальным per-intent retrieval.
+Устранить терминологический кавардак между v3-архитектурой, кодом и UI: единый словарь, протянуть его сквозь страницу документации и UI Песочницы/Настроек, добавить разобранные примеры из `docs/examples/` как читаемые страницы внутри приложения. Делается **перед** Спринтом 8 (мини-eval), чтобы тесты роутера и handoff'а уже опирались на устоявшиеся термины и читаемое UI.
+
+### Статус: ✅ Закрыт
+
+### Задачи
+- [x] Зафиксирован словарь: «намерение» (intent) и «ветка» (branch) разнесены концептуально, в коде остаётся `intent_code` (связь 1:1, см. идею в «Дальнейшие идеи»). «Маршрутизатор» вместо «роутер». «Защитное условие» вместо «guard» (буквально из v3 §3.2). «Пошаговая ветка» вместо «многошаговая». Введены: «Решение маршрутизатора», «Активная ветка», «Счётчик переключений», «Причина передачи оператору».
+- [x] **Документация (`static/docs.html`)** — карточки терминов и текст приведены к словарю. Добавлены карточки «Намерение», «Ветка» (с историческим замечанием про intent в БД), «Решение маршрутизатора», «Активная ветка», «Счётчик переключений», «Причина передачи оператору». «Guard» переименован в «Защитное условие».
+- [x] **Песочница (`static/sandbox.html`)** — «Решение роутера» → «Решение маршрутизатора». Бейдж «многошаговая» → «пошаговая ветка». Бейдж «🔒 guard X» → «🔒 защитное условие X». «Решение маршрутизатора» теперь всегда видимый бейдж (зелёный при совпадении с активной веткой, жёлтый при расхождении). Активная ветка названа явно. Счётчик переключений вынесен в визуальный элемент «N из 3» (красный при достижении капа).
+- [x] **Настройки (`static/settings.html`)** — поле «Guards (JSON)» → «Защитные условия (guards, JSON)», тост ошибки переименован.
+- [x] **Страницы примеров** — параметризованная страница `static/example.html`, рендерит markdown через marked.js + DOMPurify. Маленький роут `GET /api/docs/examples/{name}` в `main.py` отдаёт markdown из `docs/examples/` без дублирования. Навигация между 4 примерами + хлебные крошки обратно. Раздел «Разобранные примеры» добавлен в `docs.html`.
+
+### Критерий готовности
+- [ ] Слово «роутер» в UI отсутствует (только в коде как `_router` и в служебной константе `[ПОДСКАЗКА РОУТЕРА]`).
+- [ ] Слово «guard» в UI заменено на «защитное условие». В коде остаётся `guards_json`, `check_guards()`.
+- [ ] В Песочнице на каждой реплике видно отдельно «Решение маршрутизатора» и «Активная ветка»; счётчик переключений виден как «N из 3».
+- [ ] Из `docs.html` есть навигация к 4 страницам примеров; со страницы примера — обратно в документацию.
+
+---
+
+## Спринт 7. Мульти-RAG, часть A: подписка ветки на загруженные документы
+
+### Цель
+Дать каждой ветке собственный срез базы знаний, чтобы документы для одной темы (например, скрипты по детскому приёму) не засоряли ответы другой темы (цены / общая справка). Делаем **до** мини-eval Спринта 8, чтобы тесты прогонялись уже с реальным per-intent retrieval.
+
+**Часть A** этого спринта — ручная подписка через UI: оператор загружает документы как сейчас (на странице «Отладка»), а в «Настройках» ветки указывает галочками, какие из них в неё подмешивать. **Часть Б** (автосинхронизация с внешней вики операторов) — отдельной задачей в идеях на потом.
+
+**Подход** — A (M:N через document_id, не префиксы путей и не теги). Причины: `vectorstore.query()` уже умеет фильтровать по `document_ids` (нечего переписывать); нулевая миграция Chroma; на текущем масштабе (~30 документов, 6 веток) ручная подписка — 3-минутная задача один раз при загрузке; дисциплина именования путей — слабое место в проектах с >1 оператором, а галочки понятны без инструкции.
 
 ### Статус: ⏳ Запланирован
 
 ### Задачи
-- [ ] В `intents` — поле `wiki_sources: list[str]` (префиксы путей или doc-ID). Миграция.
-- [ ] В метаданные чанка при загрузке записывать `doc_path` / раздел вики.
-- [ ] В `services/vectorstore.py` — where-фильтр по `doc_path` на основе `wiki_sources` активной ветки при query.
-- [ ] UI «Настройки» — редактор `wiki_sources` у ветки (список префиксов).
-- [ ] Если `wiki_sources` пуст — дефолт: вся коллекция (для `general_info`).
-- [ ] Задел под v2 §3.4: опциональный `wiki_sources_by_step` (на уровне шага state machine) — сделать именно здесь, раз у нас уже есть state machine из Спринта 6.
+
+**Бэкенд:**
+- [ ] Миграция Alembic: новая таблица `intent_documents` с полями `intent_id` (FK на `intents.id`), `document_id` (varchar 36, тип как в metadata Chroma), `created_at`. PK составной (`intent_id`, `document_id`). Индекс по `document_id` для обратного поиска.
+- [ ] Модель `db/models/intent_document.py` (`IntentDocument`).
+- [ ] Сервис `services/intent_document_service.py` — функции `list_documents_for_intent(intent_code)`, `list_intents_for_document(document_id)`, `set_documents_for_intent(intent_code, document_ids)`, `set_intents_for_document(document_id, intent_codes)`.
+- [ ] API:
+  - `GET /intents/{code}/documents` — список `document_id`, привязанных к ветке.
+  - `PUT /intents/{code}/documents` — перезаписать список (body: `{ "document_ids": [...] }`).
+  - `GET /documents/{id}/intents` — список кодов веток конкретного документа.
+  - `PUT /documents/{id}/intents` — перезаписать список (body: `{ "intent_codes": [...] }`).
+- [ ] Retrieval-фильтр в `services/chat_service.py`: перед `vectorstore.query()` подтянуть список `document_id` для активной ветки. Передать как `document_ids=...`. **Дефолт пустой подписки — `document_ids=[]` (= 0 чанков), не «вся коллекция»**: пустая подписка означает «ветка не настроена», подмешивать случайное хуже, чем не подмешивать ничего.
+
+**UI:**
+- [ ] «Настройки» → страница ветки: новый блок «Документы базы знаний» — список всех загруженных документов с галочками, заголовок «подписано N из M», кнопка «Сохранить подписки».
+- [ ] «Отладка» → рядом с каждым документом (или в разворачиваемой панели) — компактный список веток с галочками, чтобы быстро подписать прямо на месте загрузки.
+- [ ] «Отладка» → кнопка «редактировать» рядом с «привязка»/«удалить»: разворачивает большой `<textarea>` с извлечённым `raw_text` документа. Кнопка «Сохранить и переиндексировать» делает `PUT /documents/{id}/raw` (обновляет `documents.raw_text` + переразметка + замена чанков в Chroma). С confirm перед сохранением. Подпись: правится извлечённый текст, для PDF/docx исходник теряется.
+- [ ] Системный промпт страницы «Отладка» переехал в обычную ветку `_debug` («Страница отладки»). Удалён `prompts/system_prompt.md` и логика `DEFAULT_SYSTEM_PROMPT` в `services/llm_client.py`. `routers/query.py` подтягивает активный конфиг ветки `_debug` (через `config_service`) и её подписки на документы (через `intent_document_service`). Дефолт пустой подписки в `_debug` — вся коллекция, чтобы Отладка работала «из коробки» (для пациентских веток дефолт другой — 0 чанков). На странице Отладки info-bar показывает активную версию и счётчик подписок, ссылка → Настройки. В `QueryResponse` добавлены `intent_code`, `config_version`, `rag_subscription`.
+- [ ] Песочница, отладочная панель: новый блок «Срез RAG: подписано N из M документов для ветки `<код>`». В «Найденных фрагментах» в каждой карточке — лейбл с `document_name`. Если подписка пуста и retrieval вернул 0 чанков — явная пометка «у ветки нет подписок, RAG-контекст пустой».
+
+**Документация:**
+- [ ] `static/docs.html` — карточка термина «Подписка ветки на документы», упоминание в разделе «Что происходит на каждой реплике».
+- [ ] `docs/architecture/GRAPH_ARCHITECTURE_v5.md` — переписать §6 под подход A (M:N через `document_id`, без путей и без тегов). На v4 — шапка «устарело». Changelog v4→v5.
+- [ ] `README.md` — раздел про мульти-RAG.
 
 ### Критерий готовности
-- [ ] Документ раздела `/wiki/pricing/*` автоматически используется только в `price_question` (без ручного дублирования).
-- [ ] При переключении ветки в диалоге retrieval берёт нужный срез.
-- [ ] В «Отладке» видно: какие префиксы активны, какие чанки пришли из каких разделов.
-- [ ] Для шага `offer_time` в `new_booking` отдельный per-step срез работает (если ветка его заполнила).
+- [ ] Документ, привязанный к `price_question`, появляется в retrieval только когда активна именно эта ветка. При переключении на `new_booking` — те же запросы возвращают другие чанки.
+- [ ] Ветка без подписок (например, свежесозданная) получает в retrieval 0 чанков — модель отвечает по промпту без RAG-контекста.
+- [ ] В Песочнице видно «подписано N из M», в найденных фрагментах — название документа.
+- [ ] Подписка работает в обе стороны UI: можно настроить и со страницы ветки (Настройки), и со страницы документа (Отладка).
 
 ---
 
@@ -485,11 +528,18 @@
 ## Бэклог
 
 ### Дальнейшие идеи
+- **Спринт 7, часть Б: автосинхронизация с внешней вики операторов.** Часть A Спринта 7 — ручная подписка через UI: оператор сам загружает документы и сам ставит галочки. Часть Б — подключение к внешней системе ведения вики (которая «тщательно ведётся операторами»): автоматическое обновление документов, привязка подписок к источникам в той системе, версионирование. Конкретика появится, когда будет известно, что за внешняя система.
+- **Per-step `wiki_sources`** (из v4 §3.4): отдельная подписка на уровне шага машины состояний (например, на `book` подмешивать только документы про подготовку к приёму, на `qualify` — про услуги и врачей). Сейчас не нужно — все шаги `new_booking` логически работают с одной и той же базой. Возвращаться, когда увидим, что какой-то шаг подбирает не те чанки.
+- **Превью markdown в редакторе документа** (страница «Отладка», кнопка «редактировать»): сейчас в textarea виден сырой markdown с символами `#`, `**`. Добавить split-view (слева исходник, справа отрендеренный markdown через уже подключённые `marked.js` + `DOMPurify` из Песочницы). На узких экранах — вертикальный стек. Альтернативы: вкладки «редактор/превью» (проще, но с переключением) или WYSIWYG (TipTap / EasyMDE — +500 KB и риск кривого экранирования). Рекомендация на момент записи — split-view.
+- **Confidence threshold для RAG в `general_info`** (из v3 + пример 04, A.4): если score лучшего чанка ниже порога (например 0.50) — модель отвечает шаблоном «уточним и перезвоню», ставит слот `needs_followup=true`. Защита от выдумывания фактов в случаях вроде «работаете в праздник?» при отсутствии чанка.
+- **Технические слоты для `general_info`** (из примера 04): `info_topic` (`hours` / `branches` / `transit` / `parking` / `contacts` / `preparation` / `scope_of_services`), `branch_mention`, `needs_followup`. Сейчас у `general_info` нет машины состояний и слоты не сохраняются — при втором вопросе в треде ретривер не знает, про какой филиал шла речь раньше. Подключить минимальный `answer→done` со слотами.
+- **CRM-инструменты (`crm.get_slots`, `crm.create_booking`)** (из v3 + примеры 01/02): сейчас в коде нет интеграции с CRM, на шагах `offer_time` / `book` модель «обещает» запись, но никуда её не сохраняет. Реальная интеграция — задача смежника при подключении каналов, но мок-инструменты можно завести раньше, чтобы поддерживать сквозной сценарий в Песочнице.
+- **Sub-states типа `qualify.legal_rep`** (из примера 03): сейчас тот же эффект достигается через conditional transitions + guards, и v3 сама рекомендует не плодить sub-states. Возвращаться, если guard'ов на одном шаге станет много и состояние перестанет читаться.
+- **Разделение «намерения» и «ветки» в коде и БД** (из v3, раздел «Архитектура, к которой идём»): сейчас в коде и в таблице `intents` это одна сущность, связь намерение↔ветка жёстко 1:1. В словаре терминов их разнесли только концептуально (см. словарь в `static/docs.html`). Возвращаться к этому, **когда появится сценарий «одно намерение → разные ветки в зависимости от контекста»** — например, отдельные ветки записи для детей и взрослых под одно намерение `new_booking`. Тогда понадобится завести `branch_code` рядом с `intent_code`, пересобрать модель `Intent`, поменять выбор ветки в `chat_service.py`. До такого сценария — лишняя сложность.
 - Раздельные правила по доменам — **перекрыто архитектурой: теперь это ветки (`intents`)**
 - A/B сравнение двух версий промпта на одном тест-наборе (в рамках одной ветки или между ветками)
 - Метрики качества ответов (MRR, CSAT по сценариям)
 - Подсветка цитат источников в ответе агента
-- Автосинхронизация wiki
 - Перевод правил из свободного текста в структурированный список (pattern → instruction)
 - Мультипользовательский режим (несколько операторов одновременно настраивают)
 - Хранение исходных файлов (`./data/uploads/{document_id}.{ext}` + `source_path` в метаданных Chroma) — чтобы переиндексировать без повторной загрузки и показывать оператору оригинал документа